@terrascale/sdk 0.0.0-stage → 0.0.2

package/types/database-types.d.ts

@@ -0,0 +1,213 @@
+/**
+ * The current TerraBase document protocol uses canonical UUID entity IDs.
+ */
+export type CanonicalUuid = string;
+/**
+ * All 64-bit quantities stay bigint in JavaScript and decimal strings on the wire.
+ */
+export type DatabaseScope = {
+    readonly tenant: CanonicalUuid;
+    readonly database: CanonicalUuid;
+    readonly shard: bigint;
+};
+export type CollectionBinding = {
+    readonly collection: CanonicalUuid;
+    readonly schema_generation: bigint;
+    readonly schema_digest: string;
+};
+export type DatabaseValue = ({
+    readonly type: "null";
+} | {
+    readonly type: "bool";
+    readonly value: boolean;
+} | {
+    readonly type: "i64";
+    readonly value: bigint;
+} | {
+    readonly type: "utf8";
+    readonly value: string;
+} | {
+    readonly type: "bytes";
+    readonly value: Uint8Array;
+} | {
+    readonly type: "map";
+    readonly fields: readonly DatabaseField[];
+} | {
+    readonly type: "array";
+    readonly items: readonly DatabaseValue[];
+});
+/**
+ * Missing fields are omitted; an explicit null remains a typed null value.
+ */
+export type DatabaseField = {
+    readonly id: number;
+    readonly value: DatabaseValue;
+};
+export type DatabaseObserved = {
+    readonly replica: CanonicalUuid;
+    readonly incarnation: string;
+    readonly sequence: bigint;
+};
+export type DatabaseEvent = DatabaseObserved & {
+    readonly database: CanonicalUuid;
+    readonly shard: bigint;
+};
+export type DatabaseAuthority = ({
+    readonly mode: "leaderless";
+} | {
+    readonly mode: "single_writer";
+    readonly generation: bigint;
+    readonly writer: {
+        readonly replica: CanonicalUuid;
+        readonly incarnation: string;
+    };
+});
+export type DatabaseCondition = ({
+    readonly kind: "none";
+} | {
+    readonly kind: "absent";
+} | {
+    readonly kind: "version";
+    readonly version: string;
+});
+export type DatabaseWriteValue = ({
+    readonly kind: "live";
+    readonly fields: readonly DatabaseField[];
+} | {
+    readonly kind: "tombstone";
+});
+export type DatabaseWrite = CollectionBinding & {
+    readonly document: CanonicalUuid;
+    readonly condition: DatabaseCondition;
+    readonly observed: readonly DatabaseObserved[];
+    readonly value: DatabaseWriteValue;
+};
+export type DatabaseTransactionId = {
+    readonly expires_at_unix_ms: bigint;
+    readonly nonce: string;
+};
+export type DatabaseCommit = {
+    readonly transaction_id: DatabaseTransactionId;
+    readonly authority: DatabaseAuthority;
+    readonly writes: readonly DatabaseWrite[];
+};
+export type DatabaseSibling = Omit<CollectionBinding, "collection"> & {
+    readonly event: DatabaseEvent;
+} & DatabaseWriteValue;
+/**
+ * `state_version`: only a unique live or deleted state carries an atomic condition token.
+ */
+export type DatabasePoint = {
+    readonly version: 1;
+    readonly state: "absent" | "deleted" | "value" | "conflict";
+    readonly state_version: string | null;
+    readonly context: readonly DatabaseObserved[];
+    readonly siblings: readonly DatabaseSibling[];
+};
+export type DatabaseQueryValue = Extract<DatabaseValue, {
+    readonly type: "bool" | "i64" | "utf8" | "bytes";
+}>;
+export type DatabaseQueryPredicate = ({
+    readonly op: "equal" | "less_than" | "less_than_or_equal" | "greater_than" | "greater_than_or_equal";
+    readonly path: readonly number[];
+    readonly value: DatabaseQueryValue;
+} | {
+    readonly op: "is_null" | "is_missing";
+    readonly path: readonly number[];
+});
+export type DatabaseQuery = {
+    readonly predicate: DatabaseQueryPredicate;
+    readonly limit: number;
+    readonly cursor?: string;
+};
+export type DatabaseQueryRow = {
+    readonly document: CanonicalUuid;
+    readonly point: DatabasePoint;
+};
+export type DatabaseQueryPage = {
+    readonly version: 1;
+    readonly rows: readonly DatabaseQueryRow[];
+    readonly next_cursor?: string;
+};
+export type DatabaseCommitReceipt = {
+    readonly version: 1;
+    readonly durability: "local_durable" | "object_durable";
+    readonly transaction_id: DatabaseTransactionId;
+    readonly event: DatabaseEvent;
+    readonly commit_sequence: bigint;
+    readonly effect_digest: string;
+    readonly authority: DatabaseAuthority;
+};
+export type DatabaseTransactionIdentity = {
+    readonly transaction_id: DatabaseTransactionId;
+    readonly authority: DatabaseAuthority;
+    readonly effect_digest: string;
+};
+export type DatabaseTransactionStatus = DatabaseTransactionIdentity & {
+    readonly version: 1;
+} & ({
+    readonly state: "committed";
+    readonly outcome: {
+        readonly receipt: DatabaseCommitReceipt;
+    };
+} | {
+    readonly state: "rejected";
+    readonly outcome: {
+        readonly error: {
+            readonly code: "precondition_failed";
+        };
+    };
+} | {
+    readonly state: "pending" | "unknown" | "expired";
+    readonly outcome: null;
+});
+/**
+ * An uncertain request needs status resolution; it is never an aborted transaction.
+ */
+export type DatabaseResult<T> = ({
+    readonly ok: true;
+    readonly status: number;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: string;
+        readonly status?: number;
+        readonly mutation_outcome?: "rejected" | "uncertain" | "unknown";
+        readonly transaction?: DatabaseTransactionIdentity;
+    };
+});
+export type DatabaseSubscriptionRequest = ({
+    readonly phase: "snapshot";
+    readonly predicate: DatabaseQueryPredicate;
+    readonly limit: number;
+    readonly snapshot_cursor?: string;
+} | {
+    readonly phase: "poll";
+    readonly predicate: DatabaseQueryPredicate;
+    readonly poll_cursor: string;
+});
+export type DatabaseSubscriptionEffect = {
+    readonly document: CanonicalUuid;
+    readonly point: DatabasePoint | null;
+};
+export type DatabaseSubscriptionGroup = {
+    readonly sequence: bigint;
+    readonly effects: readonly DatabaseSubscriptionEffect[];
+};
+export type DatabaseSubscriptionResponse = ({
+    readonly version: 1;
+    readonly phase: "snapshot";
+    readonly rows: readonly DatabaseQueryRow[];
+    readonly next_snapshot_cursor: string;
+} | {
+    readonly version: 1;
+    readonly phase: "snapshot";
+    readonly rows: readonly DatabaseQueryRow[];
+    readonly poll_cursor: string;
+} | {
+    readonly version: 1;
+    readonly phase: "poll";
+    readonly groups: readonly DatabaseSubscriptionGroup[];
+    readonly poll_cursor: string;
+});

