tapimo 0.1.0 → 0.3.0

package/dist/apps/relay/App.js

@@ -0,0 +1,211 @@
+import { Hono } from 'hono';
+import { createMiddleware } from 'hono/factory';
+import { RpcResponse } from 'ox';
+import { Addresses, TokenId, Transaction } from 'viem/tempo';
+import * as BillingSettings from '../../db/tables/billingSettings.js';
+import * as Db from '../../db/Db.js';
+import * as Fees from '../../internal/Fees.js';
+import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js';
+import * as Billing from '../platform/Billing.js';
+import * as Handler from '../../Handler.js';
+import * as Auth from '../../internal/Auth.js';
+import * as OpenApi from '../../internal/OpenApi.js';
+import * as Path from '../../internal/Path.js';
+import * as VerifiedTokens from '../../internal/VerifiedTokens.js';
+import * as Viem from '../../internal/Viem.js';
+import * as Scope from '../../Scope.js';
+/**
+ * The relay route group: the wallet relay at `/rpc/relay`. Mount
+ * after `data()`, whose published chain clients and supported-chain set the
+ * middleware reads from request context.
+ *
+ * ```ts
+ * App.create(options).route('/', data()).route('/', relay())
+ * ```
+ */
+export function relay(options = {}) {
+    const handler = middleware(options);
+    return new Hono()
+        .use('/rpc/relay', Auth.policy({ apiKey: { scopes: ['rpc-relay:read'] }, mpp: false, public: false }), OpenApi.describeRoute({ hide: true, summary: 'Relay RPC' }))
+        .use('/rpc/relay/*', Auth.policy({ apiKey: { scopes: ['rpc-relay:read'] }, mpp: false, public: false }), OpenApi.describeRoute({ hide: true, summary: 'Relay RPC' }))
+        .all('/rpc/relay', handler)
+        .all('/rpc/relay/:chainId', handler);
+}
+// The wallet relay middleware: proxies wallet JSON-RPC (fills, sponsored
+// sends) with wallet-aware enrichment. Built per request from context rather
+// than closed over group locals; relay traffic is low-QPS and the viem
+// clients are memoized upstream, so per-request handler construction is cheap.
+function middleware(options = {}) {
+    // Platform-wide per-transaction cap; org settings tighten it, never loosen.
+    const txFeeLimit = options.feePayer
+        ? Billing.toBaseUnits(options.feePayer.txFeeLimit ?? '1.00')
+        : 0n;
+    return createMiddleware(async (c) => {
+        const verifiedTokens = c.get('verifiedTokens');
+        const feePayer = (() => {
+            if (!options.feePayer)
+                return undefined;
+            const principal = Auth.getPrincipal(c);
+            const attribution = principal?.type === 'api_key' && principal.projectId !== undefined
+                ? {
+                    apiKeyId: principal.id,
+                    environment: principal.environment,
+                    orgId: principal.orgId,
+                    projectId: principal.projectId,
+                }
+                : undefined;
+            const sponsorable = attribution !== undefined &&
+                principal?.type === 'api_key' &&
+                (principal.apiKey.scopes.includes('rpc-relay:sponsor') ||
+                    principal.apiKey.scopes.includes(Scope.wildcard));
+            // Lifted so validation and the sponsored-token default read one value.
+            const feeToken_sponsor = options.feePayer.feeToken ?? Addresses.pathUsd;
+            return {
+                ...options.feePayer,
+                feeToken: feeToken_sponsor,
+                validate: async (transaction) => {
+                    // Allowlist the chains this deployment serves rather than denylisting
+                    // only mainnet: the relay resolves chainId from the request body, so
+                    // the query-string chain guard never sees it.
+                    const id = Number(transaction.chainId);
+                    if (!attribution || !sponsorable || !c.get('supportedChainIds').has(id))
+                        return false;
+                    if (!Viem.isMainnet(id))
+                        return true;
+                    // Mainnet is production-only: a sandbox key resolves chainId from the
+                    // request body, so the auth-layer sandbox/mainnet guard never sees
+                    // it. Refuse here, or sandbox spend would sponsor mainnet unbilled.
+                    if (attribution.environment !== 'production')
+                        return false;
+                    // Enforcement reads hit the primary, never the cached replica: a
+                    // stale `past_due`, a lowered limit, or another isolate's pending
+                    // spend must not keep the gate open.
+                    const db = Db.get(c.get('db'));
+                    // Mainnet sponsorship requires an active billing source; deployments
+                    // without billing configured have no rows, so mainnet stays closed.
+                    // `past_due` gets its own reason: the caller must settle an invoice,
+                    // not attach a card.
+                    const billing = await Billing.status(db, attribution.orgId);
+                    if (billing === 'past_due')
+                        return 'billing_past_due';
+                    if (billing !== 'active')
+                        return 'billing_required';
+                    const feeToken = (() => {
+                        try {
+                            return TokenId.toAddress(transaction.feeToken ?? feeToken_sponsor);
+                        }
+                        catch {
+                            return undefined;
+                        }
+                    })();
+                    const verified = feeToken
+                        ? (await VerifiedTokens.read(Db.get(c.get('dbCached')), id))?.byAddress.get(feeToken.toLowerCase()) // prettier-ignore
+                        : undefined;
+                    if (!verified ||
+                        verified.currency.toLowerCase() !== 'usd' ||
+                        verified.decimals !== Fees.tokenDecimals)
+                        // prettier-ignore
+                        return 'fee_token_unsupported';
+                    // Fail closed: a transaction whose signed cap cannot be computed
+                    // cannot be bounded, so it never sponsors on mainnet.
+                    const feeMax = Fees.maxOf(transaction);
+                    if (feeMax === undefined)
+                        return 'tx_fee_limit_exceeded';
+                    const settings = await BillingSettings.get(db, attribution.orgId);
+                    const cap = (() => {
+                        if (settings?.txFeeLimit == null)
+                            return txFeeLimit;
+                        const org = Billing.toBaseUnits(settings.txFeeLimit);
+                        return org < txFeeLimit ? org : txFeeLimit;
+                    })();
+                    if (feeMax > cap)
+                        return 'tx_fee_limit_exceeded';
+                    // The period spend limit is enforced atomically at recording time
+                    // (`onSponsored` → `SponsoredTransactions.reserve`); a check here
+                    // would be a check-then-act race a burst could slip through.
+                    return true;
+                },
+                onSponsored: async (event) => {
+                    if (!attribution)
+                        return;
+                    const mainnet = Viem.isMainnet(event.chainId);
+                    // Defense in depth: `validate` already refuses non-production
+                    // mainnet, so reaching here with that pair is a wiring bug.
+                    if (mainnet && attribution.environment !== 'production')
+                        throw new RpcResponse.InvalidParamsError({ message: 'Sponsorship rejected.' });
+                    // The cap recomputes from canonical envelope bytes, mirroring the
+                    // reconciliation convention; pending rows charge it to spend limits.
+                    const feeMax = Fees.maxOf(Transaction.deserialize(event.transaction));
+                    const db = Db.get(c.get('db'));
+                    const feeToken = (() => {
+                        try {
+                            return event.feeToken !== undefined ? TokenId.toAddress(event.feeToken) : undefined;
+                        }
+                        catch {
+                            return undefined;
+                        }
+                    })();
+                    const currency = feeToken
+                        ? (await VerifiedTokens.read(Db.get(c.get('dbCached')), event.chainId))?.byAddress
+                            .get(feeToken.toLowerCase())
+                            ?.currency.toLowerCase()
+                        : undefined;
+                    const input = {
+                        apiKeyId: attribution.apiKeyId,
+                        billable: attribution.environment === 'production',
+                        chainId: event.chainId,
+                        environment: attribution.environment,
+                        orgId: attribution.orgId,
+                        projectId: attribution.projectId,
+                        signPayload: event.signPayload,
+                        transaction: event.transaction,
+                        ...(currency ? { currency } : {}),
+                        ...(feeMax !== undefined ? { feeMax: feeMax.toString() } : {}),
+                        ...(feeToken ? { feeToken } : {}),
+                        ...(event.transactionHash ? { transactionHash: event.transactionHash } : {}),
+                    };
+                    // Re-read settings on the authoritative path: the limit may have
+                    // changed since `validate`, and only mainnet spend is limited.
+                    const settings = mainnet ? await BillingSettings.get(db, attribution.orgId) : undefined;
+                    if (settings?.spendLimit == null)
+                        return void (await SponsoredTransactions.upsert(db, input)); // prettier-ignore
+                    try {
+                        await SponsoredTransactions.reserve(db, input, {
+                            chainIds: [Viem.chainId.mainnet],
+                            max: Billing.toBaseUnits(settings.spendLimit),
+                            since: Billing.periodStart(settings.period),
+                        });
+                    }
+                    catch (error) {
+                        if (error instanceof SponsoredTransactions.PeriodSpendLimitError)
+                            throw new RpcResponse.InvalidParamsError({
+                                data: { code: 'spend_limit_exceeded' },
+                                message: 'Spend limit exceeded.',
+                            });
+                        throw error;
+                    }
+                },
+            };
+        })();
+        // Dispatching a standalone Hono via `fetch(c.req.raw)` bypasses Hono's
+        // mount-path stripping, so its internal routes register at the request's
+        // full external path (`basePath` + `/rpc/relay`).
+        const handler = Handler.relay({
+            cache: c.get('store'),
+            features: 'all',
+            getClient: (chainId) => c.get('getClient')(chainId),
+            path: Path.join(c.get('basePath'), 'rpc/relay'),
+            ...(feePayer ? { feePayer } : {}),
+            ...(verifiedTokens
+                ? {
+                    resolveTokens: async (chainId) => {
+                        const snapshot = await VerifiedTokens.read(Db.get(c.get('dbCached')), chainId);
+                        return snapshot?.list.map((token) => token.address) ?? [];
+                    },
+                }
+                : {}),
+        });
+        return handler.fetch(c.req.raw);
+    });
+}
+//# sourceMappingURL=App.js.map

