@proveanything/smartlinks 2.0.55 → 2.0.57

package/dist/api/integrations.d.ts

@@ -1,4 +1,4 @@
-import type { IntegrationFlow, CreateFlowInput, UpdateFlowInput, ListFlowsQuery, FlowList, RunFlowInput, RunFlowResult, RunFlowSummary, RunFlowEnqueued, RecordTypesResponse, FlowRun, ListRunsQuery, RunList, ListRunItemsQuery, RunItemList, LoggingWindow, SetLoggingInput } from "../types/integrations.js";
+import type { IntegrationFlow, CreateFlowInput, UpdateFlowInput, ListFlowsQuery, FlowList, RunFlowInput, RunFlowResult, RunFlowSummary, RunFlowEnqueued, RecordTypesResponse, FlowRun, ListRunsQuery, RunList, ListRunItemsQuery, RunItemList, LoggingWindow, SetLoggingInput, InstalledConnector, SaveConnectorInstallationInput, ConnectorConsoleStep } from "../types/integrations.js";
 export declare namespace integrations {
     /** List flows in a collection. GET /integrations/flows */
     function listFlows(collectionId: string, query?: ListFlowsQuery): Promise<FlowList>;
@@ -57,4 +57,24 @@ export declare namespace integrations {
     function cancelLogging(collectionId: string, connectionId: string): Promise<{
         canceled: boolean;
     }>;
+    /** The collection's installed connector apps. GET /integrations/connectors */
+    function listConnectors(collectionId: string): Promise<{
+        connectors: InstalledConnector[];
+    }>;
+    /** Save a connector's non-secret Connect-form values and/or settings. PUT /integrations/connectors/:appId/installation */
+    function saveConnectorInstallation(collectionId: string, appId: string, input: SaveConnectorInstallationInput): Promise<{
+        installation: {
+            connection: Record<string, unknown>;
+            settings: Record<string, unknown>;
+        };
+    }>;
+    /**
+     * Run a connector step from the console: `testConnection` → ConnectorTestResult, `describeTarget` →
+     * ConnectorTargetSchema, `sample` → ConnectorRecords, `transform` (a dry run) → ConnectorTransformResult.
+     * The server adds the installation; pass `flowId` to layer that flow's settings.
+     * POST /integrations/connectors/:appId/steps/:step
+     */
+    function runConnectorStep<T = unknown>(collectionId: string, appId: string, step: ConnectorConsoleStep, input?: Record<string, unknown> & {
+        flowId?: string;
+    }): Promise<T>;
 }

package/dist/api/integrations.js

@@ -135,4 +135,29 @@ export var integrations;
         return del(`/admin/collection/${enc(collectionId)}/integrations/logging/${enc(connectionId)}`);
     }
     integrations.cancelLogging = cancelLogging;
+    // --- Connectors (docs/connectors.md) ------------------------------------
+    // Connector apps installed on the collection: their declared contract, the installation's
+    // non-secret settings, and which secrets are set. Secrets themselves go through
+    // `secrets.put(collectionId, name, value, { appId })` for the connector's appId.
+    const connectorsBase = (collectionId) => `/admin/collection/${enc(collectionId)}/integrations/connectors`;
+    /** The collection's installed connector apps. GET /integrations/connectors */
+    async function listConnectors(collectionId) {
+        return request(connectorsBase(collectionId));
+    }
+    integrations.listConnectors = listConnectors;
+    /** Save a connector's non-secret Connect-form values and/or settings. PUT /integrations/connectors/:appId/installation */
+    async function saveConnectorInstallation(collectionId, appId, input) {
+        return put(`${connectorsBase(collectionId)}/${enc(appId)}/installation`, input);
+    }
+    integrations.saveConnectorInstallation = saveConnectorInstallation;
+    /**
+     * Run a connector step from the console: `testConnection` → ConnectorTestResult, `describeTarget` →
+     * ConnectorTargetSchema, `sample` → ConnectorRecords, `transform` (a dry run) → ConnectorTransformResult.
+     * The server adds the installation; pass `flowId` to layer that flow's settings.
+     * POST /integrations/connectors/:appId/steps/:step
+     */
+    async function runConnectorStep(collectionId, appId, step, input = {}) {
+        return post(`${connectorsBase(collectionId)}/${enc(appId)}/steps/${enc(step)}`, input);
+    }
+    integrations.runConnectorStep = runConnectorStep;
 })(integrations || (integrations = {}));

