chatablex-web-sdk 1.0.3 → 1.0.32

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/cloud.ts

@@ -0,0 +1,297 @@
+import type { Bridge } from '../bridge';
+import type {
+  ChatableXAuth,
+  ChatableXCloud,
+  CloudFileInfo,
+  CloudListOptions,
+  CloudUploadData,
+  CloudUploadOptions,
+  CloudUploadResult,
+  CloudUsage,
+} from '../types';
+
+// ---------------------------------------------------------------------------
+// Errors (instanceof-checkable so apps can branch their UI)
+// ---------------------------------------------------------------------------
+
+/** Base error for all `sdk.cloud` failures. */
+export class CloudError extends Error {
+  /** Business code from auth-fc (or the HTTP status when none was returned). */
+  readonly code: number;
+  constructor(message: string, code: number) {
+    super(message);
+    this.name = 'CloudError';
+    this.code = code;
+  }
+}
+
+/**
+ * Thrown when no authenticated session is available. The app should prompt the
+ * user to log in to ChatableX before retrying.
+ */
+export class CloudAuthRequiredError extends CloudError {
+  constructor(message = 'cloud storage requires an authenticated session') {
+    super(message, 401);
+    this.name = 'CloudAuthRequiredError';
+  }
+}
+
+/**
+ * Thrown when the user lacks the entitlement (purchased tool / membership)
+ * required to write to cloud storage. Maps to auth-fc code `40302`.
+ */
+export class CloudSubscriptionRequiredError extends CloudError {
+  constructor(message = 'cloud storage requires an active subscription') {
+    super(message, 40302);
+    this.name = 'CloudSubscriptionRequiredError';
+  }
+}
+
+/** Thrown when the upload would exceed the user's storage quota (code `40301`). */
+export class CloudQuotaExceededError extends CloudError {
+  readonly usedBytes: number;
+  readonly quotaBytes: number;
+  constructor(usedBytes: number, quotaBytes: number, message = 'storage quota exceeded') {
+    super(message, 40301);
+    this.name = 'CloudQuotaExceededError';
+    this.usedBytes = usedBytes;
+    this.quotaBytes = quotaBytes;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+const DEFAULT_CONTENT_TYPE = 'application/octet-stream';
+
+/** auth-fc response envelope: { success, code, message, data }. */
+interface ApiEnvelope<T> {
+  success?: boolean;
+  code?: number;
+  message?: string;
+  data?: T;
+}
+
+interface UploadURLData {
+  upload_url: string;
+  object_key: string;
+  expires_in: number;
+}
+interface DownloadURLData {
+  download_url: string;
+  object_key: string;
+  expires_in: number;
+}
+interface ListFilesData {
+  files: Array<{ file_key: string; size: number; last_modified: string }>;
+  total: number;
+}
+interface UsageData {
+  used_bytes: number;
+  quota_bytes: number;
+  file_count: number;
+  reconciled_at?: string;
+}
+interface QuotaErrorData {
+  used_bytes?: number;
+  quota_bytes?: number;
+}
+
+function normalizeData(data: CloudUploadData): { body: BodyInit; size: number; type: string } {
+  if (typeof Blob !== 'undefined' && data instanceof Blob) {
+    return { body: data, size: data.size, type: data.type || '' };
+  }
+  if (typeof data === 'string') {
+    const blob = new Blob([data]);
+    return { body: blob, size: blob.size, type: '' };
+  }
+  if (data instanceof ArrayBuffer) {
+    return { body: data, size: data.byteLength, type: '' };
+  }
+  if (ArrayBuffer.isView(data)) {
+    return { body: data as unknown as BodyInit, size: data.byteLength, type: '' };
+  }
+  throw new CloudError('unsupported upload data type', 400);
+}
+
+export interface CloudModuleDeps {
+  appId: string;
+  auth: ChatableXAuth;
+  /** Explicit cloud API base URL (overrides the host-provided one). */
+  apiBaseUrl?: string;
+}
+
+export function createCloudModule(bridge: Bridge, deps: CloudModuleDeps): ChatableXCloud {
+  const { appId, auth } = deps;
+  let resolvedBase: string | null = deps.apiBaseUrl ? stripTrailingSlash(deps.apiBaseUrl) : null;
+
+  function stripTrailingSlash(url: string): string {
+    return url.replace(/\/+$/, '');
+  }
+
+  /** Resolve the cloud API base URL: explicit config > host bridge > error. */
+  async function baseUrl(): Promise<string> {
+    if (resolvedBase) return resolvedBase;
+    try {
+      // Short timeout: a hosted-but-unimplemented method shouldn't hang the call.
+      const r = await bridge.sendMessage('host.getApiBaseUrl', {}, 5_000);
+      const url =
+        typeof r === 'string'
+          ? r
+          : r && typeof r === 'object' && typeof (r as { base_url?: unknown }).base_url === 'string'
+            ? (r as { base_url: string }).base_url
+            : '';
+      if (url) {
+        resolvedBase = stripTrailingSlash(url);
+        return resolvedBase;
+      }
+    } catch {
+      // host doesn't implement it / not hosted — fall through to error
+    }
+    throw new CloudError(
+      'cloud API base URL is not configured; pass apiBaseUrl to ChatableX.init()',
+      0,
+    );
+  }
+
+  /**
+   * fetch against auth-fc that injects the host login session and retries once
+   * on 401 after letting `sdk.auth` refresh. Rejects with CloudAuthRequiredError
+   * when there is no valid token (no unauthenticated request is sent).
+   */
+  async function authedFetch(path: string, init: RequestInit): Promise<Response> {
+    const token = await auth.getToken();
+    if (!token) throw new CloudAuthRequiredError();
+
+    const base = await baseUrl();
+    const url = `${base}${path}`;
+
+    const build = async (): Promise<RequestInit> => ({
+      ...init,
+      headers: { ...(init.headers ?? {}), ...(await auth.getAuthHeaders()) },
+    });
+
+    let res = await fetch(url, await build());
+    if (res.status === 401 && (await auth.refresh())) {
+      res = await fetch(url, await build());
+    }
+    return res;
+  }
+
+  /** Call an auth-fc JSON endpoint and unwrap the `data` payload. */
+  async function callApi<T>(path: string, init: RequestInit): Promise<T> {
+    const res = await authedFetch(path, init);
+
+    let body: ApiEnvelope<unknown> | null = null;
+    try {
+      body = (await res.json()) as ApiEnvelope<unknown>;
+    } catch {
+      // non-JSON body
+    }
+
+    const code = body?.code;
+    const message = body?.message || `HTTP ${res.status}`;
+
+    if (!res.ok || body?.success === false) {
+      if (code === 40301) {
+        const q = (body?.data ?? {}) as QuotaErrorData;
+        throw new CloudQuotaExceededError(q.used_bytes ?? 0, q.quota_bytes ?? 0, message);
+      }
+      if (code === 40302) throw new CloudSubscriptionRequiredError(message);
+      if (res.status === 401) throw new CloudAuthRequiredError(message);
+      throw new CloudError(message, code ?? res.status);
+    }
+
+    return (body?.data ?? null) as T;
+  }
+
+  function validateFileKey(fileKey: string): void {
+    if (!fileKey || typeof fileKey !== 'string') {
+      throw new CloudError('fileKey is required', 400);
+    }
+  }
+
+  return {
+    async upload(
+      fileKey: string,
+      data: CloudUploadData,
+      options: CloudUploadOptions = {},
+    ): Promise<CloudUploadResult> {
+      validateFileKey(fileKey);
+      const { body, size, type } = normalizeData(data);
+      const contentType = options.contentType || type || DEFAULT_CONTENT_TYPE;
+
+      const signed = await callApi<UploadURLData>('/api/storage/upload-url', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          app_id: appId,
+          file_key: fileKey,
+          content_type: contentType,
+          size_bytes: size,
+        }),
+      });
+
+      // Direct client → OSS PUT. Content-Type MUST match what was signed.
+      const put = await fetch(signed.upload_url, {
+        method: 'PUT',
+        headers: { 'Content-Type': contentType },
+        body,
+      });
+      if (!put.ok) {
+        throw new CloudError(`OSS upload failed: HTTP ${put.status}`, put.status);
+      }
+
+      return { fileKey, objectKey: signed.object_key, size, contentType };
+    },
+
+    async getDownloadUrl(fileKey: string): Promise<string> {
+      validateFileKey(fileKey);
+      const signed = await callApi<DownloadURLData>('/api/storage/download-url', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ app_id: appId, file_key: fileKey }),
+      });
+      return signed.download_url;
+    },
+
+    async download(fileKey: string): Promise<Blob> {
+      const url = await this.getDownloadUrl(fileKey);
+      const res = await fetch(url, { method: 'GET' });
+      if (!res.ok) {
+        throw new CloudError(`OSS download failed: HTTP ${res.status}`, res.status);
+      }
+      return res.blob();
+    },
+
+    async list(options: CloudListOptions = {}): Promise<CloudFileInfo[]> {
+      const qs = new URLSearchParams({ app_id: appId });
+      if (options.prefix) qs.set('prefix', options.prefix);
+      const data = await callApi<ListFilesData>(`/api/storage/files?${qs.toString()}`, {
+        method: 'GET',
+      });
+      return (data?.files ?? []).map((f) => ({
+        fileKey: f.file_key,
+        size: f.size,
+        lastModified: f.last_modified,
+      }));
+    },
+
+    async delete(fileKey: string): Promise<void> {
+      validateFileKey(fileKey);
+      const qs = new URLSearchParams({ app_id: appId, file_key: fileKey });
+      await callApi<unknown>(`/api/storage/files?${qs.toString()}`, { method: 'DELETE' });
+    },
+
+    async usage(): Promise<CloudUsage> {
+      const data = await callApi<UsageData>('/api/storage/usage', { method: 'GET' });
+      return {
+        usedBytes: data.used_bytes,
+        quotaBytes: data.quota_bytes,
+        fileCount: data.file_count,
+        reconciledAt: data.reconciled_at,
+      };
+    },
+  };
+}

