@ixo/openhands-sdk 0.0.0-stage → 0.1.0

package/dist/cjs/chain/ask.d.ts

@@ -0,0 +1,211 @@
+import type { EncodeObject } from "@cosmjs/proto-signing";
+import { type PhonePrompt, type SignHooks, type SignResult } from "./signWith.ts";
+import { type AskDenom } from "./money.ts";
+import { didOf } from "./iid.ts";
+import type { QiSession } from "./session.ts";
+export { didOf };
+/**
+ * The claim form the rubric at `#rub` is bound to — where it lives and its
+ * proof, the two values `scripts/publish-vct.ts` printed
+ * (`NEXT_PUBLIC_VCT_URL`, `NEXT_PUBLIC_VCT_PROOF`). The same shape the worker
+ * builds in `@ixo/openhands-sdk/rubric/publish`, the way `#rub` is built twice too.
+ */
+export interface ClaimFormRef {
+    url: string;
+    proof: string;
+}
+/** The ref when both halves are set, else null — an ask never posts a half address. */
+export declare const claimFormRef: (url?: string | null, proof?: string | null) => ClaimFormRef | null;
+/** Tap 1: mint the ask's entity. The title travels on-chain in alsoKnownAs. */
+/** The engine's copy of the terms, already published by `/api/rubric`. */
+export interface EngineRubricRef {
+    url: string;
+    proof: string;
+}
+export declare function createAskEntity(session: QiSession, title: string, doneMeans?: {
+    cid: string;
+    url: string;
+} | null, prompt?: PhonePrompt, rubric?: EngineRubricRef | null, 
+/** The form the rubric binds to — anchored at `#vct` beside it. Absent means none is published. */
+claimForm?: ClaimFormRef | null): Promise<string>;
+/**
+ * The module account the entity module opened for this ask — where escrow sits.
+ *
+ * This sits BETWEEN the two signatures of posting an ask, which makes its
+ * patience a product decision rather than a tuning constant. The entity is
+ * already on chain and already paid for by the time we ask; if this gives up,
+ * the person has signed once for something they cannot finish, and posting
+ * again mints a second orphan entity. Thirty seconds was not enough on a busy
+ * testnet — two minutes is, and the cost of the extra wait is only paid on the
+ * days the index is slow.
+ */
+export declare function askAdminAccount(entityDid: string): Promise<string>;
+export interface AskTerms {
+    /**
+     * Base units of `denom` — the field name is historical. It has meant "base
+     * units of what this ask pays in" since PAY arrived; renaming it would
+     * touch every caller for no gain.
+     */
+    amountUixo: string;
+    quota: number;
+    days: number;
+    /** The address that gets to check this ask. Exclusive — the chain allows one verdict per claim. */
+    checker?: string;
+    /** What the checker is paid, from escrow, whatever verdict it reaches. */
+    checkRewardUixo?: string;
+    /**
+     * What this ask pays in. Absent ⇒ the deployment's `ASK_DENOM`. Both legs
+     * and the escrow transfer take it — the chain permits mixed legs (proved on
+     * testnet collection 43827) but a poster paying workers in one currency and
+     * the checker in another is a riddle nobody asked for.
+     */
+    denom?: AskDenom;
+}
+/**
+ * What a caller writes down BEFORE the escrow broadcast, so a second attempt
+ * can tell "never sent" from "sent, and we lost the answer".
+ *
+ * Posting used to broadcast first and look the collection up afterwards; when
+ * the broadcast timed out or the index was slow, the poster saw an error for
+ * an ask whose money had already moved, and "Post again" escrowed it twice
+ * (scale review D7). Everything here is fixed before signing — the entity is
+ * already minted, its admin account known — so the marker names the ask
+ * exactly. A caller holding one must `resolveAsk(marker.entityDid)` before it
+ * ever posts that ask again.
+ */
+export interface AskMarker {
+    v: 1;
+    entityDid: string;
+    adminAccount: string;
+    /** The account signing the escrow (the person, under delegation too). */
+    poster: string;
+    escrow: {
+        denom: string;
+        amount: string;
+    };
+    preparedAt: string;
+    /** The broadcast's hash when one is known — after signing, or from a timeout that carried it. */
+    txHash: string | null;
+}
+export interface PreparedAsk {
+    marker: AskMarker;
+    messages: EncodeObject[];
+    memo: string;
+}
+/**
+ * Tap 2, built but not signed: the collection, the escrow transfer and the
+ * door grants, plus the marker that names them. Pure — no chain reads — so a
+ * caller can persist the marker and only then sign `messages`.
+ */
+export declare function prepareAsk(poster: string, entityDid: string, adminAccount: string, terms: AskTerms, now?: number): PreparedAsk;
+export interface ResolveAskOptions {
+    /** Reads before answering null. One by default: "is it there now". */
+    attempts?: number;
+    delayMs?: number;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * The collection posted for this entity, or null when the index shows none.
+ *
+ * Newest first, chosen by the chain's own sequence: collection ids are
+ * assigned in order, but the index stores them as strings, so its `ID_DESC`
+ * would put "9" after "10". The start date orders the page; the largest id
+ * decides. One entity normally carries one collection — the posting flow
+ * never makes a second on purpose — and when a double post did make two,
+ * the newest is the live one.
+ *
+ * Throws when the last read failed, so a caller deciding whether to post
+ * again never mistakes "the index did not answer" for "it is not there".
+ */
+export declare function resolveAsk(entityDid: string, options?: ResolveAskOptions): Promise<string | null>;
+/** Where a posting stands. `pending` means money may have moved: resolve before posting again. */
+export type AskPosting = {
+    status: "posted";
+    collectionId: string;
+    marker: AskMarker;
+} | {
+    status: "pending";
+    marker: AskMarker;
+    why: string;
+};
+export interface PostAskOptions {
+    /**
+     * Called with the marker after it is built and before anything is signed.
+     * Persist it here. If this throws, nothing is broadcast.
+     */
+    onPrepared?: (marker: AskMarker) => void | Promise<void>;
+    /**
+     * Called with the marker, now carrying `txHash`, once the escrow is signed
+     * and before its bytes are sent. Persist it again here: an ending after this
+     * point may be a transaction that landed, and the hash is how it is found.
+     * If this throws, nothing is broadcast.
+     */
+    onSigned?: (marker: AskMarker) => void | Promise<void>;
+    /**
+     * How to sign and broadcast; the session's own door by default. An agent
+     * signing under delegation passes its own. A signer that calls
+     * `hooks.onSigned` before sending gets the same pending rule as the default
+     * one; a signer that never calls it is trusted to have sent nothing when it
+     * throws anything but a timeout.
+     */
+    sign?: (messages: EncodeObject[], memo: string, hooks: SignHooks) => Promise<SignResult>;
+    /** How long to wait for the index after the broadcast. Two minutes by default. */
+    resolve?: ResolveAskOptions;
+    now?: number;
+}
+/**
+ * A broadcast whose outcome nobody knows by its name: cosmjs's `TimeoutError` (sent, not
+ * seen in a block in time — it carries the hash), a fetch that hit its
+ * `AbortSignal.timeout` mid-request, or the phone relay losing the thread.
+ * All of them can be a transaction that landed, so none may read as failure.
+ */
+export declare function isBroadcastTimeout(error: unknown): error is Error & {
+    txId?: string;
+};
+/**
+ * Tap 2, idempotently: look before posting, mark before signing, and never
+ * report failure once the money may have moved.
+ *
+ * 1. If the index already shows a collection for this entity, that is the
+ *    ask; nothing is signed again.
+ * 2. The marker goes to `onPrepared` before the broadcast.
+ * 3. A broadcast timeout, or an index that has not listed the collection
+ *    after two minutes, is `pending` with the marker — never a throw that
+ *    reads as "nothing happened". Neither is any other ending after the
+ *    escrow was signed and handed to `onSigned`. Only a broadcast that
+ *    definitely failed (refused, or landed with a non-zero code) or one that
+ *    never left this device throws.
+ */
+export declare function postAsk(session: QiSession, entityDid: string, adminAccount: string, terms: AskTerms, prompt?: PhonePrompt, options?: PostAskOptions): Promise<AskPosting>;
+/**
+ * A posting whose outcome is not known yet. Carries the marker, so a caller
+ * that kept the old `createAskCollection` contract can still resolve it.
+ */
+export declare class AskPending extends Error {
+    readonly marker: AskMarker;
+    constructor(marker: AskMarker, why: string);
+}
+/**
+ * Tap 2, the original contract: the collection id, or a throw. Now built on
+ * `postAsk`, so it no longer re-escrows an ask the index already lists, and a
+ * pending outcome throws `AskPending` carrying the marker — distinguishable
+ * from a failure, which the old generic throw was not. New callers should
+ * use `postAsk` and persist the marker in `onPrepared`.
+ */
+export declare function createAskCollection(session: QiSession, entityDid: string, adminAccount: string, terms: AskTerms, prompt?: PhonePrompt, options?: PostAskOptions): Promise<string>;
+/** The poster submits to their own ask (self-grant rides in the same tx). */
+export declare function submitOwnClaim(session: QiSession, args: {
+    collectionId: string;
+    adminAddress: string;
+    entityDid: string;
+    claimId: string;
+}, prompt?: PhonePrompt): Promise<SignResult>;
+/** The poster checks a submission: approve pays the escrowed amount, reject returns nothing. */
+export declare function evaluateClaim(session: QiSession, args: {
+    collectionId: string;
+    adminAddress: string;
+    entityDid: string;
+    claimId: string;
+    approve: boolean;
+}, prompt?: PhonePrompt): Promise<SignResult>;
+//# sourceMappingURL=ask.d.ts.map

package/dist/cjs/chain/ask.d.ts.map

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