package/dist/api/realtime.d.ts

@@ -1,103 +1,46 @@
-import type { AblyTokenRequest, RealtimeTokenRequest } from "../types/realtime.js";
+import type { AblyTokenRequest, RealtimeTokenRequest, RealtimeChangeEvent, RealtimeChangeFilter, RealtimeMessage, RealtimeScope } from "../types/realtime.js";
 /**
- * Real-Time Communications API
+ * One of your app's declared channels (manifest `realtime.channels`).
  *
- * Provides access to real-time communication channels using Ably.
- * Supports both public (user-scoped) and admin tokens for different permission levels.
- *
- * Channel Patterns:
- * - With appId: collection:{collectionId}:app:{appId}:*
- * - Without appId: collection:{collectionId}:*
- *
- * @example
  * ```ts
- * import { realtime } from '@proveanything/smartlinks'
- *
- * // Get token for public user
- * const tokenRequest = await realtime.getPublicToken({
- *   collectionId: 'abc123',
- *   appId: 'xyz789'
- * })
- *
- * // Initialize Ably client
- * const ably = new Ably.Realtime.Promise({
- *   authCallback: async (data, callback) => {
- *     callback(null, tokenRequest)
- *   }
- * })
- *
- * // Subscribe to a channel
- * const channel = ably.channels.get('collection:abc123:app:xyz789:chat:room-1')
- * await channel.subscribe((message) => {
- *   console.log('Received:', message.data)
- * })
- *
- * // Publish a message
- * await channel.publish('message', { text: 'Hello!', userId: '123' })
+ * const draw = realtime.channel({ collectionId, appId }, "draw")
+ * const off = draw.subscribe("status", (m) => setStatus(m.data))
+ * await draw.publish("status", { phase: "spinning" }) // if the channel lets this viewer publish
  * ```
  */
+export declare function channel(scope: RealtimeScope & {
+    appId: string;
+}, name: string): {
+    /** Listen for an event (or "*" for every event). Returns a function that stops listening. */
+    subscribe(event: string, onMessage: (msg: RealtimeMessage) => void): () => void;
+    /** Send a message. Refused (403) unless the channel's `publish` rule allows this viewer. */
+    publish(event: string, data?: unknown): Promise<{
+        ok: true;
+    }>;
+};
 /**
- * Get an Ably token for public (user-scoped) real-time communication.
+ * Something changed: refetch it. IDs only — never data.
  *
- * This endpoint returns an Ably TokenRequest that can be used to initialize an Ably client
- * with appropriate permissions for the specified collection and optional app.
+ * Admins of the collection see every change; everyone else sees changes to public things (public app
+ * records, products). Filter by `type` ('product' | 'proof' | 'asset' | 'record' | 'collection' |
+ * 'collection.apps' | 'settings'), `id`, `appId`, `recordType`, `productId`, `proofId`.
  *
- * Requires user authentication (Bearer token).
- *
- * @param params - Token request parameters
- * @param params.collectionId - The collection scope (required)
- * @param params.appId - Optional app scope for more specific permissions
- * @returns Ably TokenRequest that can be used with Ably.Realtime client
- *
- * @example
  * ```ts
- * const tokenRequest = await realtime.getPublicToken({
- *   collectionId: 'my-collection-id',
- *   appId: 'my-app-id'
- * })
- *
- * // Use with Ably
- * const ably = new Ably.Realtime.Promise({
- *   authCallback: async (data, callback) => {
- *     callback(null, tokenRequest)
- *   }
- * })
- *
- * // Subscribe to channels matching the pattern
- * const channel = ably.channels.get('collection:my-collection-id:app:my-app-id:chat:general')
- * await channel.subscribe('message', (msg) => console.log(msg.data))
+ * const off = realtime.onChange({ collectionId }, { type: "record", appId, recordType: "entry" }, () => refetch())
  * ```
  */
