@tearleads/client-sdk 0.0.0-stage → 0.1.13

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# @tearleads/client-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The React-free Tearleads client runtime: local SQLite persistence, keys, sync,
+encrypted blobs, and the domain workflows hosts build on. Hosts adapt platform
+behavior into the SDK rather than duplicate its setup.
+
+## Entry points
+
+| Entry point | Use for |
+| --- | --- |
+| `@tearleads/client-sdk` | `Tearleads`, SDK service types, local keyring helpers, document contracts, sync diagnostics, stores, purchase capabilities, and public workflow symbols |
+| `@tearleads/client-sdk/sqlite` | SQLite worker runtime factory, executor contracts, and adapter helpers |
+| `@tearleads/client-sdk/testing` | Trusted-identity fixtures for integration tests; never production code |
+
+## Quick start
+
+```ts
+import { Tearleads } from "@tearleads/client-sdk";
+
+const tearleads = new Tearleads();
+```
+
+The minimal instance uses same-origin API routes, memory blob storage, default
+logging, and an idle database. Configure SQLite before using persistence, sync,
+or identity generation:
+
+```ts
+tearleads.database.configure({
+  client: sqliteRuntime.client,
+  id: sqliteRuntime.id,
+});
+```
+
+`createSQLiteRuntime` from `@tearleads/client-sdk/sqlite` starts the runtime in
+a module worker. The worker script is not part of this package: the host serves
+it, at `/worker.js` unless it passes another `workerUrl`.
+
+Typecheck with `skipLibCheck: true`: the declarations of drizzle-orm and
+loro-crdt, which the SDK's types reference, do not typecheck without it.
+
+The [developer guide](https://github.com/a2f0/tearleads/blob/main/docs/developer/client-sdk.md)
+covers constructor options, the host contract, the local keyring, and every
+public entry point.
+
+## Publishing
+
+Inside the workspace the package exports `dist/`, built by
+`bun run --filter='@tearleads/client-sdk' build`. The npm package is built
+separately, into a directory you name, with its own generated manifest:
+
+```sh
+bun run --cwd packages/client-sdk package <out-dir>  # build the npm package
+bun run --cwd packages/client-sdk package:smoke      # pack, install, run, typecheck, and bundle outside the workspace
+```
+
+The workspace packages the SDK imports (`@tearleads/crypto`,
+`@tearleads/validators`, and the rest) export TypeScript source and are not
+published, so the build compiles them with the SDK, from its entry points, and
+ships each one under `internal/<package>/`. Imports of them become relative
+paths. Only modules the entry points reach are emitted, and only declarations
+their types reach are kept. The npm dependencies are the packages that output
+imports, at the versions the workspace pins, as caret ranges. Source maps carry
+their sources inline and name them by file name alone.
+
+`src/publishedPackage.test.ts` builds the package and checks its manifest, that
+every module imports only its own files or a declared dependency, and that no
+build path or test module ships. The smoke script imports every entry point
+under Bun and Node and bundles them for the browser. It typechecks a consumer
+under `bundler` and `nodenext` resolution with `skipLibCheck: true`, then again
+without it, failing on errors in the SDK's declarations and ignoring those in
+drizzle-orm's and loro-crdt's own. It needs the network to install the
+consumer's dependencies.
+
+Merging to `main` publishes. When `packages/client-sdk` changes there,
+`.github/workflows/client-sdk-publish.yml` publishes the version in
+`package.json` if it is newer than npm's `latest`, after running the smoke
+script; a merge that leaves the version alone, a re-run, or a run that finishes
+after a newer release succeeds without publishing
+(`scripts/lib/npmPublishDecision.ts` makes that call). Because the package
+ships the workspace packages above, `agent-tool.json` lists it under
+`versions.bundles`: a change to any of them also bumps the SDK's version, so it
+publishes too. The workflow authenticates with
+[npm trusted publishing](https://docs.npmjs.com/trusted-publishers) and
+attaches provenance to each version. On npmjs.com the package's trusted
+publisher names the `a2f0` owner, the `tearleads` repository, the
+`client-sdk-publish.yml` workflow, and the `npm` environment, which the
+repository restricts to `main`. Renaming the workflow or the environment breaks
+publishing until that setting matches.
+
+To publish by hand instead, run from the repository root with an account that
+owns the `@tearleads` npm scope:
+
+```sh
+npm login --registry https://registry.npmjs.org
+bun run publish:npm:dry-run client-sdk
+bun run publish:npm client-sdk --otp 123456
+```
+
+`scripts/publishNpmPackage.sh` rebuilds into a fresh temporary directory,
+publishes its generated manifest with public access to
+`https://registry.npmjs.org`, and removes the directory on success or failure.
+A temporary `.npmrc` overrides any scope-specific registry without changing
+your npm configuration. It accepts `--dry-run`, `--tag <tag>` (default
+`latest`), and `--otp <code>`.
+
+`ship-pr` bumps changed workspace packages before review and merge; the
+generated manifest copies `version` from `package.json`. The manifest names
+this repository, which npm requires of a version with provenance, and declares
+`"license": "UNLICENSED"` until a license is chosen.

package/client/Tearleads.d.ts

@@ -0,0 +1,111 @@
+import type { BlobStore } from "../data/blobContracts.js";
+import { type DocumentProjectorRegistryInput } from "../data/documents/documentKinds.js";
+import { type DomainScope } from "../data/domainScope.js";
+import type { ProvisionedSystemContainerSpec } from "../workflows/registration/index.js";
+import { ApiVersion } from "./apiVersion.js";
+import { type BlobStoreFactory, Blobs } from "./blobs.js";
+import { type ContainerContents } from "./containerContents.js";
+import { Database, type DatabaseOptions } from "./database.js";
+import { type DeviceFirst } from "./deviceFirst.js";
+import { type Documents } from "./documents.js";
+import { Events } from "./events.js";
+import { type Identity, type IdentityOptions } from "./identity.js";
+import { type Logger } from "./logger.js";
+import { Network } from "./network.js";
+import { type Organizations } from "./organizations/index.js";
+import type { PrincipalHistoryKeyProvider } from "./principalHistoryProtection.js";
+import { type Root } from "./root/index.js";
+import { type SecurityIncidentListener, type SecurityIncidents } from "./securityIncidents.js";
+import type { Session } from "./session/sessionTypes.js";
+import { SyncBillingGate } from "./syncBillingGate.js";
+import { type UserIdentities } from "./userIdentities.js";
+import { type Runtime } from "./workflowRuntime.js";
+export type ClientDatabaseOptions = Omit<DatabaseOptions, "status">;
+export interface ClientOptions {
+    apiBaseUrl?: string | undefined;
+    blobStore?: BlobStore | undefined;
+    blobStoreFactory?: BlobStoreFactory | undefined;
+    database?: ClientDatabaseOptions | undefined;
+    documentProjectors?: DocumentProjectorRegistryInput | undefined;
+    events?: ReadonlyArray<unknown> | undefined;
+    identity?: IdentityOptions | undefined;
+    /**
+     * Absolute, host-controlled API namespace for durable user-identity pins.
+     * Required only when apiBaseUrl is relative and no browser origin exists.
+     */
+    identityTrustDomain?: string | undefined;
+    identityProvisioning?: "auto" | "manual" | undefined;
+    logger?: Logger | undefined;
+    online?: boolean | undefined;
+    /** Called after a trust-boundary verification failure is durably recorded. */
+    onSecurityIncident?: SecurityIncidentListener | undefined;
+    /**
+     * Per-pane discriminator so documents in distinct panes derive distinct Loro
+     * peer ids (e.g. the pane's local identity namespace). Omit for single-pane.
+     */
+    peerScope?: string | undefined;
+    /** Private host key for durable history progress; omitted uses disposable session keys. */
+    principalHistoryKeyProvider?: PrincipalHistoryKeyProvider | undefined;
+    /**
+     * App-owned system containers born with every new organization (both
+     * registration and additional-org creation provision them atomically in the
+     * same server call), e.g. a trash bin. The app owns these because their slot
+     * namespaces are app concepts the SDK stays agnostic to.
+     */
+    provisionedSystemContainers?: ReadonlyArray<ProvisionedSystemContainerSpec> | undefined;
+}
+export declare class Tearleads {
+    readonly apiVersion: ApiVersion;
+    readonly blobs: Blobs;
+    readonly database: Database;
+    readonly deviceFirst: DeviceFirst;
+    readonly documents: Documents;
+    readonly events: Events;
+    readonly containerContents: ContainerContents;
+    readonly identity: Identity;
+    readonly network: Network;
+    readonly organizations: Organizations;
+    readonly root: Root;
+    readonly runtime: Runtime;
+    readonly securityIncidents: SecurityIncidents;
+    readonly session: Session;
+    readonly syncBillingGate: SyncBillingGate;
+    readonly userIdentities: UserIdentities;
+    private readonly apiClient;
+    private readonly documentProjectors;
+    private readonly disposeSecurityIncidents;
+    private retirePrincipalHistoryProtection;
+    private domainScopeKey;
+    private domainScopeValue;
+    private readonly logErrorHandler;
+    private readonly logHandler;
+    private autoIdentityProvisioned;
+    private autoIdentityProvisioningPromise;
+    private expiredSessionLoginPromise;
+    private pinLocalUserIdentity;
+    private boundUserId;
+    constructor(options?: ClientOptions);
+    /** Rebinds the session's trust callbacks once the runtime exists. */
+    private bindTrustedIdentityRuntime;
+    private configureApiClientCallbacks;
+    private createWorkflowRuntime;
+    log: (message: string) => void;
+    logError: (message: string | Error, cause?: unknown) => void;
+    /**
+     * Mint a single-use ticket to authenticate the server-events websocket
+     * handshake (which cannot carry the bearer header). Returns null when no
+     * session is active. The caller appends it to the websocket URL.
+     */
+    requestWebSocketTicket(): Promise<string | null>;
+    get domainScope(): DomainScope;
+    /**
+     * Tear down background work for the active domain scope: stop the reconciler
+     * and force-stop the sync coordinator pump, then drop the coordinator from
+     * its registry. Hosts call this from unmount/cleanup so a pump cannot outlive
+     * the React tree that created it. A later access for the same scope rebuilds
+     * fresh state.
+     */
+    dispose(): void;
+    private loginAfterSessionExpired;
+    private startAutomaticIdentityProvisioning;
+}

package/client/Tearleads.js

@@ -0,0 +1,264 @@
+import { ApiClient } from "../internal/api-client/index.js";
+import { resolveDocumentProjectorRegistry, } from "../data/documents/documentKinds.js";
+import { createDomainScope } from "../data/domainScope.js";
+import { disposeDomainSyncCoordinator } from "../data/sync/syncCoordinator.js";
+import { resolveIdentityTrustDomain } from "../data/trustedUserIdentity/index.js";
+import { ApiVersion } from "./apiVersion.js";
+import { Blobs } from "./blobs.js";
+import { createContainerContents, } from "./containerContents.js";
+import { Database } from "./database.js";
+import { createDeviceFirst } from "./deviceFirst.js";
+import { createDocuments } from "./documents.js";
+import { Events } from "./events.js";
+import { createIdentity, } from "./identity.js";
+import { logErrorToConsole } from "./logger.js";
+import { Network } from "./network.js";
+import { createOrganizations } from "./organizations/index.js";
+import { createRoot, rootRuntimeOf } from "./root/index.js";
+import { createSecurityIncidentService, } from "./securityIncidents.js";
+import { createSession } from "./session/index.js";
+import { SyncBillingGate } from "./syncBillingGate.js";
+import { createUserIdentities } from "./userIdentities.js";
+import { createRuntime, } from "./workflowRuntime.js";
+function createClientSecurityIncidentService(input) {
+    const identityTrustDomain = resolveIdentityTrustDomain({
+        apiBaseUrl: input.apiBaseUrl,
+        identityTrustDomain: input.options.identityTrustDomain,
+    });
+    return {
+        identityTrustDomain,
+        service: createSecurityIncidentService({
+            database: input.database,
+            logError: input.logError,
+            onIncident: input.options.onSecurityIncident,
+            trustDomain: identityTrustDomain,
+        }),
+    };
+}
+export class Tearleads {
+    apiVersion = new ApiVersion();
+    blobs;
+    database;
+    deviceFirst;
+    documents;
+    events;
+    containerContents;
+    identity;
+    network;
+    organizations;
+    root;
+    runtime;
+    securityIncidents;
+    session;
+    syncBillingGate;
+    userIdentities;
+    apiClient;
+    documentProjectors;
+    disposeSecurityIncidents;
+    retirePrincipalHistoryProtection = () => { };
+    // Tracks the storage/identity pair that owns domain-scoped runtime state.
+    domainScopeKey = null;
+    // Recreated when the storage database or signing identity changes.
+    domainScopeValue = createDomainScope();
+    logErrorHandler;
+    logHandler;
+    autoIdentityProvisioned = false;
+    autoIdentityProvisioningPromise = null;
+    expiredSessionLoginPromise = null;
+    // Rebound to the workflow runtime once it exists; the session is created first.
+    pinLocalUserIdentity = async () => {
+        throw new Error("Trusted user identity runtime is not initialized");
+    };
+    boundUserId = async () => {
+        throw new Error("Trusted user identity runtime is not initialized");
+    };
+    constructor(options = {}) {
+        const apiBaseUrl = options.apiBaseUrl ?? "";
+        this.apiClient = new ApiClient(apiBaseUrl);
+        this.blobs = new Blobs(options.blobStore, options.blobStoreFactory);
+        this.database = new Database(options.database);
+        this.documentProjectors = resolveDocumentProjectorRegistry(options.documentProjectors);
+        this.events = new Events(options.events, () => this.apiClient.clearWriterProjectionCaches());
+        this.logHandler = options.logger?.log ?? (() => undefined);
+        this.logErrorHandler = options.logger?.logError ?? logErrorToConsole;
+        const security = createClientSecurityIncidentService({
+            apiBaseUrl,
+            database: this.database,
+            logError: this.logError,
+            options,
+        });
+        this.securityIncidents = security.service.incidents;
+        this.disposeSecurityIncidents = security.service.dispose;
+        this.network = new Network(options.online);
+        this.syncBillingGate = new SyncBillingGate();
+        let session = null;
+        this.identity = createIdentity(options.identity, (signingFingerprint) => this.blobs.updateIdentityNamespace(signingFingerprint), this.log, {
+            bootstrapLocalRootContainer: async () => {
+                if (this.database.status !== "ready") {
+                    throw new Error("identity.generate requires a ready SQLite database.");
+                }
+                if (!session) {
+                    throw new Error("identity.generate requires an initialized session.");
+                }
+                return session.bootstrapLocalRootContainer();
+            },
+            getUserId: () => session?.userId ?? null,
+        });
+        session = createSession({
+            api: this.apiClient,
+            database: this.database,
+            documentProjectors: this.documentProjectors,
+            identity: this.identity,
+            log: this.log,
+            logError: this.logError,
+            boundUserIdForSigningKey: (signingKeyFingerprint) => this.boundUserId(signingKeyFingerprint),
+            onUserIdentityAvailable: (userId, candidate) => this.pinLocalUserIdentity(userId, candidate),
+            provisionedSystemContainers: options.provisionedSystemContainers,
+            reportSecurityIncident: security.service.report,
+        });
+        this.session = session;
+        const runtime = this.createWorkflowRuntime(security.identityTrustDomain, options, security.service.report);
+        this.bindTrustedIdentityRuntime(runtime);
+        this.runtime = runtime.publicRuntime;
+        this.documents = createDocuments({
+            getDefaultContainerId: () => this.session.containerId,
+            runtime,
+        });
+        this.containerContents = createContainerContents(runtime);
+        this.deviceFirst = createDeviceFirst(runtime, this.containerContents);
+        this.organizations = createOrganizations(runtime, this.containerContents);
+        this.root = createRoot(rootRuntimeOf(runtime, this.session));
+        this.userIdentities = createUserIdentities({
+            log: this.log,
+            resolveTrustedUserIdentity: (userId) => runtime.workflowInput().resolveTrustedUserIdentity(userId),
+        });
+        this.configureApiClientCallbacks();
+        if (options.identityProvisioning === "auto") {
+            this.startAutomaticIdentityProvisioning();
+        }
+    }
+    /** Rebinds the session's trust callbacks once the runtime exists. */
+    bindTrustedIdentityRuntime(runtime) {
+        this.retirePrincipalHistoryProtection =
+            runtime.retirePrincipalHistoryProtection;
+        this.pinLocalUserIdentity = (userId, candidate) => runtime.pinLocalUserIdentity(userId, candidate);
+        this.boundUserId = (signingKeyFingerprint) => runtime.boundUserId(signingKeyFingerprint);
+    }
+    configureApiClientCallbacks() {
+        this.apiClient.setOnError((message) => this.logError(message));
+        // An authoritative host source owns connectivity. Without one, request
+        // outcomes remain reachability hints. Browser and native app bindings both
+        // install authoritative sources so a backend outage cannot stop retries.
+        this.apiClient.setOnNetworkError(() => this.network.reportReachability(false));
+        this.apiClient.setOnNetworkSuccess(() => this.network.reportReachability(true));
+        this.apiClient.setOnApiVersion((version) => this.apiVersion.observe(version));
+        this.apiClient.setOnSessionExpired(() => this.loginAfterSessionExpired());
+        this.apiClient.setOnPaymentRequired((organizationId) => this.syncBillingGate.notifyPaymentRequired(organizationId));
+    }
+    createWorkflowRuntime(identityTrustDomain, options, reportSecurityIncident) {
+        return createRuntime({
+            api: this.apiClient,
+            blobs: this.blobs,
+            database: this.database,
+            documentProjectors: this.documentProjectors,
+            events: this.events,
+            getDomainScope: () => this.domainScope,
+            identity: this.identity,
+            identityTrustDomain,
+            log: this.log,
+            logError: this.logError,
+            network: this.network,
+            peerScope: options.peerScope ?? null,
+            principalHistoryKeyProvider: options.principalHistoryKeyProvider,
+            reportSecurityIncident,
+            session: this.session,
+            syncBillingGate: this.syncBillingGate,
+        });
+    }
+    log = (message) => {
+        this.logHandler(message);
+    };
+    // Preserve the host's return value so best-effort callers can also catch
+    // rejected promises from async loggers accepted by the void callback type.
+    logError = (message, cause) => this.logErrorHandler(message, cause);
+    /**
+     * Mint a single-use ticket to authenticate the server-events websocket
+     * handshake (which cannot carry the bearer header). Returns null when no
+     * session is active. The caller appends it to the websocket URL.
+     */
+    requestWebSocketTicket() {
+        return this.apiClient.requestWebSocketTicket();
+    }
+    get domainScope() {
+        const nextScopeKey = JSON.stringify([
+            this.database.id,
+            this.identity.signingFingerprint,
+        ]);
+        if (this.domainScopeKey !== nextScopeKey) {
+            this.domainScopeKey = nextScopeKey;
+            this.domainScopeValue = createDomainScope();
+        }
+        return this.domainScopeValue;
+    }
+    /**
+     * Tear down background work for the active domain scope: stop the reconciler
+     * and force-stop the sync coordinator pump, then drop the coordinator from
+     * its registry. Hosts call this from unmount/cleanup so a pump cannot outlive
+     * the React tree that created it. A later access for the same scope rebuilds
+     * fresh state.
+     */
+    dispose() {
+        const domainScope = this.domainScope;
+        this.disposeSecurityIncidents();
+        this.retirePrincipalHistoryProtection();
+        this.deviceFirst.dispose();
+        disposeDomainSyncCoordinator(domainScope);
+    }
+    loginAfterSessionExpired() {
+        if (!this.session.authToken || !this.identity.signingKeyPair) {
+            this.session.logout();
+            return Promise.resolve(false);
+        }
+        this.expiredSessionLoginPromise ??= this.session.login().finally(() => {
+            this.expiredSessionLoginPromise = null;
+        });
+        return this.expiredSessionLoginPromise;
+    }
+    startAutomaticIdentityProvisioning() {
+        let unsubscribe = null;
+        const stopProvisioningListener = () => {
+            unsubscribe?.();
+            unsubscribe = null;
+        };
+        const maybeProvisionIdentity = () => {
+            if (this.autoIdentityProvisioned || this.identity.signingKeyPair) {
+                stopProvisioningListener();
+                return;
+            }
+            if (this.autoIdentityProvisioningPromise ||
+                this.database.status !== "ready") {
+                return;
+            }
+            this.autoIdentityProvisioningPromise = this.identity
+                .generate()
+                .then(() => {
+                this.autoIdentityProvisioned = true;
+                stopProvisioningListener();
+            })
+                .catch((error) => {
+                try {
+                    this.logError("Automatic identity provisioning failed", error);
+                }
+                catch {
+                    // Keep background provisioning failures from surfacing as unhandled rejections.
+                }
+            })
+                .finally(() => {
+                this.autoIdentityProvisioningPromise = null;
+            });
+        };
+        unsubscribe = this.database.subscribe(maybeProvisionIdentity);
+        void Promise.resolve().then(maybeProvisionIdentity);
+    }
+}
+//# sourceMappingURL=Tearleads.js.map

package/client/Tearleads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tearleads.js","sourceRoot":"","sources":["Tearleads.ts"],"names":[],"mappings":"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","sourcesContent":["import { ApiClient } from \"@tearleads/api-client\";\nimport type { BlobStore } from \"../data/blobContracts\";\nimport {\n  type DocumentProjectorRegistry,\n  type DocumentProjectorRegistryInput,\n  resolveDocumentProjectorRegistry,\n} from \"../data/documents/documentKinds\";\nimport { createDomainScope, type DomainScope } from \"../data/domainScope\";\nimport type { SecurityIncidentReporter } from \"../data/securityIncidents\";\nimport { disposeDomainSyncCoordinator } from \"../data/sync/syncCoordinator\";\nimport { resolveIdentityTrustDomain } from \"../data/trustedUserIdentity\";\nimport type { ProvisionedSystemContainerSpec } from \"../workflows/registration\";\nimport { ApiVersion } from \"./apiVersion\";\nimport { type BlobStoreFactory, Blobs } from \"./blobs\";\nimport {\n  type ContainerContents,\n  createContainerContents,\n} from \"./containerContents\";\nimport { Database, type DatabaseOptions } from \"./database\";\nimport { createDeviceFirst, type DeviceFirst } from \"./deviceFirst\";\nimport { createDocuments, type Documents } from \"./documents\";\nimport { Events } from \"./events\";\nimport {\n  createIdentity,\n  type Identity,\n  type IdentityOptions,\n} from \"./identity\";\nimport { type Logger, logErrorToConsole } from \"./logger\";\nimport { Network } from \"./network\";\nimport { createOrganizations, type Organizations } from \"./organizations\";\nimport type { PrincipalHistoryKeyProvider } from \"./principalHistoryProtection\";\nimport { createRoot, type Root, rootRuntimeOf } from \"./root\";\nimport {\n  createSecurityIncidentService,\n  type SecurityIncidentListener,\n  type SecurityIncidents,\n} from \"./securityIncidents\";\nimport { createSession } from \"./session\";\nimport type { Session } from \"./session/sessionTypes\";\nimport { SyncBillingGate } from \"./syncBillingGate\";\nimport { createUserIdentities, type UserIdentities } from \"./userIdentities\";\nimport {\n  createRuntime,\n  type InternalRuntime,\n  type Runtime,\n} from \"./workflowRuntime\";\n\nfunction createClientSecurityIncidentService(input: {\n  readonly apiBaseUrl: string;\n  readonly database: Database;\n  readonly logError: (message: string | Error, cause?: unknown) => void;\n  readonly options: ClientOptions;\n}) {\n  const identityTrustDomain = resolveIdentityTrustDomain({\n    apiBaseUrl: input.apiBaseUrl,\n    identityTrustDomain: input.options.identityTrustDomain,\n  });\n  return {\n    identityTrustDomain,\n    service: createSecurityIncidentService({\n      database: input.database,\n      logError: input.logError,\n      onIncident: input.options.onSecurityIncident,\n      trustDomain: identityTrustDomain,\n    }),\n  };\n}\n\nexport type ClientDatabaseOptions = Omit<DatabaseOptions, \"status\">;\n\nexport interface ClientOptions {\n  apiBaseUrl?: string | undefined;\n  blobStore?: BlobStore | undefined;\n  blobStoreFactory?: BlobStoreFactory | undefined;\n  database?: ClientDatabaseOptions | undefined;\n  documentProjectors?: DocumentProjectorRegistryInput | undefined;\n  events?: ReadonlyArray<unknown> | undefined;\n  identity?: IdentityOptions | undefined;\n  /**\n   * Absolute, host-controlled API namespace for durable user-identity pins.\n   * Required only when apiBaseUrl is relative and no browser origin exists.\n   */\n  identityTrustDomain?: string | undefined;\n  identityProvisioning?: \"auto\" | \"manual\" | undefined;\n  logger?: Logger | undefined;\n  online?: boolean | undefined;\n  /** Called after a trust-boundary verification failure is durably recorded. */\n  onSecurityIncident?: SecurityIncidentListener | undefined;\n  /**\n   * Per-pane discriminator so documents in distinct panes derive distinct Loro\n   * peer ids (e.g. the pane's local identity namespace). Omit for single-pane.\n   */\n  peerScope?: string | undefined;\n  /** Private host key for durable history progress; omitted uses disposable session keys. */\n  principalHistoryKeyProvider?: PrincipalHistoryKeyProvider | undefined;\n  /**\n   * App-owned system containers born with every new organization (both\n   * registration and additional-org creation provision them atomically in the\n   * same server call), e.g. a trash bin. The app owns these because their slot\n   * namespaces are app concepts the SDK stays agnostic to.\n   */\n  provisionedSystemContainers?:\n    | ReadonlyArray<ProvisionedSystemContainerSpec>\n    | undefined;\n}\n\nexport class Tearleads {\n  readonly apiVersion = new ApiVersion();\n  readonly blobs: Blobs;\n  readonly database: Database;\n  readonly deviceFirst: DeviceFirst;\n  readonly documents: Documents;\n  readonly events: Events;\n  readonly containerContents: ContainerContents;\n  readonly identity: Identity;\n  readonly network: Network;\n  readonly organizations: Organizations;\n  readonly root: Root;\n  readonly runtime: Runtime;\n  readonly securityIncidents: SecurityIncidents;\n  readonly session: Session;\n  readonly syncBillingGate: SyncBillingGate;\n  readonly userIdentities: UserIdentities;\n\n  private readonly apiClient: ApiClient;\n  private readonly documentProjectors: DocumentProjectorRegistry;\n  private readonly disposeSecurityIncidents: () => void;\n  private retirePrincipalHistoryProtection = () => {};\n  // Tracks the storage/identity pair that owns domain-scoped runtime state.\n  private domainScopeKey: string | null = null;\n  // Recreated when the storage database or signing identity changes.\n  private domainScopeValue: DomainScope = createDomainScope();\n  private readonly logErrorHandler: (\n    message: string | Error,\n    cause?: unknown,\n  ) => void;\n  private readonly logHandler: (message: string) => void;\n  private autoIdentityProvisioned = false;\n  private autoIdentityProvisioningPromise: Promise<void> | null = null;\n  private expiredSessionLoginPromise: Promise<boolean> | null = null;\n  // Rebound to the workflow runtime once it exists; the session is created first.\n  private pinLocalUserIdentity: InternalRuntime[\"pinLocalUserIdentity\"] =\n    async () => {\n      throw new Error(\"Trusted user identity runtime is not initialized\");\n    };\n  private boundUserId: InternalRuntime[\"boundUserId\"] = async () => {\n    throw new Error(\"Trusted user identity runtime is not initialized\");\n  };\n\n  constructor(options: ClientOptions = {}) {\n    const apiBaseUrl = options.apiBaseUrl ?? \"\";\n    this.apiClient = new ApiClient(apiBaseUrl);\n    this.blobs = new Blobs(options.blobStore, options.blobStoreFactory);\n    this.database = new Database(options.database);\n    this.documentProjectors = resolveDocumentProjectorRegistry(\n      options.documentProjectors,\n    );\n    this.events = new Events(options.events, () =>\n      this.apiClient.clearWriterProjectionCaches(),\n    );\n    this.logHandler = options.logger?.log ?? (() => undefined);\n    this.logErrorHandler = options.logger?.logError ?? logErrorToConsole;\n    const security = createClientSecurityIncidentService({\n      apiBaseUrl,\n      database: this.database,\n      logError: this.logError,\n      options,\n    });\n    this.securityIncidents = security.service.incidents;\n    this.disposeSecurityIncidents = security.service.dispose;\n    this.network = new Network(options.online);\n    this.syncBillingGate = new SyncBillingGate();\n    let session: Session | null = null;\n    this.identity = createIdentity(\n      options.identity,\n      (signingFingerprint) =>\n        this.blobs.updateIdentityNamespace(signingFingerprint),\n      this.log,\n      {\n        bootstrapLocalRootContainer: async () => {\n          if (this.database.status !== \"ready\") {\n            throw new Error(\n              \"identity.generate requires a ready SQLite database.\",\n            );\n          }\n          if (!session) {\n            throw new Error(\n              \"identity.generate requires an initialized session.\",\n            );\n          }\n\n          return session.bootstrapLocalRootContainer();\n        },\n        getUserId: () => session?.userId ?? null,\n      },\n    );\n    session = createSession({\n      api: this.apiClient,\n      database: this.database,\n      documentProjectors: this.documentProjectors,\n      identity: this.identity,\n      log: this.log,\n      logError: this.logError,\n      boundUserIdForSigningKey: (signingKeyFingerprint) =>\n        this.boundUserId(signingKeyFingerprint),\n      onUserIdentityAvailable: (userId, candidate) =>\n        this.pinLocalUserIdentity(userId, candidate),\n      provisionedSystemContainers: options.provisionedSystemContainers,\n      reportSecurityIncident: security.service.report,\n    });\n    this.session = session;\n    const runtime = this.createWorkflowRuntime(\n      security.identityTrustDomain,\n      options,\n      security.service.report,\n    );\n    this.bindTrustedIdentityRuntime(runtime);\n    this.runtime = runtime.publicRuntime;\n    this.documents = createDocuments({\n      getDefaultContainerId: () => this.session.containerId,\n      runtime,\n    });\n    this.containerContents = createContainerContents(runtime);\n    this.deviceFirst = createDeviceFirst(runtime, this.containerContents);\n    this.organizations = createOrganizations(runtime, this.containerContents);\n    this.root = createRoot(rootRuntimeOf(runtime, this.session));\n    this.userIdentities = createUserIdentities({\n      log: this.log,\n      resolveTrustedUserIdentity: (userId) =>\n        runtime.workflowInput().resolveTrustedUserIdentity(userId),\n    });\n\n    this.configureApiClientCallbacks();\n\n    if (options.identityProvisioning === \"auto\") {\n      this.startAutomaticIdentityProvisioning();\n    }\n  }\n\n  /** Rebinds the session's trust callbacks once the runtime exists. */\n  private bindTrustedIdentityRuntime(runtime: InternalRuntime): void {\n    this.retirePrincipalHistoryProtection =\n      runtime.retirePrincipalHistoryProtection;\n    this.pinLocalUserIdentity = (userId, candidate) =>\n      runtime.pinLocalUserIdentity(userId, candidate);\n    this.boundUserId = (signingKeyFingerprint) =>\n      runtime.boundUserId(signingKeyFingerprint);\n  }\n\n  private configureApiClientCallbacks(): void {\n    this.apiClient.setOnError((message) => this.logError(message));\n    // An authoritative host source owns connectivity. Without one, request\n    // outcomes remain reachability hints. Browser and native app bindings both\n    // install authoritative sources so a backend outage cannot stop retries.\n    this.apiClient.setOnNetworkError(() =>\n      this.network.reportReachability(false),\n    );\n    this.apiClient.setOnNetworkSuccess(() =>\n      this.network.reportReachability(true),\n    );\n    this.apiClient.setOnApiVersion((version) =>\n      this.apiVersion.observe(version),\n    );\n    this.apiClient.setOnSessionExpired(() => this.loginAfterSessionExpired());\n    this.apiClient.setOnPaymentRequired((organizationId) =>\n      this.syncBillingGate.notifyPaymentRequired(organizationId),\n    );\n  }\n\n  private createWorkflowRuntime(\n    identityTrustDomain: string | null,\n    options: ClientOptions,\n    reportSecurityIncident: SecurityIncidentReporter,\n  ): InternalRuntime {\n    return createRuntime({\n      api: this.apiClient,\n      blobs: this.blobs,\n      database: this.database,\n      documentProjectors: this.documentProjectors,\n      events: this.events,\n      getDomainScope: () => this.domainScope,\n      identity: this.identity,\n      identityTrustDomain,\n      log: this.log,\n      logError: this.logError,\n      network: this.network,\n      peerScope: options.peerScope ?? null,\n      principalHistoryKeyProvider: options.principalHistoryKeyProvider,\n      reportSecurityIncident,\n      session: this.session,\n      syncBillingGate: this.syncBillingGate,\n    });\n  }\n\n  log = (message: string): void => {\n    this.logHandler(message);\n  };\n\n  // Preserve the host's return value so best-effort callers can also catch\n  // rejected promises from async loggers accepted by the void callback type.\n  logError = (message: string | Error, cause?: unknown): void =>\n    this.logErrorHandler(message, cause);\n\n  /**\n   * Mint a single-use ticket to authenticate the server-events websocket\n   * handshake (which cannot carry the bearer header). Returns null when no\n   * session is active. The caller appends it to the websocket URL.\n   */\n  requestWebSocketTicket(): Promise<string | null> {\n    return this.apiClient.requestWebSocketTicket();\n  }\n\n  get domainScope(): DomainScope {\n    const nextScopeKey = JSON.stringify([\n      this.database.id,\n      this.identity.signingFingerprint,\n    ]);\n    if (this.domainScopeKey !== nextScopeKey) {\n      this.domainScopeKey = nextScopeKey;\n      this.domainScopeValue = createDomainScope();\n    }\n\n    return this.domainScopeValue;\n  }\n\n  /**\n   * Tear down background work for the active domain scope: stop the reconciler\n   * and force-stop the sync coordinator pump, then drop the coordinator from\n   * its registry. Hosts call this from unmount/cleanup so a pump cannot outlive\n   * the React tree that created it. A later access for the same scope rebuilds\n   * fresh state.\n   */\n  dispose(): void {\n    const domainScope = this.domainScope;\n    this.disposeSecurityIncidents();\n    this.retirePrincipalHistoryProtection();\n    this.deviceFirst.dispose();\n    disposeDomainSyncCoordinator(domainScope);\n  }\n\n  private loginAfterSessionExpired(): Promise<boolean> {\n    if (!this.session.authToken || !this.identity.signingKeyPair) {\n      this.session.logout();\n      return Promise.resolve(false);\n    }\n\n    this.expiredSessionLoginPromise ??= this.session.login().finally(() => {\n      this.expiredSessionLoginPromise = null;\n    });\n    return this.expiredSessionLoginPromise;\n  }\n\n  private startAutomaticIdentityProvisioning(): void {\n    let unsubscribe: (() => void) | null = null;\n    const stopProvisioningListener = () => {\n      unsubscribe?.();\n      unsubscribe = null;\n    };\n    const maybeProvisionIdentity = () => {\n      if (this.autoIdentityProvisioned || this.identity.signingKeyPair) {\n        stopProvisioningListener();\n        return;\n      }\n\n      if (\n        this.autoIdentityProvisioningPromise ||\n        this.database.status !== \"ready\"\n      ) {\n        return;\n      }\n\n      this.autoIdentityProvisioningPromise = this.identity\n        .generate()\n        .then(() => {\n          this.autoIdentityProvisioned = true;\n          stopProvisioningListener();\n        })\n        .catch((error: unknown) => {\n          try {\n            this.logError(\"Automatic identity provisioning failed\", error);\n          } catch {\n            // Keep background provisioning failures from surfacing as unhandled rejections.\n          }\n        })\n        .finally(() => {\n          this.autoIdentityProvisioningPromise = null;\n        });\n    };\n\n    unsubscribe = this.database.subscribe(maybeProvisionIdentity);\n    void Promise.resolve().then(maybeProvisionIdentity);\n  }\n}\n"]}

