@prosody-events/prosody 0.5.1 → 0.6.1

package/bindings.d.ts

@@ -1,5 +1,14 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
+
+/**
+ * Which binding artifact the generated loader actually loaded: `'native'` for
+ * a native addon, otherwise the `platformArchABI` of the WASI flavor. Every
+ * flavor napi-rs can build is listed, because `NAPI_RS_NATIVE_LIBRARY_PATH`
+ * can point the loader at a WASI artifact this package does not build itself.
+ */
+export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'
+
 /**
  * Represents a client for performing administrative operations on a Prosody
  * cluster.
@@ -19,9 +28,11 @@ export declare class AdminClient {
    * @param name - The name of the topic to create.
    * @param partitionCount - The number of partitions for the topic.
    * @param replicationFactor - The replication factor for the topic.
-   * @throws Error if the topic creation fails.
+   * @param options - The cleanup policy and retention. The cluster default
+   * applies to each setting you omit.
+   * @throws Error if a number cannot convert or the topic creation fails.
    */
-  createTopic(name: string, partitionCount: number, replicationFactor: number): Promise<void>
+  createTopic(name: string, partitionCount: number, replicationFactor: number, options?: TopicOptions | undefined | null): Promise<void>
   /**
    * Deletes a topic from the Prosody cluster.
    *
@@ -43,6 +54,16 @@ export declare class ExciseMessage {
   get timestamp(): Date
   /** The key that this record excises. */
   get key(): string
+  /**
+   * The source system of the producer, or `null` when the record has no
+   * source system header.
+   */
+  get sourceSystem(): string | null
+  /**
+   * Whether the sender waits for a response from this consumer. The
+   * handler result becomes the response only when this is `true`.
+   */
+  get responseRequested(): boolean
 }
 
 /** A Kafka message received from a consumer. */
