@terrascale/sdk 0.0.3 → 0.0.5

package/types/v1/terrabase-v1.d.ts

@@ -1,5 +1,15 @@
 /**
- * Creates a TerraBase v1 client for documents, transactions, queries and shapes.
+ * @param {JsonValue | undefined} value
+ * @returns {V1QueryPage}
+ */
+export function decodeQueryPage(value: JsonValue | undefined): V1QueryPage;
+/** @typedef {{ readonly id: import("../ids.js").EntityId; readonly name: string; readonly createdAt: string }} V1CollectionInfo */
+/** @typedef {{ readonly items: readonly V1CollectionInfo[]; readonly nextCursor: string | null }} V1CollectionPage */
+/** @typedef {{ readonly limit?: number | undefined; readonly cursor?: string | undefined }} V1CollectionListOptions */
+/** @param {JsonValue | undefined} value @returns {V1CollectionInfo} */
+export function decodeCollection(value: JsonValue | undefined): V1CollectionInfo;
+/**
+ * Creates a project-scoped TerraBase client for documents, SQL, changes and catalog operations.
  * @param {TerraBaseV1ClientConfig} config
  * @returns {TerraBaseV1Client}
  */
@@ -61,6 +71,26 @@ export class V1Collection {
      * @returns {Promise<V1QueryPage>}
      */
     query(query?: V1Query, options?: V1RequestOptions): Promise<V1QueryPage>;
+    /** @param {{ readonly limit?: number | undefined; readonly cursor?: string | undefined }} [request] @param {V1RequestOptions} [options] @returns {Promise<V1QueryPage>} */
+    list(request?: {
+        readonly limit?: number | undefined;
+        readonly cursor?: string | undefined;
+    }, options?: V1RequestOptions): Promise<V1QueryPage>;
+    /** @param {V1RequestOptions} [options] */
+    getSchema(options?: V1RequestOptions): Promise<import("./catalog.js").V1CollectionSchema>;
+    /** @param {import("./json.js").JsonInputObject | boolean} schema @param {V1RequestOptions} [options] */
+    putSchema(schema: import("./json.js").JsonInputObject | boolean, options?: V1RequestOptions): Promise<import("./catalog.js").V1CollectionSchema>;
+    /** @param {V1RequestOptions} [options] */
+    deleteSchema(options?: V1RequestOptions): Promise<import("./catalog.js").V1CollectionSchema>;
+    /** @param {V1RequestOptions} [options] */
+    getTtl(options?: V1RequestOptions): Promise<import("./catalog.js").V1CollectionTtl>;
+    /**
+     * Documents whose member at `path` holds a past RFC 3339 UTC time are deleted by an hourly sweep (up to about an hour late).
+     * @param {string} path JSON Pointer such as `/expiresAt`. @param {V1RequestOptions} [options]
+     */
+    putTtl(path: string, options?: V1RequestOptions): Promise<import("./catalog.js").V1CollectionTtl>;
+    /** @param {V1RequestOptions} [options] */
+    deleteTtl(options?: V1RequestOptions): Promise<import("./catalog.js").V1CollectionTtl>;
     /**
      * Iterates over every page, following `nextCursor`. `count`
      * is sent with the first page only.
@@ -79,11 +109,50 @@ export class V1Collection {
     /**
      * Reads one C# shape snapshot page or change-log chunk. Bootstrap defaults to offset -1.
      * Echo handle, nextOffset and cursor on the following read; discard state on must_refetch.
+     * ifNoneMatch sends a complete entity-tag list or *; 304 throws not_modified with cache headers.
      * @param {V1ShapeRequest} [request]
+     * @param {V1RequestOptions & {readonly ifNoneMatch?: string}} [options]
+     * @returns {Promise<V1ShapePage>}
+     */
+    shape(request?: V1ShapeRequest, options?: V1RequestOptions & {
+        readonly ifNoneMatch?: string;
+    }): Promise<V1ShapePage>;
+    /**
+     * Subscribe to the free-read v1 protocol. Stop with close() or the request signal.
+     * @param {{where?: V1Filter | undefined}} [request]
+     * @param {import("./shape-subscription.js").V1ShapeSubscribeOptions} [options]
+     * @returns {V1ShapeSubscription}
+     */
+    subscribeShape(request?: {
+        where?: V1Filter | undefined;
+    }, options?: import("./shape-subscription.js").V1ShapeSubscribeOptions): V1ShapeSubscription;
+    /** @param {import("./shape-manifest.js").V1ShapeManifestRequest} request @param {V1RequestOptions} [options] */
+    shapeManifest(request: import("./shape-manifest.js").V1ShapeManifestRequest, options?: V1RequestOptions): Promise<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 | ExactDecimal;
+        }>[];
+    }>>;
+    /** @param {import("./shape-reader.js").V1ShapeKeyRequest} request @param {V1RequestOptions} [options] */
+    shapeKey(request: import("./shape-reader.js").V1ShapeKeyRequest, options?: V1RequestOptions): Promise<import("./shape-reader.js").V1ShapeKey>;
+    /**
+     * Verify a complete TBS1 object using its authenticated epoch key. Applies no state.
+     * Object delivery through manifests is pending the producer's FR-22 contract.
+     * @param {Uint8Array} bytes
+     * @param {import("./shape-reader.js").V1SealedShapePosition} position
      * @param {V1RequestOptions} [options]
      * @returns {Promise<V1ShapePage>}
      */
