@prosody-events/prosody 0.3.1 → 0.5.0

package/index.d.ts

@@ -5,14 +5,80 @@
  */
 
 import type {
+  AdminClient,
   Configuration,
   ConsumerState,
-  Message,
+  ExciseMessage as NativeExciseMessage,
+  Message as NativeMessage,
   Mode,
+  ReadCacheConfiguration,
   Timer,
 } from "./bindings";
 
-export { Configuration, ConsumerState, Message, Timer, Mode };
+export {
+  AdminClient,
+  Configuration,
+  ConsumerState,
+  ReadCacheConfiguration,
+  Timer,
+  Mode,
+};
+
+/** Exports all pending telemetry data. */
+export function flushTelemetry(): void;
+
+/** Stops the global telemetry providers after they export pending data. */
+export function shutdownTelemetry(): void;
+
+/** A primitive value representable in JSON. */
+export type JsonPrimitive = null | boolean | number | string;
+
+/**
+ * Any value representable in JSON.
+ *
+ * This is a compile-time contract. Prosody serializes payloads at runtime but
+ * does not validate them against a more specific application payload type.
+ */
+export type JsonValue =
+  JsonPrimitive | readonly JsonValue[] | { readonly [key: string]: JsonValue };
+
+/**
+ * Maps an application type to its JSON-compatible shape. This lets APIs
+ * accept ordinary interfaces and type aliases without requiring an index
+ * signature, while rejecting non-JSON members wherever they are nested.
+ */
+export type JsonCompatible<T> = T extends JsonPrimitive
+  ? T
+  : T extends bigint | symbol | undefined | ((...args: never[]) => unknown)
+    ? never
+    : T extends readonly (infer Item)[]
+      ? readonly JsonCompatible<Item>[]
+      : T extends object
+        ? { readonly [Key in keyof T]: JsonCompatible<T[Key]> }
+        : never;
+
+/** A value that a handler can return now or through a promise. */
+export type MaybePromise<T> = T | PromiseLike<T>;
+
+/**
+ * Represents a message consumed from a Kafka topic.
+ *
+ * The optional payload type parameter is annotation-level only: the runtime
+ * payload is unchanged. An unparameterized `Message` uses {@link JsonValue};
+ * provide an application payload type for precise field-level checking.
+ * Message-backed keyed-state collections vend their items as `Message<P>`.
+ *
+ * A message can be stored into a message collection, whether it arrived from the
+ * topic or was read back out of a collection. What is stored is the message
+ * itself, so mutating its parsed `payload` does not change what is written.
+ */
+export interface Message<P = JsonValue> extends Omit<NativeMessage, "payload"> {
+  /** The message payload as a JSON-serializable value. */
+  payload: P;
+}
+
+/** An excise record with Kafka metadata and no payload. */
+export type ExciseMessage = NativeExciseMessage;
 
 /**
  * Wrapper around `MessageContext` for use in Node.js bindings.
@@ -74,6 +140,454 @@ export declare class Context {
    * @throws Error if retrieval fails.
    */
   scheduled(): Promise<Array<Date>>;
