@crossly/mcp 0.0.0-stage → 0.1.0

package/dist/tools/cbx-rewards.js

@@ -0,0 +1,56 @@
+import { cbxRewardAdCredit } from './cbx-rewards/ad-credit.js';
+import { cbxRewardBalances } from './cbx-rewards/balances.js';
+import { cbxRewardCredit } from './cbx-rewards/credit.js';
+import { cbxRewardDisbursements } from './cbx-rewards/disbursements.js';
+import { cbxRewardEarn } from './cbx-rewards/earn-boosts.js';
+import { cbxRewardRedemptions } from './cbx-rewards/redemptions.js';
+import { cbxRewardStaking } from './cbx-rewards/staking.js';
+import { cbxRewardTierAdmin } from './cbx-rewards/tier-admin.js';
+/**
+ * CBX rewards, staking, advertising, balances, and wholesale credit.
+ *
+ * Split from `cbx.ts` to stay under the repo's file-size cap, and
+ * registered alongside it.
+ *
+ * ── WHAT AN AGENT MUST UNDERSTAND BEFORE USING THESE ──────────────────
+ * Several of these commit money forward or move it, and the descriptions
+ * say so rather than reading as neutral CRUD:
+ *
+ *   create_cbx_boost         commits a merchant's budget to cashback.
+ *   stake_cbx                makes a user's balance UNSPENDABLE. It is
+ *                            their money and this locks it.
+ *   redeem_cbx_service       debits a user for a service.
+ *   purchase_cbx_ad_credit   claims an advertising budget against a
+ *                            token transfer. One signature, one claim.
+ *   draw_cbx_credit          advances real value against a credit line.
+ *   grant_cbx                issues spendable value out of the reserve.
+ *
+ * ── THE THREE BALANCES ────────────────────────────────────────────────
+ * A subject can hold three, and they are not interchangeable:
+ *
+ *   EARNED     cashback. Withdrawable once matured.
+ *   GRANTED    ad credit, wholesale draws, promos. Spendable in the
+ *              marketplace ONLY — never withdrawable.
+ *   CONNECTED  the user's own self-custodied CBX, via a bounded
+ *              delegation. Never a platform liability.
+ *
+ * Spends always consume granted → earned → connected, and that order is
+ * not configurable. Never tell a user their granted balance can be
+ * withdrawn or cashed out; it cannot, by construction.
+ *
+ * ── AMOUNTS ───────────────────────────────────────────────────────────
+ * Cents are plain integers. TOKEN amounts are decimal STRINGS of base
+ * units, because a balance can exceed what a JSON number holds exactly.
+ * Never convert a token amount through a float before displaying it.
+ */
+export const cbxRewardTools = [
+    ...cbxRewardEarn,
+    ...cbxRewardStaking,
+    ...cbxRewardRedemptions,
+    ...cbxRewardAdCredit,
+    ...cbxRewardBalances,
+    ...cbxRewardCredit,
+    ...cbxRewardDisbursements,
+    ...cbxRewardTierAdmin,
+];
+//# sourceMappingURL=cbx-rewards.js.map

package/dist/tools/cbx-rewards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cbx-rewards.js","sourceRoot":"","sources":["../../src/tools/cbx-rewards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAGjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,CAAC,MAAM,cAAc,GAAc;IACvC,GAAG,aAAa;IAChB,GAAG,gBAAgB;IACnB,GAAG,oBAAoB;IACvB,GAAG,iBAAiB;IACpB,GAAG,iBAAiB;IACpB,GAAG,eAAe;IAClB,GAAG,sBAAsB;IACzB,GAAG,kBAAkB;CACtB,CAAC"}

package/dist/tools/cbx-wallet-payments.d.ts

@@ -0,0 +1,35 @@
+import { ToolDef } from './types.js';
+/**
+ * Checkout paid from the buyer's own wallet.
+ *
+ * ── WHAT AN AGENT MUST UNDERSTAND ─────────────────────────────────────
+ * The flow is three steps and only two of them are ours:
+ *
+ *   quote_cbx_wallet_payment    we build an unsigned transfer
+ *   (the buyer's wallet)        they sign and submit it
+ *   confirm_cbx_wallet_payment  they hand us the signature
+ *
+ * We never hold a key or a delegation and never submit anything, so the
+ * platform has no authority over the buyer's tokens at any point.
+ *
+ * ── A QUOTE IS NOT A PAYMENT ──────────────────────────────────────────
+ * Quoting reserves nothing and records nothing. Never tell a user their
+ * order is paid because a quote succeeded — the buyer may never sign it.
+ * The SIGNATURE is the event.
+ *
+ * ── `releaseDecision` IS ABOUT THE GOODS, NOT THE MONEY ───────────────
+ * By the time a signature exists the tokens have moved and cannot be
+ * un-moved. So the decision is only whether to ship:
+ *
+ *   release  ship it
+ *   review   hold — a person must look. Also what you get when no
+ *            screening provider is configured.
+ *   refuse   do not ship. The payment is STILL RECORDED, because we
+ *            received the tokens and that does not go away.
+ *
+ * A `refuse` is not "the payment failed" and must never be described
+ * that way to a buyer — their tokens are gone and they are owed either
+ * goods or a refund decision from a human.
+ */
+export declare const cbxWalletPaymentTools: ToolDef[];
+//# sourceMappingURL=cbx-wallet-payments.d.ts.map

