@terrascale/sdk 0.0.0-stage → 0.0.2

package/types/local/legacy-client.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @param {TerraBaseClientConfig} config
+ * @returns {TerraBaseClient}
+ */
+export function createTerraBaseClient(config: TerraBaseClientConfig): TerraBaseClient;
+/** Current scoped document client. All mutations are server commits in one declared shard. */
+export class TerraBaseClient {
+    /** @param {TerraBaseClientConfig} config */
+    constructor(config: TerraBaseClientConfig);
+    /** @returns {DatabaseScope} */
+    get scope(): DatabaseScope;
+    /**
+     * @param {string} collection
+     * @param {string} document
+     * @param {DatabaseRequestOptions} [options]
+     * @returns {Promise<DatabaseResult<DatabasePoint>>}
+     */
+    read(collection: string, document: string, options?: DatabaseRequestOptions): Promise<DatabaseResult<DatabasePoint>>;
+    /**
+     * @param {string} collection
+     * @param {DatabaseQuery} query
+     * @param {DatabaseRequestOptions} [options]
+     * @returns {Promise<DatabaseResult<DatabaseQueryPage>>}
+     */
+    query(collection: string, query: DatabaseQuery, options?: DatabaseRequestOptions): Promise<DatabaseResult<DatabaseQueryPage>>;
+    /**
+     * @param {string} collection
+     * @param {DatabaseSubscriptionRequest} request
+     * @param {DatabaseRequestOptions} [options]
+     * @returns {Promise<DatabaseResult<DatabaseSubscriptionResponse>>}
+     */
+    subscription(collection: string, request: DatabaseSubscriptionRequest, options?: DatabaseRequestOptions): Promise<DatabaseResult<DatabaseSubscriptionResponse>>;
+    /**
+     * Prepare once and retain this identity for exact retry and durable status resolution.
+     * @param {DatabaseCommit} commit
+     * @returns {Promise<PreparedDatabaseCommit>}
+     */
+    prepareCommit(commit: DatabaseCommit): Promise<PreparedDatabaseCommit>;
+    /**
+     * @param {PreparedDatabaseCommit} prepared
+     * @param {DatabaseRequestOptions} [options]
+     * @returns {Promise<DatabaseResult<DatabaseCommitReceipt>>}
+     */
+    commit(prepared: PreparedDatabaseCommit, options?: DatabaseRequestOptions): Promise<DatabaseResult<DatabaseCommitReceipt>>;
+    /**
+     * Unknown, pending and expired outcomes remain unresolved; an absent document proves no abort.
+     * @param {DatabaseTransactionIdentity} identity
+     * @param {DatabaseRequestOptions} [options]
+     * @returns {Promise<DatabaseResult<DatabaseTransactionStatus>>}
+     */
+    transactionStatus(identity: DatabaseTransactionIdentity, options?: DatabaseRequestOptions): Promise<DatabaseResult<DatabaseTransactionStatus>>;
+    #private;
+}
+/**
+ * Internal options for the deprecated local emulator. Remote origins are refused.
+ */
+export type TerraBaseClientConfig = DatabaseScope & {
+    readonly apiKey: string | (() => string | Promise<string>);
+    readonly endpoint?: string;
+    readonly discoveryTimeoutMs?: number;
+    readonly requestTimeoutMs?: number;
+    readonly fetch?: FetchLike;
+};
+export type DatabaseRequestOptions = {
+    readonly signal?: AbortSignal;
+};
+export type PreparedDatabaseCommit = DatabaseTransactionIdentity & {
+    readonly [preparedBrand]: true;
+};
+import type { DatabaseScope } from "../database-types.js";
+import type { DatabasePoint } from "../database-types.js";
+import type { DatabaseResult } from "../database-types.js";
+import type { DatabaseQuery } from "../database-types.js";
+import type { DatabaseQueryPage } from "../database-types.js";
+import type { DatabaseSubscriptionRequest } from "../database-types.js";
+import type { DatabaseSubscriptionResponse } from "../database-types.js";
+import type { DatabaseCommit } from "../database-types.js";
+import type { DatabaseCommitReceipt } from "../database-types.js";
+import type { DatabaseTransactionIdentity } from "../database-types.js";
+import type { DatabaseTransactionStatus } from "../database-types.js";
+import type { FetchLike } from "../config.js";
+/**
+ * Internal options for the deprecated local emulator. Remote origins are refused.
+ * @typedef {DatabaseScope & {
+ *   readonly apiKey: string | (() => string | Promise<string>);
+ *   readonly endpoint?: string;
+ *   readonly discoveryTimeoutMs?: number;
+ *   readonly requestTimeoutMs?: number;
+ *   readonly fetch?: FetchLike;
+ * }} TerraBaseClientConfig
+ */
+/** @typedef {{ readonly signal?: AbortSignal }} DatabaseRequestOptions */
+declare const preparedBrand: unique symbol;
+export {};