package/dist/apps/relay/App.js.map

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

package/dist/apps/relay/Sponsorships.d.ts

@@ -0,0 +1,107 @@
+import { type Address, type Client } from 'viem';
+import * as Db from '../../db/Db.js';
+import * as Tidx from '../../internal/Tidx.js';
+import * as Viem from '../../internal/Viem.js';
+/**
+ * Runs one finalization pass over pending sponsored transactions: rows with a
+ * receipt finalize with the actual fee (`gasUsed × effectiveGasPrice`, in
+ * fee-token base units); rows still unmined past the pending TTL fail, as do
+ * hash-less fill intents the TTL outlives. Rows whose receipt lookup errors
+ * persist past the error TTL fail so they cannot monopolize every batch.
+ *
+ * @param db - The database holding `sponsored_transactions`.
+ * @param options - Finalization options.
+ * @returns Counters for the pass.
+ */
+export declare function finalize(db: Db.Db, options: finalize.Options): Promise<finalize.Result>;
+export declare namespace finalize {
+    /** Options for {@link finalize}. */
+    type Options = {
+        /** Maximum pending rows processed per pass. @default 100 */
+        batchSize?: number | undefined;
+        /** Client resolver keyed by the row's chain id. */
+        getClient: (chainId: number) => Client;
+        /** Clock; injectable for tests. */
+        now?: (() => Date) | undefined;
+        /** Age after which an unmined sponsorship fails. @default 1 hour */
+        pendingTtlMs?: number | undefined;
+        /** Age after which repeated receipt lookup errors fail a row. @default 24 hours */
+        receiptErrorTtlMs?: number | undefined;
+    };
+    /** Counters returned by one finalization pass. */
+    type Result = {
+        /** Rows marked failed (unmined past the pending TTL). */
+        failed: number;
+        /** Rows finalized with an actual fee. */
+        finalized: number;
+        /** Rows left pending (unmined, or receipt lookup errored within the error TTL). */
+        pending: number;
+    };
+}
+/**
+ * Runs one reconciliation pass over pending fill intents (rows with no
+ * transaction hash): fetches the fee payer's recent on-chain transactions
+ * from TIDX, recomputes each candidate's fee-payer sign payload, and fills
+ * matching intents' hashes so the receipt pass can finalize them. Query or
+ * candidate errors leave intents for the next pass.
+ *
+ * @param db - The database holding `sponsored_transactions`.
+ * @param options - Reconciliation options.
+ * @returns Counters for the pass.
+ */
+export declare function reconcile(db: Db.Db, options: reconcile.Options): Promise<reconcile.Result>;
+export declare namespace reconcile {
+    /** Options for {@link reconcile}. */
+    type Options = {
+        /** Maximum intents considered per pass. @default 100 */
+        batchSize?: number | undefined;
+        /** Maximum on-chain candidates fetched per chain per pass. @default 500 */
+        candidateCap?: number | undefined;
+        /** How long failed intents remain reconciliation candidates. @default 24 hours */
+        failedIntentTtlMs?: number | undefined;
+        /** Fee payer address whose on-chain transactions are candidates. */
+        feePayer: Address;
+        /** Client resolver keyed by the intent's chain id. */
+        getClient: (chainId: number) => Client;
+        /** TIDX client resolver keyed by the intent's chain id. */
+        getTidx: (chainId: number) => Tidx.Client;
+        /** Lookback slack before the oldest intent's creation. @default 2 minutes */
+        skewMs?: number | undefined;
+    };
+    /** Counters returned by one reconciliation pass. */
+    type Result = {
+        /** Intents matched to an on-chain transaction. */
+        matched: number;
+        /** On-chain candidates inspected. */
+        scanned: number;
+    };
+}
+/**
+ * Builds a scheduled sponsorship finalizer bound to a database and RPC config.
+ * A host runtime drives {@link createFinalizer.Finalizer.tick} on a timer (a
+ * Cloudflare `scheduled` cron handler, a self-host `setInterval`, …); each
+ * tick reconciles fill intents (when `feePayer` + `tidx` are configured) and
+ * runs one {@link finalize} pass, with memoized per-chain clients.
+ */
+export declare function createFinalizer(options: createFinalizer.Options): createFinalizer.Finalizer;
+export declare namespace createFinalizer {
+    /** Options for {@link createFinalizer}. */
+    type Options = Pick<finalize.Options, 'batchSize' | 'now' | 'pendingTtlMs'> & {
+        /** Database holding sponsorship rows, or a factory resolved per tick (Workers/Hyperdrive). */
+        db: Db.Source;
+        /** Default chain id for the TIDX client resolver. */
+        defaultChainId?: Viem.ChainId | undefined;
+        /** Fee payer address whose on-chain transactions reconcile fill intents; omit to skip reconciliation. */
+        feePayer?: Address | undefined;
+        /** RPC options for the receipt-lookup clients. */
+        rpc?: Viem.getClient.Rpc | undefined;
+        /** TIDX query client options for intent reconciliation; omit to skip reconciliation. */
+        tidx?: Tidx.getClient.Tidx | undefined;
+    };
+    /** A scheduled sponsorship finalizer. */
+    type Finalizer = {
+        /** Runs one reconcile + finalize pass. */
+        tick(): Promise<finalize.Result & reconcile.Result>;
+    };
+}
+//# sourceMappingURL=Sponsorships.d.ts.map

