@bitsocial/pubsub-voting 0.0.6

package/dist/client/voter.d.ts

@@ -0,0 +1,239 @@
+import { type Criteria } from "../schema/criteria.js";
+import { type Vote, type VotesBundle } from "../schema/votes.js";
+import type { ChainClientFactory, NameResolver } from "../chain/types.js";
+import type { HeliaInstance } from "../transport/types.js";
+import type { RuleRegistry } from "../rules/types.js";
+import type { ContestTally } from "../tally/types.js";
+import type { VoteSigner } from "../signer/types.js";
+/**
+ * The recommended cadence, in buckets, at which a client should re-publish a live vote to keep
+ * it alive: half its expiry window, rounded up. A bundle is valid for `voteExpiryBuckets` after
+ * its `blockNumber` (see DESIGN.md "Passive expiry"), so re-signing at the halfway point leaves
+ * one full missed cycle of slack before the vote decays. Derived per-contest from the criteria —
+ * there is no global interval.
+ *
+ * This library does NOT re-publish on its own: deciding when (or whether) to refresh a vote is
+ * the consuming client's job (see DESIGN.md "Republishing is the client's job"). This helper, the
+ * `blockNumber` on a published `VotesBundle`, and `criteria.voteExpiryBuckets` /
+ * `criteria.blocksPerBucket` are what a client uses to schedule its own refreshes: a vote sampled
+ * at bucket `b` expires once the current bucket exceeds `b + voteExpiryBuckets`; refresh by
+ * calling `createContestVote({ criteria, votes }).publish()` again before then.
+ */
+export declare function republishIntervalBuckets(criteria: Criteria): number;
+/**
+ * Public facade — three objects, mirroring pkc-js / plebbit-js:
+ *   - {@link PubsubVoter} (`VoteClient`): the factory. Holds the host-injected dependencies once
+ *     and owns one engine per contest, keyed by topic. A contest is addressed by its full criteria
+ *     document — `createContest({ criteria })` validates it and derives the topic — so a directory
+ *     host like 5chan authors its 63 documents however it likes (e.g. merged from a local
+ *     manifest) and creates each contest, without wiring dependencies 63 times.
+ *   - {@link Contest} (`createContest`): one contest's reactive **read** view. `update()` starts
+ *     syncing and emits `update` (carrying a fresh `tally`) / `error`, like `subplebbit.update()`.
+ *   - {@link ContestVote} (`createContestVote`): one publishable **ballot**. `publish()` signs and
+ *     broadcasts it once, emitting `publishingstatechange` / `error`, like a plebbit publication.
+ *
+ * The injected seams (helia, chains, signer, nameResolvers) are the ONLY host contact surface, so
+ * the same core runs under pkc-js, plebbit, or a raw node. The host passes its running Helia node
+ * directly — no adapter — and the library drives that node's gossipsub service and blockstore
+ * itself. A voter built without a `signer` is read-only (tallies readable, publishing disabled).
+ *
+ * Republishing a live vote so it does not decay is deliberately NOT this library's job — it
+ * publishes each vote once and the client decides when to refresh (see
+ * {@link republishIntervalBuckets} and DESIGN.md "Republishing is the client's job").
+ */
+/** A vote publication's lifecycle, walked by {@link ContestVote.publish}. */
+export type PublishingState = "stopped" | "signing" | "publishing" | "succeeded" | "failed";
+/** What {@link ContestVote.publish} resolves: the signed bundle plus a peer-reach hint. */
+export interface PublishOutcome {
+    /** The signed bundle; its `blockNumber` drives the client's own refresh schedule. */
+    readonly bundle: VotesBundle;
+    /**
+     * How many peers gossipsub sent this vote *directly* to — first-hop fan-out, not total network
+     * reach and not an acceptance confirmation (each recipient still runs the forward-gate before
+     * re-forwarding). Handy as a coarse "did this reach anyone?" signal: `0` means the message went
+     * nowhere. Note gossipsub instead *rejects* the publish with `NoPeersSubscribedToTopic` when it
+     * would reach zero peers, unless the host enables `allowPublishToZeroTopicPeers` — so a
+     * resolved `recipientCount === 0` only happens under that host setting.
+     */
+    readonly recipientCount: number;
+}
+/** One contest's reactive read view: subscribe, keep the tally in sync, read it. */
+export interface Contest {
+    /** The criteria document this contest runs (already validated). */
+    readonly criteria: Criteria;
+    /** The gossipsub topic = "bitsocial-votes/" + CID(dag-cbor(criteria)). */
+    readonly topic: string;
+    /**
+     * The last computed tally, refreshed before each `update` event; `undefined` until the first
+     * compute (i.e. before `update()` resolves). For a forced fresh read use {@link getTally}.
+     */
+    readonly tally: ContestTally | undefined;
+    /**
+     * Join the topic behind the validate-before-forward gate, pull the cold-start checkpoint, and
+     * begin emitting `update` events as incoming votes change the state. Resolves once the initial
+     * tally is computed (so {@link tally} is populated). Idempotent.
+     */
+    update(): Promise<void>;
+    /** Stop syncing and leave the topic. Does not stop the host node. Idempotent. */
+    stop(): Promise<void>;
+    /** Compute the current contest ranking fresh, bypassing the cache. */
+    getTally(): Promise<ContestTally>;
+    /**
+     * Fired when incoming votes change the state; `tally` carries the freshly recomputed
+     * ranking. Background check settlements fire it too: a cold join emits a first tally with
+     * `chainVerified: false` rows immediately, then re-emits as the batched gate reads and name
+     * resolutions land (see DESIGN.md "Background chain verification").
+     */
+    on(event: "update", cb: () => void): void;
+    /**
+     * Fired on a contest-level failure: the tally's chain read throws, or the background chain
+     * verifier hits an infra-class failure (RPC/resolver down — its bundles stay pending and
+     * retry, but the degradation is surfaced here instead of silently stalling).
+     */
+    on(event: "error", cb: (error: unknown) => void): void;
+}
+/** One publishable ballot for a contest. Create it, then `publish()`. */
+export interface ContestVote {
+    /** The `contestId` this ballot targets. */
+    readonly contestId: string;
+    /** The gossipsub topic the bundle publishes to. */
+    readonly topic: string;
+    /** The votes this ballot will sign and broadcast (empty array = a withdrawal). */
+    readonly votes: readonly Vote[];
+    /** Where in the publish lifecycle this ballot is. */
+    readonly publishingState: PublishingState;
+    /** The signed bundle, once `publish()` has produced it (`undefined` before then). */
+    readonly bundle: VotesBundle | undefined;
+    /**
+     * Sign the votes into a bundle for the current bucket, add it to the local CRDT, and broadcast
+     * it once as a live delta. Joins the topic first if needed. Resolves a {@link PublishOutcome}:
+     * the `VotesBundle` (whose `blockNumber` the client uses to schedule its own refresh — see
+     * {@link republishIntervalBuckets}) plus `recipientCount`, the number of peers gossipsub sent
+     * the vote directly to. Emits `publishingstatechange` as it goes; throws (and emits `error`) on
+     * failure, and `ReadOnlyError` with no signer. This library does not re-publish: to keep the
+     * vote alive, call `publish()` again before it expires.
+     */
+    publish(): Promise<PublishOutcome>;
+    /** Fired on each `publishingState` transition. */
+    on(event: "publishingstatechange", cb: (state: PublishingState) => void): void;
+    /** Fired if publishing fails. */
+    on(event: "error", cb: (error: unknown) => void): void;
+}
+/** The factory: one set of injected dependencies, many contests. */
+export interface VoteClient {
+    /** True when constructed without a signer: every contest is read-only. */
+    readonly readOnly: boolean;
+    /**
+     * Create the reactive read view for one contest from its full criteria document. The document
+     * is strictly validated (`CriteriaSchema` + the rule registry — an unimplemented rule throws
+     * `UnknownRuleError`) and its topic derived (`topic = CID(dag-cbor(criteria))`). Returns the
+     * stable per-topic object (one CRDT/engine per topic per node), so repeated calls with
+     * byte-identical criteria return the same `Contest`.
+     */
+    createContest(args: {
+        criteria: Criteria;
+    }): Promise<Contest>;
+    /**
+     * Create a publishable ballot for one contest, validated and addressed exactly like
+     * `createContest`. Each call returns a fresh `ContestVote` over the shared per-topic engine;
+     * pass `votes: []` to build a withdrawal.
+     */
+    createContestVote(args: {
+        criteria: Criteria;
+        votes: Vote[];
+    }): Promise<ContestVote>;
+    /**
+     * Leave every topic this client joined, resetting each read view so it can `update()` again.
+     * The checkpoint fetch responder unregisters itself once the last topic is left (see
+     * `PubsubVoter`'s lazy responder lifecycle). The client stays fully reusable — call
+     * `createContest` / `update()` after.
+     */
+    stop(): Promise<void>;
+    /**
+     * Terminal teardown (mirrors pkc-js `destroy`): leave every topic, unregister the fetch
+     * responder, and mark the voter and all its contests destroyed. Unlike `stop`, this is NOT
+     * reusable — every subsequent `createContest` / `createContestVote`, and any pre-existing
+     * `Contest.update()` / `ContestVote.publish()`, throws `VoterDestroyedError`. Construct a new
+     * `PubsubVoter` to participate again. There is no store to dispose (republishing / persistence
+     * is the client's concern).
+     */
+    destroy(): Promise<void>;
+}
+/** Construction options for {@link PubsubVoter}. */
+export interface PubsubVoterOptions {
+    /**
+     * The host's running Helia node (the value `createHelia` returns; for pkc-js it is
+     * `pkc.clients.libp2pJsClients[key]._helia`). The only host-node seam, passed
+     * directly with no adapter. It MUST carry a gossipsub service at
+     * `libp2p.services.pubsub`, a usable `blockstore`, and a libp2p fetch service at
+     * `libp2p.services.fetch`; the constructor throws `MissingPubsubError` /
+     * `MissingBlockstoreError` / `MissingFetchError` otherwise (a plain Helia node has
+     * no pubsub). The library never starts or stops this node.
+     */
+    helia: HeliaInstance;
+    /**
+     * Builds a chain client from a `{ chain, config }` pair. Each contest builds its
+     * own clients from `criteria.requires.chains` via this factory, so chains are
+     * per-contest data, not a global injection.
+     */
+    chains: ChainClientFactory;
+    /** Identity. Omit for a read-only voter (renders tallies, cannot publish). */
+    signer?: VoteSigner;
+    /** Rule overrides that shadow built-ins by `type` (a flat `type -> rule` map). */
+    rules?: RuleRegistry;
+    /**
+     * Community-name resolvers, same instances a host gives pkc-js (e.g.
+     * `@bitsocial/bso-resolver` for `name.bso`). The tally resolves each vote's
+     * `community.name` claim through the first resolver whose `canResolve` matches and
+     * drops bundles whose name does not resolve to the claimed `publicKey`. Omit only
+     * if no contest's votes carry names — with no resolver for a carried name's TLD,
+     * the claim cannot be verified and the bundle is dropped (never counted unchecked).
+     */
+    nameResolvers?: NameResolver[];
+    /**
+     * Delegated Routing V1 router base URLs to ANNOUNCE provider records to (one unsigned
+     * `PUT /routing/v1/providers` per router, `Keys` batched across all joined contests:
+     * each contest's criteria CID + current checkpoint root + chunk CIDs — hourly, debounced
+     * on checkpoint/root changes, and on `self:peer:update` address changes). Absent or empty
+     * means never announce — the default, correct for plain clients: only a publicly dialable
+     * node (a seeder) should set this, and the browser build never announces regardless (the
+     * announcer is a Node-only module, stubbed inert by the package.json `browser` remap).
+     * QUERYING needs no URLs here — `#discoverProviders` rides the injected node's
+     * `libp2p.contentRouting`, which the host wires its routers into; this option exists only
+     * because the pinned js stack has no working announce path (`provide()` is a noop). See
+     * DESIGN.md "Deferred pkc-js work", provider-record announces.
+     */
+    httpRouterUrls?: string[];
+    /**
+     * Directory for the voter's persistent caches (gate results, name resolutions), the
+     * pkc-js `dataPath` equivalent. On Node the caches are better-sqlite3 databases under
+     * `{dataPath}/lru-storage/`; in the browser the path is ignored and the caches live in
+     * IndexedDB (via localforage) either way. Defaults to `{cwd}/.bitsocial-pubsub-voting`
+     * on Node. Pass `false` for in-memory-only caches (no disk, no IndexedDB — the pkc-js
+     * `noData` equivalent): nothing survives the process, but nothing is written either.
+     */
+    dataPath?: string | false;
+}
+/**
+ * The default `VoteClient`. Construct with the host-injected seams: a `helia` node (must carry a
+ * gossipsub service, a blockstore, and a libp2p fetch service), a `chains` factory, an optional
+ * `signer`, and optional `nameResolvers` (needed once votes carry community names). Contests are
+ * addressed by their full criteria document at `createContest` / `createContestVote`; the library
+ * has no knowledge of pkc-js or any other host: a host passes its own running Helia node in
+ * directly. Republishing a live vote is the client's concern — see
+ * {@link republishIntervalBuckets} and DESIGN.md "Republishing is the client's job".
+ */
+export declare class PubsubVoter implements VoteClient {
+    #private;
+    constructor(options: PubsubVoterOptions);
+    get readOnly(): boolean;
+    createContest(args: {
+        criteria: Criteria;
+    }): Promise<Contest>;
+    createContestVote(args: {
+        criteria: Criteria;
+        votes: Vote[];
+    }): Promise<ContestVote>;
+    stop(): Promise<void>;
+    destroy(): Promise<void>;
+}