@ixo/openhands-sdk 0.0.0-stage → 0.1.0

package/dist/esm/campaign/funding.js

@@ -0,0 +1,160 @@
+import { askDenom } from "../chain/money.js";
+import { givenConfig } from "../given.js";
+import { hasEnv, strictBase } from "../envRead.js";
+import { backersFor, pledgedFor } from "./pledges.js";
+import { spotTarget } from "./bands.js";
+import { checkerLegBase } from "../rubric/leg.js";
+import { cleanupTerms } from "./cleanup.js";
+/**
+ * What the checker is paid per verdict, in base units.
+ *
+ * It lives here rather than in the worker's config because the bill is now
+ * computed in three places — the pass that posts, the page that draws the
+ * bar, and the youth app that says how much more is needed — and a leg that
+ * differed between them would be a target nobody could agree on. The worker's
+ * config re-exports this one, so there is still exactly one number.
+ */
+/*
+ * Read strictly. A mis-set variable (`"100k"`, `"-1"`, `"1e3.5"`) used to
+ * become NaN here, and NaN is the one number every comparison in `planFor`
+ * answers "no" to: the target reads as met, nothing is drawn short, and the
+ * posting goes to the chain carrying "NaN" as an amount. The default stands
+ * in for anything that is not a whole, non-negative number of base units.
+ */
+export const DEFAULT_CHECK_REWARD_BASE = 100_000;
+/** `configure({ checkRewardBase })`, else `QI_CHECK_REWARD_BASE` read strictly, else 100000. */
+export const checkRewardBase = () => givenConfig().checkRewardBase ?? strictBase(hasEnv() ? process.env.QI_CHECK_REWARD_BASE : undefined, DEFAULT_CHECK_REWARD_BASE);
+/**
+ * What the whole bill is: the work, plus whoever checks it.
+ *
+ * `checkBase` is the checker's flat reward (`QI_CHECK_REWARD_BASE`, read
+ * strictly in `config.ts`, or `configure({ checkRewardBase })`) unless the
+ * caller names one.
+ *
+ * The judge's address is a placeholder here on purpose. `checkerLegBase`
+ * prices the leg from the terms' *shape* — how many criteria, of which kinds
+ * — and never from who signs them, so the bill is the same number before
+ * anybody has been named. The posting path fills in the real checker.
+ */
+export function billFor(spot, denom = askDenom(), checkBase = checkRewardBase()) {
+    const workBase = spotTarget(spot.assessment);
+    const terms = cleanupTerms({ lat: spot.lat, lon: spot.lon, judge: { address: "ixo1", rewardUixo: checkBase } });
+    const legBase = checkerLegBase(denom, terms, checkBase);
+    return { workBase, legBase, targetBase: workBase + legBase };
+}
+/**
+ * Why a pledge could not be drawn, in words a backer would recognise.
+ *
+ * The cap is the smaller of two chain facts now, so a zero no longer has one
+ * meaning: the allowance may have been revoked, or the money may simply have
+ * gone somewhere else. Both are ordinary, neither is a fault, and the round's
+ * log is the only place either gets told.
+ *
+ * **Revoked stays the default sentence**, because it is what a zero has always
+ * meant here and what every other surface quotes. The balance sentences are
+ * an *upgrade*, spoken only when the caller hands over a second read that
+ * proves the allowance is intact and the money is not — so a test, a page, or
+ * a harness that offers no diagnosis gets the plain answer and no surprise
+ * network call.
+ */
+const REVOKED = "the allowance was revoked";
+async function whyDropped(backer, agent, cap, diagnose) {
+    if (cap > 0)
+        return "the allowance is already spoken for";
+    if (!diagnose)
+        return REVOKED;
+    try {
+        const { allowance, balance } = await diagnose(backer, agent);
+        if (allowance === 0)
+            return REVOKED;
+        if (balance === 0)
+            return "the money has moved. The allowance stands, the balance does not";
+        return `the balance no longer covers it. Allowed ${allowance}, held ${balance}`;
+    }
+    catch {
+        /* The diagnosis is a courtesy. Failing to make one must never change the
+           outcome the pass already decided, nor invent a story about a backer. */
+        return REVOKED;
+    }
+}
+export async function planFor(ledger, spot, agent, read, 
+/**
+ * Override the band price. For proofs, where a testnet float cannot cover
+ * a real spot — and for chain children, whose whole price is the fixed
+ * target their parent's terms wrote, no assessment anywhere.
+ */
+overrideTargetBase, diagnose) {
+    if (overrideTargetBase === undefined && !spot.assessment)
+        throw new Error("a spot with no assessment needs a fixed target");
+    const targetBase = overrideTargetBase ?? billFor(spot).targetBase;
+    const draws = [];
+    const dropped = [];
+    let raised = 0;
+    /* One read per backer, not per pledge: their single allowance covers every
+       spot they have backed, so the same number bounds all of them. */
+    const caps = new Map();
+    const capOf = async (backer) => {
+        if (!caps.has(backer))
+            caps.set(backer, await read(backer, agent));
+        return caps.get(backer);
+    };
+    for (const pledge of backersFor(ledger, spot.claimId)) {
+        if (raised >= targetBase)
+            break;
+        const cap = await capOf(pledge.backer);
+        /* Never draw more than the spot needs, never more than the chain covers —
+           the rest of their allowance stays theirs, for another spot or for
+           nothing at all. */
+        const take = Math.min(pledge.amountBase, targetBase - raised, cap);
+        if (take <= 0) {
+            dropped.push({ address: pledge.backer, amountBase: pledge.amountBase, why: await whyDropped(pledge.backer, agent, cap, diagnose) });
+            continue;
+        }
+        draws.push({ address: pledge.backer, amountBase: String(take) });
+        caps.set(pledge.backer, cap - take);
+        raised += take;
+    }
+    return { spot, targetBase, draws, gapBase: Math.max(0, targetBase - raised), dropped };
+}
+/**
+ * Is this spot ready to post, under the campaign's rule?
+ *
+ * Two ways to be ready. Fully funded is the ordinary one. The other is
+ * **down-banding**: posting for less than the whole bill, because a spot that
+ * has stood a long time with most of its money is better cleaned partly than
+ * left standing — and the cleanup terms are sized to what actually arrives.
+ *
+ * A one-day campaign down-bands at its deadline. An ongoing one has no
+ * deadline to reach, so it uses a clock: how long this pin has stood, and how
+ * much of its bill is covered. Both numbers come from the rule, never from
+ * here — the estate's own line is that a campaign's judgement belongs in a
+ * document somebody published, not in a constant somebody compiled.
+ */
+export function fundable(plan, rule, opts) {
+    if (plan.spot.assessment.volume === "bigger")
+        return { ok: false, why: "bigger than a truck. This goes to professionals, however much money arrives" };
+    if (rule.witnesses.requiredFromBand === "truck" && plan.spot.assessment.volume === "truck" && !opts.confirmed) {
+        return { ok: false, why: "a truck-sized pin needs a second person to have confirmed it before anybody's money escrows against it" };
+    }
+    if (plan.gapBase === 0)
+        return { ok: true };
+    if (!rule.funding.downBand || plan.draws.length === 0)
+        return { ok: false, why: `short by ${plan.gapBase}. Still open` };
+    if (opts.deadlinePassed)
+        return { ok: true };
+    /* The ongoing campaign's own patience, from its own rule. */
+    const clock = rule.clock;
+    if (clock && opts.ageDays !== undefined && opts.ageDays >= clock.downBandAfterDays) {
+        const covered = plan.targetBase > 0 ? (plan.targetBase - plan.gapBase) / plan.targetBase : 0;
+        if (covered >= clock.downBandAtFraction)
+            return { ok: true };
+        return { ok: false, why: `short by ${plan.gapBase}. ${Math.round(covered * 100)}% after ${Math.floor(opts.ageDays)} days, and the rule waits for ${Math.round(clock.downBandAtFraction * 100)}%` };
+    }
+    return { ok: false, why: `short by ${plan.gapBase}. Still open` };
+}
+/** For the log line, and for the map's gap sentence. */
+export const gapSentence = (plan) => plan.dropped.length === 0
+    ? `short by ${plan.gapBase}`
+    : `short by ${plan.gapBase}. ${plan.dropped.map((one) => `${one.address.slice(0, 12)}… dropped, ${one.why}`).join("; ")}`;
+export const pledgedAgainst = pledgedFor;
+//# sourceMappingURL=funding.js.map

