remesso-sdk 0.0.0-stage → 0.2.0

package/dist/generated/deployment.d.ts

@@ -0,0 +1,114 @@
+export declare const deployment: {
+    readonly version: 1;
+    readonly generatedBy: "scripts/build-deployments.ts, from /functions/v1/agent and chain reads. Do not edit by hand.";
+    readonly chain: {
+        readonly name: "Celo";
+        readonly chainId: 42220;
+        readonly caip2: "eip155:42220";
+        readonly rpc: "https://forno.celo.org";
+    };
+    readonly contracts: {
+        readonly RemessoExecutorV5: {
+            readonly address: "0x3C357af3300f383Ea49B6D6ED8e084199a92bEd8";
+            readonly deployBlock: 80268721;
+            readonly executor: "0xA351d65c15b8a342B6ECbC7f2B9eFE62B17cdb21";
+            readonly currentExecutorSentinel: "0x0000000000000000000000000000000000000001";
+            readonly feeBps: 25;
+        };
+        readonly RemessoAgentAllowance: {
+            readonly address: "0xA6351fAeEb097698289586C4D6188530300DB209";
+            readonly deployBlock: 80467202;
+        };
+        readonly ERC8004IdentityRegistry: {
+            readonly address: "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432";
+        };
+    };
+    readonly tokens: readonly [{
+        readonly symbol: "USDT";
+        readonly address: "0x48065fbBE25f71C9282ddf5e1cD6D6A887483D5e";
+        readonly decimals: 6;
+        readonly currency: "USD";
+        readonly directAllowed: true;
+        readonly feeCurrency: "0x0E2A3e05bc9A16F5292A6170456A710cb89C6f72";
+        readonly minPerRun: "1000000";
+        readonly maxPerRun: "1000000000";
+    }, {
+        readonly symbol: "USDC";
+        readonly address: "0xcebA9300f2b948710d2653dD7B07f33A8B32118C";
+        readonly decimals: 6;
+        readonly currency: "USD";
+        readonly directAllowed: true;
+        readonly feeCurrency: "0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B";
+        readonly minPerRun: "1000000";
+        readonly maxPerRun: "1000000000";
+    }, {
+        readonly symbol: "USDm";
+        readonly address: "0x765DE816845861e75A25fCA122bb6898B8B1282a";
+        readonly decimals: 18;
+        readonly currency: "USD";
+        readonly directAllowed: true;
+        readonly feeCurrency: "0x765DE816845861e75A25fCA122bb6898B8B1282a";
+        readonly minPerRun: "1000000000000000000";
+        readonly maxPerRun: "1000000000000000000000";
+    }, {
+        readonly symbol: "USA₮";
+        readonly address: "0xD2ab3C9A02DBBAB236BfEC45D1d755DF4267F771";
+        readonly decimals: 6;
+        readonly currency: "USD";
+        readonly directAllowed: true;
+        readonly feeCurrency: "0x0357EE22278c922e1D36cFe6b899269b161880C4";
+        readonly minPerRun: "1000000";
+        readonly maxPerRun: "1000000000";
+    }, {
+        readonly symbol: "wARS";
+        readonly address: "0x0DC4F92879B7670e5f4e4e6e3c801D229129D90D";
+        readonly decimals: 18;
+        readonly currency: "ARS";
+        readonly directAllowed: true;
+        readonly feeCurrency: null;
+        readonly minPerRun: "1500000000000000000000";
+        readonly maxPerRun: "1500000000000000000000000";
+    }, {
+        readonly symbol: "wBRL";
+        readonly address: "0xD76f5Faf6888e24D9F04Bf92a0c8B921FE4390e0";
+        readonly decimals: 18;
+        readonly currency: "BRL";
+        readonly directAllowed: true;
+        readonly feeCurrency: null;
+        readonly minPerRun: "5000000000000000000";
+        readonly maxPerRun: "5000000000000000000000";
+    }, {
+        readonly symbol: "wCOP";
+        readonly address: "0x8a1D45e102e886510e891d2Ec656a708991e2D76";
+        readonly decimals: 18;
+        readonly currency: "COP";
+        readonly directAllowed: true;
+        readonly feeCurrency: null;
+        readonly minPerRun: "3200000000000000000000";
+        readonly maxPerRun: "3200000000000000000000000";
+    }, {
+        readonly symbol: "cNGN";
+        readonly address: "0xF6829D7393dAe24509eb1E52eE8e572e2E271a4f";
+        readonly decimals: 6;
+        readonly currency: "NGN";
+        readonly directAllowed: true;
+        readonly feeCurrency: null;
+        readonly minPerRun: "1300000000";
+        readonly maxPerRun: "1300000000000";
+    }];
+    readonly functions: {
+        readonly base: "https://engaboljiqudghvzmebq.supabase.co/functions/v1";
+        readonly agent: "https://engaboljiqudghvzmebq.supabase.co/functions/v1/agent";
+        readonly "request-payment": "https://engaboljiqudghvzmebq.supabase.co/functions/v1/request-payment";
+        readonly "payment-events": "https://engaboljiqudghvzmebq.supabase.co/functions/v1/payment-events";
+        readonly webhooks: "https://engaboljiqudghvzmebq.supabase.co/functions/v1/webhooks";
+        readonly "trigger-run": "https://engaboljiqudghvzmebq.supabase.co/functions/v1/trigger-run";
+        readonly "rate-service": "https://engaboljiqudghvzmebq.supabase.co/functions/v1/rate-service";
+        readonly "latam-rate": "https://engaboljiqudghvzmebq.supabase.co/functions/v1/latam-rate";
+        readonly "latam-route": "https://engaboljiqudghvzmebq.supabase.co/functions/v1/latam-route";
+    };
+    readonly app: {
+        readonly origin: "https://remesso.xyz";
+        readonly mcp: "https://remesso.xyz/mcp";
+    };
+};

