@terrascale/sdk 0.0.3 → 0.0.4

package/types/v1/decode.d.ts

@@ -4,7 +4,7 @@
  * `document` is the value, or the LWW winner when a causal read answers `"conflict"` with `siblings`.
  * Unknown future states pass through.
  * @typedef {object} V1Document
- * @property {import("../ids.js").EntityId} id
+ * @property {string} id Caller-supplied key or server-generated ULID.
  * @property {string} version
  * @property {"value" | "conflict" | (string & {})} state
  * @property {JsonObject} document
@@ -13,12 +13,13 @@
 /**
  * The result of a document write.
  * @typedef {object} V1WriteResult
- * @property {import("../ids.js").EntityId} id
+ * @property {string} id Caller-supplied key or server-generated ULID.
  * @property {string} version For a delete, the tombstone's version.
  * @property {string} offset The database commit offset (decimal u64), usable with shape `waitFor`.
  * @property {V1Durability} durability
  * @property {boolean} created True when a PUT or POST answered 201.
  * @property {string | undefined} location The Location header of a POST create.
+ * @property {JsonObject} [document] Stored document returned by PATCH.
  */
 /**
  * @param {string} what
@@ -85,7 +86,10 @@ export type V1Durability = "local_durable" | (string & {});
  * Unknown future states pass through.
  */
 export type V1Document = {
-    id: import("../ids.js").EntityId;
+    /**
+     * Caller-supplied key or server-generated ULID.
+     */
+    id: string;
     version: string;
     state: "value" | "conflict" | (string & {});
     document: JsonObject;
@@ -98,7 +102,10 @@ export type V1Document = {
  * The result of a document write.
  */
 export type V1WriteResult = {
-    id: import("../ids.js").EntityId;
+    /**
+     * Caller-supplied key or server-generated ULID.
+     */
+    id: string;
     /**
      * For a delete, the tombstone's version.
      */
@@ -116,6 +123,10 @@ export type V1WriteResult = {
      * The Location header of a POST create.
      */
     location: string | undefined;
+    /**
+     * Stored document returned by PATCH.
+     */
+    document?: JsonObject;
 };
 import type { JsonValue } from "./json.js";
 import type { JsonObject } from "./json.js";

package/types/v1/errors.d.ts

@@ -21,7 +21,7 @@ export function parseRetryAfter(headers: Headers): number | undefined;
  * @returns {TerraBaseV1Error}
  */
 export function parseV1Error(status: number, headers: Headers, text: string): TerraBaseV1Error;
-/** @import { JsonObject } from "./json.js" */
+/** @import { JsonObject, JsonValue } from "./json.js" */
 /**
  * @typedef {object} TerraBaseV1ErrorInit
  * @property {number} status
@@ -32,6 +32,9 @@ export function parseV1Error(status: number, headers: Headers, text: string): Te
  * @property {number | undefined} [retryAfter]
  * @property {string | undefined} [etag]
  * @property {JsonObject | undefined} [details]
+ * @property {JsonValue | undefined} [body]
+ * @property {string | undefined} [responseText]
+ * @property {Headers | undefined} [headers]
  */
 /**
  * A non-2xx TerraBase v1 response. `code` is the contract's `error.code`, or
@@ -54,6 +57,14 @@ export class TerraBaseV1Error extends Error {
     etag: string | undefined;
     /** @type {JsonObject | undefined} The raw error object, for route-specific metadata. */
     details: JsonObject | undefined;
+    /** @type {JsonValue | undefined} Complete parsed response body, including unknown fields. */
+    body: JsonValue | undefined;
+    /** @type {string} Original response text; empty when absent or unreadable. */
+    responseText: string;
+    /** @type {Headers} Response headers, including authentication challenges and retry metadata. */
+    headers: Headers;
+    /** @type {string | undefined} Diagnostic X-Request-ID, when supplied by the responder. */
+    requestId: string | undefined;
 }
 /** Current document, collection and shape producer codes, plus client not_modified. */
 export const V1ErrorCode: Readonly<{
@@ -103,5 +114,9 @@ export type TerraBaseV1ErrorInit = {
     retryAfter?: number | undefined;
     etag?: string | undefined;
     details?: JsonObject | undefined;
+    body?: JsonValue | undefined;
+    responseText?: string | undefined;
+    headers?: Headers | undefined;
 };
 import type { JsonObject } from "./json.js";
+import type { JsonValue } from "./json.js";

package/types/v1/ids.d.ts

@@ -10,8 +10,8 @@ export function requireName(kind: "database" | "collection", name: unknown): str
  * @returns {import("../ids.js").EntityId}
  */
 export function requireProject(project: unknown): import("../ids.js").EntityId;
-/** @param {unknown} id @returns {import("../ids.js").EntityId} */
-export function requireDocumentId(id: unknown): import("../ids.js").EntityId;
+/** A caller-supplied key is not a generated entity ID. @param {unknown} id @returns {string} */
+export function requireDocumentId(id: unknown): string;
 /**
  * @param {unknown} version
  * @returns {string}

package/types/v1/imports.d.ts

@@ -0,0 +1,132 @@
+/** @typedef {ReturnType<typeof job>} V1ImportJob */
+/** @typedef {{ readonly missingPrimaryKey?: "reject" | "generate" | null; readonly exclude?: readonly string[] | null }} V1ImportOptions */
+/** @typedef {{ readonly format: "postgres_plain" | "sqlite"; readonly sourceBytes: number; readonly sourceSha256: string; readonly options?: V1ImportOptions | null }} V1CreateImportRequest */
+/** One import job belongs to its destination database; preview confirmation is explicit. */
+export class V1Imports {
+    /** @param {V1Transport} transport @param {string} database */
+    constructor(transport: V1Transport, database: string);
+    /** @param {V1CreateImportRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+    create(request: V1CreateImportRequest, options?: V1RequestOptions): Promise<V1ImportJob>;
+    /** @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+    get(options?: V1RequestOptions): Promise<V1ImportJob>;
+    /** @param {number | bigint} offset @param {Uint8Array} bytes @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+    uploadSource(offset: number | bigint, bytes: Uint8Array, options?: V1RequestOptions): Promise<V1ImportJob>;
+    /** @param {{readonly options?: V1ImportOptions | null}} request @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+    update(request: {
+        readonly options?: V1ImportOptions | null;
+    }, options?: V1RequestOptions): Promise<V1ImportJob>;
+    /** @param {{readonly previewId: string}} request @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+    start(request: {
+        readonly previewId: string;
+    }, options?: V1RequestOptions): Promise<V1ImportJob>;
+    /** @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+    cancel(options?: V1RequestOptions): Promise<V1ImportJob>;
+    /** @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+    resume(options?: V1RequestOptions): Promise<V1ImportJob>;
+    #private;
+}
+export type V1ImportJob = ReturnType<typeof job>;
+export type V1ImportOptions = {
+    readonly missingPrimaryKey?: "reject" | "generate" | null;
+    readonly exclude?: readonly string[] | null;
+};
+export type V1CreateImportRequest = {
+    readonly format: "postgres_plain" | "sqlite";
+    readonly sourceBytes: number;
+    readonly sourceSha256: string;
+    readonly options?: V1ImportOptions | null;
+};
+import type { V1RequestOptions } from "./terrabase-v1.js";
+import type { V1Transport } from "./transport.js";
+declare const job: import("./management-decode.js").Decoder<Readonly<{
+    id: string;
+    project: string;
+    database: string;
+    region: string;
+    state: string;
+    cancelRequested: boolean;
+    options: Readonly<{
+        missingPrimaryKey: string | null;
+        exclude: readonly string[] | null;
+    }>;
+    source: Readonly<{
+        format: string;
+        bytes: number | import("./json.js").ExactDecimal;
+        sha256: string;
+        receivedBytes: number | import("./json.js").ExactDecimal;
+        staged: boolean;
+        retainedUntil: string | null;
+    }>;
+    preview: Readonly<{
+        id: string;
+        tables: readonly Readonly<{
+            source: string;
+            collection: string;
+            excluded: boolean;
+            rows: number | import("./json.js").ExactDecimal;
+            idPolicy: string;
+            primaryKey: readonly string[];
+            columns: readonly Readonly<{
+                name: /*elided*/ any;
+                sourceType: /*elided*/ any;
+                mapping: /*elided*/ any;
+                nullable: /*elided*/ any;
+                excluded: /*elided*/ any;
+            }>[];
+            constraints: readonly Readonly<{
+                kind: /*elided*/ any;
+                name: /*elided*/ any;
+                columns: /*elided*/ any;
+                references: /*elided*/ any;
+                enforced: /*elided*/ any;
+            }>[];
+            issues: readonly Readonly<{
+                severity: /*elided*/ any;
+                code: /*elided*/ any;
+                column: /*elided*/ any;
+                row: /*elided*/ any;
+                message: /*elided*/ any;
+            }>[];
+        }>[];
+        skipped: readonly Readonly<{
+            kind: string;
+            name: string;
+        }>[];
+        skippedTruncated: boolean;
+        blocking: number | import("./json.js").ExactDecimal;
+        warnings: number | import("./json.js").ExactDecimal;
+    }> | null;
+    confirmedPreviewId: string | null;
+    progress: Readonly<{
+        tablesDone: number | import("./json.js").ExactDecimal;
+        tablesTotal: number | import("./json.js").ExactDecimal;
+        rowsWritten: number | import("./json.js").ExactDecimal;
+        rowsTotal: number | import("./json.js").ExactDecimal;
+        currentTable: string | null;
+    }> | null;
+    validation: Readonly<{
+        passed: boolean;
+        tables: readonly Readonly<{
+            source: string;
+            collection: string;
+            sourceRows: number | import("./json.js").ExactDecimal;
+            documents: number | import("./json.js").ExactDecimal;
+            sourceChecksum: string;
+            documentChecksum: string;
+            match: boolean;
+        }>[];
+    }> | null;
+    error: Readonly<{
+        code: string;
+        message: string;
+        retryable: boolean;
+        table: string | null;
+        row: number | import("./json.js").ExactDecimal | null;
+        column: string | null;
+    }> | null;
+    createdAt: string;
+    updatedAt: string;
+    startedAt: string | null;
+    finishedAt: string | null;
+}>>;
+export {};