package/dist/esm/campaign/funding.js.map

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

package/dist/esm/campaign/landing.d.ts

@@ -0,0 +1,20 @@
+export declare const isSessionId: (value: string | null | undefined) => boolean;
+export interface Backing {
+    memo: string;
+    at: string;
+    amountBase: number;
+}
+export interface Landed {
+    amountBase: number;
+    at: string;
+}
+/**
+ * The backing this checkout session paid for, or null.
+ *
+ * Matched on the session id inside the memo, never on amount or time: two
+ * neighbours backing the same spot for the same tier within a minute is an
+ * ordinary Saturday, and a looser match would congratulate one of them for
+ * the other's money while their own payment was still in the air.
+ */
+export declare function landedFor(backings: readonly Backing[], session: string | null | undefined): Landed | null;
+//# sourceMappingURL=landing.d.ts.map

package/dist/esm/campaign/landing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"landing.d.ts","sourceRoot":"","sources":["../../../src/campaign/landing.ts"],"names":[],"mappings":"AA+BA,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,OAA6C,CAAC;AAE7G,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,MAAM;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAQzG"}

package/dist/esm/campaign/landing.js

@@ -0,0 +1,49 @@
+import { parseBackedMemo } from "./pledges.js";
+/**
+ * Finding one payment among a pool's backings — the question a funder's own
+ * screen asks while they watch for their money.
+ *
+ * **Not "did the pot go up".** That was the old question, and it could not
+ * be answered honestly. Coming back from Stripe is a fresh page load, so the
+ * pot the screen had read before leaving was gone; the first poll four
+ * seconds later counted as a rise and the screen congratulated the funder —
+ * whatever had happened. On 2026-09-17 four card payments were charged, the
+ * webhook was refused by the wrong deployment, no PAY ever moved, and all
+ * four funders saw confetti.
+ *
+ * It was also the wrong number. A pot that other backers feed moves for
+ * reasons that are not this payment, and one that a cleaner has just been
+ * paid from moves the other way — so a rise, or its absence, says nothing
+ * about the payment this funder is waiting on.
+ *
+ * The chain can answer the real question. A backing is one send carrying
+ * `backed:<session>:<campaign>:<claim>`, and that session id is the same
+ * one Stripe hands back in the return URL. So the screen asks for its own
+ * payment by name.
+ *
+ * Lives here, beside `parseBackedMemo`, because the memo's grammar has one
+ * home and every reader of it belongs in the same room.
+ */
+/** A Stripe Checkout Session id, as it appears in a return URL and in a memo. */
+const SESSION = /^cs_(?:test|live)_[A-Za-z0-9]{10,}$/;
+export const isSessionId = (value) => SESSION.test((value ?? "").trim());
+/**
+ * The backing this checkout session paid for, or null.
+ *
+ * Matched on the session id inside the memo, never on amount or time: two
+ * neighbours backing the same spot for the same tier within a minute is an
+ * ordinary Saturday, and a looser match would congratulate one of them for
+ * the other's money while their own payment was still in the air.
+ */
+export function landedFor(backings, session) {
+    if (!isSessionId(session))
+        return null;
+    const want = (session ?? "").trim();
+    for (const backing of backings) {
+        const read = parseBackedMemo(backing.memo);
+        if (read?.sessionId === want)
+            return { amountBase: backing.amountBase, at: backing.at };
+    }
+    return null;
+}
+//# sourceMappingURL=landing.js.map

