@tabai/sdk 0.2.0

package/dist/payments/config.js

@@ -0,0 +1,259 @@
+/**
+ * `tab.config.ts` discovery: mechanism three of R23.6.
+ *
+ * Zero-code wiring. A consumer writes a config file naming strategies as module
+ * specifiers, and the strategies register themselves at startup with no
+ * application code involved at all:
+ *
+ * ```ts
+ * // tab.config.ts, at the consumer's project root
+ * import { defineTabConfig } from "@tabai/sdk";
+ * export default defineTabConfig({ strategies: ["@acme/tab-strategy-solana"] });
+ * ```
+ *
+ * ## What an entry may be
+ *
+ * A module specifier, a strategy object, or a factory returning one. The
+ * specifier form is the point of the mechanism; the other two exist because a
+ * config file that can only name packages forces a consumer to publish one before
+ * they can try anything.
+ *
+ * ## Where a specifier resolves from
+ *
+ * From the **config file**, not from this package. `@acme/tab-strategy-solana` is
+ * the consumer's dependency and under pnpm it is not visible from inside
+ * `@tabai/sdk` at all, so resolving relative to this module would fail for the
+ * exact layout the workspace uses. `createRequire(configFileUrl)` resolves the
+ * way the consumer's own `import` would, and a bare specifier that resolution
+ * misses is retried as a plain dynamic import before the error is reported.
+ *
+ * ## The `.ts` config file and the host runtime
+ *
+ * This module imports the config file; it does not compile it. A `.ts` config
+ * loads under a runtime that strips types, `tsx`, `node --experimental-strip-types`,
+ * a bundler's dev server, and fails under one that does not. That failure comes
+ * back as a `Result` naming the file and the requirement rather than as a stack
+ * trace, and `tab.config.js` and `tab.config.mjs` are discovered too so a
+ * consumer with a plain Node process has a first-class option.
+ *
+ * Requirements: 23.6, 21.5
+ */
+import { existsSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, resolve as resolvePath } from "node:path";
+import { pathToFileURL } from "node:url";
+import { causeOf, ok, wrap, wrapSync } from "../_shared/index.js";
+import { defaultLogger } from "../logger.js";
+import { notFoundError, validationError } from "../errors.js";
+import { validatePaymentStrategy } from "./strategy.js";
+import { moduleStrategyRegistry, } from "./registry.js";
+/**
+ * Types a config file's default export. Identity at runtime, its whole job is to
+ * make a typo in the config a compile error in the consumer's editor.
+ */
+export const defineTabConfig = (config) => config;
+/**
+ * The file names discovery looks for, in order. `.ts` first because it is the
+ * documented form and the one that type-checks; the plain-JavaScript forms follow
+ * so a consumer whose runtime strips no types is not shut out.
+ */
+export const TAB_CONFIG_FILE_NAMES = [
+    "tab.config.ts",
+    "tab.config.mts",
+    "tab.config.mjs",
+    "tab.config.js",
+    "tab.config.cjs",
+];
+/**
+ * Walks from `cwd` towards the filesystem root and returns the first config file
+ * found, or `undefined` when there is none.
+ *
+ * Absence is not an error: the whole point of the mechanism is that a consumer
+ * who wants nothing from it writes nothing.
+ */
+export function findTabConfig(options = {}) {
+    return wrapSync(() => {
+        const fileNames = options.fileNames ?? TAB_CONFIG_FILE_NAMES;
+        let directory = resolvePath(options.cwd ?? ".");
+        for (;;) {
+            for (const fileName of fileNames) {
+                const candidate = resolvePath(directory, fileName);
+                if (existsSync(candidate) && statSync(candidate).isFile())
+                    return candidate;
+            }
+            const parent = dirname(directory);
+            if (parent === directory)
+                return undefined;
+            directory = parent;
+        }
+    }, (error) => ({
+        category: "INTERNAL",
+        code: "CONFIG_SEARCH_FAILED",
+        message: "the tab.config search could not read the filesystem",
+        retryable: false,
+        cause: causeOf(error),
+    }));
+}
+const EMPTY_CONFIG = {};
+/**
+ * Loads a config file, resolves every strategy entry, and registers the result.
+ *
+ * Returns a `Result` for every failure, including a config file that throws on
+ * import: a consumer's config is consumer code, and this package does not turn
+ * their mistake into an unhandled rejection.
+ */
+export async function loadTabConfig(options = {}) {
+    const logger = options.logger ?? defaultLogger;
+    const located = locateConfig(options);
+    if (!located.ok)
+        return located;
+    const path = located.value;
+    if (path === undefined) {
+        return ok({ path: undefined, config: EMPTY_CONFIG, strategies: [], registrations: [] });
+    }
+    const imported = await importModule(path, `tab config \`${path}\``);
+    if (!imported.ok)
+        return imported;
+    const config = readDefaultExport(imported.value, path);
+    if (!config.ok)
+        return config;
+    const strategies = [];
+    let declined = 0;
+    for (const [index, entry] of (config.value.strategies ?? []).entries()) {
+        const resolved = await resolveEntry(entry, index, path);
+        if (!resolved.ok)
+            return resolved;
+        // `undefined` is the factory declining, not a fault. Skip it and keep going.
+        if (resolved.value === undefined) {
+            declined += 1;
+            continue;
+        }
+        strategies.push(resolved.value);
+    }
+    const registrations = [];
+    if (options.registry !== false) {
+        const registry = options.registry ?? moduleStrategyRegistry(logger);
+        for (const strategy of strategies) {
+            const outcome = registry.register(strategy);
+            if (!outcome.ok)
+                return outcome;
+            registrations.push(outcome.value);
+        }
+    }
+    logger.debug("tab config loaded", { path, strategies: strategies.length, declined });
+    return ok({ path, config: config.value, strategies, registrations });
+}
+function locateConfig(options) {
+    if (options.configPath === undefined)
+        return findTabConfig(options);
+    const cwd = resolvePath(options.cwd ?? ".");
+    const path = isAbsolute(options.configPath)
+        ? options.configPath
+        : resolvePath(cwd, options.configPath);
+    if (!existsSync(path)) {
+        return notFoundError("CONFIG_NOT_FOUND", `no tab config file at \`${path}\``, {
+            details: { path },
+        });
+    }
+    return ok(path);
+}
+/** Imports a file by path. A `.ts` file needs a type-stripping runtime, so say so. */
+async function importModule(path, label) {
+    const href = pathToFileURL(path).href;
+    return wrap(async () => (await import(href)), (error) => ({
+        category: "UPSTREAM",
+        code: "CONFIG_IMPORT_FAILED",
+        message: path.endsWith(".ts") || path.endsWith(".mts")
+            ? `${label} could not be imported; a TypeScript config file needs a runtime that strips types, or use tab.config.mjs`
+            : `${label} could not be imported`,
+        retryable: false,
+        details: { path },
+        cause: causeOf(error),
+    }));
+}
+function readDefaultExport(module, path) {
+    const exported = module["default"];
+    if (exported === undefined) {
+        return validationError("CONFIG_NO_DEFAULT_EXPORT", `\`${path}\` must default-export a config, for example \`export default defineTabConfig({ strategies: [] })\``, { details: { path } });
+    }
+    if (typeof exported !== "object" || exported === null) {
+        return validationError("CONFIG_INVALID", `the default export of \`${path}\` must be an object`, { details: { path } });
+    }
+    const candidate = exported;
+    if (candidate.x402 !== undefined && typeof candidate.x402 !== "function") {
+        return validationError("CONFIG_INVALID", `\`${path}\` declares \`x402\` but it is not a factory; it must be a function returning a signer or undefined, so the file holds no key`, { details: { path } });
+    }
+    if (candidate.strategies !== undefined && !Array.isArray(candidate.strategies)) {
+        return validationError("CONFIG_INVALID", `\`${path}\` declares \`strategies\` but it is not an array`, { details: { path } });
+    }
+    if (candidate.services !== undefined && !Array.isArray(candidate.services)) {
+        return validationError("CONFIG_INVALID", `\`${path}\` declares \`services\` but it is not an array`, { details: { path } });
+    }
+    return ok(exported);
+}
+async function resolveEntry(entry, index, configPath) {
+    const label = `strategies[${index}] of \`${configPath}\``;
+    if (typeof entry === "string") {
+        const module = await importSpecifier(entry, configPath);
+        if (!module.ok)
+            return module;
+        const exported = module.value["default"];
+        if (exported === undefined) {
+            return validationError("STRATEGY_MODULE_INVALID", `${label}: \`${entry}\` must default-export a PaymentStrategy or a factory returning one`, { details: { specifier: entry } });
+        }
+        return callIfFactory(exported, `${label} (\`${entry}\`)`);
+    }
+    return callIfFactory(entry, label);
+}
+/**
+ * A strategy is an object and a factory is a function, so `typeof` separates them.
+ *
+ * A factory returning `undefined` is passed straight back as `undefined` rather
+ * than sent to the validator, because declining is one of the two answers a
+ * factory is allowed to give. A bare `undefined` written directly in the array
+ * is still invalid, and still reaches the validator: that is a typo rather than
+ * a decision, and nothing about it says a key was missing.
+ */
+async function callIfFactory(value, label) {
+    if (typeof value !== "function")
+        return validatePaymentStrategy(value, label);
+    const produced = await wrap(async () => (await value()), (error) => ({
+        category: "UPSTREAM",
+        code: "STRATEGY_FACTORY_FAILED",
+        message: `${label}: the strategy factory threw`,
+        retryable: false,
+        cause: causeOf(error),
+    }));
+    if (!produced.ok)
+        return produced;
+    if (produced.value === undefined || produced.value === null)
+        return ok(undefined);
+    return validatePaymentStrategy(produced.value, label);
+}
+/**
+ * Resolves a bare or relative specifier the way the consumer's own `import`
+ * would: from the config file. Falls back to a plain dynamic import, which covers
+ * a package the CommonJS resolver cannot see through its `exports` conditions.
+ */
+async function importSpecifier(specifier, configPath) {
+    const fromConfig = wrapSync(() => createRequire(pathToFileURL(configPath)).resolve(specifier), (error) => ({
+        category: "NOT_FOUND",
+        code: "STRATEGY_MODULE_NOT_FOUND",
+        message: `\`${specifier}\` could not be resolved from \`${configPath}\``,
+        retryable: false,
+        details: { specifier, configPath },
+        cause: causeOf(error),
+    }));
+    if (fromConfig.ok) {
+        return importModule(fromConfig.value, `strategy module \`${specifier}\``);
+    }
+    return wrap(async () => (await import(specifier)), (error) => ({
+        category: "NOT_FOUND",
+        code: "STRATEGY_MODULE_NOT_FOUND",
+        message: `\`${specifier}\` could not be imported from \`${configPath}\` or resolved as a bare module`,
+        retryable: false,
+        details: { specifier, configPath },
+        cause: causeOf(error),
+    }));
+}
+//# sourceMappingURL=config.js.map