package/types/v1/indexes.d.ts

@@ -0,0 +1,75 @@
+/** Secondary indexes, automatic policies and workload recommendations for one database. */
+export class V1Indexes {
+    /** @param {V1Transport} transport @param {string} database */
+    constructor(transport: V1Transport, database: string);
+    /** @param {V1CreateIndexRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1Index>} */
+    create(request: V1CreateIndexRequest, options?: V1RequestOptions): Promise<V1Index>;
+    /** @param {{ readonly collection?: string }} [request] @param {V1RequestOptions} [options] @returns {Promise<V1IndexList>} */
+    list(request?: {
+        readonly collection?: string;
+    }, options?: V1RequestOptions): Promise<V1IndexList>;
+    /** @param {string} name @param {V1RequestOptions} [options] @returns {Promise<void>} */
+    drop(name: string, options?: V1RequestOptions): Promise<void>;
+    /** @param {string} collection @param {V1RequestOptions} [options] @returns {Promise<V1AutoIndexPolicy>} */
+    getAutoPolicy(collection: string, options?: V1RequestOptions): Promise<V1AutoIndexPolicy>;
+    /** @param {string} collection @param {{ readonly enabled: boolean }} request @param {V1RequestOptions} [options] @returns {Promise<V1AutoIndexPolicy>} */
+    setAutoPolicy(collection: string, request: {
+        readonly enabled: boolean;
+    }, options?: V1RequestOptions): Promise<V1AutoIndexPolicy>;
+    /** @param {V1RequestOptions} [options] @returns {Promise<V1IndexRecommendations>} */
+    recommendations(options?: V1RequestOptions): Promise<V1IndexRecommendations>;
+    /** @param {string} id Opaque producer recommendation identifier. @param {V1RequestOptions} [options] @returns {Promise<V1AppliedIndexRecommendation>} */
+    applyRecommendation(id: string, options?: V1RequestOptions): Promise<V1AppliedIndexRecommendation>;
+    #private;
+}
+export type V1Index = ReturnType<typeof index>;
+export type V1IndexList = ReturnType<typeof indexes>;
+export type V1AutoIndexPolicy = ReturnType<typeof policy>;
+export type V1IndexRecommendations = ReturnType<typeof recommendations>;
+export type V1AppliedIndexRecommendation = ReturnType<typeof applied>;
+export type V1CreateIndexRequest = {
+    readonly collection: string;
+    readonly fields: readonly string[];
+    readonly name?: string | null;
+};
+import type { V1RequestOptions } from "./terrabase-v1.js";
+import type { V1Transport } from "./transport.js";
+/** @import { V1Transport } from "./transport.js" */
+/** @import { V1RequestOptions } from "./terrabase-v1.js" */
+declare const index: import("./management-decode.js").Decoder<Readonly<{
+    name: string;
+    collection: string;
+    fields: readonly string[];
+    state: string;
+}>>;
+declare const indexes: import("./management-decode.js").Decoder<Readonly<{
+    items: readonly Readonly<{
+        name: string;
+        collection: string;
+        fields: readonly string[];
+        state: string;
+    }>[];
+}>>;
+declare const policy: import("./management-decode.js").Decoder<Readonly<{
+    collection: string;
+    enabled: boolean;
+}>>;
+declare const recommendations: import("./management-decode.js").Decoder<Readonly<{
+    items: readonly Readonly<{
+        id: string;
+        collection: string;
+        fields: readonly string[];
+        reason: string;
+        queries: number | import("./json.js").ExactDecimal;
+    }>[];
+}>>;
+declare const applied: import("./management-decode.js").Decoder<Readonly<{
+    status: string;
+    index: Readonly<{
+        name: string;
+        collection: string;
+        fields: readonly string[];
+        state: string;
+    }>;
+}>>;
+export {};

