@stina/extension-api 0.22.0 → 0.23.0

package/dist/{types.tools-BXGZf8zc.d.ts → types.tools-6o0mTWW-.d.ts}

@@ -379,6 +379,15 @@ interface ExtensionContributions {
     commands?: CommandDefinition[];
     /** Prompt contributions for the system prompt */
     prompts?: PromptContribution[];
+    /** Storage collection declarations */
+    storage?: {
+        collections: {
+            [name: string]: {
+                /** Fields to index for fast queries */
+                indexes?: string[];
+            };
+        };
+    };
 }
 /**
  * Setting definition for the UI
@@ -819,6 +828,277 @@ type StreamEvent = {
     message: string;
 };
 
+/**
+ * Storage Types
+ *
+ * Types for the new collection-based document storage API.
+ * Provides a MongoDB-inspired but simplified query syntax for extensions.
+ */
+/**
+ * Query syntax for filtering documents in a collection.
+ * Supports exact matching and comparison operators.
+ *
+ * @example
+ * // Exact match
+ * { status: "active" }
+ *
+ * @example
+ * // Comparison operators
+ * { age: { $gt: 18 }, status: { $in: ["active", "pending"] } }
+ *
+ * @example
+ * // String contains (case-insensitive)
+ * { name: { $contains: "john" } }
+ */
+interface Query {
+    [field: string]: unknown | {
+        $gt?: unknown;
+    } | {
+        $gte?: unknown;
+    } | {
+        $lt?: unknown;
+    } | {
+        $lte?: unknown;
+    } | {
+        $ne?: unknown;
+    } | {
+        $in?: unknown[];
+    } | {
+        $contains?: string;
+    };
+}
+/**
+ * Optional modifiers for query operations.
+ * Allows sorting, pagination, and limiting results.
+ */
+interface QueryOptions {
+    /**
+     * Sort results by one or more fields.
+     * @example { createdAt: 'desc', name: 'asc' }
+     */
+    sort?: {
+        [field: string]: 'asc' | 'desc';
+    };
+    /**
+     * Maximum number of documents to return.
+     */
+    limit?: number;
+    /**
+     * Number of documents to skip (for pagination).
+     */
+    offset?: number;
+}
+/**
+ * Storage API for extension-scoped document storage.
+ * All operations are automatically scoped to the calling extension.
+ * Data is stored as JSON documents in collections.
+ */
+interface StorageAPI {
+    /**
+     * Store a document in a collection.
+     * Creates the document if it doesn't exist, or replaces it if it does.
+     *
+     * @param collection - The name of the collection
+     * @param id - Unique identifier for the document within the collection
+     * @param data - The document data to store
+     *
+     * @example
+     * await storage.put('users', 'user-123', { name: 'John', age: 30 })
+     */
+    put<T extends object>(collection: string, id: string, data: T): Promise<void>;
+    /**
+     * Retrieve a document from a collection by its ID.
+     *
+     * @param collection - The name of the collection
+     * @param id - The document ID to retrieve
+     * @returns The document data, or undefined if not found
+     *
+     * @example
+     * const user = await storage.get<User>('users', 'user-123')
+     */
+    get<T>(collection: string, id: string): Promise<T | undefined>;
+    /**
+     * Delete a document from a collection.
+     *
+     * @param collection - The name of the collection
+     * @param id - The document ID to delete
+     * @returns True if the document was deleted, false if it didn't exist
+     *
+     * @example
+     * const wasDeleted = await storage.delete('users', 'user-123')
+     */
+    delete(collection: string, id: string): Promise<boolean>;
+    /**
+     * Find documents matching a query.
+     *
+     * @param collection - The name of the collection
+     * @param query - Optional query to filter documents
+     * @param options - Optional query modifiers (sort, limit, offset)
+     * @returns Array of matching documents
+     *
+     * @example
+     * // Find all active users, sorted by name
+     * const users = await storage.find<User>('users',
+     *   { status: 'active' },
+     *   { sort: { name: 'asc' }, limit: 10 }
+     * )
+     */
+    find<T>(collection: string, query?: Query, options?: QueryOptions): Promise<T[]>;
+    /**
+     * Find a single document matching a query.
+     * Returns the first match if multiple documents match.
+     *
+     * @param collection - The name of the collection
+     * @param query - Query to filter documents
+     * @returns The first matching document, or undefined if none found
+     *
+     * @example
+     * const user = await storage.findOne<User>('users', { email: 'john@example.com' })
+     */
+    findOne<T>(collection: string, query: Query): Promise<T | undefined>;
+    /**
+     * Count documents matching a query.
+     *
+     * @param collection - The name of the collection
+     * @param query - Optional query to filter documents
+     * @returns The number of matching documents
+     *
+     * @example
+     * const activeCount = await storage.count('users', { status: 'active' })
+     */
+    count(collection: string, query?: Query): Promise<number>;
+    /**
+     * Store multiple documents in a collection in a single operation.
+     * More efficient than multiple individual put calls.
+     *
+     * @param collection - The name of the collection
+     * @param docs - Array of documents with their IDs
+     *
+     * @example
+     * await storage.putMany('users', [
+     *   { id: 'user-1', data: { name: 'John' } },
+     *   { id: 'user-2', data: { name: 'Jane' } }
+     * ])
+     */
+    putMany<T extends object>(collection: string, docs: Array<{
+        id: string;
+        data: T;
+    }>): Promise<void>;
+    /**
+     * Delete multiple documents matching a query.
+     *
+     * @param collection - The name of the collection
+     * @param query - Query to match documents for deletion
+     * @returns The number of documents deleted
+     *
+     * @example
+     * const deleted = await storage.deleteMany('users', { status: 'inactive' })
+     */
+    deleteMany(collection: string, query: Query): Promise<number>;
+    /**
+     * Drop an entire collection, deleting all its documents.
+     * Use with caution - this operation cannot be undone.
+     *
+     * @param collection - The name of the collection to drop
+     *
+     * @example
+     * await storage.dropCollection('temp-data')
+     */
+    dropCollection(collection: string): Promise<void>;
+    /**
+     * List all collections owned by this extension.
+     *
+     * @returns Array of collection names
+     *
+     * @example
+     * const collections = await storage.listCollections()
+     * // ['users', 'settings', 'cache']
+     */
+    listCollections(): Promise<string[]>;
+}
+/**
+ * Secrets API for secure storage of sensitive values.
+ * All operations are automatically scoped to the calling extension.
+ * Values are encrypted at rest.
+ */
+interface SecretsAPI {
+    /**
+     * Store a secret value.
+     * Creates the secret if it doesn't exist, or replaces it if it does.
+     *
+     * @param key - Unique key for the secret
+     * @param value - The secret value to store
+     *
+     * @example
+     * await secrets.set('api-key', 'sk-1234567890')
+     */
+    set(key: string, value: string): Promise<void>;
+    /**
+     * Retrieve a secret value.
+     *
+     * @param key - The secret key to retrieve
+     * @returns The secret value, or undefined if not found
+     *
+     * @example
+     * const apiKey = await secrets.get('api-key')
+     */
+    get(key: string): Promise<string | undefined>;
+    /**
+     * Delete a secret.
+     *
+     * @param key - The secret key to delete
+     * @returns True if the secret was deleted, false if it didn't exist
+     *
+     * @example
+     * const wasDeleted = await secrets.delete('api-key')
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * List all secret keys owned by this extension.
+     * Only returns the keys, not the secret values.
+     *
+     * @returns Array of secret keys
+     *
+     * @example
+     * const keys = await secrets.list()
+     * // ['api-key', 'webhook-secret']
+     */
+    list(): Promise<string[]>;
+}
+/**
+ * Configuration for a storage collection in the extension manifest.
+ * Allows extensions to declare collections and their indexing requirements.
+ */
+interface StorageCollectionConfig {
+    /**
+     * Fields that should be indexed for fast queries.
+     * Indexed fields allow efficient filtering and sorting.
+     *
+     * @example ['status', 'createdAt', 'userId']
+     */
+    indexes?: string[];
+}
+/**
+ * Storage contributions section in the extension manifest.
+ * Declares the collections an extension will use.
+ *
+ * @example
+ * {
+ *   collections: {
+ *     users: { indexes: ['email', 'status'] },
+ *     settings: {}
+ *   }
+ * }
+ */
+interface StorageContributions {
+    /**
+     * Map of collection names to their configuration.
+     */
+    collections: {
+        [name: string]: StorageCollectionConfig;
+    };
+}
+
 /**
  * Extension Context Types
  *
@@ -845,15 +1125,29 @@ interface Disposable {
  * - Makes code easier to reason about and debug
  * - Allows scheduler jobs to create context for the correct user
  *
+ * ## Storage and Secrets
+ *
+ * The context provides both extension-scoped and user-scoped storage:
+ * - `storage`: Extension-wide document storage (shared across all users)
+ * - `userStorage`: User-specific document storage (isolated per user)
+ * - `secrets`: Extension-wide secrets (shared across all users)
+ * - `userSecrets`: User-specific secrets (isolated per user)
+ *
  * @example
  * ```typescript
  * // In a tool execute handler:
  * execute: async (params, context) => {
- *   if (context.userId) {
- *     // User-specific logic
- *     const userData = await storage.getForUser(context.userId, 'preferences')
- *   }
- *   // Access extension metadata
+ *   // Extension-wide storage (shared across all users)
+ *   const config = await context.storage.get<Config>('settings', 'global-config')
+ *
+ *   // User-specific storage (isolated per user)
+ *   const prefs = await context.userStorage.get<Preferences>('preferences', 'theme')
+ *   await context.userStorage.put('preferences', 'theme', { mode: 'dark' })
+ *
+ *   // Secrets access
+ *   const apiKey = await context.secrets.get('api-key')
+ *   const userToken = await context.userSecrets.get('oauth-token')
+ *
  *   console.log(`Running in extension ${context.extension.id}`)
  * }
  * ```
@@ -871,6 +1165,14 @@ interface ExecutionContext {
         readonly version: string;
         readonly storagePath: string;
     };
+    /** Extension-scoped storage (same for all users) */
+    readonly storage: StorageAPI;
+    /** User-scoped storage (isolated per user) */
+    readonly userStorage: StorageAPI;
+    /** Extension-scoped secrets */
+    readonly secrets: SecretsAPI;
+    /** User-scoped secrets */
+    readonly userSecrets: SecretsAPI;
 }
 /**
  * Context provided to extension's activate function.
@@ -903,10 +1205,10 @@ interface ExtensionContext {
     readonly user?: UserAPI;
     /** Chat access (if permitted) */
     readonly chat?: ChatAPI;
