@goflowstate/widget-sdk 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,182 @@
+/** The visual lifecycle state of a widget on the canvas. */
+export type WidgetDisplayState = 'collapsed' | 'expanding' | 'expanded' | 'collapsing';
+/** Authenticated user information passed to the widget by the canvas host. */
+export interface UserContext {
+    /** The user's unique identifier. */
+    id: string;
+    /** The user's display name, or null if not set. */
+    displayName: string | null;
+}
+/** The result of a consent request for a named data scope. */
+export interface ConsentResult {
+    /** The scope that was requested. */
+    scope: string;
+    /** Whether the user granted or denied consent. */
+    granted: boolean;
+    /** Opaque token the widget can pass to the API to prove consent was granted. */
+    grantToken?: string;
+    /** Seconds until the grant token expires. */
+    expiresIn?: number;
+}
+export interface DbRecord<T = Record<string, unknown>> {
+    id: string;
+    data: T;
+    ownerUserId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface DbListOptions {
+    limit?: number;
+    cursor?: string;
+    sort?: 'createdAt:asc' | 'createdAt:desc';
+    mine?: boolean;
+}
+export interface DbCollection {
+    create(data: Record<string, unknown>): Promise<DbRecord>;
+    get(id: string): Promise<DbRecord>;
+    list(opts?: DbListOptions): Promise<DbRecord[]>;
+    update(id: string, patch: Record<string, unknown>): Promise<DbRecord>;
+    delete(id: string): Promise<void>;
+}
+export interface DbAPI {
+    collection(name: string): DbCollection;
+}
+/** Persistent key-value storage API scoped to this widget installation. */
+export interface StorageAPI {
+    /** Retrieve a value by key; resolves with undefined if the key does not exist. */
+    get(key: string): Promise<unknown>;
+    /** Store a value under the given key. */
+    set(key: string, value: unknown): Promise<void>;
+    /** Remove a key from storage. */
+    delete(key: string): Promise<void>;
+}
+/** Widget settings API — reads and writes the configuration persisted by the canvas host. */
+export interface SettingsAPI {
+    /** Returns a shallow copy of the current settings object. */
+    get(): Record<string, unknown>;
+    /** Merges new values into the current settings and persists them via the canvas host. */
+    set(settings: Record<string, unknown>): void;
+    /**
+     * Subscribe to settings changes made on another of the user's devices.
+     * The handler receives the full new settings object. Returns an unsubscribe function.
+     */
+    onRemoteChange(cb: (settings: Record<string, unknown>) => void): () => void;
+}
+/** The public interface of an initialized SDK instance returned by {@link CanvasWidget.init}. */
+export interface CanvasWidgetSDK {
+    /** The unique identifier for this widget instance on the canvas. */
+    readonly widgetId: string;
+    /** The current display state of the widget. */
+    readonly state: WidgetDisplayState;
+    /** Subscribe to display state changes; returns an unsubscribe function. */
+    onStateChange(cb: (state: WidgetDisplayState) => void): () => void;
+    /** Ask the canvas host to expand this widget into its modal view. */
+    requestExpand(): void;
+    /** Ask the canvas host to collapse this widget back to its tile view. */
+    requestCollapse(): void;
+    /** Broadcast an event on the given topic to all subscribed widgets on the canvas. */
+    emit(topic: string, payload: unknown): void;
+    /** Subscribe to events on the given topic; returns an unsubscribe function. */
+    subscribe(topic: string, cb: (event: WidgetEvent) => void): () => void;
+    /** Send a structured log entry to the canvas host for centralized debugging. */
+    log(level: 'info' | 'warn' | 'error', message: string, data?: unknown): void;
+    /** The authenticated user context, or null when user data access has not been granted. */
+    readonly user: UserContext | null;
+    /** Request user consent for a named data scope; resolves with the consent decision. */
+    requestConsent(scope: string, reason: string): Promise<ConsentResult>;
+    /** Return the cached JWT for authenticating requests to external APIs. Pass forceRefresh=true to bypass the cache. */
+    getJwt(forceRefresh?: boolean): Promise<string>;
+    /** Persistent key-value storage scoped to this widget installation. */
+    storage: StorageAPI;
+    /** Ad-hoc collections/records backend scoped to the canvas/room. */
+    db: DbAPI;
+    /** Widget configuration settings persisted by the canvas host. */
+    settings: SettingsAPI;
+    /** Display a toast notification in the canvas host UI. */
+    notify(message: string, opts?: {
+        level?: string;
+        duration?: number;
+    }): Promise<void>;
+    /** Authenticated HTTP client scoped to this widget's declared service URL. Present only when manifest.service.url is set. */
+    service?: WidgetServiceClient;
+}
+/** An event received from another widget or the canvas host via the event bus. */
+export interface WidgetEvent {
+    /** The topic this event was emitted on. */
+    topic: string;
+    /** Arbitrary event payload. */
+    payload: unknown;
+    /** Unix timestamp (ms) when the event was emitted. */
+    emittedAt: number;
+}
+/** Initialization payload delivered by the canvas host in the INIT message. */
+export interface InitPayload {
+    widgetId: string;
+    installationId: string;
+    state: WidgetDisplayState;
+    hmacSecret: string | null;
+    widgetApiUrl: string | null;
+    /** Short-lived access token for authenticated widget-api requests */
+    widgetApiToken?: string | null;
+    /** Base URL for the widget's declared service (from manifest.service.url). Null when not declared. */
+    serviceUrl: string | null;
+    user: UserContext | null;
+    settings: Record<string, unknown> | null;
+}
+/** Payload delivered when the widget's display state changes. */
+export interface StateChangePayload {
+    state: WidgetDisplayState;
+    previousState: WidgetDisplayState;
+}
+/** Payload delivered when a cross-widget event is broadcast on a subscribed topic. */
+export interface EventBroadcastPayload {
+    topic: string;
+    payload: unknown;
+    emittedAt: number;
+}
+/** Payload delivered in response to a consent request. */
+export interface ConsentResultPayload {
+    scope: string;
+    granted: boolean;
+    grantToken?: string;
+    expiresIn?: number;
+}
+export interface WidgetManifestDisplay {
+    expandPreset?: 'collapsed-only' | 'all' | 'portable' | 'immersive';
+    allowedModes?: Array<'right' | 'left' | 'bottom' | 'float' | 'fullscreen'>;
+    defaultMode?: 'right' | 'left' | 'bottom' | 'float' | 'fullscreen';
+    defaultSize?: {
+        width: number;
+        height: number;
+    };
+    minSize?: {
+        width: number;
+        height: number;
+    };
+    maxSize?: {
+        width: number;
+        height: number;
+    };
+}
+export interface WidgetManifestServiceScope {
+    name: string;
+    reason: string;
+}
+export interface WidgetManifestServiceBlock {
+    url: string;
+    jwksOverride?: string | null;
+    scopes: WidgetManifestServiceScope[];
+    events?: {
+        in?: string[];
+        out?: string[];
+    };
+    rateLimit?: {
+        perSecond?: number;
+        perMinute?: number;
+    };
+}
+export interface WidgetServiceClient {
+    /** Joins `path` against `manifest.service.url`, attaches Bearer JWT, returns parsed JSON. */
+    fetch<T = unknown>(path: string, init?: RequestInit): Promise<T>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@goflowstate/widget-sdk",
+  "version": "0.1.0",
+  "description": "SDK for building Flowstate Canvas widgets",
+  "type": "module",
+  "main": "./dist/canvas-widget-sdk.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/canvas-widget-sdk.js"
+    }
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "node build.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "esbuild": "^0.24.0",
+    "jsdom": "^28.1.0",
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/starteryllp/goflowstate-sdk.git"
+  },
+  "license": "MIT"
+}