@crossly/mcp 0.0.0-stage → 0.1.0

package/dist/tools/ads.js

@@ -0,0 +1,233 @@
+import { apiGet, apiPost, apiPut } from '../api.js';
+/**
+ * Offsite ads — promoting a merchant's items on external ad networks.
+ *
+ * Separate from the CBX tools because it is a separate product: the
+ * budget is denominated in CBX and managed by the `*_cbx_ad_credit`
+ * tools, while these cover networks, creative, attribution and policy.
+ *
+ * ── WHAT AN AGENT MUST NOT MISREPRESENT ───────────────────────────────
+ * This feature asks a merchant to hand over discretion over their money
+ * to a party whose interests only partly overlap with theirs. Three
+ * things are true and must be stated accurately if a merchant asks:
+ *
+ *   OPT-IN ONLY. Off unless the merchant turns it on, and nothing
+ *   enables it on their behalf. Never describe it as default or
+ *   automatic.
+ *
+ *   MEDIA IS PASS-THROUGH AT COST, with a separate disclosed management
+ *   fee. `mediaCostCents` versus `managementFeeCents` in the report
+ *   answers "how much of my budget reached the auction", and that is a
+ *   question the merchant is entitled to a straight answer to.
+ *
+ *   THE RETURN FLOOR IS A STOP, NOT A GUARANTEE. Below it, spend
+ *   auto-pauses. Do NOT present `minReturnBps` as a promised return —
+ *   nobody can honestly promise ad performance.
+ *
+ * ── SPILLOVER IS REPORTED, NOT PAID FOR ───────────────────────────────
+ * When a click a merchant funded converts on somebody ELSE's item it is
+ * recorded as spillover and shown in their report. If a merchant asks
+ * why their conversion count is lower than their click volume suggests,
+ * spillover is usually the answer.
+ *
+ * It is NOT credited back, and saying otherwise is the specific error
+ * this section exists to prevent. Every ad market sells clicks — Etsy
+ * Offsite Ads actually CHARGES 12-15% on attributed sales — and a
+ * credit-back would be farmable with a decoy listing: advertise a cheap
+ * obscure item, drive broad traffic, and collect a share of Crossly's
+ * fee on every other seller's sale.
+ *
+ * What a merchant should do with a high spillover rate is turn offsite
+ * ads off. That is the remedy, and the return floor is the automatic
+ * version of it.
+ */
+export const adsTools = [
+    {
+        name: 'get_offsite_ads_settings',
+        description: 'The merchant\'s offsite-ads opt-in and terms. Offsite ads spend their CBX advertising '
+            + 'budget on external networks — Google, Meta and similar — at Crossly\'s discretion; '
+            + 'their item gets promoted and the traffic lands on Crossly. '
+            + 'OFF unless they turned it on. `networkWired` false means no ad network is connected '
+            + 'yet, so campaigns will refuse rather than silently spend nothing. '
+            + '`autoPausedReason` is worth reading aloud when present — it says why spending '
+            + 'stopped.',
+        inputSchema: { type: 'object', properties: {} },
+        handler: () => apiGet('/v1/ads/offsite'),
+    },
+    {
+        name: 'set_offsite_ads',
+        description: 'Turn offsite ads on or off, and set the terms. THE MERCHANT\'S DECISION — confirm they '
+            + 'actually want it before enabling, and never enable it as a side effect of another '
+            + 'request. '
+            + '`maxOffsiteShareBps` caps how much of their budget may leave the platform. '
+            + '`minReturnBps` is the floor below which spend AUTO-PAUSES: 20000 means $2 of '
+            + 'attributed revenue per $1 spent over the window. Present it as a stop, never as a '
+            + 'promised return. '
+            + 'Toggling either way clears any existing auto-pause, so turning it back on does not '
+            + 'inherit a pause from months ago.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                enabled: {
+                    type: 'boolean',
+                    description: 'Whether offsite ads may run. The merchant decides this; nothing else sets it.',
+                },
+                maxOffsiteShareBps: {
+                    type: 'integer',
+                    description: 'Ceiling on the share of their ad budget that may go offsite, in basis points. '
+                        + '5000 = at most half.',
+                },
+                minReturnBps: {
+                    type: 'integer',
+                    description: 'Attributed revenue floor as basis points of spend. Below this over the window, '
+                        + 'offsite spend auto-pauses and the rest reverts to on-platform. A stop, not a '
+                        + 'guarantee.',
+                },
+                returnWindowDays: {
+                    type: 'integer',
+                    description: 'Days of history the return floor is measured over.',
+                },
+                allowedNetworks: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Networks the merchant will allow: google, meta, tiktok, reddit, pinterest. '
+                        + 'Omit or leave empty to allow all eligible ones.',
+                },
+            },
+            required: ['enabled'],
+        },
+        handler: (args) => apiPut('/v1/ads/offsite', args),
+    },
+    {
+        name: 'get_offsite_ads_report',
+        description: 'What the merchant\'s offsite budget bought — INCLUDING the misses. Spend, impressions '
+            + 'and clicks are reported whether or not anything converted, because a report showing '
+            + 'only conversions cannot be audited. '
+            + 'When summarising, give spend AND conversions rather than only the wins. '
+            + '`mediaCostCents` versus `managementFeeCents` is how much reached the auction versus '
+            + 'Crossly\'s fee. '
+            + '`spilloverConversions` is sales their ads produced on OTHER sellers\' items, and '
+            + '`spilloverCreditedCents` is what came back to them for it. '
+            + '`returnBps` is attributed revenue as basis points of spend — compare it with their '
+            + '`minReturnBps` floor to explain a pause.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sinceDays: {
+                    type: 'integer',
+                    description: 'Days of history to report. Defaults to 30.',
+                },
+            },
+        },
+        handler: (args) => {
+            const { sinceDays } = args;
+            // The query goes in the query argument, not concatenated onto the
+            // path. Interpolating it made this call site read as though the path
+            // carried a trailing param, so v1-parity.test.ts reported a route
+            // that exists as having no tool.
+            //
+            // Do not write the malformed form out in a comment either — that
+            // test scans source text, so a path spelled in prose is picked up as
+            // a real call site. This note cost one debugging cycle.
+            return apiGet('/v1/ads/offsite/report', sinceDays ? { sinceDays: String(sinceDays) } : undefined);
+        },
+    },
+    {
+        name: 'check_offsite_ads_eligibility',
+        description: 'Whether an item can run offsite, and why not. Reasons: not_opted_in, auto_paused, '
+            + 'network_not_allowed, category_not_allowlisted, no_adapter, no_budget. '
+            + 'The category check is an ALLOWLIST, so an unclassified category is NOT eligible — '
+            + 'that is deliberate, not a bug to work around. Ad networks suspend the whole ACCOUNT '
+            + 'over a prohibited item, and that account is shared across every merchant using this, '
+            + 'so one listing could cost all of them the feature. Do not suggest bypassing it.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                network: {
+                    type: 'string',
+                    enum: ['google', 'meta', 'tiktok', 'reddit', 'pinterest'],
+                    description: 'Which network the item would run on.',
+                },
+                category: {
+                    type: 'string',
+                    description: "The item's category, checked against the platform allowlist.",
+                },
+            },
+            required: ['network', 'category'],
+        },
+        handler: (args) => {
+            const { network, category } = args;
+            const q = new URLSearchParams({ network, category });
+            return apiGet(`/v1/ads/offsite/eligibility?${q.toString()}`);
+        },
+    },
+    {
+        name: 'resume_offsite_ads',
+        description: 'Clear an auto-pause and resume offsite spend. Returns 409 when not actually paused. '
+            + 'Read `autoPausedReason` from the settings first: resuming without changing anything '
+            + 'usually just trips the floor again over the next window, so it is worth telling the '
+            + 'merchant what tripped it before spending more of their money.',
+        inputSchema: { type: 'object', properties: {} },
+        handler: () => apiPost('/v1/ads/offsite/resume', {}),
+    },
+    {
+        name: 'create_offsite_ads_campaign',
+        description: 'Launch an offsite campaign for an item. SPENDS THE MERCHANT\'S AD BUDGET on an '
+            + 'external network. '
+            + 'Creative is built from the structured fields passed here — title, condition as '
+            + 'recorded, price, image. Do NOT embellish them: an ad saying "mint", "authenticated" '
+            + 'or "rare" when the listing says none of those is a misrepresentation Crossly '
+            + 'authored, and it is the SELLER who takes the buyer dispute, the return and the '
+            + 'feedback. Pass the listing\'s own values verbatim. '
+            + 'Refuses with 403 when no ad network is wired, rather than returning a campaign that '
+            + 'does not exist.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                network: {
+                    type: 'string',
+                    enum: ['google', 'meta', 'tiktok', 'reddit', 'pinterest'],
+                    description: 'Which network to run on.',
+                },
+                listingId: {
+                    type: 'string',
+                    description: 'The Crossly listing being promoted, when there is one.',
+                },
+                category: {
+                    type: 'string',
+                    description: "The item's category. Checked against the platform allowlist before anything "
+                        + 'is created.',
+                },
+                title: {
+                    type: 'string',
+                    description: "The listing's title, verbatim. Do not rewrite or embellish it.",
+                },
+                condition: {
+                    type: 'string',
+                    description: "The condition as the listing records it, verbatim. Omit if the listing has "
+                        + 'none — do not infer one.',
+                },
+                priceCents: {
+                    type: 'integer',
+                    description: "The listing's price in CENTS.",
+                },
+                imageUrl: {
+                    type: 'string',
+                    description: "URL of the listing's primary image.",
+                },
+                landingUrl: {
+                    type: 'string',
+                    description: 'Where the click lands. Should be the listing page on Crossly.',
+                },
+                dailyBudgetCents: {
+                    type: 'integer',
+                    description: 'Daily cap in CENTS. Drawn from the merchant\'s CBX ad budget; media is passed '
+                        + 'through at cost with a separate management fee.',
+                },
+            },
+            required: ['network', 'category', 'title', 'priceCents', 'landingUrl', 'dailyBudgetCents'],
+        },
+        handler: (args) => apiPost('/v1/ads/offsite/campaigns', args),
+    },
+];
+//# sourceMappingURL=ads.js.map