package/dist/payments/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/payments/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAe,MAAM,eAAe,CAAC;AACzE,OAAO,EAAE,aAAa,EAAe,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAwB,MAAM,eAAe,CAAC;AAE9E,OAAO,EACL,sBAAsB,GAGvB,MAAM,eAAe,CAAC;AAoHvB;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,MAAiB,EAAa,EAAE,CAAC,MAAM,CAAC;AAExE;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,eAAe;IACf,gBAAgB;IAChB,gBAAgB;IAChB,eAAe;IACf,gBAAgB;CACR,CAAC;AAQX;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,UAAgC,EAAE;IAC9D,OAAO,QAAQ,CACb,GAAG,EAAE;QACH,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,qBAAqB,CAAC;QAC7D,IAAI,SAAS,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;QAChD,SAAS,CAAC;YACR,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;gBACjC,MAAM,SAAS,GAAG,WAAW,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;gBACnD,IAAI,UAAU,CAAC,SAAS,CAAC,IAAI,QAAQ,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE;oBAAE,OAAO,SAAS,CAAC;YAC9E,CAAC;YACD,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;YAClC,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YAC3C,SAAS,GAAG,MAAM,CAAC;QACrB,CAAC;IACH,CAAC,EACD,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACV,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,sBAAsB;QAC5B,OAAO,EAAE,qDAAqD;QAC9D,SAAS,EAAE,KAAK;QAChB,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC;KACtB,CAAC,CACH,CAAC;AACJ,CAAC;AAuBD,MAAM,YAAY,GAAc,EAAE,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,UAAgC,EAAE;IAElC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,aAAa,CAAC;IAE/C,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,OAAO,CAAC;IAChC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC;IAE3B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC,CAAC;IAC1F,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,gBAAgB,IAAI,IAAI,CAAC,CAAC;IACpE,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,OAAO,QAAQ,CAAC;IAElC,MAAM,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACvD,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,MAAM,CAAC;IAE9B,MAAM,UAAU,GAAsB,EAAE,CAAC;IACzC,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;QACvE,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;QACxD,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,OAAO,QAAQ,CAAC;QAClC,6EAA6E;QAC7E,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YACjC,QAAQ,IAAI,CAAC,CAAC;YACd,SAAS;QACX,CAAC;QACD,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,MAAM,aAAa,GAA2B,EAAE,CAAC;IACjD,IAAI,OAAO,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,sBAAsB,CAAC,MAAM,CAAC,CAAC;QACpE,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;YAClC,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC5C,IAAI,CAAC,OAAO,CAAC,EAAE;gBAAE,OAAO,OAAO,CAAC;YAChC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,mBAAmB,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IACrF,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,YAAY,CAAC,OAA6B;IACjD,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS;QAAE,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC;IAEpE,MAAM,GAAG,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,UAAU,CAAC;QACzC,CAAC,CAAC,OAAO,CAAC,UAAU;QACpB,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IACzC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO,aAAa,CAAC,kBAAkB,EAAE,2BAA2B,IAAI,IAAI,EAAE;YAC5E,OAAO,EAAE,EAAE,IAAI,EAAE;SAClB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;AAClB,CAAC;AAED,sFAAsF;AACtF,KAAK,UAAU,YAAY,CAAC,IAAY,EAAE,KAAa;IACrD,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;IACtC,OAAO,IAAI,CACT,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,IAAI,CAAC,CAA4B,EAC3D,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACV,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,sBAAsB;QAC5B,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;YACpD,CAAC,CAAC,GAAG,KAAK,2GAA2G;YACrH,CAAC,CAAC,GAAG,KAAK,wBAAwB;QACpC,SAAS,EAAE,KAAK;QAChB,OAAO,EAAE,EAAE,IAAI,EAAE;QACjB,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC;KACtB,CAAC,CACH,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,MAA+B,EAAE,IAAY;IACtE,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IACnC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,eAAe,CACpB,0BAA0B,EAC1B,KAAK,IAAI,qGAAqG,EAC9G,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,CACtB,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtD,OAAO,eAAe,CACpB,gBAAgB,EAChB,2BAA2B,IAAI,sBAAsB,EACrD,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,CACtB,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,QAAwE,CAAC;IAC3F,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,SAAS,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QACzE,OAAO,eAAe,CACpB,gBAAgB,EAChB,KAAK,IAAI,+HAA+H,EACxI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,CACtB,CAAC;IACJ,CAAC;IACD,IAAI,SAAS,CAAC,UAAU,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/E,OAAO,eAAe,CACpB,gBAAgB,EAChB,KAAK,IAAI,mDAAmD,EAC5D,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,CACtB,CAAC;IACJ,CAAC;IACD,IAAI,SAAS,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3E,OAAO,eAAe,CACpB,gBAAgB,EAChB,KAAK,IAAI,iDAAiD,EAC1D,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,CACtB,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,CAAC,QAAqB,CAAC,CAAC;AACnC,CAAC;AAED,KAAK,UAAU,YAAY,CACzB,KAA6B,EAC7B,KAAa,EACb,UAAkB;IAElB,MAAM,KAAK,GAAG,cAAc,KAAK,UAAU,UAAU,IAAI,CAAC;IAE1D,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;QACxD,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,MAAM,CAAC;QAC9B,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACzC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,eAAe,CACpB,yBAAyB,EACzB,GAAG,KAAK,OAAO,KAAK,qEAAqE,EACzF,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,CAClC,CAAC;QACJ,CAAC;QACD,OAAO,aAAa,CAAC,QAAQ,EAAE,GAAG,KAAK,OAAO,KAAK,KAAK,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,aAAa,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;GAQG;AACH,KAAK,UAAU,aAAa,CAC1B,KAAc,EACd,KAAa;IAEb,IAAI,OAAO,KAAK,KAAK,UAAU;QAAE,OAAO,uBAAuB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAE9E,MAAM,QAAQ,GAAG,MAAM,IAAI,CACzB,KAAK,IAAI,EAAE,CAAC,CAAC,MAAO,KAAgC,EAAE,CAAY,EAClE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACV,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,yBAAyB;QAC/B,OAAO,EAAE,GAAG,KAAK,8BAA8B;QAC/C,SAAS,EAAE,KAAK;QAChB,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC;KACtB,CAAC,CACH,CAAC;IACF,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,OAAO,QAAQ,CAAC;IAClC,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,IAAI,QAAQ,CAAC,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC;IAClF,OAAO,uBAAuB,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,eAAe,CAC5B,SAAiB,EACjB,UAAkB;IAElB,MAAM,UAAU,GAAG,QAAQ,CACzB,GAAG,EAAE,CAAC,aAAa,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EACjE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACV,QAAQ,EAAE,WAAW;QACrB,IAAI,EAAE,2BAA2B;QACjC,OAAO,EAAE,KAAK,SAAS,mCAAmC,UAAU,IAAI;QACxE,SAAS,EAAE,KAAK;QAChB,OAAO,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE;QAClC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC;KACtB,CAAC,CACH,CAAC;IAEF,IAAI,UAAU,CAAC,EAAE,EAAE,CAAC;QAClB,OAAO,YAAY,CAAC,UAAU,CAAC,KAAK,EAAE,qBAAqB,SAAS,IAAI,CAAC,CAAC;IAC5E,CAAC;IAED,OAAO,IAAI,CACT,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,CAA4B,EAChE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACV,QAAQ,EAAE,WAAW;QACrB,IAAI,EAAE,2BAA2B;QACjC,OAAO,EAAE,KAAK,SAAS,mCAAmC,UAAU,iCAAiC;QACrG,SAAS,EAAE,KAAK;QAChB,OAAO,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE;QAClC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC;KACtB,CAAC,CACH,CAAC;AACJ,CAAC","sourcesContent":["/**\n * `tab.config.ts` discovery: mechanism three of R23.6.\n *\n * Zero-code wiring. A consumer writes a config file naming strategies as module\n * specifiers, and the strategies register themselves at startup with no\n * application code involved at all:\n *\n * ```ts\n * // tab.config.ts, at the consumer's project root\n * import { defineTabConfig } from \"@tabai/sdk\";\n * export default defineTabConfig({ strategies: [\"@acme/tab-strategy-solana\"] });\n * ```\n *\n * ## What an entry may be\n *\n * A module specifier, a strategy object, or a factory returning one. The\n * specifier form is the point of the mechanism; the other two exist because a\n * config file that can only name packages forces a consumer to publish one before\n * they can try anything.\n *\n * ## Where a specifier resolves from\n *\n * From the **config file**, not from this package. `@acme/tab-strategy-solana` is\n * the consumer's dependency and under pnpm it is not visible from inside\n * `@tabai/sdk` at all, so resolving relative to this module would fail for the\n * exact layout the workspace uses. `createRequire(configFileUrl)` resolves the\n * way the consumer's own `import` would, and a bare specifier that resolution\n * misses is retried as a plain dynamic import before the error is reported.\n *\n * ## The `.ts` config file and the host runtime\n *\n * This module imports the config file; it does not compile it. A `.ts` config\n * loads under a runtime that strips types, `tsx`, `node --experimental-strip-types`,\n * a bundler's dev server, and fails under one that does not. That failure comes\n * back as a `Result` naming the file and the requirement rather than as a stack\n * trace, and `tab.config.js` and `tab.config.mjs` are discovered too so a\n * consumer with a plain Node process has a first-class option.\n *\n * Requirements: 23.6, 21.5\n */\n\nimport { existsSync, statSync } from \"node:fs\";\nimport { createRequire } from \"node:module\";\nimport { dirname, isAbsolute, resolve as resolvePath } from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\nimport { causeOf, ok, wrap, wrapSync, type Result } from \"../_shared/index.js\";\nimport { defaultLogger, type Logger } from \"../logger.js\";\nimport { notFoundError, validationError } from \"../errors.js\";\nimport { validatePaymentStrategy, type PaymentStrategy } from \"./strategy.js\";\nimport type { X402SignerFactory } from \"../x402/client.js\";\nimport {\n  moduleStrategyRegistry,\n  type StrategyRegistration,\n  type StrategyRegistry,\n} from \"./registry.js\";\n\n/**\n * A factory in a config file, so a strategy that needs a signer can be built lazily.\n *\n * Returning `undefined` is a supported answer and means \"not available in this\n * environment\". That is what keeps every read on this rail keyless: the whole\n * point of a factory rather than an object is that a config file can declare a\n * strategy that only exists once a signing key does, and `tab_discover`,\n * `tab_status` and `doctor` never need one. A declining factory is skipped, and\n * the rest of the config - the Agent, the registry URL, the Service endpoints -\n * is kept.\n */\nexport type PaymentStrategyFactory = () =>\n  | PaymentStrategy\n  | undefined\n  | Promise<PaymentStrategy | undefined>;\n\n/** A module specifier, a ready strategy, or a factory returning one. */\nexport type TabConfigStrategyEntry = string | PaymentStrategy | PaymentStrategyFactory;\n\n/**\n * One Service's off-chain coordinates.\n *\n * The chain records who operates a Service, what its tools cost and where it\n * collects Settlements. It records no URL, deliberately: an endpoint moves, and\n * a registry that pinned one would either go stale or need a write every time a\n * Service redeployed. So the endpoint is configuration, and this is where a\n * consumer states it.\n *\n * Without an entry here, `tab_discover` reports the Service with a null endpoint\n * and `tab_call` refuses it by name rather than inventing a URL.\n */\nexport interface TabServiceEntry {\n  /** The Service's 32-byte registry key, as `tab_discover` reports it. */\n  readonly serviceId: string;\n  /** A label for a person. Defaults to the ascii the serviceId decodes to. */\n  readonly name?: string;\n  /** Absolute base URL `tab_call` sends requests to. */\n  readonly endpoint: string;\n  /**\n   * The API Hub provider this Service fronts, if it fronts one.\n   *\n   * With this set, `tab_discover` fetches the provider's manifest and lists its\n   * endpoints under the Service as the tools they are, each reachable through\n   * the Service's `/hub/<prefix>` mount and metered onto the Agent's Open Tab.\n   */\n  readonly hub?: TabServiceHubEntry;\n  /**\n   * Headers sent with every call to this Service.\n   *\n   * A record for a Service that gates on something fixed, such as an API key. A\n   * function for one that gates on something per request: the reference metering\n   * gateway, for instance, requires a claim over the method, the path, the Agent\n   * and the tool, which no static header can satisfy. Tab defines neither scheme\n   * and validates neither -- this is the seam through which a Service's own\n   * access control stays the Service's own.\n   *\n   * Never a Tab credential. The Tab identity headers are added by the 402 client\n   * and nothing in Tab authenticates an Agent with a bearer token.\n   */\n  readonly headers?: Readonly<Record<string, string>> | ServiceHeaderProvider;\n}\n\n/** An API Hub provider fronted by a Service. See {@link TabServiceEntry.hub}. */\nexport interface TabServiceHubEntry {\n  /** The Hub's provider slug, for example `weather-underground`. */\n  readonly provider: string;\n  /** The mount under the Service endpoint. Defaults to the provider slug, so `/hub/<provider>`. */\n  readonly prefix?: string;\n  /** Overrides the manifest URL, for a mirror or a test. */\n  readonly manifestUrl?: string;\n}\n\n/** Builds the per-request headers one Service requires. See {@link TabServiceEntry.headers}. */\nexport type ServiceHeaderProvider = (\n  request: ServiceHeaderRequest,\n) => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;\n\n/** What the provider is told about the call it is producing headers for. */\nexport interface ServiceHeaderRequest {\n  readonly method: string;\n  /** The absolute URL the request is going to. */\n  readonly url: string;\n  /** The tool name as the caller gave it, before it is packed into a 32-byte key. */\n  readonly tool: string;\n  /** The Agent the call is metered against. */\n  readonly agent: string;\n  readonly serviceId: string;\n}\n\nexport interface TabConfig {\n  readonly strategies?: readonly TabConfigStrategyEntry[];\n  /**\n   * The Agent's Monad address: whose Open Tab a metered call lands on.\n   *\n   * An address and never a key. Nothing in this package derives an address from\n   * a private key, because doing so would mean a config file that holds one.\n   */\n  readonly agent?: string;\n  /** Absolute base URL of the Tab registry read API, which serves discovery and status. */\n  readonly registryUrl?: string;\n  /** Where each Service can be reached. See {@link TabServiceEntry}. */\n  readonly services?: readonly TabServiceEntry[];\n  /**\n   * The x402 signer, for the prepaid fallback.\n   *\n   * A factory and only a factory, for the reason `strategies` holds factories:\n   * a signer is built from a key, and a config file must be loadable by the\n   * three surfaces that hold none. Nothing calls this until a Service has\n   * refused a call on credit and offered x402 for it, and a factory returning\n   * `undefined` declines, which leaves that refusal the `LIMIT_EXCEEDED` it was.\n   */\n  readonly x402?: X402SignerFactory;\n}\n\n/**\n * Types a config file's default export. Identity at runtime, its whole job is to\n * make a typo in the config a compile error in the consumer's editor.\n */\nexport const defineTabConfig = (config: TabConfig): TabConfig => config;\n\n/**\n * The file names discovery looks for, in order. `.ts` first because it is the\n * documented form and the one that type-checks; the plain-JavaScript forms follow\n * so a consumer whose runtime strips no types is not shut out.\n */\nexport const TAB_CONFIG_FILE_NAMES = [\n  \"tab.config.ts\",\n  \"tab.config.mts\",\n  \"tab.config.mjs\",\n  \"tab.config.js\",\n  \"tab.config.cjs\",\n] as const;\n\nexport interface FindTabConfigOptions {\n  /** Where the walk starts. Defaults to the working directory. */\n  readonly cwd?: string;\n  readonly fileNames?: readonly string[];\n}\n\n/**\n * Walks from `cwd` towards the filesystem root and returns the first config file\n * found, or `undefined` when there is none.\n *\n * Absence is not an error: the whole point of the mechanism is that a consumer\n * who wants nothing from it writes nothing.\n */\nexport function findTabConfig(options: FindTabConfigOptions = {}): Result<string | undefined> {\n  return wrapSync(\n    () => {\n      const fileNames = options.fileNames ?? TAB_CONFIG_FILE_NAMES;\n      let directory = resolvePath(options.cwd ?? \".\");\n      for (;;) {\n        for (const fileName of fileNames) {\n          const candidate = resolvePath(directory, fileName);\n          if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;\n        }\n        const parent = dirname(directory);\n        if (parent === directory) return undefined;\n        directory = parent;\n      }\n    },\n    (error) => ({\n      category: \"INTERNAL\",\n      code: \"CONFIG_SEARCH_FAILED\",\n      message: \"the tab.config search could not read the filesystem\",\n      retryable: false,\n      cause: causeOf(error),\n    }),\n  );\n}\n\nexport interface LoadTabConfigOptions extends FindTabConfigOptions {\n  /** An explicit config file. Absolute, or relative to `cwd`. Missing is an error. */\n  readonly configPath?: string;\n  /**\n   * Where the discovered strategies are registered. Omitted means the\n   * module-level registry, which is what makes the mechanism zero-code; `false`\n   * loads and validates without registering anything.\n   */\n  readonly registry?: StrategyRegistry | false;\n  readonly logger?: Logger;\n}\n\nexport interface LoadedTabConfig {\n  /** The file that was loaded, or `undefined` when none was found. */\n  readonly path: string | undefined;\n  readonly config: TabConfig;\n  readonly strategies: readonly PaymentStrategy[];\n  /** Empty when `registry` was `false`. */\n  readonly registrations: readonly StrategyRegistration[];\n}\n\nconst EMPTY_CONFIG: TabConfig = {};\n\n/**\n * Loads a config file, resolves every strategy entry, and registers the result.\n *\n * Returns a `Result` for every failure, including a config file that throws on\n * import: a consumer's config is consumer code, and this package does not turn\n * their mistake into an unhandled rejection.\n */\nexport async function loadTabConfig(\n  options: LoadTabConfigOptions = {},\n): Promise<Result<LoadedTabConfig>> {\n  const logger = options.logger ?? defaultLogger;\n\n  const located = locateConfig(options);\n  if (!located.ok) return located;\n  const path = located.value;\n\n  if (path === undefined) {\n    return ok({ path: undefined, config: EMPTY_CONFIG, strategies: [], registrations: [] });\n  }\n\n  const imported = await importModule(path, `tab config \\`${path}\\``);\n  if (!imported.ok) return imported;\n\n  const config = readDefaultExport(imported.value, path);\n  if (!config.ok) return config;\n\n  const strategies: PaymentStrategy[] = [];\n  let declined = 0;\n  for (const [index, entry] of (config.value.strategies ?? []).entries()) {\n    const resolved = await resolveEntry(entry, index, path);\n    if (!resolved.ok) return resolved;\n    // `undefined` is the factory declining, not a fault. Skip it and keep going.\n    if (resolved.value === undefined) {\n      declined += 1;\n      continue;\n    }\n    strategies.push(resolved.value);\n  }\n\n  const registrations: StrategyRegistration[] = [];\n  if (options.registry !== false) {\n    const registry = options.registry ?? moduleStrategyRegistry(logger);\n    for (const strategy of strategies) {\n      const outcome = registry.register(strategy);\n      if (!outcome.ok) return outcome;\n      registrations.push(outcome.value);\n    }\n  }\n\n  logger.debug(\"tab config loaded\", { path, strategies: strategies.length, declined });\n  return ok({ path, config: config.value, strategies, registrations });\n}\n\nfunction locateConfig(options: LoadTabConfigOptions): Result<string | undefined> {\n  if (options.configPath === undefined) return findTabConfig(options);\n\n  const cwd = resolvePath(options.cwd ?? \".\");\n  const path = isAbsolute(options.configPath)\n    ? options.configPath\n    : resolvePath(cwd, options.configPath);\n  if (!existsSync(path)) {\n    return notFoundError(\"CONFIG_NOT_FOUND\", `no tab config file at \\`${path}\\``, {\n      details: { path },\n    });\n  }\n  return ok(path);\n}\n\n/** Imports a file by path. A `.ts` file needs a type-stripping runtime, so say so. */\nasync function importModule(path: string, label: string): Promise<Result<Record<string, unknown>>> {\n  const href = pathToFileURL(path).href;\n  return wrap(\n    async () => (await import(href)) as Record<string, unknown>,\n    (error) => ({\n      category: \"UPSTREAM\",\n      code: \"CONFIG_IMPORT_FAILED\",\n      message: path.endsWith(\".ts\") || path.endsWith(\".mts\")\n        ? `${label} could not be imported; a TypeScript config file needs a runtime that strips types, or use tab.config.mjs`\n        : `${label} could not be imported`,\n      retryable: false,\n      details: { path },\n      cause: causeOf(error),\n    }),\n  );\n}\n\nfunction readDefaultExport(module: Record<string, unknown>, path: string): Result<TabConfig> {\n  const exported = module[\"default\"];\n  if (exported === undefined) {\n    return validationError(\n      \"CONFIG_NO_DEFAULT_EXPORT\",\n      `\\`${path}\\` must default-export a config, for example \\`export default defineTabConfig({ strategies: [] })\\``,\n      { details: { path } },\n    );\n  }\n  if (typeof exported !== \"object\" || exported === null) {\n    return validationError(\n      \"CONFIG_INVALID\",\n      `the default export of \\`${path}\\` must be an object`,\n      { details: { path } },\n    );\n  }\n  const candidate = exported as { strategies?: unknown; services?: unknown; x402?: unknown };\n  if (candidate.x402 !== undefined && typeof candidate.x402 !== \"function\") {\n    return validationError(\n      \"CONFIG_INVALID\",\n      `\\`${path}\\` declares \\`x402\\` but it is not a factory; it must be a function returning a signer or undefined, so the file holds no key`,\n      { details: { path } },\n    );\n  }\n  if (candidate.strategies !== undefined && !Array.isArray(candidate.strategies)) {\n    return validationError(\n      \"CONFIG_INVALID\",\n      `\\`${path}\\` declares \\`strategies\\` but it is not an array`,\n      { details: { path } },\n    );\n  }\n  if (candidate.services !== undefined && !Array.isArray(candidate.services)) {\n    return validationError(\n      \"CONFIG_INVALID\",\n      `\\`${path}\\` declares \\`services\\` but it is not an array`,\n      { details: { path } },\n    );\n  }\n  return ok(exported as TabConfig);\n}\n\nasync function resolveEntry(\n  entry: TabConfigStrategyEntry,\n  index: number,\n  configPath: string,\n): Promise<Result<PaymentStrategy | undefined>> {\n  const label = `strategies[${index}] of \\`${configPath}\\``;\n\n  if (typeof entry === \"string\") {\n    const module = await importSpecifier(entry, configPath);\n    if (!module.ok) return module;\n    const exported = module.value[\"default\"];\n    if (exported === undefined) {\n      return validationError(\n        \"STRATEGY_MODULE_INVALID\",\n        `${label}: \\`${entry}\\` must default-export a PaymentStrategy or a factory returning one`,\n        { details: { specifier: entry } },\n      );\n    }\n    return callIfFactory(exported, `${label} (\\`${entry}\\`)`);\n  }\n\n  return callIfFactory(entry, label);\n}\n\n/**\n * A strategy is an object and a factory is a function, so `typeof` separates them.\n *\n * A factory returning `undefined` is passed straight back as `undefined` rather\n * than sent to the validator, because declining is one of the two answers a\n * factory is allowed to give. A bare `undefined` written directly in the array\n * is still invalid, and still reaches the validator: that is a typo rather than\n * a decision, and nothing about it says a key was missing.\n */\nasync function callIfFactory(\n  value: unknown,\n  label: string,\n): Promise<Result<PaymentStrategy | undefined>> {\n  if (typeof value !== \"function\") return validatePaymentStrategy(value, label);\n\n  const produced = await wrap(\n    async () => (await (value as PaymentStrategyFactory)()) as unknown,\n    (error) => ({\n      category: \"UPSTREAM\",\n      code: \"STRATEGY_FACTORY_FAILED\",\n      message: `${label}: the strategy factory threw`,\n      retryable: false,\n      cause: causeOf(error),\n    }),\n  );\n  if (!produced.ok) return produced;\n  if (produced.value === undefined || produced.value === null) return ok(undefined);\n  return validatePaymentStrategy(produced.value, label);\n}\n\n/**\n * Resolves a bare or relative specifier the way the consumer's own `import`\n * would: from the config file. Falls back to a plain dynamic import, which covers\n * a package the CommonJS resolver cannot see through its `exports` conditions.\n */\nasync function importSpecifier(\n  specifier: string,\n  configPath: string,\n): Promise<Result<Record<string, unknown>>> {\n  const fromConfig = wrapSync(\n    () => createRequire(pathToFileURL(configPath)).resolve(specifier),\n    (error) => ({\n      category: \"NOT_FOUND\",\n      code: \"STRATEGY_MODULE_NOT_FOUND\",\n      message: `\\`${specifier}\\` could not be resolved from \\`${configPath}\\``,\n      retryable: false,\n      details: { specifier, configPath },\n      cause: causeOf(error),\n    }),\n  );\n\n  if (fromConfig.ok) {\n    return importModule(fromConfig.value, `strategy module \\`${specifier}\\``);\n  }\n\n  return wrap(\n    async () => (await import(specifier)) as Record<string, unknown>,\n    (error) => ({\n      category: \"NOT_FOUND\",\n      code: \"STRATEGY_MODULE_NOT_FOUND\",\n      message: `\\`${specifier}\\` could not be imported from \\`${configPath}\\` or resolved as a bare module`,\n      retryable: false,\n      details: { specifier, configPath },\n      cause: causeOf(error),\n    }),\n  );\n}\n"]}