package/types/database-view.d.ts

@@ -0,0 +1,184 @@
+/**
+ * @deprecated Retired SQLite/Rust subscriptions; use the C# client.
+ * Native snapshot/poll source shared by React, Svelte and TanStack.
+ * @param {TerraBaseClient} client
+ * @param {DatabaseQueryOptions} options
+ * @returns {DatabaseQuerySource}
+ */
+export function createDatabaseQuery(client: TerraBaseClient, options: DatabaseQueryOptions): DatabaseQuerySource;
+/**
+ * @import { TerraBaseClient } from "./local/legacy-client.js"
+ * @import {
+ *   DatabaseField, DatabasePoint, DatabaseQueryPredicate, DatabaseQueryRow,
+ *   DatabaseResult, DatabaseScope, DatabaseSubscriptionRequest,
+ *   DatabaseSubscriptionResponse, DatabaseValue,
+ * } from "./database-types.js"
+ * @import { ReactiveReset, ReactiveSubscriptionContext } from "./react/core.js"
+ */
+/**
+ * - `limit`: snapshot page size, between 1 and 128.
+ * - `maximumRows`: client memory bound, including all snapshot pages and later inserts.
+ * - `retryLimit`: bounded retries of read transport failures with the identical cursor.
+ * @typedef {{
+ *   readonly collection: string;
+ *   readonly predicate: DatabaseQueryPredicate;
+ *   readonly limit?: number;
+ *   readonly maximumRows?: number;
+ *   readonly pollIntervalMs?: number;
+ *   readonly retryLimit?: number;
+ *   readonly retryDelayMs?: number;
+ * }} DatabaseQueryOptions
+ */
+/**
+ * @typedef {{
+ *   readonly scope: DatabaseScope;
+ *   readonly collection: string;
+ *   readonly predicate: DatabaseQueryPredicate;
+ *   readonly limit: number;
+ * }} DatabaseViewBinding
+ */
+/**
+ * Local generation and server position of one complete authorized cut.
+ * @typedef {{
+ *   readonly generation: number;
+ *   readonly poll_cursor: string;
+ *   readonly sequence?: bigint;
+ * }} DatabaseViewPosition
+ */
+/**
+ * @typedef {{
+ *   readonly rows: readonly DatabaseQueryRow[];
+ *   readonly position: DatabaseViewPosition;
+ * }} DatabaseViewSnapshot
+ */
+/**
+ * `next`: an async consumer can acknowledge publication before the next poll.
+ * @typedef {{
+ *   readonly next: (rows: readonly DatabaseQueryRow[], position: DatabaseViewPosition) => void | Promise<void>;
+ *   readonly error: (error: unknown) => void;
+ *   readonly reset: (reset: ReactiveReset<readonly DatabaseQueryRow[]>) => void;
+ * }} DatabaseQueryCallbacks
+ */
+/**
+ * @typedef {{
+ *   readonly key?: string | readonly unknown[];
+ *   readonly binding: DatabaseViewBinding;
+ *   readonly subscribe: (
+ *     observer: DatabaseQueryCallbacks,
+ *     context: ReactiveSubscriptionContext,
+ *   ) => () => void;
+ * }} DatabaseQuerySource
+ */
+export class DatabaseSubscriptionError extends Error {
+    /**
+     * @param {string} code
+     * @param {Extract<DatabaseResult<never>, { readonly ok: false }>["error"]} [detail]
+     */
+    constructor(code: string, detail?: Extract<DatabaseResult<never>, {
+        readonly ok: false;
+    }>["error"]);
+    /**
+     * @override
+     * @readonly
+     * @type {"DatabaseSubscriptionError"}
+     */
+    override readonly name: "DatabaseSubscriptionError";
+    /**
+     * @readonly
+     * @type {string}
+     */
+    readonly code: string;
+    /**
+     * @readonly
+     * @type {Extract<DatabaseResult<never>, { readonly ok: false }>["error"] | undefined}
+     */
+    readonly detail: Extract<DatabaseResult<never>, {
+        readonly ok: false;
+    }>["error"] | undefined;
+}
+/**
+ * Pure native result reducer. A paged snapshot stays private until its
+ * terminal poll cursor. Poll groups are staged in order and published as one
+ * complete response; invalid input cannot partially replace the prior cut.
+ */
+export class DatabaseSubscriptionView {
+    /**
+     * @param {DatabaseScope} scope
+     * @param {Pick<DatabaseQueryOptions, "collection" | "predicate" | "limit" | "maximumRows">} options
+     */
+    constructor(scope: DatabaseScope, options: Pick<DatabaseQueryOptions, "collection" | "predicate" | "limit" | "maximumRows">);
+    /**
+     * @readonly
+     * @type {DatabaseViewBinding}
+     */
+    readonly binding: DatabaseViewBinding;
+    /** @returns {DatabaseViewSnapshot | undefined} */
+    getSnapshot(): DatabaseViewSnapshot | undefined;
+    /** @returns {DatabaseSubscriptionRequest} */
+    getRequest(): DatabaseSubscriptionRequest;
+    /**
+     * Discard every opaque position; the next request starts a fresh cut.
+     * @returns {void}
+     */
+    restart(): void;
+    /**
+     * @param {DatabaseSubscriptionResponse} response
+     * @returns {DatabaseViewSnapshot | undefined}
+     */
+    apply(response: DatabaseSubscriptionResponse): DatabaseViewSnapshot | undefined;
+    #private;
+}
+/**
+ * - `limit`: snapshot page size, between 1 and 128.
+ * - `maximumRows`: client memory bound, including all snapshot pages and later inserts.
+ * - `retryLimit`: bounded retries of read transport failures with the identical cursor.
+ */
+export type DatabaseQueryOptions = {
+    readonly collection: string;
+    readonly predicate: DatabaseQueryPredicate;
+    readonly limit?: number;
+    readonly maximumRows?: number;
+    readonly pollIntervalMs?: number;
+    readonly retryLimit?: number;
+    readonly retryDelayMs?: number;
+};
+export type DatabaseViewBinding = {
+    readonly scope: DatabaseScope;
+    readonly collection: string;
+    readonly predicate: DatabaseQueryPredicate;
+    readonly limit: number;
+};
+/**
+ * Local generation and server position of one complete authorized cut.
+ */
+export type DatabaseViewPosition = {
+    readonly generation: number;
+    readonly poll_cursor: string;
+    readonly sequence?: bigint;
+};
+export type DatabaseViewSnapshot = {
+    readonly rows: readonly DatabaseQueryRow[];
+    readonly position: DatabaseViewPosition;
+};
+/**
+ * `next`: an async consumer can acknowledge publication before the next poll.
+ */
+export type DatabaseQueryCallbacks = {
+    readonly next: (rows: readonly DatabaseQueryRow[], position: DatabaseViewPosition) => void | Promise<void>;
+    readonly error: (error: unknown) => void;
+    readonly reset: (reset: ReactiveReset<readonly DatabaseQueryRow[]>) => void;
+};
+export type DatabaseQuerySource = {
+    readonly key?: string | readonly unknown[];
+    readonly binding: DatabaseViewBinding;
+    readonly subscribe: (observer: DatabaseQueryCallbacks, context: ReactiveSubscriptionContext) => () => void;
+};
+import type { TerraBaseClient } from "./local/legacy-client.js";
+import type { DatabaseResult } from "./database-types.js";
+import type { DatabaseSubscriptionRequest } from "./database-types.js";
+import type { DatabaseSubscriptionResponse } from "./database-types.js";
+import type { DatabaseScope } from "./database-types.js";
+import type { DatabaseQueryPredicate } from "./database-types.js";
+import type { DatabaseQueryRow } from "./database-types.js";
+import type { ReactiveReset } from "./react/core.js";
+import type { ReactiveSubscriptionContext } from "./react/core.js";