package/dist/generated/deployment.js

@@ -0,0 +1,127 @@
+// Copied from deployments/celo-mainnet.json by scripts/build-sdk.ts. Edit the original and re-run;
+// `build-sdk.ts --check` fails while the two differ.
+/// Celo mainnet as Remesso runs it: contracts, tokens with their per-run
+/// limits, the fee, and the public endpoints.
+export const deployment = {
+    "version": 1,
+    "generatedBy": "scripts/build-deployments.ts, from /functions/v1/agent and chain reads. Do not edit by hand.",
+    "chain": {
+        "name": "Celo",
+        "chainId": 42220,
+        "caip2": "eip155:42220",
+        "rpc": "https://forno.celo.org"
+    },
+    "contracts": {
+        "RemessoExecutorV5": {
+            "address": "0x3C357af3300f383Ea49B6D6ED8e084199a92bEd8",
+            "deployBlock": 80268721,
+            "executor": "0xA351d65c15b8a342B6ECbC7f2B9eFE62B17cdb21",
+            "currentExecutorSentinel": "0x0000000000000000000000000000000000000001",
+            "feeBps": 25
+        },
+        "RemessoAgentAllowance": {
+            "address": "0xA6351fAeEb097698289586C4D6188530300DB209",
+            "deployBlock": 80467202
+        },
+        "ERC8004IdentityRegistry": {
+            "address": "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"
+        }
+    },
+    "tokens": [
+        {
+            "symbol": "USDT",
+            "address": "0x48065fbBE25f71C9282ddf5e1cD6D6A887483D5e",
+            "decimals": 6,
+            "currency": "USD",
+            "directAllowed": true,
+            "feeCurrency": "0x0E2A3e05bc9A16F5292A6170456A710cb89C6f72",
+            "minPerRun": "1000000",
+            "maxPerRun": "1000000000"
+        },
+        {
+            "symbol": "USDC",
+            "address": "0xcebA9300f2b948710d2653dD7B07f33A8B32118C",
+            "decimals": 6,
+            "currency": "USD",
+            "directAllowed": true,
+            "feeCurrency": "0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B",
+            "minPerRun": "1000000",
+            "maxPerRun": "1000000000"
+        },
+        {
+            "symbol": "USDm",
+            "address": "0x765DE816845861e75A25fCA122bb6898B8B1282a",
+            "decimals": 18,
+            "currency": "USD",
+            "directAllowed": true,
+            "feeCurrency": "0x765DE816845861e75A25fCA122bb6898B8B1282a",
+            "minPerRun": "1000000000000000000",
+            "maxPerRun": "1000000000000000000000"
+        },
+        {
+            "symbol": "USA₮",
+            "address": "0xD2ab3C9A02DBBAB236BfEC45D1d755DF4267F771",
+            "decimals": 6,
+            "currency": "USD",
+            "directAllowed": true,
+            "feeCurrency": "0x0357EE22278c922e1D36cFe6b899269b161880C4",
+            "minPerRun": "1000000",
+            "maxPerRun": "1000000000"
+        },
+        {
+            "symbol": "wARS",
+            "address": "0x0DC4F92879B7670e5f4e4e6e3c801D229129D90D",
+            "decimals": 18,
+            "currency": "ARS",
+            "directAllowed": true,
+            "feeCurrency": null,
+            "minPerRun": "1500000000000000000000",
+            "maxPerRun": "1500000000000000000000000"
+        },
+        {
+            "symbol": "wBRL",
+            "address": "0xD76f5Faf6888e24D9F04Bf92a0c8B921FE4390e0",
+            "decimals": 18,
+            "currency": "BRL",
+            "directAllowed": true,
+            "feeCurrency": null,
+            "minPerRun": "5000000000000000000",
+            "maxPerRun": "5000000000000000000000"
+        },
+        {
+            "symbol": "wCOP",
+            "address": "0x8a1D45e102e886510e891d2Ec656a708991e2D76",
+            "decimals": 18,
+            "currency": "COP",
+            "directAllowed": true,
+            "feeCurrency": null,
+            "minPerRun": "3200000000000000000000",
+            "maxPerRun": "3200000000000000000000000"
+        },
+        {
+            "symbol": "cNGN",
+            "address": "0xF6829D7393dAe24509eb1E52eE8e572e2E271a4f",
+            "decimals": 6,
+            "currency": "NGN",
+            "directAllowed": true,
+            "feeCurrency": null,
+            "minPerRun": "1300000000",
+            "maxPerRun": "1300000000000"
+        }
+    ],
+    "functions": {
+        "base": "https://engaboljiqudghvzmebq.supabase.co/functions/v1",
+        "agent": "https://engaboljiqudghvzmebq.supabase.co/functions/v1/agent",
+        "request-payment": "https://engaboljiqudghvzmebq.supabase.co/functions/v1/request-payment",
+        "payment-events": "https://engaboljiqudghvzmebq.supabase.co/functions/v1/payment-events",
+        "webhooks": "https://engaboljiqudghvzmebq.supabase.co/functions/v1/webhooks",
+        "trigger-run": "https://engaboljiqudghvzmebq.supabase.co/functions/v1/trigger-run",
+        "rate-service": "https://engaboljiqudghvzmebq.supabase.co/functions/v1/rate-service",
+        "latam-rate": "https://engaboljiqudghvzmebq.supabase.co/functions/v1/latam-rate",
+        "latam-route": "https://engaboljiqudghvzmebq.supabase.co/functions/v1/latam-route"
+    },
+    "app": {
+        "origin": "https://remesso.xyz",
+        "mcp": "https://remesso.xyz/mcp"
+    }
+};

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { createRemesso, type Remesso, type RemessoOptions } from "./client.js";
+export { RemessoError, type RemessoErrorCode } from "./errors.js";
+export { ALLOWANCE, CHAIN_ID, CURRENT_EXECUTOR, deployment, EXECUTOR, FEE_BPS, findToken, formatAmount, REGISTRY, runLimits, type Token, token, toUnits, } from "./deployment.js";
+export { feeOf, grossFor, netOf } from "./vendor/fee.js";
+export { allowanceAbi, erc20Abi, executorAbi, registryAbi } from "./abi.js";
+export { ATTRIBUTION, attributionFor } from "./attribution.js";
+export { CADENCES, type Cadence, type CreatedSchedule, type CreateScheduleInput, type Schedule } from "./schedules.js";
+export { memo32, type PayInput, type PaymentResult } from "./payments.js";
+export type { CreatePolicyInput, Policy } from "./policies.js";
+export type { CreateRequestInput, RequestState, RequestStatus, RequestSummary } from "./requests.js";
+export type { EventKind, EventQuery, PaymentEvent } from "./events.js";
+export { parseWebhook, verifyWebhook, webhookHandler, type WebhookHandlerOptions, type WebhookMessage, type WebhookType, } from "./webhooks.js";
+export type { FoundAgent } from "./agents.js";
+export type { PayeeProfile } from "./vendor/payee-profile.js";
+export { type PayLink, type PayLinkInput, parsePayLink, payLink } from "./links.js";
+export { memoryStore, type PaymentRecord, type PaymentStore } from "./store.js";