package/client/apiVersion.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The API build that served this client's latest response, as named by the
+ * API's version header: the commit count of the default branch it was built
+ * from, so a later deploy always reads higher.
+ *
+ * Held in memory only. It describes the server answering right now, so a value
+ * persisted across launches would misattribute the first failures after a
+ * redeploy, and the first response of every session replaces it anyway.
+ */
+export declare class ApiVersion {
+    private readonly listeners;
+    private currentValue;
+    /** Null until a response names its build. */
+    get current(): number | null;
+    observe(version: number): void;
+    subscribe: (listener: (version: number) => void) => (() => void);
+}

package/client/apiVersion.js

@@ -0,0 +1,27 @@
+import { createListenerSet } from "./listenerSet.js";
+/**
+ * The API build that served this client's latest response, as named by the
+ * API's version header: the commit count of the default branch it was built
+ * from, so a later deploy always reads higher.
+ *
+ * Held in memory only. It describes the server answering right now, so a value
+ * persisted across launches would misattribute the first failures after a
+ * redeploy, and the first response of every session replaces it anyway.
+ */
+export class ApiVersion {
+    listeners = createListenerSet();
+    currentValue = null;
+    /** Null until a response names its build. */
+    get current() {
+        return this.currentValue;
+    }
+    observe(version) {
+        if (this.currentValue === version) {
+            return;
+        }
+        this.currentValue = version;
+        this.listeners.notify(version);
+    }
+    subscribe = (listener) => this.listeners.subscribe(listener);
+}
+//# sourceMappingURL=apiVersion.js.map