package/types/local/router.d.ts

@@ -0,0 +1,66 @@
+/** Development implementation of the admitted native grammar, never producer qualification. */
+export class TerraScaleLocalRouter {
+    /**
+     * @param {TerraScaleSqliteStore} store
+     * @param {DatabaseScope} scope
+     * @param {{
+     *   readonly authentication: LocalAuthenticationMode;
+     *   readonly bearerToken?: string;
+     * }} options
+     */
+    constructor(store: TerraScaleSqliteStore, scope: DatabaseScope, options: {
+        readonly authentication: LocalAuthenticationMode;
+        readonly bearerToken?: string;
+    });
+    get authority(): Readonly<{
+        mode: "single_writer";
+        generation: 1n;
+        writer: {
+            readonly replica: string;
+            readonly incarnation: string;
+        };
+    }>;
+    /**
+     * @param {CollectionBinding} binding
+     * @returns {void}
+     */
+    bindCollection(binding: CollectionBinding): void;
+    /**
+     * @readonly
+     * @type {FetchLike}
+     */
+    readonly fetch: FetchLike;
+    /**
+     * @param {Request} request
+     * @returns {Promise<Response>}
+     */
+    handle(request: Request): Promise<Response>;
+    #private;
+}
+export type JsonObject = Record<string, unknown>;
+export type WirePoint = JsonObject;
+export type Change = {
+    readonly sequence: string;
+    readonly entries: readonly {
+        readonly collection: string;
+        readonly document: string;
+        readonly before: WirePoint;
+        readonly after: WirePoint;
+    }[];
+};
+export type Snapshot = {
+    readonly route: string;
+    readonly predicate: string;
+    readonly limit: number;
+    readonly sequence: string;
+    readonly rows: readonly {
+        readonly document: string;
+        readonly point: WirePoint;
+    }[];
+    readonly expires: number;
+};
+import type { CollectionBinding } from "../database-types.js";
+import type { FetchLike } from "../config.js";
+import type { TerraScaleSqliteStore } from "./store.js";
+import type { DatabaseScope } from "../database-types.js";
+import type { LocalAuthenticationMode } from "./context.js";

