takerofnotes-plugin-sdk/README.md

@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

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

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().

definePlugin({
  id: string
  name: string
  description: string
  version: string
  apiVersion: string
  configSchema: ConfigField[]
  createAdapter(config): BaseNotesAdapter
})

BaseNotesAdapter

All storage adapters must extend:

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.

type ConfigField = {
    key: string
    label: string
    type: 'text' | 'password' | 'directory' | 'number' | 'boolean'
    default: 'text' | 'password' | 'directory' | 'number' | 'boolean'
    required?: boolean
}

Example:

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:

{
    "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