@ixo/openhands-sdk 0.0.0-stage → 0.2.0

package/dist/cjs/campaign/fold.d.ts

@@ -0,0 +1,227 @@
+/**
+ * The campaign, folded once and read many times.
+ *
+ * `campaignCollections` used to be a walk: every claim collection since the
+ * campaign began, paged from the index, and a terms document fetched for
+ * each to learn whether it belonged here and what kind of ask it was — per
+ * request, per instance, inside a budget it ran out of most evenings, at
+ * which point which asks made it into the fold depended on how fast the
+ * index felt. When the mapping ask was among the ones it dropped, the map
+ * had no pins.
+ *
+ * The terms are content-addressed and never change, so the classification
+ * is a fact worth writing down once. The worker does that (workers/src/fold)
+ * and publishes the folded shape; this module is the two halves everybody
+ * else needs: the one classifier, so the walk, the worker's posting hook and
+ * the reader can never disagree about what an ask is, and the reader that
+ * turns a published fold back into `CampaignCollections`.
+ *
+ * Nothing here imports `spots.ts` at runtime: `spots.ts` imports this.
+ */
+import type { CampaignCollections, Pin } from "./spots.ts";
+export type AskKind = "mess-report" | "field-report" | "commitment" | "cleanup" | "other";
+export interface Classified {
+    campaign: string | null;
+    kind: AskKind;
+    /** A cleanup: the pin it clears. */
+    clears: string | null;
+}
+/**
+ * What an ask is, from its terms — the rule the walk always applied, in one
+ * place. A document that names no campaign is nobody's; a deliverable type
+ * decides the bucket; a `clears` with no recognised type is a cleanup.
+ */
+export declare function classifyTerms(terms: unknown): Classified;
+/** The published shape: the four buckets, newest first, with each cleanup's pin. `open` is recomputed on read. */
+export interface CampaignFoldBody {
+    campaign: string;
+    foldedAt: string;
+    mapping: CampaignCollections["mapping"];
+    cleanups: {
+        node: CampaignCollections["cleanups"][number]["node"];
+        clears: string;
+    }[];
+    reports: CampaignCollections["reports"];
+    commitments: CampaignCollections["commitments"];
+}
+/** An ask is open while its deadline stands and its state says so — the same rule every surface uses. */
+export declare const askOpen: (node: {
+    state: number;
+    endDate: string | null;
+}, now?: number) => boolean;
+/** A fold as the apps consume it. `open` is a function of the clock, so it is decided here, not when the fold was written. */
+export declare function fromFold(body: CampaignFoldBody, now?: number): CampaignCollections;
+/**
+ * Where a fold comes from.
+ *
+ * The worker reads its own D1 and registers that here; everybody else asks
+ * the worker over HTTP (`GET /campaign/<tag>/collections`, edge-cached), at
+ * the address the grant proxy already uses. Null means "no fold to be had",
+ * and the caller walks the index as it always did — so a deployment without
+ * the worker, or with one that has not folded yet, is slower and not broken.
+ */
+export type CampaignFoldSource = (campaign: string) => Promise<CampaignFoldBody | null>;
+export declare function useCampaignFold(reader: CampaignFoldSource | null): void;
+/** The campaign worker: `configure({ workerUrl })`, else `WORKER_URL` or `NEXT_PUBLIC_WORKER_URL`, else "". */
+export declare const workerUrl: () => string;
+/** Where the published fold is read: `configure({ campaignFoldUrl })`, else `CAMPAIGN_FOLD_URL`, else the worker. */
+export declare const campaignFoldUrl: () => string;
+export declare const FOLD_TIMEOUT_MS = 6000;
+/** The worker's published fold, or null for any reason — a missing address, a 404, a slow answer, a body that is not a fold. */
+export declare function fetchCampaignFold(campaign: string, fetchImpl?: typeof fetch): Promise<CampaignFoldBody | null>;
+/** The registered source first, the worker's endpoint otherwise. */
+export declare function readCampaignFold(campaign: string): Promise<CampaignFoldBody | null>;
+type Collection = CampaignCollections["mapping"][number];
+export declare const COLLECTION_FIELDS = "id state endDate entity admin quota evaluated payments\n          claimsByCollectionId { nodes { claimId submissionDate agentAddress evaluationByClaimId { status evaluationDate } } }";
+/**
+ * How many of a mapping ask's claims the live read takes: the newest.
+ *
+ * Read whole, a mapping ask with two thousand claims is half a megabyte every
+ * thirty seconds, per server — to find the one pin mapped since the last
+ * publish. The worker already holds every older pin as a row
+ * (`readCampaignPins`); what only the index knows is what is NEW, and new is
+ * the head of this list. A claim submitted long ago and approved just now is
+ * not in it, and is picked up by the worker's next publish instead.
+ */
+export declare const LIVE_CLAIMS = 100;
+export type NodeReader = (ids: string[]) => Promise<Collection[]>;
+/** The index's own copy of these collections, a hundred ids to a query. */
+export declare const liveNodes: NodeReader;
+/** The same campaign, its mapping asks as the index has them now. Order kept; a failed read changes nothing. */
+export declare function liveMapping(collections: CampaignCollections, read?: NodeReader): Promise<CampaignCollections>;
+/**
+ * Pins approved a moment ago that no cleanup ask clears yet.
+ *
+ * The campaign posts a cleanup ask for every approved pin, on its pass. A pin
+ * in this list is one the pass still owes — which is the only reason a nudge
+ * is allowed to ask for a pass ahead of the clock. Bounded to recent
+ * approvals on purpose: a pin the campaign decided not to fund (gone,
+ * hazardous, for professionals) is owed nothing, and must not keep asking.
+ */
+export declare function owedPins(body: CampaignFoldBody, now?: number, windowMs?: number): string[];
+/** `owedPins`, over plain claim facts — what the rows publisher has in hand, which is not a fold body. */
+export declare function owedAmong(claims: {
+    claimId: string;
+    status: number | null;
+    decidedAt: string | null;
+}[], cleared: ReadonlySet<string>, now?: number, windowMs?: number): string[];
+export declare const NUDGE_TIMEOUT_MS = 2500;
+/**
+ * Tell the worker the campaign just changed, so it publishes now rather than
+ * at its next tick. Best-effort by design: the clock still folds every ten
+ * minutes, so a nudge that is lost costs minutes and never correctness. It
+ * never throws and never waits long — it is called from a poll.
+ */
+export declare function nudgeCampaignFold(campaign: string, fetchImpl?: typeof fetch, proxy?: Record<string, string>): Promise<boolean>;
+export type PublishedKind = Exclude<AskKind, "other">;
+export interface FoldNodeWire {
+    id: string;
+    kind: PublishedKind;
+    clears: string | null;
+    node: Collection;
+}
+export interface FoldNodesPage {
+    campaign: string;
+    foldedAt: string;
+    through: string;
+    rows: FoldNodeWire[];
+    next: string | null;
+}
+export interface FoldPinWire {
+    claimId: string;
+    approved: boolean;
+    pin: Pin | null;
+}
+export interface FoldPinsPage {
+    campaign: string;
+    through: string;
+    rows: FoldPinWire[];
+    next: string | null;
+}
+export declare const ROWS_PAGE = 500;
+export declare const SYNC_OVERLAP_MS = 10000;
+/** The fold the apps consume, from its rows — newest ask first, as the walk always had it. */
+export declare function bodyFromNodes(campaign: string, foldedAt: string, nodes: Iterable<FoldNodeWire>): CampaignFoldBody;
+/** For tests: forget everything this process has synced. */
+export declare function forgetSyncedRows(): void;
+/**
+ * Every pin the worker has read, by claim id — or null when there is nobody
+ * to ask, which sends the reader back to fetching each claim's body itself.
+ *
+ * The map's readers used to fetch the sealed body of EVERY approved claim,
+ * eight at a time, whenever their hour-long cache was cold: a minute for two
+ * thousand pins, which no page waits. The worker reads each body once and
+ * keeps the pin it makes (`campaign_pins`); this is that, synced the same way
+ * the asks are. A claim whose verdict stops being approved is in the
+ * difference too, and is dropped here.
+ */
+export type CampaignPinSource = (campaign: string) => Promise<Map<string, Pin> | null>;
+/** Register where this process reads pins from (the worker: its own D1), or null to fetch the worker's door. */
+export declare function useCampaignPins(reader: CampaignPinSource | null): void;
+export declare function fetchCampaignPins(campaign: string, fetchImpl?: typeof fetch): Promise<Map<string, Pin> | null>;
+export declare function readCampaignPins(campaign: string): Promise<Map<string, Pin> | null>;
+/**
+ * The campaign's leaderboards, as the worker last folded them.
+ *
+ * One request, no parameters, and nothing said about who is asking. A phone
+ * works out its own place from the `spread` histogram against totals it
+ * already has, so being told "thirty-first" costs it no disclosure at all.
+ *
+ * Null on anything at all — no worker configured, a campaign never folded,
+ * a store that will not answer. The boards are an ornament on a page that
+ * works without them, and a page that fails because a leaderboard did is a
+ * worse page than one with no leaderboard.
+ */
+/**
+ * One row as the worker publishes it — `Standing` from `standings.ts`, typed
+ * for the reader. `name`, `source` and `account` are additive and optional
+ * here because the worker and the apps ship in either order: a body folded
+ * before they existed has only `alias`, and a reader renders
+ * `row.name ?? row.alias` until every fold carries them. Nothing else is ever
+ * on a row: no address, no Matrix id, no full display name, no avatar.
+ */
+export interface StandingRowWire {
+    creature: string;
+    /** The typed nickname, through cleanName — what clients before `name` render. */
+    alias: string | null;
+    /** The display name by precedence: account (opted in) › alias › generated. */
+    name?: string;
+    source?: "account" | "alias" | "generated";
+    /** A signed-in account; only ever true beside a chosen name. Label it "signed-in account", never "verified". */
+    account?: boolean;
+    count: number;
+    rank: number;
+}
+export interface StandingsWire {
+    campaign: string;
+    at: string;
+    since: string;
+    week: Record<string, StandingRowWire[]>;
+    all: Record<string, StandingRowWire[]>;
+    spread: {
+        week: Record<string, Record<string, number>>;
+        all: Record<string, Record<string, number>>;
+    };
+}
+/** The Next.js cache tag on every standings read, so a switch-off can drop them at once. */
+export declare const STANDINGS_TAG = "standings";
+export declare function fetchStandings(campaign: string, init?: {
+    timeoutMs?: number;
+    revalidate?: number;
+}): Promise<StandingsWire | null>;
+/**
+ * Send somebody's name preference for the board to the worker:
+ * `POST <fold>/campaign/<campaign>/name` with `body` as JSON.
+ *
+ * The body is the worker's contract, not this function's — it passes it on
+ * untouched. What comes back is the status and whatever JSON the worker said
+ * (null when it said none), so a caller can tell a refusal from a success
+ * and show the worker's reason. Null only when the worker could not be
+ * reached at all: none configured, the network, or the timeout.
+ */
+export declare function postNamePref(campaign: string, body: unknown, fetchImpl?: typeof fetch, timeoutMs?: number): Promise<{
+    status: number;
+    json: unknown;
+} | null>;
+export {};
+//# sourceMappingURL=fold.d.ts.map

package/dist/cjs/campaign/fold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold.d.ts","sourceRoot":"","sources":["../../../src/campaign/fold.ts"],"names":[],"mappings":"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"}