@peers-app/peers-sdk 0.19.13 → 0.20.0

package/dist/contracts/contract-proxy.d.ts

@@ -0,0 +1,333 @@
+import type { Table } from "../data/orm/table";
+import type { IToolInstance } from "../data/tools";
+import type { Event, ISubscriptionResult } from "../events";
+import { type Observable } from "../observable";
+import { type IContractTransport } from "./contract-transport";
+import type { IContractDefinition } from "./types";
+/**
+ * The RPC event name used to proxy a single {@link IContractCall} over a
+ * {@link Connection} (`connection.emit(CONTRACT_CALL_RPC, call)` on the consumer
+ * side; `connection.exposeRPC(CONTRACT_CALL_RPC, handler)` on the provider side).
+ *
+ * Alias of {@link CONTRACT_REQUEST_CHANNEL} — the fixed request/response channel of an
+ * {@link IContractTransport}. Kept for existing provider registrations that reference it.
+ */
+export declare const CONTRACT_CALL_RPC = "contractCall";
+/** The kind of contract member being invoked. */
+export type ContractMemberType = "table" | "tool" | "observable" | "event";
+/**
+ * A single, fully-serializable invocation against a contract member. This is the
+ * wire format passed between a contract **consumer** (which produces it) and a
+ * contract **provider** (which executes it) regardless of transport — same process,
+ * another iframe, or a remote device connection.
+ */
+export interface IContractCall {
+    /** Target contract id. */
+    contractId: string;
+    /** Target contract version. */
+    version: number;
+    /** Which kind of member is being invoked. */
+    member: ContractMemberType;
+    /** Name of the table / tool / observable within the contract. */
+    name: string;
+    /**
+     * Operation to perform on the member:
+     * - `table`: the table method name (`"list"`, `"get"`, `"save"`, …), or the reserved
+     *   `"subscribe"` / `"unsubscribe"` to (un)subscribe to a table event (see
+     *   {@link IContractCall.event}). A `Table` has no methods by those names, so they are
+     *   safe to reserve.
+     * - `tool`: always `"run"`
+     * - `observable`: `"get"` / `"set"` for one-shot reads/writes, or the reserved
+     *   `"subscribe"` / `"unsubscribe"` to (un)subscribe to the observable's value-change
+     *   stream. Unlike events, observable streaming is *not* consumer-gated: the consumer
+     *   subscribes implicitly when its proxy is built (see {@link IContractConsumer.observables}).
+     * - `event`: `"subscribe"` or `"unsubscribe"`
+     */
+    operation: string;
+    /** Positional arguments for the operation. */
+    args: unknown[];
+    /**
+     * Optional data context (group) requested by the consumer. The trusted provider host
+     * selects the canonical route; the current user-context provider defaults an omitted
+     * id to the local provider user's personal context.
+     */
+    dataContextId?: string;
+    /**
+     * For any subscription call (a generic `event`, a table `dataChanged`, or an observable
+     * value stream): the consumer-chosen id that ties a `"subscribe"` (and its later
+     * `"unsubscribe"`) to the {@link IContractNotification}s pushed back for it. Globally
+     * unique so a shared transport can multiplex many subscriptions.
+     */
+    subscriptionId?: string;
+    /**
+     * For a `table` member with a `"subscribe"` / `"unsubscribe"` operation: names the
+     * table event to subscribe to. Currently always `"dataChanged"`, which is also the
+     * default when absent. Not used by generic `event` members — those carry the event
+     * name in {@link IContractCall.name}.
+     */
+    event?: string;
+}
+/**
+ * A provider→consumer push delivered on {@link CONTRACT_NOTIFY_CHANNEL}. The consumer
+ * routes it purely by {@link IContractNotification.subscriptionId} to the handler that
+ * registered that id, so notifications for other consumers' subscriptions on a shared
+ * transport are simply ignored.
+ */
+export interface IContractNotification {
+    /** The subscription this payload belongs to (matches an earlier `event.subscribe`). */
+    subscriptionId: string;
+    /** The event payload emitted by the provider. */
+    value: unknown;
+    /** Originating contract id — informational, for debugging/logging only. */
+    contractId?: string;
+    /** Originating event name — informational, for debugging/logging only. */
+    name?: string;
+}
+/**
+ * The consumer-side proxy for a single contract table. Any accessed name is forwarded
+ * as a remote method call returning a promise, **except** `dataChanged`, which is a
+ * subscribable that rides the notify channel like a generic event (subscription-gated).
+ *
+ * Declared as an intersection so `dataChanged` type-checks as a subscribable while
+ * `.list(...)`, `.save(...)`, etc. still type-check as async methods. This is a widening
+ * of precise per-table typing (deferred to a later phase).
+ */
+export type IContractTableProxy = Record<string, (...args: any[]) => Promise<any>> & {
+    /**
+     * Subscribe to the provider table's `dataChanged` event over the transport.
+     * Subscription-gated and refcounted exactly like a generic contract event; returns an
+     * {@link ISubscriptionResult} whose `unsubscribe()` stops delivery.
+     */
+    dataChanged: {
+        subscribe(handler: (event: any) => void): ISubscriptionResult;
+    };
+};
+/**
+ * A live proxy over a contract, handed to a **consumer**. Every member access is
+ * turned into an {@link IContractCall} and dispatched through the transport, so the
+ * consumer interacts with the contract identically no matter where the provider runs.
+ */
+export interface IContractConsumer {
+    contractId: string;
+    version: number;
+    /**
+     * `tables[name].<method>(...args)` → the remote table method's result, or
+     * `tables[name].dataChanged.subscribe(handler)` → a subscription to the remote table's
+     * `dataChanged` event (see {@link IContractTableProxy}).
+     */
+    tables: Record<string, IContractTableProxy>;
+    /** `tools[name](...args)` → the remote tool's result. */
+    tools: Record<string, (...args: any[]) => Promise<any>>;
+    /**
+     * `observables[name]` is a live, callable {@link Observable} that mirrors the provider's
+     * observable: call it with no args to read the latest streamed value synchronously, or
+     * with a value to write it when the contract marks it writable (fire-and-forget;
+     * durability is awaitable via {@link IContractConsumer.loadingPromise}). A read-only
+     * write throws before changing the mirror or emitting. Unlike events and table `dataChanged`,
+     * observable streaming is *not* subscription-gated — the consumer subscribes implicitly
+     * when the proxy is built and the provider always streams changes, so the mirror is kept
+     * current for synchronous reads (see decision 4 in the implementation doc).
+     */
+    observables: Record<string, Observable<any>>;
+    /**
+     * `events[name].subscribe(handler)` → registers `handler` for provider pushes of that
+     * event and asks the provider to start sending. Returns an {@link ISubscriptionResult}
+     * whose `unsubscribe()` stops delivery and tells the provider to stop sending — the same
+     * shape as the local {@link Event} API, so consumers subscribe identically regardless of
+     * where the provider runs.
+     */
+    events: Record<string, {
+        subscribe: (handler: (value: any) => void) => ISubscriptionResult;
+    }>;
+    /**
+     * Resolves once every observable's initial snapshot has loaded (so reads are meaningful),
+     * then is re-chained on each local observable write so `await consumer.loadingPromise`
+     * also awaits write durability. Mirrors the persistent-var `loadingPromise` pattern
+     * ([`persistent-vars.ts`](../data/persistent-vars.ts)). Always resolves (never rejects);
+     * a failed writable set is logged once and leaves the optimistic mirror in place until
+     * the next provider push reconciles it.
+     */
+    loadingPromise: Promise<void>;
+    /**
+     * Idempotently detach everything this consumer opened: generic events, table events,
+     * always-on observable streams, observable write observers, and its notify listener.
+     * New remote table/tool calls and subscriptions reject after disposal; cached observable
+     * reads remain available, but observable writes throw.
+     */
+    dispose(): void;
+}
+/**
+ * Build the **consumer** side of a contract proxy from a contract definition and a
+ * transport. Member names come from the contract shape; table members are backed by a
+ * `Proxy` that forwards accessed method names. The provider accepts only standard data
+ * operations and custom methods marked by `ProxyClientTableMethodCalls`.
+ *
+ * Every access is turned into an {@link IContractCall} sent on the transport's fixed
+ * {@link CONTRACT_REQUEST_CHANNEL}; the resolved ack is the provider's return value.
+ *
+ * The consumer also subscribes to provider pushes: `events[name].subscribe(handler)` and
+ * `tables[name].dataChanged.subscribe(handler)` both send a `"subscribe"` request and
+ * demultiplex provider pushes arriving on {@link CONTRACT_NOTIFY_CHANNEL} by their
+ * `subscriptionId` (shared `subscribeVia` path). Observables use the same push channel but
+ * are *not* gated: each `observables[name]` is a live {@link Observable} mirror that subscribes
+ * implicitly at creation, loads an initial snapshot (awaitable via
+ * {@link IContractConsumer.loadingPromise}), and streams every subsequent change; local writes
+ * send a fire-and-forget `set`. Call {@link IContractConsumer.dispose} to remove the notify
+ * listener and unsubscribe every stream. Read-only observable writes are rejected on both
+ * consumer and provider boundaries. Disposal is idempotent and prevents new remote operations;
+ * cached observable reads remain available afterward.
+ *
+ * @param contract   The contract definition (shape) being consumed.
+ * @param transport  Bidirectional channel to the provider; requests go out on
+ *   {@link CONTRACT_REQUEST_CHANNEL}, notifications arrive on {@link CONTRACT_NOTIFY_CHANNEL}.
+ * @param opts.dataContextId  Optional data context to scope every call to.
+ */
+export declare function createContractConsumer(contract: IContractDefinition, transport: IContractTransport, opts?: {
+    dataContextId?: string;
+}): IContractConsumer;
+/**
+ * The live implementation a **provider** dispatches contract calls to. This is the
+ * runtime-callable counterpart to {@link IResolvedContract} (which additionally tracks
+ * the providing package); the proxy layer only needs the live members.
+ */
+export interface IContractResolution {
+    contractId: string;
+    version: number;
+    tables?: Record<string, Table<any>>;
+    tools?: Record<string, IToolInstance>;
+    observables?: Record<string, Observable<any>>;
+    /**
+     * Provider-owned write policy for live observables. A `set` is allowed only when the
+     * matching entry is explicitly `true`; crafted calls cannot bypass a contract's
+     * read-only declaration.
+     */
+    observableWritability?: Record<string, boolean>;
+    /**
+     * Live events the provider forwards from, keyed by contract event name. A
+     * {@link createContractProviderEndpoint} subscribes to these on demand and passes
+     * their payloads to its configured notification sink.
+     */
+    events?: Record<string, Event<any>>;
+}
+/** Identity of the caller, supplied by the transport layer for permission checks. */
+export interface IContractCallContext {
+    /** User id of the caller (e.g. the remote device's user), if known. */
+    callerUserId?: string;
+    /** User id of the local device executing the call. */
+    localUserId?: string;
+}
+/**
+ * A gate that decides whether a given call is allowed. Runs before dispatch on the
+ * provider side. Return `false` (or throw) to deny.
+ */
+export type ContractPermissionCheck = (call: IContractCall, context: IContractCallContext) => boolean | Promise<boolean>;
+/**
+ * Legacy gate that allows calls only when caller and provider user ids match.
+ *
+ * @deprecated Production connection routing uses the signed-identity, provider-personal
+ * Self-trust policy in `createUserContextContractProviderRouter`. Keep this helper only
+ * for compatibility and isolated in-process providers that intentionally need the old gate.
+ */
+export declare const sameUserContractPermissionCheck: ContractPermissionCheck;
+/**
+ * Build the **provider** side of a contract proxy: an async handler that permission-checks
+ * an {@link IContractCall} and dispatches it to the live table method / tool fn / observable
+ * accessor in the given resolution. Table dispatch is constrained to standard serializable
+ * data operations plus custom methods explicitly marked by `ProxyClientTableMethodCalls`;
+ * internal helpers, event properties, document/cursor helpers, and prototype properties
+ * are not remotely callable.
+ *
+ * @param resolution  The live contract implementation to dispatch to.
+ * @param opts.permissionCheck  Optional gate run before every dispatch.
+ */
+export declare function createContractProvider(resolution: IContractResolution, opts?: {
+    permissionCheck?: ContractPermissionCheck;
+}): (call: IContractCall, context?: IContractCallContext) => Promise<any>;
+/** Options for {@link createContractProviderSession}. */
+export interface IContractProviderSessionOptions {
+    /** Gate run before every request and every event `subscribe` (see {@link ContractPermissionCheck}). */
+    permissionCheck?: ContractPermissionCheck;
+    /**
+     * Caller identity used for permission checks when the transport does not deliver a
+     * per-call {@link IContractCallContext} as the request handler's second argument.
+     * In-process wiring typically sets this; a real connection supplies context per call.
+     */
+    context?: IContractCallContext;
+}
+/**
+ * A stateful provider endpoint bound to a single {@link IContractTransport}. Unlike the
+ * stateless {@link createContractProvider}, a session also handles subscriptions on every
+ * streamable member: generic `event` members, table events (`table` member with
+ * `subscribe`/`unsubscribe`, e.g. `dataChanged`), and observable value streams (`observable`
+ * member with `subscribe`/`unsubscribe`). It tracks per-consumer subscriptions and pushes
+ * matching payloads back independently on {@link CONTRACT_NOTIFY_CHANNEL}. Duplicate
+ * subscription ids are rejected without disturbing the existing subscription. Call
+ * {@link IContractProviderSession.dispose} to remove the request listener and detach every
+ * live subscription.
+ */
+export interface IContractProviderSession {
+    /** Tear down the request listener and all live subscriptions. */
+    dispose(): void;
+}
+/**
+ * Delivers a provider notification to the transport or host router that owns an
+ * {@link IContractProviderEndpoint}.
+ */
+export type ContractNotificationSink = (notification: IContractNotification) => Promise<unknown>;
+/** Options for {@link createContractProviderEndpoint}. */
+export interface IContractProviderEndpointOptions {
+    /** Delivers subscription payloads without binding the endpoint to a transport. */
+    notify: ContractNotificationSink;
+    /** Optional defense-in-depth gate run before calls and subscription creation. */
+    permissionCheck?: ContractPermissionCheck;
+    /** Default caller identity when {@link IContractProviderEndpoint.handleCall} omits it. */
+    context?: IContractCallContext;
+}
+/**
+ * Stateful provider dispatcher independent of any particular transport. A host router can
+ * cache one endpoint per contract/version/data-context route, or a transport-bound provider
+ * session can wrap it for backward compatibility.
+ */
+export interface IContractProviderEndpoint {
+    /**
+     * Dispatch a request/response or subscription call. Subscribe operations are permission
+     * checked and tracked; unsubscribe is idempotent and intentionally skips reauthorization.
+     */
+    handleCall(call: IContractCall, context?: IContractCallContext): Promise<any>;
+    /** Detach every live subscription. Idempotent. */
+    dispose(): void;
+}
+/**
+ * Build a stateful **provider endpoint**: it serves the same request/response dispatch as
+ * {@link createContractProvider} for table/tool/observable calls, and additionally serves
+ * subscriptions on any streamable member — generic `event` calls, table events (a `table`
+ * member with `"subscribe"` / `"unsubscribe"`, resolving `dataChanged` by default), and
+ * observable value streams (an `observable` member with `"subscribe"` / `"unsubscribe"`;
+ * `get`/`set` still flow to the stateless dispatch).
+ *
+ * The live source — an {@link Event} (`resolution.events[name]` or a table's `dataChanged`)
+ * or an {@link Observable} (`resolution.observables[name]`) — is only subscribed to while at
+ * least one consumer holds a subscription (refcounted by a resolved key), and each payload is
+ * fanned out through the supplied {@link ContractNotificationSink} as an
+ * {@link IContractNotification}. The endpoint owns no request listener, which lets a
+ * connection-wide router multiplex many endpoints through one request channel and later
+ * substitute sandbox-backed endpoint implementations.
+ *
+ * @param resolution  The live contract implementation to dispatch to and stream from.
+ * @param opts         Notification sink plus optional permission gate and default context.
+ */
+export declare function createContractProviderEndpoint(resolution: IContractResolution, opts: IContractProviderEndpointOptions): IContractProviderEndpoint;
+/**
+ * Build the backward-compatible transport-bound provider session. The session owns the
+ * transport's request listener while its underlying {@link IContractProviderEndpoint} owns
+ * request dispatch and live subscription state.
+ *
+ * Use {@link createContractProviderEndpoint} behind a connection-wide router when multiple
+ * contracts or data contexts share one transport.
+ *
+ * @param resolution  The live contract implementation to dispatch to and stream from.
+ * @param transport   Requests arrive on {@link CONTRACT_REQUEST_CHANNEL}; notifications are
+ *   emitted on {@link CONTRACT_NOTIFY_CHANNEL}.
+ * @param opts        Optional permission gate and default caller context.
+ */
+export declare function createContractProviderSession(resolution: IContractResolution, transport: IContractTransport, opts?: IContractProviderSessionOptions): IContractProviderSession;