@@ -57,6 +78,16 @@ export declare class Message {
   get timestamp(): Date
   /** The message key used for partitioning. */
   get key(): string
+  /**
+   * The source system of the producer, or `null` when the message has no
+   * source system header.
+   */
+  get sourceSystem(): string | null
+  /**
+   * Whether the sender waits for a response from this consumer. The
+   * handler result becomes the response only when this is `true`.
+   */
+  get responseRequested(): boolean
   /**
    * The payload as the raw JSON text read from the wire.
    *
@@ -91,11 +122,13 @@ export declare class NativeClient {
    */
   consumerState(): Promise<ConsumerState>
   /** Builds a read-only view of a published value collection. */
-  publishedValue(subsystem: string, name: string, cacheMs?: number | undefined | null, cacheDisabled?: boolean | undefined | null): Promise<NativePublishedValue>
+  publishedValue(subsystem: string, name: string, readCache?: ReadCacheOption | undefined | null): Promise<NativePublishedValue>
   /** Builds a read-only view of a published map collection. */
-  publishedMap(subsystem: string, name: string, cacheMs?: number | undefined | null, cacheDisabled?: boolean | undefined | null): Promise<NativePublishedMap>
+  publishedMap(subsystem: string, name: string, readCache?: ReadCacheOption | undefined | null): Promise<NativePublishedMap>
+  /** Builds a read-only view of a published set collection. */
+  publishedSet(subsystem: string, name: string, readCache?: ReadCacheOption | undefined | null): Promise<NativePublishedSet>
   /** Builds a read-only view of a published deque collection. */
-  publishedDeque(subsystem: string, name: string, cacheMs?: number | undefined | null, cacheDisabled?: boolean | undefined | null): Promise<NativePublishedDeque>
+  publishedDeque(subsystem: string, name: string, readCache?: ReadCacheOption | undefined | null): Promise<NativePublishedDeque>
   /**
    * Sends a message to a specified topic.
    *
@@ -110,9 +143,9 @@ export declare class NativeClient {
    * @param metadata - The event metadata read off the payload object
    * @param otelContext - The OpenTelemetry context for tracing
    * @param maybeAbort - Optional promise that resolves when the operation
-   * should be aborted @returns A promise that resolves when the message
-   * has been sent @throws Error if the send operation fails or is
-   * aborted
+   *   should be aborted
+   * @returns A promise that resolves when the message has been sent
+   * @throws Error if the send operation fails or is aborted
    */
   send(topic: string, key: string, payload: string, metadata: EventMetadata, otelContext: Record<string, string>, maybeAbort?: Promise<undefined> | undefined | null): Promise<void>
   /** Sends an excise record to a specified topic. */
@@ -167,6 +200,12 @@ export declare class NativeClient {
 
 /** Wrapper around `MessageContext` for use in Node.js bindings. */
 export declare class NativeContext {
+  /**
+   * The demand that started this handler invocation.
+   *
+   * @returns The demand kind and its retry count.
+   */
+  get demand(): NativeDemand
   /**
    * Checks whether cancellation has been signaled.
    *
@@ -223,80 +262,19 @@ export declare class NativeContext {
    * @throws Error if retrieval fails.
    */
   scheduled(otelContext: Record<string, string>): Promise<Array<Date>>
-  /**
-   * Vends the state handle for the named JSON value collection.
-   *
-   * Vending verifies the collection's registration (core-side); no span is
-   * opened here — vended handles outlive the call, and every operation opens
-   * its own span.
-   *
-   * @param name The registered collection name.
-   * @returns The value-state handle for this event's transaction.
-   * @throws Error (permanent) if the name is unregistered or its registered
-   *   identity mismatches.
-   */
+  /** Vends the state handle for the named JSON value collection. */
   valueState(name: string): NativeJsonValueState
-  /**
-   * Vends the state handle for the named JSON map collection.
-   *
-   * Vending verifies the collection's registration (core-side); no span is
-   * opened here — vended handles outlive the call, and every operation opens
-   * its own span.
-   *
-   * @param name The registered collection name.
-   * @returns The map-state handle for this event's transaction.
-   * @throws Error (permanent) if the name is unregistered or its registered
-   *   identity mismatches.
-   */
+  /** Vends the state handle for the named JSON map collection. */
   mapState(name: string): NativeJsonMapState
-  /**
-   * Vends the state handle for the named JSON deque collection.
-   *
-   * Vending verifies the collection's registration (core-side); no span is
-   * opened here — vended handles outlive the call, and every operation opens
-   * its own span.
-   *
-   * @param name The registered collection name.
-   * @returns The deque-state handle for this event's transaction.
-   * @throws Error (permanent) if the name is unregistered or its registered
-   *   identity mismatches.
-   */
+  /** Vends the state handle for the named set collection. */
+  setState(name: string): NativeSetState
+  /** Vends the state handle for the named JSON deque collection. */
   dequeState(name: string): NativeJsonDequeState
-  /**
-   * Vends the state handle for the named Kafka-message value collection.
-   *
-   * Items are the full `Message` the handler received, loader-resolved on
-   * read. Vending verifies registration (core-side); no span is opened here.
-   *
-   * @param name The registered collection name.
-   * @returns The message value-state handle for this event's transaction.
-   * @throws Error (permanent) if the name is unregistered or its registered
-   *   identity mismatches.
-   */
+  /** Vends the state handle for the named Kafka-message value collection. */
   messageValueState(name: string): NativeMessageValueState
-  /**
-   * Vends the state handle for the named Kafka-message map collection.
-   *
-   * Items are the full `Message` the handler received, loader-resolved on
-   * read. Vending verifies registration (core-side); no span is opened here.
-   *
-   * @param name The registered collection name.
-   * @returns The message map-state handle for this event's transaction.
-   * @throws Error (permanent) if the name is unregistered or its registered
-   *   identity mismatches.
-   */
+  /** Vends the state handle for the named Kafka-message map collection. */
   messageMapState(name: string): NativeMessageMapState
-  /**
-   * Vends the state handle for the named Kafka-message deque collection.
-   *
-   * Items are the full `Message` the handler received, loader-resolved on
-   * read. Vending verifies registration (core-side); no span is opened here.
-   *
-   * @param name The registered collection name.
-   * @returns The message deque-state handle for this event's transaction.
-   * @throws Error (permanent) if the name is unregistered or its registered
-   *   identity mismatches.
-   */
+  /** Vends the state handle for the named Kafka-message deque collection. */
   messageDequeState(name: string): NativeMessageDequeState
 }
 
@@ -310,120 +288,32 @@ export declare class NativeJsonDequeCursor {
 
 /** JSON deque state handle for one event. */
 export declare class NativeJsonDequeState {
-  /**
-   * The number of live elements.
-   *
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @returns The element count.
-   * @throws Error carrying the category on `cause` if the read fails, or if
-   *   the count exceeds the `u32` range.
-   */
+  /** Returns the number of live elements. */
   len(otelContext: Record<string, string>): Promise<number>
-  /**
-   * Whether the deque holds no live elements.
-   *
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @returns True when the deque is empty.
-   * @throws Error carrying the category on `cause` if the read fails.
-   */
+  /** Reports whether the deque has no live elements. */
   isEmpty(otelContext: Record<string, string>): Promise<boolean>
-  /**
-   * Reads the element at front-relative position `index`.
-   *
-   * @param index The zero-based position from the front.
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @returns The element, or null past the end.
-   * @throws Error carrying the category on `cause` if the read fails.
-   */
+  /** Reads one element by its position from the front. */
   get(index: number, otelContext: Record<string, string>): Promise<string | null>
-  /**
-   * Reads the front endpoint SLOT without a length round trip — exactly
-   * `get(0)`.
-   *
-   * Decodes and resolves the returned element (unlike eviction). An empty
-   * deque, or a front endpoint slot expired under a TTL, yields null even
-   * when live interior elements exist — a peek never searches inward.
-   *
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @returns The front element, or null when the endpoint slot is empty.
-   * @throws Error carrying the category on `cause` if the read fails.
-   */
+  /** Reads the front endpoint. */
   peekFront(otelContext: Record<string, string>): Promise<string | null>
-  /**
-   * Reads the back endpoint SLOT without a length round trip — exactly
-   * `get(len − 1)`.
-   *
-   * Decodes and resolves the returned element (unlike eviction). An empty
-   * deque, or a back endpoint slot expired under a TTL, yields null even
-   * when live interior elements exist — a peek never searches inward.
-   *
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @returns The back element, or null when the endpoint slot is empty.
-   * @throws Error carrying the category on `cause` if the read fails.
-   */
+  /** Reads the back endpoint. */
   peekBack(otelContext: Record<string, string>): Promise<string | null>
-  /**
-   * Appends a JSON document at the back.
-   *
-   * JSON null is not a storable element and is rejected with a transient
-   * error.
-   *
-   * @param json The document's JSON text.
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @throws Error carrying the category on `cause` if the write fails.
-   */
+  /** Appends a JSON document. */
   pushBack(json: string, otelContext: Record<string, string>): Promise<void>
-  /**
-   * Prepends a JSON document at the front.
-   *
-   * JSON null is not a storable element and is rejected with a transient
-   * error.
-   *
-   * @param json The document's JSON text.
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @throws Error carrying the category on `cause` if the write fails.
-   */
+  /** Prepends a JSON document. */
   pushFront(json: string, otelContext: Record<string, string>): Promise<void>
-  /**
-   * Removes and returns the front element.
-   *
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @returns The removed front element, or null when empty.
-   * @throws Error carrying the category on `cause` if the operation fails.
-   */
+  /** Removes and returns the front element. */
   popFront(otelContext: Record<string, string>): Promise<string | null>
-  /**
-   * Removes and returns the back element.
-   *
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @returns The removed back element, or null when empty.
-   * @throws Error carrying the category on `cause` if the operation fails.
-   */
+  /** Removes and returns the back element. */
   popBack(otelContext: Record<string, string>): Promise<string | null>
-  /**
-   * Removes every element.
-   *
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @throws Error carrying the category on `cause` if the clear fails.
-   */
+  /** Removes every element. */
   clear(otelContext: Record<string, string>): Promise<void>
-  /**
-   * Opens a demand-driven cursor over the live elements in index order.
-   *
-   * Synchronous — it performs no I/O. The extracted JavaScript context is
-   * active while core constructs its semantic stream span; chunk pulls do
-   * not create binding spans.
-   *
-   * @param direction The scan direction (`"forward"` or `"backward"`).
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @returns A cursor over the deque elements.
-   * @throws Error if the direction token is invalid.
-   */
-  scan(direction: string, otelContext: Record<string, string>): NativeJsonDequeCursor
+  /** Opens a cursor over the selected elements. */
+  values(query: NativePositionQuery): NativeJsonDequeCursor
   /** Durably commits the buffered operations. */
-  commit(otelContext: Record<string, string>): Promise<void>
+  commit(otelContext: Record<string, string>): Promise<NativeStoreOutcome>
   /** Discards the buffered operations. */
-  rollback(otelContext: Record<string, string>): Promise<void>
+  rollback(otelContext: Record<string, string>): Promise<NativeStoreOutcome>
 }
 
 /** Demand-driven cursor with one element type. */
@@ -436,143 +326,48 @@ export declare class NativeJsonMapCursor {
 
 /** JSON ordered-map state handle for one event. */
 export declare class NativeJsonMapState {
-  /**
-   * Reads the value for `key`.
-   *
-   * @param key The map key.
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @returns The value, or null when the key is absent.
-   * @throws Error carrying the category on `cause` if the read fails.
-   */
+  /** Reads the value for `key`. */
   get(key: string, otelContext: Record<string, string>): Promise<string | null>
-  /**
-   * Reads several keys in a single call.
-   *
-   * Returns one entry per key, in the same order requested: the entry at
-   * index `i` is the value for `keys[i]`. A key that isn't there reads as
-   * null, and a key listed more than once is answered at each of its spots.
-   * The whole read happens as one step, so no other change to this event's
-   * state can slip in partway through.
-   *
-   * @param keys The keys to read, in order.
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @returns One result per input key; null for a key that is absent.
-   * @throws Error carrying the category on `cause` if the read fails.
-   */
+  /** Reads several keys in one operation. */
   getMany(keys: Array<string>, otelContext: Record<string, string>): Promise<Array<string | undefined | null>>
-  /**
-   * Reports whether a stored cell exists for `key`.
-   *
-   * Reads the event's dirty overlay (read-your-writes) and answers presence
-   * WITHOUT decoding the value or running the resolver — a message-backed
-   * map answers with zero Kafka fetches and can report `true` for a
-   * message that can no longer be fetched. This is NOT "no I/O": a cache
-   * miss can still reach Cassandra, so it is async and fallible exactly
-   * like `get`.
-   *
-   * @param key The map key.
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @returns True when a stored cell exists for `key`.
-   * @throws Error carrying the category on `cause` if the read fails.
-   */
+  /** Reports whether the map holds an entry for `key`. */
   contains(key: string, otelContext: Record<string, string>): Promise<boolean>
-  /**
-   * Inserts or overwrites `key` with a JSON document.
-   *
-   * JSON null is rejected with a transient error naming `delete` as the way
-   * to remove an entry.
-   *
-   * @param key The map key.
-   * @param json The document's JSON text.
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @throws Error carrying the category on `cause` if the write fails.
-   */
+  /** Tests several keys for presence in one read. */
+  containsMany(keys: Array<string>, otelContext: Record<string, string>): Promise<Array<boolean>>
+  /** Reports whether the map has no live entries. */
+  isEmpty(otelContext: Record<string, string>): Promise<boolean>
+  /** Inserts or overwrites `key` with a JSON document. */
   set(key: string, json: string, otelContext: Record<string, string>): Promise<void>
-  /**
-   * Removes `key`.
-   *
-   * @param key The map key.
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @throws Error carrying the category on `cause` if the removal fails.
-   */
+  /** Removes `key`. */
   remove(key: string, otelContext: Record<string, string>): Promise<void>
-  /**
-   * Removes every entry.
-   *
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @throws Error carrying the category on `cause` if the clear fails.
-   */
+  /** Removes every entry. */
   clear(otelContext: Record<string, string>): Promise<void>
-  /**
-   * Opens a demand-driven cursor over the live entries in key order.
-   *
-   * Synchronous — it performs no I/O. The extracted JavaScript context is
-   * active while core constructs its semantic stream span; chunk pulls do
-   * not create binding spans. Entries are yielded as `(key, value)` pairs.
-   *
-   * @param direction The scan direction (`"forward"` or `"backward"`).
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @returns A cursor over the map entries.
-   * @throws Error if the direction token is invalid.
-   */
-  scan(direction: string, otelContext: Record<string, string>): NativeJsonMapCursor
-  /**
-   * Opens a demand-driven cursor over the live KEYS in key order.
-   *
-   * Skips the value codec and the resolver (no value decode, no Kafka
-   * fetch), so a message-backed map enumerates keys with zero Kafka
-   * fetches — but it still reads presence, so it is not zero-I/O.
-   * Synchronous like `scan`: the extracted JavaScript context is active
-   * while core constructs its semantic stream span. Yields bare keys.
-   *
-   * @param direction The scan direction (`"forward"` or `"backward"`).
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @returns A cursor over the map keys.
-   * @throws Error if the direction token is invalid.
-   */
-  keys(direction: string, otelContext: Record<string, string>): NativeMapKeyCursor
+  /** Opens a cursor over the selected entries. */
+  entries(query: NativeKeyQuery): NativeJsonMapCursor
+  /** Opens a cursor over the selected keys. */
+  keys(query: NativeKeyQuery): NativeKeyCursor
   /** Durably commits the buffered operations. */
-  commit(otelContext: Record<string, string>): Promise<void>
+  commit(otelContext: Record<string, string>): Promise<NativeStoreOutcome>
   /** Discards the buffered operations. */
-  rollback(otelContext: Record<string, string>): Promise<void>
+  rollback(otelContext: Record<string, string>): Promise<NativeStoreOutcome>
 }
 
 /** JSON single-value state handle for one event. */
 export declare class NativeJsonValueState {
-  /**
-   * Reads the current value.
-   *
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @returns The current value, or null when absent/cleared.
-   * @throws Error carrying the category on `cause` if the read fails.
-   */
+  /** Reads the current value. */
   get(otelContext: Record<string, string>): Promise<string | null>
-  /**
-   * Buffers a write of a JSON document.
-   *
-   * JSON null is rejected with a transient error naming `clear` as the way
-   * to delete.
-   *
-   * @param json The document's JSON text.
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @throws Error carrying the category on `cause` if the write fails.
-   */
+  /** Buffers a write of a JSON document. */
   set(json: string, otelContext: Record<string, string>): Promise<void>
-  /**
-   * Buffers a clear of the value.
-   *
-   * @param otelContext The OpenTelemetry context for tracing.
-   * @throws Error carrying the category on `cause` if the clear fails.
-   */
+  /** Buffers a clear of the value. */
   clear(otelContext: Record<string, string>): Promise<void>
   /** Durably commits the buffered operations. */
-  commit(otelContext: Record<string, string>): Promise<void>
+  commit(otelContext: Record<string, string>): Promise<NativeStoreOutcome>
   /** Discards the buffered operations. */
-  rollback(otelContext: Record<string, string>): Promise<void>
+  rollback(otelContext: Record<string, string>): Promise<NativeStoreOutcome>
 }
 
 /** Demand-driven cursor with one element type. */
-export declare class NativeMapKeyCursor {
+export declare class NativeKeyCursor {
   /** Pulls the next ready chunk. */
   nextChunk(otelContext: Record<string, string>): Promise<Array<string> | null>
   /** Closes the cursor. */
@@ -609,12 +404,12 @@ export declare class NativeMessageDequeState {
   popBack(otelContext: Record<string, string>): Promise<Message | null>
   /** Removes every element. */
   clear(otelContext: Record<string, string>): Promise<void>
-  /** Opens a cursor over the live elements. */
-  scan(direction: string, otelContext: Record<string, string>): NativeMessageDequeCursor
+  /** Opens a cursor over the selected elements. */
+  values(query: NativePositionQuery): NativeMessageDequeCursor
   /** Durably commits the buffered operations. */
-  commit(otelContext: Record<string, string>): Promise<void>
+  commit(otelContext: Record<string, string>): Promise<NativeStoreOutcome>
   /** Discards the buffered operations. */
-  rollback(otelContext: Record<string, string>): Promise<void>
+  rollback(otelContext: Record<string, string>): Promise<NativeStoreOutcome>
 }
 
 /** Demand-driven cursor with one element type. */
@@ -631,22 +426,26 @@ export declare class NativeMessageMapState {
   get(key: string, otelContext: Record<string, string>): Promise<Message | null>
   /** Reads several keys in one operation. */
   getMany(keys: Array<string>, otelContext: Record<string, string>): Promise<Array<Message | undefined | null>>
-  /** Reports whether `key` has a stored cell. */
+  /** Reports whether the map holds an entry for `key`. */
   contains(key: string, otelContext: Record<string, string>): Promise<boolean>
+  /** Tests several keys for presence in one read. */
+  containsMany(keys: Array<string>, otelContext: Record<string, string>): Promise<Array<boolean>>
+  /** Reports whether the map has no live entries. */
+  isEmpty(otelContext: Record<string, string>): Promise<boolean>
   /** Inserts or overwrites `key` with a Kafka message. */
   set(key: string, message: Message, otelContext: Record<string, string>): Promise<void>
   /** Removes `key`. */
   remove(key: string, otelContext: Record<string, string>): Promise<void>
   /** Removes every entry. */
   clear(otelContext: Record<string, string>): Promise<void>
-  /** Opens a cursor over entries in key order. */
-  scan(direction: string, otelContext: Record<string, string>): NativeMessageMapCursor
-  /** Opens a cursor over keys in key order. */
-  keys(direction: string, otelContext: Record<string, string>): NativeMapKeyCursor
+  /** Opens a cursor over the selected entries. */
+  entries(query: NativeKeyQuery): NativeMessageMapCursor
+  /** Opens a cursor over the selected keys. */
+  keys(query: NativeKeyQuery): NativeKeyCursor
   /** Durably commits the buffered operations. */
-  commit(otelContext: Record<string, string>): Promise<void>
+  commit(otelContext: Record<string, string>): Promise<NativeStoreOutcome>
   /** Discards the buffered operations. */
-  rollback(otelContext: Record<string, string>): Promise<void>
+  rollback(otelContext: Record<string, string>): Promise<NativeStoreOutcome>
 }
 
 /** Kafka-message single-value state handle for one event. */
@@ -658,9 +457,9 @@ export declare class NativeMessageValueState {
   /** Buffers a clear of the value. */
   clear(otelContext: Record<string, string>): Promise<void>
   /** Durably commits the buffered operations. */
-  commit(otelContext: Record<string, string>): Promise<void>
+  commit(otelContext: Record<string, string>): Promise<NativeStoreOutcome>
   /** Discards the buffered operations. */
-  rollback(otelContext: Record<string, string>): Promise<void>
+  rollback(otelContext: Record<string, string>): Promise<NativeStoreOutcome>
 }
 
 /** A read-only published deque collection. */
@@ -668,15 +467,15 @@ export declare class NativePublishedDeque {
   /** Reads one front-relative element. */
   get(key: string, index: number, otelContext: Record<string, string>): Promise<string | null>
   /** Returns the committed deque length. */
-  length(key: string, otelContext: Record<string, string>): Promise<number>
+  len(key: string, otelContext: Record<string, string>): Promise<number>
   /** Reports whether the committed deque is empty. */
   isEmpty(key: string, otelContext: Record<string, string>): Promise<boolean>
   /** Reads the committed front element. */
   peekFront(key: string, otelContext: Record<string, string>): Promise<string | null>
   /** Reads the committed back element. */
   peekBack(key: string, otelContext: Record<string, string>): Promise<string | null>
-  /** Opens an ordered element cursor. */
-  scan(key: string, direction: string, otelContext: Record<string, string>): Promise<NativeJsonDequeCursor>
+  /** Opens a cursor over the selected elements. */
+  values(key: string, query: NativePositionQuery): NativeJsonDequeCursor
 }
 
 /** A read-only published map collection. */
@@ -687,10 +486,26 @@ export declare class NativePublishedMap {
   getMany(key: string, mapKeys: Array<string>, otelContext: Record<string, string>): Promise<Array<string | undefined | null>>
   /** Reports whether a committed map entry exists. */
   contains(key: string, mapKey: string, otelContext: Record<string, string>): Promise<boolean>
-  /** Opens an ordered entry cursor. */
-  scan(key: string, direction: string, otelContext: Record<string, string>): Promise<NativeJsonMapCursor>
-  /** Opens an ordered key cursor. */
-  keys(key: string, direction: string, otelContext: Record<string, string>): Promise<NativeMapKeyCursor>
+  /** Tests committed presence aligned with the supplied map keys. */
+  containsMany(key: string, mapKeys: Array<string>, otelContext: Record<string, string>): Promise<Array<boolean>>
+  /** Reports whether the committed map is empty. */
+  isEmpty(key: string, otelContext: Record<string, string>): Promise<boolean>
+  /** Opens a cursor over the selected entries. */
+  entries(key: string, query: NativeKeyQuery): NativeJsonMapCursor
+  /** Opens a cursor over the selected keys. */
+  keys(key: string, query: NativeKeyQuery): NativeKeyCursor
+}
+
+/** A read-only published set collection. */
+export declare class NativePublishedSet {
+  /** Reports whether the committed set contains a member. */
+  contains(key: string, member: string, otelContext: Record<string, string>): Promise<boolean>
+  /** Tests committed membership aligned with the supplied members. */
+  containsMany(key: string, members: Array<string>, otelContext: Record<string, string>): Promise<Array<boolean>>
+  /** Reports whether the committed set has no members. */
+  isEmpty(key: string, otelContext: Record<string, string>): Promise<boolean>
+  /** Opens a cursor over the selected members. */
+  keys(key: string, query: NativeKeyQuery): NativeKeyCursor
 }
 
 /** A read-only published value collection. */
@@ -699,6 +514,34 @@ export declare class NativePublishedValue {
   get(key: string, otelContext: Record<string, string>): Promise<string | null>
 }
 
+/** Presence-only ordered set of string members for one event. */
+export declare class NativeSetState {
+  /** Reports whether `member` belongs to the set. */
+  contains(member: string, otelContext: Record<string, string>): Promise<boolean>
+  /** Tests several members in one read. */
+  containsMany(members: Array<string>, otelContext: Record<string, string>): Promise<Array<boolean>>
+  /** Reports whether the set has no live members. */
+  isEmpty(otelContext: Record<string, string>): Promise<boolean>
+  /** Adds `member` to the set. */
+  insert(member: string, otelContext: Record<string, string>): Promise<void>
+  /** Removes `member` from the set. */
+  remove(member: string, otelContext: Record<string, string>): Promise<void>
+  /** Removes every member. */
+  clear(otelContext: Record<string, string>): Promise<void>
+  /** Opens a cursor over the selected members. */
+  keys(query: NativeKeyQuery): NativeKeyCursor
+  /** Durably commits the buffered operations. */
+  commit(otelContext: Record<string, string>): Promise<NativeStoreOutcome>
+  /** Discards the buffered operations. */
+  rollback(otelContext: Record<string, string>): Promise<NativeStoreOutcome>
+}
+
+/** The kind of a keyed-state collection. */
+export type CollectionKind = 'value' | 'map' | 'set' | 'deque'
+
+/** The item payload of a value, map, or deque collection. A set has none. */
+export type CollectionPayload = 'json' | 'message'
+
 /** Configuration options for the Prosody client. */
 export interface Configuration {
   /** Kafka servers for initial connection. */
@@ -710,8 +553,9 @@ export interface Configuration {
   /** Consumer group name. */
   groupId?: string
   /**
-   * Global shared cache capacity across all partitions for deduplicating
-   * messages. Must be greater than 0.
+   * Capacity of both idempotence caches: the producer cache that skips a
+   * repeated event ID, and the consumer cache that drops a duplicate
+   * message. The consumer cache requires at least 1.
    */
   idempotenceCacheSize?: number
   /**
@@ -726,7 +570,7 @@ export interface Configuration {
    *
    * Must be at least 1 minute. Defaults to 7 days.
    */
-  idempotenceTtlS?: number
+  idempotenceTtlSeconds?: number
   /** Topics to subscribe to. */
   subscribedTopics?: string | Array<string>
   /** Allowed event type prefixes. All event types are allowed if unset. */
@@ -751,6 +595,12 @@ export interface Configuration {
   pollIntervalMs?: number
   /** Time between offset commits in milliseconds. */
   commitIntervalMs?: number
+  /**
+   * Time between librdkafka statistics reports in milliseconds. Prosody
+   * accepts 1 ms to 24 hours. Uses `PROSODY_STATISTICS_INTERVAL` when
+   * omitted, then 5 seconds.
+   */
+  statisticsIntervalMs?: number
   /** Operating mode. */
   mode?: Mode
   /** Initial delay for exponential backoff in retries in milliseconds. */
@@ -904,12 +754,14 @@ export interface Configuration {
    */
   stateCollections?: Array<StateCollectionConfig>
   /**
-   * Disk workspace for the local keyed-state cache.
+   * Directory that holds the local keyed-state caches.
    *
-   * Each live client needs its own directory because it is locked
-   * exclusively. Falls back to the `PROSODY_STATE_CACHE_DIR` environment
-   * variable, then a per-client temporary directory. Must not be an
-   * empty string when set.
+   * Each consumer opens its cache in a fresh subdirectory and removes that
+   * subdirectory when the consumer drops. So clients can share the
+   * directory, and the mount needs no persistence. Production deployments
+   * must set a mounted path, for example a Kubernetes `emptyDir`. Falls
+   * back to the `PROSODY_STATE_CACHE_DIR` environment variable, then to
+   * `<temp>/prosody/keyed-state`. Must not be an empty string when set.
    */
   stateCacheDir?: string
   /**
@@ -918,6 +770,14 @@ export interface Configuration {
    * storage engine selects its default.
    */
   stateOwnedCacheSize?: string
+  /**
+   * Bytes of in-memory writes the local keyed-state cache holds for each
+   * assigned partition before it flushes them to disk. Memory use scales
+   * with the number of assigned partitions. Accepts a human-readable size.
+   * Uses `PROSODY_STATE_MEMTABLE_SIZE` when omitted. Otherwise, the
+   * storage engine's default of 64 MiB applies.
+   */
+  stateMemtableSize?: string
   /**
    * Capacity of the published-state read-through cache. Uses
    * `PROSODY_STATE_READ_CACHE_SIZE` when omitted. It then uses the owning
@@ -925,22 +785,16 @@ export interface Configuration {
    */
   stateReadCacheSize?: string
   /**
-   * Default cache policy for published-state reads. Uses
+   * Default cache policy for published-state reads: `false` turns the
+   * cache off, and `{ ttlMs }` sets the cache duration. The older form
+   * `{ disabled: true }` still turns the cache off. Uses
    * `PROSODY_STATE_READ_CACHE_TTL` when omitted, then 5 seconds.
    */
-  stateReadCache?: ReadCacheConfiguration
+  stateReadCache?: ReadCacheConfiguration | false
   /**
-   * Delay in whole seconds between staging a provisional cell and the
-   * keyed-state recovery sweep. Every registered TTL must strictly exceed
-   * this. Falls back to the `PROSODY_STATE_RECOVERY_DELAY` environment
-   * variable (a duration string such as `30s`), then to 30 seconds. Must be
-   * a whole number of seconds >= 1 when set (fractional, negative, and
-   * non-finite values are rejected).
-   */
-  stateRecoveryDelaySeconds?: number
-  /**
-   * Subsystem under which published JSON collections are advertised.
-   * Uses `PROSODY_SUBSYSTEM` when omitted. Published collections require it.
+   * Subsystem under which published JSON and set collections are
+   * advertised. Uses `PROSODY_SUBSYSTEM` when omitted. Published
+   * collections require it.
    */
   subsystem?: string
   /**
@@ -971,16 +825,10 @@ export interface Configuration {
 }
 
 /** Current consumer state. */
-export type ConsumerState = /** The client is shut down. */
-'Shutdown'|
-/** The consumer is not configured. */
-'Unconfigured'|
-/** The consumer is configured but not active. */
-'Configured'|
-/** The consumer is active. */
-'Running'|
-/** The consumer configuration failed. */
-'ConfigurationFailed';
+export type ConsumerState = 'Shutdown' | 'Unconfigured' | 'Configured' | 'Running' | 'ConfigurationFailed'
+
+/** Why the handler runs: a normal delivery or a retry after a failure. */
+export type DemandKind = 'normal' | 'failure'
 
 /**
  * Event metadata read off a payload before it was serialized.
@@ -995,8 +843,7 @@ export interface EventMetadata {
 }
 
 /** Type alias for excise handler arguments. */
-export type ExciseHandlerArgs =
-  [NativeContext, ExciseMessage, Record<string, string>]
+export type ExciseHandlerArgs = [NativeContext, ExciseMessage, Record<string, string>]
 
 /**
  * Exports all pending telemetry data.
@@ -1017,12 +864,10 @@ export declare function flushTelemetry(): void
 export declare function initialize(): void
 
 /** Type alias for error classification arguments. */
-export type IsPermanentArgs =
-  [Error]
+export type IsPermanentArgs = [Error]
 
 /** Type alias for the arguments passed to JavaScript logging functions. */
-export type LogArgs =
-  [string | undefined | null, any]
+export type LogArgs = [string | undefined | null, any]
 
 /** JavaScript-compatible logger structure. */
 export interface Logger {
@@ -1038,27 +883,25 @@ export interface Logger {
   trace: (arg: LogArgs) => void
 }
 
-/**
- * Checks if a logger has been set in the logging system.
- *
- * @returns True if a logger is currently configured, false otherwise.
- */
-export declare function loggerIsSet(): boolean
-
 /** Type alias for message handler arguments. */
-export type MessageHandlerArgs =
-  [NativeContext, Message, Record<string, string>]
+export type MessageHandlerArgs = [NativeContext, Message, Record<string, string>]
 
 /** Enum representing the operating mode of the Prosody client. */
-export type Mode = /** Pipeline mode for standard processing. */
-'Pipeline'|
-/** Low-latency mode for faster processing with potential trade-offs. */
-'LowLatency'|
-/**
- * Best-effort mode for development or when messages can be discarded when
- * processing fails
- */
-'BestEffort';
+export type Mode = 'Pipeline' | 'LowLatency' | 'BestEffort'
+
+/** The demand that started this handler invocation. */
+export interface NativeDemand {
+  /** Whether the handler runs for a normal delivery or a retry. */
+  kind: DemandKind
+  /**
+   * The retry count: 0 for normal demand and 1 on the first retry. It is
+   * an estimate. Keep an exact attempt count in keyed state if needed.
+   */
+  retry: number
+}
+
+/** The order of a scan. */
+export type NativeDirection = 'forward' | 'backward'
 
 /** One excise subsystem request. */
 export interface NativeExciseRequest {
@@ -1115,6 +958,50 @@ export interface NativeHandler {
   isPermanent: (arg: IsPermanentArgs) => boolean
 }
 
+/** Query options for map keys, map entries, and set members. */
+export interface NativeKeyQuery {
+  /** The query order. */
+  direction?: NativeDirection
+  /** Keeps keys that start with this prefix. */
+  prefix?: string
+  /** Starts at this key in query order. */
+  from?: string
+  /** Starts after this key in query order. */
+  after?: string
+  /** Stops at this key in query order. */
+  to?: string
+  /** Stops before this key in query order. */
+  before?: string
+  /**
+   * Keeps keys from the first bound up to, but not including, the second.
+   * A `null` bound leaves its end open.
+   */
+  range?: [string | undefined | null, string | undefined | null]
+  /** The maximum number of results. */
+  limit?: number
+}
+
+/** Query options for deque values. Positions count from the front. */
+export interface NativePositionQuery {
+  /** The query order. */
+  direction?: NativeDirection
+  /** Starts at this position in query order. */
+  from?: number
+  /** Starts after this position in query order. */
+  after?: number
+  /** Stops at this position in query order. */
+  to?: number
+  /** Stops before this position in query order. */
+  before?: number
+  /**
+   * Keeps positions from the first bound up to, but not including, the
+   * second. A `null` bound leaves its end open.
+   */
+  range?: [number | undefined | null, number | undefined | null]
+  /** The maximum number of results. */
+  limit?: number
+}
+
 /** One subsystem request. */
 export interface NativeRequest {
   /** Kafka topic. */
@@ -1140,10 +1027,15 @@ export interface NativeResponseError {
 }
 
 /** One response failure kind. */
-export type NativeResponseErrorKind =  'handler'|
-'timeout'|
-'formatMismatch'|
-'malformedResponse';
+export type NativeResponseErrorKind = 'handler' | 'timeout' | 'formatMismatch' | 'malformedResponse'
+
+/**
+ * The effect of a commit or a rollback.
+ *
+ * `"applied"` means the call wrote or discarded buffered operations.
+ * `"noOp"` means nothing was buffered.
+ */
+export type NativeStoreOutcome = 'applied' | 'noOp'
 
 /** One subsystem and its outcome. */
 export interface NativeSubsystemOutcome {
@@ -1153,14 +1045,20 @@ export interface NativeSubsystemOutcome {
   outcome: string | NativeResponseError
 }
 
-/** Default cache policy for published-state reads. */
+/** The cache options for published-state reads. */
 export interface ReadCacheConfiguration {
-  /** Cache duration in milliseconds. */
+  /** Cache duration in milliseconds. Omit it to use the default duration. */
   ttlMs?: number
-  /** Read durable storage on every operation. */
+  /** `true` turns the cache off, the same as `false`. */
   disabled?: boolean
 }
 
+/**
+ * A read cache option: `false` turns the cache off, and
+ * `{ ttlMs }` sets the cache duration.
+ */
+export type ReadCacheOption = boolean | ReadCacheConfiguration
+
 /**
  * Sets a new JavaScript logger for the Prosody client.
  *
@@ -1169,23 +1067,13 @@ export interface ReadCacheConfiguration {
  * levels.
  *
  * @param logger - The JavaScript logger object with error, warn, info, debug,
- * and trace methods. @throws Error if creating the new JavaScript logger
- * fails.
- */
-export declare function setLogger(logger: Logger): void
-
-/**
- * Sets a JavaScript logger only if no logger is currently configured.
+ * and trace methods.
  *
- * This function is useful for providing a default logger without overriding
- * an existing one that may have been set earlier.
+ * # Errors
  *
- * @param logger - The JavaScript logger object with error, warn, info, debug,
- * and trace methods. @returns True if the logger was set (no previous logger
- * existed), false if a logger was already configured. @throws Error if
- * creating the new JavaScript logger fails.
+ * Returns an error if the thread-safe logger functions cannot be created.
  */
-export declare function setLoggerIfUnset(logger: Logger): boolean
+export declare function setLogger(logger: Logger): void
 
 /**
  * Stops the global telemetry providers after they export pending data.
@@ -1205,17 +1093,17 @@ export interface StateCollectionConfig {
    * within the definition set.
    */
   name: string
-  /** The collection kind: `"value"`, `"map"`, or `"deque"`. */
-  kind: string
+  /** The collection kind. */
+  kind: CollectionKind
   /**
-   * The item payload: `"json"` (JSON values) or `"message"` (the full Kafka
-   * message the handler received).
+   * The item payload. Required for value, map, and deque collections. Set
+   * collections store members only and take no payload.
    */
-  payload: string
+  payload?: CollectionPayload
   /**
    * Optional per-write TTL in whole seconds. Must be a whole number >= 1
    * (fractional, negative, and non-finite values are rejected) and must
-   * exceed the recovery delay (the latter checked at consumer build).
+   * stay within the Cassandra TTL limit.
    */
   ttlSeconds?: number
   /**
@@ -1226,10 +1114,10 @@ export interface StateCollectionConfig {
   /** Whether other consumer groups may read this collection. */
   published?: boolean
   /**
-   * Optional map-only keyset bound (`0..=4096`; default 128 core-side; `0`
-   * disables ordered-scan tracking). The binding rejects values that cannot
-   * map to an unsigned integer. Prosody enforces the semantic ceiling.
-   * Invalid on value or deque collections.
+   * Optional keyset bound for map and set collections (`0..=4096`; default
+   * 128 core-side; `0` disables ordered-scan tracking). The binding rejects
+   * values that cannot map to an unsigned integer. Prosody enforces the
+   * semantic ceiling. Invalid on value or deque collections.
    */
   keysetLimit?: number
   /**
@@ -1255,5 +1143,15 @@ export interface Timer {
 }
 
 /** Type alias for timer handler arguments. */
-export type TimerHandlerArgs =
-  [NativeContext, Timer, Record<string, string>]
+export type TimerHandlerArgs = [NativeContext, Timer, Record<string, string>]
+
+/** Optional settings for a new topic. */
+export interface TopicOptions {
+  /**
+   * The cleanup policy, such as `"delete"`, `"compact"`, or
+   * `"delete,compact"`.
+   */
+  cleanupPolicy?: string
+  /** How long the topic keeps a message before deletion, in milliseconds. */
+  retentionMs?: number
+}