package/types/local/server.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The local HTTP endpoint exposed by a running server.
+ *
+ * @typedef {Readonly<{
+ *   readonly origin: string;
+ *   readonly host: string;
+ *   readonly port: number;
+ * }>} LocalServerAddress
+ */
+/** @typedef {(request: Request) => Promise<Response>} LocalRequestHandler */
+/** @typedef {Readonly<{ host?: string; port?: number }>} StartOptions */
+/** @typedef {boolean | Readonly<{ allowRemote?: boolean }>} ConstructorOptions */
+/** @typedef {ReturnType<typeof createServer>} ServerLike */
+/**
+ * A small Node-only bridge for handlers that speak the Fetch API.
+ *
+ * The handler is deliberately the sole routing authority. In particular, this
+ * adapter does not reserve a health route (or any other private route).
+ */
+export class TerraScaleLocalHttpServer {
+    /**
+     * @param {LocalRequestHandler} handler
+     * @param {ConstructorOptions} [options]
+     */
+    constructor(handler: LocalRequestHandler, options?: ConstructorOptions);
+    /** @returns {LocalServerAddress | undefined} */
+    get address(): LocalServerAddress | undefined;
+    /**
+     * @param {StartOptions} [options]
+     * @returns {Promise<LocalServerAddress>}
+     */
+    start(options?: StartOptions): Promise<LocalServerAddress>;
+    /** @returns {Promise<void>} */
+    close(): Promise<void>;
+    #private;
+}
+/**
+ * The local HTTP endpoint exposed by a running server.
+ */
+export type LocalServerAddress = Readonly<{
+    readonly origin: string;
+    readonly host: string;
+    readonly port: number;
+}>;
+export type LocalRequestHandler = (request: Request) => Promise<Response>;
+export type StartOptions = Readonly<{
+    host?: string;
+    port?: number;
+}>;
+export type ConstructorOptions = boolean | Readonly<{
+    allowRemote?: boolean;
+}>;
+export type ServerLike = ReturnType<typeof createServer>;
+import { createServer } from "node:http";

package/types/local/store.d.ts

@@ -0,0 +1,106 @@
+/**
+ * A small synchronous JSON record store for Node local adapters.
+ *
+ * This module intentionally imports node:sqlite and must not be used from a
+ * browser bundle. The database handle is kept private so consumers cannot
+ * bypass the store's serialization and transaction invariants.
+ */
+export class TerraScaleSqliteStore {
+    /**
+     * @param {string} databasePath
+     */
+    constructor(databasePath: string);
+    /**
+     * @readonly
+     * @type {string}
+     */
+    readonly databasePath: string;
+    /** @returns {void} */
+    close(): void;
+    /** @returns {void} */
+    reset(): void;
+    /**
+     * @template T
+     * @param {string} namespace
+     * @param {string} scope
+     * @param {string} id
+     * @returns {T | undefined}
+     */
+    get<T>(namespace: string, scope: string, id: string): T | undefined;
+    /**
+     * @template T
+     * @param {string} namespace
+     * @param {string} scope
+     * @returns {T[]}
+     */
+    list<T>(namespace: string, scope: string): T[];
+    /**
+     * @template T
+     * @param {string} namespace
+     * @returns {readonly {
+     *   readonly scope: string;
+     *   readonly id: string;
+     *   readonly value: T;
+     * }[]}
+     */
+    listNamespace<T>(namespace: string): readonly {
+        readonly scope: string;
+        readonly id: string;
+        readonly value: T;
+    }[];
+    /**
+     * @template T
+     * @param {string} namespace
+     * @param {string} scope
+     * @param {string} id
+     * @param {T} value
+     * @returns {void}
+     */
+    put<T>(namespace: string, scope: string, id: string, value: T): void;
+    /**
+     * @param {string} namespace
+     * @param {string} scope
+     * @param {string} id
+     * @returns {boolean}
+     */
+    delete(namespace: string, scope: string, id: string): boolean;
+    /**
+     * @param {string} namespace
+     * @returns {void}
+     */
+    clearNamespace(namespace: string): void;
+    /**
+     * @template T
+     * @param {string} key
+     * @returns {T | undefined}
+     */
+    getMeta<T>(key: string): T | undefined;
+    /**
+     * @template T
+     * @param {string} key
+     * @param {T} value
+     * @returns {void}
+     */
+    setMeta<T>(key: string, value: T): void;
+    /**
+     * Serialize local native requests and async auth callbacks on this connection.
+     *
+     * @template T
+     * @param {() => Promise<T> | T} work
+     * @returns {Promise<T>}
+     */
+    exclusive<T>(work: () => Promise<T> | T): Promise<T>;
+    /**
+     * @template T
+     * @param {() => Promise<T>} work
+     * @returns {Promise<T>}
+     */
+    transactionAsync<T>(work: () => Promise<T>): Promise<T>;
+    /**
+     * @template T
+     * @param {() => T} work
+     * @returns {T}
+     */
+    transaction<T>(work: () => T): T;
+    #private;
+}

