@spine-event-engine/client-web 2.0.0-snapshot.10

package/dist/client/browser-session.js

@@ -0,0 +1,228 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+/**
+ * Browser-managed cookie or memory-only bearer session resource.
+ */
+export class BrowserSession {
+    #fetch;
+    #maxRequestMs;
+    #credentials;
+    #controllers = new Set();
+    #bearer;
+    #closed = false;
+    #context;
+    #reauthenticationGeneration = 0;
+    constructor(credentials, bearer, options) {
+        this.#credentials = credentials;
+        this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+        if (typeof this.#fetch !== "function")
+            throw new TypeError("Browser session requires a fetch implementation.");
+        this.#maxRequestMs = BrowserSessionValues.requestDeadline(options.maxRequestMs);
+        this.#bearer = bearer;
+    }
+    /**
+     * Gets the browser Fetch credential mode selected by this immutable session.
+     * @returns Returns the selected credential mode.
+     */
+    get credentials() {
+        return this.#credentials;
+    }
+    /**
+     * Creates a browser-managed cookie session. Cookies never enter JavaScript metadata.
+     * @param options Configures fetch and the request deadline.
+     * @returns Returns the new cookie session.
+     */
+    static cookie(options = {}) {
+        return new BrowserSession("include", undefined, options);
+    }
+    /**
+     * Creates a memory-only bearer session. The token is never persisted by this resource.
+     * @param options Supplies the bearer token and session configuration.
+     * @returns Returns the new bearer session.
+     */
+    static bearer(options) {
+        return new BrowserSession("omit", BrowserSessionValues.requiredToken(options.token), options);
+    }
+    /**
+     * Gets the latest application gateway facts, which are informational and never credentials.
+     * @returns Returns a copied context, if one is available.
+     */
+    get context() {
+        return this.#context === undefined
+            ? undefined
+            : BrowserSessionValues.copyContext(this.#context);
+    }
+    /**
+     * Creates metadata for one request without exposing cookie values.
+     * @returns Returns the request metadata.
+     */
+    requestMetadata() {
+        const headers = new Headers();
+        if (this.#bearer !== undefined)
+            headers.set("authorization", `Bearer ${this.#bearer}`);
+        return headers;
+    }
+    /**
+     * Updates the memory-only bearer value.
+     * @param token Supplies the new bearer token.
+     */
+    replaceBearer(token) {
+        this.#assertOpen();
+        if (this.#credentials !== "omit")
+            throw new TypeError("Cookie sessions do not accept bearer tokens.");
+        this.#bearer = BrowserSessionValues.requiredToken(token);
+    }
+    /**
+     * Removes the memory-only bearer value. Cookie sessions remain browser-managed.
+     */
+    clearBearer() {
+        this.#bearer = undefined;
+    }
+    /**
+     * Executes an application-owned HTTP request with session transport behavior and
+     * a finite deadline. It does not implement a provider sign-in flow.
+     * @param input Supplies the request URL or request object.
+     * @param init Supplies optional request initialization.
+     * @returns Resolves to the HTTP response.
+     */
+    async fetch(input, init = {}) {
+        const bearer = this.#bearer;
+        return this.#run(init.signal ?? undefined, async (signal) => {
+            const headers = new Headers(init.headers);
+            if (bearer === undefined)
+                headers.delete("authorization");
+            else
+                headers.set("authorization", `Bearer ${bearer}`);
+            try {
+                return await this.#fetch(input, {
+                    ...init,
+                    credentials: this.#credentials,
+                    headers,
+                    signal,
+                });
+            }
+            catch (error) {
+                throw BrowserSessionValues.redactedError(error, bearer);
+            }
+        });
+    }
+    /**
+     * Updates informational context before a reconnect without treating it as credentials.
+     * @param onContext Resolves the latest application context.
+     * @param options Supplies optional cancellation.
+     * @returns Completes after the latest context is retained.
+     */
+    async reauthenticate(onContext, options = {}) {
+        if (typeof onContext !== "function")
+            throw new TypeError("Browser reauthentication adapter is required.");
+        const generation = ++this.#reauthenticationGeneration;
+        const context = await this.#run(options.signal, (signal) => onContext({ signal }));
+        if (generation !== this.#reauthenticationGeneration || this.#closed)
+            return;
+        this.#context = context === undefined ? undefined : BrowserSessionValues.freezeContext(context);
+    }
+    /**
+     * Closes session-owned HTTP or reauthentication work and clears memory-only credentials.
+     * @returns Completes after cancellation is requested.
+     */
+    close() {
+        if (this.#closed)
+            return Promise.resolve();
+        this.#closed = true;
+        this.#bearer = undefined;
+        this.#context = undefined;
+        for (const controller of this.#controllers)
+            controller.abort(new Error("Browser session is closed."));
+        return Promise.resolve();
+    }
+    async #run(signal, work) {
+        this.#assertOpen();
+        if (signal?.aborted)
+            throw signal.reason;
+        const controller = new AbortController();
+        const abort = () => {
+            controller.abort(signal?.reason);
+        };
+        const timeout = setTimeout(() => {
+            controller.abort(new Error("Browser session request timed out."));
+        }, this.#maxRequestMs);
+        signal?.addEventListener("abort", abort, { once: true });
+        this.#controllers.add(controller);
+        try {
+            const operation = work(controller.signal);
+            void operation.catch(() => undefined);
+            const aborted = Promise.withResolvers();
+            const rejectAbort = () => {
+                aborted.reject(controller.signal.reason ?? new Error("Browser session request aborted."));
+            };
+            controller.signal.addEventListener("abort", rejectAbort, { once: true });
+            const result = await Promise.race([operation, aborted.promise]).finally(() => {
+                controller.signal.removeEventListener("abort", rejectAbort);
+            });
+            this.#assertOpen();
+            return result;
+        }
+        finally {
+            clearTimeout(timeout);
+            this.#controllers.delete(controller);
+            signal?.removeEventListener("abort", abort);
+        }
+    }
+    #assertOpen() {
+        if (this.#closed)
+            throw new Error("Browser session is closed.");
+    }
+}
+const BrowserSessionValues = Object.freeze({
+    requestDeadline(value) {
+        const deadline = value ?? 10_000;
+        if (!Number.isSafeInteger(deadline) || deadline <= 0 || deadline > 60_000)
+            throw new RangeError("Browser session request deadline must be a positive safe integer at most 60000.");
+        return deadline;
+    },
+    requiredToken(value) {
+        if (typeof value !== "string" || value.length === 0 || value.length > 16_384)
+            throw new TypeError("Browser bearer token must be a non-empty string of at most 16384 characters.");
+        return value;
+    },
+    freezeContext(value) {
+        if (value.actor !== undefined &&
+            (typeof value.actor !== "string" || value.actor.length === 0 || value.actor.length > 4_096))
+            throw new TypeError("Browser session actor must be a non-empty string of at most 4096 characters.");
+        if (value.tenant !== undefined &&
+            (typeof value.tenant !== "string" || value.tenant.length === 0 || value.tenant.length > 4_096))
+            throw new TypeError("Browser session tenant must be a non-empty string of at most 4096 characters.");
+        if (value.expiresAt !== undefined &&
+            (!(value.expiresAt instanceof Date) || !Number.isFinite(value.expiresAt.getTime())))
+            throw new TypeError("Browser session expiry must be a valid Date.");
+        return Object.freeze({
+            ...(value.actor === undefined ? {} : { actor: value.actor }),
+            ...(value.tenant === undefined ? {} : { tenant: value.tenant }),
+            ...(value.expiresAt === undefined ? {} : { expiresAt: new Date(value.expiresAt) }),
+        });
+    },
+    copyContext(value) {
+        return Object.freeze({
+            ...(value.actor === undefined ? {} : { actor: value.actor }),
+            ...(value.tenant === undefined ? {} : { tenant: value.tenant }),
+            ...(value.expiresAt === undefined ? {} : { expiresAt: new Date(value.expiresAt) }),
+        });
+    },
+    redactedError(error, bearer) {
+        const source = error instanceof Error ? error.message : String(error);
+        const message = bearer === undefined ? source : source.replaceAll(bearer, "[REDACTED]");
+        return new Error(message);
+    },
+});
+//# sourceMappingURL=browser-session.js.map

package/dist/client/browser-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-session.js","sourceRoot":"","sources":["../../src/client/browser-session.ts"],"names":[],"mappings":"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"}

package/dist/client/client.d.ts

@@ -0,0 +1,394 @@
+import { type Message, type MessageShape } from "@bufbuild/protobuf";
+import type { GenMessage } from "@bufbuild/protobuf/codegenv2";
+import { type Transport } from "@connectrpc/connect";
+import { type TenantId, type ZoneId } from "@spine-event-engine/proto";
+import { type Query, type QueryResponse, type SubscriptionUpdate, type Topic } from "@spine-event-engine/proto/client";
+/**
+ * A valid application-level command outcome.
+ */
+export type ClientOutcome = Readonly<{
+    /**
+     * Identifies a successful command.
+     */
+    readonly kind: "ok";
+}> | Readonly<{
+    /**
+     * Identifies a command that produced an application error.
+     */
+    readonly kind: "error";
+    /**
+     * Carries the application error message.
+     */
+    readonly error: Message;
+}> | Readonly<{
+    /**
+     * Identifies a command rejected by application rules.
+     */
+    readonly kind: "rejection";
+    /**
+     * Carries the rejection message.
+     */
+    readonly rejection: Message;
+}>;
+/**
+ * Options shared by client operations.
+ */
+export interface ClientOperationOptions {
+    /**
+     * Cancels the operation when aborted.
+     */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Immutable context selected when a client is created.
+ */
+export interface ClientOptions {
+    /**
+     * Selects the tenant for all client requests.
+     */
+    readonly tenant?: string | TenantId;
+    /**
+     * Selects the time zone for all client requests.
+     */
+    readonly zoneId?: string | ZoneId;
+    /**
+     * Configures runtime behavior for created subscriptions.
+     */
+    readonly subscriptions?: SubscriptionRuntimeOptions;
+    /**
+     * Updates application credentials before one reconnect attempt.
+     * @param signal Cancels the refresh when the reconnect attempt ends.
+     * @returns Completes after the application refresh ends.
+     */
+    readonly onReauthenticateBeforeReconnect?: (signal: AbortSignal) => Promise<void>;
+}
+/**
+ * Bounded queues, retry policy, and scheduling for subscription recovery.
+ */
+export interface SubscriptionRuntimeOptions {
+    /**
+     * Limits queued updates by count.
+     */
+    readonly updateBufferCapacity?: number;
+    /**
+     * Limits queued updates by serialized byte size.
+     */
+    readonly updateBufferByteCapacity?: number;
+    /**
+     * Limits queued lifecycle notices by count.
+     */
+    readonly lifecycleBufferCapacity?: number;
+    /**
+     * Configures bounded reconnect retries.
+     */
+    readonly retryPolicy?: SubscriptionRetryPolicy;
+    /**
+     * Supplies clock and wait behavior for retries.
+     */
+    readonly scheduler?: SubscriptionScheduler;
+}
+/**
+ * Finite retry settings for retries after the initial subscription attempt.
+ */
+export interface SubscriptionRetryPolicy {
+    /**
+     * Limits retry attempts after the initial connection.
+     */
+    readonly maxAttempts: number;
+    /**
+     * Limits one recovery episode in milliseconds. A stream that remains
+     * connected for at least this duration starts a fresh episode on its next
+     * failure.
+     */
+    readonly maxElapsedMs: number;
+    /**
+     * Calculates the delay before a retry.
+     * @param attempt Identifies the retry attempt starting at one.
+     * @returns Returns the delay in milliseconds.
+     */
+    delayMs(attempt: number): number;
+}
+/**
+ * Clock and abortable-wait seam used by deterministic reconnect scheduling.
+ */
+export interface SubscriptionScheduler {
+    /**
+     * Returns the current scheduler time in milliseconds.
+     * @returns Returns the current time.
+     */
+    now(): number;
+    /**
+     * Waits for a retry delay unless cancelled.
+     * @param delayMs Supplies the delay in milliseconds.
+     * @param signal Cancels the wait.
+     * @returns Completes when the delay ends or rejects on cancellation.
+     */
+    wait(delayMs: number, signal: AbortSignal): Promise<void>;
+}
+/**
+ * An event subscription does not perform authoritative state recovery.
+ */
+export interface EventSubscriptionOptions extends ClientOperationOptions {
+    /**
+     * Identifies this as an event subscription.
+     */
+    readonly kind: "event";
+}
+/**
+ * An entity subscription supplies the query used for later authoritative recovery.
+ */
+export interface EntitySubscriptionOptions extends ClientOperationOptions {
+    /**
+     * Identifies this as an entity subscription.
+     */
+    readonly kind: "entity";
+    /**
+     * Builds the query used after a possible update gap.
+     * @returns Returns the authoritative entity query.
+     */
+    readonly authoritativeQuery: () => Query | {
+        build(): Query;
+    };
+}
+/**
+ * Explicit kind and recovery information required to create a subscription.
+ */
+export type CreateSubscriptionOptions = EventSubscriptionOptions | EntitySubscriptionOptions;
+/**
+ * A delivered raw wire update or an authoritative entity recovery result.
+ */
+export type SubscriptionDelivery = Readonly<{
+    /**
+     * Identifies a live subscription update.
+     */
+    readonly kind: "update";
+    /**
+     * Carries the live update.
+     */
+    readonly update: SubscriptionUpdate;
+}> | Readonly<{
+    /**
+     * Identifies an authoritative recovery response.
+     */
+    readonly kind: "resynchronization";
+    /**
+     * Carries the recovered query response.
+     */
+    readonly response: QueryResponse;
+}>;
+/**
+ * A lifecycle state emitted independently for one logical subscription.
+ */
+export type SubscriptionLifecycleState = "connecting" | "connected" | "resynchronizing" | "gapPossible" | "failed" | "closed";
+/**
+ * Describes one lifecycle transition for a logical subscription.
+ */
+export type SubscriptionLifecycle = 
+/**
+ * A generation is starting; `attempt` counts retries after its initial attempt.
+ */
+Readonly<{
+    /**
+     * Identifies initial connection.
+     */
+    readonly state: "connecting";
+    /**
+     * Identifies this logical subscription generation.
+     */
+    readonly generation: number;
+    /**
+     * Counts retries after the initial attempt.
+     */
+    readonly attempt: number;
+}>
+/**
+ * A non-terminal lifecycle transition, identified by its generation.
+ */
+ | Readonly<{
+    /**
+     * Identifies a non-terminal lifecycle transition.
+     */
+    readonly state: "connected" | "resynchronizing" | "gapPossible";
+    /**
+     * Identifies this logical subscription generation.
+     */
+    readonly generation: number;
+}>
+/**
+ * A terminal cancellation for a generation.
+ */
+ | Readonly<{
+    /**
+     * Identifies normal lifecycle closure.
+     */ readonly state: "closed";
+    /**
+     * Identifies this logical subscription generation.
+     */ readonly generation: number;
+}>
+/**
+ * A terminal failure for a generation, carrying its exact failure object.
+ */
+ | Readonly<{
+    /**
+     * Identifies terminal lifecycle failure.
+     */ readonly state: "failed";
+    /**
+     * Identifies this logical subscription generation.
+     */ readonly generation: number;
+    /**
+     * Carries the terminal failure.
+     */ readonly error: Error;
+}>;
+/**
+ * Returns fresh application-owned request metadata synchronously for one outbound call.
+ * @returns Returns headers for the outbound call.
+ */
+export type OnRequestMetadata = () => HeadersInit;
+/**
+ * Browser factory options, including an optional per-call metadata supplier.
+ */
+export interface BrowserClientOptions extends ClientOptions {
+    /**
+     * Supplies request metadata for each browser transport call.
+     */
+    readonly onRequestMetadata?: OnRequestMetadata;
+    /**
+     * Browser Fetch credential mode for this explicit protocol transport.
+     */
+    readonly credentials?: RequestCredentials;
+}
+/**
+ * Transport and request-ID source injected by an application or platform adapter.
+ */
+export interface ClientTransport {
+    /**
+     * Carries the Connect transport used for RPC calls.
+     */
+    readonly transport: Transport;
+    /**
+     * Creates a non-empty identifier for each outbound command.
+     * @returns Returns the new request identifier.
+     */
+    createRequestId(): string;
+    /**
+     * Closes a platform transport owned by this client after work settles.
+     */
+    close?(): void;
+}
+/**
+ * A manually activated protocol subscription.
+ */
+export interface Subscription {
+    /**
+     * Raw updates and authoritative entity recovery results for one consumer.
+     */
+    readonly updates: AsyncIterable<SubscriptionDelivery>;
+    /**
+     * Independent lifecycle notices for one consumer.
+     */
+    readonly lifecycle: AsyncIterable<SubscriptionLifecycle>;
+    /**
+     * Starts the remote subscription and makes its updates available for iteration.
+     * @param options Supplies cancellation options for activation.
+     * @returns Completes after remote activation ends.
+     */
+    activate(options?: ClientOperationOptions): Promise<void>;
+    /**
+     * Cancels local iteration and performs one bounded remote cancellation.
+     * @returns Completes after remote cancellation ends.
+     */
+    cancel(): Promise<void>;
+}
+/**
+ * Thrown for a service response that violates the frozen wire contract.
+ */
+export declare class ClientProtocolError extends Error {
+    /**
+     * Creates an error for an invalid wire response.
+     * @param message Explains the protocol violation.
+     */
+    constructor(message: string);
+}
+/**
+ * Browser-safe Spine client whose transport and ID source are supplied by the caller.
+ */
+export declare class Client {
+    #private;
+    /**
+     * Creates a browser client from a supplied transport and immutable options.
+     *
+     * @param source Supplies the browser-safe transport and request-ID source.
+     * @param options Supplies optional tenant, zone, reconnect, and subscription settings.
+     */
+    protected constructor(source: ClientTransport, options: ClientOptions);
+    /**
+     * Creates a client from an injected transport and request-ID source.
+     * @param source Supplies the transport and request-ID source.
+     * @param options Supplies immutable client options.
+     * @returns Returns the created client.
+     */
+    static usingTransport(source: ClientTransport, options?: ClientOptions): Client;
+    /**
+     * Creates a browser client that always uses the gRPC-Web protocol.
+     * @param baseUrl Supplies the gateway base URL.
+     * @param options Supplies browser client options.
+     * @returns Returns the created client.
+     */
+    static forGrpcWeb(baseUrl: string, options?: BrowserClientOptions): Client;
+    /**
+     * Creates a browser client that always uses binary Connect (`application/proto`).
+     *
+     * The selected gateway must permit binary Connect, including packed `Any` command
+     * and query values. Selection is explicit: this method never probes or falls back.
+     * @param baseUrl Supplies the gateway base URL.
+     * @param options Supplies browser client options.
+     * @returns Returns the created client.
+     */
+    static forConnect(baseUrl: string, options?: BrowserClientOptions): Client;
+    /**
+     * Creates an immutable request scope for the guest actor.
+     * @returns Returns the guest request scope.
+     */
+    asGuest(): ClientRequest;
+    /**
+     * Creates an immutable request scope for one actor.
+     * @param user Identifies the actor for requests in the scope.
+     * @returns Returns the actor request scope.
+     */
+    onBehalfOf(user: string): ClientRequest;
+    /**
+     * Closes the client by requesting open-work cancellation, awaiting subscription cleanup, and closing its transport.
+     * @returns Completes after subscription cleanup and transport closure.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Immutable actor scope for one client lifecycle owner.
+ */
+export interface ClientRequest {
+    /**
+     * Posts a command and returns its validated application-level outcome.
+     * @param schema Supplies the command message schema.
+     * @param message Supplies the command message.
+     * @param options Supplies cancellation options.
+     * @returns Returns the validated command outcome.
+     */
+    post<Schema extends GenMessage<Message>>(schema: Schema, message: MessageShape<Schema>, options?: ClientOperationOptions): Promise<ClientOutcome>;
+    /**
+     * Sends a query after applying this scope's immutable actor context.
+     * @param query Supplies a query or its builder.
+     * @param options Supplies cancellation options.
+     * @returns Returns the query response.
+     */
+    send(query: Query | {
+        build(): Query;
+    }, options?: ClientOperationOptions): Promise<QueryResponse>;
+    /**
+     * Creates an inactive topic subscription owned by this client lifecycle.
+     * @param topic Supplies the subscription topic.
+     * @param options Supplies the subscription kind and recovery options.
+     * @returns Returns the inactive subscription.
+     */
+    createSubscription(topic: Topic, options: CreateSubscriptionOptions): Promise<Subscription>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"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"}