js-bao-wss-client 2.0.4 → 2.0.5

package/dist/JsBaoClient.js

@@ -15,7 +15,7 @@ import { HttpClient, } from "./internal/httpClient";
 import { DocumentManager, } from "./internal/documentManager";
 import { ensureArrayBuffer, toBase64, fromBase64, decompressGzip, } from "./utils/binary";
 import { hashUint8Array } from "./utils/crypto";
-import { JsBaoError } from "./errors";
+import { JsBaoError, JsBaoApiError, JsBaoNetworkError } from "./errors";
 import { DocumentsAPI, } from "./api/documentsApi";
 import { createCacheFacade } from "./api/cacheFacade";
 import { MeAPI } from "./api/meApi";
@@ -26,6 +26,7 @@ import { UsersAPI } from "./api/usersApi";
 import { DatabasesAPI } from "./api/databasesApi";
 import { GroupsAPI } from "./api/groupsApi";
 import { CronTriggersAPI } from "./api/cronTriggersApi";
+import { ResourceMetadataAPI } from "./api/resourceMetadataApi";
 import { RuleSetsAPI } from "./api/ruleSetsApi";
 import { BlobBucketsAPI } from "./api/blobBucketsApi";
 import { GroupTypeConfigsAPI } from "./api/groupTypeConfigsApi";
@@ -33,7 +34,8 @@ import { CollectionTypeConfigsAPI } from "./api/collectionTypeConfigsApi";
 import { DatabaseTypeConfigsAPI } from "./api/databaseTypeConfigsApi";
 import { CollectionsAPI } from "./api/collectionsApi";
 import { InvitationsAPI } from "./api/invitationsApi";
-export { JsBaoError, isJsBaoError } from "./errors";
+import { NotificationsAPI } from "./api/notificationsApi";
+export { JsBaoError, isJsBaoError, JsBaoApiError, isJsBaoApiError, JsBaoNetworkError, isJsBaoNetworkError, } from "./errors";
 export { AuthError, AUTH_CODES } from "./internal/authController";
 export { ANALYTICS_UNAUTHENTICATED_USER } from "./internal/analyticsQueue";
 const DEFAULT_RETURN_ACTIVE_MIN_MS = 5 * 60 * 1000;
