@abloatai/transaction 0.59.1 → 0.60.0

package/src/{transport/connection/credentialLifecycle.ts → sessions/lifecycle.ts}

@@ -1,20 +1,20 @@
 /**
  * Keeps the short-lived access credential fresh. It owns the re-mint hook, a
  * single-flight guard that stops concurrent triggers from minting more than
- * once, and a browser-only proactive refresh — a timer plus an OS-wake listener
- * — that renews the credential ahead of expiry. It reaches the rest of the
+ * once, and proactive refresh — an expiry-aware timer plus a browser OS-wake
+ * listener — that renews the credential ahead of expiry. It reaches the rest of the
  * client only through the small {@link CredentialLifecycleContext} interface,
  * so the two can reference each other without an import cycle.
  */
 
-import type { RecoveryClass } from '../../errorCodes.js';
-import { noopLogger, type Logger } from '../../logger.js';
+import type { RecoveryClass } from '../errorCodes.js';
+import { noopLogger, type Logger } from '../logger.js';
 import {
   credentialExpiry,
   credentialToken,
   type CredentialProvider,
   type CredentialProviderResult,
-} from '../../auth/credentialResult.js';
+} from '../auth/credentialResult.js';
 
 /**
  * Tri-state outcome of a credential re-mint, mirroring the `getToken`

package/src/sessions/source.ts

@@ -0,0 +1,94 @@
+/**
+ * Runtime lifecycle for a renewable session supplied to `Ablo({ session })`.
+ *
+ * A session provider mints a credential, while this boundary decides when to
+ * reuse it. Keeping that policy here prevents HTTP requests and the WebSocket
+ * bootstrap from independently minting duplicate sessions for the same actor.
+ */
+
+import type {
+  CredentialProvider,
+  CredentialProviderResult,
+} from '../auth/credentialResult.js';
+import type {
+  SessionProvider,
+  SessionProviderResult,
+  SessionSource,
+} from './contract.js';
+import { AbloValidationError } from '../errors.js';
+import {
+  createEndpointCredentialResolver,
+  isCredentialEndpoint,
+} from '../auth/credentialEndpoint.js';
+import { protectBrowserCredentialProvider } from '../auth/browserCredentialSafety.js';
+
+const SESSION_REFRESH_SKEW_MS = 30_000;
+
+function remainsUsable(session: Exclude<SessionProviderResult, null>, now: number): boolean {
+  const expiresAt = Date.parse(session.expiresAt);
+  return Number.isFinite(expiresAt) && expiresAt - now > SESSION_REFRESH_SKEW_MS;
+}
+
+/** Cache one minted session until it approaches expiry; concurrent refreshes share one mint. */
+export function cachedSessionProvider(provider: SessionProvider): CredentialProvider {
+  let current: Exclude<SessionProviderResult, null> | null = null;
+  let refreshing: Promise<SessionProviderResult> | null = null;
+
+  return async () => {
+    if (current && remainsUsable(current, Date.now())) return current;
+    refreshing ??= provider().then((next) => {
+      current = next;
+      return next;
+    }).finally(() => {
+      refreshing = null;
+    });
+    return refreshing;
+  };
+}
+
+/** The one credential input a live transport consumes. */
+export interface SessionAccess {
+  readonly renewable: boolean;
+  credential(): Promise<CredentialProviderResult>;
+}
+
+/** Normalize a static or renewable session before it reaches a transport. */
+export function createSessionAccess(
+  source: SessionSource | null | undefined,
+  credential: () => Promise<CredentialProviderResult>,
+): SessionAccess {
+  return {
+    renewable:
+      typeof source === 'function'
+      || (typeof source === 'object' && source !== null && 'endpoint' in source),
+    credential,
+  };
+}
+
+/** Resolve the public session forms into the credential shape auth consumes. */
+export function resolveSessionCredential(
+  source: SessionSource,
+  options: {
+    readonly fetch?: typeof globalThis.fetch;
+    readonly dangerouslyAllowBrowser?: boolean;
+  },
+): string | CredentialProvider {
+  if (typeof source === 'function') {
+    return protectBrowserCredentialProvider(
+      cachedSessionProvider(source),
+      options.dangerouslyAllowBrowser,
+    );
+  }
+  if (!('endpoint' in source)) return source.token;
+  if (!isCredentialEndpoint(source.endpoint)) {
+    throw new AbloValidationError(
+      '`session.endpoint` expects a URL or path such as \'/api/ablo-session\'.',
+      { code: 'invalid_options', param: 'session.endpoint' },
+    );
+  }
+  return protectBrowserCredentialProvider(createEndpointCredentialResolver(source.endpoint, {
+    fetch: options.fetch,
+    timeoutMs: source.timeoutMs,
+    allowCrossOrigin: source.allowCrossOrigin,
+  }), options.dangerouslyAllowBrowser);
+}

