remesso-sdk 0.0.0-stage → 0.2.0

package/dist/client.js

@@ -0,0 +1,60 @@
+/// `createRemesso`: one client for paying, being paid, and knowing you were.
+import { createPublicClient, createWalletClient, http } from "viem";
+import { celo } from "viem/chains";
+import { makeAgents } from "./agents.js";
+import { attributionFor } from "./attribution.js";
+import { makeCtx } from "./context.js";
+import { deployment } from "./deployment.js";
+import { makeEvents } from "./events.js";
+import { payLink } from "./links.js";
+import { makePay } from "./payments.js";
+import { makePolicies } from "./policies.js";
+import { makeRequests } from "./requests.js";
+import { makeSchedules } from "./schedules.js";
+import { memoryStore } from "./store.js";
+import { makeWebhooks } from "./webhooks.js";
+export function createRemesso(opts = {}) {
+    const rpc = opts.rpcUrl ?? deployment.chain.rpc;
+    const pub = opts.publicClient ?? createPublicClient({ chain: celo, transport: http(rpc) });
+    const account = opts.walletClient?.account ?? opts.account ?? null;
+    const wallet = opts.walletClient ?? (account ? createWalletClient({ account, chain: celo, transport: http(rpc) }) : null);
+    const base = (opts.functionsUrl ?? deployment.functions.base).replace(/\/+$/, "");
+    const appOrigin = opts.appOrigin ?? deployment.app.origin;
+    const ctx = makeCtx({
+        pub,
+        wallet,
+        account,
+        endpoints: {
+            requestPayment: opts.functionsUrl ? `${base}/request-payment` : deployment.functions["request-payment"],
+            paymentEvents: opts.functionsUrl ? `${base}/payment-events` : deployment.functions["payment-events"],
+            webhooks: opts.functionsUrl ? `${base}/webhooks` : deployment.functions.webhooks,
+        },
+        appOrigin,
+        fetch: opts.fetch ?? globalThis.fetch.bind(globalThis),
+        dataSuffix: attributionFor(opts.builderCodes, opts.attribution !== false),
+        store: opts.store ?? memoryStore(),
+        fetchText: opts.fetchText,
+    });
+    const policies = makePolicies(ctx);
+    const pay = makePay(ctx, policies);
+    const requests = makeRequests(ctx, { pay, policies });
+    const schedules = makeSchedules(ctx, { getRequest: requests.get, answer: requests.answer });
+    return {
+        address: account?.address ?? null,
+        publicClient: pub,
+        deployment,
+        schedules,
+        pay,
+        policies,
+        requests,
+        events: makeEvents(ctx),
+        webhooks: makeWebhooks(ctx),
+        agents: makeAgents(ctx),
+        payLink(p) {
+            const to = p.to ?? account?.address;
+            if (!to)
+                throw new Error("payLink needs to without an account");
+            return payLink({ ...p, to }, appOrigin);
+        },
+    };
+}

package/dist/context.d.ts

@@ -0,0 +1,42 @@
+import { type Abi, type Account, type Address, type Hex, type PublicClient, type TransactionReceipt, type WalletClient } from "viem";
+import { type Token } from "./deployment.js";
+import type { PaymentStore } from "./store.js";
+export type Ctx = {
+    pub: PublicClient;
+    wallet: WalletClient | null;
+    account: Account | null;
+    endpoints: {
+        requestPayment: string;
+        paymentEvents: string;
+        webhooks: string;
+    };
+    appOrigin: string;
+    fetch: typeof fetch;
+    dataSuffix: Hex | undefined;
+    store: PaymentStore;
+    fetchText?: (url: string) => Promise<string>;
+    assertChain(): Promise<void>;
+    requireAccount(): Account;
+    post<T>(url: string, body: unknown): Promise<T>;
+    get<T>(url: string): Promise<T>;
+    serial<T>(fn: () => Promise<T>): Promise<T>;
+};
+export declare function makeCtx(parts: Omit<Ctx, "assertChain" | "requireAccount" | "post" | "get" | "serial">): Ctx;
+export declare function untilVisible<T>(read: () => Promise<T>, ready: (v: T) => boolean, waitMs?: number): Promise<T>;
+export declare function gasFor(ctx: Ctx, t: Token | null, gas?: bigint): Promise<{
+    feeCurrency?: Address;
+}>;
+type WriteArgs = {
+    address: Address;
+    abi: Abi;
+    functionName: string;
+    args: readonly unknown[];
+    gasToken: Token | null;
+    nonce?: number;
+};
+export declare function write(ctx: Ctx, w: WriteArgs): Promise<{
+    hash: Hex;
+    receipt: TransactionReceipt;
+}>;
+export declare function refusal(e: unknown): string;
+export {};

