@parity/product-sdk-statement-store 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,583 @@
+import { TopicFilter as TopicFilter$1, Statement } from '@novasamatech/sdk-statement';
+export { Proof, TopicFilter as SdkTopicFilter, SignedStatement, Statement, SubmitResult, UnsignedStatement } from '@novasamatech/sdk-statement';
+
+/** Maximum size of a single statement's data payload in bytes. */
+declare const MAX_STATEMENT_SIZE = 512;
+/** Maximum total storage per user in bytes. */
+declare const MAX_USER_TOTAL = 1024;
+/** Default time-to-live for published statements in seconds. */
+declare const DEFAULT_TTL_SECONDS = 30;
+/**
+ * A 32-byte blake2b-256 hash used as a statement topic.
+ *
+ * Topics allow subscribers to filter statements efficiently on the network.
+ * Create one with {@link createTopic}.
+ */
+type TopicHash = Uint8Array & {
+    readonly __brand: "TopicHash";
+};
+/**
+ * A 32-byte blake2b-256 hash used as a statement channel identifier.
+ *
+ * Channels enable last-write-wins semantics: for a given channel,
+ * only the most recent statement (by timestamp) is kept.
+ * Create one with {@link createChannel}.
+ */
+type ChannelHash = Uint8Array & {
+    readonly __brand: "ChannelHash";
+};
+/**
+ * Filter for statement subscriptions and queries.
+ *
+ * - `"any"` — matches all statements (no filtering).
+ * - `{ matchAll: [...] }` — matches statements that have **all** listed topics.
+ * - `{ matchAny: [...] }` — matches statements that have **any** listed topic.
+ */
+type TopicFilter = "any" | {
+    matchAll: TopicHash[];
+} | {
+    matchAny: TopicHash[];
+};
+/**
+ * A function that signs a message with an Sr25519 key.
+ *
+ * Takes the signature material bytes and returns a 64-byte Sr25519 signature.
+ * May be synchronous or asynchronous (e.g., when signing via a hardware wallet).
+ */
+type StatementSigner = (message: Uint8Array) => Uint8Array | Promise<Uint8Array>;
+/**
+ * An Sr25519 signer with its associated public key.
+ *
+ * Used by {@link StatementStoreClient.connect} to sign published statements
+ * when running outside a container (local mode).
+ */
+interface StatementSignerWithKey {
+    /** 32-byte Sr25519 public key. */
+    publicKey: Uint8Array;
+    /** Signing function. */
+    sign: StatementSigner;
+}
+/**
+ * Credentials for connecting to the statement store.
+ *
+ * - **Host mode**: Inside a container, proof creation is delegated to the host API.
+ *   The `accountId` is a `[ss58Address, chainPrefix]` tuple from product-sdk.
+ * - **Local mode**: Outside a container, statements are signed locally using the
+ *   provided Sr25519 signer.
+ */
+type ConnectionCredentials = {
+    mode: "host";
+    accountId: [string, number];
+} | {
+    mode: "local";
+    signer: StatementSignerWithKey;
+};
+/**
+ * Configuration for {@link StatementStoreClient}.
+ *
+ * The client uses the Host API's native statement store protocol.
+ * The SDK is designed to run exclusively inside a host container.
+ */
+interface StatementStoreConfig {
+    /**
+     * Application namespace used as the primary topic (topic1).
+     *
+     * All statements published by this client are tagged with `blake2b(appName)`.
+     * Subscribers filter on this topic to receive only relevant statements.
+     *
+     * @example "ss-webrtc", "mark3t-presence", "my-app"
+     */
+    appName: string;
+    /**
+     * Default time-to-live for published statements in seconds.
+     *
+     * Statements automatically expire after this duration.
+     * Can be overridden per-publish via {@link PublishOptions.ttlSeconds}.
+     *
+     * @default 30
+     */
+    defaultTtlSeconds?: number;
+    /**
+     * Provide a custom transport instead of auto-detection.
+     *
+     * When set, the client uses this transport directly.
+     * Useful for testing or advanced BYOD setups.
+     */
+    transport?: StatementTransport;
+}
+/**
+ * Options for publishing a single statement.
+ */
+interface PublishOptions {
+    /**
+     * Channel name for last-write-wins semantics.
+     *
+     * When provided, the statement is tagged with `blake2b(channel)`.
+     * For a given channel, only the most recent statement is kept.
+     *
+     * @example "presence/peer-abc123", "handshake/alice-bob"
+     */
+    channel?: string;
+    /**
+     * Secondary topic for additional filtering.
+     *
+     * Hashed with blake2b and set as topic2. Useful for scoping
+     * statements to a specific room, document, or context.
+     *
+     * @example "doc-abc123", "room-456"
+     */
+    topic2?: string;
+    /**
+     * Time-to-live in seconds. Overrides {@link StatementStoreConfig.defaultTtlSeconds}.
+     */
+    ttlSeconds?: number;
+    /**
+     * Decryption key hint (32 bytes).
+     *
+     * Used by the `statement_posted` RPC method to filter statements.
+     * Typically set to the blake2b hash of the room or document ID.
+     */
+    decryptionKey?: Uint8Array;
+}
+/**
+ * A received statement with typed data and metadata.
+ *
+ * @typeParam T - The parsed data type (decoded from JSON).
+ */
+interface ReceivedStatement<T = unknown> {
+    /** Parsed data payload. */
+    data: T;
+    /** Signer's public key hex (from proof), if present. */
+    signerHex?: string;
+    /** Channel hex, if present. */
+    channelHex?: string;
+    /** Topics array (hex strings). */
+    topics: string[];
+    /** Combined expiry value (upper 32 bits = timestamp, lower 32 bits = sequence). */
+    expiry?: bigint;
+    /** The full statement from the transport for advanced inspection. */
+    raw: Statement;
+}
+/** Handle returned by subscription methods. Call `unsubscribe()` to stop receiving events. */
+interface Unsubscribable {
+    unsubscribe: () => void;
+}
+/**
+ * Low-level transport interface for statement store communication.
+ *
+ * Uses **HostTransport** — the Host API's native binary protocol.
+ *
+ * Most consumers should use {@link StatementStoreClient} instead of this interface directly.
+ */
+interface StatementTransport {
+    /**
+     * Subscribe to statements matching a topic filter.
+     *
+     * @param filter - sdk-statement topic filter.
+     * @param onStatements - Called with batches of received statements.
+     * @param onError - Called when the subscription encounters an error.
+     * @returns A handle to unsubscribe.
+     */
+    subscribe(filter: TopicFilter$1, onStatements: (statements: Statement[]) => void, onError: (error: Error) => void): Unsubscribable;
+    /**
+     * Sign and submit a statement.
+     *
+     * - **Host mode**: delegates to the host API's `createProof` then `submit`.
+     * - **Local mode**: signs locally using `getStatementSigner` from sdk-statement, then submits.
+     *
+     * @param statement - The unsigned statement to sign and submit.
+     * @param credentials - Signing credentials (host accountId or local signer).
+     */
+    signAndSubmit(statement: Statement, credentials: ConnectionCredentials): Promise<void>;
+    /**
+     * Query existing statements from the store.
+     *
+     * Note: The host API subscription replays initial state, so this may not be needed.
+     */
+    query?(filter: TopicFilter$1): Promise<Statement[]>;
+    /** Destroy the transport and release all resources. */
+    destroy(): void;
+}
+
+/**
+ * High-level client for the Polkadot Statement Store.
+ *
+ * Provides a simple publish/subscribe API over the ephemeral statement store,
+ * handling topic management and signing through the host API.
+ *
+ * The SDK is designed to run exclusively inside a host container.
+ *
+ * @example
+ * ```ts
+ * import { StatementStoreClient } from "@parity/product-sdk-statement-store";
+ *
+ * // Inside a container (host mode)
+ * const client = new StatementStoreClient({ appName: "my-app" });
+ * await client.connect({ mode: "host", accountId: ["5Grw...", 42] });
+ *
+ * // Publish
+ * await client.publish({ type: "presence", peerId: "abc" }, {
+ *     channel: "presence/abc",
+ *     topic2: "room-123",
+ * });
+ *
+ * // Subscribe
+ * client.subscribe<{ type: string }>(statement => {
+ *     console.log(statement.data.type);
+ * });
+ *
+ * // Cleanup
+ * client.destroy();
+ * ```
+ */
+declare class StatementStoreClient {
+    private readonly config;
+    private transport;
+    private credentials;
+    private subscription;
+    private callbacks;
+    private connected;
+    private connectPromise;
+    /** Set by destroy() so doConnect() can abort cleanly if destroy races with an in-flight connect. */
+    private destroyed;
+    /**
+     * Track seen statements by channel hex to avoid re-delivering the same statement.
+     * Maps channel hex (or data hash) to the expiry value.
+     */
+    private seen;
+    /** Monotonic counter to ensure unique sequence numbers even within the same millisecond. */
+    private sequenceCounter;
+    /** Cached hex topic string for the app name, used as the primary subscription topic. */
+    private readonly appTopicHex;
+    constructor(config: StatementStoreConfig);
+    /**
+     * Connect to the statement store and start receiving statements.
+     *
+     * @param credentials - Connection credentials (host accountId or local signer).
+     * @throws {StatementConnectionError} If the transport cannot be established.
+     */
+    connect(credentials: ConnectionCredentials): Promise<void>;
+    /** @deprecated Use `connect({ mode: "local", signer })` instead. */
+    connect(signer: StatementSignerWithKey): Promise<void>;
+    private doConnect;
+    /**
+     * Publish typed data to the statement store.
+     *
+     * @typeParam T - The type of data being published.
+     * @param data - The value to publish (must be JSON-serializable, max 512 bytes).
+     * @param options - Optional channel, topic2, TTL, and decryption key overrides.
+     * @returns `true` if accepted, `false` if rejected or errored.
+     * @throws {StatementConnectionError} If not connected.
+     * @throws {StatementDataTooLargeError} If the encoded data exceeds 512 bytes.
+     */
+    publish<T>(data: T, options?: PublishOptions): Promise<boolean>;
+    /**
+     * Subscribe to incoming statements on this application's topic.
+     *
+     * @typeParam T - The expected data type (decoded from JSON).
+     * @param callback - Called for each new statement.
+     * @param options - Optional secondary topic filter.
+     * @returns A handle to unsubscribe.
+     */
+    subscribe<T>(callback: (statement: ReceivedStatement<T>) => void, options?: {
+        topic2?: string;
+    }): Unsubscribable;
+    /** Whether the client is connected and ready to publish/subscribe. */
+    isConnected(): boolean;
+    /**
+     * Get the signer's public key as a hex string (with 0x prefix).
+     *
+     * @returns The hex-encoded public key, or empty string if not connected or in host mode.
+     */
+    getPublicKeyHex(): string;
+    /**
+     * Destroy the client, unsubscribing and closing the transport.
+     *
+     * Safe to call multiple times. After destruction, the client cannot be reused.
+     */
+    destroy(): void;
+    private startSubscription;
+    /** Remove entries from the seen map whose expiry timestamp is in the past. */
+    private pruneSeenMap;
+    /**
+     * Process a received statement, dedup, parse, and deliver to callbacks.
+     * Returns true if the statement was new and delivered.
+     */
+    private handleStatementReceived;
+    private parseStatement;
+    /** Build an SdkTopicFilter for the app's primary topic. */
+    private buildFilter;
+}
+
+/**
+ * Higher-level abstraction providing last-write-wins channel semantics
+ * over the statement store.
+ *
+ * Each channel name maps to a single value. When a new value is written
+ * to a channel, it replaces the previous one if its timestamp is newer.
+ * This is ideal for presence announcements, signaling, and ephemeral state.
+ *
+ * @typeParam T - The type of values stored in channels.
+ *   Values should include a `timestamp` field for ordering;
+ *   if omitted, the current time is used automatically.
+ *
+ * @example
+ * ```ts
+ * interface Presence {
+ *     type: "presence";
+ *     peerId: string;
+ *     timestamp: number;
+ * }
+ *
+ * const channels = new ChannelStore<Presence>(client, { topic2: "doc-123" });
+ *
+ * // Write presence
+ * await channels.write("presence/peer-abc", {
+ *     type: "presence",
+ *     peerId: "abc",
+ *     timestamp: Date.now(),
+ * });
+ *
+ * // Read all presences
+ * for (const [name, value] of channels.readAll()) {
+ *     console.log(`${name}: ${value.peerId}`);
+ * }
+ *
+ * // React to changes
+ * channels.onChange((name, value, previous) => {
+ *     console.log(`Channel ${name} updated`);
+ * });
+ *
+ * channels.destroy();
+ * ```
+ */
+declare class ChannelStore<T extends {
+    timestamp?: number;
+}> {
+    private readonly client;
+    private readonly topic2;
+    private readonly values;
+    /** Maps human-readable channel names to their hex hash keys, for consistent lookup. */
+    private readonly nameToHash;
+    private readonly changeCallbacks;
+    private subscription;
+    /**
+     * @param client - The connected {@link StatementStoreClient} to use.
+     * @param options - Optional secondary topic for scoping channels.
+     */
+    constructor(client: StatementStoreClient, options?: {
+        topic2?: string;
+    });
+    /**
+     * Write a value to a named channel.
+     *
+     * If the value doesn't include a `timestamp`, one is added automatically
+     * using `Date.now()`. The value is published to the statement store
+     * with the channel name as the statement channel.
+     *
+     * @param channelName - The channel name (e.g., "presence/peer-abc").
+     * @param value - The value to write.
+     * @returns `true` if the statement was accepted by the network.
+     */
+    write(channelName: string, value: T): Promise<boolean>;
+    /**
+     * Read the latest value for a channel by its human-readable name.
+     *
+     * Looks up the channel hash from the name, then retrieves the value.
+     * Also checks the hash directly for values received from the network
+     * before any local write established the name mapping.
+     *
+     * @param channelName - The channel name (e.g., "presence/peer-abc").
+     * @returns The latest value, or `undefined` if no value has been received.
+     */
+    read(channelName: string): T | undefined;
+    /**
+     * Read all channel values as a read-only map.
+     *
+     * Keys are hex-encoded channel hashes. Use {@link read} for
+     * lookup by human-readable name.
+     *
+     * @returns A map of channel hash to latest value.
+     */
+    readAll(): ReadonlyMap<string, T>;
+    /**
+     * Get the number of channels currently tracked.
+     */
+    get size(): number;
+    /**
+     * Subscribe to channel value changes.
+     *
+     * The callback is invoked whenever a channel value is updated
+     * (either from the network or from a local write).
+     *
+     * @param callback - Called with the channel key (hex hash for network-received, hex hash for local writes), new value, and previous value.
+     * @returns A handle to unsubscribe.
+     */
+    onChange(callback: (channelName: string, value: T, previous: T | undefined) => void): Unsubscribable;
+    /**
+     * Destroy the channel store and clean up subscriptions.
+     *
+     * Does not destroy the underlying client.
+     */
+    destroy(): void;
+    private handleStatement;
+    private updateChannel;
+}
+
+/**
+ * Create a 32-byte topic hash from a human-readable string.
+ *
+ * Uses blake2b-256 to hash the UTF-8 encoded string into a deterministic
+ * 32-byte topic identifier. Statements are tagged with topics so subscribers
+ * can filter efficiently on the network.
+ *
+ * @param name - A human-readable topic name (e.g., "ss-webrtc", "my-app").
+ * @returns A branded 32-byte topic hash.
+ *
+ * @example
+ * ```ts
+ * const topic = createTopic("ss-webrtc");
+ * // Use in subscriptions and publish options
+ * ```
+ */
+declare function createTopic(name: string): TopicHash;
+/**
+ * Create a 32-byte channel hash from a human-readable channel name.
+ *
+ * Channels enable last-write-wins semantics: for a given channel,
+ * only the most recent statement (by timestamp) is retained.
+ *
+ * @param name - A human-readable channel name (e.g., "presence/peer-abc").
+ * @returns A branded 32-byte channel hash.
+ *
+ * @example
+ * ```ts
+ * const channel = createChannel("presence/peer-abc123");
+ * ```
+ */
+declare function createChannel(name: string): ChannelHash;
+/**
+ * Convert a topic or channel hash to a hex string (with 0x prefix).
+ *
+ * @param hash - A 32-byte topic or channel hash.
+ * @returns Hex string with "0x" prefix.
+ */
+declare function topicToHex(hash: Uint8Array): string;
+/**
+ * Compare two topic or channel hashes for byte equality.
+ *
+ * @param a - First hash.
+ * @param b - Second hash.
+ * @returns True if the hashes are identical.
+ */
+declare function topicsEqual(a: Uint8Array, b: Uint8Array): boolean;
+/**
+ * Serialize a {@link TopicFilter} into the JSON-RPC format expected by statement store nodes.
+ *
+ * - `"any"` is passed through as the string `"any"`.
+ * - `{ matchAll: [...] }` becomes `{ matchAll: ["0x...", ...] }` with hex-encoded topics.
+ * - `{ matchAny: [...] }` becomes `{ matchAny: ["0x...", ...] }` with hex-encoded topics.
+ *
+ * @param filter - The topic filter to serialize.
+ * @returns A JSON-RPC compatible filter value.
+ */
+declare function serializeTopicFilter(filter: TopicFilter): TopicFilter$1;
+
+/** Convert a hex string (with or without 0x prefix) to bytes. */
+declare function fromHex(hex: string): Uint8Array;
+/** Convert bytes to a hex string with 0x prefix. */
+declare function toHex(bytes: Uint8Array): string;
+/**
+ * Encode a value as a JSON-serialized data payload for a statement.
+ *
+ * Serializes the value as JSON and encodes to UTF-8 bytes.
+ * Throws {@link StatementDataTooLargeError} if the result exceeds
+ * {@link MAX_STATEMENT_SIZE} bytes.
+ *
+ * @typeParam T - The type of value being encoded.
+ * @param value - The value to serialize.
+ * @returns UTF-8 encoded JSON bytes.
+ * @throws {StatementDataTooLargeError} If the encoded data exceeds 512 bytes.
+ */
+declare function encodeData<T>(value: T): Uint8Array;
+/**
+ * Decode a JSON-serialized data payload from statement bytes.
+ *
+ * @typeParam T - The expected parsed type.
+ * @param bytes - UTF-8 encoded JSON bytes.
+ * @returns The parsed value.
+ * @throws {StatementEncodingError} If the bytes are not valid UTF-8 or valid JSON.
+ */
+declare function decodeData<T>(bytes: Uint8Array): T;
+
+/**
+ * Create a statement store transport.
+ *
+ * Uses the Host API via `@parity/product-sdk-host` — the container's native
+ * statement store protocol (binary, not JSON-RPC). This is the only supported path.
+ *
+ * @throws {StatementConnectionError} If the host statement store is unavailable.
+ */
+declare function createTransport(): Promise<StatementTransport>;
+
+/**
+ * Base class for all statement store errors.
+ *
+ * Use `instanceof StatementStoreError` to catch any error originating
+ * from the statement store package.
+ */
+declare class StatementStoreError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * A SCALE encoding or decoding operation failed.
+ *
+ * Thrown when statement bytes cannot be parsed (corrupt data, unknown field tags)
+ * or when encoding produces invalid output.
+ */
+declare class StatementEncodingError extends StatementStoreError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * The statement store node rejected a submitted statement.
+ *
+ * Carries the raw RPC response detail for programmatic inspection.
+ */
+declare class StatementSubmitError extends StatementStoreError {
+    /** The raw response from the RPC call. */
+    readonly detail: unknown;
+    constructor(detail: unknown);
+}
+/**
+ * Failed to set up or maintain a statement subscription.
+ *
+ * This is a non-fatal error — the client falls back to polling
+ * when subscriptions are unavailable.
+ */
+declare class StatementSubscriptionError extends StatementStoreError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Failed to connect to the statement store transport.
+ *
+ * Thrown when the WebSocket connection cannot be established
+ * or the chain-client's bulletin chain is not connected.
+ */
+declare class StatementConnectionError extends StatementStoreError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * The statement data payload exceeds the maximum allowed size.
+ *
+ * The statement store protocol limits individual statement data
+ * to {@link MAX_STATEMENT_SIZE} bytes (512 bytes).
+ */
+declare class StatementDataTooLargeError extends StatementStoreError {
+    /** The actual size of the data in bytes. */
+    readonly actualSize: number;
+    /** The maximum allowed size in bytes. */
+    readonly maxSize: number;
+    constructor(actualSize: number, maxSize?: number);
+}
+
+export { type ChannelHash, ChannelStore, type ConnectionCredentials, DEFAULT_TTL_SECONDS, MAX_STATEMENT_SIZE, MAX_USER_TOTAL, type PublishOptions, type ReceivedStatement, StatementConnectionError, StatementDataTooLargeError, StatementEncodingError, type StatementSigner, type StatementSignerWithKey, StatementStoreClient, type StatementStoreConfig, StatementStoreError, StatementSubmitError, StatementSubscriptionError, type StatementTransport, type TopicFilter, type TopicHash, type Unsubscribable, createChannel, createTopic, createTransport, decodeData, encodeData, fromHex, serializeTopicFilter, toHex, topicToHex, topicsEqual };