package/types/local/test-environment.d.ts

@@ -0,0 +1,25 @@
+/** @import { TerraScaleSqliteRuntimeOptions } from "./index.js" */
+/** @import { DatabaseCommit, DatabaseField, DatabasePoint } from "../database-types.js" */
+/**
+ * @param {Omit<TerraScaleSqliteRuntimeOptions, "sqlite">} [options]
+ */
+export function localFixture(options?: Omit<TerraScaleSqliteRuntimeOptions, "sqlite">): Promise<{
+    runtime: import("./index.js").TerraScaleSqliteRuntime;
+    client: import("./legacy-client.js").TerraBaseClient;
+    collection: `${string}-${string}-${string}-${string}-${string}`;
+    binding: {
+        collection: `${string}-${string}-${string}-${string}-${string}`;
+        schema_generation: bigint;
+        schema_digest: string;
+    };
+    directory: string;
+    databasePath: string;
+    commit: (document: string, fields: readonly DatabaseField[], point?: DatabasePoint) => DatabaseCommit;
+    close: () => Promise<void>;
+}>;
+/** Local development tests never relax CI/deployment/qualification guards. */
+export const localSqliteUnitTestsAllowed: boolean;
+import type { TerraScaleSqliteRuntimeOptions } from "./index.js";
+import type { DatabaseField } from "../database-types.js";
+import type { DatabasePoint } from "../database-types.js";
+import type { DatabaseCommit } from "../database-types.js";

package/types/management-contracts.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @param {TerraScaleBlockedCapability} capability
+ * @returns {never}
+ */
+export function requireTerraScaleCapability(capability: TerraScaleBlockedCapability): never;
+/** Required capabilities whose producer/runtime admission is still open. */
+export const terraScaleReleaseBlockers: Readonly<{
+    management: Readonly<{
+        code: "management_contract_unavailable";
+        owner: "C06/C07 regional management service";
+        required: readonly string[];
+    }>;
+    betterAuth: Readonly<{
+        code: "security_authority_unavailable";
+        owner: "native single-writer security admission and C06/C07";
+        required: readonly string[];
+    }>;
+    qualification: Readonly<{
+        code: "runtime_qualification_unavailable";
+        owner: "real producer allocation and deployed customer application";
+        required: readonly string[];
+    }>;
+}>;
+/** @typedef {keyof typeof terraScaleReleaseBlockers} TerraScaleBlockedCapability */
+export class TerraScaleCapabilityUnavailableError extends Error {
+    /** @param {TerraScaleBlockedCapability} capability */
+    constructor(capability: TerraScaleBlockedCapability);
+    /**
+     * @readonly
+     * @type {string}
+     */
+    readonly code: string;
+    /**
+     * @readonly
+     * @type {TerraScaleBlockedCapability}
+     */
+    readonly capability: TerraScaleBlockedCapability;
+    /**
+     * @readonly
+     * @type {readonly string[]}
+     */
+    readonly required: readonly string[];
+}
+export type TerraScaleBlockedCapability = keyof typeof terraScaleReleaseBlockers;

package/types/management.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Required public management support remains closed until C06/C07 route admission.
+ * @returns {never}
+ */
+export function requireTerraScaleManagement(): never;
+export { terraScaleReleaseBlockers, TerraScaleCapabilityUnavailableError } from "./management-contracts.js";

package/types/native-origin.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function requireNativeRegion(value: unknown): string;
+/**
+ * @param {unknown} code
+ * @returns {string}
+ */
+export function nativeRegionalOrigin(code: unknown): string;
+/**
+ * Hosted identity refuses database API origins, without using native admission.
+ * @param {string} hostname
+ * @returns {boolean}
+ */
+export function isDataApiHostname(hostname: string): boolean;
+/**
+ * @param {string} raw
+ * @returns {string}
+ */
+export function nativeServiceOrigin(raw: string): string;
+/** Internal admission policy shared by native clients and qualification configuration. */
+export const terraScaleServiceDomain: "terrascale.tech";