package/dist/tools/ads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ads.js","sourceRoot":"","sources":["../../src/tools/ads.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAc;IACjC;QACE,IAAI,EAAE,0BAA0B;QAChC,WAAW,EACT,wFAAwF;cACtF,qFAAqF;cACrF,6DAA6D;cAC7D,sFAAsF;cACtF,oEAAoE;cACpE,gFAAgF;cAChF,UAAU;QACd,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;QAC/C,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,iBAAiB,CAAC;KACzC;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,WAAW,EACT,yFAAyF;cACvF,oFAAoF;cACpF,WAAW;cACX,6EAA6E;cAC7E,+EAA+E;cAC/E,oFAAoF;cACpF,mBAAmB;cACnB,qFAAqF;cACrF,kCAAkC;QACtC,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,OAAO,EAAE;oBACP,IAAI,EAAE,SAAS;oBACf,WAAW,EACT,+EAA+E;iBAClF;gBACD,kBAAkB,EAAE;oBAClB,IAAI,EAAE,SAAS;oBACf,WAAW,EACT,gFAAgF;0BAC9E,sBAAsB;iBAC3B;gBACD,YAAY,EAAE;oBACZ,IAAI,EAAE,SAAS;oBACf,WAAW,EACT,iFAAiF;0BAC/E,+EAA+E;0BAC/E,YAAY;iBACjB;gBACD,gBAAgB,EAAE;oBAChB,IAAI,EAAE,SAAS;oBACf,WAAW,EAAE,oDAAoD;iBAClE;gBACD,eAAe,EAAE;oBACf,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACzB,WAAW,EACT,6EAA6E;0BAC3E,iDAAiD;iBACtD;aACF;YACD,QAAQ,EAAE,CAAC,SAAS,CAAC;SACtB;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,iBAAiB,EAAE,IAAI,CAAC;KACnD;IACD;QACE,IAAI,EAAE,wBAAwB;QAC9B,WAAW,EACT,wFAAwF;cACtF,sFAAsF;cACtF,sCAAsC;cACtC,0EAA0E;cAC1E,sFAAsF;cACtF,kBAAkB;cAClB,mFAAmF;cACnF,6DAA6D;cAC7D,qFAAqF;cACrF,0CAA0C;QAC9C,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,SAAS,EAAE;oBACT,IAAI,EAAE,SAAS;oBACf,WAAW,EAAE,4CAA4C;iBAC1D;aACF;SACF;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YAChB,MAAM,EAAE,SAAS,EAAE,GAAG,IAA8B,CAAC;YACrD,kEAAkE;YAClE,qEAAqE;YACrE,kEAAkE;YAClE,iCAAiC;YACjC,EAAE;YACF,iEAAiE;YACjE,qEAAqE;YACrE,wDAAwD;YACxD,OAAO,MAAM,CACX,wBAAwB,EACxB,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CACzD,CAAC;QACJ,CAAC;KACF;IACD;QACE,IAAI,EAAE,+BAA+B;QACrC,WAAW,EACT,oFAAoF;cAClF,wEAAwE;cACxE,oFAAoF;cACpF,sFAAsF;cACtF,uFAAuF;cACvF,iFAAiF;QACrF,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,CAAC;oBACzD,WAAW,EAAE,sCAAsC;iBACpD;gBACD,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,8DAA8D;iBAC5E;aACF;YACD,QAAQ,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC;SAClC;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YAChB,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,IAA6C,CAAC;YAC5E,MAAM,CAAC,GAAG,IAAI,eAAe,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;YACrD,OAAO,MAAM,CAAC,+BAA+B,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC/D,CAAC;KACF;IACD;QACE,IAAI,EAAE,oBAAoB;QAC1B,WAAW,EACT,sFAAsF;cACpF,sFAAsF;cACtF,sFAAsF;cACtF,+DAA+D;QACnE,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;QAC/C,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,wBAAwB,EAAE,EAAE,CAAC;KACrD;IACD;QACE,IAAI,EAAE,6BAA6B;QACnC,WAAW,EACT,iFAAiF;cAC/E,oBAAoB;cACpB,iFAAiF;cACjF,sFAAsF;cACtF,+EAA+E;cAC/E,iFAAiF;cACjF,qDAAqD;cACrD,sFAAsF;cACtF,iBAAiB;QACrB,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,CAAC;oBACzD,WAAW,EAAE,0BAA0B;iBACxC;gBACD,SAAS,EAAE;oBACT,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,wDAAwD;iBACtE;gBACD,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,8EAA8E;0BAC5E,aAAa;iBAClB;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,gEAAgE;iBAC9E;gBACD,SAAS,EAAE;oBACT,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,6EAA6E;0BAC3E,0BAA0B;iBAC/B;gBACD,UAAU,EAAE;oBACV,IAAI,EAAE,SAAS;oBACf,WAAW,EAAE,+BAA+B;iBAC7C;gBACD,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,qCAAqC;iBACnD;gBACD,UAAU,EAAE;oBACV,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,+DAA+D;iBAC7E;gBACD,gBAAgB,EAAE;oBAChB,IAAI,EAAE,SAAS;oBACf,WAAW,EACT,gFAAgF;0BAC9E,iDAAiD;iBACtD;aACF;YACD,QAAQ,EAAE,CAAC,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,kBAAkB,CAAC;SAC3F;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,2BAA2B,EAAE,IAAI,CAAC;KAC9D;CACF,CAAC"}

package/dist/tools/ai.d.ts

@@ -0,0 +1,3 @@
+import { ToolDef } from './types.js';
+export declare const aiTools: ToolDef[];
+//# sourceMappingURL=ai.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../src/tools/ai.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,OAAO,EAAE,MAAM,YAAY,CAAC;AAEvD,eAAO,MAAM,OAAO,EAAE,OAAO,EAsd5B,CAAC"}