package/client/apiVersion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiVersion.js","sourceRoot":"","sources":["apiVersion.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElD;;;;;;;;GAQG;AACH,MAAM,OAAO,UAAU;IACJ,SAAS,GAAG,iBAAiB,EAAY,CAAC;IACnD,YAAY,GAAkB,IAAI,CAAC;IAE3C,6CAA6C;IAC7C,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,OAAO,CAAC,OAAe;QACrB,IAAI,IAAI,CAAC,YAAY,KAAK,OAAO,EAAE,CAAC;YAClC,OAAO;QACT,CAAC;QACD,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC;QAC5B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,SAAS,GAAG,CAAC,QAAmC,EAAgB,EAAE,CAChE,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;CACtC","sourcesContent":["import { createListenerSet } from \"./listenerSet\";\n\n/**\n * The API build that served this client's latest response, as named by the\n * API's version header: the commit count of the default branch it was built\n * from, so a later deploy always reads higher.\n *\n * Held in memory only. It describes the server answering right now, so a value\n * persisted across launches would misattribute the first failures after a\n * redeploy, and the first response of every session replaces it anyway.\n */\nexport class ApiVersion {\n  private readonly listeners = createListenerSet<[number]>();\n  private currentValue: number | null = null;\n\n  /** Null until a response names its build. */\n  get current(): number | null {\n    return this.currentValue;\n  }\n\n  observe(version: number): void {\n    if (this.currentValue === version) {\n      return;\n    }\n    this.currentValue = version;\n    this.listeners.notify(version);\n  }\n\n  subscribe = (listener: (version: number) => void): (() => void) =>\n    this.listeners.subscribe(listener);\n}\n"]}