package/dist/apps/relay/Sponsorships.d.ts.map

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

package/dist/apps/relay/Sponsorships.js

@@ -0,0 +1,194 @@
+import { TxEnvelopeTempo } from 'ox/tempo';
+import { TransactionReceiptNotFoundError, } from 'viem';
+import { getTransactionReceipt } from 'viem/actions';
+import * as Db from '../../db/Db.js';
+import * as Fees from '../../internal/Fees.js';
+import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js';
+import * as Tidx from '../../internal/Tidx.js';
+import * as Viem from '../../internal/Viem.js';
+/**
+ * Runs one finalization pass over pending sponsored transactions: rows with a
+ * receipt finalize with the actual fee (`gasUsed × effectiveGasPrice`, in
+ * fee-token base units); rows still unmined past the pending TTL fail, as do
+ * hash-less fill intents the TTL outlives. Rows whose receipt lookup errors
+ * persist past the error TTL fail so they cannot monopolize every batch.
+ *
+ * @param db - The database holding `sponsored_transactions`.
+ * @param options - Finalization options.
+ * @returns Counters for the pass.
+ */
+export async function finalize(db, options) {
+    const { batchSize = 100, getClient, now = () => new Date(), pendingTtlMs = 3_600_000, receiptErrorTtlMs = 86_400_000, } = options;
+    const rows = await SponsoredTransactions.listPending(db, { limit: batchSize });
+    const result = { failed: 0, finalized: 0, pending: 0 };
+    for (const row of rows) {
+        // Fill intents carry no hash until reconciliation matches them on-chain;
+        // here only the TTL can settle them.
+        if (row.transactionHash === null) {
+            if (Date.parse(row.createdAt) + pendingTtlMs <= now().getTime()) {
+                await SponsoredTransactions.fail(db, row.id, now().toISOString());
+                result.failed++;
+            }
+            else
+                result.pending++;
+            continue;
+        }
+        let receipt;
+        try {
+            receipt = await getTransactionReceipt(getClient(row.chainId), {
+                hash: row.transactionHash,
+            });
+        }
+        catch (error) {
+            // Unmined transactions surface as a typed not-found; let the TTL decide.
+            if (error instanceof TransactionReceiptNotFoundError)
+                receipt = null;
+            else {
+                if (Date.parse(row.createdAt) + receiptErrorTtlMs <= now().getTime()) {
+                    await SponsoredTransactions.fail(db, row.id, now().toISOString());
+                    result.failed++;
+                }
+                else
+                    result.pending++;
+                continue;
+            }
+        }
+        if (receipt) {
+            // A reverted transaction still finalizes: the fee payer paid its fees.
+            const feeAmount = Fees.fromGas(receipt.gasUsed, receipt.effectiveGasPrice);
+            await SponsoredTransactions.finalize(db, row.id, {
+                feeAmount: feeAmount.toString(),
+                finalizedAt: now().toISOString(),
+            });
+            result.finalized++;
+        }
+        else if (Date.parse(row.createdAt) + pendingTtlMs <= now().getTime()) {
+            await SponsoredTransactions.fail(db, row.id, now().toISOString());
+            result.failed++;
+        }
+        else
+            result.pending++;
+    }
+    return result;
+}
+/**
+ * Runs one reconciliation pass over pending fill intents (rows with no
+ * transaction hash): fetches the fee payer's recent on-chain transactions
+ * from TIDX, recomputes each candidate's fee-payer sign payload, and fills
+ * matching intents' hashes so the receipt pass can finalize them. Query or
+ * candidate errors leave intents for the next pass.
+ *
+ * @param db - The database holding `sponsored_transactions`.
+ * @param options - Reconciliation options.
+ * @returns Counters for the pass.
+ */
+export async function reconcile(db, options) {
+    const { batchSize = 100, candidateCap = 500, failedIntentTtlMs = 86_400_000, feePayer, getClient, getTidx, skewMs = 120_000, } = options;
+    const intents = await SponsoredTransactions.listIntents(db, {
+        failedSince: new Date(Date.now() - failedIntentTtlMs).toISOString(),
+        limit: batchSize,
+    });
+    const result = { matched: 0, scanned: 0 };
+    if (intents.length === 0)
+        return result;
+    const chains = new Map();
+    for (const intent of intents)
+        chains.set(intent.chainId, [...(chains.get(intent.chainId) ?? []), intent]); // prettier-ignore
+    for (const [chainId, rows] of chains) {
+        const bySignPayload = new Map(rows.map((row) => [row.signPayload, row]));
+        // The intent set bounds the scan window: no cursor state to persist.
+        const since = new Date(Math.min(...rows.map((row) => Date.parse(row.createdAt))) - skewMs).toISOString();
+        let candidates;
+        try {
+            // Dynamic filter values; the tidx client's query type wants literals.
+            const fetched = await getTidx(chainId).fetch({
+                chainId,
+                query: `SELECT hash, "from" FROM txs WHERE fee_payer = '${feePayer.toLowerCase()}' AND block_timestamp >= '${since}' ORDER BY block_timestamp ASC LIMIT ${candidateCap}`,
+            });
+            candidates = fetched.rows;
+        }
+        catch {
+            // Indexer outage must not fail intents; retry on the next pass.
+            continue;
+        }
+        for (const candidate of candidates) {
+            if (bySignPayload.size === 0)
+                break;
+            const hash = candidate['hash'];
+            const sender = candidate['from'];
+            if (!hash || !sender)
+                continue;
+            result.scanned++;
+            try {
+                const serialized = await getRawTransaction(getClient(chainId), hash);
+                if (!serialized?.startsWith(TxEnvelopeTempo.serializedType))
+                    continue;
+                const signPayload = TxEnvelopeTempo.getFeePayerSignPayload(TxEnvelopeTempo.deserialize(serialized), { sender });
+                const intent = bySignPayload.get(signPayload);
+                if (!intent)
+                    continue;
+                await SponsoredTransactions.assignTransactionHash(db, intent.id, hash);
+                bySignPayload.delete(signPayload);
+                result.matched++;
+            }
+            catch {
+                // Unresolvable candidate (lookup error, malformed envelope): skip it.
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Fetches a mined transaction's canonical envelope bytes.
+ * `eth_getRawTransactionByHash` is a node extension absent from viem's typed
+ * RPC schema, hence the request-fn narrowing.
+ */
+function getRawTransaction(client, hash) {
+    return client.request({ method: 'eth_getRawTransactionByHash', params: [hash] });
+}
+/**
+ * Builds a scheduled sponsorship finalizer bound to a database and RPC config.
+ * A host runtime drives {@link createFinalizer.Finalizer.tick} on a timer (a
+ * Cloudflare `scheduled` cron handler, a self-host `setInterval`, …); each
+ * tick reconciles fill intents (when `feePayer` + `tidx` are configured) and
+ * runs one {@link finalize} pass, with memoized per-chain clients.
+ */
+export function createFinalizer(options) {
+    const clients = new Map();
+    const getClient = (chainId) => {
+        let client = clients.get(chainId);
+        if (!client) {
+            client = Viem.getClient({ chainId: chainId, rpc: options.rpc });
+            clients.set(chainId, client);
+        }
+        return client;
+    };
+    const getTidx = options.tidx
+        ? Tidx.createGetClient({ defaultChainId: options.defaultChainId, tidx: options.tidx })
+        : undefined;
+    const feePayer = options.feePayer;
+    return {
+        async tick() {
+            // Resolve per tick so Workers factories build a fresh Hyperdrive-pooled
+            // connection each run.
+            const db = Db.get(options.db);
+            // Reconcile first so freshly matched intents finalize in the same tick.
+            const reconciled = feePayer && getTidx
+                ? await reconcile(db, {
+                    batchSize: options.batchSize,
+                    feePayer,
+                    getClient,
+                    getTidx: (chainId) => getTidx(chainId),
+                })
+                : { matched: 0, scanned: 0 };
+            const finalized = await finalize(db, {
+                batchSize: options.batchSize,
+                getClient,
+                now: options.now,
+                pendingTtlMs: options.pendingTtlMs,
+            });
+            return { ...finalized, ...reconciled };
+        },
+    };
+}
+//# sourceMappingURL=Sponsorships.js.map

package/dist/apps/relay/Sponsorships.js.map

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

package/dist/apps/relay/index.d.ts

@@ -0,0 +1,3 @@
+export { relay } from './App.js';
+export * as Sponsorships from './Sponsorships.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/apps/relay/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/apps/relay/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAChC,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA"}

package/dist/apps/relay/index.js

@@ -0,0 +1,3 @@
+export { relay } from './App.js';
+export * as Sponsorships from './Sponsorships.js';
+//# sourceMappingURL=index.js.map

package/dist/apps/relay/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/apps/relay/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAChC,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA"}

package/dist/cli/Cli.d.ts

@@ -1,12 +1,17 @@
 import { Cli as incur_Cli, Fetch, type Openapi } from 'incur';
+import type { mcp } from '../apps/mcp.js';
 /**
- * Creates an incur CLI backed by a hosted Tempo API, plus the operator
- * commands (`<cli> admin …`).
+ * Creates an incur CLI backed by a hosted Tempo API, plus the super admin
+ * commands (`<cli> admin …`) and the remote Tempo docs tools (`<cli> docs …`).
  */
 export declare function from(url: string | URL, options?: from.Options): incur_Cli.Cli<{
     [x: `${string} ${string} ${string}`]: {
         args: {};
         options: {
+            clickhouseDatabase?: string | undefined;
+            clickhouseMigratePassword?: string | undefined;
+            clickhouseMigrateUser?: string | undefined;
+            clickhouseUrl?: string | undefined;
             databaseUrl?: string | undefined;
             dbSchema?: string | undefined;
         };
@@ -17,6 +22,8 @@ export declare namespace from {
     type Options = {
         /** CLI description. */
         description?: string | undefined;
+        /** Remote docs MCP source mounted as the `docs` command group, or `false` to omit it. @default 'https://mcp.tempo.xyz/mcp' */
+        docs?: mcp.Source | false | undefined;
         /** CLI name. */
         name?: string | undefined;
         /** OpenAPI document source. Relative paths resolve from the API URL. */

package/dist/cli/Cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Cli.d.ts","sourceRoot":"","sources":["../../src/cli/Cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,IAAI,SAAS,EAAE,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,OAAO,CAAA;AAI7D;;;GAGG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,OAAO,GAAE,IAAI,CAAC,OAAY;;;;;;;;oCAkBjE;AAED,MAAM,CAAC,OAAO,WAAW,IAAI,CAAC;IAC5B,8DAA8D;IAC9D,KAAK,OAAO,GAAG;QACb,uBAAuB;QACvB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;QAChC,gBAAgB;QAChB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;QACzB,wEAAwE;QACxE,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,GAAG,SAAS,CAAA;QAC3C,4EAA4E;QAC5E,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,GAAG,SAAS,CAAA;QAC1C,4CAA4C;QAC5C,OAAO,CAAC,EAAE,KAAK,CAAC,WAAW,CAAC,OAAO,GAAG,SAAS,CAAA;QAC/C,mBAAmB;QACnB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAC7B,CAAA;CACF"}
+{"version":3,"file":"Cli.d.ts","sourceRoot":"","sources":["../../src/cli/Cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,IAAI,SAAS,EAAE,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,OAAO,CAAA;AAE7D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AAUzC;;;GAGG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,OAAO,GAAE,IAAI,CAAC,OAAY;;;;;;;;;;;;oCAuBjE;AAED,MAAM,CAAC,OAAO,WAAW,IAAI,CAAC;IAC5B,8DAA8D;IAC9D,KAAK,OAAO,GAAG;QACb,uBAAuB;QACvB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;QAChC,8HAA8H;QAC9H,IAAI,CAAC,EAAE,GAAG,CAAC,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;QACrC,gBAAgB;QAChB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;QACzB,wEAAwE;QACxE,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,GAAG,SAAS,CAAA;QAC3C,4EAA4E;QAC5E,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,GAAG,SAAS,CAAA;QAC1C,4CAA4C;QAC5C,OAAO,CAAC,EAAE,KAAK,CAAC,WAAW,CAAC,OAAO,GAAG,SAAS,CAAA;QAC/C,mBAAmB;QACnB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAC7B,CAAA;CACF"}

package/dist/cli/Cli.js

@@ -1,19 +1,27 @@
 import { Cli as incur_Cli, Fetch } from 'incur';
 import * as Admin from './commands/admin.js';
+/** Tool patterns hidden from MCP clients: super admin, partner-shaped gecko mirrors, browser session flows. */
+const excludedTools = ['admin_*', 'gecko_*', 'v1_auth_*'];
+/** Usage guidance surfaced to MCP clients on initialize (`<cli> --mcp`). */
+const instructions = 'Tools mirror the hosted Tempo API. Authenticated tools accept an `authorization` input (`Bearer <api key>`). List endpoints paginate via `cursor`/`nextCursor`. `docs_*` tools search the Tempo documentation.';
 /**
- * Creates an incur CLI backed by a hosted Tempo API, plus the operator
- * commands (`<cli> admin …`).
+ * Creates an incur CLI backed by a hosted Tempo API, plus the super admin
+ * commands (`<cli> admin …`) and the remote Tempo docs tools (`<cli> docs …`).
  */
 export function from(url, options = {}) {
-    const { description = 'Tempo API CLI', name = 'tapimo', openapi = 'openapi.json', request, version = '0.0.0', } = options;
-    return incur_Cli
+    const { description = 'Tempo API CLI', docs = 'https://mcp.tempo.xyz/mcp', name = 'tapimo', openapi = 'openapi.json', request, version = '0.0.0', } = options;
+    const cli = incur_Cli
         .create(name, {
         description,
         fetch: Fetch.fromRequest(url, request),
+        mcp: { instructions, tools: { exclude: excludedTools } },
         openapi,
         openapiConfig: options.openapiConfig ?? { mode: 'namespace' },
         version,
     })
         .command(Admin.admin);
+    if (docs !== false)
+        cli.command('docs', { description: 'Search the Tempo documentation.', mcp: docs });
+    return cli;
 }
 //# sourceMappingURL=Cli.js.map

package/dist/cli/Cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"Cli.js","sourceRoot":"","sources":["../../src/cli/Cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,IAAI,SAAS,EAAE,KAAK,EAAgB,MAAM,OAAO,CAAA;AAE7D,OAAO,KAAK,KAAK,MAAM,qBAAqB,CAAA;AAE5C;;;GAGG;AACH,MAAM,UAAU,IAAI,CAAC,GAAiB,EAAE,OAAO,GAAiB,EAAE;IAChE,MAAM,EACJ,WAAW,GAAG,eAAe,EAC7B,IAAI,GAAG,QAAQ,EACf,OAAO,GAAG,cAAc,EACxB,OAAO,EACP,OAAO,GAAG,OAAO,GAClB,GAAG,OAAO,CAAA;IAEX,OAAO,SAAS;SACb,MAAM,CAAC,IAAI,EAAE;QACZ,WAAW;QACX,KAAK,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC;QACtC,OAAO;QACP,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE;QAC7D,OAAO;KACR,CAAC;SACD,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;AACzB,CAAC"}
+{"version":3,"file":"Cli.js","sourceRoot":"","sources":["../../src/cli/Cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,IAAI,SAAS,EAAE,KAAK,EAAgB,MAAM,OAAO,CAAA;AAG7D,OAAO,KAAK,KAAK,MAAM,qBAAqB,CAAA;AAE5C,+GAA+G;AAC/G,MAAM,aAAa,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,WAAW,CAAC,CAAA;AAEzD,4EAA4E;AAC5E,MAAM,YAAY,GAChB,gNAAgN,CAAA;AAElN;;;GAGG;AACH,MAAM,UAAU,IAAI,CAAC,GAAiB,EAAE,OAAO,GAAiB,EAAE;IAChE,MAAM,EACJ,WAAW,GAAG,eAAe,EAC7B,IAAI,GAAG,2BAA2B,EAClC,IAAI,GAAG,QAAQ,EACf,OAAO,GAAG,cAAc,EACxB,OAAO,EACP,OAAO,GAAG,OAAO,GAClB,GAAG,OAAO,CAAA;IAEX,MAAM,GAAG,GAAG,SAAS;SAClB,MAAM,CAAC,IAAI,EAAE;QACZ,WAAW;QACX,KAAK,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC;QACtC,GAAG,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,aAAa,EAAE,EAAE;QACxD,OAAO;QACP,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE;QAC7D,OAAO;KACR,CAAC;SACD,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IACvB,IAAI,IAAI,KAAK,KAAK;QAChB,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,WAAW,EAAE,iCAAiC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAA;IACpF,OAAO,GAAG,CAAA;AACZ,CAAC"}