package/dist/index.js

@@ -0,0 +1,15 @@
+/// remesso-sdk: recurring and agent payments on Celo.
+///
+/// Celo mainnet only: there is no testnet. The contracts are live and have
+/// not been audited by a person, so start with small amounts.
+export { createRemesso } from "./client.js";
+export { RemessoError } from "./errors.js";
+export { ALLOWANCE, CHAIN_ID, CURRENT_EXECUTOR, deployment, EXECUTOR, FEE_BPS, findToken, formatAmount, REGISTRY, runLimits, token, toUnits, } from "./deployment.js";
+export { feeOf, grossFor, netOf } from "./vendor/fee.js";
+export { allowanceAbi, erc20Abi, executorAbi, registryAbi } from "./abi.js";
+export { ATTRIBUTION, attributionFor } from "./attribution.js";
+export { CADENCES } from "./schedules.js";
+export { memo32 } from "./payments.js";
+export { parseWebhook, verifyWebhook, webhookHandler, } from "./webhooks.js";
+export { parsePayLink, payLink } from "./links.js";
+export { memoryStore } from "./store.js";

package/dist/links.d.ts

@@ -0,0 +1,25 @@
+export type PayLinkInput = {
+    to: string;
+    /** Who is asking, shown on the form. */
+    from?: string;
+    /** What the recipient should receive per payment, decimal. */
+    amount?: string;
+    token?: string;
+    every?: "week" | "fortnight" | "month" | "quarter";
+    runs?: number;
+    note?: string;
+    /** The payment request this link answers. */
+    request?: string;
+};
+export type PayLink = {
+    to?: `0x${string}`;
+    from?: string;
+    amount?: string;
+    token?: string;
+    intervalSeconds?: number;
+    runs?: number;
+    note?: string;
+    request?: string;
+};
+export declare function payLink(p: PayLinkInput, origin?: string): string;
+export declare function parsePayLink(urlOrQuery: string): PayLink;