package/dist/esm/campaign/landing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"landing.js","sourceRoot":"","sources":["../../../src/campaign/landing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,iFAAiF;AACjF,MAAM,OAAO,GAAG,qCAAqC,CAAC;AAEtD,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAgC,EAAW,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAa7G;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,QAA4B,EAAE,OAAkC;IACxF,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,MAAM,IAAI,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACpC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,IAAI,EAAE,SAAS,KAAK,IAAI;YAAE,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC;IAC1F,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/esm/campaign/pledges.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Who has promised what against which spot.
+ *
+ * **A pledge is not money moved.** It is a capped, expiring, revocable
+ * allowance on the backer's own account, and the campaign draws against it
+ * only at the moment a cleanup ask is posted. So this file records
+ * *allocations* — which spot a backer meant their allowance for — while the
+ * chain remains the authority on how much they can actually cover.
+ *
+ * The split is forced rather than chosen. Cosmos authz keeps **one**
+ * `SendAuthorization` per (granter, grantee, message type): a second grant
+ * overwrites the first, and its `allowList` cannot name an escrow account
+ * that does not exist until posting. So a backer's grant is their *campaign
+ * total*, chain-verified and enumerable, and the per-spot split is ours to
+ * keep — bounded at every turn by what the chain says they still have.
+ *
+ * The recovery path if this ledger is ever lost: every pledge's own
+ * `MsgGrant` carries `<campaign>:pledge:<claimId>` in its memo, so the
+ * allocations can be rebuilt from the chain's own history.
+ */
+export interface Pledge {
+    /** The backer's address — the granter of the allowance. */
+    backer: string;
+    /** The pin this was meant for: the mapping claim's id. */
+    claimId: string;
+    amountBase: number;
+    at: string;
+    /**
+     * What the backer asked to be called, and whether they backed as an
+     * organisation. The chain has no field for either — a grant carries an
+     * address and a memo — so this is the journal's own half, and it is a
+     * courtesy: a pin says "backed by a neighbour 💚" perfectly well without it.
+     * An organisation putting money into a public campaign generally wants the
+     * credit, and that credit is the whole product for them.
+     */
+    who?: string;
+    org?: boolean;
+    /** Set when the funding pass finds the chain no longer covers it. */
+    lapsedAt?: string;
+    /** Set when a posting actually drew this money. */
+    drawnAt?: string;
+}
+export interface PledgeLedger {
+    v: 1;
+    pledges: Pledge[];
+    /** Sponsor draws that actually posted — written by the funding pass, read
+     *  by the wall for its "crowd $X + matched $Y by NAME" line. Optional so
+     *  every ledger written before matching existed still reads. */
+    matches?: {
+        claimId: string;
+        sponsor: string;
+        amountBase: number;
+        askId: string;
+        at: string;
+    }[];
+    /** Chain children that actually posted — the journal half of the
+     *  double-spawn belt. The other half is tag discovery, which survives
+     *  this file not existing at all (Vercel has no disk). */
+    spawned?: {
+        parent: string;
+        claimId: string;
+        askId: string;
+        at: string;
+    }[];
+}
+export declare const emptyLedger: () => PledgeLedger;
+/**
+ * The grant's own receipt, now complete. Three parts said *which spot*; the
+ * chain probe that made this format load-bearing found the fourth was owed:
+ * the authorization inside a MsgGrant is stored as raw proto bytes on the
+ * index, so a rebuilt ledger cannot read amounts out of grant history — and
+ * a backer's grant is a cumulative TOTAL besides. The memo carries the one
+ * number the chain cannot cheaply answer. A memo that lies about it is
+ * self-defeating: every draw is bounded by the live allowance at round time.
+ */
+export declare const memo: (campaign: string, claimId: string, amountBase: number) => string;
+/** A pledge memo, read back — or null for anything else a memo might say. */
+export declare function parsePledgeMemo(text: string | null | undefined): {
+    campaign: string;
+    claimId: string;
+    amountBase: number;
+} | null;
+/**
+ * A card purchase's receipt, written on the chain that delivered it.
+ *
+ * The webhook's own memory is one serverless instance's `Set`, and Stripe
+ * retries land wherever the platform puts them — so a cold instance would
+ * happily pay a second time for one payment. The chain already remembers
+ * every send the treasury ever made; naming the Stripe session in the memo
+ * turns that history into the idempotency key, durable and free.
+ *
+ * When the purchase was for a spot, the campaign and pin ride along: a
+ * buyer whose tab died between paying and pledging can have the pledge
+ * finished from chain history alone, by them or by an operator.
+ */
+export declare const boughtMemo: (sessionId: string, spot?: {
+    campaign: string;
+    claimId: string;
+}) => string;
+/**
+ * A backing: money sent to a pin's own pool, and who sent it.
+ *
+ * `bought:` above says PAY was delivered to somebody's key. This says it was
+ * paid into a cleanup's pot, where nobody can take it back — a different
+ * fact, so a different word, and the `by:` tail is what lets a signed-in
+ * backer's credential cite the transaction that proves it. Anonymous
+ * backing is the same memo without the tail, which is why the tail is
+ * optional rather than a second shape.
+ */
+export declare const backedMemo: (sessionId: string, spot: {
+    campaign: string;
+    claimId: string;
+}, backer?: string | null) => string;
+/**
+ * The same fact when the money came from a wallet instead of a card.
+ *
+ * A sponsor with PAY in their account sends it into the pool themselves.
+ * There is no Stripe session to name, so the first field carries a nonce
+ * instead — which exists only so two allocations to the same pin from the
+ * same account are distinguishable transactions. It is not a secret and
+ * nothing looks it up.
+ *
+ * **One grammar, not two.** A second memo shape would be a second thing to
+ * keep in step, and this file has watched that go wrong: the `by:` tail is
+ * optional precisely so the card path and this one cannot drift apart. A
+ * wallet backing always names its backer — an organisation's allocation is
+ * never anonymous — but the *grammar* leaves the tail optional, because the
+ * card path still needs it that way.
+ */
+export declare const walletBackedMemo: (nonce: string, spot: {
+    campaign: string;
+    claimId: string;
+}, backer: string) => string;
+/** Sixteen random bytes as hex — the nonce `walletBackedMemo` wants. */
+export declare function backingNonce(): string;
+export declare function parseBackedMemo(text: string | null | undefined): {
+    sessionId: string;
+    campaign: string;
+    claimId: string;
+    backer?: string;
+} | null;
+/**
+ * Money going back out of a pool to the account that put it in.
+ *
+ * Written by the pool pass when a pin's ask has lapsed untried, or the pin
+ * was reported gone, and the rule says the pool is returned. Read by the
+ * sponsor's own dashboard, which asks what came *back* to it — so the memo
+ * names the campaign, the pin and the account, and the reader checks all
+ * three: anybody can send a coin to a sponsor with the word `refund` on it,
+ * and the dashboard must not count that as the campaign returning money.
+ *
+ * Built and parsed here, beside the backing memo it answers, for the reason
+ * that whole file gives: one grammar in one place cannot drift.
+ */
+export declare const refundMemo: (campaign: string, claimId: string, backer: string) => string;
+export declare function parseRefundMemo(text: string | null | undefined): {
+    campaign: string;
+    claimId: string;
+    backer: string;
+} | null;
+/**
+ * A card payment contested through the payer's bank, and the money coming
+ * back out of the pot it went into.
+ *
+ * When a dispute lands, whatever that backing still has in the pot is
+ * drawn back to the campaign before it can pay anybody — so we never pay a
+ * cleaner and lose the charge as well. The memo names the Stripe session,
+ * which is the same thing the `backed:` memo named on the way in, so the
+ * two halves of one payment's life can be read off the chain by anybody.
+ *
+ * `restored:` is the other direction: a dispute we won, whose money goes
+ * back into the pot it was taken from. Both are written by the campaign
+ * key in the pool pass — never by the web app, which does not hold it.
+ */
+export declare const disputeMemo: (sessionId: string, campaign: string, claimId: string) => string;
+export declare const restoredMemo: (sessionId: string, campaign: string, claimId: string) => string;
+export declare function parseDisputeMemo(text: string | null | undefined): {
+    kind: "dispute" | "restored";
+    sessionId: string;
+    campaign: string;
+    claimId: string;
+} | null;
+export declare function parseBoughtMemo(text: string | null | undefined): {
+    sessionId: string;
+    campaign?: string;
+    claimId?: string;
+} | null;
+/**
+ * Taking a backing back.
+ *
+ * The chain keeps ONE `SendAuthorization` per (granter, grantee, message
+ * type), so there is no such thing as revoking one pledge: a backer who has
+ * put money behind three spots holds a single grant covering all of them.
+ * Undoing one of them means signing a *new* grant for the smaller total —
+ * and then saying, in the memo, which allocation the difference came out of.
+ *
+ * Without that sentence the round would see only a shrunken cap and would
+ * have to guess which spot lost its money, which is exactly the guess that
+ * turns "I took back the one I changed my mind about" into "the pass dropped
+ * my oldest pledge instead".
+ *
+ * The same self-defeating arithmetic as a pledge protects it: an unpledge
+ * that lies about its amount only ever reduces what the liar themselves can
+ * cover, and the live allowance still bounds every draw.
+ */
+export declare const unpledgeMemo: (campaign: string, claimId: string, amountBase: number) => string;
+export declare function parseUnpledgeMemo(text: string | null | undefined): {
+    campaign: string;
+    claimId: string;
+    amountBase: number;
+} | null;
+/**
+ * The other sentence the grammar speaks: a poster's standing fund for their
+ * own chain. No claimId and no amount, deliberately — the children this
+ * grant will fund do not exist yet, and the chain's live allowance is the
+ * only number that matters at spawn time. The tag is the parent's collection
+ * id, all digits: the namespace K1 reserved is what lets one regex know
+ * this is a chain's fund and not a campaign pledge.
+ */
+export declare const chainFundMemo: (tag: string) => string;
+export declare function parseChainFundMemo(text: string | null | undefined): {
+    tag: string;
+} | null;
+/** What one backer has allocated and not yet had drawn or lapsed. */
+export declare function standingFor(ledger: PledgeLedger, backer: string): number;
+/** What a spot has pledged against it, live. Never called "raised". */
+export declare function pledgedFor(ledger: PledgeLedger, claimId: string): number;
+/** The backers of one spot, oldest first — the order a draw follows. */
+export declare const backersFor: (ledger: PledgeLedger, claimId: string) => Pledge[];
+/**
+ * May this backer allocate this much more?
+ *
+ * `capBase` comes from the chain and is the only authority. Everything else
+ * they have standing counts against it, because one grant covers them all.
+ */
+export declare function withinCap(ledger: PledgeLedger, backer: string, capBase: number, addBase: number): boolean;
+//# sourceMappingURL=pledges.d.ts.map

package/dist/esm/campaign/pledges.d.ts.map

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