+
+  /**
+   * Binds a registered message single-value collection, vending a handle whose
+   * item is the full `Message<P>`.
+   *
+   * The handle and any iterator it opens are valid only within this event
+   * attempt. Throws a {@link PermanentStateError} if the collection name is
+   * unregistered or its registered identity mismatches.
+   * @param definition - A definition from {@link messageValue}.
+   */
+  state<P>(definition: MessageValueDefinition<P>): ValueState<Message<P>>;
+  /**
+   * Binds a registered message ordered-map collection, vending a handle whose
+   * values are the full `Message<P>`. Valid only within this event attempt;
+   * throws {@link PermanentStateError} on an unregistered name or identity
+   * mismatch.
+   * @param definition - A definition from {@link messageMap}.
+   */
+  state<P>(definition: MessageMapDefinition<P>): MapState<Message<P>>;
+  /**
+   * Binds a registered message deque collection, vending a handle whose
+   * elements are the full `Message<P>`. Valid only within this event attempt;
+   * throws {@link PermanentStateError} on an unregistered name or identity
+   * mismatch.
+   * @param definition - A definition from {@link messageDeque}.
+   */
+  state<P>(definition: MessageDequeDefinition<P>): DequeState<Message<P>>;
+  /**
+   * Binds a registered single-value JSON collection. Valid only within this
+   * event attempt; throws {@link PermanentStateError} on an unregistered name
+   * or identity mismatch.
+   * @param definition - A definition from {@link value}.
+   */
+  state<T>(definition: ValueDefinition<T>): ValueState<T>;
+  /**
+   * Binds a registered ordered-map JSON collection (string keys). Valid only
+   * within this event attempt; throws {@link PermanentStateError} on an
+   * unregistered name or identity mismatch.
+   * @param definition - A definition from {@link map}.
+   */
+  state<V>(definition: MapDefinition<V>): MapState<V>;
+  /**
+   * Binds a registered deque JSON collection. Valid only within this event
+   * attempt; throws {@link PermanentStateError} on an unregistered name or
+   * identity mismatch.
+   * @param definition - A definition from {@link deque}.
+   */
+  state<T>(definition: DequeDefinition<T>): DequeState<T>;
+}
+
+/**
+ * Scan direction over a map or deque collection. `"forward"` visits a map in
+ * ascending key order and a deque from front to back; `"backward"` reverses
+ * each. Defaults to `"forward"` wherever it is optional.
+ */
+export type ScanDirection = "forward" | "backward";
+
+/** Options accepted by every keyed-state definition constructor. */
+export interface StateDefinitionOptions {
+  /**
+   * Optional per-write TTL in whole seconds. Must be at least 1 and must
+   * exceed the client's recovery delay (enforced core-side).
+   */
+  ttlSeconds?: number;
+  /**
+   * Opt out of transactional staging (read-uncommitted, at-least-once).
+   * Defaults to transactional.
+   */
+  readUncommitted?: boolean;
+}
+
+/** Options accepted by JSON collections that may be published. */
+export interface PublishedStateDefinitionOptions extends StateDefinitionOptions {
+  /** Allow read-only access from other consumer groups. */
+  published?: boolean;
+  /** Override caching when this descriptor opens a published reader. */
+  readCache?: ReadCacheOptions | false;
+}
+
+/** Options accepted by the map definition constructors. */
+export interface MapDefinitionOptions extends PublishedStateDefinitionOptions {
+  /**
+   * Keyset bound for ordered scans (`0..=4096`; default 128 core-side; `0`
+   * disables ordered-scan tracking). Map collections only.
+   */
+  keysetLimit?: number;
+}
+
+/** Options accepted by the deque definition constructors. */
+export interface DequeDefinitionOptions extends PublishedStateDefinitionOptions {
+  /**
+   * Optional maximum element count (bounded backlog). Must be a whole number
+   * >= 1. Runtime-only: not persisted, not part of collection identity, and
+   * changeable across deploys. Enforced lazily on push — the opposite end is
+   * evicted toward the bound (no decode, no fetch); a shrunk deque reports its
+   * old length until the next push trims it. Deque collections only.
+   */
+  capacity?: number;
+}
+
+/** Options accepted by message-map definitions, which cannot be published. */
+export interface MessageMapDefinitionOptions extends StateDefinitionOptions {
+  /** Keyset bound for ordered scans (`0..=4096`; default 128 core-side). */
+  keysetLimit?: number;
+}
+
+/** Options accepted by message-deque definitions, which cannot be published. */
+export interface MessageDequeDefinitionOptions extends StateDefinitionOptions {
+  /** Optional maximum element count. Must be a whole number >= 1. */
+  capacity?: number;
+}
+
+/**
+ * Phantom brand carrying a definition's item type. Never present at runtime —
+ * it exists only so the item type survives on the frozen definition object and
+ * flows into the vended handle.
+ */
+declare const StateItem: unique symbol;
+declare const StateDescriptor: unique symbol;
+
+interface DefinitionBrand {
+  readonly [StateDescriptor]: true;
+}
+
+/** A frozen single-value JSON collection definition. */
+export interface ValueDefinition<T = JsonValue> extends DefinitionBrand {
+  readonly name: string;
+  readonly kind: "value";
+  readonly payload: "json";
+  readonly ttlSeconds?: number;
+  readonly readUncommitted?: boolean;
+  readonly published?: boolean;
+  readonly readCache?: ReadCacheOptions | false;
+  readonly [StateItem]?: T;
+}
+
+/** A frozen ordered-map JSON collection definition (string keys). */
+export interface MapDefinition<V = JsonValue> extends DefinitionBrand {
+  readonly name: string;
+  readonly kind: "map";
+  readonly payload: "json";
+  readonly ttlSeconds?: number;
+  readonly readUncommitted?: boolean;
+  readonly published?: boolean;
+  readonly readCache?: ReadCacheOptions | false;
+  readonly keysetLimit?: number;
+  readonly [StateItem]?: V;
+}
+
+/** A frozen deque JSON collection definition. */
+export interface DequeDefinition<T = JsonValue> extends DefinitionBrand {
+  readonly name: string;
+  readonly kind: "deque";
+  readonly payload: "json";
+  readonly ttlSeconds?: number;
+  readonly readUncommitted?: boolean;
+  readonly published?: boolean;
+  readonly readCache?: ReadCacheOptions | false;
+  readonly capacity?: number;
+  readonly [StateItem]?: T;
+}
+
+/** A frozen single-value message collection definition (items are `Message<P>`). */
+export interface MessageValueDefinition<P = JsonValue> extends DefinitionBrand {
+  readonly name: string;
+  readonly kind: "value";
+  readonly payload: "message";
+  readonly ttlSeconds?: number;
+  readonly readUncommitted?: boolean;
+  readonly [StateItem]?: P;
+}
+
+/** A frozen ordered-map message collection definition (values are `Message<P>`). */
+export interface MessageMapDefinition<P = JsonValue> extends DefinitionBrand {
+  readonly name: string;
+  readonly kind: "map";
+  readonly payload: "message";
+  readonly ttlSeconds?: number;
+  readonly readUncommitted?: boolean;
+  readonly keysetLimit?: number;
+  readonly [StateItem]?: P;
+}
+
+/** A frozen deque message collection definition (elements are `Message<P>`). */
+export interface MessageDequeDefinition<P = JsonValue> extends DefinitionBrand {
+  readonly name: string;
+  readonly kind: "deque";
+  readonly payload: "message";
+  readonly ttlSeconds?: number;
+  readonly readUncommitted?: boolean;
+  readonly capacity?: number;
+  readonly [StateItem]?: P;
+}
+
+/**
+ * Declares a single-value JSON collection. The returned frozen definition is
+ * the single source of typing: place it in `Configuration.stateCollections` to
+ * register the collection, and pass it to `Context.state()` to vend a typed
+ * handle. The type parameter annotates the stored value and is compile-time
+ * only — payloads cross as plain JSON with no runtime validation.
+ * @param name - The collection name (unique per client).
+ * @param options - Optional retention, transaction, publication, and read-cache
+ *   settings.
+ */
+export function value<T = JsonValue>(
+  name: string,
+  options?: PublishedStateDefinitionOptions,
+): ValueDefinition<T>;
+
+/**
+ * Declares an ordered-map JSON collection. Map keys are always `string`. The
+ * returned frozen definition is used both in `Configuration.stateCollections`
+ * and with `Context.state()`. The type parameter annotates the stored value
+ * (compile-time only).
+ * @param name - The collection name (unique per client).
+ * @param options - Optional retention, transaction, publication, read-cache,
+ *   and `keysetLimit` settings.
+ */
+export function map<V = JsonValue>(
+  name: string,
+  options?: MapDefinitionOptions,
+): MapDefinition<V>;
+
+/**
+ * Declares a double-ended-queue JSON collection. The returned frozen definition
+ * is used both in `Configuration.stateCollections` and with `Context.state()`.
+ * The type parameter annotates the stored element (compile-time only).
+ * @param name - The collection name (unique per client).
+ * @param options - Optional retention, transaction, publication, read-cache,
+ *   and `capacity` settings.
+ */
+export function deque<T = JsonValue>(
+  name: string,
+  options?: DequeDefinitionOptions,
+): DequeDefinition<T>;
+
+/**
+ * Declares a single-value message collection: each stored item is the full
+ * Kafka `Message<P>` the handler received. The type parameter annotates the
+ * message payload (compile-time only).
+ * @param name - The collection name (unique per client).
+ * @param options - Optional `ttlSeconds` (whole seconds) and `readUncommitted`.
+ */
+export function messageValue<P = JsonValue>(
+  name: string,
+  options?: StateDefinitionOptions,
+): MessageValueDefinition<P>;
+
+/**
+ * Declares an ordered-map message collection (string keys; values are the full
+ * Kafka `Message<P>`). The type parameter annotates the message payload
+ * (compile-time only).
+ * @param name - The collection name (unique per client).
+ * @param options - Optional `ttlSeconds`, `readUncommitted`, and `keysetLimit`.
+ */
+export function messageMap<P = JsonValue>(
+  name: string,
+  options?: MessageMapDefinitionOptions,
+): MessageMapDefinition<P>;
+
+/**
+ * Declares a double-ended-queue message collection: each stored element is the
+ * full Kafka `Message<P>`. The type parameter annotates the message payload
+ * (compile-time only).
+ * @param name - The collection name (unique per client).
+ * @param options - Optional `ttlSeconds` (whole seconds), `readUncommitted`, and
+ *   `capacity` (bounded backlog; enforced lazily on push).
+ */
+export function messageDeque<P = JsonValue>(
+  name: string,
+  options?: MessageDequeDefinitionOptions,
+): MessageDequeDefinition<P>;
+
+/**
+ * Typed handle over a single-value keyed-state collection, vended by
+ * `Context.state()`. Valid only within the handler invocation (attempt) that
+ * vended it. Every method opens its own per-operation trace span.
+ */
+export declare class ValueState<T = JsonValue> {
+  /** Vended only by {@link Context#state}; not constructible directly. */
+  private constructor(native: unknown);
+  /** Reads the current value, or null when absent/cleared. */
+  get(): Promise<T | null>;
+  /**
+   * Buffers a write of the value. The parameter type excludes `null`/`undefined`
+   * (via {@link !NonNullable}) because a top-level `null` is not a storable
+   * value — writing one (or an unrepresentable value) is a caller mistake,
+   * rejected at runtime with a {@link TransientStateError} naming `clear()` —
+   * use {@link ValueState#clear}. Transient so it retries and stays visible
+   * rather than discarding the message. (Nested `null`, e.g. inside an object or
+   * array, is permitted and round-trips.)
+   */
+  set(value: NonNullable<T>): Promise<void>;
+  /** Deletes the stored value. */
+  clear(): Promise<void>;
+  /**
+   * Durably commits the buffered operations mid-handler (at-least-once).
+   * Resolves with no value — the erased seam drops the store outcome.
+   */
+  commit(): Promise<void>;
+  /** Discards buffered uncommitted operations back to the committed floor. */
+  rollback(): Promise<void>;
+}
+
+/**
+ * Typed handle over an ordered-map keyed-state collection, vended by
+ * `Context.state()`. Map keys are always `string`. Valid only within the
+ * handler invocation (attempt) that vended it. Every method opens its own
+ * per-operation trace span.
+ */
+export declare class MapState<V = JsonValue> {
+  /** Vended only by {@link Context#state}; not constructible directly. */
+  private constructor(native: unknown);
+  /** Reads the value for `key`, or null when the key is absent. */
+  get(key: string): Promise<V | null>;
+  /**
+   * Reads several keys in a single call. Returns an array with one entry per
+   * key, in the same order you asked, so `result[i]` is the value for
+   * `keys[i]`. A key that isn't there comes back as `null`, and a key you list
+   * more than once is answered at each spot. The whole read happens as one
+   * step, so no other change to this event's state can slip in partway through.
+   */
+  getMany(keys: readonly string[]): Promise<(V | null)[]>;
+  /**
+   * Reports whether `key` currently has a stored value. A presence check that
+   * skips the value decode and the resolver: for a message-backed map it
+   * answers with zero Kafka fetches and can report `true` for a message that
+   * can no longer be fetched. Not zero-I/O — a cache miss can still reach the
+   * store — but cheaper than {@link MapState#get} when you only need presence.
+   */
+  has(key: string): Promise<boolean>;
+  /**
+   * Inserts or overwrites `key`. The value type excludes `null`/`undefined`
+   * (via {@link !NonNullable}) because a top-level `null` is not a storable
+   * value — writing one (or an unrepresentable value) is a caller mistake,
+   * rejected at runtime with a {@link TransientStateError} — use
+   * {@link MapState#delete} to remove. Transient so it retries and stays visible
+   * rather than discarding the message. (Nested `null` is permitted.)
+   */
+  set(key: string, value: NonNullable<V>): Promise<void>;
+  /**
+   * Removes `key`.
+   *
+   * Deliberate divergence from `Map#delete`: returns void, NOT a boolean
+   * "was present" flag — surfacing that boolean would force a hidden read on
+   * every delete. (The underlying native operation is named `remove`.)
+   */
+  delete(key: string): Promise<void>;
+  /** Removes every entry. */
+  clear(): Promise<void>;
+  /**
+   * Async iterator over the live `[key, value]` entries in key order. Valid
+   * only within the handler invocation (attempt) that opened it; early exit
+   * from a `for await` loop closes the underlying cursor.
+   */
+  entries(direction?: ScanDirection): AsyncIterableIterator<[string, V]>;
+  /**
+   * Async iterator over the live keys in key order. Skips the value decode and
+   * the resolver, so a message-backed map enumerates keys with zero Kafka
+   * fetches; it still reads presence, so it is not zero-I/O. Valid only within
+   * the handler invocation (attempt) that opened it; early exit from a
+   * `for await` loop closes the underlying cursor.
+   */
+  keys(direction?: ScanDirection): AsyncIterableIterator<string>;
+  /**
+   * Async iterator over the live values in key order. Valid only within the
+   * handler invocation (attempt) that opened it; early exit from a `for await`
+   * loop closes the underlying cursor.
+   */
+  values(direction?: ScanDirection): AsyncIterableIterator<V>;
+  /**
+   * Forward iteration over `[key, value]` entries. Valid only within the
+   * handler invocation (attempt) that opened it.
+   */
+  [Symbol.asyncIterator](): AsyncIterableIterator<[string, V]>;
+  /**
+   * Durably commits the buffered operations mid-handler (at-least-once).
+   * Resolves with no value — the erased seam drops the store outcome.
+   */
+  commit(): Promise<void>;
+  /** Discards buffered uncommitted operations back to the committed floor. */
+  rollback(): Promise<void>;
+}
+
+/**
+ * Typed handle over a double-ended-queue keyed-state collection, vended by
+ * `Context.state()`. Valid only within the handler invocation (attempt) that
+ * vended it. Every method opens its own per-operation trace span.
+ */
+export declare class DequeState<T = JsonValue> {
+  /** Vended only by {@link Context#state}; not constructible directly. */
+  private constructor(native: unknown);
+  /**
+   * Appends an element at the back. The item type excludes `null`/`undefined`
+   * (via {@link !NonNullable}) because a top-level `null` is not a storable
+   * element — writing one (or an unrepresentable value) is a caller mistake,
+   * rejected at runtime with a {@link TransientStateError} so it retries and
+   * stays visible rather than discarding the message. (Nested `null` is
+   * permitted.)
+   */
+  push(item: NonNullable<T>): Promise<void>;
+  /**
+   * Prepends an element at the front. The item type excludes `null`/`undefined`
+   * (via {@link !NonNullable}); see {@link DequeState#push}.
+   */
+  unshift(item: NonNullable<T>): Promise<void>;
+  /** Removes and returns the back element, or null when empty. */
+  pop(): Promise<T | null>;
+  /** Removes and returns the front element, or null when empty. */
+  shift(): Promise<T | null>;
+  /** Returns the number of live elements. */
+  length(): Promise<number>;
+  /** Reports whether the deque holds no live elements. */
+  isEmpty(): Promise<boolean>;
+  /** Removes every element. */
+  clear(): Promise<void>;
+  /**
+   * Reads the element at `index`, like `Array.prototype.at`: a non-negative
+   * `index` counts from the front (`0` is the front), a negative `index` counts
+   * back from the end (`-1` is the back). Any out-of-range position — including
+   * every index on an empty deque — resolves to null. `index` must be a safe
+   * integer; a fractional, `NaN`, or infinite value is a caller mistake,
+   * rejected with a {@link TransientStateError} (it retries and stays visible).
+   *
+   * The endpoints `at(0)` and `at(-1)` ride the front/back peeks — a single
+   * read, and `at(-1)` makes no length read. Any other negative `index` is
+   * resolved against the current {@link DequeState#length}, so it makes an
+   * extra boundary crossing that a non-negative one does not.
+   */
+  at(index: number): Promise<T | null>;
+  /**
+   * Async iterator over the live elements in index order. Valid only within
+   * the handler invocation (attempt) that opened it; early exit from a
+   * `for await` loop closes the underlying cursor.
+   */
+  values(direction?: ScanDirection): AsyncIterableIterator<T>;
+  /**
+   * Forward iteration over the elements. Valid only within the handler
+   * invocation (attempt) that opened it.
+   */
+  [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+  /**
+   * Durably commits the buffered operations mid-handler (at-least-once).
+   * Resolves with no value — the erased seam drops the store outcome.
+   */
+  commit(): Promise<void>;
+  /** Discards buffered uncommitted operations back to the committed floor. */
+  rollback(): Promise<void>;
 }
 
 /**
@@ -83,31 +597,52 @@ export declare class Context {
  */
 export interface Logger {
   /** Logs error-level messages. */
-  error: (message: string | undefined | null, metadata?: any) => void;
+  error: (
+    message: string | undefined | null,
+    metadata?: Record<string, unknown>,
+  ) => void;
   /** Logs warning-level messages. */
-  warn: (message: string | undefined | null, metadata?: any) => void;
+  warn: (
+    message: string | undefined | null,
+    metadata?: Record<string, unknown>,
+  ) => void;
   /** Logs info-level messages. */
-  info: (message: string | undefined | null, metadata?: any) => void;
+  info: (
+    message: string | undefined | null,
+    metadata?: Record<string, unknown>,
+  ) => void;
   /** Logs debug-level messages. */
-  debug: (message: string | undefined | null, metadata?: any) => void;
+  debug: (
+    message: string | undefined | null,
+    metadata?: Record<string, unknown>,
+  ) => void;
   /** Logs trace-level messages. */
-  trace: (message: string | undefined | null, metadata?: any) => void;
+  trace: (
+    message: string | undefined | null,
+    metadata?: Record<string, unknown>,
+  ) => void;
 }
 
-export interface EventHandler {
+export interface EventHandler<P = JsonValue, R = JsonValue> {
+  /** Handles an excise record. */
+  onExcise: (
+    context: Context,
+    message: ExciseMessage,
+    signal: AbortSignal,
+  ) => MaybePromise<R & JsonCompatible<R>>;
   /**
    * Callback function to handle incoming messages.
    *
    * @param context - The context of the message processing.
    * @param message - The received Kafka message.
    * @param signal - An AbortSignal that can be used to cancel the message processing.
-   * @returns A promise that resolves when the message has been processed.
+   * @returns A JSON response for subsystem requests. JSON null is valid.
    */
-  onMessage?: (
+  onMessage: (
     context: Context,
-    message: Message,
+    message: Message<P>,
     signal: AbortSignal,
-  ) => Promise<void>;
+  ) => MaybePromise<R & JsonCompatible<R>>;
 
   /**
    * Callback function to handle timers.
@@ -115,22 +650,56 @@ export interface EventHandler {
    * @param context - The context of the message processing.
    * @param timer - The triggered timer.
    * @param signal - An AbortSignal that can be used to cancel the message processing.
-   * @returns A promise that resolves when the timer has been processed.
+   * @returns No value.
    */
-  onTimer?: (
+  onTimer: (
     context: Context,
     timer: Timer,
     signal: AbortSignal,
-  ) => Promise<void>;
+  ) => MaybePromise<void>;
+}
+
+/** One successful subsystem outcome. */
+export interface Success<T> {
+  readonly ok: true;
+  readonly value: T;
+}
+
+/** One failed subsystem outcome. */
+export interface Failure {
+  readonly ok: false;
+  readonly error: ResponseError;
+}
+
+/** One subsystem outcome. */
+export type Outcome<T> = Success<T> | Failure;
+
+/** One subsystem failure. */
+export type ResponseError =
+  | { readonly kind: "handler"; readonly message: string }
+  | { readonly kind: "timeout"; readonly message: string }
+  | { readonly kind: "formatMismatch"; readonly message: string }
+  | { readonly kind: "malformedResponse"; readonly message: string };
+
+/** Request targets, deadline, and cancellation. */
+export interface RequestOptions {
+  /** The subsystems that must respond. */
+  readonly subsystems: readonly string[];
+  /** The response deadline in milliseconds. */
+  readonly timeoutMs: number;
+  /** Cancels the local wait. */
+  readonly signal?: AbortSignal;
 }
 
 export declare class ProsodyClient {
+  private constructor();
+
   /**
-   * Creates a new ProsodyClient instance.
+   * Creates a Prosody client without blocking the Node.js event loop.
    *
    * @param config - The configuration options for the client.
    */
-  constructor(config: Configuration);
+  static create(config: Configuration): Promise<ProsodyClient>;
 
   /**
    * Gets the current state of the consumer.
@@ -156,6 +725,22 @@ export declare class ProsodyClient {
    */
   isStalled(): Promise<boolean>;
 
+  /** Opens a read-only view of a published JSON value collection. */
+  state<T>(
+    subsystem: string,
+    definition: ValueDefinition<T>,
+  ): Promise<PublishedValue<T>>;
+  /** Opens a read-only view of a published JSON map collection. */
+  state<V>(
+    subsystem: string,
+    definition: MapDefinition<V>,
+  ): Promise<PublishedMap<V>>;
+  /** Opens a read-only view of a published JSON deque collection. */
+  state<T>(
+    subsystem: string,
+    definition: DequeDefinition<T>,
+  ): Promise<PublishedDeque<T>>;
+
   /**
    * Gets the source system identifier configured for the client.
    *
@@ -173,29 +758,96 @@ export declare class ProsodyClient {
    * @returns A promise that resolves when the message has been successfully sent.
    * @throws Error if the send operation fails or is aborted.
    */
-  send(
+  send<P>(
     topic: string,
     key: string,
-    payload: unknown,
+    payload: P & JsonCompatible<P>,
     signal?: AbortSignal,
   ): Promise<void>;
 
+  /** Sends an excise record for a key. */
+  excise(topic: string, key: string, signal?: AbortSignal): Promise<void>;
+
+  /**
+   * Sends a request and returns one outcome for each subsystem.
+   *
+   * The map contains every selected subsystem. A missing response has a timeout outcome.
+   * @throws Error if the input is invalid, sending fails, shutdown starts, or the signal aborts.
+   */
+  request<R = JsonValue>(
+    topic: string,
+    key: string,
+    payload: JsonValue,
+    options: RequestOptions,
+  ): Promise<ReadonlyMap<string, Outcome<R>>>;
+
+  /** Sends an excise request and returns one outcome for each subsystem. */
+  requestExcise<R = JsonValue>(
+    topic: string,
+    key: string,
+    options: RequestOptions,
+  ): Promise<ReadonlyMap<string, Outcome<R>>>;
+
   /**
    * Subscribes to receive messages using the provided event handler.
    *
    * @param eventHandler - The event handler to process received messages and timers.
    * @returns A promise that resolves when the subscription is successfully established and the consumer is ready to receive messages.
+   * @throws TypeError if any required handler method is missing.
    * @throws Error if the subscription fails to establish.
    */
-  subscribe(eventHandler: EventHandler): Promise<void>;
+  subscribe<P = JsonValue, R = JsonValue>(
+    eventHandler: EventHandler<P, R>,
+  ): Promise<void>;
 
   /**
-   * Unsubscribes from receiving messages and shuts down the consumer.
+   * Stops the consumer. You can subscribe again later.
    *
    * @returns A promise that resolves when the unsubscribe operation is complete.
    * @throws Error if the unsubscribe operation fails.
    */
   unsubscribe(): Promise<void>;
+
+  /**
+   * Shuts down the client and all its services.
+   * Concurrent and repeated calls await the same shutdown operation.
+   *
+   * @returns A promise that resolves when shutdown is complete.
+   * @throws Error if shutdown fails.
+   */
+  shutdown(): Promise<void>;
+}
+
+/** Per-collection cache override for published reads. */
+export interface ReadCacheOptions {
+  /** Cache duration in milliseconds. */
+  ttlMs: number;
+}
+
+/** Read-only published value collection. */
+export declare class PublishedValue<T = JsonValue> {
+  get(key: string): Promise<T | null>;
+}
+
+/** Read-only published map collection. */
+export declare class PublishedMap<V = JsonValue> {
+  get(key: string, mapKey: string): Promise<V | null>;
+  getMany(key: string, mapKeys: string[]): Promise<Array<V | null>>;
+  has(key: string, mapKey: string): Promise<boolean>;
+  entries(
+    key: string,
+    direction?: ScanDirection,
+  ): AsyncIterableIterator<[string, V]>;
+  keys(key: string, direction?: ScanDirection): AsyncIterableIterator<string>;
+  values(key: string, direction?: ScanDirection): AsyncIterableIterator<V>;
+}
+
+/** Read-only published deque collection. */
+export declare class PublishedDeque<T = JsonValue> {
+  length(key: string): Promise<number>;
+  isEmpty(key: string): Promise<boolean>;
+  at(key: string, index: number): Promise<T | null>;
+  values(key: string, direction?: ScanDirection): AsyncIterableIterator<T>;
 }
 
 /**
@@ -277,8 +929,40 @@ export class PermanentError extends EventHandlerError {
   get isPermanent(): true;
 }
 
+/**
+ * Represents a transient keyed-state failure that may succeed on a later
+ * attempt — a store read/write timeout, AND every caller mistake (a
+ * null/unrepresentable write, an item-shape mismatch, an out-of-range index, an
+ * invalid scan direction). Caller mistakes are transient on purpose so they
+ * retry and stay visible rather than discarding the message. Subclasses
+ * {@link TransientError}, so rethrowing it from a handler classifies the event
+ * transient through the existing error bridge unchanged.
+ */
+export class TransientStateError extends TransientError {}
+
+/**
+ * Represents a permanent keyed-state failure a retry cannot resolve in-process
+ * — an unregistered collection name, a registered-identity mismatch, or a
+ * duplicate registration (or one a handler throws explicitly). Caller mistakes
+ * are NOT permanent; they are {@link TransientStateError}. Subclasses
+ * {@link PermanentError}, so rethrowing it from a handler classifies the event
+ * permanent through the existing error bridge unchanged.
+ */
+export class PermanentStateError extends PermanentError {}
+
+/**
+ * Name-branded predicate that narrows to either keyed-state error class,
+ * regardless of category.
+ *
+ * @param error - The value to test.
+ * @returns True when the value is a keyed-state error.
+ */
+export function isStateError(
+  error: unknown,
+): error is PermanentStateError | TransientStateError;
+
 /** Type alias for a constructor of an Error subclass. */
-type ErrorClass<T extends Error> = new (...args: any[]) => T;
+type ErrorClass<T extends Error> = new (...args: never[]) => T;
 
 /**
  * Type for a decorator function that can be applied to both methods and standalone functions.