chatablex-web-sdk 1.0.0 → 1.0.31

package/src/modules/auth.ts

@@ -0,0 +1,102 @@
+import type { Bridge } from '../bridge';
+import type { AuthTokenData, ChatableXAuth } from '../types';
+
+/**
+ * Strategy interface behind `sdk.auth`. Lets us swap how a token is obtained
+ * (hosted WebView today, browser/unified-login later) without touching any
+ * consumer code or the public `ChatableXAuth` surface.
+ */
+export interface AuthProvider extends ChatableXAuth {}
+
+/** Treat a token as expired this many ms before its real `expires_at`. */
+const EXPIRY_SKEW_MS = 5_000;
+
+/** Shape of the host reply to `host.getAuthToken`. */
+type HostAuthResponse =
+  | { access_token: string; expires_at: number; user_id: string; error?: undefined }
+  | { error: string; access_token?: undefined };
+
+function isValid(token: AuthTokenData | null, now: number): token is AuthTokenData {
+  return !!token && typeof token.access_token === 'string' && token.access_token.length > 0
+    && token.expires_at - EXPIRY_SKEW_MS > now;
+}
+
+/**
+ * Auth provider that reuses the desktop host's login session over the bridge.
+ * Token lives in memory only; the refresh_token never crosses the bridge —
+ * the host refreshes before sending (see FR-05).
+ */
+export class HostAuthProvider implements AuthProvider {
+  private _bridge: Bridge;
+  private _token: AuthTokenData | null = null;
+  /** In-flight refresh, so concurrent callers share one host round-trip. */
+  private _refreshing: Promise<boolean> | null = null;
+
+  constructor(bridge: Bridge) {
+    this._bridge = bridge;
+  }
+
+  async getToken(): Promise<AuthTokenData | null> {
+    if (isValid(this._token, Date.now())) return this._token;
+    const ok = await this.refresh();
+    return ok ? this._token : null;
+  }
+
+  async getAuthHeaders(): Promise<Record<string, string>> {
+    const token = await this.getToken();
+    if (!token) return {};
+    return { Authorization: `Bearer ${token.access_token}` };
+  }
+
+  getUserId(): string | null {
+    return this._token?.user_id ?? null;
+  }
+
+  isAuthenticated(): boolean {
+    return isValid(this._token, Date.now());
+  }
+
+  refresh(): Promise<boolean> {
+    // single-flight: merge concurrent refreshes into one host round-trip
+    if (this._refreshing) return this._refreshing;
+    this._refreshing = this._doRefresh().finally(() => {
+      this._refreshing = null;
+    });
+    return this._refreshing;
+  }
+
+  private async _doRefresh(): Promise<boolean> {
+    try {
+      const raw = (await this._bridge.sendMessage('host.getAuthToken')) as HostAuthResponse | null;
+      if (
+        raw &&
+        typeof raw === 'object' &&
+        typeof raw.access_token === 'string' &&
+        raw.access_token.length > 0
+      ) {
+        this._token = {
+          access_token: raw.access_token,
+          expires_at: Number(raw.expires_at) || 0,
+          user_id: String(raw.user_id ?? ''),
+        };
+        return true;
+      }
+      // not authenticated / not hosted / host returned { error }
+      this._token = null;
+      return false;
+    } catch {
+      // bridge unavailable (non-WebView) or host error — degrade safely
+      this._token = null;
+      return false;
+    }
+  }
+}
+
+/**
+ * Build the `auth` module. Selects the provider for the current environment;
+ * today there is only `HostAuthProvider`. A future `WebAuthProvider`
+ * (browser / unified login) can be slotted in here without changing callers.
+ */
+export function createAuthModule(bridge: Bridge): ChatableXAuth {
+  return new HostAuthProvider(bridge);
+}

package/src/modules/platform.ts

@@ -0,0 +1,14 @@
+import type { Bridge } from '../bridge';
+import type { ChatableXPlatform } from '../types';
+
+export function createPlatformModule(bridge: Bridge): ChatableXPlatform {
+  return {
+    async openInBrowser(targetUrl: string): Promise<void> {
+      const url = typeof targetUrl === 'string' ? targetUrl.trim() : '';
+      if (!url) {
+        throw new Error('openInBrowser: targetUrl is required');
+      }
+      await bridge.sendMessage('host.openInBrowser', { url });
+    },
+  };
+}

package/src/modules/ui.ts