-    shape(request?: V1ShapeRequest, options?: V1RequestOptions): Promise<V1ShapePage>;
+    decryptShapeObject(bytes: Uint8Array, position: import("./shape-reader.js").V1SealedShapePosition, options?: V1RequestOptions): Promise<V1ShapePage>;
     #private;
 }
 /**
@@ -197,6 +266,16 @@ export class V1Database {
      * @param {string} name
      */
     constructor(transport: V1Transport, name: string);
+    /** @type {V1Imports} */
+    imports: V1Imports;
+    /** @type {V1Backups} */
+    backups: V1Backups;
+    /** @type {V1DatabaseUsageClient} */
+    metrics: V1DatabaseUsageClient;
+    /** @type {V1Indexes} */
+    indexes: V1Indexes;
+    /** @type {V1DatabaseSchemaClient} */
+    schema: V1DatabaseSchemaClient;
     /** @type {V1Collections} */
     collections: V1Collections;
     /** @type {string} */
@@ -208,6 +287,19 @@ export class V1Database {
     collection(name: string): V1Collection;
     /** @returns {V1Transaction} */
     transaction(): V1Transaction;
+    /** @param {string} statement @param {V1RequestOptions} [options] */
+    sql(statement: string, options?: V1RequestOptions): Promise<import("./sql.js").V1SqlResult>;
+    /** @param {string} statement @param {V1RequestOptions} [options] */
+    checkSql(statement: string, options?: V1RequestOptions): Promise<import("./sql.js").V1SqlCheck>;
+    /** @param {string} statement @param {V1RequestOptions} [options] */
+    explainSql(statement: string, options?: V1RequestOptions): Promise<import("./sql.js").V1SqlCheck>;
+    /** @param {import("./changes.js").V1ChangeStreamRequest} [request] @param {V1RequestOptions} [options] */
+    changes(request?: import("./changes.js").V1ChangeStreamRequest, options?: V1RequestOptions): AsyncGenerator<import("./changes.js").V1DatabaseChange | import("./changes.js").V1DatabaseChangeCursor, void, undefined>;
+    /**
+     * Streams every live document as `{ collection, id, document }`, in collection then id order, from one snapshot.
+     * @param {import("./export.js").V1ExportOptions} [options]
+     */
+    export(options?: import("./export.js").V1ExportOptions): AsyncGenerator<import("./export.js").V1ExportedDocument, void, undefined>;
     #private;
 }
 /**
@@ -222,9 +314,22 @@ export class TerraBaseV1Client {
      * @returns {V1Database}
      */
     database(name: string): V1Database;