package/types/database.d.ts

@@ -0,0 +1,2 @@
+export type TerraBaseClientConfig = import("./v1/transport.js").TerraBaseV1ClientConfig;
+export { createTerraBaseV1Client as createTerraBaseClient, TerraBaseV1Client as TerraBaseClient } from "./v1/terrabase-v1.js";

package/types/http.d.ts

@@ -0,0 +1,47 @@
+/** Private transport for the named hosted identity and OIDC operations. */
+export class TsAuthHttp {
+    /**
+     * @param {TsAuthRuntimeConfig} config
+     * @param {{ readonly authReverseProxy?: boolean }} [options]
+     */
+    constructor(config: TsAuthRuntimeConfig, options?: {
+        readonly authReverseProxy?: boolean;
+    });
+    /**
+     * @readonly
+     * @type {ResolvedTsAuthRuntimeConfig}
+     */
+    readonly config: ResolvedTsAuthRuntimeConfig;
+    /**
+     * @template TResponse
+     * @template [TBody=unknown]
+     * @param {TsAuthRequest<TBody>} options
+     * @returns {Promise<TerraScaleResult<TResponse>>}
+     */
+    request<TResponse, TBody = unknown>(options: TsAuthRequest<TBody>): Promise<TerraScaleResult<TResponse>>;
+    #private;
+}
+export type ParsedBody = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly errorMessage: string;
+};
+export type TsAuthRouteName = `tsauth.${string}`;
+export type TsAuthHttpMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+export type TsAuthRequest<TBody> = {
+    readonly method: TsAuthHttpMethod;
+    readonly path: string;
+    readonly routeName: TsAuthRouteName;
+    readonly query?: object | undefined;
+    readonly body?: TBody | undefined;
+    readonly formBody?: URLSearchParams | string | undefined;
+    readonly userinfoAccessToken?: string | undefined;
+    readonly resourceIntrospectionBasic?: string | undefined;
+    readonly issuer?: string | undefined;
+    readonly signal?: AbortSignal | undefined;
+};
+import type { ResolvedTsAuthRuntimeConfig } from "./config.js";
+import type { TerraScaleResult } from "./result.js";
+import type { TsAuthRuntimeConfig } from "./config.js";