@@ -481,6 +483,7 @@ export class JsBaoClient extends Observable {
         this.auth = new AuthController({
             appId: this.appId,
             apiUrl: this.apiUrl,
+            globalAdminAppId: this.globalAdminAppId,
             logger,
             offlineStore: this.offlineStore,
             request: (method, path, data) => this.makeRequest(method, path, data),
@@ -590,14 +593,20 @@ export class JsBaoClient extends Observable {
         this.collectionTypeConfigs = new CollectionTypeConfigsAPI(this);
         this.databaseTypeConfigs = new DatabaseTypeConfigsAPI(this);
         this.cronTriggers = new CronTriggersAPI(this);
+        this.resourceMetadata = new ResourceMetadataAPI(this);
         this.invitations = new InvitationsAPI(this);
+        this.notifications = new NotificationsAPI(this);
         this.integrations = {
             call: async (request) => this.callIntegration(request),
         };
         this.workflows = {
+            // The public overloads type `input` generically (Omit base input + I);
+            // the private impls read `input` as an opaque payload, so widen back to
+            // the concrete option types here. Runtime just forwards `input`.
             start: (options) => this.startWorkflow(options),
             runSync: (options) => this.runSyncWorkflow(options),
             getStatus: (options) => this.getWorkflowStatus(options),
+            waitFor: (runId, options) => this.waitForWorkflow(runId, options),
             terminate: (options) => this.terminateWorkflow(options),
             listRuns: (options) => this.listWorkflowRuns(options),
             listStepRuns: (options) => this.listWorkflowStepRuns(options),
@@ -2078,10 +2087,32 @@ export class JsBaoClient extends Observable {
             Authorization: `Bearer ${this.token || ""}`,
             "X-Global-Admin-App-Id": this.getGlobalAdminAppId(),
         };
-        const res = await fetch(url.toString(), { method, headers });
+        let res;
+        try {
+            res = await fetch(url.toString(), { method, headers });
+        }
+        catch (err) {
+            throw new JsBaoNetworkError(`Network request to ${url.toString()} failed`, err);
+        }
         if (!res.ok) {
             const text = await res.text().catch(() => "");
-            throw new Error(`HTTP ${res.status}: ${text}`);
+            let body = text === "" ? null : text;
+            let code;
+            if (text) {
+                try {
+                    const parsed = JSON.parse(text);
+                    body = parsed;
+                    if (parsed &&
+                        typeof parsed === "object" &&
+                        typeof parsed.code === "string") {
+                        code = parsed.code;
+                    }
+                }
+                catch {
+                    // non-JSON body — keep the raw text
+                }
+            }
+            throw new JsBaoApiError(res.status, text, body, code);
         }
         return res.arrayBuffer();
     }
@@ -2285,6 +2316,15 @@ export class JsBaoClient extends Observable {
             path += `?contextDocId=${encodeURIComponent(options.contextDocId)}`;
         }
         const response = await this.makeRequest("GET", path);
+        return this.normalizeWorkflowStatusResponse(response);
+    }
+    /**
+     * Normalize a raw `{ status: rawStatus, run }` status response into a
+     * {@link WorkflowStatusResult}. Shared by `getStatus` (workflowKey/runKey
+     * route) and `waitFor`'s reconcile fetch (runId route) so both surfaces map
+     * the Cloudflare status spellings and apply-flow states identically.
+     */
+    normalizeWorkflowStatusResponse(response) {
         // The API returns { status: rawStatus, run } where rawStatus is the Cloudflare workflow status object
         // and run is the WorkflowRun DB record (which tracks apply-flow states).
         const rawStatus = response?.status;
@@ -2317,6 +2357,191 @@ export class JsBaoClient extends Observable {
             run,
         };
     }
+    /**
+     * Fetch normalized run status keyed by `runId` via the #1443 endpoint
+     * (`GET /workflows/runs/:runId/status`). Used by `waitFor`'s reconcile
+     * fetch. A 404 surfaces as a `NOT_FOUND` {@link JsBaoError} (unknown or
+     * not-owned run).
+     */
+    async getWorkflowStatusByRunId(runId) {
+        const path = `/workflows/runs/${encodeURIComponent(runId)}/status`;
+        const response = await this.makeRequest("GET", path);
+        return this.normalizeWorkflowStatusResponse(response);
+    }
+    /**
+     * Implementation of {@link WorkflowsAPI.waitFor} (#1443). See the interface
+     * doc for the contract. Cleanup mirrors `createUserIdWaiter` in
+     * authController — a guarded `cleanup()` that clears the timer and removes
+     * every listener, run on every exit path.
+     */
+    async waitForWorkflow(runId, options) {
+        if (!runId || typeof runId !== "string") {
+            throw new JsBaoError("INVALID_ARGUMENT", "runId is required for workflows.waitFor");
+        }
+        const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes
+        const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        return new Promise((resolve, reject) => {
+            let cleaned = false;
+            let timer = null;
+            // Guards overlapping reconcile fetches (initial + reconnect) so a slow
+            // fetch can't stack up behind a burst of reconnect events.
+            let reconciling = false;
+            const cleanup = () => {
+                if (cleaned)
+                    return;
+                cleaned = true;
+                try {
+                    if (timer) {
+                        clearTimeout(timer);
+                        timer = null;
+                    }
+                }
+                catch { }
+                try {
+                    this.off("workflowStatus", onWorkflowStatus);
+                }
+                catch { }
+                try {
+                    this.off("status", onConnectionStatus);
+                }
+                catch { }
+            };
+            const settle = (result) => {
+                cleanup();
+                resolve(result);
+            };
+            const fail = (err) => {
+                cleanup();
+                reject(err);
+            };
+            // Map a reconcile response into a terminal result, or null if the run is
+            // not yet terminal. A run is terminal when its status is a terminal
+            // value, OR its `endedAt` is set regardless of status (#1388 robustness).
+            const terminalFromReconcile = (res) => {
+                const run = res.run;
+                const isTerminalStatus = res.status === "completed" ||
+                    res.status === "failed" ||
+                    res.status === "terminated" ||
+                    res.status === "apply_pending" ||
+                    res.status === "apply_claimed";
+                const endedAtSet = !!(run && run.endedAt);
+                if (!isTerminalStatus && !endedAtSet)
+                    return null;
+                return {
+                    status: this.toTerminalWaitStatus(res.status, run),
+                    output: res.output,
+                    error: res.error,
+                };
+            };
+            const onWorkflowStatus = (event) => {
+                if (!event || event.runId !== runId)
+                    return;
+                // The workflowStatus frame is only emitted on a terminal transition
+                // (completed/failed/terminated), and carries the terminal payload
+                // directly — resolve from the event with ZERO extra HTTP.
+                //
+                // Apply-required workflows are the one wrinkle: the server broadcasts
+                // status:"completed" with needsApply:true while the run row is actually
+                // `apply_pending`. Map that frame to the apply-ready terminal status so
+                // the event path agrees with the reconcile path (behavior 11) and
+                // callers don't miss that a client-side apply step is still required.
+                const status = event.needsApply
+                    ? "apply_pending"
+                    : event.status;
+                settle({
+                    status,
+                    output: event.output,
+                    error: event.error,
+                });
+            };
+            // Recognise a "run not found" (HTTP 404) from either error shape the
+            // status endpoint can throw: a structured JsBaoError NOT_FOUND, a plain
+            // Error whose message starts with "HTTP 404" (the real transport), or an
+            // error object carrying a numeric `status` of 404.
+            const isNotFound = (err) => {
+                if (err instanceof JsBaoError && err.code === "NOT_FOUND")
+                    return true;
+                if (err && typeof err === "object" && err.status === 404) {
+                    return true;
+                }
+                const msg = String((err && err.message) || err || "");
+                return msg.startsWith("HTTP 404");
+            };
+            const reconcile = () => {
+                if (cleaned || reconciling)
+                    return;
+                reconciling = true;
+                this.getWorkflowStatusByRunId(runId)
+                    .then((res) => {
+                    if (cleaned)
+                        return;
+                    const terminal = terminalFromReconcile(res);
+                    if (terminal)
+                        settle(terminal);
+                })
+                    .catch((err) => {
+                    if (cleaned)
+                        return;
+                    // A 404 means the run is unknown or not readable by this caller —
+                    // reject immediately rather than waiting for the timeout. The
+                    // status endpoint surfaces a 404 in two shapes: a JsBaoError with
+                    // code NOT_FOUND (from higher-level paths / the transport spy), or
+                    // a plain Error("HTTP 404: ...") thrown by the real
+                    // HttpClient.request transport. Recognise both so the real 404
+                    // rejects promptly instead of falling through as "transient".
+                    if (isNotFound(err)) {
+                        fail(err instanceof JsBaoError
+                            ? err
+                            : new JsBaoError("NOT_FOUND", `Workflow run ${runId} not found`));
+                        return;
+                    }
+                    // Other (transient / network) errors: swallow and rely on the
+                    // workflowStatus event, the next reconnect reconcile, or timeout.
+                })
+                    .finally(() => {
+                    reconciling = false;
+                });
+            };
+            const onConnectionStatus = (evt) => {
+                // Fork 1 = B: on WS reconnect, re-run the single reconcile fetch to
+                // recover a terminal frame missed during the outage. No interval timer.
+                if (evt?.status === "connected") {
+                    reconcile();
+                }
+            };
+            this.on("workflowStatus", onWorkflowStatus);
+            this.on("status", onConnectionStatus);
+            // 0 / Infinity disables the timeout (documented warning): the listener
+            // lives until the run terminates.
+            if (timeoutMs > 0 && Number.isFinite(timeoutMs)) {
+                timer = setTimeout(() => {
+                    fail(new JsBaoError("WORKFLOW_WAIT_TIMEOUT", `workflows.waitFor timed out after ${timeoutMs}ms waiting for run ${runId}`));
+                }, timeoutMs);
+            }
+            // Always reconcile once at start (Fork 4 = A) to close the
+            // started-before-subscribed race — the terminal frame may have fired
+            // before this listener was attached and is never replayed.
+            reconcile();
+        });
+    }
+    /**
+     * Collapse a normalized {@link WorkflowStatusValue} into the narrower
+     * {@link WaitForWorkflowStatus} for `waitFor`. Terminal statuses pass
+     * through unchanged. A `"running"` status only reaches here when `endedAt`
+     * is set (#1388): derive the real terminal state from the run row's error
+     * (failed if an error message is present, otherwise completed).
+     */
+    toTerminalWaitStatus(status, run) {
+        if (status === "completed" ||
+            status === "failed" ||
+            status === "terminated" ||
+            status === "apply_pending" ||
+            status === "apply_claimed") {
+            return status;
+        }
+        // status === "running" but endedAt is set (#1388 stale status).
+        return run && run.errorMessage ? "failed" : "completed";
+    }
     async terminateWorkflow(options) {
         const { workflowKey, runKey, contextDocId } = options;
         if (!workflowKey || typeof workflowKey !== "string") {
@@ -4370,6 +4595,9 @@ export class JsBaoClient extends Observable {
             else if (data.type === "invitation") {
                 this.handleInvitationMessage(data);
             }
+            else if (data.type === "notification") {
+                this.handleNotificationMessage(data);
+            }
             else if (data.type === "workflowStatus") {
                 this.handleWorkflowStatusMessage(data);
             }
@@ -4608,6 +4836,14 @@ export class JsBaoClient extends Observable {
             logger.debug("[invitation] client emit failed", { error: err });
         }
     }
+    handleNotificationMessage(data) {
+        try {
+            this.emit("notification", [data]);
+        }
+        catch (err) {
+            logger.debug("[notification] client emit failed", { error: err });
+        }
+    }
     handleWorkflowStatusMessage(data) {
         try {
             this.emit("workflowStatus", [data]);