package/src/types.ts

@@ -161,6 +161,14 @@ export interface ChatableXInitConfig {
   debug?: boolean;
   /** Timeout in ms for the handshake with Flutter (default: 10000) */
   timeout?: number;
+  /**
+   * Base URL of the ChatableX cloud API (auth-fc), e.g.
+   * `https://chatabl-fc-prod-xxxx.cn-hangzhou.fcapp.run`. Required for
+   * `sdk.cloud` to work. When omitted, the SDK best-effort asks the host via
+   * the `host.getApiBaseUrl` bridge call; if that is also unavailable, cloud
+   * calls reject with a clear error.
+   */
+  apiBaseUrl?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -210,6 +218,120 @@ export interface ChatableXPlatform {
   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>;
+}
+
+// ---------------------------------------------------------------------------
+// Cloud Storage
+// ---------------------------------------------------------------------------
+
+/** Binary payload accepted by `sdk.cloud.upload`. */
+export type CloudUploadData = Blob | ArrayBuffer | ArrayBufferView | string;
+
+export interface CloudUploadOptions {
+  /**
+   * MIME type to store the object as. Defaults to the `Blob.type` when a Blob
+   * is given, otherwise `application/octet-stream`. Must be one allowed by the
+   * server's content-type whitelist.
+   */
+  contentType?: string;
+}
+
+/** Result of a successful `sdk.cloud.upload`. */
+export interface CloudUploadResult {
+  /** App-relative key (the same `fileKey` passed to `upload`). */
+  fileKey: string;
+  /** Fully-qualified OSS object key (`user-data/{user_id}/{app_id}/{fileKey}`). */
+  objectKey: string;
+  /** Bytes uploaded. */
+  size: number;
+  /** MIME type the object was stored as. */
+  contentType: string;
+}
+
+/** A single file in the user's cloud storage for this app. */
+export interface CloudFileInfo {
+  fileKey: string;
+  size: number;
+  /** ISO-8601 timestamp. */
+  lastModified: string;
+}
+
+export interface CloudListOptions {
+  /** Restrict the listing to keys under this app-relative prefix. */
+  prefix?: string;
+}
+
+/** The user's storage usage / quota for the whole account. */
+export interface CloudUsage {
+  usedBytes: number;
+  quotaBytes: number;
+  fileCount: number;
+  /** ISO-8601 timestamp of the last server-side reconciliation, if any. */
+  reconciledAt?: string;
+}
+
+/**
+ * Cloud storage for WebUI apps. Backed by auth-fc presigned OSS URLs; the
+ * app's `appId` (from `ChatableX.init`) is injected automatically so every key
+ * is namespaced to `{user}/{app}` and apps cannot reach into each other's data.
+ *
+ * Requires an authenticated session (`sdk.auth`) and a configured cloud API
+ * base URL (see `ChatableXInitConfig.apiBaseUrl`).
+ */
+export interface ChatableXCloud {
+  /** Upload (overwrite) a file. Resolves once the bytes are stored in OSS. */
+  upload(fileKey: string, data: CloudUploadData, options?: CloudUploadOptions): Promise<CloudUploadResult>;
+  /** Download a file's bytes as a Blob. */
+  download(fileKey: string): Promise<Blob>;
+  /** Get a short-lived presigned GET URL (e.g. to feed an `<img src>`). */
+  getDownloadUrl(fileKey: string): Promise<string>;
+  /** List the current app's files for this user. */
+  list(options?: CloudListOptions): Promise<CloudFileInfo[]>;
+  /** Delete a file. Resolves even if the object did not exist. */
+  delete(fileKey: string): Promise<void>;
+  /** Read the account's storage usage / quota. */
+  usage(): Promise<CloudUsage>;
+}
+
 export interface ChatableXSDK {
   ai: ChatableXAI;
   tools: ChatableXTools;
@@ -218,6 +340,8 @@ export interface ChatableXSDK {
   storage: ChatableXStorage;
   tool: ChatableXToolModule;
   platform: ChatableXPlatform;
+  auth: ChatableXAuth;
+  cloud: ChatableXCloud;
 }
 
 // ---------------------------------------------------------------------------