+    /** @returns {V1Databases} Project-scoped database catalog. */
+    get databases(): V1Databases;
+    /** @returns {V1SavedQueries} */
+    get savedQueries(): V1SavedQueries;
+    /** @returns {V1ProjectUsageClient} */
+    get metrics(): V1ProjectUsageClient;
+    /** @returns {V1BackupDestinationClient} */
+    get backupDestination(): V1BackupDestinationClient;
+    /** @returns {V1Health} */
+    get health(): V1Health;
+    /** @returns {V1Platform} */
+    get platform(): V1Platform;
     #private;
 }
 export type V1CollectionInfo = {
+    readonly id: import("../ids.js").EntityId;
     readonly name: string;
     readonly createdAt: string;
 };
@@ -277,6 +382,10 @@ export type V1PatchOp = {
     readonly op: "inc";
     readonly path: string;
     readonly by: number | bigint | ExactDecimal;
+} | {
+    readonly op: "add" | "remove";
+    readonly path: string;
+    readonly value: import("./filter.js").V1Scalar;
 } | {
     readonly op: "append";
     readonly path: string;
@@ -290,17 +399,28 @@ export type V1Patch = {
 } | {
     readonly ops: readonly V1PatchOp[];
 };
-export type V1SortKey = {
+export type V1FieldSortKey = {
     readonly path: V1Path;
     readonly order?: "asc" | "desc" | undefined;
 };
+/**
+ * Vector similarity sort, nearest first. It must be the only sort key; limit is at most 100 and there is no cursor.
+ */
+export type V1NearSortKey = {
+    readonly near: {
+        readonly path: V1Path;
+        readonly vector: readonly number[];
+        readonly metric?: "cosine" | "l2" | undefined;
+    };
+};
+export type V1SortKey = V1FieldSortKey | V1NearSortKey;
 /**
  * A query-v1 request. Every member is optional.
  */
 export type V1Query = {
     filter?: V1Filter | null | undefined;
     /**
-     * At most 4 keys; results are finally ordered by `$id`.
+     * At most 4 keys, or one `near` key; results are finally ordered by `$id`.
      */
     sort?: readonly V1SortKey[] | undefined;
     /**
@@ -344,6 +464,7 @@ export type V1Precondition = {
 export type V1TransactionOpResult = {
     readonly id: string;
     readonly version: string;
+    readonly document?: import("./json.js").JsonObject;
 } | {
     readonly asserted: true;
     readonly count?: string;
@@ -360,15 +481,28 @@ export type V1TransactionResult = {
      */
     results: readonly V1TransactionOpResult[];
 };
+import type { JsonValue } from "./json.js";
 import type { TerraBaseV1ClientConfig } from "./transport.js";
 import type { V1Document } from "./decode.js";
 import type { JsonInputObject } from "./json.js";
 import type { V1WriteResult } from "./decode.js";
 import type { V1ShapeRequest } from "./shapes.js";
 import type { V1ShapePage } from "./shapes.js";
-import { V1Transport } from "./transport.js";
 import type { V1Filter } from "./filter.js";
-import type { JsonInput } from "./json.js";
+import { V1ShapeSubscription } from "./shape-subscription.js";
 import { ExactDecimal } from "./json.js";
+import { V1Transport } from "./transport.js";
+import { V1Imports } from "./imports.js";
+import { V1Backups } from "./backups.js";
+import { V1DatabaseUsageClient } from "./usage.js";
+import { V1Indexes } from "./indexes.js";
+import { V1DatabaseSchemaClient } from "./database-schema.js";
+import { V1Databases } from "./catalog.js";
+import { V1SavedQueries } from "./saved-queries.js";
+import { V1ProjectUsageClient } from "./usage.js";
+import { V1BackupDestinationClient } from "./backups.js";
+import { V1Health } from "./system.js";
+import { V1Platform } from "./system.js";
+import type { JsonInput } from "./json.js";
 import type { V1Path } from "./filter.js";
 import type { V1Durability } from "./decode.js";

package/types/v1/transport.d.ts

@@ -31,8 +31,13 @@ export class V1Transport {
      * @returns {JsonValue | undefined}
      */
     static "__#private@#decodeJson"(response: Response, text: string): JsonValue | undefined;
-    /** @param {TerraBaseV1ClientConfig} config */
-    constructor(config: TerraBaseV1ClientConfig);
+    /** @param {TerraBaseV1ClientConfig | (import("./system.js").TerraBaseSystemClientConfig & { project?: undefined; endpointResolver?: undefined })} config */
+    constructor(config: TerraBaseV1ClientConfig | (import("./system.js").TerraBaseSystemClientConfig & {
+        project?: undefined;
+        endpointResolver?: undefined;
+    }));
+    /** Internal credential lifetime metadata; never exposes the bearer value. */
+    get hasTokenProvider(): boolean;
     /**
      * @param {V1Operation} operation
      * @param {Readonly<Record<string, string>>} params
@@ -44,21 +49,24 @@ export class V1Transport {
      * Reads a response body as UTF-8 text within the response byte bound. A
      * connection failure while reading is a BodyTransportError.
      * @param {Response} response
+     * @param {AbortSignal | undefined} [signal]
      * @returns {Promise<string>}
      */
-    readText(response: Response): Promise<string>;
+    readText(response: Response, signal?: AbortSignal | undefined): Promise<string>;
     /**
      * Parses a JSON response body exactly.
      * @param {Response} response
+     * @param {AbortSignal | undefined} [signal]
      * @returns {Promise<JsonValue | undefined>}
      */
-    readJson(response: Response): Promise<JsonValue | undefined>;
+    readJson(response: Response, signal?: AbortSignal | undefined): Promise<JsonValue | undefined>;
     /**
      * Converts a non-success response to a TerraBaseV1Error.
      * @param {Response} response
+     * @param {AbortSignal | undefined} [signal]
      * @returns {Promise<TerraBaseV1Error>}
      */
-    error(response: Response): Promise<TerraBaseV1Error>;
+    error(response: Response, signal?: AbortSignal | undefined): Promise<TerraBaseV1Error>;
     /**
      * Calls only a named producer route. Redirects and failed mutations are never replayed.
      * @param {V1Operation} operation
@@ -67,17 +75,28 @@ export class V1Transport {
      * @returns {Promise<V1CallResult>}
      */
     call(operation: V1Operation, params: Readonly<Record<string, string>>, options?: V1CallOptions): Promise<V1CallResult>;
+    /**
+     * @param {"streamDatabaseChanges" | "exportDatabase"} operation
+     * @param {Readonly<Record<string, string>>} params
+     * @param {V1CallOptions} [options]
+     * @returns {Promise<Response>}
+     */
+    openStream(operation: "streamDatabaseChanges" | "exportDatabase", params: Readonly<Record<string, string>>, options?: V1CallOptions): Promise<Response>;
     #private;
 }
 /**
  * Resolver input contains no credential. A successful URL is cached for this client/database.
  */
 export type V1EndpointContext = {
-    readonly project: string;
-    readonly database: string;
+    readonly project: string | undefined;
+    readonly database?: string | undefined;
     readonly signal?: AbortSignal | undefined;
 };
 export type V1EndpointResolver = (context: V1EndpointContext) => string | Promise<string>;
+/**
+ * A fresh access token for each authenticated request, including stream reconnects.
+ */
+export type V1TokenProvider = () => string | Promise<string>;
 /**
  * Project-scoped C# Documents API client. Supply exactly one of baseUrl or endpointResolver.
  * URLs must use HTTPS or loopback HTTP. Mutations are never automatically replayed.
@@ -85,9 +104,9 @@ export type V1EndpointResolver = (context: V1EndpointContext) => string | Promis
 export type TerraBaseV1ClientConfig = {
     project: string;
     /**
-     * A ts-auth project access JWT (or a legacy C# tb_ key); held privately.
+     * An access JWT (or a legacy C# tb_ key), or a provider resolved per authenticated request; held privately. Browser callers must use end-user tokens, never project credentials.
      */
-    token: string;
+    token: string | V1TokenProvider;
     baseUrl?: string | undefined;
     endpointResolver?: V1EndpointResolver | undefined;
     fetch?: FetchLike | undefined;
@@ -97,7 +116,7 @@ export type TerraBaseV1ClientConfig = {
     maxResponseBytes?: number | undefined;
 };
 export type V1CallOptions = {
-    body?: string;
+    body?: string | Uint8Array;
     contentType?: string;
     /**
      * Contract headers only (If-Match, If-None-Match).
@@ -105,6 +124,10 @@ export type V1CallOptions = {
     headers?: Readonly<Record<string, string>>;
     query?: URLSearchParams | undefined;
     signal?: AbortSignal | undefined;
+    /**
+     * Authenticated shape epoch keys must bypass caches.
+     */
+    cache?: "no-store" | undefined;
 };
 export type V1CallResult = {
     status: number;

package/types/v1/usage.d.ts

@@ -0,0 +1,171 @@
+/** Project and database usage retain the producer's separate response envelopes. */
+export class V1ProjectUsageClient {
+    /** @param {V1Transport} transport */
+    constructor(transport: V1Transport);
+    /** @param {V1UsageRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<V1ProjectUsage>} */
+    usage(request?: V1UsageRequest, options?: V1RequestOptions): Promise<V1ProjectUsage>;
+    /** @param {V1AnalyticsRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<V1Analytics>} */
+    analytics(request?: V1AnalyticsRequest, options?: V1RequestOptions): Promise<V1Analytics>;
+    /** @param {V1AnalyticsRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<V1Replication>} */
+    replication(request?: V1AnalyticsRequest, options?: V1RequestOptions): Promise<V1Replication>;
+    #private;
+}
+export class V1DatabaseUsageClient {
+    /** @param {V1Transport} transport @param {string} database */
+    constructor(transport: V1Transport, database: string);
+    /** @param {V1UsageRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<V1DatabaseUsage>} */
+    usage(request?: V1UsageRequest, options?: V1RequestOptions): Promise<V1DatabaseUsage>;
+    /** @param {Omit<V1AnalyticsRequest, "database">} [request] @param {V1RequestOptions} [options] @returns {Promise<V1Analytics>} */
+    analytics(request?: Omit<V1AnalyticsRequest, "database">, options?: V1RequestOptions): Promise<V1Analytics>;
+    /** @param {Omit<V1AnalyticsRequest, "database">} [request] @param {V1RequestOptions} [options] @returns {Promise<V1Replication>} */
+    replication(request?: Omit<V1AnalyticsRequest, "database">, options?: V1RequestOptions): Promise<V1Replication>;
+    #private;
+}
+export type V1DatabaseUsage = ReturnType<typeof databaseUsage>;
+export type V1ProjectUsage = ReturnType<typeof projectUsage>;
+export type V1Analytics = ReturnType<typeof analytics>;
+export type V1Replication = ReturnType<typeof replication>;
+export type V1UsageRequest = {
+    readonly granularity?: "hour" | "day";
+    readonly from?: string;
+    readonly to?: string;
+};
+export type V1AnalyticsRequest = {
+    readonly range?: "1h" | "24h" | "7d" | "30d";
+    readonly database?: string;
+    readonly region?: string;
+};
+import type { V1RequestOptions } from "./terrabase-v1.js";
+import type { V1Transport } from "./transport.js";
+declare const databaseUsage: import("./management-decode.js").Decoder<Readonly<{
+    databaseId: string;
+    storageBytes: number | import("./json.js").ExactDecimal;
+    logicalBytes: number | import("./json.js").ExactDecimal;
+    collections: number | import("./json.js").ExactDecimal;
+    documents: number | import("./json.js").ExactDecimal;
+    reads: number | import("./json.js").ExactDecimal;
+    writes: number | import("./json.js").ExactDecimal;
+    period: Readonly<{
+        from: string;
+        to: string;
+        granularity: string;
+        reads: number | import("./json.js").ExactDecimal;
+        writes: number | import("./json.js").ExactDecimal;
+    }>;
+    series: readonly Readonly<{
+        start: string;
+        reads: number | import("./json.js").ExactDecimal;
+        writes: number | import("./json.js").ExactDecimal;
+    }>[];
+}>>;
+declare const projectUsage: import("./management-decode.js").Decoder<Readonly<{
+    projectId: string;
+    databases: number | import("./json.js").ExactDecimal;
+    storageBytes: number | import("./json.js").ExactDecimal;
+    logicalBytes: number | import("./json.js").ExactDecimal;
+    documents: number | import("./json.js").ExactDecimal;
+    reads: number | import("./json.js").ExactDecimal;
+    writes: number | import("./json.js").ExactDecimal;
+    period: Readonly<{
+        from: string;
+        to: string;
+        granularity: string;
+        reads: number | import("./json.js").ExactDecimal;
+        writes: number | import("./json.js").ExactDecimal;
+    }>;
+    series: readonly Readonly<{
+        start: string;
+        reads: number | import("./json.js").ExactDecimal;
+        writes: number | import("./json.js").ExactDecimal;
+    }>[];
+    items: readonly Readonly<{
+        databaseId: string;
+        storageBytes: number | import("./json.js").ExactDecimal;
+        logicalBytes: number | import("./json.js").ExactDecimal;
+        collections: number | import("./json.js").ExactDecimal;
+        documents: number | import("./json.js").ExactDecimal;
+        reads: number | import("./json.js").ExactDecimal;
+        writes: number | import("./json.js").ExactDecimal;
+        period: Readonly<{
+            from: string;
+            to: string;
+            granularity: string;
+            reads: number | import("./json.js").ExactDecimal;
+            writes: number | import("./json.js").ExactDecimal;
+        }>;
+        series: readonly Readonly<{
+            start: string;
+            reads: number | import("./json.js").ExactDecimal;
+            writes: number | import("./json.js").ExactDecimal;
+        }>[];
+    }>[];
+}>>;
+declare const analytics: import("./management-decode.js").Decoder<Readonly<{
+    projectId: string;
+    range: string;
+    from: string;
+    to: string;
+    bucketSeconds: number | import("./json.js").ExactDecimal;
+    items: readonly Readonly<{
+        databaseId: string;
+        databaseName: string;
+        region: string;
+        series: readonly Readonly<{
+            start: string;
+            requests: Readonly<Record<string, number | import("./json.js").ExactDecimal>>;
+            operations: Readonly<Record<string, number | import("./json.js").ExactDecimal>>;
+            errors: number | import("./json.js").ExactDecimal;
+            latency: Readonly<{
+                p50Ms: /*elided*/ any;
+                p95Ms: /*elided*/ any;
+                p99Ms: /*elided*/ any;
+            }>;
+            storageBytes: number | import("./json.js").ExactDecimal | null;
+            clientBandwidth: Readonly<{
+                bytesSent: /*elided*/ any;
+                bytesReceived: /*elided*/ any;
+            }>;
+            replicationBandwidth: Readonly<{
+                bytesSent: /*elided*/ any;
+                bytesReceived: /*elided*/ any;
+            }>;
+        }>[];
+    }>[];
+}>>;
+declare const replication: import("./management-decode.js").Decoder<Readonly<{
+    projectId: string;
+    range: string;
+    from: string;
+    to: string;
+    bucketSeconds: number | import("./json.js").ExactDecimal;
+    items: readonly Readonly<{
+        databaseId: string;
+        databaseName: string;
+        region: string;
+        status: string;
+        replicatedOps: number | import("./json.js").ExactDecimal;
+        lagMs: number | import("./json.js").ExactDecimal | null;
+        divergence: boolean | null;
+        convergenceMs: number | import("./json.js").ExactDecimal | null;
+        lastApplied: string | null;
+        bandwidth: readonly Readonly<{
+            sourceRegion: string;
+            destinationRegion: string;
+            kind: string;
+            bytesSent: number | import("./json.js").ExactDecimal;
+            bytesReceived: number | import("./json.js").ExactDecimal;
+        }>[];
+        series: readonly Readonly<{
+            start: string;
+            replicatedOps: number | import("./json.js").ExactDecimal;
+            bandwidth: readonly Readonly<{
+                sourceRegion: /*elided*/ any;
+                destinationRegion: /*elided*/ any;
+                kind: /*elided*/ any;
+                bytesSent: /*elided*/ any;
+                bytesReceived: /*elided*/ any;
+            }>[];
+        }>[];
+    }>[];
+}>>;
+export {};