package/dist/context.js

@@ -0,0 +1,157 @@
+/// What every part of the client shares: the chain, the account, the
+/// endpoints, and the few rules every write follows.
+import { formatEther, } from "viem";
+import { celo } from "viem/chains";
+import { erc20Abi } from "./abi.js";
+import { CHAIN_ID } from "./deployment.js";
+import { RemessoError } from "./errors.js";
+export function makeCtx(parts) {
+    let chainCheck = null;
+    let queue = Promise.resolve();
+    const request = async (url, init) => {
+        let res;
+        try {
+            res = await parts.fetch(url, { ...init, signal: AbortSignal.timeout(20_000) });
+        }
+        catch (e) {
+            throw new RemessoError("http", `couldn't reach ${url}: ${e.message}`);
+        }
+        const text = await res.text();
+        let body = null;
+        try {
+            body = text ? JSON.parse(text) : null;
+        }
+        catch { /* not JSON */ }
+        if (!res.ok) {
+            const said = body;
+            const message = said?.error ? `${said.error}${said.detail ? `: ${said.detail}` : ""}` : `${res.status} ${text.slice(0, 200)}`;
+            const code = res.status === 400 ? "invalid" : res.status === 404 ? "not_found" : res.status === 409 ? "conflict"
+                : [401, 403, 429].includes(res.status) ? "refused" : "http";
+            throw new RemessoError(code, message, { status: res.status, body });
+        }
+        return body;
+    };
+    return {
+        ...parts,
+        assertChain() {
+            chainCheck ??= parts.pub.getChainId().then((id) => {
+                if (id !== CHAIN_ID) {
+                    throw new RemessoError("wrong_chain", `the RPC answers chain ${id}, not Celo mainnet (${CHAIN_ID}), so nothing is signed`);
+                }
+            }).catch((e) => {
+                chainCheck = null; // ask again next time: the RPC may have been down
+                throw e;
+            });
+            return chainCheck;
+        },
+        requireAccount() {
+            if (!parts.account)
+                throw new RemessoError("no_account", "this needs an account: createRemesso({ account })");
+            return parts.account;
+        },
+        post: (url, body) => request(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) }),
+        get: (url) => request(url, { method: "GET" }),
+        serial(fn) {
+            const run = queue.then(fn, fn);
+            queue = run.catch(() => { });
+            return run;
+        },
+    };
+}
+/// Reads until `ready` holds, for a few seconds at most. Right after a
+/// transaction lands, a node behind forno's load balancer can still answer
+/// from an earlier block, so a schedule or policy this client created a
+/// moment ago can read as empty. The mainnet run hit exactly that.
+export async function untilVisible(read, ready, waitMs = 6_000) {
+    const until = Date.now() + waitMs;
+    for (;;) {
+        const v = await read();
+        if (ready(v) || Date.now() >= until)
+            return v;
+        await new Promise((r) => setTimeout(r, 1_000));
+    }
+}
+/// Gas: CELO if the account holds enough, else the token itself through
+/// Celo's fee abstraction, for the tokens that support it. A payer who holds
+/// only USD₮ can still create a schedule.
+export async function gasFor(ctx, t, gas = 300000n) {
+    const account = ctx.requireAccount();
+    const [native, price] = await Promise.all([ctx.pub.getBalance({ address: account.address }), ctx.pub.getGasPrice()]);
+    const need = gas * price * 2n;
+    if (native >= need)
+        return {};
+    if (t?.feeCurrency) {
+        const held = await ctx.pub.readContract({ address: t.address, abi: erc20Abi, functionName: "balanceOf", args: [account.address] });
+        if (held > 0n)
+            return { feeCurrency: t.feeCurrency };
+    }
+    throw new RemessoError("no_gas", `${account.address} has ${formatEther(native)} CELO, and this costs about ${formatEther(gas * price)}. ` +
+        `Send it a little CELO${t?.feeCurrency ? `, or hold some ${t.symbol}, which can pay for gas` : ""}.`);
+}
+/// Simulate, send, and wait for the receipt. A mined transaction isn't a
+/// successful one: viem returns a reverted receipt without throwing, so this
+/// checks it.
+export async function write(ctx, w) {
+    await ctx.assertChain();
+    const account = ctx.requireAccount();
+    if (!ctx.wallet)
+        throw new RemessoError("no_account", "this needs an account that can send transactions");
+    const fee = await gasFor(ctx, w.gasToken);
+    try {
+        await ctx.pub.simulateContract({ address: w.address, abi: w.abi, functionName: w.functionName, args: w.args, account, ...fee });
+    }
+    catch (e) {
+        throw new RemessoError("refused", `the contract would refuse ${w.functionName}: ${refusal(e)}`, { cause: String(e) });
+    }
+    const hash = await ctx.wallet.writeContract({
+        address: w.address,
+        abi: w.abi,
+        functionName: w.functionName,
+        args: w.args,
+        account,
+        chain: celo,
+        dataSuffix: ctx.dataSuffix,
+        ...(w.nonce != null ? { nonce: w.nonce } : {}),
+        ...fee,
+    });
+    const receipt = await ctx.pub.waitForTransactionReceipt({ hash, timeout: 120_000 });
+    if (receipt.status !== "success") {
+        throw new RemessoError("reverted", `${w.functionName} reverted on-chain, so nothing changed: https://celoscan.io/tx/${hash}`, { hash });
+    }
+    return { hash, receipt };
+}
+/// Why the contract refused, in words a person can act on. Errors neither
+/// contract names fall through to viem's short message.
+export function refusal(e) {
+    const err = e;
+    const name = err?.cause?.data?.errorName ?? err?.data?.errorName ??
+        err?.cause?.cause?.data?.errorName;
+    const known = {
+        // RemessoAgentAllowance
+        NotAgent: "the policy names a different agent",
+        NotOwner: "only the policy's owner can do that",
+        Revoked: "the policy was revoked",
+        Expired: "the policy has expired",
+        OverPerPayment: "the amount is over the policy's per-payment cap",
+        OverPerDay: "today's cap is used up; it resets 24 hours after the day's first payment",
+        RecipientNotAllowed: "the recipient isn't on the policy's allowlist",
+        SelfPayment: "a policy can't pay its own owner",
+        SafeERC20FailedOperation: "the token refused the transfer: the balance or the approval is too low",
+        BadExpiry: "the expiry is in the past or too far ahead",
+        BadLimits: "the per-payment cap must be above zero and at most the daily cap",
+        TooManyRecipients: "too many recipients for one policy",
+        // RemessoExecutorV5
+        TokenNotAllowed: "the contract doesn't accept this token for new schedules",
+        InvalidAmount: "the amount is zero or too large",
+        InvalidInterval: "the interval is out of range",
+        InvalidDestination: "the recipient address isn't allowed",
+        ScheduleLifetimeTooLong: "the schedule would last longer than a year",
+        FirstRunAfterExpiry: "the first payment would fall after the schedule expires",
+        NotScheduleOwner: "only the schedule's sender can do that",
+        ScheduleIsCancelled: "the schedule is cancelled",
+        InvalidTrigger: "that address can't be a trigger (grant Remesso with the CURRENT_EXECUTOR sentinel)",
+        ZeroAddress: "an address is zero",
+        ZeroAmount: "the amount is zero",
+    };
+    return (name && known[name]) ?? name ?? String(err?.shortMessage ?? err?.message ?? e);
+}