package/src/transport/connection/index.ts

@@ -1,4 +1,3 @@
 /** Shared connection lifecycle boundary. */
 export * from './manager.js';
-export * from './credentialLifecycle.js';
 export * from './networkProbe.js';

package/src/transport/connection/manager.ts

@@ -42,7 +42,7 @@
 
 import { probeNetwork, type ProbeResult } from './networkProbe.js';
 import type { AuthTokenGetter } from '../../auth/credentialSource.js';
-import type { CredentialRefreshOutcome } from './credentialLifecycle.js';
+import type { CredentialRefreshOutcome } from '../../sessions/lifecycle.js';
 import { noopLogger, type Logger } from '../../logger.js';
 import {
   noopSocketObservability,

package/src/transport/http/client.ts

@@ -21,7 +21,6 @@ import {
   createHttpTransport,
   type HttpTransport,
 } from './transport.js';
-import { modelWireNames } from '../../auth/capability.js';
 import type { HttpClientConfig } from './options.js';
 import type {
   CommitResource,
@@ -33,9 +32,6 @@ import type {
   ModelReadOptions,
   ModelMutationOptions,
   ModelList,
-  CreateSessionParams,
-  AbloSession,
-  SessionResource,
 } from '../../client/resources/httpResources.js';
 import { collectModelList, modelList } from '../../client/resources/httpResources.js';
 import { resolveCreateId } from '../../client/resources/modelCreate.js';
@@ -56,6 +52,7 @@ import {
   type FunctionalUpdateOptions,
 } from '../../client/resources/functionalUpdate.js';
 import type { HeldClaim, HeldLease } from '../../types/streams.js';
+import type { JsonValue } from '../../types/streams.js';
 import { AbloConnectionError, AbloValidationError } from '../../errors.js';
 import type { ReadDependency } from '../../coordination/schema.js';
 import {
@@ -65,8 +62,22 @@ import {
   prepareReadSet,
   type ReadSetContext,
 } from '../../commit/readSetContext.js';
-import { recordHttpCommitReceipt } from '../../commit/recordRuntime.js';
+import {
+  recordHttpCommitReceipt,
+  recordWebSocketCommitReceipt,
+} from '../../commit/recordRuntime.js';
 import type { EffectiveAuthority } from '../../auth/capability.js';
+import {
+  createWebSocketSession,
+} from '../websocket/session.js';
+import type {
+  AbloWebSocketSession,
+  WebSocketObservedDelta,
+} from '../websocket/sessionContract.js';
+import { subscribeWebSocketReadChanges } from '../websocket/contextSubscription.js';
+import type {
+  CoreSyncEventMap,
+} from '../websocket/transport.js';
 
 export interface AbloHttpClientOptions<S extends SchemaRecord>
   extends HttpClientConfig<S> {
@@ -76,6 +87,16 @@ export interface AbloHttpClientOptions<S extends SchemaRecord>
    * @default 30_000
    */
   readonly timeoutMs?: number;
+  /** Initial groups observed by a session-backed WebSocket client. */
+  readonly groups?: readonly string[];
+  /** Application frame names accepted by `subscribe` on the WebSocket transport. */
+  readonly collaborationEvents?: readonly string[];
+  /** Durable resume position for WebSocket observation. */
+  readonly cursorStore?: import('../../client/contract.js').ObserveCursorStore;
+  readonly cursorKey?: string;
+  readonly reconnectDelay?: number;
+  readonly maxReconnectDelay?: number;
+  readonly connectTimeoutMs?: number;
 }
 
 declare const capturedRowBrand: unique symbol;
@@ -98,7 +119,7 @@ export type HttpModelMutationParams<P> = Omit<P, 'reads'> & {
  * coordinated writes.
  * It deliberately omits the stateful client's local-only
  * reads (the `local` namespace) and live subscriptions (`onChange`), which need
- * a resident graph and a persistent socket; those are absent from the type, so
+ * a local graph and a persistent socket; those are absent from the type, so
  * reaching for one is a compile error rather than a runtime gap.
  *
  * This is also the base the reactive per-model surface is composed from, rather
@@ -174,7 +195,7 @@ export interface HttpModelClient<T, C = T> {
 
 /**
  * The type of the stateless HTTP client: a typed {@link HttpModelClient} per
- * schema model, plus `commits`, `dispose`, and the session-mint surface. It
+ * schema model, plus `commits` and lifecycle operations. It
  * exposes only what request/response transport can do, so reaching for a
  * stateful-only capability — the `local` reads, `onChange`, or the synchronous
  * `claim.state`/`queue`/`reorder` reads — is a compile error rather than a value
@@ -210,13 +231,30 @@ export type AbloHttpClient<S extends SchemaRecord> = {
   dispose(): Promise<void>;
   /** Resolves the bearer credential this client authenticates with, or `null` if none is set. */
   getAuthToken(): Promise<string | null>;
-  /**
-   * Mints a short-lived, scoped session token. Minting is itself a stateless
-   * request, so it is available here even though the local-cache reads are not.
-   * Pass `{ user }` to mint an end-user key (`ek_`) or `{ agent, can }` to mint a
-   * scoped agent key (`rk_`). See {@link CreateSessionParams}.
-  */
-  readonly sessions: SessionResource<S>;
+};
+
+/** The same typed resource client, with server-pushed capabilities carried by WebSocket. */
+export type AbloWebSocketClient<S extends SchemaRecord> = AbloHttpClient<S> & {
+  observe(options?: { signal?: AbortSignal }): AsyncIterable<WebSocketObservedDelta>;
+  subscribe<K extends keyof CoreSyncEventMap>(
+    event: K,
+    listener: (...args: CoreSyncEventMap[K]) => void,
+  ): () => void;
+  updateSubscription(
+    groups: readonly string[],
+    options?: { timeoutMs?: number },
+  ): Promise<{ groups: string[] }>;
+  readonly presence: {
+    update(input?: {
+      readonly status?: 'online' | 'away' | 'offline';
+      readonly customStatus?: string;
+      readonly timezone?: string;
+      readonly activity?: Readonly<Record<string, JsonValue>>;
+    }): Promise<void>;
+  };
+  readonly collaboration: {
+    send(event: string, payload: Readonly<Record<string, JsonValue>>): Promise<void>;
+  };
 };
 
 /**
@@ -232,7 +270,6 @@ const PROTOCOL_MEMBERS = new Set<string>([
   'logs',
   'identity',
   'getAuthToken',
-  'sessions',
 ]);
 
 /** Narrows a bare property name to a transport key so the facade can index it typed. */
@@ -489,26 +526,39 @@ function createHttpModelClient<T, C = T>(
 }
 
 /**
- * Builds the stateless, typed HTTP client. Each `client.<model>` resolves to the
- * protocol client's model accessor, while `commits`, `dispose`, and the other
- * protocol members pass through unchanged. No socket is ever opened; the bearer
- * credential is the identity.
+ * Builds the typed headless client. An API-key identity uses HTTP. A session
+ * identity uses one lazily opened WebSocket by default for commits and live
+ * coordination until `dispose()`; point reads and administration remain HTTP.
  */
-/** @internal Constructed only through the public `Ablo({ transport: 'http' })` factory. */
+/** @internal Constructed only through the public `Ablo()` factory. */
 export function createAbloHttpClient<S extends SchemaRecord>(
   options: AbloHttpClientOptions<S>,
-): AbloHttpClient<S> {
+): AbloHttpClient<S> | AbloWebSocketClient<S> {
   const { schema, onCommitReceipt, ...rest } = options;
+  const usesWebSocket = options.transport === 'websocket'
+    || (options.transport === undefined && options.session != null);
   const readSetContext = createReadSetContext();
   const transport: HttpTransport = createHttpTransport({
     ...rest,
-    // Derived from the schema this client is bound to, never assembled by hand
-    // — see `auth/capability.ts`.
-    modelTypenames: modelWireNames(schema.models),
     onCommitReceipt: (observation) => {
       recordHttpCommitReceipt(readSetContext, observation);
       onCommitReceipt?.(observation);
     },
+    ...(usesWebSocket ? {
+      dispatchCommit: async (input) => {
+        const receipt = await (await webSocketSession()).commit(input);
+        recordWebSocketCommitReceipt(readSetContext, {
+          receipt,
+          operations: input.operations,
+          reads: input.reads,
+        });
+        return receipt;
+      },
+      dispatchClaim: async (input) => (await webSocketSession()).claim(input),
+      releaseDispatchedClaim: (input) => {
+        void webSocketSession().then((session) => session.release(input));
+      },
+    } : {}),
   });
   const schemaModels = new Set(Object.keys(schema.models));
   const clientIdentity = {};
@@ -517,6 +567,56 @@ export function createAbloHttpClient<S extends SchemaRecord>(
     string,
     HttpModelClient<Record<string, unknown>, Record<string, unknown>>
   >();
+  let webSocket: AbloWebSocketSession | null = null;
+  let webSocketPromise: Promise<AbloWebSocketSession> | null = null;
+  const webSocketOpen = new AbortController();
+  let disposed = false;
+
+  const webSocketSession = (): Promise<AbloWebSocketSession> => {
+    if (disposed) {
+      return Promise.reject(new AbloConnectionError('This Ablo client is disposed.'));
+    }
+    if (webSocket) return Promise.resolve(webSocket);
+    if (webSocketPromise) return webSocketPromise;
+    webSocketPromise = (async () => {
+      await transport.ready();
+      const session = await createWebSocketSession({
+        baseUrl: rest.baseURL ?? undefined,
+        access: transport.access,
+        syncGroups: options.groups,
+        collaborationEvents: options.collaborationEvents,
+        cursorStore: options.cursorStore,
+        cursorKey: options.cursorKey,
+        reconnectDelay: options.reconnectDelay,
+        maxReconnectDelay: options.maxReconnectDelay,
+        connectTimeoutMs: options.connectTimeoutMs,
+      }, webSocketOpen.signal);
+      if (disposed) {
+        await session.close();
+        throw new AbloConnectionError('This Ablo client is disposed.');
+      }
+      webSocket = session;
+      return session;
+    })().finally(() => {
+      webSocketPromise = null;
+    });
+    return webSocketPromise;
+  };
+
+  const ready = async (): Promise<void> => {
+    await transport.ready();
+    if (usesWebSocket) await webSocketSession();
+  };
+
+  const dispose = async (): Promise<void> => {
+    if (disposed) return;
+    disposed = true;
+    webSocketOpen.abort();
+    const opening = webSocketPromise;
+    if (webSocket) await webSocket.close();
+    else await opening?.then((session) => session.close()).catch(() => undefined);
+    await transport.dispose();
+  };
 
   const model = (
     name: string,
@@ -563,11 +663,55 @@ export function createAbloHttpClient<S extends SchemaRecord>(
         return {
           context: readSetContext,
           client: clientIdentity,
-          onChange: transport.onChange,
+          onChange: (reads: readonly ReadDependency[], listener: Parameters<typeof transport.onChange>[1]) =>
+            usesWebSocket
+              ? subscribeWhenConnected(webSocketSession, reads, listener)
+              : transport.onChange(reads, listener),
         };
       }
       if (typeof prop !== 'string') return undefined;
       if (prop === 'commits') return commits;
+      if (prop === 'ready') return ready;
+      if (prop === 'dispose') return dispose;
+      if (usesWebSocket && prop === 'observe') {
+        return async function* (observeOptions?: { signal?: AbortSignal }) {
+          yield* (await webSocketSession()).observe(observeOptions);
+        };
+      }
+      if (usesWebSocket && prop === 'subscribe') {
+        return <K extends keyof CoreSyncEventMap>(
+          event: K,
+          listener: (...args: CoreSyncEventMap[K]) => void,
+        ) => {
+          let stop: (() => void) | undefined;
+          let cancelled = false;
+          void webSocketSession().then((session) => {
+            if (!cancelled) stop = session.subscribe(event, listener);
+          });
+          return () => { cancelled = true; stop?.(); };
+        };
+      }
+      if (usesWebSocket && prop === 'updateSubscription') {
+        return async (groups: readonly string[], subscriptionOptions?: { timeoutMs?: number }) => {
+          const result = await (await webSocketSession()).updateSubscription(
+            groups,
+            subscriptionOptions,
+          );
+          return { groups: result.syncGroups };
+        };
+      }
+      if (usesWebSocket && prop === 'presence') {
+        return {
+          update: async (input?: Parameters<AbloWebSocketSession['presence']['update']>[0]) =>
+            (await webSocketSession()).presence.update(input),
+        };
+      }
+      if (usesWebSocket && prop === 'collaboration') {
+        return {
+          send: async (event: string, payload: Readonly<Record<string, JsonValue>>) =>
+            (await webSocketSession()).collaboration.send(event, payload),
+        };
+      }
       // Real protocol members pass through unchanged.
       if (isProtocolMember(prop)) {
         return transport[prop];
@@ -586,5 +730,18 @@ export function createAbloHttpClient<S extends SchemaRecord>(
   // A single boundary cast. `AbloHttpClient<S>` declares only what the model
   // accessor and the passed-through protocol members actually implement, so no
   // method on this type is missing at runtime.
-  return facade as AbloHttpClient<S>;
+  return facade as AbloHttpClient<S> | AbloWebSocketClient<S>;
+}
+
+function subscribeWhenConnected(
+  session: () => Promise<AbloWebSocketSession>,
+  reads: readonly ReadDependency[],
+  listener: Parameters<typeof subscribeWebSocketReadChanges>[2],
+): () => void {
+  let stop: (() => void) | undefined;
+  let cancelled = false;
+  void session().then((connected) => {
+    if (!cancelled) stop = subscribeWebSocketReadChanges(connected, reads, listener);
+  });
+  return () => { cancelled = true; stop?.(); };
 }

package/src/transport/http/options.ts

@@ -37,7 +37,10 @@ export interface HttpClientConfig<S extends SchemaRecord = SchemaRecord>
   commitOutbox?: DurableWriteStore;
   /** Compatibility input and internal child-client identity seam. */
   commitOutboxScope?: CommitOutboxScope;
-  /** Which transport carries this client's traffic. */
+  /**
+   * Which transport carries this client's traffic. Defaults to WebSocket for
+   * a scoped `session` and HTTP for an API key or direct auth token.
+   */
   transport?: 'websocket' | 'http' | undefined;
   /** @internal Exact receipt phases observed while dispatching one HTTP commit. */
   onCommitReceipt?: (observation: {