@prosody-events/prosody 0.1.0

package/bindings.d.ts

@@ -0,0 +1,522 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/**
+ * Represents a client for performing administrative operations on a Prosody
+ * cluster.
+ */
+export declare class AdminClient {
+  /**
+   * Creates a new `AdminClient` instance.
+   *
+   * @param bootstrapServers - A single server address or an array of server
+   * addresses to connect to. @throws Error if the client cannot be
+   * created.
+   */
+  constructor(bootstrapServers: string | Array<string>)
+  /**
+   * Creates a new topic in the Prosody cluster.
+   *
+   * @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.
+   */
+  createTopic(name: string, partitionCount: number, replicationFactor: number): Promise<void>
+  /**
+   * Deletes a topic from the Prosody cluster.
+   *
+   * @param name - The name of the topic to delete.
+   * @throws Error if the topic deletion fails.
+   */
+  deleteTopic(name: string): Promise<void>
+}
+
+/**
+ * A native client wrapper for the Prosody high-level client.
+ * Provides methods for sending messages, subscribing to topics, and managing
+ * consumer state.
+ */
+export declare class NativeClient {
+  /**
+   * Creates a new `NativeClient` instance.
+   *
+   * @param config - The configuration for the client
+   * @throws Error if the client creation fails
+   */
+  constructor(config: Configuration)
+  /**
+   * Gets the current state of the consumer.
+   *
+   * @returns The current state of the consumer
+   * @throws Error if the operation fails
+   */
+  consumerState(): Promise<ConsumerState>
+  /**
+   * Sends a message to a specified topic.
+   *
+   * @param topic - The topic to send the message to
+   * @param key - The key of the message
+   * @param payload - The payload of the message (must be JSON-serializable)
+   * @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
+   */
+  send(topic: string, key: string, payload: any, otelContext: Record<string, string>, maybeAbort?: Promise<undefined> | undefined | null): Promise<void>
+  /**
+   * 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
+   * established @throws Error if the subscription fails
+   */
+  subscribe(eventHandler: { onMessage: (err: null | Error, args: [Context, Message, Record<string, string>]) => Promise<void>; onTimer: (err: null | Error, args: [Context, Timer, Record<string, string>]) => Promise<void>; isPermanent: (args: [Error]) => boolean }): Promise<void>
+  /**
+   * Gets the number of partitions assigned to the consumer.
+   *
+   * @returns The number of assigned partitions, or 0 if the consumer is not
+   * in the Running state @throws Error if the operation fails
+   */
+  assignedPartitionCount(): Promise<number>
+  /**
+   * Checks if the consumer is stalled.
+   *
+   * @returns Whether the consumer is stalled, or false if the consumer is
+   * not in the Running state @throws Error if the operation fails
+   */
+  isStalled(): Promise<boolean>
+  /**
+   * Unsubscribes from receiving messages and shuts down the consumer.
+   *
+   * @returns A promise that resolves when the unsubscribe operation is
+   * complete @throws Error if the unsubscribe operation fails
+   */
+  unsubscribe(): Promise<void>
+  /**
+   * Gets the source system identifier configured for the client.
+   *
+   * @returns The source system identifier
+   */
+  get sourceSystem(): string
+}
+
+/** Wrapper around `MessageContext` for use in Node.js bindings. */
+export declare class NativeContext {
+  /**
+   * Checks whether cancellation has been signaled.
+   *
+   * Cancellation includes message-level cancellation (e.g., timeout) and
+   * partition shutdown. During shutdown, cancellation is delayed until near
+   * the end of the shutdown timeout to allow in-flight work to complete.
+   *
+   * @returns True if cancellation was requested, otherwise false.
+   */
+  get shouldCancel(): boolean
+  /**
+   * Waits for a cancellation signal.
+   *
+   * Cancellation includes message-level cancellation (e.g., timeout) and
+   * partition shutdown. During shutdown, cancellation is delayed until near
+   * the end of the shutdown timeout to allow in-flight work to complete.
+   *
+   * @returns A promise that resolves when cancellation is signaled.
+   */
+  onCancel(): Promise<void>
+  /**
+   * Schedule a timer at the given time.
+   *
+   * @param time - The UTC timestamp to schedule.
+   * @param otelContext - The OpenTelemetry context for tracing
+   * @throws Error if time conversion or scheduling fails.
+   */
+  schedule(time: Date, otelContext: Record<string, string>): Promise<void>
+  /**
+   * Clear existing timers and schedule a new one at the given time.
+   *
+   * @param time - The UTC timestamp to schedule.
+   * @param otelContext - The OpenTelemetry context for tracing
+   * @throws Error if time conversion or scheduling fails.
+   */
+  clearAndSchedule(time: Date, otelContext: Record<string, string>): Promise<void>
+  /**
+   * Unschedules the timer for the specified time.
+   * @param time - The time to unschedule.
+   * @param otelContext - The OpenTelemetry context for tracing
+   * @throws Error if unscheduling fails.
+   */
+  unschedule(time: Date, otelContext: Record<string, string>): Promise<void>
+  /**
+   * Clears all scheduled timers.
+   * @param otelContext - The OpenTelemetry context for tracing
+   * @throws Error if clearing schedules fails.
+   */
+  clearScheduled(otelContext: Record<string, string>): Promise<void>
+  /**
+   * Retrieves all scheduled times.
+   * @param otelContext - The OpenTelemetry context for tracing
+   * @returns An array of scheduled times as Date objects.
+   * @throws Error if retrieval fails.
+   */
+  scheduled(otelContext: Record<string, string>): Promise<Array<Date>>
+}
+
+/** Configuration options for the Prosody client. */
+export interface Configuration {
+  /** Kafka servers for initial connection. */
+  bootstrapServers?: string | Array<string>
+  /** Use mock client for testing if true. */
+  mock?: boolean
+  /** Timeout for message send operations in milliseconds. */
+  sendTimeoutMs?: number
+  /** Consumer group name. */
+  groupId?: string
+  /**
+   * Global shared cache capacity across all partitions for deduplicating
+   * messages. Set to 0 to disable deduplication entirely.
+   */
+  idempotenceCacheSize?: number
+  /**
+   * Version string for cache-busting deduplication hashes.
+   *
+   * Changing this value invalidates all previously recorded dedup entries,
+   * causing messages to be reprocessed.
+   */
+  idempotenceVersion?: string
+  /**
+   * TTL for deduplication records in Cassandra in seconds.
+   *
+   * Must be at least 1 minute. Defaults to 7 days.
+   */
+  idempotenceTtlS?: number
+  /** Topics to subscribe to. */
+  subscribedTopics?: string | Array<string>
+  /** Allowed event type prefixes. All event types are allowed if unset. */
+  allowedEvents?: string | Array<string>
+  /**
+   * Identifier for the producing system, used to prevent loops.
+   * Defaults to the consumer group name.
+   */
+  sourceSystem?: string
+  /** Maximum global concurrency limit. */
+  maxConcurrency?: number
+  /** Max number of uncommitted messages. */
+  maxUncommitted?: number
+  /** Threshold determining when message processing has stalled. */
+  stallThresholdMs?: number
+  /**
+   * Shutdown budget; handlers complete freely before cancellation fires
+   * near the deadline.
+   */
+  shutdownTimeoutMs?: number
+  /** Time between message polls in milliseconds. */
+  pollIntervalMs?: number
+  /** Time between offset commits in milliseconds. */
+  commitIntervalMs?: number
+  /** Operating mode. */
+  mode?: Mode
+  /** Initial delay for exponential backoff in retries in milliseconds. */
+  retryBaseMs?: number
+  /** Maximum number of retries. */
+  maxRetries?: number
+  /** Maximum delay between retries in milliseconds. */
+  maxRetryDelayMs?: number
+  /** Topic for failed messages in low-latency mode. */
+  failureTopic?: string
+  /** Port for the probe server. Set to null to disable. */
+  probePort?: number | null
+  /**
+   * Timer slab partitioning duration in milliseconds.
+   * Controls how timers are grouped for storage and retrieval.
+   */
+  slabSizeMs?: number
+  /** Cassandra contact nodes (hostnames or IPs). */
+  cassandraNodes?: string | Array<string>
+  /** Cassandra keyspace to use for storing timer data. */
+  cassandraKeyspace?: string
+  /** Preferred Cassandra datacenter for query routing. */
+  cassandraDatacenter?: string
+  /** Preferred Cassandra rack identifier for topology-aware routing. */
+  cassandraRack?: string
+  /** Username for authenticating with Cassandra. */
+  cassandraUser?: string
+  /** Password for authenticating with Cassandra. */
+  cassandraPassword?: string
+  /**
+   * Retention period for failed/unprocessed timer data in Cassandra in
+   * seconds.
+   */
+  cassandraRetentionSeconds?: number
+  /**
+   * Target proportion of execution time for failure/retry task processing
+   * (0.0 to 1.0). Controls bandwidth allocation between Normal and
+   * Failure task classes. Higher values allocate more execution time to
+   * retrying failed tasks.
+   */
+  schedulerFailureWeight?: number
+  /**
+   * Wait duration (in milliseconds) at which urgency boost reaches maximum
+   * intensity. Controls how quickly wait urgency ramps up for queued
+   * tasks. Shorter values make the scheduler more responsive to wait
+   * time.
+   */
+  schedulerMaxWaitMs?: number
+  /**
+   * Maximum urgency boost (in seconds of virtual time) for waiting tasks.
+   * Higher values increase the importance of wait time relative to virtual
+   * time fairness.
+   */
+  schedulerWaitWeight?: number
+  /**
+   * Cache capacity for tracking per-key virtual time in the scheduler.
+   * Larger caches provide more accurate long-term fairness across many keys.
+   */
+  schedulerCacheSize?: number
+  /**
+   * Whether monopolization detection is enabled.
+   * When disabled, the monopolization middleware is bypassed.
+   */
+  monopolizationEnabled?: boolean
+  /**
+   * Threshold for monopolization detection (0.0 to 1.0).
+   * If a key's execution time exceeds this fraction of the window duration,
+   * it is considered to be monopolizing execution.
+   */
+  monopolizationThreshold?: number
+  /** Rolling window duration (in milliseconds) for monopolization detection. */
+  monopolizationWindowMs?: number
+  /**
+   * Cache size for tracking key execution intervals in monopolization
+   * detection.
+   */
+  monopolizationCacheSize?: number
+  /**
+   * Whether deferral is enabled for new messages.
+   * When disabled, transient failures will not be deferred.
+   */
+  deferEnabled?: boolean
+  /**
+   * Base exponential backoff delay for deferred retries in milliseconds.
+   * Handles persistent failures that need time to recover.
+   */
+  deferBaseMs?: number
+  /**
+   * Maximum delay between deferred retries in milliseconds.
+   * Caps exponential backoff to prevent excessively long delays.
+   */
+  deferMaxDelayMs?: number
+  /**
+   * Failure rate threshold for enabling deferral (0.0 to 1.0).
+   * When exceeded within the failure window, deferral is disabled.
+   */
+  deferFailureThreshold?: number
+  /** Sliding window duration (in milliseconds) for failure rate tracking. */
+  deferFailureWindowMs?: number
+  /**
+   * Cache size for defer middleware.
+   * Controls capacity for store cache and loader cache.
+   */
+  deferCacheSize?: number
+  /** Timeout for Kafka seek operations in milliseconds. */
+  deferSeekTimeoutMs?: number
+  /**
+   * Messages to read sequentially before seeking.
+   * If next offset is within this threshold, reads rather than seeks.
+   */
+  deferDiscardThreshold?: number
+  /**
+   * Fixed timeout duration for handler execution in milliseconds.
+   * If unset, defaults to 80% of stall threshold.
+   */
+  timeoutMs?: number
+  /** Kafka topic to produce telemetry events to. */
+  telemetryTopic?: string
+  /** Whether the telemetry emitter is enabled. */
+  telemetryEnabled?: boolean
+  /**
+   * Span linking for message execution spans.
+   *
+   * Controls how the receive span connects to the `OTel` context propagated
+   * from the Kafka message producer. Accepted values: `"child"` (child-of
+   * relationship) or `"follows_from"`. Default: `"child"`.
+   */
+  messageSpans?: string
+  /**
+   * Span linking for timer execution spans.
+   *
+   * Controls how timer spans connect to the `OTel` context stored when the
+   * timer was scheduled. Accepted values: `"child"` (child-of relationship)
+   * or `"follows_from"`. Default: `"follows_from"`.
+   */
+  timerSpans?: string
+}
+
+/**
+ * Current state of the consumer.
+ * Represents the lifecycle stages of a Prosody consumer.
+ */
+export type ConsumerState = /** The consumer is not yet configured */
+'Unconfigured'|
+/** The consumer is configured but not running */
+'Configured'|
+/** The consumer is actively running */
+'Running'|
+/** The consumer configuration failed */
+'ConfigurationFailed';
+
+/**
+ * Initializes the logging system for the Prosody client.
+ *
+ * This function sets up the tracing infrastructure and prepares the logging
+ * system to accept JavaScript loggers. It should be called once during
+ * application startup before any other logging operations.
+ */
+export declare function initialize(): void
+
+/** Type alias for error classification arguments. */
+export type IsPermanentArgs =
+  [Error]
+
+/** Type alias for the arguments passed to JavaScript logging functions. */
+export type LogArgs =
+  [string | undefined | null, any]
+
+/** JavaScript-compatible logger structure. */
+export interface Logger {
+  /** Function for logging error messages. */
+  error: (arg: LogArgs) => void
+  /** Function for logging warning messages. */
+  warn: (arg: LogArgs) => void
+  /** Function for logging informational messages. */
+  info: (arg: LogArgs) => void
+  /** Function for logging debug messages. */
+  debug: (arg: LogArgs) => void
+  /** Function for logging trace messages. */
+  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
+
+/**
+ * Represents a message consumed from a Kafka topic.
+ *
+ * This object contains all the relevant information about a Kafka message,
+ * including its topic, partition, offset, timestamp, key, and payload.
+ */
+export interface Message {
+  /** The name of the topic from which the message was consumed. */
+  topic: string
+  /** The partition number from which the message was consumed. */
+  partition: number
+  /** The message offset within the partition. */
+  offset: number
+  /** The timestamp when the message was created or sent to Kafka. */
+  timestamp: Date
+  /** The message key. */
+  key: string
+  /** The message payload as a JSON-serializable value. */
+  payload: any
+}
+
+/** Type alias for message handler arguments. */
+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';
+
+/**
+ * Represents a native handler for processing messages and timers.
+ *
+ * This struct contains functions that handle incoming messages, timer events,
+ * and error classification for the Prosody consumer.
+ */
+export interface NativeHandler {
+  /**
+   * A function to be called when a message is received.
+   *
+   * @param context - A Context object representing the message processing
+   * context @param message - A Message object containing the received
+   * Kafka message @param otelContext - A record of string key-value
+   * pairs representing the OpenTelemetry context @returns A Promise that
+   * resolves when the message has been processed
+   *
+   * Note: Error parameter is automatically added by CalleeHandled=true
+   */
+  onMessage: (arg: MessageHandlerArgs) => Promise<undefined>
+  /**
+   * A function to be called when a timer fires.
+   *
+   * @param context - A Context object representing the timer processing
+   * context @param timer - A Timer object containing the timer details
+   * @param otelContext - A record of string key-value pairs representing the
+   * OpenTelemetry context @returns A Promise that resolves when the
+   * timer has been processed
+   *
+   * Note: Error parameter is automatically added by CalleeHandled=true
+   */
+  onTimer: (arg: TimerHandlerArgs) => Promise<undefined>
+  /**
+   * Function that determines whether an error is permanent.
+   *
+   * @param err - An Error object to classify
+   * @returns A boolean that is true when the given error is permanent and
+   * false otherwise
+   */
+  isPermanent: (arg: IsPermanentArgs) => boolean
+}
+
+/**
+ * Sets a new JavaScript logger for the Prosody client.
+ *
+ * This function configures the logging system to use the provided JavaScript
+ * logger for all log output. The logger must implement all required log
+ * 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.
+ *
+ * This function is useful for providing a default logger without overriding
+ * an existing one that may have been set earlier.
+ *
+ * @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.
+ */
+export declare function setLoggerIfUnset(logger: Logger): boolean
+
+/**
+ * Represents a timer event.
+ *
+ * Contains the key and scheduled time for a timer trigger.
+ */
+export interface Timer {
+  /** The timer key. */
+  key: string
+  /** The timer trigger time */
+  time: Date
+}
+
+/** Type alias for timer handler arguments. */
+export type TimerHandlerArgs =
+  [NativeContext, Timer, Record<string, string>]