package/dist/payments/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The payment-strategy seam, assembled.
+ *
+ * Requirements: 23.1, 23.6, 23.7
+ */
+export * from "./strategy.js";
+export * from "./registry.js";
+export * from "./config.js";
+export * from "./abi.js";
+export * from "./monad.js";
+export * from "./kuru.js";
+export * from "./permit2.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/payments/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/payments/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC"}

package/dist/payments/index.js

@@ -0,0 +1,13 @@
+/**
+ * The payment-strategy seam, assembled.
+ *
+ * Requirements: 23.1, 23.6, 23.7
+ */
+export * from "./strategy.js";
+export * from "./registry.js";
+export * from "./config.js";
+export * from "./abi.js";
+export * from "./monad.js";
+export * from "./kuru.js";
+export * from "./permit2.js";
+//# sourceMappingURL=index.js.map

package/dist/payments/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/payments/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC","sourcesContent":["/**\n * The payment-strategy seam, assembled.\n *\n * Requirements: 23.1, 23.6, 23.7\n */\n\nexport * from \"./strategy.js\";\nexport * from \"./registry.js\";\nexport * from \"./config.js\";\nexport * from \"./abi.js\";\nexport * from \"./monad.js\";\nexport * from \"./kuru.js\";\nexport * from \"./permit2.js\";\n"]}