package/types/index.d.ts

@@ -0,0 +1,43 @@
+export { v1Filter } from "./v1/filter.js";
+export { documentIdFor } from "./v1/ids.js";
+export { ExactDecimal } from "./v1/json.js";
+export { staticBaseUrlResolver } from "./v1/transport.js";
+export type TerraBaseV1ClientConfig = import("./v1/transport.js").TerraBaseV1ClientConfig;
+export type V1RequestOptions = import("./v1/terrabase-v1.js").V1RequestOptions;
+export type V1ReadOptions = import("./v1/terrabase-v1.js").V1ReadOptions;
+export type V1WriteOptions = import("./v1/terrabase-v1.js").V1WriteOptions;
+export type V1CreateOptions = import("./v1/terrabase-v1.js").V1CreateOptions;
+export type V1ConditionalWriteOptions = import("./v1/terrabase-v1.js").V1ConditionalWriteOptions;
+export type V1PatchOp = import("./v1/terrabase-v1.js").V1PatchOp;
+export type V1Patch = import("./v1/terrabase-v1.js").V1Patch;
+export type V1SortKey = import("./v1/terrabase-v1.js").V1SortKey;
+export type V1Query = import("./v1/terrabase-v1.js").V1Query;
+export type V1Count = import("./v1/terrabase-v1.js").V1Count;
+export type V1QueryPage = import("./v1/terrabase-v1.js").V1QueryPage;
+export type V1Precondition = import("./v1/terrabase-v1.js").V1Precondition;
+export type V1TransactionOpResult = import("./v1/terrabase-v1.js").V1TransactionOpResult;
+export type V1CountBounds = import("./v1/terrabase-v1.js").V1CountBounds;
+export type V1TransactionResult = import("./v1/terrabase-v1.js").V1TransactionResult;
+export type V1Document = import("./v1/decode.js").V1Document;
+export type V1WriteResult = import("./v1/decode.js").V1WriteResult;
+export type V1Durability = import("./v1/decode.js").V1Durability;
+export type V1Filter = import("./v1/filter.js").V1Filter;
+export type V1Path = import("./v1/filter.js").V1Path;
+export type V1Scalar = import("./v1/filter.js").V1Scalar;
+export type V1JsonValue = import("./v1/json.js").JsonValue;
+export type V1JsonObject = import("./v1/json.js").JsonObject;
+export type V1JsonInput = import("./v1/json.js").JsonInput;
+export type V1JsonInputObject = import("./v1/json.js").JsonInputObject;
+export type V1ShapeRequest = import("./v1/shapes.js").V1ShapeRequest;
+export type V1ShapeChange = import("./v1/shapes.js").V1ShapeChange;
+export type V1ShapeOp = import("./v1/shapes.js").V1ShapeOp;
+export type TerraBaseClientConfig = import("./v1/transport.js").TerraBaseV1ClientConfig;
+export type V1EndpointContext = import("./v1/transport.js").V1EndpointContext;
+export type V1EndpointResolver = import("./v1/transport.js").V1EndpointResolver;
+export type V1CollectionInfo = import("./v1/terrabase-v1.js").V1CollectionInfo;
+export type V1CollectionPage = import("./v1/terrabase-v1.js").V1CollectionPage;
+export type V1CollectionListOptions = import("./v1/terrabase-v1.js").V1CollectionListOptions;
+export type V1ShapePage = import("./v1/shapes.js").V1ShapePage;
+export { createTerraBaseV1Client as createTerraBaseClient, TerraBaseV1Client as TerraBaseClient, createTerraBaseV1Client, TerraBaseV1Client, V1Database, V1Collection, V1Collections, V1Transaction } from "./v1/terrabase-v1.js";
+export { terraScaleReleaseBlockers, TerraScaleCapabilityUnavailableError } from "./management-contracts.js";
+export { TerraBaseV1Error, V1PreconditionFailedError, V1InvalidKeyError, V1ForbiddenScopeError, V1NotFoundError, V1ErrorCode, isTerraBaseV1Error } from "./v1/errors.js";