package/dist/deployment.d.ts

@@ -0,0 +1,19 @@
+import { type Address } from "viem";
+import { deployment } from "./generated/deployment.js";
+export { deployment };
+export type Token = (typeof deployment.tokens)[number];
+export declare const CHAIN_ID: 42220;
+export declare const EXECUTOR: Address;
+export declare const ALLOWANCE: Address;
+export declare const REGISTRY: Address;
+export declare const CURRENT_EXECUTOR: Address;
+export declare const FEE_BPS: number;
+export declare function findToken(symbolOrAddress: string): Token | undefined;
+export declare function token(symbolOrAddress: string): Token;
+export declare function toUnits(amount: string, t: Token): bigint;
+export declare function formatAmount(units: bigint | string, tokenOrAddress: Token | string): string;
+export declare function runLimits(t: Token): {
+    min: bigint;
+    max: bigint;
+};
+export declare const checksum: (a: string) => Address;

package/dist/deployment.js

@@ -0,0 +1,80 @@
+/// The deployment, and tokens by symbol or address.
+///
+/// Everything here is generated from `deployments/celo-mainnet.json`, which is
+/// generated from what is live. Tokens are matched by address: several Celo
+/// tokens have fee-currency adapters that report the same symbol with other
+/// decimals, and a symbol can be spelled more than one way (USA₮, USD₮).
+import { formatUnits, getAddress, parseUnits } from "viem";
+import { deployment } from "./generated/deployment.js";
+import { RemessoError } from "./errors.js";
+export { deployment };
+export const CHAIN_ID = deployment.chain.chainId;
+export const EXECUTOR = deployment.contracts.RemessoExecutorV5.address;
+export const ALLOWANCE = deployment.contracts.RemessoAgentAllowance.address;
+export const REGISTRY = deployment.contracts.ERC8004IdentityRegistry.address;
+/// Stored as a schedule's trigger, address(1) means "whoever is Remesso's
+/// executor now", so a key rotation moves the grant.
+export const CURRENT_EXECUTOR = deployment.contracts.RemessoExecutorV5.currentExecutorSentinel;
+/// The commission a schedule created now pins, in basis points. Taken from the
+/// payment, rounded up. Policy payments take none.
+export const FEE_BPS = deployment.contracts.RemessoExecutorV5.feeBps;
+/// Other spellings people and agents use.
+const ALIASES = {
+    USAT: "USA₮",
+    "USD₮": "USDT",
+    USDT0: "USDT",
+    CUSD: "USDm",
+};
+/// A token by symbol (any case; USAT for USA₮, cUSD for USDm) or address, or
+/// undefined.
+export function findToken(symbolOrAddress) {
+    const s = String(symbolOrAddress).trim();
+    if (/^0x[0-9a-fA-F]{40}$/.test(s)) {
+        return deployment.tokens.find((t) => t.address.toLowerCase() === s.toLowerCase());
+    }
+    const upper = s.toUpperCase();
+    const name = ALIASES[upper] ?? s;
+    return deployment.tokens.find((t) => t.symbol.toUpperCase() === name.toUpperCase());
+}
+/// A token by symbol or address. Throws for one Remesso doesn't know.
+export function token(symbolOrAddress) {
+    const t = findToken(symbolOrAddress);
+    if (!t) {
+        throw new RemessoError("invalid", `unknown token ${symbolOrAddress}: Remesso takes ${deployment.tokens.map((x) => x.symbol).join(", ")}`);
+    }
+    return t;
+}
+/// A decimal amount in a token's own units, e.g. "2.50" USDT → 2_500_000n.
+/// Strings only: a float in between is how precision is lost.
+export function toUnits(amount, t) {
+    const s = String(amount).trim();
+    if (!/^\d{1,30}(\.\d+)?$/.test(s))
+        throw new RemessoError("invalid", `amount must be a decimal string, like "2.50" (got ${amount})`);
+    const decimals = s.split(".")[1]?.length ?? 0;
+    if (decimals > t.decimals)
+        throw new RemessoError("invalid", `${t.symbol} has ${t.decimals} decimals; ${amount} has ${decimals}`);
+    return parseUnits(s, t.decimals);
+}
+/// Base units as a decimal string with the symbol, e.g. "0.9975 USA₮".
+export function formatAmount(units, tokenOrAddress) {
+    const t = typeof tokenOrAddress === "string" ? findToken(tokenOrAddress) : tokenOrAddress;
+    if (!t)
+        return `${units} units of ${tokenOrAddress}`;
+    return `${formatUnits(BigInt(units), t.decimals)} ${t.symbol}`;
+}
+/// What Remesso's executor runs per payment, gross, in base units. Outside
+/// these a schedule is valid on-chain and never runs.
+export function runLimits(t) {
+    if (!t.directAllowed || t.minPerRun == null || t.maxPerRun == null) {
+        throw new RemessoError("refused", `${t.symbol} isn't accepted for new schedules`);
+    }
+    return { min: BigInt(t.minPerRun), max: BigInt(t.maxPerRun) };
+}
+export const checksum = (a) => {
+    try {
+        return getAddress(a);
+    }
+    catch {
+        throw new RemessoError("invalid", `not an address: ${a}`);
+    }
+};

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+export type RemessoErrorCode = 
+/** The input is wrong: an address that isn't one, an unknown token, an amount out of range. */
+"invalid"
+/** The RPC isn't Celo mainnet, so nothing is signed. */
+ | "wrong_chain"
+/** A write needs an account and none was given. */
+ | "no_account"
+/** The contract or Remesso's backend would refuse it: caught before anything was sent. */
+ | "refused"
+/** Already done or taken: a subscription that exists, a request already answered, a nonce already spent. */
+ | "conflict"
+/** Mined, and reverted: nothing moved. */
+ | "reverted"
+/** No gas: neither CELO nor a token that can pay for it. */
+ | "no_gas"
+/** An idempotency key already used for a different payment. */
+ | "key_reused"
+/** An identical payment went out minutes ago and no idempotency key was given. */
+ | "repeat"
+/** A Remesso endpoint answered with an error. */
+ | "http"
+/** Not found: a request, a schedule, a subscription. */
+ | "not_found"
+/** Waited, and it didn't happen in time. */
+ | "timeout";
+export declare class RemessoError extends Error {
+    readonly code: RemessoErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor(code: RemessoErrorCode, message: string, details?: Record<string, unknown>);
+}

