@polkadot-apps/statement-store 0.2.0

package/dist/client.d.ts

@@ -0,0 +1,133 @@
+import type { PublishOptions, ReceivedStatement, StatementSignerWithKey, StatementStoreConfig, Unsubscribable } from "./types.js";
+/**
+ * High-level client for the Polkadot Statement Store.
+ *
+ * Provides a simple publish/subscribe API over the ephemeral statement store,
+ * handling SCALE encoding, Sr25519 signing, topic management, and resilient
+ * delivery (subscription + polling fallback).
+ *
+ * @example
+ * ```ts
+ * import { StatementStoreClient } from "@polkadot-apps/statement-store";
+ *
+ * const client = new StatementStoreClient({ appName: "my-app" });
+ * await client.connect(signer);
+ *
+ * // 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();
+ * ```
+ */
+export declare class StatementStoreClient {
+    private readonly config;
+    private transport;
+    private signer;
+    private subscription;
+    private pollTimer;
+    private callbacks;
+    private connected;
+    private connectPromise;
+    /**
+     * Track seen statements by channel hex to avoid re-delivering the same statement.
+     * Maps channel hex (or statement data hash) to the expiry value.
+     */
+    private seen;
+    /** Monotonic counter to ensure unique sequence numbers even within the same millisecond. */
+    private sequenceCounter;
+    /** Cached blake2b hash of the appName, used as topic1. */
+    private readonly appTopic;
+    constructor(config: StatementStoreConfig);
+    /**
+     * Connect to the statement store and start receiving statements.
+     *
+     * Establishes the transport connection, starts a real-time subscription
+     * on the application's topic, fetches existing statements, and begins
+     * the polling fallback (if enabled).
+     *
+     * @param signer - The Sr25519 signer used to sign published statements.
+     * @throws {StatementConnectionError} If the transport cannot be established.
+     */
+    connect(signer: StatementSignerWithKey): Promise<void>;
+    private doConnect;
+    /**
+     * Publish typed data to the statement store.
+     *
+     * Encodes the data as JSON, builds a SCALE-encoded statement with the
+     * configured topics and TTL, signs it with Sr25519, and submits it
+     * to the network.
+     *
+     * @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 ("new" or "known"), `false` if rejected.
+     * @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.
+     *
+     * Receives both real-time subscription events and polling results.
+     * Statements are deduplicated by channel + expiry to prevent double delivery.
+     *
+     * @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;
+    /**
+     * Query existing statements from the store.
+     *
+     * Fetches statements that were published before the subscription started.
+     * Useful for catching up on state (e.g., existing presence announcements).
+     *
+     * @typeParam T - The expected data type.
+     * @param options - Optional secondary topic filter.
+     * @returns Array of received statements.
+     */
+    query<T>(options?: {
+        topic2?: string;
+        /** Explicit decryption key for `statement_posted` filtering. If omitted, derived from topic2. */
+        decryptionKey?: Uint8Array;
+    }): Promise<ReceivedStatement<T>[]>;
+    /** 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.
+     */
+    getPublicKeyHex(): string;
+    /**
+     * Destroy the client, stopping polling, unsubscribing, and closing the transport.
+     *
+     * Safe to call multiple times. After destruction, the client cannot be reused.
+     */
+    destroy(): void;
+    private startSubscription;
+    private startPolling;
+    private stopPolling;
+    private poll;
+    /** Remove entries from the seen map whose expiry timestamp is in the past. */
+    private pruneSeenMap;
+    /**
+     * Process a received statement hex, dedup, parse, and deliver to callbacks.
+     * Returns true if the statement was new and delivered.
+     */
+    private handleStatementReceived;
+    private parseStatement;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAER,cAAc,EACd,iBAAiB,EAEjB,sBAAsB,EACtB,oBAAoB,EAEpB,cAAc,EACjB,MAAM,YAAY,CAAC;AAKpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,oBAAoB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAKG;IAE1B,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,MAAM,CAAuC;IACrD,OAAO,CAAC,YAAY,CAA+B;IACnD,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,SAAS,CAA8D;IAC/E,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,cAAc,CAA8B;IAEpD;;;OAGG;IACH,OAAO,CAAC,IAAI,CAA6B;IAEzC,4FAA4F;IAC5F,OAAO,CAAC,eAAe,CAAK;IAE5B,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAEd,MAAM,EAAE,oBAAoB;IAWxC;;;;;;;;;OASG;IACG,OAAO,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;YAgB9C,SAAS;IA6BvB;;;;;;;;;;;;;OAaG;IACG,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAgDrE;;;;;;;;;;OAUG;IACH,SAAS,CAAC,CAAC,EACP,QAAQ,EAAE,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,IAAI,EACnD,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC9B,cAAc;IA0BjB;;;;;;;;;OASG;IACG,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE;QACrB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,iGAAiG;QACjG,aAAa,CAAC,EAAE,UAAU,CAAC;KAC9B,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAAC;IA8BnC,sEAAsE;IACtE,WAAW,IAAI,OAAO;IAItB;;;;OAIG;IACH,eAAe,IAAI,MAAM;IAIzB;;;;OAIG;IACH,OAAO,IAAI,IAAI;IA2Bf,OAAO,CAAC,iBAAiB;IAiBzB,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,WAAW;YAQL,IAAI;IAuBlB,8EAA8E;IAC9E,OAAO,CAAC,YAAY;IAUpB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IA8B/B,OAAO,CAAC,cAAc;CAqBzB"}