package/types/local/authentication.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function normalizeLocalBearerToken(value: unknown): string;
+/**
+ * @param {string | null} authorization
+ * @param {string} expectedToken
+ * @returns {boolean}
+ */
+export function matchesLocalBearerAuthorization(authorization: string | null, expectedToken: string): boolean;

package/types/local/better-auth.d.ts

@@ -0,0 +1,33 @@
+/** @import { CleanedWhere, CustomAdapter, DBAdapter, JoinConfig } from "@better-auth/core/db/adapter" */
+/** @import { BetterAuthOptions } from "@better-auth/core" */
+/** @import { TerraScaleSqliteStore } from "./store.js" */
+/** @typedef {Record<string, unknown>} Row */
+/**
+ * @typedef {Parameters<
+ *   NonNullable<Parameters<typeof createAdapterFactory>[0]["adapter"]>
+ * >[0]} FactoryConfig
+ */
+/**
+ * @typedef {(
+ *   options: BetterAuthOptions,
+ * ) => DBAdapter<BetterAuthOptions>} LocalBetterAuthAdapterFactory
+ */
+/**
+ * Better Auth 1.7.2 over explicitly enabled development SQLite only.
+ *
+ * @param {TerraScaleSqliteStore} store
+ * @returns {LocalBetterAuthAdapterFactory}
+ */
+export function createLocalBetterAuthAdapter(store: TerraScaleSqliteStore): LocalBetterAuthAdapterFactory;
+export class LocalAuthConstraintError extends Error {
+    constructor();
+    /** @readonly */
+    readonly code: "unique_conflict";
+}
+export type Row = Record<string, unknown>;
+export type FactoryConfig = Parameters<NonNullable<Parameters<typeof createAdapterFactory>[0]["adapter"]>>[0];
+export type LocalBetterAuthAdapterFactory = (options: BetterAuthOptions) => DBAdapter<BetterAuthOptions>;
+import type { TerraScaleSqliteStore } from "./store.js";
+import { createAdapterFactory } from "@better-auth/core/db/adapter";
+import type { BetterAuthOptions } from "@better-auth/core";
+import type { DBAdapter } from "@better-auth/core/db/adapter";