+export declare function onChange(scope: RealtimeScope, filter: RealtimeChangeFilter, onChangeFn: (change: RealtimeChangeEvent) => void): () => void;
+/**
+ * Messages for the signed-in person only (e.g. "scan" — a tag they just scanned on another device).
+ */
+export declare function onMine(scope: RealtimeScope, onMessage: (msg: RealtimeMessage) => void): () => void;
+/**
+ * @deprecated Use `realtime.channel()` / `realtime.onChange()`. Returns a raw Ably TokenRequest for
+ * `collection:{collectionId}:*` (subscribe; publish only for the collection's admins).
+ */
 export declare function getPublicToken(params: RealtimeTokenRequest): Promise<AblyTokenRequest>;
 /**
- * Get an Ably token for admin real-time communication.
- *
- * This endpoint returns an Ably TokenRequest that can be used to initialize an Ably client
- * with admin permissions to receive system notifications and alerts.
- *
- * Admin users get subscribe-only (read-only) access to the interaction:{userId} channel pattern.
- *
- * Requires admin authentication (Bearer token).
- *
- * @returns Ably TokenRequest that can be used with Ably.Realtime client
- *
- * @example
- * ```ts
- * const tokenRequest = await realtime.getAdminToken()
- *
- * // Use with Ably
- * const ably = new Ably.Realtime.Promise({
- *   authCallback: async (data, callback) => {
- *     callback(null, tokenRequest)
- *   }
- * })
- *
- * // Subscribe to admin interaction channel
- * const userId = 'my-user-id'
- * const channel = ably.channels.get(`interaction:${userId}`)
- * await channel.subscribe((message) => {
- *   console.log('Admin notification:', message.data)
- * })
- * ```
+ * @deprecated Use `realtime.onMine()`. Returns a raw Ably TokenRequest for `interaction:{userId}`
+ * (subscribe only).
  */
 export declare function getAdminToken(): Promise<AblyTokenRequest>;

package/dist/api/realtime.js

@@ -1,113 +1,259 @@
 // src/api/realtime.ts
