update testing and versioning

.nvmrc

@@ -0,0 +1 @@
+22

README.md

@@ -10,7 +10,7 @@ It includes:
 -   `definePlugin()` helper
 -   Runtime plugin validation
 -   Strong TypeScript types
--   API version enforcement
+-   Semver-based API version enforcement
 
 # Installation
 
@@ -50,7 +50,7 @@ export default definePlugin({
     name: 'My Adapter',
     description: 'Example storage adapter',
     version: '1.0.0',
-    apiVersion: '1.0.0',
+    apiVersion: '0.3.1',
     configSchema: [],
     createAdapter(config) {
         return new MyAdapter(config)
@@ -155,13 +155,17 @@ In your plugin's package.json:
     "version": "1.0.0",
     "type": "module",
     "peerDependencies": {
-        "@nicwands/notes-plugin-sdk": "^0.1.0"
+        "@nicwands/notes-plugin-sdk": "^0.3.0"
     }
 }
 ```
 
 Use peerDependencies to ensure compatibility with the host app.
 
+# API Versioning
+
+The SDK uses semver range matching for API versions. Your plugin's `apiVersion` should fall within the supported range exported as `SUPPORTED_API_RANGE` from the SDK. Minor and patch version changes in the SDK remain compatible with your plugin.
+
 # Security Considerations
 
 Plugins execute in the Notes main process.

package.json

@@ -7,7 +7,7 @@
     "types": "dist/index.d.ts",
     "repository": {
         "type": "git",
-        "url": "git+https://github.com/nicwands/takerofnotes-plugin-sdk.git"
+        "url": "git+https://git.alt-tuning.co/takerofnotes/takerofnotes-plugin-sdk"
     },
     "files": [
         "dist"
@@ -27,11 +27,12 @@
     "author": "nicwands",
     "license": "MIT",
     "devDependencies": {
+        "@types/semver": "^7.7.1",
         "tsup": "^8.5.1",
-        "typescript": "^5.9.3",
+        "typescript": "^5.9.3"
-        "vitest": "^3.2.4"
     },
     "dependencies": {
+        "semver": "^7.7.4",
         "zod": "^4.3.6"
     }
 }

src/BaseNotesAdapter.ts

@@ -10,4 +10,5 @@ export abstract class BaseNotesAdapter {
     abstract create(note: any): Promise<void>
     abstract update(note: any): Promise<void>
     abstract delete(id: string): Promise<void>
+    abstract testConnection(): Promise<boolean>
 }

src/index.ts

@@ -1,6 +1,6 @@
 export { BaseNotesAdapter } from './BaseNotesAdapter'
 export { definePlugin } from './definePlugin'
-export { validatePlugin, SUPPORTED_API_VERSION } from './validatePlugin'
+export { validatePlugin, SUPPORTED_API_RANGE } from './validatePlugin'
-export { runPluginTests, createTestNote } from './testPlugin'
+export { describePluginTests, createTestNote } from './testPlugin'
 export type { NotesPlugin, ConfigField } from './types'
 export type { TestNote, TestPluginOptions } from './testPlugin'

src/testPlugin.ts

@@ -1,4 +1,5 @@
-import { SUPPORTED_API_VERSION, validatePlugin } from './validatePlugin'
+import semver from 'semver'
+import { SUPPORTED_API_RANGE, validatePlugin } from './validatePlugin'
 
 export interface TestNote {
     id: string
@@ -24,123 +25,136 @@ export interface TestPluginOptions {
         create(note: any): Promise<void>
         update(note: any): Promise<void>
         delete(id: string): Promise<void>
-    }
+        testConnection(): Promise<boolean>
-    config?: any
-}
-
-export const runPluginTests = ({ plugin, adapter }: TestPluginOptions) => {
-    return {
-        validatePlugin: (it: any, equal: (a: any, b: any) => void) => {
-            it('should be a valid plugin', () => {
-                try {
-                    validatePlugin(plugin)
-                } catch (e) {
-                    throw new Error('Plugin validation failed')
-                }
-            })
-            it('should have correct apiVersion', () => {
-                equal(plugin.apiVersion, SUPPORTED_API_VERSION)
-            })
-        },
-
-        init: (it: any) => {
-            it('should initialize without errors', async () => {
-                await adapter.init()
-            })
-        },
-
-        getAll: (it: any) => {
-            it('should return an array', async () => {
-                const notes = await adapter.getAll()
-                if (!Array.isArray(notes)) {
-                    throw new Error('getAll should return an array')
-                }
-            })
-        },
-
-        create: (it: any) => {
-            it('should create a note without errors', async () => {
-                const note = createTestNote()
-                await adapter.create(note)
-            })
-
-            it('created note should be retrievable via getAll()', async () => {
-                const note = createTestNote('test-create-note')
-                await adapter.create(note)
-                const notes = await adapter.getAll()
-                const found = notes.find((n: any) => n.id === note.id)
-                if (!found) {
-                    throw new Error('Created note not found')
-                }
-            })
-        },
-
-        update: (it: any) => {
-            it('should update a note without errors', async () => {
-                const note = createTestNote('test-update-note')
-                await adapter.create(note)
-                const updatedNote = { ...note, data: 'Updated data' }
-                await adapter.update(updatedNote)
-            })
-
-            it('updated note should reflect changes', async () => {
-                const note = createTestNote('test-update-note-2')
-                await adapter.create(note)
-                const updatedNote = { ...note, data: 'Updated data v2' }
-                await adapter.update(updatedNote)
-                const notes = await adapter.getAll()
-                const found = notes.find((n: any) => n.id === note.id)
-                if (found?.data !== 'Updated data v2') {
-                    throw new Error('Updated note data does not match')
-                }
-            })
-        },
-
-        delete: (it: any) => {
-            it('should delete a note without errors', async () => {
-                const note = createTestNote('test-delete-note')
-                await adapter.create(note)
-                await adapter.delete(note.id)
-            })
-
-            it('deleted note should not be in getAll() results', async () => {
-                const note = createTestNote('test-delete-note-2')
-                await adapter.create(note)
-                await adapter.delete(note.id)
-                const notes = await adapter.getAll()
-                const found = notes.find((n: any) => n.id === note.id)
-                if (found) {
-                    throw new Error('Deleted note still exists')
-                }
-            })
-        },
-
-        crudCycle: (it: any) => {
-            it('should complete full create -> read -> update -> delete cycle', async () => {
-                const note = createTestNote('test-crud-cycle')
-                await adapter.create(note)
-
-                let notes = await adapter.getAll()
-                if (!notes.find((n: any) => n.id === note.id)) {
-                    throw new Error('Created note not found')
-                }
-
-                const updatedNote = { ...note, data: 'CRUD update' }
-                await adapter.update(updatedNote)
-                notes = await adapter.getAll()
-                if (
-                    notes.find((n: any) => n.id === note.id)?.data !==
-                    'CRUD update'
-                ) {
-                    throw new Error('Updated note data does not match')
-                }
-
-                await adapter.delete(note.id)
-                notes = await adapter.getAll()
-                if (notes.find((n: any) => n.id === note.id)) {
-                    throw new Error('Deleted note still exists')
-                }
-            })
-        },
     }
 }
+
+export const describePluginTests = (
+    { plugin, adapter }: TestPluginOptions,
+    describe: (name: string, fn: () => void) => void,
+    it: (name: string, fn: () => void | Promise<void>) => void,
+    expect: (value: any) => {
+        toBe: (expected: any) => void
+    },
+) => {
+    describe('Plugin Validation', () => {
+        it('should be a valid plugin', () => {
+            try {
+                validatePlugin(plugin)
+            } catch (e) {
+                throw new Error('Plugin validation failed')
+            }
+        })
+        it('should have correct apiVersion', () => {
+            if (!semver.satisfies(plugin.apiVersion, SUPPORTED_API_RANGE)) {
+                throw new Error(
+                    `Plugin apiVersion ${plugin.apiVersion} does not satisfy ${SUPPORTED_API_RANGE}`,
+                )
+            }
+        })
+    })
+
+    describe('Adapter: init()', () => {
+        it('should initialize without errors', async () => {
+            await adapter.init()
+        })
+    })
+
+    describe('Adapter: getAll()', () => {
+        it('should return an array', async () => {
+            const notes = await adapter.getAll()
+            if (!Array.isArray(notes)) {
+                throw new Error('getAll should return an array')
+            }
+        })
+    })
+
+    describe('Adapter: create()', () => {
+        it('should create a note without errors', async () => {
+            const note = createTestNote()
+            await adapter.create(note)
+        })
+
+        it('created note should be retrievable via getAll()', async () => {
+            const note = createTestNote('test-create-note')
+            await adapter.create(note)
+            const notes = await adapter.getAll()
+            const found = notes.find((n) => n.id === note.id)
+            if (!found) {
+                throw new Error('Created note not found')
+            }
+        })
+    })
+
+    describe('Adapter: update()', () => {
+        it('should update a note without errors', async () => {
+            const note = createTestNote('test-update-note')
+            await adapter.create(note)
+            const updatedNote = { ...note, data: 'Updated data' }
+            await adapter.update(updatedNote)
+        })
+
+        it('updated note should reflect changes', async () => {
+            const note = createTestNote('test-update-note-2')
+            await adapter.create(note)
+            const updatedNote = { ...note, data: 'Updated data v2' }
+            await adapter.update(updatedNote)
+            const notes = await adapter.getAll()
+            const found = notes.find((n) => n.id === note.id)
+            if (found?.data !== 'Updated data v2') {
+                throw new Error('Updated note data does not match')
+            }
+        })
+    })
+
+    describe('Adapter: delete()', () => {
+        it('should delete a note without errors', async () => {
+            const note = createTestNote('test-delete-note')
+            await adapter.create(note)
+            await adapter.delete(note.id)
+        })
+
+        it('deleted note should not be in getAll() results', async () => {
+            const note = createTestNote('test-delete-note-2')
+            await adapter.create(note)
+            await adapter.delete(note.id)
+            const notes = await adapter.getAll()
+            const found = notes.find((n) => n.id === note.id)
+            if (found) {
+                throw new Error('Deleted note still exists')
+            }
+        })
+    })
+
+    describe('Adapter: testConnection()', () => {
+        it('connection test should return true', async () => {
+            const result = await adapter.testConnection()
+            expect(result).toBe(true)
+        })
+    })
+
+    describe('Full CRUD Cycle', () => {
+        it('should complete full create -> read -> update -> delete cycle', async () => {
+            const note = createTestNote('test-crud-cycle')
+            await adapter.create(note)
+
+            let notes = await adapter.getAll()
+            if (!notes.find((n) => n.id === note.id)) {
+                throw new Error('Created note not found')
+            }
+
+            const updatedNote = { ...note, data: 'CRUD update' }
+            await adapter.update(updatedNote)
+            notes = await adapter.getAll()
+            if (notes.find((n) => n.id === note.id)?.data !== 'CRUD update') {
+                throw new Error('Updated note data does not match')
+            }
+
+            await adapter.delete(note.id)
+            notes = await adapter.getAll()
+            if (notes.find((n) => n.id === note.id)) {
+                throw new Error('Deleted note still exists')
+            }
+        })
+    })
+}

src/validatePlugin.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod'
+import semver from 'semver'
 
-export const SUPPORTED_API_VERSION = '0.3.1'
+export const SUPPORTED_API_RANGE = '^0.3.0'
 
 const ConfigFieldSchema = z.object({
     key: z.string(),
@@ -23,9 +24,9 @@ const PluginSchema = z.object({
 export const validatePlugin = (plugin: unknown) => {
     const parsed = PluginSchema.parse(plugin)
 
-    if (parsed.apiVersion !== SUPPORTED_API_VERSION) {
+    if (!semver.satisfies(parsed.apiVersion, SUPPORTED_API_RANGE)) {
         throw new Error(
-            `Plugin API mismatch. Expected ${SUPPORTED_API_VERSION}`,
+            `Plugin API mismatch. Plugin uses ${parsed.apiVersion}, SDK requires ${SUPPORTED_API_RANGE}`,
         )
     }
 

tsconfig.json

@@ -8,7 +8,6 @@
         "moduleResolution": "Node",
         "esModuleInterop": true,
         "skipLibCheck": true,
-        "types": ["vitest/globals"]
     },
-    "include": ["src"]
+    "include": ["src"],
 }