package/dist/tools/cbx-wallet-payments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cbx-wallet-payments.d.ts","sourceRoot":"","sources":["../../src/tools/cbx-wallet-payments.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,qBAAqB,EAAE,OAAO,EAuI1C,CAAC"}

package/dist/tools/cbx-wallet-payments.js

@@ -0,0 +1,156 @@
+import { apiGet, apiPost } from '../api.js';
+/**
+ * Checkout paid from the buyer's own wallet.
+ *
+ * ── WHAT AN AGENT MUST UNDERSTAND ─────────────────────────────────────
+ * The flow is three steps and only two of them are ours:
+ *
+ *   quote_cbx_wallet_payment    we build an unsigned transfer
+ *   (the buyer's wallet)        they sign and submit it
+ *   confirm_cbx_wallet_payment  they hand us the signature
+ *
+ * We never hold a key or a delegation and never submit anything, so the
+ * platform has no authority over the buyer's tokens at any point.
+ *
+ * ── A QUOTE IS NOT A PAYMENT ──────────────────────────────────────────
+ * Quoting reserves nothing and records nothing. Never tell a user their
+ * order is paid because a quote succeeded — the buyer may never sign it.
+ * The SIGNATURE is the event.
+ *
+ * ── `releaseDecision` IS ABOUT THE GOODS, NOT THE MONEY ───────────────
+ * By the time a signature exists the tokens have moved and cannot be
+ * un-moved. So the decision is only whether to ship:
+ *
+ *   release  ship it
+ *   review   hold — a person must look. Also what you get when no
+ *            screening provider is configured.
+ *   refuse   do not ship. The payment is STILL RECORDED, because we
+ *            received the tokens and that does not go away.
+ *
+ * A `refuse` is not "the payment failed" and must never be described
+ * that way to a buyer — their tokens are gone and they are owed either
+ * goods or a refund decision from a human.
+ */
+export const cbxWalletPaymentTools = [
+    {
+        name: 'quote_cbx_wallet_payment',
+        description: 'Build an unsigned transfer for a buyer to sign with their own wallet. '
+            + 'RESERVES NOTHING and RECORDS NOTHING — no row, no hold, no balance change. Do not '
+            + 'tell anyone their order is paid on the strength of a quote; the buyer may never '
+            + 'sign it. '
+            + '`lastValidBlockHeight` is when it expires: a wallet prompt left open for a couple '
+            + 'of minutes yields a transaction the chain rejects, so re-quote rather than retry. '
+            + '`payerCanCover` is a courtesy balance read so you can warn before the prompt — null '
+            + 'means we could not read it, which is NOT the same as "no". '
+            + 'The buyer needs no prior wallet registration: a payment proves control of the '
+            + 'tokens, which is what a connect step would have been proving.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                payerAddress: {
+                    type: 'string',
+                    description: "The buyer's wallet address. They will sign the transfer themselves; no prior "
+                        + 'registration or verification is required.',
+                },
+                valueCents: {
+                    type: 'integer',
+                    description: 'What the order costs, in CENTS. Converted to a token amount at the live spot. '
+                        + 'Pass dollars, never a token quantity — a client naming the quantity could pay '
+                        + 'whatever it liked for a fixed-price order.',
+                },
+            },
+            required: ['payerAddress', 'valueCents'],
+        },
+        handler: (args) => apiPost('/v1/cbx/wallet-payments/quote', args),
+    },
+    {
+        name: 'confirm_cbx_wallet_payment',
+        description: 'Present the signature of a transfer the buyer already made, and get a ship / '
+            + 'do-not-ship decision. '
+            + 'Everything is read from the CHAIN at finalized commitment — amount, payer, '
+            + 'destination. Nothing asserted in the request is trusted. '
+            + 'Read `releaseDecision` before telling anyone anything: `release` means ship, '
+            + '`review` means a person must look (including when no screening provider is '
+            + 'configured), `refuse` means do not ship. '
+            + 'A `refuse` is NOT "the payment failed" — the tokens moved and the buyer is owed '
+            + 'either goods or a refund decision from a human. Never describe it as a failed '
+            + 'payment. '
+            + 'Idempotent on txSig globally and on (merchant, externalId). A 409 means it has not '
+            + 'finalized yet and you should retry; a 400 means it never will be claimable.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                externalId: {
+                    type: 'string',
+                    description: "The merchant's order id. Idempotency key — one order is paid once.",
+                },
+                txSig: {
+                    type: 'string',
+                    description: 'Signature of the transfer the buyer signed and submitted. Claimable exactly '
+                        + 'once across every merchant and order.',
+                },
+                subjectId: {
+                    type: 'string',
+                    description: 'The paying subject, when they are a known user. Optional — a payment does not '
+                        + 'require an account.',
+                },
+                valueCents: {
+                    type: 'integer',
+                    description: 'What the order costs, in CENTS. Used for the review ceiling on large orders. '
+                        + 'Omit to use the value read from the chain.',
+                },
+            },
+            required: ['externalId', 'txSig'],
+        },
+        handler: (args) => apiPost('/v1/cbx/wallet-payments/confirm', args),
+    },
+    {
+        name: 'list_cbx_wallet_payments_for_review',
+        description: 'Payments held for a human — the ops queue. Every row is money taken and goods not '
+            + 'shipped, which is not a state to leave a buyer in quietly. '
+            + '`riskLevel` and `riskExposures` are the verdict as recorded at the time, not '
+            + 're-derived: asking a provider again later answers a different question than the one '
+            + 'already decided. '
+            + 'When summarising, lead with how long each has been waiting — a buyer who paid and '
+            + 'received nothing is the most urgent case in this system.',
+        inputSchema: { type: 'object', properties: {} },
+        handler: () => apiGet('/v1/cbx/wallet-payments/review'),
+    },
+    {
+        name: 'resolve_cbx_wallet_payment',
+        description: 'Record a human decision on a held payment. RELEASES OR REFUSES MERCHANDISE against a '
+            + 'payment somebody flagged — confirm the person actually reviewed it before calling. '
+            + 'Only moves a payment OUT of `review`, never between the other two: a refusal that '
+            + 'could later be flipped to a release is an approval control with no teeth, and a '
+            + 'release re-decided as a refusal after shipping is a record that no longer describes '
+            + 'what happened. '
+            + 'The reviewer and note are stored, because this is the decision somebody will be '
+            + 'asked to justify.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                paymentId: {
+                    type: 'string',
+                    description: 'The held payment, from list_cbx_wallet_payments_for_review.',
+                },
+                decision: {
+                    type: 'string',
+                    enum: ['release', 'refuse'],
+                    description: 'release ships the goods; refuse does not. There is no path back to review, and '
+                        + 'neither decision can be overwritten by a later call.',
+                },
+                note: {
+                    type: 'string',
+                    description: 'Why. Stored on the row alongside the reviewer, and this is the text somebody '
+                        + 'reads when asked to justify the call.',
+                },
+            },
+            required: ['paymentId', 'decision', 'note'],
+        },
+        handler: (args) => {
+            const { paymentId, ...body } = args;
+            return apiPost(`/v1/cbx/wallet-payments/${encodeURIComponent(paymentId)}/resolve`, body);
+        },
+    },
+];
+//# sourceMappingURL=cbx-wallet-payments.js.map

