@terrascale/sdk 0.0.4 → 0.0.6

package/types/v1/export.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Streams every live document of a database as NDJSON, in collection then id order, from one read snapshot.
+ * A stream that ends inside a line is incomplete and throws; resume with `after` set to the last document received.
+ * @param {V1Transport} transport
+ * @param {string} database
+ * @param {V1ExportOptions} [options]
+ * @returns {AsyncGenerator<V1ExportedDocument, void, undefined>}
+ */
+export function exportDocuments(transport: V1Transport, database: string, options?: V1ExportOptions): AsyncGenerator<V1ExportedDocument, void, undefined>;
+export type V1ExportedDocument = {
+    readonly collection: string;
+    readonly id: string;
+    readonly document: JsonObject;
+};
+export type V1ExportOptions = {
+    /**
+     * Resume after this document; the resumed part reads a new snapshot.
+     */
+    after?: {
+        readonly collection: string;
+        readonly id: string;
+    } | undefined;
+    signal?: AbortSignal | undefined;
+};
+import type { V1Transport } from "./transport.js";
+import type { JsonObject } from "./json.js";

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

@@ -1,3 +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";
+export type ManagementOperation = "getShapeManifest" | "exportDatabase" | "executeSql" | "putCollectionTtl" | "getCollectionTtl" | "deleteCollectionTtl" | "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" | "createChangeWebhook" | "listChangeWebhooks" | "deleteChangeWebhook" | "listChangeWebhookDeliveries";

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