-import { request } from "../http.js";
+import { request, post } from "../http.js";
+/** One live stream per (collection, app): every listener on this page shares it. */
+class Stream {
+    constructor(collectionId, appId, onEmpty) {
+        this.collectionId = collectionId;
+        this.appId = appId;
+        this.onEmpty = onEmpty;
+        this.listeners = new Map(); // logical name ("draw", "feed:admin") → listeners
+        this.physical = new Map(); // physical channel → logical name
+        this.granted = new Set();
+        this.source = null;
+        this.lastEvent = null;
+        this.refreshTimer = null;
+        this.retryTimer = null;
+        this.pending = null;
+        this.retries = 0;
+        this.closed = false;
+    }
+    add(name, listener) {
+        let set = this.listeners.get(name);
+        const isNew = !set;
+        if (!set)
+            this.listeners.set(name, (set = new Set()));
+        set.add(listener);
+        if (isNew || !this.source)
+            this.schedule();
+        return () => {
+            const s = this.listeners.get(name);
+            if (!s)
+                return;
+            s.delete(listener);
+            if (!s.size)
+                this.listeners.delete(name);
+            if (!this.listeners.size)
+                this.close();
+        };
+    }
+    /** What was granted (empty until connected). */
+    has(name) {
+        return this.granted.has(name);
+    }
+    schedule(delay = 30) {
+        if (this.pending)
+            clearTimeout(this.pending);
+        this.pending = setTimeout(() => {
+            this.pending = null;
+            void this.open();
+        }, delay);
+    }
+    async open() {
+        var _a;
+        if (this.closed || typeof EventSource === "undefined")
+            return;
+        const names = [...this.listeners.keys()];
+        const feeds = names.filter((n) => n.startsWith("feed:")).map((n) => n.slice(5));
+        const channels = names.filter((n) => !n.startsWith("feed:"));
+        let reply;
+        try {
+            reply = await post("/public/realtime/connect", Object.assign(Object.assign({ collectionId: this.collectionId }, (this.appId ? { appId: this.appId } : {})), { feeds,
+                channels }));
+        }
+        catch (err) {
+            return this.retryLater(err);
+        }
+        if (this.closed)
+            return;
+        (_a = this.source) === null || _a === void 0 ? void 0 : _a.close();
+        this.source = null;
+        this.physical.clear();
+        this.granted = new Set(reply.channels.map((c) => c.name));
+        for (const c of reply.channels)
+            this.physical.set(c.channel, c.name);
+        if (reply.transport !== "sse" || !reply.url)
+            return; // nothing this viewer may see
+        const url = this.lastEvent ? `${reply.url}&lastEvent=${encodeURIComponent(this.lastEvent)}` : reply.url;
+        const source = new EventSource(url);
+        this.source = source;
+        source.addEventListener("message", (e) => this.deliver(e));
+        source.addEventListener("error", (e) => {
+            const data = e.data;
+            // A stream error with a body (e.g. the token expired): get a fresh token and resume.
+            if (data || source.readyState === EventSource.CLOSED)
+                this.retryLater(data);
+        });
+        source.addEventListener("open", () => {
+            this.retries = 0;
+        });
+        // Renew a minute before the token expires (the stream can't renew its own token).
+        if (this.refreshTimer)
+            clearTimeout(this.refreshTimer);
+        if (reply.expiresAt) {
+            const ms = Math.max(10000, reply.expiresAt - Date.now() - 60000);
+            this.refreshTimer = setTimeout(() => this.schedule(0), ms);
+        }
+    }
+    retryLater(_why) {
+        var _a;
+        if (this.closed)
+            return;
+        (_a = this.source) === null || _a === void 0 ? void 0 : _a.close();
+        this.source = null;
+        if (this.retryTimer)
+            clearTimeout(this.retryTimer);
+        const ms = Math.min(30000, 1000 * 2 ** this.retries++);
+        this.retryTimer = setTimeout(() => this.schedule(0), ms);
+    }
+    deliver(e) {
+        var _a, _b;
+        if (e.lastEventId)
+            this.lastEvent = e.lastEventId;
+        let env;
+        try {
+            env = JSON.parse(String(e.data));
+        }
+        catch (_c) {
+            return;
+        }
+        const name = env.channel ? this.physical.get(env.channel) : undefined;
+        if (!name)
+            return;
+        let data = env.data;
+        if (typeof data === "string" && env.encoding && /json/.test(env.encoding)) {
+            try {
+                data = JSON.parse(data);
+            }
+            catch (_d) {
+                /* leave as the string */
+            }
+        }
+        const msg = { channel: name, event: (_a = env.name) !== null && _a !== void 0 ? _a : "", data, at: env.timestamp };
+        for (const l of [...((_b = this.listeners.get(name)) !== null && _b !== void 0 ? _b : [])]) {
+            try {
+                l(msg);
+            }
+            catch (err) {
+                console.error("[SmartLinks realtime] a listener threw", err);
+            }
+        }
+    }
+    close() {
+        var _a;
+        this.closed = true;
+        for (const t of [this.pending, this.refreshTimer, this.retryTimer])
+            if (t)
+                clearTimeout(t);
+        (_a = this.source) === null || _a === void 0 ? void 0 : _a.close();
+        this.source = null;
+        this.onEmpty();
+    }
+}
+const streams = new Map();
+function streamFor(scope) {
+    var _a, _b;
+    if (!(scope === null || scope === void 0 ? void 0 : scope.collectionId))
+        throw new Error("realtime: collectionId is required");
+    const key = `${scope.collectionId}|${(_a = scope.appId) !== null && _a !== void 0 ? _a : ""}`;
+    let s = streams.get(key);
+    if (!s) {
+        s = new Stream(scope.collectionId, (_b = scope.appId) !== null && _b !== void 0 ? _b : null, () => streams.delete(key));
+        streams.set(key, s);
+    }
+    return s;
+}
 /**
- * Real-Time Communications API
- *
- * Provides access to real-time communication channels using Ably.
- * Supports both public (user-scoped) and admin tokens for different permission levels.
- *
- * Channel Patterns:
- * - With appId: collection:{collectionId}:app:{appId}:*
- * - Without appId: collection:{collectionId}:*
+ * One of your app's declared channels (manifest `realtime.channels`).
  *
- * @example
  * ```ts
- * import { realtime } from '@proveanything/smartlinks'
- *
- * // Get token for public user
- * const tokenRequest = await realtime.getPublicToken({
- *   collectionId: 'abc123',
- *   appId: 'xyz789'
- * })
- *
- * // Initialize Ably client
- * const ably = new Ably.Realtime.Promise({
- *   authCallback: async (data, callback) => {
- *     callback(null, tokenRequest)
- *   }
- * })
- *
- * // Subscribe to a channel
- * const channel = ably.channels.get('collection:abc123:app:xyz789:chat:room-1')
- * await channel.subscribe((message) => {
- *   console.log('Received:', message.data)
- * })
- *
- * // Publish a message
- * await channel.publish('message', { text: 'Hello!', userId: '123' })
+ * const draw = realtime.channel({ collectionId, appId }, "draw")
+ * const off = draw.subscribe("status", (m) => setStatus(m.data))
+ * await draw.publish("status", { phase: "spinning" }) // if the channel lets this viewer publish
  * ```
  */