package/dist/links.js

@@ -0,0 +1,60 @@
+/// A link that says "pay me here", and the parser that reads one. Ported from
+/// `web/lib/payLink.ts`, which the app reads links with.
+///
+/// A link fills in a form. It can't create a schedule, approve an allowance or
+/// sign anything: the payer reviews every field and signs in their own wallet,
+/// and the form says a link filled it. Everything is validated, not trusted:
+/// a link is input from a stranger.
+import { isAddress } from "viem";
+import { deployment, findToken } from "./deployment.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/// The cadences the form's picker offers. Anything else is dropped.
+const CADENCE = {
+    week: 604_800, weekly: 604_800,
+    fortnight: 1_209_600, fortnightly: 1_209_600,
+    month: 2_592_000, monthly: 2_592_000,
+    quarter: 7_776_000, quarterly: 7_776_000,
+};
+/// The link that opens the payer's Remesso form prefilled.
+export function payLink(p, origin = deployment.app.origin) {
+    const q = new URLSearchParams();
+    q.set("to", p.to);
+    const token = p.token ? findToken(p.token)?.symbol ?? p.token : undefined;
+    for (const [k, v] of Object.entries({ from: p.from, amount: p.amount, token, every: p.every, runs: p.runs, note: p.note, req: p.request })) {
+        if (v != null && v !== "")
+            q.set(k, String(v));
+    }
+    return `${origin.replace(/\/+$/, "")}/schedules/new?${q.toString()}`;
+}
+/// What a link says, keeping only what validates.
+export function parsePayLink(urlOrQuery) {
+    const s = String(urlOrQuery);
+    const q = new URLSearchParams(s.includes("?") ? s.slice(s.indexOf("?") + 1) : s);
+    const out = {};
+    const to = (q.get("to") ?? "").trim();
+    if (isAddress(to))
+        out.to = to;
+    const from = (q.get("from") ?? q.get("name") ?? "").trim();
+    if (from)
+        out.from = from.slice(0, 40);
+    const note = (q.get("note") ?? "").trim();
+    if (note)
+        out.note = note.slice(0, 120);
+    const amount = (q.get("amount") ?? "").trim();
+    if (/^\d{1,12}(\.\d{1,18})?$/.test(amount) && Number(amount) > 0)
+        out.amount = amount;
+    const token = findToken((q.get("token") ?? "").trim());
+    if (token && token.directAllowed)
+        out.token = token.symbol;
+    const every = (q.get("every") ?? "").trim().toLowerCase();
+    const seconds = CADENCE[every] ?? (/^\d+$/.test(every) ? Number(every) : NaN);
+    if (Object.values(CADENCE).includes(seconds))
+        out.intervalSeconds = seconds;
+    const runs = (q.get("runs") ?? "").trim();
+    if (/^\d{1,4}$/.test(runs) && Number(runs) > 0)
+        out.runs = Number(runs);
+    const req = (q.get("req") ?? "").trim();
+    if (UUID.test(req))
+        out.request = req.toLowerCase();
+    return out;
+}

