@littlebigbrain/client 0.6.1 → 0.7.0

package/dist/client.d.ts

@@ -1,8 +1,8 @@
-import type { ImportLine, LbbClientOptions, LbbStackActivityResponse, LbbStackActivityWindow, ListResponse, RawLbbResponse, RdfExportOptions, RdfImportOptions, Schemas, SparqlResults } from "./types.js";
-import { type RequestOptions } from "./transport.js";
+import type { ImportLine, LbbClientOptions, ListResponse, RawLbbResponse, RdfExportOptions, RdfImportOptions, Schemas, SparqlResults } from "./types.js";
+import { type CallOptions, type RequestOptions } from "./transport.js";
 import { ContextNamespace, EntityNamespace, GraphNamespace, IndexNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace } from "./namespaces.js";
 export { parseSparqlResults } from "./types.js";
-export type { AttributeFilter, AttributeFilterOp, AttributeFilterValue, EntityAttributeFilterOptions, EntityPropertiesLine, FetchLike, FlatProperties, ImportLine, LbbClientOptions, LbbRequestEvent, LbbResponseEvent, LbbRetryEvent, LbbErrorPayload, LbbStackActivityResponse, LbbStackActivityWindow, ListResponse, RawLbbResponse, RdfExportOptions, RdfImportOptions, Schemas, SparqlResults, SparqlResultsJson, SparqlTerm, AskRequest, AskResponse, CommitRequest, CommitResponse, Entity, EntitySelector, GraphMetadata, GraphSummary, SchemaView, SearchRequest, SearchResponse, SearchResult, Snapshot, } from "./types.js";
+export type { AttributeFilter, AttributeFilterOp, AttributeFilterValue, EntityAttributeFilterOptions, EntityPropertiesLine, FetchLike, FlatProperties, ImportLine, LbbClientOptions, LbbRequestEvent, LbbResponseEvent, LbbRetryEvent, LbbErrorPayload, ListResponse, RawLbbResponse, RdfExportOptions, RdfImportOptions, Schemas, SparqlResults, SparqlResultsJson, SparqlTerm, AskRequest, AskResponse, CommitRequest, CommitResponse, Entity, EntitySelector, GraphMetadata, GraphSummary, SchemaView, SearchRequest, SearchResponse, SearchResult, Snapshot, } from "./types.js";
 export { LbbError } from "./transport.js";
 export type { CallOptions, Query, QueryValue, RequestOptions, } from "./transport.js";
 export type { EntityListOptions, HybridSearchOptions } from "./namespaces.js";
@@ -115,6 +115,42 @@ export declare class LbbClient {
     }): Promise<Schemas["GraphRetractResponse"]>;
     /** Create the scoped graph/branch. Construct the client with the desired graph/branch first. */
     createGraph(): Promise<Schemas["CreateGraphResponse"]>;
+    /**
+     * Fork a whole graph into a brand-new destination graph in the same tenant.
+     * The copy runs as a durable background job (`confirm` is fixed to `dst`, which
+     * the route requires to authorize the fork); the destination must not already
+     * exist, so the create-only CAS on the server side makes the call safe to
+     * retry. The response only acknowledges the enqueue — poll the destination
+     * graph's metadata (see `response.poll`) to observe the fork completing: the
+     * destination becomes readable once its head is published.
+     */
+    forkGraph(opts: {
+        src: string;
+        dst: string;
+    }): Promise<Schemas["GraphForkResponse"]>;
+    /**
+     * Declarative full-state replace: reconcile the scoped graph so its current
+     * state matches exactly the NDJSON payload (same line grammar as
+     * {@link import} — triplets or `{type,name,properties}` entity records; pass an
+     * array, serialized here, or a pre-built NDJSON string). The whole
+     * reconciliation lands as one atomic cutover: payload records are upserted, and
+     * entities present at the pre-reload head but absent from the payload leave
+     * current state (retraction semantics — history is preserved, so an `as_of`
+     * read pinned before the cutover still sees the old state). `confirm` must
+     * equal the target graph id (reload is semi-destructive). `dryRun` previews the
+     * full delta with zero durable changes. The response carries
+     * `prior_commit_seq` / `prior_snapshot_token` as the rollback anchor — read
+     * them back with `?as_of_commit_seq=<prior_commit_seq>` to see the pre-reload
+     * state. An Idempotency-Key scopes the single cutover commit, so a retry
+     * replays rather than re-applying.
+     */
+    reload(lines: ImportLine[] | string, opts: {
+        confirm: string;
+        dryRun?: boolean;
+        strict?: boolean;
+        observedAt?: string;
+        idempotencyKey?: string;
+    }): Promise<Schemas["GraphReloadResponse"]>;
     /** Fork the scoped branch from an existing branch in the same graph. */
     createBranch(body: Schemas["GraphBranchCreateRequest"]): Promise<Schemas["GraphBranchCreateResponse"]>;
     /**
@@ -385,7 +421,14 @@ export declare class LbbClient {
         name?: string;
         relations?: string[];
         asOf?: string;
+        /** Require the bounded ranged-adjacency path; returns `index_busy` while unavailable. */
+        indexed?: boolean;
     }): Promise<Schemas["EntityNeighborhoodResponse"]>;