-    /** Database access (if permitted) */
-    readonly database?: DatabaseAPI;
-    /** Local storage (if permitted) */
+    /** Collection-based document storage (if permitted) */
     readonly storage?: StorageAPI;
+    /** Secure secrets storage (if permitted) */
+    readonly secrets?: SecretsAPI;
     /** Background workers (if permitted) */
     readonly backgroundWorkers?: BackgroundWorkersAPI;
     /** Logging (always available) */
@@ -1081,82 +1383,6 @@ interface ChatInstructionMessage {
 interface ChatAPI {
     appendInstruction(message: ChatInstructionMessage): Promise<void>;
 }
-/**
- * Database API for extension-specific tables
- */
-interface DatabaseAPI {
-    /**
-     * Execute a SQL query (only extension's prefixed tables allowed)
-     */
-    execute<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
-}
-/**
- * Simple key-value storage API with support for user-scoped storage.
- *
- * ## Global vs User-Scoped Storage
- *
- * Extensions have access to two types of storage:
- * - **Global storage**: Shared across all users, accessed via `get()`, `set()`, etc.
- * - **User-scoped storage**: Isolated per user, accessed via `getForUser()`, `setForUser()`, etc.
- *
- * Use global storage for extension-wide settings and user-scoped storage for
- * user preferences, session data, or any data that should be private to a user.
- *
- * @example
- * ```typescript
- * // Global storage (extension-wide)
- * await storage.set('apiEndpoint', 'https://api.example.com')
- * const endpoint = await storage.get<string>('apiEndpoint')
- *
- * // User-scoped storage (per-user)
- * if (context.userId) {
- *   await storage.setForUser(context.userId, 'preferences', { theme: 'dark' })
- *   const prefs = await storage.getForUser<Preferences>(context.userId, 'preferences')
- * }
- * ```
- */
-interface StorageAPI {
-    /**
-     * Get a value by key (global/extension-scoped)
-     */
-    get<T>(key: string): Promise<T | undefined>;
-    /**
-     * Set a value (global/extension-scoped)
-     */
-    set(key: string, value: unknown): Promise<void>;
-    /**
-     * Delete a key (global/extension-scoped)
-     */
-    delete(key: string): Promise<void>;
-    /**
-     * Get all keys (global/extension-scoped)
-     */
-    keys(): Promise<string[]>;
-    /**
-     * Get a value by key for a specific user (user-scoped)
-     * @param userId The user ID
-     * @param key The storage key
-     */
-    getForUser<T>(userId: string, key: string): Promise<T | undefined>;
-    /**
-     * Set a value for a specific user (user-scoped)
-     * @param userId The user ID
-     * @param key The storage key
-     * @param value The value to store
-     */
-    setForUser(userId: string, key: string, value: unknown): Promise<void>;
-    /**
-     * Delete a key for a specific user (user-scoped)
-     * @param userId The user ID
-     * @param key The storage key
-     */
-    deleteForUser(userId: string, key: string): Promise<void>;
-    /**
-     * Get all keys for a specific user (user-scoped)
-     * @param userId The user ID
-     */
-    keysForUser(userId: string): Promise<string[]>;
-}
 /**
  * Logging API
  */
@@ -1429,4 +1655,4 @@ interface ActionResult {
     error?: string;
 }
 
-export { type BackgroundWorkersAPI as $, type ActionResult as A, type ExtensionContext as B, type ChatMessage as C, type Disposable as D, type ExtensionContributions as E, type SettingsAPI as F, type GetModelsOptions as G, type ProvidersAPI as H, type ToolsAPI as I, type ActionsAPI as J, type EventsAPI as K, type LocalizedString as L, type ModelInfo as M, type NetworkAPI as N, type SchedulerAPI as O, type PanelDefinition as P, type SchedulerJobRequest as Q, type SchedulerSchedule as R, type SchedulerFirePayload as S, type ToolResult as T, type UserAPI as U, type UserProfile as V, type ChatAPI as W, type ChatInstructionMessage as X, type DatabaseAPI as Y, type StorageAPI as Z, type LogAPI as _, type ChatOptions as a, type BackgroundTaskConfig as a0, type BackgroundTaskCallback as a1, type BackgroundTaskContext as a2, type BackgroundTaskHealth as a3, type BackgroundRestartPolicy as a4, type AIProvider as a5, type ToolCall as a6, type Tool as a7, type Action as a8, type ExtensionModule as a9, type CollapsibleProps as aA, type PillVariant as aB, type PillProps as aC, type CheckboxProps as aD, type MarkdownProps as aE, type ModalProps as aF, type ConditionalGroupProps as aG, type ExecutionContext as aH, type AllowedCSSProperty as aa, type ExtensionComponentStyle as ab, type ExtensionComponentData as ac, type ExtensionComponentIterator as ad, type ExtensionComponentChildren as ae, type ExtensionActionCall as af, type ExtensionActionRef as ag, type ExtensionDataSource as ah, type ExtensionPanelDefinition as ai, type HeaderProps as aj, type LabelProps as ak, type ParagraphProps as al, type ButtonProps as am, type TextInputProps as an, type DateTimeInputProps as ao, type SelectProps as ap, type VerticalStackProps as aq, type HorizontalStackProps as ar, type GridProps as as, type DividerProps as at, type IconProps as au, type IconButtonType as av, type IconButtonProps as aw, type PanelAction as ax, type PanelProps as ay, type ToggleProps as az, type StreamEvent as b, type SettingDefinition as c, type SettingOptionsMapping as d, type SettingCreateMapping as e, type ToolSettingsViewDefinition as f, type ToolSettingsView as g, type ToolSettingsListView as h, type ToolSettingsListMapping as i, type ToolSettingsComponentView as j, type ToolSettingsActionDataSource as k, type PanelView as l, type PanelComponentView as m, type PanelActionDataSource as n, type PanelUnknownView as o, type ProviderDefinition as p, type PromptContribution as q, resolveLocalizedString as r, type PromptSection as s, type ToolDefinition as t, type CommandDefinition as u, type ProviderConfigSchema as v, type ProviderConfigProperty as w, type ProviderConfigPropertyType as x, type ProviderConfigSelectOption as y, type ProviderConfigValidation as z };
+export { type BackgroundTaskCallback as $, type ActionResult as A, type ExtensionContext as B, type ChatMessage as C, type Disposable as D, type ExtensionContributions as E, type SettingsAPI as F, type GetModelsOptions as G, type ProvidersAPI as H, type ToolsAPI as I, type ActionsAPI as J, type EventsAPI as K, type LocalizedString as L, type ModelInfo as M, type NetworkAPI as N, type SchedulerAPI as O, type PanelDefinition as P, type SchedulerJobRequest as Q, type SchedulerSchedule as R, type SchedulerFirePayload as S, type ToolResult as T, type UserAPI as U, type UserProfile as V, type ChatAPI as W, type ChatInstructionMessage as X, type LogAPI as Y, type BackgroundWorkersAPI as Z, type BackgroundTaskConfig as _, type ChatOptions as a, type BackgroundTaskContext as a0, type BackgroundTaskHealth as a1, type BackgroundRestartPolicy as a2, type Query as a3, type QueryOptions as a4, type StorageAPI as a5, type SecretsAPI as a6, type StorageCollectionConfig as a7, type StorageContributions as a8, type AIProvider as a9, type IconButtonProps as aA, type PanelAction as aB, type PanelProps as aC, type ToggleProps as aD, type CollapsibleProps as aE, type PillVariant as aF, type PillProps as aG, type CheckboxProps as aH, type MarkdownProps as aI, type ModalProps as aJ, type ConditionalGroupProps as aK, type ExecutionContext as aL, type ToolCall as aa, type Tool as ab, type Action as ac, type ExtensionModule as ad, type AllowedCSSProperty as ae, type ExtensionComponentStyle as af, type ExtensionComponentData as ag, type ExtensionComponentIterator as ah, type ExtensionComponentChildren as ai, type ExtensionActionCall as aj, type ExtensionActionRef as ak, type ExtensionDataSource as al, type ExtensionPanelDefinition as am, type HeaderProps as an, type LabelProps as ao, type ParagraphProps as ap, type ButtonProps as aq, type TextInputProps as ar, type DateTimeInputProps as as, type SelectProps as at, type VerticalStackProps as au, type HorizontalStackProps as av, type GridProps as aw, type DividerProps as ax, type IconProps as ay, type IconButtonType as az, type StreamEvent as b, type SettingDefinition as c, type SettingOptionsMapping as d, type SettingCreateMapping as e, type ToolSettingsViewDefinition as f, type ToolSettingsView as g, type ToolSettingsListView as h, type ToolSettingsListMapping as i, type ToolSettingsComponentView as j, type ToolSettingsActionDataSource as k, type PanelView as l, type PanelComponentView as m, type PanelActionDataSource as n, type PanelUnknownView as o, type ProviderDefinition as p, type PromptContribution as q, resolveLocalizedString as r, type PromptSection as s, type ToolDefinition as t, type CommandDefinition as u, type ProviderConfigSchema as v, type ProviderConfigProperty as w, type ProviderConfigPropertyType as x, type ProviderConfigSelectOption as y, type ProviderConfigValidation as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stina/extension-api",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -19,18 +19,30 @@
       "types": "./dist/runtime.d.ts",
       "import": "./dist/runtime.js",
       "require": "./dist/runtime.cjs"
-    }
+    },
+    "./schemas": {
+      "types": "./dist/schemas/index.d.ts",
+      "import": "./dist/schemas/index.js",
+      "require": "./dist/schemas/index.cjs"
+    },
+    "./schema.json": "./schema/extension-manifest.schema.json"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && pnpm build:schema",
+    "build:schema": "tsx scripts/generate-schema.ts",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
     "tsup": "^8.0.0",
-    "typescript": "^5.3.0"
+    "tsx": "^4.21.0",
+    "typescript": "^5.3.0",
+    "zod-to-json-schema": "^3.25.1"
+  },
+  "dependencies": {
+    "zod": "^3.25.76"
   }
 }