package/dist/node.d.ts

@@ -0,0 +1,5 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type PaymentStore } from "./store.js";
+export { safeFetchText } from "./vendor/safe-fetch.js";
+export declare function fileStore(path?: string): PaymentStore;
+export declare function toNodeListener(handler: (req: Request) => Promise<Response>): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/dist/node.js

@@ -0,0 +1,60 @@
+/// Node-only parts: a payment store on disk, the safe fetch for remote
+/// registration files, and an adapter from the fetch-style webhook handler to
+/// `http.createServer` or Express.
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { upsert } from "./store.js";
+export { safeFetchText } from "./vendor/safe-fetch.js";
+/// Agent payment records in a JSON file (mode 0600), so a retry after a
+/// restart still pays once. Default `~/.remesso-sdk/payments.json`. One
+/// process per file: it isn't locked.
+export function fileStore(path = join(homedir(), ".remesso-sdk", "payments.json")) {
+    const load = () => {
+        try {
+            return JSON.parse(readFileSync(path, "utf8")).payments ?? [];
+        }
+        catch {
+            return [];
+        }
+    };
+    return {
+        byKey: async (key, deployment) => load().reverse().find((p) => p.key === key && p.deployment === deployment),
+        since: async (since) => load().filter((p) => Date.parse(p.at) > since),
+        save: async (rec) => {
+            mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+            const tmp = `${path}.${process.pid}.tmp`;
+            writeFileSync(tmp, JSON.stringify({ version: 1, payments: upsert(load(), rec) }, null, 2), { mode: 0o600 });
+            renameSync(tmp, path); // whole or not at all: a crash mid-write keeps the old file
+            chmodSync(path, 0o600);
+        },
+    };
+}
+/// `http.createServer(toNodeListener(webhookHandler({...})))`, or as Express
+/// middleware on a route: it reads the raw body itself, so mount it before
+/// any JSON body parser.
+export function toNodeListener(handler) {
+    return async (req, res) => {
+        try {
+            const chunks = [];
+            for await (const c of req)
+                chunks.push(c);
+            const headers = new Headers();
+            for (const [k, v] of Object.entries(req.headers))
+                if (typeof v === "string")
+                    headers.set(k, v);
+            const url = `http://${req.headers.host ?? "localhost"}${req.url ?? "/"}`;
+            const out = await handler(new Request(url, {
+                method: req.method,
+                headers,
+                body: req.method === "GET" || req.method === "HEAD" ? undefined : Buffer.concat(chunks),
+            }));
+            res.writeHead(out.status, Object.fromEntries(out.headers));
+            res.end(Buffer.from(await out.arrayBuffer()));
+        }
+        catch (e) {
+            res.writeHead(500, { "content-type": "application/json" });
+            res.end(JSON.stringify({ error: e.message }));
+        }
+    };
+}

package/dist/payments.d.ts

@@ -0,0 +1,39 @@
+import { type Address, type Hex } from "viem";
+import { type Ctx } from "./context.js";
+import type { Policies } from "./policies.js";
+export type PayInput = {
+    to: string;
+    /** Decimal, in the policy token's units: "0.10". */
+    amount: string;
+    /** Symbol or address. Default: the token of the policy used. */
+    token?: string;
+    /** Which policy to pay under. Default: an active one for the token that can cover the amount. */
+    policyId?: bigint | number | string;
+    /** Up to 32 bytes, recorded on-chain in the Paid event. A request's reference goes here. */
+    memo?: string;
+    /**
+     * One per payment you intend (an invoice or request id is ideal). A retry with the
+     * same key reports the first payment's outcome and never pays twice.
+     */
+    idempotencyKey?: string;
+    /** Pay even though an identical payment went out in the last ten minutes. */
+    allowRepeat?: boolean;
+    /** How long to wait for the receipt before answering "pending". Default 45s. */
+    waitMs?: number;
+};
+export type PaymentResult = {
+    status: "confirmed" | "pending";
+    hash: Hex;
+    policyId: bigint;
+    to: Address;
+    amount: bigint;
+    token: Address;
+    /** "1.5 USDT" */
+    sent: string;
+    explorer: string;
+    /** True when this key had already paid and nothing new was sent. */
+    repeat?: boolean;
+};
+export declare const DEPLOYMENT: string;
+export declare function memo32(memo?: string): Hex;
+export declare function makePay(ctx: Ctx, policies: Policies): (input: PayInput) => Promise<PaymentResult>;