package/dist/tools/cbx-wallet-payments.js.map

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

package/dist/tools/cbx.d.ts

@@ -0,0 +1,23 @@
+import { ToolDef } from './types.js';
+/**
+ * CBX — cashback rails for a physical-goods marketplace.
+ *
+ * ── WHAT AN AGENT NEEDS TO UNDERSTAND BEFORE USING THESE ──────────────
+ * Two of these tools move real money and one of them is irreversible, so
+ * the descriptions say so plainly rather than reading as neutral CRUD.
+ * Specifically:
+ *
+ *   accrue_cbx           creates a liability. Idempotent ONLY if you pass
+ *                        sourceExternalId.
+ *   reverse_cbx_accrual  works while pending, fails once converted.
+ *   create_cbx_claim     debits a balance and queues a transfer OFF the
+ *                        platform. Not reversible once confirmed.
+ *   execute_cbx_campaign distributes a pool to many users at once.
+ *
+ * ── AMOUNTS ───────────────────────────────────────────────────────────
+ * Cents are plain integers. TOKEN amounts are decimal STRINGS of base
+ * units, because a balance can exceed what a JSON number holds exactly.
+ * Never convert a token amount through a float before displaying it.
+ */
+export declare const cbxTools: ToolDef[];
+//# sourceMappingURL=cbx.d.ts.map

package/dist/tools/cbx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cbx.d.ts","sourceRoot":"","sources":["../../src/tools/cbx.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,QAAQ,EAAE,OAAO,EA8d7B,CAAC"}