package/dist/errors.js

@@ -0,0 +1,10 @@
+export class RemessoError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "RemessoError";
+        this.code = code;
+        this.details = details;
+    }
+}

package/dist/events.d.ts

@@ -0,0 +1,59 @@
+import type { Address, Hex } from "viem";
+import type { Ctx } from "./context.js";
+export type EventKind = "run" | "schedule_created" | "policy_payment" | "policy_created" | "policy_revoked";
+export type PaymentEvent = {
+    seq: number;
+    chainId: number;
+    contract: Address;
+    kind: EventKind;
+    /** The schedule id for a run, the policy id for a policy event. */
+    refId: string;
+    from: Address | null;
+    to: Address | null;
+    agent: Address | null;
+    token: Address | null;
+    /** Base units, after the fee: what arrived. */
+    amount: string | null;
+    /** For a run, base units before the fee. */
+    amountIn: string | null;
+    memo: Hex | null;
+    memoText: string | null;
+    runNumber: number | null;
+    early: boolean | null;
+    details: Record<string, unknown> | null;
+    txHash: Hex;
+    logIndex: number;
+    blockNumber: number;
+    blockHash: Hex;
+    blockTime: string;
+    /** At or below Celo's finalized block. */
+    final: boolean;
+    /** Undone by a reorg. */
+    removed: boolean;
+};
+export type EventQuery = {
+    /** Default: this account. */
+    address?: string;
+    /** Which side of the event the address is on. Default any. */
+    role?: "to" | "from" | "agent" | "any";
+    kinds?: EventKind[];
+    /** The `next` of a previous page. Default 0: from the start. */
+    after?: number;
+    /** 1 to 500. Default 100. */
+    limit?: number;
+};
+export declare function makeEvents(ctx: Ctx): {
+    list: (q?: EventQuery) => Promise<{
+        events: PaymentEvent[];
+        next: number;
+    }>;
+    watch: (q?: EventQuery & {
+        intervalMs?: number;
+        signal?: AbortSignal;
+    }) => AsyncGenerator<PaymentEvent>;
+    waitFor(match: (e: PaymentEvent) => boolean, q?: EventQuery & {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<PaymentEvent>;
+};
+export type Events = ReturnType<typeof makeEvents>;

package/dist/events.js

@@ -0,0 +1,53 @@
+import { checksum } from "./deployment.js";
+import { RemessoError } from "./errors.js";
+export function makeEvents(ctx) {
+    async function list(q = {}) {
+        const address = (q.address ? checksum(q.address) : ctx.account?.address)?.toLowerCase();
+        if (!address)
+            throw new RemessoError("invalid", "address is required without an account");
+        const params = new URLSearchParams({ address, role: q.role ?? "any", after: String(q.after ?? 0), limit: String(q.limit ?? 100) });
+        if (q.kinds?.length)
+            params.set("kind", q.kinds.join(","));
+        return await ctx.get(`${ctx.endpoints.paymentEvents}?${params}`);
+    }
+    /// Every event from `after` on, then each new one or change as it comes,
+    /// until `signal` aborts. Polls every `intervalMs` (default 15s) when idle.
+    async function* watch(q = {}) {
+        let after = q.after ?? 0;
+        while (!q.signal?.aborted) {
+            const page = await list({ ...q, after, limit: q.limit ?? 500 });
+            for (const e of page.events)
+                yield e;
+            after = page.next;
+            if (page.events.length < (q.limit ?? 500))
+                await sleep(q.intervalMs ?? 15_000, q.signal);
+        }
+    }
+    return {
+        list,
+        watch,
+        /// The first event, from `after` on, that `match` accepts.
+        async waitFor(match, q = {}) {
+            const stop = new AbortController();
+            const timer = setTimeout(() => stop.abort(), q.timeoutMs ?? 20 * 60_000);
+            try {
+                for await (const e of watch({ ...q, signal: stop.signal }))
+                    if (match(e))
+                        return e;
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            throw new RemessoError("timeout", "no matching payment event in time");
+        },
+    };
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        const t = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(t);
+            resolve();
+        }, { once: true });
+    });
+}