179 lines
3.3 KiB
Markdown
179 lines
3.3 KiB
Markdown
# @takerofnotes/plugin-sdk
|
|
|
|
Official plugin SDK for Taker of Notes.
|
|
|
|
This package provides the public contract for building storage adapters and third-party plugins for Taker of Notes.
|
|
|
|
It includes:
|
|
|
|
- `BaseNotesAdapter` (abstract adapter class)
|
|
- `definePlugin()` helper
|
|
- Runtime plugin validation
|
|
- Strong TypeScript types
|
|
- API version enforcement
|
|
|
|
# Installation
|
|
|
|
```bash
|
|
npm install @takerofnotes/plugin-sdk
|
|
```
|
|
|
|
# Quick Start
|
|
|
|
All plugins must:
|
|
|
|
1. Extend BaseNotesAdapter
|
|
2. Export a plugin definition using definePlugin()
|
|
3. Declare a compatible apiVersion
|
|
|
|
# Minimal Example
|
|
|
|
```typescript
|
|
import { BaseNotesAdapter, definePlugin } from '@nicwands/notes-plugin-sdk'
|
|
|
|
class MyAdapter extends BaseNotesAdapter {
|
|
async init() {}
|
|
|
|
async getAll() {
|
|
return []
|
|
}
|
|
|
|
async create(note) {}
|
|
|
|
async update(note) {}
|
|
|
|
async delete(id) {}
|
|
}
|
|
|
|
export default definePlugin({
|
|
id: 'my-adapter',
|
|
name: 'My Adapter',
|
|
description: 'Example storage adapter',
|
|
version: '1.0.0',
|
|
apiVersion: '1.0.0',
|
|
configSchema: [],
|
|
createAdapter(config) {
|
|
return new MyAdapter(config)
|
|
},
|
|
})
|
|
```
|
|
|
|
# Plugin Structure
|
|
|
|
A plugin exports a single default object created via `definePlugin()`.
|
|
|
|
```typescript
|
|
definePlugin({
|
|
id: string
|
|
name: string
|
|
description: string
|
|
version: string
|
|
apiVersion: string
|
|
configSchema: ConfigField[]
|
|
createAdapter(config): BaseNotesAdapter
|
|
})
|
|
```
|
|
|
|
# BaseNotesAdapter
|
|
|
|
All storage adapters must extend:
|
|
|
|
```typescript
|
|
abstract class BaseNotesAdapter {
|
|
constructor(config?: any)
|
|
|
|
init(): Promise<void>
|
|
getAll(): Promise<any[]>
|
|
create(note: any): Promise<void>
|
|
update(note: any): Promise<void>
|
|
delete(id: string): Promise<void>
|
|
}
|
|
```
|
|
|
|
The adapter is responsible only for persistence.
|
|
|
|
It should:
|
|
|
|
- Store notes
|
|
- Retrieve notes
|
|
- Update notes
|
|
- Delete notes
|
|
|
|
It should NOT:
|
|
|
|
- Perform indexing
|
|
- Cache data
|
|
- Apply business logic
|
|
|
|
That is handled by Taker of Notes core.
|
|
|
|
# Config Schema
|
|
|
|
`configSchema` defines UI configuration fields shown in the app.
|
|
|
|
```typescript
|
|
type ConfigField = {
|
|
key: string
|
|
label: string
|
|
type: 'text' | 'password' | 'directory' | 'number' | 'boolean'
|
|
default: 'text' | 'password' | 'directory' | 'number' | 'boolean'
|
|
required?: boolean
|
|
}
|
|
```
|
|
|
|
Example:
|
|
|
|
```typescript
|
|
configSchema: [
|
|
{ key: 'endpoint', label: 'S3 Endpoint', type: 'text', required: true },
|
|
{ key: 'accessKey', label: 'Access Key', type: 'password', required: true },
|
|
{ key: 'secretKey', label: 'Secret Key', type: 'password', required: true },
|
|
]
|
|
```
|
|
|
|
Taker of Notes will automatically generate the configuration UI based on this schema.
|
|
|
|
# Publishing a Plugin
|
|
|
|
Recommended naming convention:
|
|
|
|
`notes-plugin-<adapter-name>`
|
|
|
|
Example:
|
|
|
|
```
|
|
notes-plugin-s3
|
|
notes-plugin-sqlite
|
|
notes-plugin-dropbox
|
|
```
|
|
|
|
In your plugin's package.json:
|
|
|
|
```json
|
|
{
|
|
"name": "takerofnotes-plugin-s3",
|
|
"version": "1.0.0",
|
|
"type": "module",
|
|
"peerDependencies": {
|
|
"@nicwands/notes-plugin-sdk": "^0.1.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
Use peerDependencies to ensure compatibility with the host app.
|
|
|
|
# Security Considerations
|
|
|
|
Plugins execute in the Notes main process.
|
|
|
|
You should:
|
|
|
|
- Avoid executing untrusted code
|
|
- Protect credentials securely
|
|
- Avoid leaking sensitive configuration
|
|
|
|
If building a remote storage adapter (S3, Supabase, etc.), never log secrets.
|
|
|
|
License
|
|
MIT
|