package/types/v1/management-decode.d.ts

@@ -0,0 +1,15 @@
+/** @template T @param {{ [K in keyof T]: Decoder<T[K]> }} fields @returns {Decoder<Readonly<T>>} */
+export function record<T>(fields: { [K in keyof T]: Decoder<T[K]>; }): Decoder<Readonly<T>>;
+/** @import { JsonValue } from "./json.js" */
+/** @template T @typedef {(value: JsonValue | undefined) => T} Decoder */
+export const text: Decoder<string>;
+export const flag: Decoder<boolean>;
+/** @type {Decoder<number | ExactDecimal>} */
+export const numeric: Decoder<number | ExactDecimal>;
+export function nullable<T>(decode: Decoder<T>): Decoder<T | null>;
+export function optional<T>(decode: Decoder<T>): Decoder<T | undefined>;
+export function list<T>(decode: Decoder<T>): Decoder<readonly T[]>;
+export function dictionary<T>(decode: Decoder<T>): Decoder<Readonly<Record<string, T>>>;
+export type Decoder<T> = (value: JsonValue | undefined) => T;
+import { ExactDecimal } from "./json.js";
+import type { JsonValue } from "./json.js";

package/types/v1/management-routes.d.ts

@@ -0,0 +1,3 @@
+/** @type {readonly import("./routes.js").V1Route[]} */
+export const managementV1Routes: readonly import("./routes.js").V1Route[];
+export type ManagementOperation = "getShapeManifest" | "healthz" | "readyz" | "backupz" | "replicationHealth" | "listPlatformDatabases" | "listPlatformCollections" | "listPlatformDocuments" | "getPlatformDocument" | "createImport" | "getImport" | "uploadImportSource" | "updateImport" | "startImport" | "cancelImport" | "resumeImport" | "createBackup" | "listBackups" | "restoreBackup" | "getBackupPolicy" | "setBackupPolicy" | "getRestoreWindow" | "planPointInTime" | "restorePointInTime" | "getBackupDestination" | "setBackupDestination" | "deleteBackupDestination" | "getProjectUsage" | "getProjectAnalytics" | "getProjectReplication" | "getDatabaseUsage" | "getDatabaseAnalytics" | "getDatabaseReplication" | "createIndex" | "listIndexes" | "dropIndex" | "getAutoIndexPolicy" | "setAutoIndexPolicy" | "listIndexRecommendations" | "applyIndexRecommendation" | "getDatabaseSchema" | "inferCollectionSchema" | "declareCollectionSchema" | "listQueryShapes" | "createSavedQuery" | "listSavedQueries" | "getSavedQuery" | "updateSavedQuery" | "deleteSavedQuery";