@@ -9,7 +9,7 @@ export function decodeFreeShapePage(value: import("./json.js").JsonValue | undef
  */
 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.
+ * Reuse keys only for static credentials; callback tokens authorize every decrypt with no-store.
  * @param {V1Transport} transport @param {Readonly<Record<string,string>>} params
  * @param {Uint8Array} bytes @param {V1SealedShapePosition} position @param {AbortSignal | undefined} signal
  * @returns {Promise<V1ShapePage>}

package/types/v1/sql-execute.d.ts

@@ -0,0 +1,61 @@
+/** @param {string} sql @param {V1SqlArguments | undefined} args @returns {V1SqlStatement} */
+export function sqlStatement(sql: string, args: V1SqlArguments | undefined): V1SqlStatement;
+/**
+ * Runs 1 to 256 statements as one transaction: all commit or none do. BEGIN, COMMIT and ROLLBACK are refused.
+ * A refused statement throws SqlError with its index.
+ * @param {V1Transport} transport
+ * @param {string} database
+ * @param {readonly (string | V1SqlStatement)[]} statements
+ * @param {V1RequestOptions} [options]
+ * @returns {Promise<readonly V1SqlExecuteResult[]>}
+ */
+export function executeSql(transport: V1Transport, database: string, statements: readonly (string | V1SqlStatement)[], options?: V1RequestOptions): Promise<readonly V1SqlExecuteResult[]>;
+/**
+ * Rows as objects keyed by column name; a later duplicate column name wins.
+ * @template [T=Record<string, V1SqlValue>]
+ * @param {V1SqlExecuteResult} result
+ * @returns {T[]}
+ */
+export function sqlRowObjects<T = Record<string, V1SqlValue>>(result: V1SqlExecuteResult): T[];
+/**
+ * An argument: null, a finite number, an int64 `bigint` or ExactDecimal, a boolean (stored as 1 or 0) or a string.
+ */
+export type V1SqlArgument = null | boolean | number | bigint | ExactDecimal | string;
+/**
+ * Positional array, or named values keyed without their `:`, `@` or `$` prefix.
+ */
+export type V1SqlArguments = readonly V1SqlArgument[] | Readonly<Record<string, V1SqlArgument>>;
+export type V1SqlStatement = {
+    sql: string;
+    /**
+     * Positional arguments.
+     */
+    args?: readonly V1SqlArgument[] | undefined;
+    /**
+     * Named arguments, keys without their prefix.
+     */
+    named?: Readonly<Record<string, V1SqlArgument>> | undefined;
+};
+/**
+ * A result value. Integers beyond 2^53 decode as ExactDecimal, keeping every digit; `BigInt(String(value))` converts one.
+ */
+export type V1SqlValue = null | number | ExactDecimal | string;
+/**
+ * A column; `decltype` is null for an expression.
+ */
+export type V1SqlColumn = {
+    readonly name: string;
+    readonly decltype: string | null;
+};
+export type V1SqlExecuteResult = {
+    columns: readonly V1SqlColumn[];
+    /**
+     * One value per column.
+     */
+    rows: readonly (readonly V1SqlValue[])[];
+    rowsAffected: number;
+    lastInsertRowid: number | ExactDecimal | null;
+};
+import type { V1Transport } from "./transport.js";
+import type { V1RequestOptions } from "./terrabase-v1.js";
+import { ExactDecimal } from "./json.js";

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

@@ -22,6 +22,8 @@ export class V1Collection {
      * @param {string} name
      */
     constructor(transport: V1Transport, database: string, name: string);
+    /** @type {V1ChangeWebhooks} */
+    webhooks: V1ChangeWebhooks;
     /** @type {string} */
     name: string;
     /** @type {string} */
@@ -82,6 +84,15 @@ export class V1Collection {
     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.
@@ -284,8 +295,36 @@ export class V1Database {
     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>;
+    /**
+     * Runs one relational SQL statement as its own transaction. Reads need documents:read; writes and DDL need documents:write.
+     * @param {string} sql
+     * @param {import("./sql-execute.js").V1SqlArguments} [args] Positional array, or named values keyed without their prefix.
+     * @param {V1RequestOptions} [options]
+     * @returns {Promise<import("./sql-execute.js").V1SqlExecuteResult>}
+     */
+    execute(sql: string, args?: import("./sql-execute.js").V1SqlArguments, options?: V1RequestOptions): Promise<import("./sql-execute.js").V1SqlExecuteResult>;
+    /**
+     * Runs one statement and returns its rows as objects keyed by column name.
+     * @template [T=Record<string, import("./sql-execute.js").V1SqlValue>]
+     * @param {string} sql
+     * @param {import("./sql-execute.js").V1SqlArguments} [args]
+     * @param {V1RequestOptions} [options]
+     * @returns {Promise<T[]>}
+     */
+    query<T = Record<string, import("./sql-execute.js").V1SqlValue>>(sql: string, args?: import("./sql-execute.js").V1SqlArguments, options?: V1RequestOptions): Promise<T[]>;
+    /**
+     * Runs 1 to 256 statements as one transaction: all commit or none do. A refused statement throws SqlError.
+     * @param {readonly (string | import("./sql-execute.js").V1SqlStatement)[]} statements
+     * @param {V1RequestOptions} [options]
+     */
+    batch(statements: readonly (string | import("./sql-execute.js").V1SqlStatement)[], options?: V1RequestOptions): Promise<readonly import("./sql-execute.js").V1SqlExecuteResult[]>;
     /** @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;
 }
 /**
@@ -385,17 +424,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;
     /**
@@ -458,6 +508,7 @@ export type V1TransactionResult = {
 };
 import type { JsonValue } from "./json.js";
 import type { TerraBaseV1ClientConfig } from "./transport.js";
+import { V1ChangeWebhooks } from "./change-webhooks.js";
 import type { V1Document } from "./decode.js";
 import type { JsonInputObject } from "./json.js";
 import type { V1WriteResult } from "./decode.js";

package/types/v1/transport.d.ts

@@ -36,6 +36,8 @@ export class V1Transport {
         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
@@ -74,12 +76,12 @@ export class V1Transport {
      */
     call(operation: V1Operation, params: Readonly<Record<string, string>>, options?: V1CallOptions): Promise<V1CallResult>;
     /**
-     * @param {"streamDatabaseChanges"} operation
+     * @param {"streamDatabaseChanges" | "exportDatabase"} operation
      * @param {Readonly<Record<string, string>>} params
      * @param {V1CallOptions} [options]
      * @returns {Promise<Response>}
      */
-    openStream(operation: "streamDatabaseChanges", params: Readonly<Record<string, string>>, options?: V1CallOptions): Promise<Response>;
+    openStream(operation: "streamDatabaseChanges" | "exportDatabase", params: Readonly<Record<string, string>>, options?: V1CallOptions): Promise<Response>;
     #private;
 }
 /**
@@ -91,6 +93,10 @@ export type V1EndpointContext = {
     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.
@@ -98,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;