@littlebigbrain/client 0.14.0 → 0.15.0

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import type { DurableImportSource, ImportLine, LbbClientOptions, ListResponse, RawLbbResponse, ReadConsistencyOptions, RdfImportDocument, RdfImportManyResult, RdfImportOptions, Schemas, SearchConsistency, SparqlResults } from "./types.js";
-import { type CallOptions, type RequestOptions } from "./transport.js";
+import { type RequestOptions } from "./transport.js";
 import { EntityNamespace, GraphNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace, EvalsNamespace, EmbeddingsNamespace } from "./namespaces.js";
 export { parseSparqlResults } from "./types.js";
 export type { AttributeFilter, AttributeFilterOp, AttributeFilterValue, EntityAttributeFilterOptions, EntityPropertiesLine, DurableImportLine, DurableImportSource, FetchLike, FlatProperties, ImportLine, LbbClientOptions, LbbRequestEvent, LbbResponseEvent, LbbRetryEvent, LbbErrorPayload, ListResponse, RawLbbResponse, ReadConsistencyOptions, RdfImportDocument, RdfImportManyResult, RdfImportOptions, Schemas, SearchConsistency, SparqlResults, SparqlResultsJson, SparqlTerm, CommitRequest, CommitResponse, Entity, EntitySelector, GraphMetadata, GraphSummary, SchemaView, Snapshot, } from "./types.js";
@@ -290,34 +290,6 @@ export declare class LbbClient {
     }): Promise<Schemas["SearchFeedbackResponse"]>;
     /** Export the stored relevance labels as qrels-style rows for training. */
     searchFeedbackExport(): Promise<Schemas["SearchFeedbackExportResponse"]>;
-    /**
-     * Ranked incoming/outgoing neighborhood for a graph entity.
-     *
-     * `edges` caps the edges returned per direction (default 1000, maximum
-     * 10000). When a cap cuts a direction the response carries a `truncation`
-     * block; an uncut response omits it entirely.
-     */
-    entityNeighborhood(opts: {
-        id?: string;
-        type?: string;
-        name?: string;
-        relations?: string[];
-        asOf?: string;
-        edges?: number;
-    }): Promise<Schemas["EntityNeighborhoodResponse"]>;
-    /** Exact type cardinality plus a bounded deterministic sample from Base. */
-    entityTypeSample(opts: {
-        type: string;
-        limit?: number;
-    } & CallOptions): Promise<Schemas["EntityTypeSampleResponse"]>;
-    /** Stored entity object-ref status and index-coverage metadata (no
-     * attributes — read those from `entityDetail`'s top-level `attributes`). */
-    entityMetadata(opts: {
-        id?: string;
-        type?: string;
-        name?: string;
-        asOf?: string;
-    }): Promise<Schemas["EntityMetadataResponse"]>;
     /**
      * Read projected attributes and current relationships from one RDF snapshot.
      * Inspect `unavailable_sections` before interpreting legacy provenance arrays.
@@ -341,14 +313,6 @@ export declare class LbbClient {
      * The caller supplies a bounded collection endpoint and its cursor.
      */
     listAll<T>(fetchPage: (cursor?: string) => Promise<ListResponse<T>>): AsyncGenerator<T, void, unknown>;
-    /** Current state of an entity's relations, optionally as-of a timestamp. */
-    currentState(body: Schemas["CurrentStateRequest"]): Promise<Schemas["CurrentStateResponse"]>;
-    /** Full edge-event history for a relationship. */
-    history(body: Schemas["RelationshipHistoryRequest"]): Promise<Schemas["RelationshipHistoryResponse"]>;
-    /** Ordered state-transition log for an entity's relation, with dwell time. */
-    transitions(body: Schemas["EntityTransitionsRequest"]): Promise<Schemas["EntityTransitionsResponse"]>;
-    /** Lineage and evidence for a single edge. */
-    why(body: Schemas["WhyRequest"]): Promise<Schemas["WhyResponse"]>;
     /**
      * SPARQL-subset SELECT/ASK/aggregate query (FILTER, HAVING, ORDER BY, ASK,
      * COUNT/SUM/AVG/MIN/MAX). GROUP BY is not limited to entity identity:
@@ -360,14 +324,27 @@ export declare class LbbClient {
      * `groups[].keys`.
      */
     sparql(body: Schemas["SparqlSelectRequest"], opts?: ReadConsistencyOptions): Promise<Schemas["SparqlSelectResponse"]>;