package/types/v1/management-validation.d.ts

@@ -0,0 +1,8 @@
+/** @import { V1DatabaseListRequest } from "./catalog.js" */
+/** @param {unknown} request @param {readonly string[]} allowed */
+export function members(request: unknown, allowed: readonly string[]): void;
+/** @param {object} options */
+export function mutationOptions(options: object): void;
+/** @param {V1DatabaseListRequest} request */
+export function pageQuery(request: V1DatabaseListRequest): URLSearchParams;
+import type { V1DatabaseListRequest } from "./catalog.js";

package/types/v1/routes.d.ts

@@ -4,12 +4,15 @@ export function v1Route(operation: V1Operation): V1Route;
 export function v1RoutePath(route: V1Route, params: Readonly<Record<string, string>>): string;
 /** @type {readonly V1Route[]} */
 export const v1Routes: readonly V1Route[];
-export type V1Operation = "getDocument" | "putDocument" | "createDocument" | "patchDocument" | "deleteDocument" | "commitTransaction" | "queryDocuments" | "createCollection" | "getCollection" | "listCollections" | "dropCollection" | "readShape";
+/** @type {readonly V1Route[]} */
+export const shapeV1Routes: readonly V1Route[];
+export type V1Operation = import("./management-routes.js").ManagementOperation | "readFreeShape" | "getShapeKey" | "getDocument" | "putDocument" | "createDocument" | "patchDocument" | "deleteDocument" | "commitTransaction" | "queryDocuments" | "createCollection" | "getCollection" | "listCollections" | "dropCollection" | "readShape" | "runSql" | "checkSql" | "explainSql" | "streamDatabaseChanges" | "listDocuments" | "getCollectionSchema" | "putCollectionSchema" | "deleteCollectionSchema" | "createDatabase" | "listDatabases" | "getDatabase" | "updateDatabase" | "deleteDatabase" | "branchDatabase";
 export type V1Route = {
     operation: V1Operation;
     method: "GET" | "PUT" | "POST" | "PATCH" | "DELETE";
     pathTemplate: string;
-    permission: "documents:read" | "documents:write" | "shapes:read";
+    permission: "documents:read" | "documents:write" | "shapes:read" | "databases:read" | "databases:write" | "anonymous" | "platform-admin";
+    additionalPermissions?: readonly string[];
     requestMediaTypes: readonly string[];
     responseMediaType: string;
     successStatuses: readonly number[];

package/types/v1/saved-queries.d.ts

@@ -0,0 +1,33 @@
+/** Saved queries belong to the authorized project, independently of database handles. */
+export class V1SavedQueries {
+    /** @param {V1Transport} transport */
+    constructor(transport: V1Transport);
+    /** @param {V1SavedQueryRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1SavedQuery>} */
+    create(request: V1SavedQueryRequest, options?: V1RequestOptions): Promise<V1SavedQuery>;
+    /** @param {import("./catalog.js").V1DatabaseListRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<V1SavedQueryPage>} */
+    list(request?: import("./catalog.js").V1DatabaseListRequest, options?: V1RequestOptions): Promise<V1SavedQueryPage>;
+    /** @param {string} id @param {V1RequestOptions} [options] @returns {Promise<V1SavedQuery>} */
+    get(id: string, options?: V1RequestOptions): Promise<V1SavedQuery>;
+    /** @param {string} id @param {V1SavedQueryRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1SavedQuery>} */
+    update(id: string, request: V1SavedQueryRequest, options?: V1RequestOptions): Promise<V1SavedQuery>;
+    /** @param {string} id @param {V1RequestOptions} [options] @returns {Promise<void>} */
+    delete(id: string, options?: V1RequestOptions): Promise<void>;
+    #private;
+}
+export type V1SavedQuery = {
+    readonly id: string;
+    readonly name: string;
+    readonly sql: string;
+    readonly createdAt: string;
+    readonly updatedAt: string | null;
+};
+export type V1SavedQueryRequest = {
+    readonly name: string;
+    readonly sql: string;
+};
+export type V1SavedQueryPage = {
+    readonly items: readonly V1SavedQuery[];
+    readonly next: string | null;
+};
+import type { V1RequestOptions } from "./terrabase-v1.js";
+import type { V1Transport } from "./transport.js";

package/types/v1/shape-crypto.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @typedef {object} ShapeObjectRequest
+ * @property {string} handle The shape handle this client requested, e.g. `h1-…`.
+ * @property {string} offset Canonical offset of the object's URL, e.g. `2` or `snap.0.0`.
+ * @property {string} epoch Decimal epoch the client expects in the header.
+ * @property {string} keyId The 26-character project data key id the client expects in the header.
+ * @property {Uint8Array} key Raw 32-byte epoch key `K_e`.
+ */
+/**
+ * Verifies and decrypts one TBS1 sealed shape object. The plaintext is returned only when the
+ * header, every frame tag and the framing rules pass. Any failure throws and yields no bytes.
+ *
+ * @param {Uint8Array} input Exact TBS1 object bytes.
+ * @param {ShapeObjectRequest} request
+ * @returns {Promise<Uint8Array>}
+ */
+export function decryptShapeObject(input: Uint8Array, { handle, offset, epoch, keyId, key: keyInput }: ShapeObjectRequest): Promise<Uint8Array>;
+export type ShapeObjectRequest = {
+    /**
+     * The shape handle this client requested, e.g. `h1-…`.
+     */
+    handle: string;
+    /**
+     * Canonical offset of the object's URL, e.g. `2` or `snap.0.0`.
+     */
+    offset: string;
+    /**
+     * Decimal epoch the client expects in the header.
+     */
+    epoch: string;
+    /**
+     * The 26-character project data key id the client expects in the header.
+     */
+    keyId: string;
+    /**
+     * Raw 32-byte epoch key `K_e`.
+     */
+    key: Uint8Array;
+};

package/types/v1/shape-manifest.d.ts

@@ -0,0 +1,28 @@
+/** @typedef {ReturnType<typeof manifest>} V1ShapeManifest */
+/** @typedef {{readonly handle: string; readonly offset: string; readonly where?: import("./filter.js").V1Filter}} V1ShapeManifestRequest */
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {V1ShapeManifestRequest} request @param {AbortSignal | undefined} signal @returns {Promise<V1ShapeManifest>} */
+export function readShapeManifest(transport: V1Transport, params: Readonly<Record<string, string>>, request: V1ShapeManifestRequest, signal: AbortSignal | undefined): Promise<V1ShapeManifest>;
+export type V1ShapeManifest = ReturnType<typeof manifest>;
+export type V1ShapeManifestRequest = {
+    readonly handle: string;
+    readonly offset: string;
+    readonly where?: import("./filter.js").V1Filter;
+};
+import type { V1Transport } from "./transport.js";
+/** @import { V1Transport } from "./transport.js" */
+declare const manifest: import("./management-decode.js").Decoder<Readonly<{
+    handle: string;
+    objects: readonly Readonly<{
+        offset: string;
+        next_offset: string;
+        binding: string;
+        object: string;
+        url: string;
+        expires_at: string;
+        epoch: string;
+        key_id: string;
+        sha256: string;
+        size: number | import("./json.js").ExactDecimal;
+    }>[];
+}>>;
+export {};

package/types/v1/shape-reader.d.ts

@@ -0,0 +1,45 @@
+/** @param {import("./json.js").JsonValue | undefined} value @param {Headers} headers @returns {V1ShapePage} */
+export function decodeFreeShapePage(value: import("./json.js").JsonValue | undefined, headers: Headers): V1ShapePage;
+/**
+ * Follows exactly one authorized same-route 307; credentials never follow an arbitrary Location.
+ * @param {V1Transport} transport @param {Readonly<Record<string,string>>} params
+ * @param {V1ShapeRequest} request @param {AbortSignal | undefined} signal
+ * @param {string | undefined} [ifNoneMatch] A complete entity-tag list or *; 304 throws not_modified with response headers.
+ * @returns {Promise<V1ShapePage>}
+ */
+export function readShapePage(transport: V1Transport, params: Readonly<Record<string, string>>, request: V1ShapeRequest, signal: AbortSignal | undefined, ifNoneMatch?: string | undefined): Promise<V1ShapePage>;
+/**
+ * Reuse process-memory keys for this handle/epoch/KID; fetch misses without HTTP cache reuse.
+ * @param {V1Transport} transport @param {Readonly<Record<string,string>>} params
+ * @param {Uint8Array} bytes @param {V1SealedShapePosition} position @param {AbortSignal | undefined} signal
+ * @returns {Promise<V1ShapePage>}
+ */
+export function decryptSealedShapePage(transport: V1Transport, params: Readonly<Record<string, string>>, bytes: Uint8Array, position: V1SealedShapePosition, signal: AbortSignal | undefined): Promise<V1ShapePage>;
+/** @typedef {{readonly handle: string; readonly epoch: string; readonly keyId: string}} V1ShapeKeyRequest */
+/** @typedef {V1ShapeKeyRequest & {readonly key: Uint8Array}} V1ShapeKey */
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {V1ShapeKeyRequest} request @param {AbortSignal | undefined} signal @returns {Promise<V1ShapeKey>} */
+export function readShapeKey(transport: V1Transport, params: Readonly<Record<string, string>>, request: V1ShapeKeyRequest, signal: AbortSignal | undefined): Promise<V1ShapeKey>;
+export type V1ShapeKeyRequest = {
+    readonly handle: string;
+    readonly epoch: string;
+    readonly keyId: string;
+};
+export type V1ShapeKey = V1ShapeKeyRequest & {
+    readonly key: Uint8Array;
+};
+export type V1SealedShapePosition = {
+    handle: string;
+    offset: string;
+    epoch: string;
+    keyId: string;
+};
+export type ShapeKeys = {
+    latestEpoch: bigint;
+    keys: Map<string, {
+        epoch: bigint;
+        key: Uint8Array;
+    }>;
+};
+import type { V1ShapePage } from "./shapes.js";
+import type { V1Transport } from "./transport.js";
+import type { V1ShapeRequest } from "./shapes.js";

package/types/v1/shape-subscription.d.ts

@@ -0,0 +1,35 @@
+export class V1ShapeSubscription {
+    /**
+     * @param {V1Transport} transport
+     * @param {Readonly<Record<string, string>>} params
+     * @param {{ where?: V1Filter | undefined }} [shape]
+     * @param {V1ShapeSubscribeOptions} [options]
+     */
+    constructor(transport: V1Transport, params: Readonly<Record<string, string>>, shape?: {
+        where?: V1Filter | undefined;
+    }, options?: V1ShapeSubscribeOptions);
+    /** A copy per read: callers cannot change the documents this subscription holds. */
+    get state(): Map<string, V1ShapeDocument>;
+    get upToDate(): boolean;
+    /** Settles when the run ends: resolves on close, rejects on a terminal failure. */
+    get done(): Promise<void>;
+    close(): void;
+    #private;
+}
+export type V1ShapeSubscribeOptions = {
+    /**
+     * Closes the subscription when aborted; cancellation settles `done`.
+     */
+    signal?: AbortSignal | undefined;
+    /**
+     * Runs after validated responses and freshness changes; throwing rejects `done` unless already closed or aborted.
+     */
+    onUpdate?: ((subscription: V1ShapeSubscription) => void) | undefined;
+};
+export type V1ShapeDocument = {
+    readonly version: string;
+    readonly document: JsonObject;
+};
+import type { V1Transport } from "./transport.js";
+import type { V1Filter } from "./filter.js";
+import type { JsonObject } from "./json.js";

package/types/v1/shapes.d.ts

@@ -4,6 +4,8 @@
  * @returns {string}
  */
 export function requireShapeOffset(value: unknown): string;
+/** @param {unknown} value @returns {string} */
+export function requireShapeHandle(value: unknown): string;
 /** @param {V1ShapeRequest} request @returns {URLSearchParams} */
 export function encodeShapeRequest(request: V1ShapeRequest): URLSearchParams;
 /** @param {JsonValue | undefined} value @param {Headers} headers @returns {V1ShapePage} */
@@ -42,12 +44,12 @@ export type V1ShapeRequest = {
 };
 export type V1ShapeOp = {
     readonly op: "upsert";
-    readonly id: import("../ids.js").EntityId;
+    readonly id: string;
     readonly version: string;
     readonly document: JsonObject;
 } | {
     readonly op: "delete";
-    readonly id: import("../ids.js").EntityId;
+    readonly id: string;
 };
 export type V1ShapeChange = {
     readonly offset: string;
@@ -71,6 +73,18 @@ export type V1ShapePage = {
      */
     cursor: string | undefined;
     etag: string | undefined;
+    /**
+     * Free-read protocol coverage (feed sequence, not write offset).
+     */
+    coveredOffset?: string | undefined;
+    /**
+     * Free-read materialization position.
+     */
+    valuesAt?: string | undefined;
+    /**
+     * Opaque free-read resume token.
+     */
+    cursorResume?: string | undefined;
 };
 import type { JsonValue } from "./json.js";
 import type { V1Transport } from "./transport.js";

package/types/v1/sql.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Runs the producer's read-only SQL subset; it never converts a legacy SQL builder.
+ * @param {V1Transport} transport
+ * @param {string} database
+ * @param {string} sql
+ * @param {V1RequestOptions} [options]
+ * @returns {Promise<V1SqlResult>}
+ */
+export function runSql(transport: V1Transport, database: string, sql: string, options?: V1RequestOptions): Promise<V1SqlResult>;
+/**
+ * Check reports invalid SQL in a successful body; explain reports a producer HTTP error.
+ * @param {V1Transport} transport
+ * @param {string} database
+ * @param {string} sql
+ * @param {V1RequestOptions} [options]
+ * @param {"checkSql" | "explainSql"} [operation]
+ * @returns {Promise<V1SqlCheck>}
+ */
+export function checkSql(transport: V1Transport, database: string, sql: string, options?: V1RequestOptions, operation?: "checkSql" | "explainSql"): Promise<V1SqlCheck>;
+export type V1SqlRow = {
+    readonly id: string;
+    readonly value: JsonObject;
+};
+/**
+ * SQL returns one bounded result, without a pagination cursor.
+ */
+export type V1SqlResult = {
+    readonly matched: number;
+    readonly truncated: boolean;
+    readonly rows: readonly V1SqlRow[];
+};
+export type V1SqlIndexSuggestion = {
+    readonly field: string;
+    readonly reason: string;
+};
+export type V1SqlCheck = {
+    readonly ok: boolean;
+    readonly error: string | null;
+    readonly collection: string | null;
+    readonly hasLimit: boolean;
+    readonly plan: readonly string[];
+    readonly indexes: readonly string[];
+    readonly suggestions: readonly V1SqlIndexSuggestion[];
+};
+import type { V1Transport } from "./transport.js";
+import type { V1RequestOptions } from "./terrabase-v1.js";
+import type { JsonObject } from "./json.js";