+    /** Exact type cardinality plus a bounded deterministic sample from ranged adjacency. */
+    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: {
@@ -581,8 +624,12 @@ export declare class LbbClient {
     }): Promise<Schemas["WalCompactResponse"]>;
     /** Server, graph, and persisted-index status. */
     status(): Promise<unknown>;
-    /** Graph footprint, WAL tail, and index coverage. */
-    metadata(): Promise<Schemas["GraphMetadataResponse"]>;
+    /** Graph footprint, WAL tail, and index coverage. Exact object inventory is opt-in. */
+    metadata(opts?: {
+        includeObjects?: boolean;
+        includeIndexes?: boolean;
+        includeTemporalCoverage?: boolean;
+    }): Promise<Schemas["GraphMetadataResponse"]>;
     waitForIndexLineage(targetSeq: number, opts?: {
         timeoutMs?: number;
         pollIntervalMs?: number;
@@ -591,6 +638,4 @@ export declare class LbbClient {
     summary(): Promise<Schemas["GraphSummaryResponse"]>;
     /** List the graphs (and branches) under the scoped tenant. */
     listGraphs(): Promise<Schemas["GraphListResponse"]>;
-    /** Activity for the stack selected by the bearer stack key or session. */
-    stackActivity(window?: LbbStackActivityWindow): Promise<LbbStackActivityResponse>;
 }

package/dist/client.js

@@ -400,6 +400,53 @@ export class LbbClient {
     createGraph() {
         return this.request("POST", "/v1/graph/create");
     }
+    /**
+     * Fork a whole graph into a brand-new destination graph in the same tenant.
+     * The copy runs as a durable background job (`confirm` is fixed to `dst`, which
+     * the route requires to authorize the fork); the destination must not already
+     * exist, so the create-only CAS on the server side makes the call safe to
+     * retry. The response only acknowledges the enqueue — poll the destination
+     * graph's metadata (see `response.poll`) to observe the fork completing: the
+     * destination becomes readable once its head is published.
+     */
+    forkGraph(opts) {
+        return this.request("POST", "/v1/graph/fork", {
+            query: { src: opts.src, dst: opts.dst, confirm: opts.dst },
+            retry: true,
+        });
+    }
+    /**
+     * Declarative full-state replace: reconcile the scoped graph so its current
+     * state matches exactly the NDJSON payload (same line grammar as
+     * {@link import} — triplets or `{type,name,properties}` entity records; pass an
+     * array, serialized here, or a pre-built NDJSON string). The whole
+     * reconciliation lands as one atomic cutover: payload records are upserted, and
+     * entities present at the pre-reload head but absent from the payload leave
+     * current state (retraction semantics — history is preserved, so an `as_of`
+     * read pinned before the cutover still sees the old state). `confirm` must
+     * equal the target graph id (reload is semi-destructive). `dryRun` previews the
+     * full delta with zero durable changes. The response carries
+     * `prior_commit_seq` / `prior_snapshot_token` as the rollback anchor — read
+     * them back with `?as_of_commit_seq=<prior_commit_seq>` to see the pre-reload
+     * state. An Idempotency-Key scopes the single cutover commit, so a retry
+     * replays rather than re-applying.
+     */
+    reload(lines, opts) {
+        const ndjson = typeof lines === "string"
+            ? lines
+            : lines.map((line) => JSON.stringify(line)).join("\n");
+        return this.request("POST", "/v1/graph/reload", {
+            rawBody: ndjson,
+            contentType: "application/x-ndjson",
+            query: {
+                confirm: opts.confirm,
+                dry_run: opts.dryRun,
+                strict: opts.strict,
+                observed_at: opts.observedAt,
+            },
+            idempotencyKey: opts.idempotencyKey ?? this.idempotencyKey("reload"),
+        });
+    }
     /** Fork the scoped branch from an existing branch in the same graph. */
     createBranch(body) {
         return this.request("POST", "/v1/graph/branch", { body });
@@ -783,9 +830,18 @@ export class LbbClient {
                 name: opts.name,
                 relations: opts.relations?.join(","),
                 as_of: opts.asOf,
+                indexed: opts.indexed,
             },
         });
     }
+    /** Exact type cardinality plus a bounded deterministic sample from ranged adjacency. */
+    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) {
@@ -1078,9 +1134,15 @@ export class LbbClient {
     status() {
         return this.request("GET", "/v1/status");
     }
-    /** Graph footprint, WAL tail, and index coverage. */
-    metadata() {
-        return this.request("GET", "/v1/graph/metadata");
+    /** Graph footprint, WAL tail, and index coverage. Exact object inventory is opt-in. */
+    metadata(opts = {}) {
+        return this.request("GET", "/v1/graph/metadata", {
+            query: {
+                include_objects: opts.includeObjects,
+                include_indexes: opts.includeIndexes,
+                include_temporal_coverage: opts.includeTemporalCoverage,
+            },
+        });
     }
     async waitForIndexLineage(targetSeq, opts = {}) {
         const deadline = Date.now() + (opts.timeoutMs ?? 30_000);
@@ -1121,9 +1183,4 @@ export class LbbClient {
     listGraphs() {
         return this.request("GET", "/v1/graphs");
     }
-    // --- stack activity ---
-    /** Activity for the stack selected by the bearer stack key or session. */
-    stackActivity(window = "24h") {
-        return this.request("GET", "/v1/stack/activity", { query: { window } });
-    }
 }

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { LbbClient, LbbError, parseSparqlResults } from "./client.js";
-export type { LbbClientOptions, CallOptions, RequestOptions, EntityListOptions, HybridSearchOptions, LbbRequestEvent, LbbResponseEvent, LbbStackActivityResponse, LbbStackActivityWindow, FetchLike, Schemas, SparqlResults, SparqlResultsJson, SparqlTerm, AskRequest, AskResponse, CommitRequest, CommitResponse, Entity, EntitySelector, GraphMetadata, GraphSummary, SchemaView, SearchRequest, SearchResponse, SearchResult, Snapshot, } from "./client.js";
+export type { LbbClientOptions, CallOptions, RequestOptions, EntityListOptions, HybridSearchOptions, LbbRequestEvent, LbbResponseEvent, FetchLike, Schemas, SparqlResults, SparqlResultsJson, SparqlTerm, AskRequest, AskResponse, CommitRequest, CommitResponse, Entity, EntitySelector, GraphMetadata, GraphSummary, SchemaView, SearchRequest, SearchResponse, SearchResult, Snapshot, } from "./client.js";
 export type { components, paths, operations } from "./schema.js";

package/dist/namespaces.d.ts

@@ -143,6 +143,15 @@ export declare class IndexNamespace {
 export declare class EntityNamespace {
     private readonly client;
     constructor(client: LbbClient);
+    /**
+     * Return the exact type cardinality and a bounded deterministic sample from
+     * the ranged adjacency index. The server returns `index_busy` rather than
+     * falling back to an exhaustive snapshot scan when the index is unavailable.
+     */
+    sample(opts: {
+        type: string;
+        limit?: number;
+    } & CallOptions): Promise<Schemas["EntityTypeSampleResponse"]>;
     /**
      * Browse entities as the unified list envelope. Pass `fields` (names or `*`)
      * to inline each row's typed attributes as native JSON (under `attributes`) —

package/dist/namespaces.js

@@ -344,6 +344,14 @@ export class EntityNamespace {
     constructor(client) {
         this.client = client;
     }
+    /**
+     * Return the exact type cardinality and a bounded deterministic sample from
+     * the ranged adjacency index. The server returns `index_busy` rather than
+     * falling back to an exhaustive snapshot scan when the index is unavailable.
+     */
+    sample(opts) {
+        return this.client.entityTypeSample(opts);
+    }
     /**
      * Browse entities as the unified list envelope. Pass `fields` (names or `*`)
      * to inline each row's typed attributes as native JSON (under `attributes`) —