package/dist/payments/kuru.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Settle in any asset through Kuru: a strategy that tops the Agent's balance of
+ * the Asset up from another token before delegating the Settlement.
+ *
+ * ## What it does
+ *
+ * `TabSettlement.settle` moves the Asset the tab is denominated in, and an
+ * Agent that holds MON, or a different stablecoin, cannot settle until it holds
+ * enough of that Asset. {@link createKuruFundedStrategy} wraps the Monad
+ * strategy: before every `settle` it reads the Agent's balance of the Asset,
+ * and when it is short, swaps the shortfall in from a configured source token
+ * through Kuru, Monad's on-chain order book, and only then settles. The
+ * Settlement itself is still the inner strategy's transaction, so the receipt,
+ * the `Settled` event and the atomic apply are unchanged.
+ *
+ * ## The swap is a seam
+ *
+ * The swap runs through a {@link KuruRouter}: `quote` says how much of the
+ * source token buys the shortfall, `swap` executes it. {@link createKuruOnchainRouter}
+ * is the shipped implementation over Kuru's `Router.anyToAnySwap`, which is
+ * the same entry point on Testnet and Mainnet, driven with a configured route
+ * of market addresses. A test hands in a fake router and exercises the whole
+ * decision without a chain.
+ *
+ * ## Why not Kuru's own SDK or its aggregator API
+ *
+ * `@kuru-labs/kuru-sdk` pins ethers 5 and takes swap amounts as floating
+ * point numbers, and the Kuru Flow aggregator API (`ws.kuru.io/api/quote`)
+ * needs a bearer token and returns a transaction in a shape the docs do not
+ * define. Amounts here are `bigint` base units end to end, so the router talks
+ * to the contract directly, with the amounts it was given.
+ *
+ * ## Amounts
+ *
+ * `amountOut` is the exact shortfall and is passed as the swap's minimum, so
+ * the Settlement is either fully funded or the swap reverts. `amountIn` is a
+ * ceiling: the on-chain router quotes by simulation at that ceiling, and the
+ * Agent's slippage tolerance sets how much above the quoted price it will pay.
+ * Anything the swap returns above the shortfall stays in the Agent's balance.
+ */
+import { type Address, type Hex, type Result } from "../_shared/index.js";
+import { type Logger } from "../logger.js";
+import type { EthersV6Signer } from "./monad.js";
+import { type AssetRef, type PaymentStrategy } from "./strategy.js";
+/** The address Kuru's router reads as the native token, MON. */
+export declare const KURU_NATIVE_TOKEN: Address;
+/** Kuru's deployments, from its Contract Addresses page. The Router is what `anyToAnySwap` lives on. */
+export declare const KURU_DEPLOYMENTS: {
+    readonly mainnet: {
+        readonly chainId: 143n;
+        readonly router: Address;
+        readonly marginAccount: Address;
+        /** The aggregator entry point. Mainnet only: the docs list none for Testnet. */
+        readonly flowEntrypoint: Address;
+        readonly wmon: Address;
+        readonly markets: {
+            readonly "MON-USDC": Address;
+            readonly "MON-AUSD": Address;
+        };
+    };
+    readonly testnet: {
+        readonly chainId: 10143n;
+        readonly router: Address;
+        readonly marginAccount: Address;
+        /** Kuru's own test USDC on Testnet, which is not Tab's `MockUsdc`. */
+        readonly usdc: Address;
+    };
+};
+/** The source token a swap draws from. `address` is {@link KURU_NATIVE_TOKEN} for MON. */
+export interface KuruSourceToken {
+    readonly address: Address;
+    readonly decimals: number;
+    readonly symbol: string;
+}
+/** What the router is asked for. */
+export interface KuruSwapRequest {
+    readonly chainId: bigint;
+    readonly tokenIn: Address;
+    readonly tokenOut: Address;
+    /** The exact shortfall in `tokenOut` base units. The swap must return at least this. */
+    readonly amountOut: bigint;
+    /** The most `tokenIn` the caller will spend. */
+    readonly maxAmountIn: bigint;
+    /** Where the output lands. The Agent, always. */
+    readonly recipient: Address;
+}
+export interface KuruQuote {
+    readonly request: KuruSwapRequest;
+    /** How much `tokenIn` the swap will be sent with. At most `request.maxAmountIn`. */
+    readonly amountIn: bigint;
+    /** What the router expects back. At least `request.amountOut`. */
+    readonly expectedOut: bigint;
+}
+export interface KuruSwapReceipt {
+    readonly txHash: Hex;
+    readonly amountIn: bigint;
+    /** What the swap returned, when the router could read it; the quote's expectation otherwise. */
+    readonly amountOut: bigint;
+}
+/** The swap seam. Both methods return a `Result`, never throw. */
+export interface KuruRouter {
+    quote(request: KuruSwapRequest): Promise<Result<KuruQuote>>;
+    swap(quote: KuruQuote): Promise<Result<KuruSwapReceipt>>;
+}
+export interface KuruConfig {
+    readonly router: KuruRouter;
+    readonly source: KuruSourceToken;
+    /**
+     * Reads the Agent's balance of an Asset. Defaults to `balanceOf` through the
+     * inner signer's provider when `signer` is given; required otherwise.
+     */
+    readonly balanceOf?: (asset: AssetRef, owner: Address) => Promise<Result<bigint>>;
+    /** The most of the source token one Settlement may spend. Omitted sets no ceiling. */
+    readonly maxSourceAmount?: bigint;
+    /** Called with every swap that funded a Settlement. */
+    readonly onFunded?: (event: KuruFundingEvent) => void;
+}
+/** One top-up, as reported after the Settlement it funded. */
+export interface KuruFundingEvent {
+    readonly agent: Address;
+    readonly asset: AssetRef;
+    readonly balanceBefore: bigint;
+    readonly shortfall: bigint;
+    readonly quote: KuruQuote;
+    readonly swap: KuruSwapReceipt;
+}
+export interface KuruFundedStrategyConfig {
+    /** The strategy that settles once the balance is there. The Monad strategy, ordinarily. */
+    readonly inner: PaymentStrategy;
+    readonly kuru: KuruConfig;
+    /**
+     * The Agent's signer, for the default `balanceOf`. Its `provider` is what the
+     * balance is read through. Not needed when `kuru.balanceOf` is supplied.
+     */
+    readonly signer?: EthersV6Signer;
+    readonly id?: string;
+    readonly logger?: Logger;
+}
+/**
+ * Builds the funded strategy. Construction is total.
+ *
+ * `supports`, `chainIds` and `quote` are the inner strategy's, so registering
+ * this in place of it changes nothing about which Assets resolve to it.
+ */
+export declare function createKuruFundedStrategy(config: KuruFundedStrategyConfig): PaymentStrategy;
+/** Kuru's `Router.anyToAnySwap`, the multi-hop swap entry point. */
+export declare const KURU_ROUTER_ABI: readonly ["function anyToAnySwap(address[] _marketAddresses, bool[] _isBuy, bool[] _nativeSend, address _debitToken, address _creditToken, uint256 _amount, uint256 _minAmountOut) payable returns (uint256 _amountOut)"];
+/**
+ * One route through Kuru's markets, as `anyToAnySwap` takes it.
+ *
+ * Every array is per hop. `isBuy` says whether the hop buys the market's base
+ * with its quote, `nativeSend` whether the hop is paid in MON. The MON-USDC
+ * market on Mainnet, selling MON for USDC, is one hop: `{ markets: [MON_USDC],
+ * isBuy: [false], nativeSend: [true] }`.
+ */
+export interface KuruRoute {
+    readonly markets: readonly Address[];
+    readonly isBuy: readonly boolean[];
+    readonly nativeSend: readonly boolean[];
+}
+/** What the on-chain router needs of a signer: a call for the quote, a send for the swap. An `ethers.Signer` satisfies it. */
+export type KuruSigner = EthersV6Signer;
+export interface KuruOnchainRouterOptions {
+    readonly signer: KuruSigner;
+    /** Kuru's Router on the chain the signer is on. */
+    readonly router: Address;
+    /** Routes keyed by `${tokenIn}->${tokenOut}`, lower-cased. */
+    readonly routes: Readonly<Record<string, KuruRoute>>;
+    /** How far above the simulated price the swap may pay. Defaults to 100, one percent. */
+    readonly slippageBps?: number;
+    /**
+     * The `tokenIn` amount the price is probed at. Defaults to `maxAmountIn`.
+     * Probing at the size to be swapped keeps the quote honest about depth.
+     */
+    readonly probeAmountIn?: bigint;
+    readonly logger?: Logger;
+}
+/** The key `routes` is looked up by. */
+export declare const kuruRouteKey: (tokenIn: string, tokenOut: string) => string;
+/**
+ * A router over `anyToAnySwap`.
+ *
+ * Quoting is a simulation: the swap is `eth_call`ed at a probe size, the
+ * price it implies is scaled to the shortfall, and the slippage margin is
+ * added. Two probes at most, the second at the computed size, so the quote is
+ * checked at the amount that will be sent. The swap is then sent with the
+ * shortfall as `_minAmountOut`, which is what makes over-quoting harmless and
+ * under-quoting a revert rather than a short Settlement.
+ */
+export declare function createKuruOnchainRouter(options: KuruOnchainRouterOptions): KuruRouter;
+//# sourceMappingURL=kuru.d.ts.map

package/dist/payments/kuru.d.ts.map

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