+export function channel(scope, name) {
+    return {
+        /** Listen for an event (or "*" for every event). Returns a function that stops listening. */
+        subscribe(event, onMessage) {
+            return streamFor(scope).add(name, (m) => {
+                if (event === "*" || m.event === event)
+                    onMessage(m);
+            });
+        },
+        /** Send a message. Refused (403) unless the channel's `publish` rule allows this viewer. */
+        publish(event, data) {
+            return post("/public/realtime/publish", {
+                collectionId: scope.collectionId,
+                appId: scope.appId,
+                channel: name,
+                event,
+                data: data === undefined ? null : data,
+            });
+        },
+    };
+}
+function matches(change, filter) {
+    for (const k of ["type", "id", "appId", "recordType", "productId", "proofId"]) {
+        if (filter[k] !== undefined && change[k] !== filter[k])
+            return false;
+    }
+    return true;
+}
 /**
- * Get an Ably token for public (user-scoped) real-time communication.
+ * Something changed: refetch it. IDs only — never data.
  *
- * This endpoint returns an Ably TokenRequest that can be used to initialize an Ably client
- * with appropriate permissions for the specified collection and optional app.
+ * Admins of the collection see every change; everyone else sees changes to public things (public app
+ * records, products). Filter by `type` ('product' | 'proof' | 'asset' | 'record' | 'collection' |
+ * 'collection.apps' | 'settings'), `id`, `appId`, `recordType`, `productId`, `proofId`.
  *
- * Requires user authentication (Bearer token).
- *
- * @param params - Token request parameters
- * @param params.collectionId - The collection scope (required)
- * @param params.appId - Optional app scope for more specific permissions
- * @returns Ably TokenRequest that can be used with Ably.Realtime client
- *
- * @example
  * ```ts
- * const tokenRequest = await realtime.getPublicToken({
- *   collectionId: 'my-collection-id',
- *   appId: 'my-app-id'
- * })
- *
- * // Use with Ably
- * const ably = new Ably.Realtime.Promise({
- *   authCallback: async (data, callback) => {
- *     callback(null, tokenRequest)
- *   }
- * })
- *
- * // Subscribe to channels matching the pattern
- * const channel = ably.channels.get('collection:my-collection-id:app:my-app-id:chat:general')
- * await channel.subscribe('message', (msg) => console.log(msg.data))
+ * const off = realtime.onChange({ collectionId }, { type: "record", appId, recordType: "entry" }, () => refetch())
  * ```
  */
