js-bao-wss-client 2.0.6 → 2.0.8

package/dist/browser.umd.js

@@ -5689,10 +5689,22 @@
             return result.data;
         }
         async requestRaw(method, path, data, options) {
-            await this.refreshIfExpiring();
-            const response = await this.fetchWithRefresh(method, path, data, options);
+            // Establish the single apply-lifecycle deadline HERE, before the proactive
+            // `refreshIfExpiring()` preflight — not inside `fetchWithRefresh()`. The
+            // preflight can itself fire a token refresh (when the access token is
+            // within 120s of expiry), and a hung refresh endpoint at that point would
+            // otherwise hang the whole call before any timeout budget existed. Passing
+            // the deadline into both the preflight and `fetchWithRefresh` keeps the
+            // WHOLE call (proactive refresh + request + reactive refresh + retry)
+            // bounded by one `timeoutMs`. Non-apply callers omit `timeoutMs`, so
+            // `deadline` is undefined and every step stays untimed exactly as before.
+            const timeoutMs = options?.timeoutMs;
+            const deadline = typeof timeoutMs === "number" && timeoutMs > 0
+                ? Date.now() + timeoutMs
+                : undefined;
+            await this.refreshIfExpiring(deadline);
+            const { response, text } = await this.fetchWithRefresh(method, path, data, options, deadline, timeoutMs);
             const contentType = response.headers.get("content-type") || "";
-            const text = await response.text();
             let parsed = text;
             if (contentType.includes("application/json")) {
                 if (text) {
@@ -5715,21 +5727,40 @@
                 text,
             };
         }
-        async tryRefreshAccessToken() {
+        /**
+         * Refresh the access token via the refresh endpoint.
+         *
+         * `timeoutMs` bounds the refresh fetch with an `AbortController`, using the
+         * same timeout path as normal requests (`fetchOrThrow`). It is passed by the
+         * apply-lifecycle path so the whole call (original attempt + refresh + retry)
+         * stays within the caller's request budget — a hung refresh endpoint would
+         * otherwise bypass that budget and hang indefinitely. Omit it (the default)
+         * to leave the refresh untimed, which is how the background
+         * `refreshIfExpiring` and the public `refreshAccessToken` callers use it.
+         *
+         * On an aborted (timed-out) or otherwise failed refresh fetch this returns
+         * `"network"`, so callers surface a retryable `JsBaoNetworkError`.
+         */
+        async tryRefreshAccessToken(timeoutMs) {
             try {
                 const { url, headers } = this.buildRefreshRequestConfig();
-                const res = await fetch(url, {
+                const { response: res, text } = await this.fetchOrThrow(url, {
                     method: "POST",
                     credentials: "include",
                     headers,
-                });
+                }, timeoutMs);
                 if (res.status === 401) {
                     return "invalid";
                 }
                 if (!res.ok) {
                     return "network";
                 }
-                const data = await res.json();
+                // `fetchOrThrow` already read the body under the same abort timer, so a
+                // refresh response that stalled mid-body was aborted (surfacing as a
+                // rejected fetch → outer catch → "network") rather than hanging here.
+                // A malformed body throws from JSON.parse → outer catch → "network",
+                // matching the prior `res.json()` behavior.
+                const data = text ? JSON.parse(text) : null;
                 const newToken = data?.token;
                 if (!newToken)
                     return "invalid";
@@ -5740,14 +5771,36 @@
                 return "network";
             }
         }
-        async refreshIfExpiring() {
+        /**
+         * Proactively refresh the access token when it is within 120s of expiry.
+         *
+         * When the caller opted into an apply-lifecycle deadline, thread the
+         * REMAINING budget into the refresh fetch so a hung refresh endpoint at this
+         * preflight point is aborted within the same `timeoutMs` (rather than hanging
+         * before the request path's budget exists). This is best-effort: if the
+         * budget is already spent we simply skip the proactive refresh and let the
+         * request path surface the exhausted-budget network error. Untimed callers
+         * (deadline undefined) keep the original behavior — an unbounded proactive
+         * refresh.
+         */
+        async refreshIfExpiring(deadline) {
             try {
                 const token = this.config.getToken();
                 if (!token)
                     return;
                 const exp = this.getTokenExpiry(token);
                 if (exp && exp - Date.now() / 1000 < 120) {
-                    const outcome = await this.tryRefreshAccessToken();
+                    let budget;
+                    if (deadline !== undefined) {
+                        const remaining = deadline - Date.now();
+                        // No time left for a best-effort proactive refresh — skip it; the
+                        // request path's `remainingBudgetOrThrow` raises the retryable
+                        // exhausted-budget error.
+                        if (remaining <= 0)
+                            return;
+                        budget = remaining;
+                    }
+                    const outcome = await this.tryRefreshAccessToken(budget);
                     this.config.onRefreshOutcome(outcome);
                 }
             }
@@ -5869,16 +5922,40 @@
             }
             return { url: url.toString(), init };
         }
-        async fetchWithRefresh(method, path, data, options) {
+        /**
+         * Return the remaining apply-lifecycle budget for the next sub-step, or throw
+         * a retryable `JsBaoNetworkError` if the shared deadline is already spent.
+         * Threading the *remaining* time into each sub-step keeps every step
+         * (request, token refresh, retry) bounded by the caller's single `timeoutMs`.
+         * Non-timed requests (deadline undefined) return undefined — every step stays
+         * untimed exactly as before.
+         */
+        remainingBudgetOrThrow(deadline, timeoutMs, url) {
+            if (deadline === undefined)
+                return undefined;
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                throw new JsBaoNetworkError(`Network request to ${url} timed out: apply-lifecycle budget of ${timeoutMs}ms exhausted`);
+            }
+            return remaining;
+        }
+        async fetchWithRefresh(method, path, data, options, deadline, timeoutMs) {
+            // The whole apply-lifecycle call (original attempt + a possible token
+            // refresh + the retry after refresh) shares ONE budget via the absolute
+            // `deadline` established in `requestRaw`. `remainingBudgetOrThrow` throws a
+            // retryable network error if the budget is already spent, so we never start
+            // a sub-step (including the refresh) with no time left.
             let requestConfig = this.buildRequestInit(method, path, data, options);
             this.logger.debug(`Making ${method} request to ${requestConfig.url}`);
-            let response = await this.fetchOrThrow(requestConfig.url, requestConfig.init);
-            if (response.status === 401) {
-                const outcome = await this.tryRefreshAccessToken();
+            let result = await this.fetchOrThrow(requestConfig.url, requestConfig.init, this.remainingBudgetOrThrow(deadline, timeoutMs, requestConfig.url));
+            if (result.response.status === 401) {
+                // Bound the refresh with whatever time is left in the shared budget
+                // (throws if already exhausted, rather than starting an unbounded refresh).
+                const outcome = await this.tryRefreshAccessToken(this.remainingBudgetOrThrow(deadline, timeoutMs, requestConfig.url));
                 this.config.onRefreshOutcome(outcome);
                 if (outcome === "success") {
                     requestConfig = this.buildRequestInit(method, path, data, options);
-                    response = await this.fetchOrThrow(requestConfig.url, requestConfig.init);
+                    result = await this.fetchOrThrow(requestConfig.url, requestConfig.init, this.remainingBudgetOrThrow(deadline, timeoutMs, requestConfig.url));
                 }
                 else if (outcome === "invalid") {
                     throw new JsBaoApiError(401, "Invalid credentials");
@@ -5892,17 +5969,51 @@
                     throw new JsBaoNetworkError("Token refresh failed due to a network error");
                 }
             }
-            return response;
+            return result;
         }
-        async fetchOrThrow(url, init) {
+        /**
+         * Fetch `url`, then read the full response body — both under one
+         * `AbortController`/timeout. The timer is NOT cleared when `fetch()` resolves:
+         * a resolved `fetch` only means the response HEADERS arrived. A server that
+         * sends headers and then stalls the body would leave the body read
+         * (`response.text()`) hanging indefinitely, stranding an apply run even though
+         * the request "succeeded". Keeping the timer active through body consumption
+         * lets the timeout abort a stalled body read too; on timeout the aborted read
+         * rejects and we surface the same retryable `JsBaoNetworkError` as any other
+         * transport failure. The timer is cleared in `finally`, after the body is
+         * fully read (or the read/fetch rejects), so it never leaks.
+         */
+        async fetchOrThrow(url, init, timeoutMs) {
+            let controller;
+            let timer;
+            let fetchInit = init;
+            if (typeof timeoutMs === "number" &&
+                timeoutMs > 0 &&
+                typeof AbortController !== "undefined") {
+                controller = new AbortController();
+                fetchInit = { ...init, signal: controller.signal };
+                timer = setTimeout(() => controller.abort(), timeoutMs);
+            }
             try {
-                return await fetch(url, init);
+                const response = await fetch(url, fetchInit);
+                const text = await response.text();
+                return { response, text };
             }
             catch (err) {
-                // fetch itself rejected — the server was never reached (unreachable
-                // host, refused connection, DNS failure, abort). Surface a typed,
-                // retryable network error instead of the raw TypeError.
-                throw new JsBaoNetworkError(`Network request to ${url} failed`, err);
+                // fetch — OR the body read — rejected: the server was never reached
+                // (unreachable host, refused connection, DNS failure), or the request /
+                // body read outran its timeout and was aborted. Surface a typed,
+                // retryable network error instead of the raw TypeError/AbortError so
+                // callers can retry.
+                const timedOut = controller?.signal.aborted === true;
+                throw new JsBaoNetworkError(timedOut
+                    ? `Network request to ${url} timed out after ${timeoutMs}ms`
+                    : `Network request to ${url} failed`, err);
+            }
+            finally {
+                if (timer) {
+                    clearTimeout(timer);
+                }
             }
         }
     }
@@ -10590,6 +10701,18 @@
             }
             return this.client.makeRequest("PUT", `/documents/${documentId}/link-access`, { level });
         }
+        /**
+         * Read the current "anyone with the link" access state for a document.
+         * Authorized for any caller who can read the document OR manage its sharing
+         * (document owner, app owner, or read-write editor) — so an app owner can
+         * inspect the state even without a content grant. Returns
+         * `{ documentId, linkAccess: null }` when link access is off.
+         *
+         * @param documentId - The document to read link access for.
+         */
+        async getLinkAccess(documentId) {
+            return this.client.makeRequest("GET", `/documents/${documentId}/link-access`);
+        }
         /**
          * Turn off "anyone with the link" access for a document. Existing explicit
          * grants are unaffected; link-only viewers lose access.
@@ -11314,6 +11437,10 @@
         async setLinkAccess(level) {
             return this.docs.setLinkAccess(this.documentId, level);
         }
+        /** Read the current "anyone with the link" access state for this document. */
+        async getLinkAccess() {
+            return this.docs.getLinkAccess(this.documentId);
+        }
         /** Turn off "anyone with the link" access for this document. */
         async clearLinkAccess() {
             return this.docs.clearLinkAccess(this.documentId);
@@ -12384,6 +12511,11 @@
          * The returned payload includes the same dict under both `metadata` (legacy
          * wire name) and `celContext` (new user-facing name).
          *
+         * @deprecated Prefer resource metadata categories (issue #1420). The
+         * `metadataAccess` gate that controls this read uses one CEL expression to
+         * gate read AND update, so granting read also grants update. A metadata
+         * category has separate `readRule`/`writeRule`; read its values from CEL as
+         * `md.self.<category>.<key>`. See the migration recipe in `databases.md`.
          * @param databaseId - The unique identifier of the database to read
          */
         async getCelContext(databaseId) {
@@ -12396,6 +12528,12 @@
          * `database.celContext.<key>` (or legacy `database.metadata.<key>`) and
          * from filter JSON as `$database.celContext.<key>`.
          *
+         * @deprecated Prefer resource metadata categories (issue #1420). Writing here
+         * is gated by the same single `metadataAccess` expression that gates reads, so
+         * anyone allowed to read can also update. A metadata category has separate
+         * `readRule`/`writeRule`; write its values with `resourceMetadata` /
+         * `initialMetadata` and read them from CEL as `md.self.<category>.<key>`. See
+         * the migration recipe in `databases.md`.
          * @param databaseId - The unique identifier of the database to update
          * @param celContext - Key-value pairs to merge into the database's existing CEL context
          */
@@ -12404,7 +12542,11 @@
         }
         /**
          * Read a database's CEL context dict.
-         * @deprecated Use {@link getCelContext} instead.
+         * @deprecated Prefer resource metadata categories (issue #1420) — a category
+         * has separate `readRule`/`writeRule` (read no longer implies update) and is
+         * read from CEL as `md.self.<category>.<key>`. See the migration recipe in
+         * `databases.md`. This is the legacy wire-name alias of the (also-deprecated)
+         * {@link getCelContext}.
          * @param databaseId - The unique identifier of the database to read
          */
         async getMetadata(databaseId) {
@@ -12412,7 +12554,12 @@
         }
         /**
          * Update a database's CEL context dict (merge with existing).
-         * @deprecated Use {@link updateCelContext} instead.
+         * @deprecated Prefer resource metadata categories (issue #1420) — a category
+         * has separate `readRule`/`writeRule`, so a writer no longer inherits update
+         * from read access. Write category values with `resourceMetadata` /
+         * `initialMetadata` and read them from CEL as `md.self.<category>.<key>`. See
+         * the migration recipe in `databases.md`. This is the legacy wire-name alias
+         * of the (also-deprecated) {@link updateCelContext}.
          * @param databaseId - The unique identifier of the database to update
          * @param metadata - Key-value pairs to merge into the database's existing CEL context
          */
@@ -13541,7 +13688,14 @@
             return this.client.makeRequest("POST", "/invitations", params);
         }
         /**
-         * List app-level invitations (admin/owner only).
+         * List app-level invitations.
+         *
+         * Admins and owners see the full app list. Members see only the
+         * invitations they created themselves — the `memberInvitationsEnabled`
+         * flag gates *creating* invitations, not listing your own (a member can
+         * always see and revoke invitations they already sent). A member with no
+         * invitations of their own gets an empty list, not a 403.
+         *
          * @param options - Pagination options
          */
         async list(options) {
@@ -13555,8 +13709,13 @@
             return this.client.makeRequest("GET", path);
         }
         /**
-         * Delete an app-level invitation (admin/owner only).
-         * Also cascade-deletes any linked deferred grants.
+         * Delete (revoke) an app-level invitation.
+         *
+         * Admins and owners can revoke any invitation. A member can revoke only
+         * invitations they created themselves (403 otherwise). Revoking an active
+         * invitation frees the member's quota. Also cascade-deletes any linked
+         * deferred grants.
+         *
          * @param invitationId - The invitation to delete
          */
         async delete(invitationId) {
@@ -13687,6 +13846,24 @@
     const DEFAULT_RETURN_ACTIVE_MIN_MS = 5 * 60 * 1000;
     const DEFAULT_SYNC_ERROR_MIN_MS = 30 * 1000;
     const logger = createLogger({ scope: "JsBaoClient" });
+    // Workflow apply-lifecycle durability (#1694). The server confirm is idempotent
+    // (read-then-conditional-write; returns `confirmed: true` if the run already
+    // completed), so a lost or hung confirm POST is safe to retry — retrying only
+    // re-sends the confirm, never the user's onApply handler. These bounds keep the
+    // retry inside the server's 30s apply lease so a stranded run recovers within
+    // the same client session instead of waiting for a full restart.
+    //
+    // A per-request timeout (via AbortController in the HTTP layer) turns a hung
+    // apply POST into a retryable network error. Scope note: this timeout is applied
+    // only to the apply-lifecycle calls (claim/confirm/release), not to every client
+    // request — a blanket request timeout has a much larger blast radius.
+    const APPLY_REQUEST_TIMEOUT_MS = 8000;
+    const APPLY_CONFIRM_MAX_ATTEMPTS = 6;
+    const APPLY_CONFIRM_BASE_DELAY_MS = 250;
+    const APPLY_CONFIRM_MAX_DELAY_MS = 4000;
+    // Total retry budget, kept under the 30s server apply lease so the claim is
+    // still valid when a retry finally lands.
+    const APPLY_CONFIRM_RETRY_BUDGET_MS = 25000;
     function debugLog(tag, payload) {
         try {
             if (!logger.shouldLog("debug"))
@@ -16268,7 +16445,9 @@
             if (options.contextDocId) {
                 payload.contextDocId = options.contextDocId;
             }
-            const response = await this.makeRequest("POST", path, payload);
+            const response = await this.makeRequest("POST", path, payload, {
+                timeoutMs: APPLY_REQUEST_TIMEOUT_MS,
+            });
             return response;
         }
         async releaseWorkflowApply(options) {
@@ -16279,7 +16458,9 @@
             if (options.contextDocId) {
                 payload.contextDocId = options.contextDocId;
             }
-            const response = await this.makeRequest("POST", path, payload);
+            const response = await this.makeRequest("POST", path, payload, {
+                timeoutMs: APPLY_REQUEST_TIMEOUT_MS,
+            });
             return response;
         }
         async confirmWorkflowApply(options) {
@@ -16296,9 +16477,63 @@
             if (options.contextDocId) {
                 payload.contextDocId = options.contextDocId;
             }
-            const response = await this.makeRequest("POST", path, payload);
+            const response = await this.makeRequest("POST", path, payload, {
+                timeoutMs: APPLY_REQUEST_TIMEOUT_MS,
+            });
             return response;
         }
+        /**
+         * Whether a thrown confirm-apply error is worth retrying. Network failures
+         * (unreachable server, refused connection, DNS failure, or an aborted
+         * timeout — all surfaced as `JsBaoNetworkError`) and HTTP 5xx are transient,
+         * so retrying the idempotent confirm may still succeed. Any other HTTP status
+         * (4xx) is a definitive rejection and is not retried.
+         */
+        isRetryableConfirmError(err) {
+            if (err instanceof JsBaoNetworkError) {
+                return true;
+            }
+            if (err instanceof JsBaoApiError) {
+                return err.status >= 500 && err.status < 600;
+            }
+            return false;
+        }
+        /**
+         * Retry the confirm POST on transient failures, bounded by both an attempt
+         * count and a time budget that stays within the server's apply lease. Only
+         * the confirm POST is retried here — the caller runs the user's onApply
+         * handler exactly once, before invoking this, so retries never re-run it.
+         * A `confirmed: false` result (a genuine claim loss) is returned normally,
+         * not retried; the caller releases the claim in that case.
+         */
+        async confirmWorkflowApplyWithRetry(options) {
+            const deadline = Date.now() + APPLY_CONFIRM_RETRY_BUDGET_MS;
+            let attempt = 0;
+            let delayMs = APPLY_CONFIRM_BASE_DELAY_MS;
+            for (;;) {
+                attempt++;
+                try {
+                    return await this.confirmWorkflowApply(options);
+                }
+                catch (err) {
+                    const nextDelay = Math.min(delayMs, APPLY_CONFIRM_MAX_DELAY_MS);
+                    const outOfBudget = Date.now() + nextDelay >= deadline;
+                    if (!this.isRetryableConfirmError(err) ||
+                        attempt >= APPLY_CONFIRM_MAX_ATTEMPTS ||
+                        outOfBudget) {
+                        throw err;
+                    }
+                    logger.warn("[workflowApply] confirm failed, retrying", {
+                        workflowKey: options.workflowKey,
+                        runKey: options.runKey,
+                        attempt,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                    await new Promise((resolve) => setTimeout(resolve, nextDelay));
+                    delayMs = Math.min(delayMs * 2, APPLY_CONFIRM_MAX_DELAY_MS);
+                }
+            }
+        }
         async getWorkflowPendingApplies(options) {
             if (!options?.contextDocId) {
                 throw new JsBaoError("INVALID_ARGUMENT", "contextDocId is required for workflows.getPendingApplies");
@@ -16346,11 +16581,15 @@
                     startedByUserId: event.startedByUserId,
                     meta: statusResult.run?.meta ?? undefined,
                 });
-                // Confirm the apply. Surface a server-side rejection (`confirmed: false`)
-                // as an error so we don't silently leave the workflow stuck in
-                // `apply_claimed` (issue #614). The catch block below releases the
-                // claim and emits a diagnostic.
-                const confirmResult = await this.confirmWorkflowApply({
+                // Confirm the apply, retrying the POST on transient failures (#1694).
+                // The handler above has already run exactly once; the retry re-sends only
+                // the idempotent confirm, never the handler. A lost or hung confirm would
+                // otherwise strand the run in `apply_claimed` for the whole client session
+                // with no way to recover short of a restart. Surface a server-side
+                // rejection (`confirmed: false`) as an error so we don't silently leave
+                // the workflow stuck in `apply_claimed` (issue #614). The catch block
+                // below releases the claim and emits a diagnostic.
+                const confirmResult = await this.confirmWorkflowApplyWithRetry({
                     workflowKey: event.workflowKey,
                     runKey: event.runKey,
                     contextDocId: event.contextDocId,
@@ -16360,7 +16599,10 @@
                 }
             }
             catch (err) {
-                logger.warn("[workflowApply] apply handler failed", {
+                // Elevated to `error` (#1694): apply-flow failures strand a run in
+                // `apply_claimed`, and tests (and apps) commonly run at logLevel `error`,
+                // so a `warn`/`debug` diagnostic here is invisible exactly when it matters.
+                logger.error("[workflowApply] apply handler failed", {
                     workflowKey: event.workflowKey,
                     runKey: event.runKey,
                     error: err instanceof Error ? err.message : String(err),
@@ -16374,7 +16616,7 @@
                     });
                 }
                 catch (releaseErr) {
-                    logger.debug("[workflowApply] failed to release claim", {
+                    logger.error("[workflowApply] failed to release claim", {
                         workflowKey: event.workflowKey,
                         runKey: event.runKey,
                         error: releaseErr instanceof Error ? releaseErr.message : String(releaseErr),