@@ -16,11 +16,11 @@ export function createUIModule(bridge: Bridge): ChatableXUI {
     },
 
     openTab(config: TabConfig): Promise<void> {
-      return bridge.sendMessage('ui.openTab', config as unknown as Record<string, unknown>) as Promise<void>;
+      return bridge.sendMessage('ui.openTab', config) as Promise<void>;
     },
 
     updateState(state: StateUpdate): Promise<void> {
-      return bridge.sendMessage('ui.updateState', state as Record<string, unknown>) as Promise<void>;
+      return bridge.sendMessage('ui.updateState', state) as Promise<void>;
     },
   };
 }

package/src/types.ts

@@ -80,38 +80,6 @@ export interface ToolResult {
 
 export type ToolExecuteHandler = (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
 
-// ---------------------------------------------------------------------------
-// Skill
-// ---------------------------------------------------------------------------
-
-export interface Skill {
-  id: string;
-  name: string;
-  description: string;
-  version: string;
-  author?: string;
-  category?: string;
-  toolIds: string[];
-  variables: SkillVariable[];
-  installed: boolean;
-}
-
-export interface SkillVariable {
-  name: string;
-  type: string;
-  description: string;
-  required: boolean;
-  default?: unknown;
-}
-
-export interface SkillResult {
-  success: boolean;
-  data?: unknown;
-  error?: string;
-  skillId: string;
-  toolResults?: ToolResult[];
-}
-
 // ---------------------------------------------------------------------------
 // UI
 // ---------------------------------------------------------------------------
@@ -211,11 +179,6 @@ export interface ChatableXTools {
   executeWithConfirm(toolId: string, params: Record<string, unknown>): Promise<ToolResult>;
 }
 
-export interface ChatableXSkills {
-  list(): Promise<Skill[]>;
-  execute(skillId: string, variables: Record<string, unknown>): Promise<SkillResult>;
-}
-
 export interface ChatableXUI {
   showNotification(message: string, type?: NotificationType): Promise<void>;
   showConfirm(title: string, message: string): Promise<boolean>;
@@ -242,14 +205,61 @@ export interface ChatableXToolModule {
   onExecute(handler: ToolExecuteHandler): void;
 }
 
+export interface ChatableXPlatform {
+  /** Open URL in system browser with auth handoff (WebView only; implemented by Flutter host). */
+  openInBrowser(targetUrl: string): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Auth
+// ---------------------------------------------------------------------------
+
+/** Token payload returned by the host (never includes the refresh_token). */
+export interface AuthTokenData {
+  /** Bearer access token to put in the Authorization header. */
+  access_token: string;
+  /** Access token expiry, epoch milliseconds. */
+  expires_at: number;
+  /** Authenticated user id. */
+  user_id: string;
+}
+
+/**
+ * Unified auth entry point for all WebUI apps.
+ *
+ * In a hosted (Flutter WebView) environment this reuses the desktop login
+ * session via the `host.getAuthToken` bridge call — apps never implement
+ * login or token handling themselves.
+ */
+export interface ChatableXAuth {
+  /**
+   * Get a valid access token. Returns the in-memory cached token when still
+   * valid, otherwise fetches a fresh one from the host. Returns `null` when
+   * not authenticated / not hosted.
+   */
+  getToken(): Promise<AuthTokenData | null>;
+  /**
+   * Build auth headers ready to spread into a `fetch`. Returns
+   * `{ Authorization: "Bearer <token>" }` when authenticated, otherwise `{}`.
+   */
+  getAuthHeaders(): Promise<Record<string, string>>;
+  /** Currently authenticated user id, or `null`. Synchronous (cache only). */
+  getUserId(): string | null;
+  /** Whether a valid token is currently cached. Synchronous (cache only). */
+  isAuthenticated(): boolean;
+  /** Force a token refresh via the host. Resolves `true` on success. */
+  refresh(): Promise<boolean>;
+}
+
 export interface ChatableXSDK {
   ai: ChatableXAI;
   tools: ChatableXTools;
-  skills: ChatableXSkills;
   ui: ChatableXUI;
   events: ChatableXEvents;
   storage: ChatableXStorage;
   tool: ChatableXToolModule;
+  platform: ChatableXPlatform;
+  auth: ChatableXAuth;
 }
 
 // ---------------------------------------------------------------------------

package/src/modules/skills.ts

@@ -1,14 +0,0 @@
-import type { Bridge } from '../bridge';
-import type { Skill, SkillResult, ChatableXSkills } from '../types';
-
-export function createSkillsModule(bridge: Bridge): ChatableXSkills {
-  return {
-    list(): Promise<Skill[]> {
-      return bridge.sendMessage('skills.list', {}) as Promise<Skill[]>;
-    },
-
-    execute(skillId: string, variables: Record<string, unknown>): Promise<SkillResult> {
-      return bridge.sendMessage('skills.execute', { skillId, variables }) as Promise<SkillResult>;
-    },
-  };
-}