lumiverse-spindle-types 0.2.2 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "types": "./src/index.ts",
   "keywords": [
     "lumiverse",

package/src/spindle-api.ts

@@ -402,6 +402,56 @@ export interface SpindleAPI {
     }>;
   };
 
+  /**
+   * Macro resolution (free tier — no permission needed).
+   * Resolve `{{macro}}` placeholders in arbitrary text using
+   * the full Lumiverse macro engine (character fields, chat context,
+   * variables, time/date, random, etc.).
+   */
+  macros: {
+    /**
+     * Resolve all macros in the given template string.
+     * Provide `chatId` and/or `characterId` for full context resolution.
+     * Without them, only context-free macros (time, random, etc.) resolve.
+     *
+     * @example
+     * ```ts
+     * const { text } = await spindle.macros.resolve(
+     *   'Hello {{user}}, I am {{char}}!',
+     *   { chatId: 'abc', characterId: 'xyz' },
+     * )
+     * ```
+     */
+    resolve(
+      template: string,
+      options?: {
+        chatId?: string;
+        characterId?: string;
+        /** For operator-scoped extensions only. */
+        userId?: string;
+      },
+    ): Promise<{
+      text: string;
+      diagnostics: Array<{ message: string; offset: number; length: number }>;
+    }>;
+  };
+
+  /**
+   * User presence queries (free tier — no permission needed).
+   * Check whether a user currently has the Lumiverse app visible/focused
+   * in at least one browser tab or PWA window.
+   */
+  users: {
+    /**
+     * Returns true if the user has the app visible in at least one session.
+     * Returns false if all sessions are hidden/backgrounded or the user has no
+     * active WebSocket connections.
+     * For user-scoped extensions, userId is inferred from the extension owner.
+     * For operator-scoped extensions, pass userId explicitly.
+     */
+    isVisible(userId?: string): Promise<boolean>;
+  };
+
   /** Show toast notifications in the frontend UI (free tier — no permission needed) */
   toast: {
     success(message: string, options?: { title?: string; duration?: number }): void;