From 52d7d78a84002495575fb7b85a51f92d6b638960 Mon Sep 17 00:00:00 2001
From: nicwands <wands.nic@gmail.com>
Date: Tue, 24 Feb 2026 12:42:00 -0500
Subject: [PATCH] readme

---
 README.md    | 178 +++++++++++++++++++++++++++++++++++++++++++++++++++
 package.json |   2 +-
 2 files changed, 179 insertions(+), 1 deletion(-)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fc39eb8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,178 @@
+# @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
diff --git a/package.json b/package.json
index 4629b58..59c9b01 100644
--- a/package.json
+++ b/package.json
@@ -19,7 +19,7 @@
         "dev": "tsup src/index.ts --format esm --dts --watch"
     },
     "author": "nicwands",
-    "license": "ISC",
+    "license": "MIT",
     "devDependencies": {
         "tsup": "^8.5.1",
         "typescript": "^5.9.3"