@stina/extension-api 0.11.2 → 0.14.0

package/src/types.ts

@@ -435,7 +435,28 @@ export interface Disposable {
 }
 
 /**
- * Context provided to extension's activate function
+ * Context provided to extension's activate function.
+ *
+ * ## User ID Context
+ *
+ * The `userId` field provides the current user context for extensions. It is set when:
+ * - A tool is executed by a user
+ * - An action is executed by a user
+ * - A scheduled job fires (if the job was created with a userId)
+ *
+ * For extension activation, `userId` is undefined since activation happens at system level.
+ * Extensions should check for `userId` in their tool/action handlers to access user-specific data.
+ *
+ * @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')
+ *   }
+ * }
+ * ```
  */
 export interface ExtensionContext {
   /** Extension metadata */
@@ -445,6 +466,12 @@ export interface ExtensionContext {
     readonly storagePath: string
   }
 
+  /**
+   * Current user ID if in a user context, undefined for global/system operations.
+   * Set when tools or actions are executed by a user, or when a user-scoped job fires.
+   */
+  readonly userId?: string
+
   /** Network access (if permitted) */
   readonly network?: NetworkAPI
 
@@ -573,6 +600,12 @@ export interface SchedulerJobRequest {
   schedule: SchedulerSchedule
   payload?: Record<string, unknown>
   misfire?: 'run_once' | 'skip'
+  /**
+   * Optional user ID for user-scoped jobs.
+   * If set, the job is associated with a specific user and the userId
+   * will be passed to the extension when the job fires.
+   */
+  userId?: string
 }
 
 /**
@@ -584,6 +617,8 @@ export interface SchedulerFirePayload {
   scheduledFor: string
   firedAt: string
   delayMs: number
+  /** User ID if this is a user-scoped job, undefined if global */
+  userId?: string
 }
 
 /**
@@ -638,28 +673,78 @@ export interface DatabaseAPI {
 }
 
 /**
- * Simple key-value storage API
+ * 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')
+ * }
+ * ```
  */
 export interface StorageAPI {
   /**
-   * Get a value by key
+   * Get a value by key (global/extension-scoped)
    */
   get<T>(key: string): Promise<T | undefined>
 
   /**
-   * Set a value
+   * Set a value (global/extension-scoped)
    */
   set(key: string, value: unknown): Promise<void>
 
   /**
-   * Delete a key
+   * Delete a key (global/extension-scoped)
    */
   delete(key: string): Promise<void>
 
   /**
-   * Get all keys
+   * 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[]>
 }
 
 /**

package/dist/chunk-IKJ37ZGB.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/messages.ts"],"sourcesContent":["/**\n * Message protocol between Extension Host and Extension Workers\n */\n\nimport type {\n  ChatMessage,\n  ChatOptions,\n  GetModelsOptions,\n  StreamEvent,\n  ToolResult,\n  ActionResult,\n  ModelInfo,\n  SchedulerFirePayload,\n} from './types.js'\n\n// ============================================================================\n// Host → Worker Messages\n// ============================================================================\n\nexport type HostToWorkerMessage =\n  | ActivateMessage\n  | DeactivateMessage\n  | SettingsChangedMessage\n  | SchedulerFireMessage\n  | ProviderChatRequestMessage\n  | ProviderModelsRequestMessage\n  | ToolExecuteRequestMessage\n  | ActionExecuteRequestMessage\n  | ResponseMessage\n\nexport interface ActivateMessage {\n  type: 'activate'\n  id: string\n  payload: {\n    extensionId: string\n    extensionVersion: string\n    storagePath: string\n    permissions: string[]\n    settings: Record<string, unknown>\n  }\n}\n\nexport interface DeactivateMessage {\n  type: 'deactivate'\n  id: string\n}\n\nexport interface SettingsChangedMessage {\n  type: 'settings-changed'\n  id: string\n  payload: {\n    key: string\n    value: unknown\n  }\n}\n\nexport interface SchedulerFireMessage {\n  type: 'scheduler-fire'\n  id: string\n  payload: SchedulerFirePayload\n}\n\nexport interface ProviderChatRequestMessage {\n  type: 'provider-chat-request'\n  id: string\n  payload: {\n    providerId: string\n    messages: ChatMessage[]\n    options: ChatOptions\n  }\n}\n\nexport interface ProviderModelsRequestMessage {\n  type: 'provider-models-request'\n  id: string\n  payload: {\n    providerId: string\n    options?: GetModelsOptions\n  }\n}\n\nexport interface ToolExecuteRequestMessage {\n  type: 'tool-execute-request'\n  id: string\n  payload: {\n    toolId: string\n    params: Record<string, unknown>\n  }\n}\n\nexport interface ActionExecuteRequestMessage {\n  type: 'action-execute-request'\n  id: string\n  payload: {\n    actionId: string\n    params: Record<string, unknown>\n  }\n}\n\nexport interface ResponseMessage {\n  type: 'response'\n  id: string\n  payload: {\n    requestId: string\n    success: boolean\n    data?: unknown\n    error?: string\n  }\n}\n\n// ============================================================================\n// Worker → Host Messages\n// ============================================================================\n\nexport type WorkerToHostMessage =\n  | ReadyMessage\n  | RequestMessage\n  | ProviderRegisteredMessage\n  | ToolRegisteredMessage\n  | ActionRegisteredMessage\n  | StreamEventMessage\n  | LogMessage\n  | ProviderModelsResponseMessage\n  | ToolExecuteResponseMessage\n  | ActionExecuteResponseMessage\n\nexport interface ReadyMessage {\n  type: 'ready'\n}\n\nexport interface RequestMessage {\n  type: 'request'\n  id: string\n  method: RequestMethod\n  payload: unknown\n}\n\nexport type RequestMethod =\n  | 'network.fetch'\n  | 'settings.getAll'\n  | 'settings.get'\n  | 'settings.set'\n  | 'user.getProfile'\n  | 'events.emit'\n  | 'scheduler.schedule'\n  | 'scheduler.cancel'\n  | 'chat.appendInstruction'\n  | 'database.execute'\n  | 'storage.get'\n  | 'storage.set'\n  | 'storage.delete'\n  | 'storage.keys'\n\nexport interface ProviderRegisteredMessage {\n  type: 'provider-registered'\n  payload: {\n    id: string\n    name: string\n  }\n}\n\nexport interface ToolRegisteredMessage {\n  type: 'tool-registered'\n  payload: {\n    id: string\n    name: string\n    description: string\n    parameters?: Record<string, unknown>\n  }\n}\n\nexport interface ActionRegisteredMessage {\n  type: 'action-registered'\n  payload: {\n    id: string\n  }\n}\n\nexport interface StreamEventMessage {\n  type: 'stream-event'\n  payload: {\n    requestId: string\n    event: StreamEvent\n  }\n}\n\nexport interface ProviderModelsResponseMessage {\n  type: 'provider-models-response'\n  payload: {\n    requestId: string\n    models: ModelInfo[]\n    error?: string\n  }\n}\n\nexport interface ToolExecuteResponseMessage {\n  type: 'tool-execute-response'\n  payload: {\n    requestId: string\n    result: ToolResult\n    error?: string\n  }\n}\n\nexport interface ActionExecuteResponseMessage {\n  type: 'action-execute-response'\n  payload: {\n    requestId: string\n    result: ActionResult\n    error?: string\n  }\n}\n\nexport interface LogMessage {\n  type: 'log'\n  payload: {\n    level: 'debug' | 'info' | 'warn' | 'error'\n    message: string\n    data?: Record<string, unknown>\n  }\n}\n\n// ============================================================================\n// Utility Types\n// ============================================================================\n\nexport interface PendingRequest<T = unknown> {\n  resolve: (value: T) => void\n  reject: (error: Error) => void\n  timeout: ReturnType<typeof setTimeout>\n}\n\n/**\n * Generate a unique message ID\n */\nexport function generateMessageId(): string {\n  return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`\n}\n"],"mappings":";;;;;;;;AA2OO,SAAS,oBAA4B;AAC1C,SAAO,GAAG,KAAK,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,GAAG,EAAE,CAAC;AACjE;","names":[]}