@littlebigbrain/client 0.5.2 → 0.6.1

package/dist/transport.d.ts

@@ -3,8 +3,10 @@ export interface CallOptions {
     idempotencyKey?: string;
     /** Override the client's per-attempt timeout. Set 0 to disable it. */
     timeoutMs?: number;
-    /** Override the client's retry count for this request. */
+    /** Override the client's retry count (secondary cap) for this request. */
     maxRetries?: number;
+    /** Override the client's deadline-based retry budget (ms) for this request. */
+    retryBudgetMs?: number;
     /** Override retry safety classification. Read-only POST namespaces set this automatically. */
     retry?: boolean;
     /** Abort the request and suppress any further retries. */
@@ -32,6 +34,8 @@ export declare class LbbError extends Error {
     readonly docUrl?: string | null;
     readonly retryable?: boolean;
     readonly retryAfterSeconds?: number;
+    /** Actionable guidance for composite stack-endpoint routing errors. */
+    readonly endpointHint?: string;
     constructor(status: number, body: string, error?: LbbErrorPayload | undefined);
 }
 export type QueryValue = string | number | boolean | undefined;
@@ -41,6 +45,34 @@ export declare function retryableStatus(status: number): boolean;
 export declare function retryAllowed(method: string, idempotencyKey?: string): boolean;
 /** Parse a Retry-After delta-seconds or HTTP-date value, capped at one minute. */
 export declare function parseRetryAfterMs(value: string | null | undefined, nowMs?: number): number | undefined;
-export declare function retryDelayForAttempt(baseDelayMs: number, attempt: number, retryAfter?: string | null): number;
+/**
+ * Full-jitter exponential backoff: `uniform(0, base * 2**attempt)`, capped at
+ * one minute. Replaces linear backoff so many clients recovering from one
+ * outage do not retry in lockstep (a thundering herd that re-triggers it).
+ */
+export declare function fullJitterBackoffMs(baseDelayMs: number, attempt: number, rng?: () => number): number;
+/**
+ * The server's own body hint `error.retry_after_seconds` in ms (capped), or
+ * `undefined` when the body is naked (a bare LB 5xx) or carries no hint. Used
+ * as the backoff when the `Retry-After` *header* is absent.
+ */
+export declare function retryAfterFromBodyMs(body: string): number | undefined;
+/** The parsed `error.code` from an error body, or `undefined` when absent/naked. */
+export declare function errorCodeFromBody(body: string): string | undefined;
+/**
+ * True iff the server explicitly marked this error non-retryable in the body
+ * (`error.retryable === false`) — a durable rejection (e.g. an exhausted quota)
+ * the client must surface immediately instead of spending its retry budget.
+ */
+export declare function bodyMarksTerminal(body: string): boolean;
+/**
+ * The backoff (ms) before the next attempt: the `Retry-After` header, else the
+ * server's body `retry_after_seconds` hint, else full-jitter exponential
+ * backoff.
+ */
+export declare function retryDelayMs(baseDelayMs: number, attempt: number, opts?: {
+    retryAfterHeader?: string | null;
+    body?: string;
+}, rng?: () => number): number;
 export declare function parseResponseJson<T>(text: string, status: number, requestId?: string): T;
 export declare function parseLbbError(status: number, body: string, fallbackRequestId?: string): LbbError;

package/dist/transport.js

@@ -10,6 +10,8 @@ export class LbbError extends Error {
     docUrl;
     retryable;
     retryAfterSeconds;
+    /** Actionable guidance for composite stack-endpoint routing errors. */
+    endpointHint;
     constructor(status, body, error) {
         super(error?.message ?? `Little Big Brain ${status}: ${body}`);
         this.status = status;
@@ -23,8 +25,18 @@ export class LbbError extends Error {
         this.docUrl = error?.doc_url;
         this.retryable = error?.retryable;
         this.retryAfterSeconds = error?.retry_after_seconds;
+        this.endpointHint = endpointMigrationHint(this.code);
     }
 }
+function endpointMigrationHint(code) {
+    if (code === "stack_endpoint_required") {
+        return "Copy endpoint_url from the stack's Connect page and use it as baseUrl.";
+    }
+    if (code === "stack_endpoint_mismatch") {
+        return "Use the endpoint_url and API key from the same stack.";
+    }
+    return undefined;
+}
 export function sleep(ms) {
     if (ms <= 0)
         return Promise.resolve();
@@ -62,9 +74,73 @@ export function parseRetryAfterMs(value, nowMs = Date.now()) {
         return undefined;
     return Math.min(Math.max(0, dateMs - nowMs), MAX_RETRY_AFTER_MS);
 }
-export function retryDelayForAttempt(baseDelayMs, attempt, retryAfter) {
-    const fallback = Math.max(0, baseDelayMs) * (attempt + 1);
-    return parseRetryAfterMs(retryAfter) ?? fallback;
+/**
+ * Full-jitter exponential backoff: `uniform(0, base * 2**attempt)`, capped at
+ * one minute. Replaces linear backoff so many clients recovering from one
+ * outage do not retry in lockstep (a thundering herd that re-triggers it).
+ */
+export function fullJitterBackoffMs(baseDelayMs, attempt, rng = Math.random) {
+    const ceiling = Math.min(Math.max(0, baseDelayMs) * 2 ** attempt, MAX_RETRY_AFTER_MS);
+    return rng() * ceiling;
+}
+/**
+ * The server's own body hint `error.retry_after_seconds` in ms (capped), or
+ * `undefined` when the body is naked (a bare LB 5xx) or carries no hint. Used
+ * as the backoff when the `Retry-After` *header* is absent.
+ */
+export function retryAfterFromBodyMs(body) {
+    try {
+        const parsed = JSON.parse(body);
+        const seconds = parsed.error?.retry_after_seconds;
+        if (typeof seconds === "number" &&
+            Number.isFinite(seconds) &&
+            seconds >= 0) {
+            return Math.min(seconds * 1_000, MAX_RETRY_AFTER_MS);
+        }
+    }
+    catch {
+        // Naked LB body (no error envelope) — no hint.
+    }
+    return undefined;
+}
+/** The parsed `error.code` from an error body, or `undefined` when absent/naked. */
+export function errorCodeFromBody(body) {
+    try {
+        const parsed = JSON.parse(body);
+        const code = parsed.error?.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * True iff the server explicitly marked this error non-retryable in the body
+ * (`error.retryable === false`) — a durable rejection (e.g. an exhausted quota)
+ * the client must surface immediately instead of spending its retry budget.
+ */
+export function bodyMarksTerminal(body) {
+    try {
+        const parsed = JSON.parse(body);
+        return parsed.error?.retryable === false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The backoff (ms) before the next attempt: the `Retry-After` header, else the
+ * server's body `retry_after_seconds` hint, else full-jitter exponential
+ * backoff.
+ */
+export function retryDelayMs(baseDelayMs, attempt, opts = {}, rng = Math.random) {
+    const header = parseRetryAfterMs(opts.retryAfterHeader);
+    if (header !== undefined)
+        return header;
+    const bodyHint = opts.body !== undefined ? retryAfterFromBodyMs(opts.body) : undefined;
+    if (bodyHint !== undefined)
+        return bodyHint;
+    return fullJitterBackoffMs(baseDelayMs, attempt, rng);
 }
 export function parseResponseJson(text, status, requestId) {
     try {

package/dist/types.d.ts

@@ -153,7 +153,7 @@ export declare function parseSparqlResults(response: Schemas["SparqlTextResponse
 export declare function firstPatternVariable(patterns: Schemas["AnalyticTriplePattern"][]): string;
 export declare function attributeFilter(filter: AttributeFilter, defaultVar: string): Schemas["SparqlFilter"];
 export interface LbbClientOptions {
-    /** Base URL of the little big brain server, e.g. `https://db.eu.littlebigbrain.com`. */
+    /** Hosted stack endpoint, e.g. `https://7k3m9q2x--production.db.eu.littlebigbrain.com`. */
     baseUrl: string;
     /** Stack API key (`lbb_sk_test_…` / `lbb_sk_live_…`) or single-mode token. */
     apiKey?: string;
@@ -171,16 +171,27 @@ export interface LbbClientOptions {
     fetch?: FetchLike;
     /** API version header sent on every request. Defaults to the beta reset contract. */
     apiVersion?: string;
-    /** Retry count for 429/5xx responses and network failures. Defaults to 2. */
+    /**
+     * Secondary safety cap on retries for 429/5xx responses and network failures.
+     * The binding limit is `retryBudgetMs`. Defaults to 6.
+     */
     maxRetries?: number;
     /** Base delay between retries. Defaults to 100ms. Tests can set 0. */
     retryDelayMs?: number;
+    /**
+     * Deadline-based retry budget (ms): keep retrying a retryable request until
+     * this much wall-clock has elapsed, so a server's advertised `Retry-After`
+     * window is honored rather than truncated by `maxRetries`. Defaults to 60000.
+     */
+    retryBudgetMs?: number;
     /** Per-attempt timeout, including response-body reads. Defaults to 120 seconds; 0 disables it. */
     timeoutMs?: number;
     /** Called immediately before each network attempt. Bodies and credentials are never included. */
     onRequest?: (event: LbbRequestEvent) => void;
     /** Called once after the final HTTP response. Bodies and credentials are never included. */
     onResponse?: (event: LbbResponseEvent) => void;
+    /** Called before each backoff sleep, so absorbed retries are observable. Bodies and credentials are never included. */
+    onRetry?: (event: LbbRetryEvent) => void;
 }
 export interface LbbRequestEvent {
     method: string;
@@ -198,6 +209,20 @@ export interface LbbResponseEvent {
     retryCount: number;
     elapsedMs: number;
 }
+export interface LbbRetryEvent {
+    method: string;
+    url: string;
+    /** 1-based number of the attempt that just failed and triggered this retry. */
+    attempt: number;
+    /** HTTP status of the failed attempt, or `undefined` for a network error. */
+    status?: number;
+    /** Parsed `error.code` of the failed attempt, when the body carried one. */
+    errorCode?: string;
+    /** The backoff (ms) about to be slept — header, body hint, or jittered backoff. */
+    delayMs: number;
+    /** Inclusive wall-clock elapsed (ms) across attempts and waits so far. */
+    elapsedMs: number;
+}
 export type LbbStackActivityWindow = "1h" | "4h" | "12h" | "24h";
 export interface LbbStackActivityResponse {
     ok: true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/client",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "description": "TypeScript client for the little big brain graph + hybrid search HTTP API",
   "license": "Apache-2.0",
   "repository": {