package/types/postgres.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Validate and clone a builder descriptor without converting or interpolating values.
+ *
+ * @param {string} statement
+ * @param {readonly unknown[]} [parameters]
+ * @returns {PostgresBoundQuery}
+ */
+export function postgresQuery(statement: string, parameters?: readonly unknown[]): PostgresBoundQuery;
+/** @typedef {bigint | string} PostgresParameter */
+/**
+ * @typedef {{
+ *   readonly statement: string;
+ *   readonly parameters: readonly unknown[];
+ * }} PostgresQuery
+ */
+/**
+ * @typedef {{
+ *   readonly statement: string;
+ *   readonly parameters: readonly PostgresParameter[];
+ * }} PostgresBoundQuery
+ */
+/**
+ * @typedef {{
+ *   readonly host: string;
+ *   readonly port: number;
+ *   readonly tlsServerName: string;
+ *   readonly caCertificatePem: string;
+ *   readonly database: string;
+ *   readonly keyId: string;
+ *   readonly password: string;
+ *   readonly connectTimeoutMs?: number;
+ * }} PostgresConfig
+ */
+/**
+ * @typedef {{
+ *   readonly name: string;
+ *   readonly oid: 20 | 25;
+ * }} PostgresColumn
+ */
+/**
+ * @typedef {{
+ *   readonly command: string;
+ *   readonly affectedRows: number;
+ *   readonly columns: readonly PostgresColumn[];
+ *   readonly rows: readonly (readonly PostgresParameter[])[];
+ * }} PostgresResult
+ */
+/** Diagnostics retain SQLSTATE, but never driver messages, SQL or passwords. */
+export class PostgresError extends Error {
+    /**
+     * @param {"configuration" | "query" | "connection" | "database" | "protocol"} kind
+     * @param {string} [sqlState]
+     */
+    constructor(kind: "configuration" | "query" | "connection" | "database" | "protocol", sqlState?: string);
+    /**
+     * @override
+     * @readonly
+     */
+    override readonly name: "PostgresError";
+    /**
+     * @readonly
+     * @type {"configuration" | "query" | "connection" | "database" | "protocol"}
+     */
+    readonly kind: "configuration" | "query" | "connection" | "database" | "protocol";
+    /**
+     * @readonly
+     * @type {string | undefined}
+     */
+    readonly sqlState: string | undefined;
+}
+/** One driver connection; no automatic reconnect, mutation retry or callback replay. */
+/** @deprecated The C# TerraBase has no PostgreSQL listener. */
+export class PostgresClient {
+    /**
+     * @param {PostgresConfig} input
+     * @returns {Promise<PostgresClient>}
+     */
+    static connect(input: PostgresConfig): Promise<PostgresClient>;
+    /**
+     * @private
+     * @param {DriverClient} driver
+     * @param {typeof DatabaseError} databaseError
+     */
+    private constructor();
+    /**
+     * @param {PostgresQuery} input
+     * @returns {Promise<PostgresResult>}
+     */
+    query(input: PostgresQuery): Promise<PostgresResult>;
+    /**
+     * @returns {Promise<void>}
+     */
+    close(): Promise<void>;
+    #private;
+}
+export type PostgresParameter = bigint | string;
+export type PostgresQuery = {
+    readonly statement: string;
+    readonly parameters: readonly unknown[];
+};
+export type PostgresBoundQuery = {
+    readonly statement: string;
+    readonly parameters: readonly PostgresParameter[];
+};
+export type PostgresConfig = {
+    readonly host: string;
+    readonly port: number;
+    readonly tlsServerName: string;
+    readonly caCertificatePem: string;
+    readonly database: string;
+    readonly keyId: string;
+    readonly password: string;
+    readonly connectTimeoutMs?: number;
+};
+export type PostgresColumn = {
+    readonly name: string;
+    readonly oid: 20 | 25;
+};
+export type PostgresResult = {
+    readonly command: string;
+    readonly affectedRows: number;
+    readonly columns: readonly PostgresColumn[];
+    readonly rows: readonly (readonly PostgresParameter[])[];
+};