package/types/local/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/types/local/context.d.ts

@@ -0,0 +1,14 @@
+/** @typedef {"permissive" | "required"} LocalAuthenticationMode */
+/**
+ * @param {unknown} value
+ * @param {number} [status]
+ * @returns {Response}
+ */
+export function jsonResponse(value: unknown, status?: number): Response;
+/**
+ * @param {number} status
+ * @param {string} code
+ * @returns {Response}
+ */
+export function problemResponse(status: number, code: string): Response;
+export type LocalAuthenticationMode = "permissive" | "required";

package/types/local/environment.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @param {Readonly<Record<string, string | undefined>>} [environment]
+ * @returns {void}
+ */
+export function assertLocalSqliteEnvironment(environment?: Readonly<Record<string, string | undefined>>): void;
+export const localSqlitePresenceIndicators: readonly ["CI", "CONTINUOUS_INTEGRATION", "GITHUB_ACTIONS", "GITLAB_CI", "FORGEJO_ACTIONS", "GITEA_ACTIONS", "TF_BUILD", "BUILDKITE", "CIRCLECI", "JENKINS_URL", "TEAMCITY_VERSION", "VERCEL", "NETLIFY", "CF_PAGES", "RENDER", "FLY_APP_NAME", "K_SERVICE", "CLOUD_RUN_JOB", "KUBERNETES_SERVICE_HOST", "AWS_LAMBDA_FUNCTION_NAME", "AWS_EXECUTION_ENV", "ECS_CONTAINER_METADATA_URI", "ECS_CONTAINER_METADATA_URI_V4", "WEBSITE_INSTANCE_ID", "WEBSITE_SITE_NAME", "FUNCTIONS_WORKER_RUNTIME", "DYNO", "HEROKU_APP_NAME", "RAILWAY_ENVIRONMENT", "RAILWAY_SERVICE_ID", "NOMAD_ALLOC_ID", "TERRASCALE_DEPLOYMENT", "TERRASCALE_QUALIFICATION"];
+/**
+ * Explicit opt-in for a hosted development environment.
+ *
+ * Hosting platforms set a presence indicator on every workload, including
+ * development environments, so the SDK cannot tell a hosted dev environment
+ * from production by presence alone. Setting this variable to a true value
+ * relaxes *platform* indicators only: CI, qualification, and every stage
+ * indicator (`NODE_ENV=production`, `STAGE=staging`, …) still refuse.
+ */
+export const localSqliteHostedOptIn: "TERRASCALE_LOCAL_SQLITE_ALLOW_HOSTED";
+/**
+ * Presence indicators the opt-in never relaxes.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const localSqliteUnrelaxableIndicators: ReadonlySet<string>;
+export const localSqliteStageIndicators: readonly ["NODE_ENV", "APP_ENV", "ENVIRONMENT", "STAGE", "DEPLOY_ENV", "DEPLOYMENT_ENVIRONMENT", "TERRASCALE_ENV", "TERRASCALE_ENVIRONMENT", "VERCEL_ENV"];

package/types/local/index.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @deprecated Retired Rust emulator; use a local TerraBase release.
+ * @param {TerraScaleSqliteRuntimeOptions} options
+ * @returns {TerraScaleSqliteRuntime}
+ */
+export function createTerraScaleSqliteRuntime(options: TerraScaleSqliteRuntimeOptions): TerraScaleSqliteRuntime;
+/** @import { TerraBaseClient, TerraBaseClientConfig } from "./legacy-client.js" */
+/** @import { CollectionBinding, DatabaseScope } from "../database-types.js" */
+/** @typedef {import("./context.js").LocalAuthenticationMode} LocalAuthenticationMode */
+/** @typedef {import("./server.js").LocalServerAddress} LocalServerAddress */
+/** @typedef {import("./better-auth.js").LocalBetterAuthAdapterFactory} LocalBetterAuthAdapterFactory */
+/**
+ * @typedef {{
+ *   readonly sqlite: { readonly enabled: true; readonly databasePath: string };
+ *   readonly scope?: DatabaseScope;
+ *   readonly authentication?: LocalAuthenticationMode;
+ *   readonly bearerToken?: string;
+ *   readonly allowRemote?: boolean;
+ * }} TerraScaleSqliteRuntimeOptions
+ */
+/**
+ * @typedef {{
+ *   readonly host?: string;
+ *   readonly port?: number;
+ * }} TerraScaleLocalListenOptions
+ */
+/** @deprecated Retired Rust SQLite emulator; use a local TerraBase release binary.
+ * Explicit Node development backend. Never load this entrypoint in deployment or qualification. */
+export class TerraScaleSqliteRuntime {
+    /**
+     * @param {TerraScaleSqliteRuntimeOptions} options
+     */
+    constructor(options: TerraScaleSqliteRuntimeOptions);
+    /**
+     * @readonly
+     * @type {DatabaseScope}
+     */
+    readonly scope: DatabaseScope;
+    /** @returns {string} */
+    get databasePath(): string;
+    /** @returns {LocalServerAddress | undefined} */
+    get address(): LocalServerAddress | undefined;
+    get authority(): Readonly<{
+        mode: "single_writer";
+        generation: 1n;
+        writer: {
+            readonly replica: string;
+            readonly incarnation: string;
+        };
+    }>;
+    /**
+     * @param {CollectionBinding} binding
+     * @returns {Promise<void>}
+     */
+    bindCollection(binding: CollectionBinding): Promise<void>;
+    /**
+     * @param {Pick<TerraBaseClientConfig, "requestTimeoutMs">} [options]
+     * @returns {TerraBaseClient}
+     */
+    createClient(options?: Pick<TerraBaseClientConfig, "requestTimeoutMs">): TerraBaseClient;
+    /** @returns {Promise<LocalBetterAuthAdapterFactory>} */
+    createBetterAuthAdapter(): Promise<LocalBetterAuthAdapterFactory>;
+    /**
+     * @param {TerraScaleLocalListenOptions} [options]
+     * @returns {Promise<LocalServerAddress>}
+     */
+    start(options?: TerraScaleLocalListenOptions): Promise<LocalServerAddress>;
+    /** @returns {Promise<void>} */
+    stop(): Promise<void>;
+    /** @returns {Promise<void>} */
+    reset(): Promise<void>;
+    /** @returns {Promise<void>} */
+    close(): Promise<void>;
+    #private;
+}
+export type LocalAuthenticationMode = import("./context.js").LocalAuthenticationMode;
+export type LocalServerAddress = import("./server.js").LocalServerAddress;
+export type LocalBetterAuthAdapterFactory = import("./better-auth.js").LocalBetterAuthAdapterFactory;
+export type TerraScaleSqliteRuntimeOptions = {
+    readonly sqlite: {
+        readonly enabled: true;
+        readonly databasePath: string;
+    };
+    readonly scope?: DatabaseScope;
+    readonly authentication?: LocalAuthenticationMode;
+    readonly bearerToken?: string;
+    readonly allowRemote?: boolean;
+};
+export type TerraScaleLocalListenOptions = {
+    readonly host?: string;
+    readonly port?: number;
+};
+import type { DatabaseScope } from "../database-types.js";
+import type { CollectionBinding } from "../database-types.js";
+import type { TerraBaseClientConfig } from "./legacy-client.js";
+import type { TerraBaseClient } from "./legacy-client.js";