+export function onChange(scope, filter, onChangeFn) {
+    const s = streamFor({ collectionId: scope.collectionId });
+    // Ask for both feeds; an admin is granted both (public changes reach the admin feed too), so the
+    // public feed is ignored once the admin feed is granted — no change arrives twice.
+    const handle = (fromAdminFeed) => (m) => {
+        if (m.event !== "change" || !m.data || typeof m.data !== "object")
+            return;
+        if (!fromAdminFeed && s.has("feed:admin"))
+            return;
+        const change = m.data;
+        if (matches(change, filter))
+            onChangeFn(change);
+    };
+    const offAdmin = s.add("feed:admin", handle(true));
+    const offPublic = s.add("feed:public", handle(false));
+    return () => {
+        offAdmin();
+        offPublic();
+    };
+}
+/**
+ * Messages for the signed-in person only (e.g. "scan" — a tag they just scanned on another device).
+ */
+export function onMine(scope, onMessage) {
+    return streamFor({ collectionId: scope.collectionId }).add("feed:me", onMessage);
+}
+// ---------------------------------------------------------------------------------------------------
+// Legacy (raw Ably tokens). New code uses channel / onChange above — no provider in your app.
+// ---------------------------------------------------------------------------------------------------
+/**
+ * @deprecated Use `realtime.channel()` / `realtime.onChange()`. Returns a raw Ably TokenRequest for
+ * `collection:{collectionId}:*` (subscribe; publish only for the collection's admins).
+ */
 export async function getPublicToken(params) {
     const queryParams = new URLSearchParams();
-    queryParams.append('collectionId', params.collectionId);
-    if (params.appId) {
-        queryParams.append('appId', params.appId);
-    }
+    queryParams.append("collectionId", params.collectionId);
+    if (params.appId)
+        queryParams.append("appId", params.appId);
     return request(`/public/push/token?${queryParams.toString()}`);
 }
 /**
- * Get an Ably token for admin real-time communication.
- *
- * This endpoint returns an Ably TokenRequest that can be used to initialize an Ably client
- * with admin permissions to receive system notifications and alerts.
- *
- * Admin users get subscribe-only (read-only) access to the interaction:{userId} channel pattern.
- *
- * Requires admin authentication (Bearer token).
- *
- * @returns Ably TokenRequest that can be used with Ably.Realtime client
- *
- * @example
- * ```ts
- * const tokenRequest = await realtime.getAdminToken()
- *
- * // Use with Ably
- * const ably = new Ably.Realtime.Promise({
- *   authCallback: async (data, callback) => {
- *     callback(null, tokenRequest)
- *   }
- * })
- *
- * // Subscribe to admin interaction channel
- * const userId = 'my-user-id'
- * const channel = ably.channels.get(`interaction:${userId}`)
- * await channel.subscribe((message) => {
- *   console.log('Admin notification:', message.data)
- * })
- * ```
+ * @deprecated Use `realtime.onMine()`. Returns a raw Ably TokenRequest for `interaction:{userId}`
+ * (subscribe only).
  */
 export async function getAdminToken() {
-    return request('/admin/auth/push');
+    return request("/admin/auth/push");
 }