@apex-inc/mcp-server 0.15.0 → 0.17.0

package/dist/tools.js

@@ -53,6 +53,24 @@ function titleCaseEvent(event) {
         .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
         .join(" ");
 }
+/**
+ * Query string for the pack report windows: relative (`days` / `months`)
+ * or explicit `start` + `end` (YYYY-MM-DD, both required together —
+ * explicit bounds win server-side).
+ */
+function windowQuery(opts) {
+    const params = new URLSearchParams();
+    if (opts.days)
+        params.set("days", String(opts.days));
+    if (opts.months)
+        params.set("months", String(opts.months));
+    if (opts.start && opts.end) {
+        params.set("start", opts.start);
+        params.set("end", opts.end);
+    }
+    const qs = params.toString();
+    return qs ? `?${qs}` : "";
+}
 function errMsg(err) {
     return err instanceof Error ? err.message : String(err);
 }
@@ -1599,6 +1617,327 @@ export const toolDefinitions = {
             };
         },
     },
+    get_channel_economics: {
+        description: `${APEX} — "Where should my next dollar go?" Per acquisition channel (raw first-touch): gross-margin-adjusted LTV:CAC, payback months, CAC, and customers, split into Acquisition (paid) vs Leverage (owned/organic, no spend). Computed from real contacts + spend + revenue — metrics with missing inputs are shown as "—", never fabricated. Free intelligence; the verdict is never gated.`,
+        schema: z.object({
+            days: z
+                .union([z.number(), z.literal("all")])
+                .optional()
+                .describe("Trailing window in days, or 'all' for since-inception (default)."),
+        }),
+        handler: async ({ days }) => {
+            const q = days && days !== "all" ? `?days=${days}` : "?days=all";
+            const res = await apiGet(`/api/channels/economics${q}`);
+            const channels = res.data?.channels ?? [];
+            if (channels.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} No channel economics yet — connect attributed traffic (Apex Links auto-tag it) and revenue so acquisition channels can be measured.`,
+                        },
+                    ],
+                };
+            }
+            const label = (slug) => ({
+                linkedin: "LinkedIn Ads",
+                google: "Google",
+                meta: "Meta",
+                microsoft: "Microsoft Ads",
+                tiktok: "TikTok",
+                twitter: "Twitter / X",
+                direct: "Direct",
+                email: "Email",
+                affiliate: "Partner Network",
+            })[slug] ?? slug.charAt(0).toUpperCase() + slug.slice(1);
+            const money = (n) => n == null ? "—" : `$${Math.round(n).toLocaleString()}`;
+            const ratio = (r) => (r == null ? "—" : `${r.toFixed(2)}x`);
+            const ranked = [...channels].sort((a, b) => (b.ltvCacRatio ?? -1) - (a.ltvCacRatio ?? -1));
+            const acquisition = ranked.filter((c) => c.spend !== null && c.spend > 0);
+            const leverage = ranked.filter((c) => c.spend === null || c.spend === 0);
+            const fmt = (c) => `  • ${label(c.channel)}: ${ratio(c.ltvCacRatio)} LTV:CAC · payback ${c.paybackMonths != null ? `${c.paybackMonths}mo` : "—"} · CAC ${money(c.cac)} · ${c.customers.toLocaleString()} customers`;
+            const lines = [
+                `${APEX} Channel economics — gross-margin LTV:CAC`,
+                "═".repeat(40),
+            ];
+            if (res.data?.needsReferee) {
+                lines.push("Revenue figures hidden: two live revenue sources with no referee picked. Choose one in Connect revenue.", "");
+            }
+            if (acquisition.length > 0) {
+                lines.push("Acquisition (paid):", ...acquisition.map(fmt), "");
+            }
+            if (leverage.length > 0) {
+                lines.push("Leverage (owned / organic):", ...leverage.map(fmt), "");
+            }
+            lines.push("3-5x LTV:CAC is healthy; <1x loses margin on every customer; >5x is likely underinvested.");
+            if (res.data?.grossMarginFromDefault) {
+                lines.push(`(Using a default ${res.data.grossMargin != null
+                    ? `${Math.round(res.data.grossMargin * 100)}%`
+                    : ""} gross margin — set your real margin in workspace settings to sharpen this.)`);
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        },
+    },
+    // ─── Vertical Widget Packs read tools (2026-07-02) ─────────────────────
+    // One tool per pack read API. All aggregate-only (analytics:read scope);
+    // small-n suppression applies to API responses exactly as to widgets.
+    get_saas_recurring_revenue: {
+        description: `${APEX} — SaaS recurring-revenue economics: MRR, ARR, the monthly waterfall (new / expansion / reactivation / contraction / churn — accounting-identity tested), and NRR/GRR for the last complete month. Computed from materialized monthly snapshots (calendar months, UTC); the current month is flagged in-progress. NRR/GRR read "collecting history" until 13 months of snapshots exist — never fabricated.`,
+        schema: z.object({
+            months: z
+                .number()
+                .optional()
+                .describe("Months of waterfall history to include (2-36, default 13)."),
+            start: z
+                .string()
+                .optional()
+                .describe("Explicit window start, YYYY-MM-DD (mapped to calendar months; use with end — overrides months)."),
+            end: z
+                .string()
+                .optional()
+                .describe("Explicit window end, YYYY-MM-DD (use with start)."),
+        }),
+        handler: async ({ months, start, end }) => {
+            const q = windowQuery({ months, start, end });
+            const res = await apiGet(`/api/saas/recurring-revenue${q}`);
+            const d = res.data;
+            if (!d?.hasData) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} No MRR state yet — connect Stripe or send subscription events (subscription_started / subscription_event with amount + period_type) and monthly snapshots build from there.`,
+                        },
+                    ],
+                };
+            }
+            const money = (n) => n == null ? "—" : `$${Math.round(n).toLocaleString()}`;
+            const pct = (r) => r == null ? "collecting history" : `${Math.round(r * 1000) / 10}%`;
+            const lines = [
+                `${APEX} Recurring revenue`,
+                "═".repeat(40),
+                `MRR ${money(d.currentMrr)} (month in progress) · ARR ${money(d.currentArr)} · ${d.payingAccounts ?? "—"} paying accounts`,
+                `NRR ${pct(d.retention?.nrr ?? null)} · GRR ${pct(d.retention?.grr ?? null)} (trailing 12mo, ${d.retention?.cohortSize ?? 0}-account cohort)`,
+                "",
+                "Waterfall (last months):",
+                ...d.waterfall
+                    .slice(-6)
+                    .map((m) => `  • ${m.month}${m.inProgress ? " (in progress)" : ""}: ${money(m.startMrr)} → ${money(m.endMrr)}  (+${money(m.newMrr)} new, +${money(m.expansionMrr)} expansion, +${money(m.reactivationMrr)} reactivation, −${money(m.contractionMrr)} contraction, −${money(m.churnedMrr)} churn)`),
+            ];
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        },
+    },
+    get_saas_expansion: {
+        description: `${APEX} — SaaS expansion economics: expansion vs contraction MRR for the last complete month, accounts expanding (counts — small-n honest), and seat growth from seat_count. Metrics with missing inputs come back null, never fabricated.`,
+        schema: z.object({
+            months: z
+                .number()
+                .optional()
+                .describe("Months of series history to include (2-36, default 13)."),
+            start: z
+                .string()
+                .optional()
+                .describe("Explicit window start, YYYY-MM-DD (mapped to calendar months; use with end — overrides months)."),
+            end: z
+                .string()
+                .optional()
+                .describe("Explicit window end, YYYY-MM-DD (use with start)."),
+        }),
+        handler: async ({ months, start, end }) => {
+            const q = windowQuery({ months, start, end });
+            const res = await apiGet(`/api/saas/expansion${q}`);
+            const d = res.data;
+            if (!d?.hasData) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} No subscription data yet — expansion metrics unlock once MRR snapshots exist.`,
+                        },
+                    ],
+                };
+            }
+            const money = (n) => n == null ? "—" : `$${Math.round(n).toLocaleString()}`;
+            const seatsLine = d.seatCount != null
+                ? `Seats: ${d.seatCount}${d.seatCountPrevMonth != null ? ` (${d.seatCount - d.seatCountPrevMonth >= 0 ? "+" : ""}${d.seatCount - d.seatCountPrevMonth} vs last month)` : ""}`
+                : "Seats: — (send seat_count on subscription events to unlock)";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${APEX} Expansion (last complete month)`,
+                            "═".repeat(40),
+                            `Expansion MRR ${money(d.expansionMrrLastMonth)} · Contraction MRR ${money(d.contractionMrrLastMonth)}`,
+                            `Accounts expanding: ${d.expandedAccounts ?? "—"} of ${d.payingAccountsAtStart ?? "—"} paying at month start`,
+                            seatsLine,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    get_ecommerce_product_sales: {
+        description: `${APEX} — E-commerce product sales: top products by revenue with the per-product view → add-to-cart → purchase funnel and refund counts. Products need a product_id on commerce events; never-wired signals are reported as unwired, not zero.`,
+        schema: z.object({
+            days: z.number().optional().describe("Trailing window in days (default 90, max 180)."),
+            start: z
+                .string()
+                .optional()
+                .describe("Explicit window start, YYYY-MM-DD (use with end — overrides days)."),
+            end: z
+                .string()
+                .optional()
+                .describe("Explicit window end, YYYY-MM-DD (use with start)."),
+        }),
+        handler: async ({ days, start, end }) => {
+            const q = windowQuery({ days, start, end });
+            const res = await apiGet(`/api/ecommerce/product-sales${q}`);
+            const d = res.data;
+            if (!d?.hasData) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} No product-scoped events yet — fire product_view / add_to_cart / purchases with a product_id.`,
+                        },
+                    ],
+                };
+            }
+            const money = (n) => `$${Math.round(n).toLocaleString()}`;
+            const lines = [
+                `${APEX} Product sales — ${money(d.totals.revenue)} product revenue, ${d.totals.purchases} purchases`,
+                "═".repeat(40),
+                ...d.items
+                    .slice(0, 10)
+                    .map((i) => `  • ${i.label ?? i.itemKey}${i.category ? ` [${i.category}]` : ""}: ${money(i.revenue)} · ${i.views} views → ${i.adds} adds → ${i.purchases} purchases${i.refunds > 0 ? ` · ${i.refunds} refunds` : ""}`),
+            ];
+            if (!d.wired.views)
+                lines.push("(product_view not wired — funnel rates unavailable)");
+            return { content: [{ type: "text", text: lines.join("\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({
+            days: z.number().optional().describe("Trailing window in days (default 90, max 180)."),
+            start: z
+                .string()
+                .optional()
+                .describe("Explicit window start, YYYY-MM-DD (use with end — overrides days)."),
+            end: z
+                .string()
+                .optional()
+                .describe("Explicit window end, YYYY-MM-DD (use with start)."),
+        }),
+        handler: async ({ days, start, end }) => {
+            const q = windowQuery({ days, start, end });
+            const res = await apiGet(`/api/ecommerce/returns${q}`);
+            const d = res.data;
+            if (!d?.hasData) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} No order data in the window yet — connect Stripe or send purchase events.`,
+                        },
+                    ],
+                };
+            }
+            const lines = [
+                `${APEX} Returns & refunds`,
+                "═".repeat(40),
+                `Refunded orders: ${d.refundedOrders} of ${d.ordersInWindow} ($${Math.round(d.refundedAmount).toLocaleString()})`,
+                `Returns (goods back): ${d.returnsCompleted ?? "— (wire return_completed to unlock)"}`,
+                `Refund cycle: ${d.refundCycleHours != null ? `${d.refundCycleHours}h median` : "—"} · AOV: ${d.aov != null ? `$${d.aov}` : "—"} · Repeat: ${d.repeatCustomers} of ${d.purchasingCustomers} customers`,
+            ];
+            if (d.reasons.length > 0) {
+                lines.push("", "Reasons:", ...d.reasons.map((r) => `  • ${r.reason}: ${r.count}`));
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        },
+    },
+    get_marketplace_metrics: {
+        description: `${APEX} — Marketplace health across six pillars: liquidity (search→transaction, match rate, zero-result searches, unfulfilled demand), supply & demand balance, economics (GMV vs the take — fee_amount is the platform's revenue, GMV never inflates LTV), buyer retention, trust rates, and concentration risk. Sliceable by category / geo / price_band (low-volume slices are suppressed for privacy). Metrics whose events aren't wired come back as unwired hints, never fabricated zeros.`,
+        schema: z.object({
+            days: z.number().optional().describe("Trailing window in days (default 90, max 180)."),
+            start: z
+                .string()
+                .optional()
+                .describe("Explicit window start, YYYY-MM-DD (use with end — overrides days)."),
+            end: z
+                .string()
+                .optional()
+                .describe("Explicit window end, YYYY-MM-DD (use with start)."),
+            category: z.string().optional().describe("Slice: listing category."),
+            geo: z.string().optional().describe("Slice: transaction geo."),
+            priceBand: z.string().optional().describe("Slice: price band (e.g. '100-250')."),
+        }),
+        handler: async ({ days, start, end, category, geo, priceBand, }) => {
+            const params = new URLSearchParams();
+            if (days)
+                params.set("days", String(days));
+            if (start && end) {
+                params.set("start", start);
+                params.set("end", end);
+            }
+            if (category)
+                params.set("category", category);
+            if (geo)
+                params.set("geo", geo);
+            if (priceBand)
+                params.set("price_band", priceBand);
+            const qs = params.toString();
+            const res = await apiGet(`/api/marketplace/metrics${qs ? `?${qs}` : ""}`);
+            const d = res.data;
+            if (!d?.hasData) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} No marketplace events yet — wire seller_signup, listing_created, search, offer_submitted, and transaction_completed (with fee_amount, buyer_id, seller_id).`,
+                        },
+                    ],
+                };
+            }
+            if (d.sliceSuppressed) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} That slice has too few participants to report honestly (privacy floor). Broaden the slice.`,
+                        },
+                    ],
+                };
+            }
+            const money = (n) => n == null ? "—" : `$${Math.round(n).toLocaleString()}`;
+            const L = d.liquidity;
+            const lines = [
+                `${APEX} Marketplace metrics`,
+                "═".repeat(40),
+                `Liquidity: ${L.searchersWhoTransacted}/${L.searchers} searchers transacted (7d)` +
+                    (L.searchesWithResultCount > 0
+                        ? ` · ${L.zeroResultSearches}/${L.searchesWithResultCount} zero-result searches`
+                        : "") +
+                    ` · ${L.transactions} transactions / ${L.offers} offers` +
+                    (L.medianHoursToMatch != null ? ` · ${L.medianHoursToMatch}h median to match` : "") +
+                    ` · ${L.buyersUnfulfilled}/${L.buyersWithIntent} buyers unfulfilled`,
+                `Supply & demand: ${d.supplyDemand.activeBuyers} buyers · ${d.supplyDemand.activeSellers} sellers (${d.supplyDemand.sellersWithTransaction} transacting) · ${d.supplyDemand.newListings} new listings`,
+                `Economics: GMV ${money(d.economics.gmv)} (refund-adj ${money(d.economics.refundAdjustedGmv)}) · take ${money(d.economics.netRevenue)}${d.economics.takeRate != null ? ` (${Math.round(d.economics.takeRate * 1000) / 10}%)` : ""} · contribution ${money(d.economics.contributionMargin)} · payouts ${money(d.economics.sellerPayouts)} · AOV ${money(d.economics.aov)}`,
+                d.demandMix
+                    ? `Demand mix: paid ${money(d.demandMix.paidGmv)} · organic ${money(d.demandMix.organicGmv)} · unattributed ${money(d.demandMix.unattributedGmv)} (buyer first-touch)`
+                    : "Demand mix: — (needs identified buyers with acquisition attribution)",
+                `Trust: ${d.trust.canceled} cancels · ${d.trust.refunded} refunds · ${d.trust.disputes} disputes over ${d.trust.transactions} transactions` +
+                    (d.trust.averageRating != null ? ` · ${d.trust.averageRating}/5 avg rating` : ""),
+                d.concentration.suppressed
+                    ? `Concentration: needs ≥5 sellers (currently ${d.concentration.sellerCount}) for an honest read`
+                    : `Concentration: top 10% of sellers = ${Math.round((d.concentration.topSellerGmvShare?.top10 ?? 0) * 1000) / 10}% of GMV (${d.concentration.sellerCount} sellers)`,
+            ];
+            if (!d.wired.searches)
+                lines.push("(search not wired — liquidity is partial)");
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        },
+    },
     suggest_experiment: {
         description: `${APEX} — Get smart experiment suggestions based on context. Analyzes your assumptions, past experiments, and confidence gaps to recommend what to test next.`,
         schema: z.object({
@@ -2079,19 +2418,20 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     identify_user: {
-        description: `${APEX} — Identify a user by email for identity stitching. Works identically to the SDK's identify() and the snippet's apex.identify(). Links an anonymous visitor to a known email/lead.`,
+        description: `${APEX} — Identify a user by email for identity stitching. Works identically to the SDK's identify() and the snippet's apex.identify(). Links an anonymous visitor to a known email/lead. Pass avatarUrl (a canonical attribute) to give the Contact a profile photo that renders across Apex — Customers list, detail page, and Live Customers widget.`,
         schema: z.object({
             email: z.string().describe("User email address"),
             name: z.string().optional().describe("User name"),
             company: z.string().optional().describe("Company name"),
+            avatarUrl: z.string().optional().describe("Profile photo URL (https). Maps to the canonical avatar_url attribute; renders across Apex. Validated on write — non-https/invalid URLs are dropped and the UI falls back to initials. From OIDC logins this is the `picture` claim (`photoURL` in Firebase)."),
             metadata: z.record(z.unknown()).optional().describe("Additional traits"),
         }),
-        handler: async ({ email, name, company, metadata }) => {
+        handler: async ({ email, name, company, avatarUrl, metadata }) => {
             await apiPost("/api/identity/stitch", {
                 visitorId: `mcp-${email}`,
                 email,
                 workspaceKey: (process.env.APEX_WORKSPACE_KEY || process.env.APEX_PROJECT_KEY) || "default",
-                metadata: { name, company, ...metadata, source: "mcp" },
+                metadata: { name, company, avatar_url: avatarUrl, ...metadata, source: "mcp" },
             });
             return {
                 content: [{
@@ -2150,6 +2490,52 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
             };
         },
     },
+    define_event: {
+        description: `${APEX} — Define a governed custom event in the workspace's Schema (the customer-extensible registry). Promotes one of the merchant's own events to a first-class, typed, versioned definition that behaves like a canonical Apex Spec event (selectable as a journey trigger/goal, resolvable as comm tokens, validated at ingest). Names must be snake_case and CANNOT shadow a canonical Apex Spec event — call get_event_spec first and reuse the canonical event when one fits. Propose the schema from the merchant's observed payloads (get_schema) and codebase, then confirm with them before defining.`,
+        schema: z.object({
+            name: z.string().describe("snake_case event name, not already in the Apex Spec"),
+            description: z.string().describe("One sentence: when this event fires"),
+            fields: z
+                .record(z.string())
+                .describe('Field name -> type. Types: "string" | "number" | "boolean" | "object" | "array"; append "?" for optional (e.g. {"widget_id":"string","width":"number?"})'),
+            scope: z
+                .enum(["workspace", "org"])
+                .optional()
+                .describe("workspace (default) or org (shared across the org's workspaces)"),
+            primary_metric: z
+                .boolean()
+                .optional()
+                .describe("True if this is a conversion/outcome that can be a journey goal"),
+            recommended_transport: z
+                .enum(["client", "server", "either"])
+                .optional()
+                .describe("Where to fire it: server for money-truth, client for intent/engagement"),
+        }),
+        handler: async (args) => {
+            const res = await apiPost("/api/schema/events", {
+                name: args.name,
+                description: args.description,
+                fields: args.fields,
+                scope: args.scope,
+                primaryMetric: args.primaryMetric,
+                recommendedTransport: args.recommendedTransport,
+            });
+            if (res.error) {
+                const hint = res.suggestion
+                    ? ` Use the canonical event "${res.suggestion}" instead.`
+                    : "";
+                return { content: [{ type: "text", text: `Could not define "${args.name}": ${res.error}.${hint}` }] };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Defined governed event "${res.name}" (SchemaVer ${res.schemaVer ?? "1-0-0"}, draft). It's now selectable as a trigger/goal and resolvable as comm tokens once published.`,
+                    },
+                ],
+            };
+        },
+    },
     log_prediction: {
         description: `${APEX} — Log a prediction about a metric change. Feeds the calibration loop. Before calling, present the metric, expected change, and confidence as options the user can pick from or adjust.`,
         schema: z.object({
@@ -3889,5 +4275,136 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             };
         },
     },
+    // ─── Conversions & Targets (Goals & Conversions Convergence — PR8) ──────────
+    // A Conversion is the merchant-facing definition of a valued action (the
+    // owned-event matcher managed on /dashboard/conversions). A Target is an
+    // aggregate KPI number to hit by a date. "Goal" is retired as a noun.
+    list_conversions: {
+        description: `${APEX} — List the workspace's Conversions (the owned-event definitions of valued actions, e.g. "Purchase", "Signup"). Call this when the user asks what conversions are defined, or before creating an experiment/journey that needs an objective. The one flagged primary drives default experiment objectives, funnel metrics, and scoring.`,
+        schema: z.object({}),
+        handler: async () => {
+            const conversions = await apiGet("/api/conversion-goals");
+            const active = conversions.filter((c) => !c.archivedAt);
+            if (active.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No conversions defined yet. Use create_conversion to define one (e.g. a custom_event named 'purchase').",
+                        },
+                    ],
+                };
+            }
+            const lines = active.map((c) => `• ${c.name} (${c.id}) — ${c.type}${c.eventName ? ` [${c.eventName}]` : ""}${c.isPrimary ? " ★ primary" : ""}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${active.length} conversion${active.length === 1 ? "" : "s"}:\n\n${lines.join("\n")}`,
+                    },
+                ],
+            };
+        },
+    },
+    create_conversion: {
+        description: `${APEX} — Define a new Conversion (an owned-event definition of a valued action). Most conversions are a custom_event with an eventName (e.g. "purchase", "signup") matching an Apex Spec event you send via track. Set isPrimary to make it the default objective for experiments and the headline funnel metric.`,
+        schema: z.object({
+            name: z.string().describe('Human label, e.g. "Purchase" or "Signup"'),
+            type: z
+                .enum([
+                "form_submit",
+                "click",
+                "pageview",
+                "custom_event",
+                "file_download",
+                "engaged_time",
+            ])
+                .describe("How the conversion is detected. custom_event is the most common (set eventName)."),
+            eventName: z
+                .string()
+                .optional()
+                .describe("For custom_event: the Apex Spec event name to match, e.g. 'purchase'."),
+            selector: z
+                .string()
+                .optional()
+                .describe("For click/form_submit: a CSS selector to match."),
+            targetUrl: z
+                .string()
+                .optional()
+                .describe("For pageview: the URL (or path) that counts as a completion."),
+            isPrimary: z
+                .boolean()
+                .optional()
+                .describe("Make this the primary conversion (only one can be primary)."),
+        }),
+        handler: async (args) => {
+            const payload = {
+                name: args.name,
+                type: args.type,
+                metricType: "binary",
+                isPrimary: args.isPrimary ?? false,
+                ...(args.eventName ? { eventName: args.eventName } : {}),
+                ...(args.selector ? { selector: args.selector } : {}),
+                ...(args.targetUrl ? { targetUrl: args.targetUrl } : {}),
+            };
+            const data = await apiPost("/api/conversion-goals", payload);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Conversion created.\n\n${JSON.stringify(data, null, 2)}`,
+                    },
+                ],
+            };
+        },
+    },
+    set_primary_conversion: {
+        description: `${APEX} — Mark a Conversion as the primary one. Experiments without an explicit objective default to the primary conversion, and the headline funnel + scoring use it. Pass the conversion id from list_conversions.`,
+        schema: z.object({
+            conversionId: z.string().describe("The conversion id to promote (from list_conversions)."),
+        }),
+        handler: async ({ conversionId }) => {
+            const data = await apiPatch("/api/conversion-goals", { id: conversionId, isPrimary: true });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Primary conversion set.\n\n${JSON.stringify(data, null, 2)}`,
+                    },
+                ],
+            };
+        },
+    },
+    create_target: {
+        description: `${APEX} — Create a Target: an aggregate KPI number to hit by a date (MRR, pipeline, "1,000 signups by Q3"). Optionally bind it to a Conversion (sourceConversionId from list_conversions) to auto-count progress from that conversion's completions; otherwise it's a manual number you update yourself.`,
+        schema: z.object({
+            metric: z.string().describe('What you\'re tracking, e.g. "MRR", "Signups", "Pipeline".'),
+            target: z.number().describe("The numeric goal to reach."),
+            deadline: z.string().describe('Target date, ISO "YYYY-MM-DD".'),
+            sourceConversionId: z
+                .string()
+                .optional()
+                .describe("Optional: bind to a Conversion (from list_conversions) to auto-track progress."),
+        }),
+        handler: async (args) => {
+            const payload = {
+                metric: args.metric,
+                target: args.target,
+                deadline: args.deadline,
+                ...(args.sourceConversionId
+                    ? { sourceConversionId: args.sourceConversionId }
+                    : {}),
+            };
+            const data = await apiPost("/api/targets", payload);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Target created.\n\n${JSON.stringify(data, null, 2)}`,
+                    },
+                ],
+            };
+        },
+    },
 };
 //# sourceMappingURL=tools.js.map