-    /** SPARQL 1.1 query from text (SELECT/ASK) over the live graph; `results` is SPARQL 1.1 Query Results JSON. The text dialect carries `consistency`/`min_indexed_seq` on the URL; a floor with no explicit consistency implies a strong base-plus-delta read. */
+    /**
+     * SPARQL 1.1 query from text (SELECT/ASK) over the live graph; `results` is
+     * SPARQL 1.1 Query Results JSON. The text dialect carries
+     * `consistency`/`min_indexed_seq` on the URL; a floor with no explicit
+     * consistency implies a strong base-plus-delta read. `as_of_commit_seq` in
+     * the body reads the retained published generation of that exact commit.
+     *
+     * The query is read-only, so a retryable `429` (for example
+     * `read_your_writes_pending` while publication catches up to the floor) is
+     * retried within the retry budget. A `5xx` is not retried: a query that
+     * timed out would run again.
+     */
     sparqlText(body: Schemas["SparqlTextRequest"], opts?: ReadConsistencyOptions): Promise<Schemas["SparqlTextResponse"]>;
     /**
      * Run a SPARQL 1.1 text query and return parsed results — the ergonomic
      * complement to {@link sparqlText} (which hands back the raw results string).
-     * Returns `{ vars, boolean, bindings, rows }` via {@link parseSparqlResults}:
-     * `rows` is the bindings flattened to `{ variable: lexicalValue }`, `boolean`
-     * is the ASK answer (or `null` for a SELECT).
+     * Returns `{ vars, boolean, bindings, rows, snapshot }` via
+     * {@link parseSparqlResults}: `rows` is the bindings flattened to
+     * `{ variable: lexicalValue }`, `boolean` is the ASK answer (or `null` for a
+     * SELECT), and `snapshot.served_at_seq` is the commit an eventual or pinned
+     * read answered from (`snapshot` is `null` for a plain strong read).
      */
     sparqlRows(body: Schemas["SparqlTextRequest"], opts?: ReadConsistencyOptions): Promise<SparqlResults>;
     /**

package/dist/client.js

@@ -1,5 +1,5 @@
 import { parseSparqlResults } from "./types.js";
-import { bodyMarksTerminal, errorCodeFromBody, fullJitterBackoffMs, parseLbbError, parseResponseJson, retryAllowed, retryableStatus, retryDelayMs, sleep, } from "./transport.js";
+import { bodyMarksTerminal, errorCodeFromBody, fullJitterBackoffMs, parseLbbError, parseResponseJson, retriesNetworkFailure, retriesStatus, retryAllowed, retryableStatus, retryDelayMs, sleep, } from "./transport.js";
 import { LbbCapabilityError } from "./transport.js";
 import { EntityNamespace, GraphNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace, EvalsNamespace, EmbeddingsNamespace, } from "./namespaces.js";
 export { parseSparqlResults } from "./types.js";
@@ -237,7 +237,7 @@ export class LbbClient {
         if (opts.idempotencyKey !== undefined)
             headers["idempotency-key"] = opts.idempotencyKey;
         Object.assign(headers, opts.headers ?? {});
-        const canRetry = opts.retry ?? retryAllowed(method, opts.idempotencyKey);
+        const retry = opts.retry ?? retryAllowed(method, opts.idempotencyKey);
         const body = opts.rawBody !== undefined
             ? opts.rawBody
             : opts.body !== undefined
@@ -302,7 +302,9 @@ export class LbbClient {
                         cause: error,
                     }), { name: "TimeoutError" })
                     : error;
-                if (!callerAborted && canRetry && attempt < maxRetries) {
+                if (!callerAborted &&
+                    retriesNetworkFailure(retry) &&
+                    attempt < maxRetries) {
                     const delayMs = fullJitterBackoffMs(this.retryDelayMs, attempt);
                     if (Date.now() + delayMs <= deadline) {
                         this.onRetry?.({
@@ -329,7 +331,7 @@ export class LbbClient {
                 attempt === maxRetries) {
                 break;
             }
-            if (!canRetry) {
+            if (!retriesStatus(retry, response.status)) {
                 break;
             }
             // Honor the server's typed body verdict: a terminal error
@@ -804,45 +806,6 @@ export class LbbClient {
     searchFeedbackExport() {
         return this.request("GET", "/v1/search/feedback/export");
     }
-    /**
-     * Ranked incoming/outgoing neighborhood for a graph entity.
-     *
-     * `edges` caps the edges returned per direction (default 1000, maximum
-     * 10000). When a cap cuts a direction the response carries a `truncation`
-     * block; an uncut response omits it entirely.
-     */
-    entityNeighborhood(opts) {
-        return this.request("GET", "/v1/graph/entity/neighborhood", {
-            query: {
-                id: opts.id,
-                type: opts.type,
-                name: opts.name,
-                relations: opts.relations?.join(","),
-                as_of: opts.asOf,
-                edges: opts.edges,
-            },
-        });
-    }
-    /** Exact type cardinality plus a bounded deterministic sample from Base. */
-    entityTypeSample(opts) {
-        const { type, limit, ...request } = opts;
-        return this.request("GET", "/v1/graph/entities/sample", {
-            ...request,
-            query: { type, limit },
-        });
-    }
-    /** Stored entity object-ref status and index-coverage metadata (no
-     * attributes — read those from `entityDetail`'s top-level `attributes`). */
-    entityMetadata(opts) {
-        return this.request("GET", "/v1/graph/entity/metadata", {
-            query: {
-                id: opts.id,
-                type: opts.type,
-                name: opts.name,
-                as_of: opts.asOf,
-            },
-        });
-    }
     /**
      * Read projected attributes and current relationships from one RDF snapshot.
      * Inspect `unavailable_sections` before interpreting legacy provenance arrays.
@@ -879,23 +842,7 @@ export class LbbClient {
             cursor = page.next_cursor;
         }
     }
-    // --- temporal / lineage / shapes ---
-    /** Current state of an entity's relations, optionally as-of a timestamp. */
-    currentState(body) {
-        return this.request("POST", "/v1/query/state", { body });
-    }
-    /** Full edge-event history for a relationship. */
-    history(body) {
-        return this.request("POST", "/v1/query/history", { body });
-    }
-    /** Ordered state-transition log for an entity's relation, with dwell time. */
-    transitions(body) {
-        return this.request("POST", "/v1/query/transitions", { body });
-    }
-    /** Lineage and evidence for a single edge. */
-    why(body) {
-        return this.request("POST", "/v1/query/why", { body });
-    }
+    // --- query ---
     /**
      * SPARQL-subset SELECT/ASK/aggregate query (FILTER, HAVING, ORDER BY, ASK,
      * COUNT/SUM/AVG/MIN/MAX). GROUP BY is not limited to entity identity:
@@ -911,19 +858,33 @@ export class LbbClient {
             body: this.mergeReadConsistency(body, opts),
         });
     }
-    /** SPARQL 1.1 query from text (SELECT/ASK) over the live graph; `results` is SPARQL 1.1 Query Results JSON. The text dialect carries `consistency`/`min_indexed_seq` on the URL; a floor with no explicit consistency implies a strong base-plus-delta read. */
+    /**
+     * SPARQL 1.1 query from text (SELECT/ASK) over the live graph; `results` is
+     * SPARQL 1.1 Query Results JSON. The text dialect carries
+     * `consistency`/`min_indexed_seq` on the URL; a floor with no explicit
+     * consistency implies a strong base-plus-delta read. `as_of_commit_seq` in
+     * the body reads the retained published generation of that exact commit.
+     *
+     * The query is read-only, so a retryable `429` (for example
+     * `read_your_writes_pending` while publication catches up to the floor) is
+     * retried within the retry budget. A `5xx` is not retried: a query that
+     * timed out would run again.
+     */
     sparqlText(body, opts) {
         return this.request("POST", "/v1/query/sparql-text", {
             body,
             query: this.readConsistencyQuery(opts),
+            retry: "rate_limited",
         });
     }
     /**
      * Run a SPARQL 1.1 text query and return parsed results — the ergonomic
      * complement to {@link sparqlText} (which hands back the raw results string).
-     * Returns `{ vars, boolean, bindings, rows }` via {@link parseSparqlResults}:
-     * `rows` is the bindings flattened to `{ variable: lexicalValue }`, `boolean`
-     * is the ASK answer (or `null` for a SELECT).
+     * Returns `{ vars, boolean, bindings, rows, snapshot }` via
+     * {@link parseSparqlResults}: `rows` is the bindings flattened to
+     * `{ variable: lexicalValue }`, `boolean` is the ASK answer (or `null` for a
+     * SELECT), and `snapshot.served_at_seq` is the commit an eventual or pinned
+     * read answered from (`snapshot` is `null` for a plain strong read).
      */
     async sparqlRows(body, opts) {
         return parseSparqlResults(await this.sparqlText(body, opts));

package/dist/namespaces.d.ts

@@ -61,20 +61,6 @@ export declare class SearchNamespace {
 export declare class EntityNamespace {
     private readonly client;
     constructor(client: LbbClient);
-    /**
-     * Return the exact type cardinality and a bounded deterministic sample from
-     * the Base family pinned by the published generation.
-     */
-    sample(opts: {
-        type: string;
-        limit?: number;
-    } & CallOptions): Promise<Schemas["EntityTypeSampleResponse"]>;
-    get(opts: {
-        id?: string;
-        type?: string;
-        name?: string;
-        asOf?: string;
-    }): Promise<Schemas["EntityMetadataResponse"]>;
     detail(opts: Parameters<LbbClient["entityDetail"]>[0]): Promise<Schemas["EntityDetailResponse"]>;
     /**
      * Filter entities already bound by relation patterns using typed attributes,

package/dist/namespaces.js

@@ -155,16 +155,6 @@ export class EntityNamespace {
     constructor(client) {
         this.client = client;
     }
-    /**
-     * Return the exact type cardinality and a bounded deterministic sample from
-     * the Base family pinned by the published generation.
-     */
-    sample(opts) {
-        return this.client.entityTypeSample(opts);
-    }
-    get(opts) {
-        return this.client.entityMetadata(opts);
-    }
     detail(opts) {
         return this.client.entityDetail(opts);
     }