@apex-inc/mcp-server 0.23.4 → 0.25.0

package/dist/tools.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
-import { apiGet, apiPost, apiPatch, apiDelete, postWithIdempotency, setActiveWorkspace, getActiveWorkspace, setActiveOrg, getActiveOrg, getUserContext } from "./api-client.js";
+import { apiGet, apiPost, apiPatch, apiPut, apiDelete, postWithIdempotency, setActiveWorkspace, getActiveWorkspace, setActiveOrg, getActiveOrg, getUserContext } from "./api-client.js";
 import { resolveExperimentHypothesis } from "./experiment-copy.js";
 import { controlGateGuidanceFor } from "./control-gate-guidance.js";
 import { getPersonLabel, lowerPerson } from "./person-label.js";
@@ -36,7 +36,7 @@ function daysRunningOf(exp) {
     const endMs = exp.completedAt ? new Date(exp.completedAt).getTime() : Date.now();
     return Math.max(0, Math.floor((endMs - startMs) / 86_400_000));
 }
-/** Find a unified variant by its key (e.g. "control", "variant_b"). */
+/** Find a unified variant by its key (e.g. "control", "variant_a"). */
 function findVariant(exp, key) {
     return exp.variants?.find((v) => v.key === key);
 }
@@ -667,9 +667,9 @@ export const toolDefinitions = {
                         payload: { content: args.controlContent },
                     },
                     {
-                        id: "v_b",
-                        key: "variant_b",
-                        label: "Variant B",
+                        id: "v_a",
+                        key: "variant_a",
+                        label: "Variant A",
                         surface: "mobile",
                         createdAt: createdAtIso,
                         description: "Modified content",
@@ -688,9 +688,9 @@ export const toolDefinitions = {
                         changes: [],
                     },
                     {
-                        id: "v_b",
-                        key: "variant_b",
-                        label: "Variant B",
+                        id: "v_a",
+                        key: "variant_a",
+                        label: "Variant A",
                         surface: "web",
                         mode,
                         createdAt: createdAtIso,
@@ -741,7 +741,7 @@ export const toolDefinitions = {
                 hypothesisId,
                 predictionId: args.predictionId,
                 primaryMetric,
-                allocation: { strategy: "hash", weights: { control: controlW, variant_b: 1 - controlW } },
+                allocation: { strategy: "hash", weights: { control: controlW, variant_a: 1 - controlW } },
                 secondaryMetrics: [],
                 // Explicit EXTRA guardrail when the agent named one (orthogonal to the
                 // goal). When omitted, the server auto-attaches the conversion-model
@@ -775,7 +775,7 @@ export const toolDefinitions = {
             let previewUrl = "";
             try {
                 const vu = new URL(exp.targetUrl || args.targetUrl);
-                vu.searchParams.set("_apex_preview", "variant_b");
+                vu.searchParams.set("_apex_preview", "variant_a");
                 vu.searchParams.set("_apex_exp", exp.id);
                 if (args.targetAnchor)
                     vu.hash = args.targetAnchor;
@@ -812,7 +812,7 @@ export const toolDefinitions = {
                 `3. Add: import { useApexVariant } from "@apex-inc/react"`,
                 `4. In the component, add: const variant = useApexVariant("${exp.id}")  // fires experiment_exposure automatically`,
                 `5. Wrap the target content in a conditional (fall back to control on null/error):`,
-                `   {variant === "variant_b" ? <VARIANT_CONTENT> : <CONTROL_CONTENT>}`,
+                `   {variant === "variant_a" || variant === "variant_b" ? <VARIANT_CONTENT> : <CONTROL_CONTENT>}`,
                 `6. Screenshots for the dashboard:`,
                 `   - Public web page: Apex auto-captures on create — nothing to do.`,
                 `   - localhost / auth-gated: capture BOTH arms, then call attach_experiment_asset({experimentId, variantKey, imageBase64}).`,
@@ -829,7 +829,7 @@ export const toolDefinitions = {
                 `2. Install the plugin: npm i @apex-inc/capacitor-plugin`,
                 `3. Add: import { Apex } from "@apex-inc/capacitor-plugin"`,
                 `4. Resolve the variant: const { value: variant } = await Apex.getVariant({ experimentId: "${exp.id}" })  // fires experiment_exposure automatically`,
-                `5. Render conditionally (fall back to control on null/error): variant === "variant_b" ? <VARIANT> : <CONTROL>`,
+                `5. Render conditionally (fall back to control on null/error): variant === "variant_a" || variant === "variant_b" ? <VARIANT> : <CONTROL>`,
                 `6. Screenshot both arms — add ONE debug-gated line on the screen that renders the variant, keyed to the resolved variant so it fires once the arm is on-screen:`,
                 `       useEffect(() => { if (variant) Apex.captureVariantScreenshot({ experimentId: "${exp.id}", variantKey: variant }); }, [variant]);`,
                 `   It is debug-gated (init Apex with debug:true) — a no-op in production, so real users are never screenshotted.`,
@@ -2063,6 +2063,163 @@ export const toolDefinitions = {
             return { content: [{ type: "text", text: lines.join("\n") }] };
         },
     },
+    list_product_costs: {
+        description: `${APEX} — What each product costs, and which ones Apex has no cost for. Lists every SKU with a declared cost PLUS every SKU the merchant's orders have sold in the last 30 days, so an uncosted product is visible rather than merely absent. Apex reports gross profit and LTGP:CAC only where cost is known, so the uncosted rows are the gap worth closing. Two columns matter: "orders" is the per-unit cost the merchant's own purchase events reported (preferred — it tracks their real costs over time), "declared" is a standing cost set in Apex that fills orders reporting none. Use this before set_product_cost so you never overwrite a cost that is already right.`,
+        schema: z.object({
+            uncostedOnly: z
+                .boolean()
+                .optional()
+                .describe("Only SKUs with no cost from either route — the actionable list."),
+            limit: z.number().optional().describe("Max rows to show (default 25)."),
+        }),
+        handler: async ({ uncostedOnly, limit, }) => {
+            const res = await apiGet("/api/products");
+            const all = res.data?.products ?? [];
+            if (all.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            // Not "no products" — an empty list here means Apex has neither a
+                            // declared cost NOR an order it could name a product from, and
+                            // those are different problems with different fixes.
+                            text: `${APEX} No products on file. Apex lists a product once it either has a declared cost or appears on an order — so send purchase events with product_id on each line item (see get_apex_spec for "order_placed"), or connect Shopify to import variant costs.`,
+                        },
+                    ],
+                };
+            }
+            const costKnown = (p) => p.costUsd !== undefined || p.unitCostUsd !== undefined;
+            const rows = uncostedOnly ? all.filter((p) => !costKnown(p)) : all;
+            const money = (n) => `$${n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+            const withCost = all.filter(costKnown).length;
+            const lines = [
+                `${APEX} Product cost — Apex knows the cost of ${withCost} of ${all.length} products`,
+                "═".repeat(40),
+                ...rows.slice(0, limit ?? 25).map((p) => {
+                    const observed = p.unitCostUsd !== undefined
+                        ? `orders ${money(p.unitCostUsd)}`
+                        : "orders: not reported";
+                    const declared = p.costUsd !== undefined
+                        ? `declared ${money(p.costUsd)}${p.costSource ? ` (${p.costSource})` : ""}${p.costEffectiveFrom ? ` from ${p.costEffectiveFrom.slice(0, 10)}` : ""}`
+                        : "declared: none";
+                    const sold = p.revenue !== undefined && p.revenue > 0
+                        ? ` · ${money(p.revenue)} in 30d`
+                        : "";
+                    return `  • ${p.name ?? p.itemKey} [${p.itemKey}]: ${observed} · ${declared}${sold}`;
+                }),
+            ];
+            if (rows.length > (limit ?? 25)) {
+                lines.push(`  … and ${rows.length - (limit ?? 25)} more`);
+            }
+            const uncosted = all.filter((p) => !costKnown(p)).length;
+            if (uncosted > 0) {
+                lines.push("", `${uncosted} product${uncosted === 1 ? "" : "s"} have no cost. The durable fix is sending unit_cost (per unit) on each purchase line item, which keeps up as costs change. Use set_product_cost to declare a standing cost where the checkout can't report one, or to backfill history.`);
+            }
+            if (res.metadata?.observed?.truncated) {
+                lines.push("", "(The 30-day sales scan hit its read cap, so this list is a lower bound — a SKU that sold only in the unread remainder is missing.)");
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        },
+    },
+    set_product_cost: {
+        description: `${APEX} — Declare what one product costs per unit, so Apex can report gross profit on orders that didn't carry a cost of their own. PREFER instrumenting unit_cost on purchase line items instead where you can: an order carries the cost that was true when it happened, whereas a standing cost declared here is a snapshot that goes stale silently. Use this to backfill history, or for a SKU whose checkout can't report cost. NEVER invent or estimate a cost — a fabricated margin looks measured and is not, and the merchant has no way to tell downstream. Ask them for the number. Rules: the cost is PER UNIT (not a line total), it never overrides a cost an order reported for itself, and it never applies backward before effective_from.`,
+        schema: z.object({
+            item_key: z
+                .string()
+                .describe("The product identifier Apex knows this SKU by — the product_id or sku on the merchant's order lines. Get it from list_product_costs."),
+            cost_usd: z
+                .number()
+                .describe("Cost PER UNIT in USD. A four-figure value on a low-priced item is usually cents typed as dollars; values above 1000000 are refused."),
+            effective_from: z
+                .string()
+                .optional()
+                .describe("ISO date the cost applies from. Defaults to NOW, which is deliberate — defaulting backward would restate the merchant's whole order history at today's supplier price. Pass an explicit date only when they know the older price."),
+            name: z
+                .string()
+                .optional()
+                .describe("Display name, if Apex has no name for this SKU yet."),
+        }),
+        handler: async ({ item_key, cost_usd, effective_from, name, }) => {
+            const res = await apiPut(`/api/products/${encodeURIComponent(item_key)}/cost`, {
+                cost_usd,
+                ...(effective_from ? { effective_from } : {}),
+                ...(name ? { name } : {}),
+            });
+            const d = res.data;
+            if (d && !d.changed) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} ${item_key} already had that cost on file — nothing changed, no log entry written.`,
+                        },
+                    ],
+                };
+            }
+            const from = d?.entry?.effectiveFrom?.slice(0, 10) ?? "now";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${APEX} Set ${item_key} to $${cost_usd.toFixed(2)} per unit, applying from ${from} forward. Orders before that date, and orders that reported their own cost, are untouched. Check list_product_costs to see what's still uncosted.`,
+                    },
+                ],
+            };
+        },
+    },
+    upload_product_catalog: {
+        description: `${APEX} — Tell Apex what the merchant sells, in bulk, BEFORE the first sale. Every other way a product reaches Apex needs a sale to have happened already, so a merchant setting up pre-launch has a catalog Apex knows nothing about. Use this when you can read their catalog from somewhere — a products table, a Shopify/Stripe export, a CSV they hand you. NEVER invent, estimate, or derive a cost from a price: a fabricated margin looks measured and nobody downstream can tell. Ask them, or send only the fields you actually know. cost_usd is applied to orders that report no cost of their own, from effective_from forward. price_usd is reference only — revenue, LTV and gross profit always come from what orders actually report, so a price here can never distort them; it makes the catalog complete before launch and lets Apex flag it when real orders disagree with it. Re-running with the same data is safe. Max 500 products per call — page through a larger catalog. This does not replace instrumenting unit_cost on purchase line items, which stays the durable fix because an order then carries the cost that was true when it happened; a catalog cost is a snapshot that goes stale silently.`,
+        schema: z.object({
+            products: z
+                .array(z.object({
+                item_key: z
+                    .string()
+                    .describe("The identifier the merchant's ORDERS will send for this SKU — their product_id or sku. If this doesn't match what the order lines carry, Apex can't connect the two."),
+                name: z.string().optional().describe("Display name."),
+                cost_usd: z
+                    .number()
+                    .optional()
+                    .describe("What the product costs the MERCHANT, per unit. Omit rather than guess."),
+                price_usd: z
+                    .number()
+                    .optional()
+                    .describe("What the merchant SELLS it for, per unit. Reference data — never used as revenue."),
+                effective_from: z
+                    .string()
+                    .optional()
+                    .describe("ISO date cost_usd applies from. Defaults to now, which is deliberate — defaulting backward would restate order history at today's supplier price."),
+            }))
+                .describe("Up to 500 products. Each needs item_key plus at least one of name, cost_usd, price_usd."),
+        }),
+        handler: async ({ products, }) => {
+            const res = await apiPost("/api/products", { products });
+            const d = res.data;
+            if (!d) {
+                return {
+                    content: [
+                        { type: "text", text: `${APEX} Catalog upload returned no result.` },
+                    ],
+                };
+            }
+            const parts = [
+                `${APEX} Saved ${d.upserted} product${d.upserted === 1 ? "" : "s"} — ${d.costChanged} with a new cost, ${d.priceSet} with a price.`,
+            ];
+            if (d.rejected > 0) {
+                // Named rather than counted: a rejected row is a line the merchant can
+                // fix, and "12 rejected" sends them back through the whole file.
+                const listed = (d.errors ?? [])
+                    .slice(0, 10)
+                    .map((e) => `  - ${e.item_key || "(no item_key)"}: ${e.error}`)
+                    .join("\n");
+                parts.push(`${d.rejected} row${d.rejected === 1 ? "" : "s"} rejected:\n${listed}`);
+                if ((d.errors?.length ?? 0) > 10) {
+                    parts.push(`…and ${(d.errors?.length ?? 0) - 10} more.`);
+                }
+            }
+            parts.push(`Costs apply only to orders that report no cost of their own. The durable fix is still sending unit_cost on each purchase line item — run list_product_costs once orders start arriving to see what's still uncovered.`);
+            return { content: [{ type: "text", text: parts.join("\n\n") }] };
+        },
+    },
     get_ecommerce_returns: {
         description: `${APEX} — E-commerce returns & refunds: refund rate (money back, order basis), return rate (goods back — separate metric, never summed), reason breakdown, refund cycle time, AOV, and repeat purchase. Refund data lands automatically from Stripe; return_requested / return_completed events power the goods-back story.`,
         schema: z.object({
@@ -2936,7 +3093,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     generate_communications: {
-        description: "Create your communication program from recommendations. Pass catalog entry IDs to generate tenant communications with pre-written copy.",
+        description: "Create your communication program from recommendations. Pass catalog entry IDs to generate tenant communications with pre-written copy. Each new letter wears the workspace default Theme (Title / Body / Button look is snapshotted; catalog copy is not rewritten to match). Preview with preview_communication to see theme roles vs block overrides.",
         schema: z.object({
             catalogEntryIds: z.array(z.string()).describe("IDs from the recommendation output to generate"),
         }),
@@ -3036,6 +3193,76 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
             };
         },
     },
+    list_communication_themes: {
+        description: "List workspace communication Themes (the look: fonts, sizes, colors, Title/Body/Button roles). A Theme is not a Template — Templates are the job (event, slots, copy). Activate a Template with no extra theme step; new emails wear the workspace default theme. Apply writes drafts only; the merchant still publishes each email.",
+        schema: z.object({}),
+        handler: async () => {
+            const json = await apiGet("/api/communications/themes");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(json, null, 2),
+                    },
+                ],
+            };
+        },
+    },
+    create_communication_theme: {
+        description: "Create a communication Theme (the look). Clone an existing theme with clone_from_id, or pass style/roles. Does not assign other emails. Tell the merchant to publish emails after applying.",
+        schema: z.object({
+            name: z.string().min(1).max(60),
+            clone_from_id: z.string().optional(),
+            style: z.record(z.string(), z.unknown()).optional(),
+            roles: z.record(z.string(), z.unknown()).optional(),
+        }),
+        handler: async (args) => {
+            const data = await apiPost("/api/communications/themes", {
+                name: args.name,
+                cloneFromId: args.clone_from_id,
+                style: args.style,
+                roles: args.roles,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        },
+    },
+    update_communication_theme: {
+        description: "Update a communication Theme's name, style tokens, or Title/Body/Button roles. Does not rewrite other emails. Use apply_communication_theme to draft the look onto chosen emails. set_default makes new activations wear this theme.",
+        schema: z.object({
+            theme_id: z.string(),
+            name: z.string().min(1).max(60).optional(),
+            style: z.record(z.string(), z.unknown()).optional(),
+            roles: z.record(z.string(), z.unknown()).optional(),
+            set_default: z.boolean().optional(),
+        }),
+        handler: async (args) => {
+            const data = await apiPatch(`/api/communications/themes/${encodeURIComponent(args.theme_id)}`, {
+                name: args.name,
+                style: args.style,
+                roles: args.roles,
+                setDefault: args.set_default,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        },
+    },
+    apply_communication_theme: {
+        description: "Apply a Theme's look onto chosen communication Templates. Default apply is draft — recipients keep the old look until the merchant publishes. apply=live uses the look on the next send. Omit comm_ids to target every template already on this theme. Never group emails by experiment catalog ids; a shop's order-updates series is the same object.",
+        schema: z.object({
+            theme_id: z.string(),
+            comm_ids: z.array(z.string()).optional(),
+            apply: z.enum(["draft", "live"]).optional(),
+        }),
+        handler: async (args) => {
+            const data = await apiPost(`/api/communications/themes/${encodeURIComponent(args.theme_id)}/apply`, { commIds: args.comm_ids, apply: args.apply });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        },
+    },
     edit_communication: {
         description: "Update a communication's subject, body, CTA, channels, or status. Pass the communication ID and the fields to update. For blank/builder comms, the headline/body/ctaLabel/ctaUrl slots are synced into the rendered email body — verify with preview_communication.\n\nA communication's Control is protected when it won an experiment or a published journey is sending it. Editing it then requires `intent`: \"compete\" adds your edit as a variant and measures it against the current content (nothing changes for recipients yet); \"replace\" makes your edit what everyone receives and supersedes any prior win. WHEN IN DOUBT, USE \"compete\" — it is recoverable, \"replace\" discards a measured result permanently. The server returns 409 intent_required with both options if you omit it.",
         schema: z.object({
@@ -3161,7 +3388,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     preview_communication: {
-        description: "See the rendered communication with your brand applied. Returns the subject, the rendered plain-text body (so you can verify edits actually landed), and a browser preview link.",
+        description: "See the rendered communication with your brand and Theme applied. Returns the subject, the rendered plain-text body, Title/Body/Button roles, which blocks override the theme, and a browser preview link.",
         schema: z.object({
             communicationId: z.string().describe("The communication ID to preview"),
         }),
@@ -3171,6 +3398,21 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
             const subject = (data.subject ?? "").replace(/<[^>]+>/g, "");
             const text = (data.text ?? "").trim();
             const link = appUrl(`/dashboard/communications/${args.communicationId}`);
+            const look = data.themeLook;
+            const roleLines = look?.roles
+                ? Object.entries(look.roles).map(([role, style]) => {
+                    const bits = [
+                        style.type,
+                        style.headingLevel,
+                        style.align,
+                        style.width,
+                    ].filter(Boolean);
+                    return `  ${role}: ${bits.join(" / ") || "(default)"}`;
+                })
+                : ["  (no role snapshot — look is whatever is baked on the blocks)"];
+            const overrideLines = look?.overrides && look.overrides.length > 0
+                ? look.overrides.map((row) => `  ${row.label}: ${row.keys.join(", ")}`)
+                : ["  (none)"];
             return {
                 content: [
                     {
@@ -3181,6 +3423,12 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                             `Rendered body:`,
                             text ? text : "(empty — add content via edit_communication)",
                             ``,
+                            `Theme roles:`,
+                            ...roleLines,
+                            ``,
+                            `Block overrides:`,
+                            ...overrideLines,
+                            ``,
                             `Open in the browser to see the full styled email: ${link}`,
                         ].join("\n"),
                     },
@@ -3188,6 +3436,24 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
             };
         },
     },
+    add_communication_variant: {
+        description: "Add a content variant (Variant A, B, …) to a communication. Clones the current Control into a new column so you can run a content experiment. Does not change what recipients get until you publish. Theme look is inherited; do not set per-block align here.",
+        schema: z.object({
+            communicationId: z.string().describe("The communication to add a variant to"),
+            label: z.string().optional().describe("Optional column label (e.g. Variant A)"),
+        }),
+        handler: async (args) => {
+            const data = await apiPost(`/api/communications/${args.communicationId}/variants`, { label: args.label });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Variant added.\n\n${JSON.stringify(data, null, 2)}`,
+                    },
+                ],
+            };
+        },
+    },
     send_test_communication: {
         description: "Send a test email to yourself. The email will be sent to the logged-in user's email address.",
         schema: z.object({