@joy-loyalty/mcp 0.3.7

package/build/index.js

@@ -0,0 +1,1955 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/config.ts
+var ConfigError = class extends Error {
+};
+var DEFAULT_API_BASE_URL = "https://api.joy.so";
+var JOY_API_HOSTS = /* @__PURE__ */ new Set(["api.joy.so", "dev-api.joy.so"]);
+var FIREBASE_STAGING_HOST = /^avada-joy(-staging(-\d+)?)?\.(firebaseapp\.com|web\.app)$/;
+function assertAllowedBaseUrl(baseUrl) {
+  let parsed;
+  try {
+    parsed = new URL(baseUrl);
+  } catch {
+    throw new ConfigError(`JOY_API_BASE_URL is not a valid URL: "${baseUrl}".`);
+  }
+  const host = parsed.hostname;
+  const isLocal = host === "localhost" || host === "127.0.0.1";
+  if (!isLocal && parsed.protocol !== "https:") {
+    throw new ConfigError(
+      `JOY_API_BASE_URL must use https (got "${parsed.protocol}//") \u2014 the shop's secret key travels in request headers.`
+    );
+  }
+  if (isLocal || JOY_API_HOSTS.has(host) || FIREBASE_STAGING_HOST.test(host)) return;
+  throw new ConfigError(
+    `JOY_API_BASE_URL host "${host}" is not a Joy API host \u2014 refusing to send the shop's secret key there. Allowed: api.joy.so, dev-api.joy.so, avada-joy-staging-N.firebaseapp.com, localhost.`
+  );
+}
+function loadConfig(env = process.env) {
+  const appKey = env.JOY_APP_KEY?.trim();
+  const secretKey = env.JOY_SECRET_KEY?.trim() || void 0;
+  const privateBotKey = env.JOY_PRIVATE_BOT_KEY?.trim() || void 0;
+  const apiBaseUrl = (env.JOY_API_BASE_URL?.trim() || DEFAULT_API_BASE_URL).replace(/\/+$/, "");
+  assertAllowedBaseUrl(apiBaseUrl);
+  if (!appKey) {
+    throw new ConfigError(
+      'Missing JOY_APP_KEY (your shop ID). Set it in the "env" block of your MCP client config.'
+    );
+  }
+  if (!secretKey && !privateBotKey) {
+    throw new ConfigError(
+      "Missing credential: set JOY_SECRET_KEY (merchant API secret key) or JOY_PRIVATE_BOT_KEY (Joy-internal, read-only)."
+    );
+  }
+  if (secretKey && privateBotKey) {
+    throw new ConfigError(
+      "Set only ONE of JOY_SECRET_KEY or JOY_PRIVATE_BOT_KEY \u2014 they are mutually exclusive auth modes."
+    );
+  }
+  const mode = privateBotKey ? "internal-bot" : "merchant";
+  const writesEnabled = mode === "merchant" && env.JOY_MCP_ENABLE_WRITES === "true";
+  const rawThreshold = Number(env.JOY_MCP_DEDUCT_DRYRUN_THRESHOLD ?? "1000");
+  const deductDryRunThreshold = Number.isFinite(rawThreshold) && rawThreshold >= 0 ? rawThreshold : 1e3;
+  return { apiBaseUrl, appKey, secretKey, privateBotKey, mode, writesEnabled, deductDryRunThreshold };
+}
+
+// ../mcp-core/build/client/joyApi.js
+var JoyApiError = class extends Error {
+  kind;
+  modelMessage;
+  status;
+  constructor(kind, modelMessage, status) {
+    super(modelMessage);
+    this.kind = kind;
+    this.modelMessage = modelMessage;
+    this.status = status;
+    this.name = "JoyApiError";
+  }
+};
+var DEFAULT_TIMEOUT_MS = 1e4;
+function extractServerMessage(body) {
+  if (!body || typeof body !== "object")
+    return void 0;
+  const record = body;
+  if (typeof record.error === "string")
+    return record.error;
+  if (record.error && typeof record.error === "object") {
+    const message = record.error.message;
+    if (typeof message === "string")
+      return message;
+  }
+  if (typeof record.message === "string")
+    return record.message;
+  return void 0;
+}
+function extractServerCode(body) {
+  if (!body || typeof body !== "object")
+    return void 0;
+  const record = body;
+  if (typeof record.code === "string")
+    return record.code;
+  if (record.error && typeof record.error === "object") {
+    const code = record.error.code;
+    if (typeof code === "string")
+      return code;
+  }
+  return void 0;
+}
+function classifyError(status, serverMessage, retryAfter, credentialHint) {
+  const detail = serverMessage ? ` Server said: "${serverMessage}".` : "";
+  if (status === 401) {
+    return new JoyApiError("auth", `Authentication failed \u2014 the app key or credential is wrong.${detail} This is a server configuration problem; do NOT retry. Ask the merchant to re-check ${credentialHint} in the MCP config.`, status);
+  }
+  if (status === 403) {
+    const text = (serverMessage ?? "").toLowerCase();
+    if (text.includes("plan")) {
+      return new JoyApiError("plan_gate", `The shop's subscription plan does not include REST API access (Advanced plan or higher is required).${detail} Do NOT retry \u2014 the merchant must upgrade their Joy plan first.`, status);
+    }
+    return new JoyApiError("forbidden", `This operation is not permitted with the current credential (read-only key or insufficient scope).${detail} Do NOT retry with the same credential.`, status);
+  }
+  if (status === 429) {
+    const wait = retryAfter ? `${retryAfter} seconds` : "~10 seconds";
+    return new JoyApiError("rate_limit", `Rate limited: the Joy API allows 120 requests per 10 seconds per shop. Wait ${wait} before the next call, and prefer fewer, more specific queries (e.g. filter by email instead of listing pages). Do NOT retry immediately.`, status);
+  }
+  if (status === 404) {
+    return new JoyApiError("not_found", `Not found.${detail} Verify the identifier and try a lookup tool first (e.g. joy_find_member) instead of guessing IDs.`, status);
+  }
+  if (status === 400 || status === 422) {
+    return new JoyApiError("validation", `Invalid request.${detail} Fix the named parameter and call again.`, status);
+  }
+  if (status === 409) {
+    return new JoyApiError("conflict", `Conflict.${detail} Another attempt with the same Idempotency-Key is still in flight \u2014 wait ~30 seconds and call again with the SAME idempotency_key to retrieve its result. Never switch to a new key for the same operation; if this persists for minutes, verify the outcome via joy_get_member_activity instead.`, status);
+  }
+  return new JoyApiError("server", `Joy API internal error (HTTP ${status}).${detail} Safe to retry ONCE after a short wait; if it persists, stop and report the failure to the merchant.`, status);
+}
+function errorFromOkBody(body) {
+  if (!body || typeof body !== "object")
+    return void 0;
+  const record = body;
+  const hasError = record.success === false || typeof record.error === "string" || record.error !== null && record.error !== void 0 && typeof record.error === "object";
+  if (!hasError)
+    return void 0;
+  const message = extractServerMessage(record);
+  const code = extractServerCode(record);
+  if (code === "SHOP_UNINSTALLED" || /uninstall/i.test(message ?? "")) {
+    return new JoyApiError("forbidden", "The shop has uninstalled the Joy app \u2014 no loyalty data is available. Stop and inform the merchant; do NOT retry.");
+  }
+  if (code === "VALIDATION_ERROR") {
+    return new JoyApiError("validation", `Invalid request${message ? `: "${message}"` : ""}. Fix the named parameter and call again.`);
+  }
+  return new JoyApiError("server", `The Joy API reported an error: "${message ?? "unknown error"}". Do not treat this as an empty result. First re-check your parameters against the message; if they look correct, retry ONCE, then report the failure to the merchant.`);
+}
+var JoyApi = class {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  credentialHint() {
+    return this.config.mode === "internal-bot" ? "JOY_APP_KEY and JOY_PRIVATE_BOT_KEY" : "JOY_APP_KEY and JOY_SECRET_KEY";
+  }
+  headers() {
+    const headers = {
+      "Content-Type": "application/json",
+      "X-Joy-Loyalty-App-Key": this.config.appKey
+    };
+    if (this.config.privateBotKey) {
+      headers["X-Joy-Private-Bot-Key"] = this.config.privateBotKey;
+    } else if (this.config.secretKey) {
+      headers["X-Joy-Loyalty-Secret-Key"] = this.config.secretKey;
+    }
+    return headers;
+  }
+  async request(path, options = {}) {
+    const { method = "GET", query, body, timeoutMs = DEFAULT_TIMEOUT_MS, headers } = options;
+    const url = new URL(`${this.config.apiBaseUrl}/rest_api/v2${path}`);
+    for (const [key, value] of Object.entries(query ?? {})) {
+      if (value !== void 0)
+        url.searchParams.set(key, String(value));
+    }
+    let response;
+    try {
+      response = await fetch(url, {
+        method,
+        headers: { ...headers, ...this.headers() },
+        body: body === void 0 ? void 0 : JSON.stringify(body),
+        // fetch strips authorization on cross-origin redirects but NOT custom
+        // headers — an open redirect would forward the shop key elsewhere
+        redirect: "error",
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+    } catch (error) {
+      if (error instanceof Error && error.name === "TimeoutError") {
+        throw new JoyApiError("timeout", `The Joy API did not respond within ${Math.round(timeoutMs / 1e3)}s. Safe to retry ONCE; if it times out again, report the outage instead of retrying further.`);
+      }
+      throw new JoyApiError("network", `Could not reach the Joy API at ${this.config.apiBaseUrl}. Check network connectivity and JOY_API_BASE_URL. Safe to retry ONCE.`);
+    }
+    let parsed;
+    try {
+      parsed = await response.json();
+    } catch {
+      parsed = void 0;
+    }
+    if (!response.ok) {
+      throw classifyError(response.status, extractServerMessage(parsed), response.headers.get("Retry-After"), this.credentialHint());
+    }
+    const okBodyError = errorFromOkBody(parsed);
+    if (okBodyError)
+      throw okBodyError;
+    return parsed ?? {};
+  }
+  /** GET that unwraps the {success, data, meta} envelope — agent context never sees the wrapper. */
+  async getData(path, options = {}) {
+    const envelope = await this.request(path, options);
+    return {
+      data: envelope.data,
+      hasNext: envelope.meta?.pagination?.hasNext === true
+    };
+  }
+  /** POST/PUT that unwraps the envelope — for write tools. */
+  async mutateData(path, options = {}) {
+    const envelope = await this.request(path, options);
+    return envelope.data;
+  }
+};
+
+// ../mcp-core/build/cache.js
+var TtlCache = class {
+  store = /* @__PURE__ */ new Map();
+  get(key, ttlMs, loader) {
+    const now = Date.now();
+    const hit = this.store.get(key);
+    if (hit && hit.expiresAt > now)
+      return hit.promise;
+    const promise = loader().catch((error) => {
+      this.store.delete(key);
+      throw error;
+    });
+    this.store.set(key, { expiresAt: now + ttlMs, promise });
+    return promise;
+  }
+};
+
+// ../mcp-core/build/tools/members.js
+import { z } from "zod";
+
+// ../mcp-core/build/logger.js
+var log = {
+  info(message) {
+    console.error(`[joy-mcp] ${message}`);
+  },
+  error(message) {
+    console.error(`[joy-mcp:error] ${message}`);
+  }
+};
+
+// ../mcp-core/build/toolkit.js
+async function runHandler(name, run) {
+  try {
+    const text = await run();
+    return { content: [{ type: "text", text }] };
+  } catch (error) {
+    if (error instanceof JoyApiError) {
+      return { isError: true, content: [{ type: "text", text: error.modelMessage }] };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    log.error(`${name} failed unexpectedly: ${message}`);
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `Unexpected error in ${name}: ${message}. This is likely a bug in the Joy MCP server, not your input \u2014 report it to the merchant rather than retrying.`
+        }
+      ]
+    };
+  }
+}
+function registerReadTool(server, spec) {
+  const callback = (async (args) => runHandler(spec.name, () => spec.handler(args ?? {})));
+  server.registerTool(spec.name, {
+    title: spec.title,
+    description: spec.description,
+    inputSchema: spec.inputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+  }, callback);
+}
+function registerWriteTool(server, ctx, spec) {
+  const callback = (async (args) => {
+    if (!ctx.config.writesEnabled) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `${spec.name} is disabled: this server is running read-only. The merchant must set JOY_MCP_ENABLE_WRITES=true (with their secret key) in the MCP config to allow write operations. Do not retry until they have.`
+          }
+        ]
+      };
+    }
+    return runHandler(spec.name, () => spec.handler(args ?? {}));
+  });
+  server.registerTool(spec.name, {
+    title: spec.title,
+    description: spec.description,
+    inputSchema: spec.inputSchema,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: spec.destructiveHint,
+      idempotentHint: spec.idempotentHint,
+      openWorldHint: false
+    }
+  }, callback);
+}
+
+// ../mcp-core/build/shape.js
+var CHARACTER_LIMIT = 24e3;
+var MAX_STRING_FIELD = 400;
+function truncateString(value) {
+  return value.length > MAX_STRING_FIELD ? `${value.slice(0, MAX_STRING_FIELD)}\u2026` : value;
+}
+function scalarOnly(source) {
+  const result = {};
+  const omitted = [];
+  for (const [key, value] of Object.entries(source)) {
+    if (value === null || value === void 0 || value === "")
+      continue;
+    if (typeof value === "string") {
+      result[key] = truncateString(value);
+    } else if (typeof value === "number" || typeof value === "boolean") {
+      result[key] = value;
+    } else {
+      omitted.push(key);
+    }
+  }
+  if (omitted.length > 0)
+    result._omitted = omitted;
+  return result;
+}
+function compact(source, preferredKeys) {
+  if (!preferredKeys)
+    return scalarOnly(source);
+  const result = {};
+  for (const key of preferredKeys) {
+    const value = source[key];
+    if (value === null || value === void 0 || value === "")
+      continue;
+    result[key] = typeof value === "string" ? truncateString(value) : value;
+  }
+  if (Object.keys(result).length < 2)
+    return scalarOnly(source);
+  return result;
+}
+function clampText(text) {
+  if (text.length <= CHARACTER_LIMIT)
+    return text;
+  return `${text.slice(0, CHARACTER_LIMIT)}
+\u2026 [truncated: response exceeded ${CHARACTER_LIMIT} chars \u2014 narrow the query or use limit/after paging]`;
+}
+function formatPoints(value) {
+  return typeof value === "number" ? value.toLocaleString("en-US") : String(value ?? "?");
+}
+function summaryWithJson(summary, payload) {
+  return clampText(`${summary}
+${JSON.stringify(payload, null, 1)}`);
+}
+
+// ../mcp-core/build/tools/members.js
+var MEMBER_DETAIL_KEYS = [
+  "id",
+  "shopifyCustomerId",
+  "email",
+  "name",
+  "phone",
+  "type",
+  "point",
+  "pointsRemain",
+  "tierPoint",
+  "pendingPoint",
+  "totalSpent",
+  "totalEarnedPoints",
+  "tierId",
+  "tierName",
+  "referralCode",
+  "state",
+  "birthday",
+  "createdAt"
+];
+var MEMBER_LIST_KEYS = ["id", "shopifyCustomerId", "email", "name", "point", "tierName", "type"];
+var MEMBER_SORTS = {
+  points: { field: "point", label: "points balance" },
+  tier_points: { field: "tierPoint", label: "VIP tier points" },
+  created_at: { field: "createdAt", label: "signup date" },
+  recent_activity: { field: "updatedAt", label: "recent activity" }
+};
+var ACTIVITY_KEYS = [
+  "id",
+  "type",
+  "event",
+  "content",
+  "oldPoint",
+  "newPoint",
+  "earnPoint",
+  "spendPoint",
+  "programTitle",
+  "couponCode",
+  "source",
+  "orderName",
+  "adminNote",
+  "userNote",
+  "reason",
+  "createdAt"
+];
+var REWARD_KEYS = [
+  "id",
+  "couponCode",
+  "programTitle",
+  "discountStatus",
+  "orderReqAmount",
+  "expiredAt",
+  "usedAt",
+  "createdAt"
+];
+var memberIdentifierSchema = {
+  email: z.string().optional().describe("Member email. Matched exactly after lowercasing/trimming \u2014 typos return no result."),
+  shopify_customer_id: z.string().optional().describe('Shopify customer ID (numeric string), e.g. "7348912345".')
+};
+function normalizeEmail(email) {
+  return email.trim().toLowerCase();
+}
+async function resolveMember(api, args) {
+  if (args.shopify_customer_id) {
+    const { data } = await api.getData(`/customers/external/${encodeURIComponent(args.shopify_customer_id.trim())}`);
+    if (data && typeof data === "object") {
+      if (args.email && typeof data.email === "string") {
+        const givenEmail = normalizeEmail(args.email);
+        if (normalizeEmail(data.email) !== givenEmail) {
+          throw new JoyApiError("validation", `Identifier mismatch: shopify_customer_id "${args.shopify_customer_id}" belongs to ${data.email}, not "${givenEmail}". These point at DIFFERENT customers \u2014 re-check which one you mean and pass only ONE identifier.`);
+        }
+      }
+      return data;
+    }
+    throw new JoyApiError("not_found", `No loyalty member found for shopify_customer_id "${args.shopify_customer_id}". Verify the ID, or look the member up by email instead.`);
+  }
+  if (args.email) {
+    const email = normalizeEmail(args.email);
+    const { data } = await api.getData("/customers", { query: { email, limit: 1 } });
+    const member = Array.isArray(data) ? data[0] : void 0;
+    if (member)
+      return member;
+    throw new JoyApiError("not_found", `No loyalty member found with email "${email}" (exact match). Double-check the spelling, or use shopify_customer_id if you have it. Customers who never joined the program will not appear.`);
+  }
+  throw new JoyApiError("validation", "Provide either email or shopify_customer_id to identify the member.");
+}
+function memberDisplayName(member) {
+  const name = typeof member.name === "string" ? member.name.trim() : "";
+  return name || String(member.email ?? member.id ?? "member");
+}
+function reclassifyCursorError(error, after) {
+  if (error instanceof JoyApiError && error.kind === "server" && after) {
+    throw new JoyApiError("validation", `The 'after' cursor "${after}" appears to be invalid. Retry WITHOUT 'after', or use only a next_after value returned by a previous call.`);
+  }
+  throw error;
+}
+function registerMemberTools(server, ctx) {
+  registerReadTool(server, {
+    name: "joy_find_member",
+    title: "Find a loyalty member",
+    description: 'Look up ONE loyalty member by email or Shopify customer ID and return their points balance, VIP tier, and lifetime stats. Use this first whenever the merchant refers to a specific customer. Email matching is exact (case-insensitive) \u2014 if it misses, confirm spelling before concluding the customer is not a member. Field notes: "point" is the CURRENT spendable balance; "totalEarnedPoints" is lifetime earned (not spendable); "pointsRemain" is points needed to reach the next tier. Shopify store credit (money) is NOT included here \u2014 use joy_get_member_store_credit for that.',
+    inputSchema: memberIdentifierSchema,
+    handler: async (args) => {
+      const member = await resolveMember(ctx.api, args);
+      const shaped = compact(member, MEMBER_DETAIL_KEYS);
+      const tier = member.tierName ? `, tier ${String(member.tierName)}` : "";
+      return summaryWithJson(`Member ${memberDisplayName(member)}: ${formatPoints(member.point)} points${tier}.`, shaped);
+    }
+  });
+  registerReadTool(server, {
+    name: "joy_get_member_store_credit",
+    title: "Get a member's store credit balance",
+    description: "Shopify STORE CREDIT balance for ONE member (by email or Shopify customer ID). Store credit is real MONEY on the customer's Shopify account (e.g. from referral rewards or refunds) \u2014 it is NOT loyalty points; for the points balance use joy_find_member. A customer holds at most one account per currency, so multiple accounts mean multiple currencies. No account = zero store credit.",
+    inputSchema: memberIdentifierSchema,
+    handler: async (args) => {
+      let path;
+      let who;
+      if (args.shopify_customer_id) {
+        const externalId = args.shopify_customer_id.trim();
+        path = `/customers/external/${encodeURIComponent(externalId)}/store-credit`;
+        who = `Shopify customer ${externalId}`;
+      } else {
+        const member = await resolveMember(ctx.api, args);
+        path = `/customers/${encodeURIComponent(String(member.id))}/store-credit`;
+        who = memberDisplayName(member);
+      }
+      const { data } = await ctx.api.getData(path);
+      const accounts = Array.isArray(data?.accounts) ? data.accounts : [];
+      if (accounts.length === 0) {
+        return `${who} has NO store credit \u2014 no store credit account exists on Shopify (balance 0).`;
+      }
+      const balances = accounts.map((account) => `${String(account.amount)} ${String(account.currencyCode)}`).join(", ");
+      return summaryWithJson(`${who} has store credit: ${balances}.`, {
+        accounts: accounts.map((account) => compact(account, ["amount", "currencyCode"]))
+      });
+    }
+  });
+  registerReadTool(server, {
+    name: "joy_list_members",
+    title: "List loyalty members",
+    description: 'List loyalty members a page at a time, with sorting and an optional VIP-tier filter. Default order is most RECENT ACTIVITY (updatedAt desc). For ranking questions use sort_by \u2014 "which customer has the most points?" / "top 10 members" is ONE call with sort_by "points" (the first page IS the leaderboard; never page through the whole list for this). "How many customers/members does the shop have?" is ONE call with include_total_count true and limit 1 \u2014 never sum tier counts or page the list for this. sort_by "created_at" answers newest/oldest signups; tier_id narrows any of these to one tier. To inspect ONE known customer, prefer joy_find_member (cheaper and more precise). Returns up to `limit` members plus `has_more` and `next_after`; pass `next_after` back as `after` for the next page. Do not page through the whole list to answer aggregate questions \u2014 that burns the shop\'s API rate limit.',
+    inputSchema: {
+      limit: z.number().int().min(1).max(100).optional().describe("Members per page (default 20, max 100)."),
+      sort_by: z.enum(["points", "tier_points", "created_at", "recent_activity"]).optional().describe('Sort field (default recent_activity). "points" = current spendable balance (use for top/bottom members by points); "tier_points" = VIP tier progress points; "created_at" = signup date; "recent_activity" = last update.'),
+      direction: z.enum(["desc", "asc"]).optional().describe('"desc" (default) = highest/newest first; "asc" = lowest/oldest first.'),
+      tier_id: z.string().optional().describe("Only members currently in this VIP tier. Must be a tier `id` from joy_list_tiers, NOT the tier name."),
+      include_total_count: z.boolean().optional().describe("Set true when the merchant asks HOW MANY members/customers there are \u2014 returns total_members (exact count of the whole list, respecting tier_id). Combine with limit 1 when only the number is needed. Costs extra database reads; leave unset otherwise."),
+      after: z.string().optional().describe("Cursor: a next_after value returned by a previous call. Never invent one, and only reuse it with the SAME sort_by/direction/tier_id that produced it.")
+    },
+    handler: async (args) => {
+      const limit = args.limit ?? 20;
+      const sortBy = args.sort_by ?? "recent_activity";
+      const direction = args.direction ?? "desc";
+      const withTotal = args.include_total_count === true;
+      const sort = MEMBER_SORTS[sortBy];
+      let envelope;
+      try {
+        envelope = await ctx.api.request("/customers", {
+          query: {
+            limit,
+            after: args.after,
+            order: `${sort.field}_${direction}`,
+            tierId: args.tier_id?.trim() || void 0,
+            hasCount: withTotal ? true : void 0
+          }
+        });
+      } catch (error) {
+        reclassifyCursorError(error, args.after);
+      }
+      const result = {
+        data: envelope.data,
+        hasNext: envelope.meta?.pagination?.hasNext === true
+      };
+      const totalMembers = withTotal ? envelope.meta?.pagination?.total : void 0;
+      const members = Array.isArray(result.data) ? result.data : [];
+      if (members.length === 0) {
+        if (args.after)
+          return "No more members after this cursor \u2014 you have reached the end of the list.";
+        if (args.tier_id) {
+          return `No members are currently in tier "${args.tier_id}". Verify the tier id via joy_list_tiers (pass the id, not the name).`;
+        }
+        return "This shop has no loyalty members yet.";
+      }
+      const listKeys = sortBy === "tier_points" || sortBy === "created_at" ? [...MEMBER_LIST_KEYS, sort.field] : MEMBER_LIST_KEYS;
+      const shaped = members.map((member) => compact(member, listKeys));
+      const lastId = members[members.length - 1]?.id;
+      const isDateSort = sortBy === "created_at" || sortBy === "recent_activity";
+      const dirWord = direction === "desc" ? isDateSort ? "newest" : "highest" : isDateSort ? "oldest" : "lowest";
+      const orderNote = ` sorted by ${sort.label} (${dirWord} first)`;
+      const totalNote = typeof totalMembers === "number" ? ` This shop has ${totalMembers} member(s)${args.tier_id ? " in this tier" : ""} in TOTAL.` : "";
+      return summaryWithJson(`${members.length} member(s) on this page,${orderNote}${result.hasNext ? " (more available)" : ""}.${totalNote}`, {
+        members: shaped,
+        has_more: result.hasNext,
+        ...typeof totalMembers === "number" ? { total_members: totalMembers } : {},
+        ...result.hasNext && lastId ? { next_after: lastId } : {}
+      });
+    }
+  });
+  registerReadTool(server, {
+    name: "joy_get_member_activity",
+    title: "Get a member's point activity",
+    description: 'Point transactions (earned, spent, adjusted, refund deductions\u2026) for ONE member, most recent first. Use to answer "why is this customer\'s balance X?" or to audit changes. Each entry shows the point change, balance before/after (oldPoint \u2192 newPoint), the source system, and any notes. Returns `next_after` when more history exists \u2014 pass it back as `after` to keep auditing.',
+    inputSchema: {
+      ...memberIdentifierSchema,
+      limit: z.number().int().min(1).max(50).optional().describe("Transactions per page (default 10, max 50)."),
+      after: z.string().optional().describe("Cursor: a next_after value returned by a previous call. Never invent one.")
+    },
+    handler: async (args) => {
+      const limit = args.limit ?? 10;
+      const query = { limit, after: args.after };
+      if (args.shopify_customer_id) {
+        query.shopifyCustomerId = args.shopify_customer_id.trim();
+      } else {
+        const member = await resolveMember(ctx.api, args);
+        query.customerId = String(member.id);
+      }
+      let transactionsResult;
+      try {
+        transactionsResult = await ctx.api.getData("/transactions", { query });
+      } catch (error) {
+        reclassifyCursorError(error, args.after);
+      }
+      const { data, hasNext } = transactionsResult;
+      const activities = Array.isArray(data) ? data : [];
+      if (activities.length === 0) {
+        return args.after ? "No more activity after this cursor \u2014 you have reached the end of the history." : "This member has no point activity yet.";
+      }
+      const lastId = activities[activities.length - 1]?.id;
+      return summaryWithJson(`${activities.length} point transaction(s)${hasNext ? " (more available)" : ""}.`, {
+        activities: activities.map((activity) => compact(activity, ACTIVITY_KEYS)),
+        has_more: hasNext,
+        ...hasNext && lastId ? { next_after: lastId } : {}
+      });
+    }
+  });
+  registerReadTool(server, {
+    name: "joy_get_member_rewards",
+    title: "Get a member's reward/coupon history",
+    description: `Coupons and rewards ONE member has already redeemed \u2014 code, discount program, status (active/used/expired), expiry. This is the member's OWN history, NOT the shop's catalog of what CAN be redeemed (use joy_list_redemption_rules for that). Use to answer "what coupons does this customer have?" or "did they already use that discount code?".`,
+    inputSchema: {
+      ...memberIdentifierSchema,
+      limit: z.number().int().min(1).max(50).optional().describe("Rewards per page (default 10, max 50)."),
+      after: z.string().optional().describe("Cursor: a next_after value returned by a previous call. Never invent one.")
+    },
+    handler: async (args) => {
+      const limit = args.limit ?? 10;
+      const query = { limit, after: args.after };
+      if (args.shopify_customer_id) {
+        query.shopifyCustomerId = args.shopify_customer_id.trim();
+      } else {
+        const member = await resolveMember(ctx.api, args);
+        query.customerId = String(member.id);
+      }
+      let rewardsResult;
+      try {
+        rewardsResult = await ctx.api.getData("/rewards", { query });
+      } catch (error) {
+        reclassifyCursorError(error, args.after);
+      }
+      const { data, hasNext } = rewardsResult;
+      const rewards = Array.isArray(data) ? data : [];
+      if (rewards.length === 0) {
+        return args.after ? "No more rewards after this cursor \u2014 you have reached the end of the history." : "This member has no redeemed rewards yet.";
+      }
+      const lastId = rewards[rewards.length - 1]?.id;
+      return summaryWithJson(`${rewards.length} reward(s)${hasNext ? " (more available)" : ""}.`, {
+        rewards: rewards.map((reward) => compact(reward, REWARD_KEYS)),
+        has_more: hasNext,
+        ...hasNext && lastId ? { next_after: lastId } : {}
+      });
+    }
+  });
+}
+
+// ../mcp-core/build/tools/tiers.js
+import { z as z2 } from "zod";
+var TIER_KEYS = [
+  "id",
+  "name",
+  "targetPoint",
+  "targetAmount",
+  "entryMethod",
+  "members",
+  "rateMoney",
+  "earnPoint",
+  "tierRewards",
+  "inactive",
+  "isExclusiveTier",
+  "systemType"
+];
+var TIERS_TTL_MS = 15 * 60 * 1e3;
+function getTiersCached(ctx) {
+  return ctx.cache.get("tiers", TIERS_TTL_MS, async () => {
+    const { data } = await ctx.api.getData("/tiers");
+    return Array.isArray(data) ? data : [];
+  });
+}
+function registerTierTools(server, ctx) {
+  registerReadTool(server, {
+    name: "joy_list_tiers",
+    title: "List VIP tiers",
+    description: 'List the shop\'s VIP tiers with thresholds (targetPoint/targetAmount), earning multipliers, and per-tier benefits (tierRewards). Use to understand the tier ladder before answering tier questions. For "how many customers are in tier X?" set include_member_counts \u2014 it returns memberCount (live count of current members) per tier; the plain `members` field is a stale cached snapshot, NEVER quote it as the member count. Config-only calls are cached ~15 minutes \u2014 one call per conversation is enough.',
+    inputSchema: {
+      include_member_counts: z2.boolean().optional().describe("Set true ONLY when the merchant asks how many customers/members are in tiers \u2014 adds memberCount (live count) per tier. Leave unset for tier-config questions; counting costs extra database reads.")
+    },
+    handler: async (args) => {
+      if (args.include_member_counts === true) {
+        const { data } = await ctx.api.getData("/tiers", { query: { hasCount: true } });
+        const tiers2 = Array.isArray(data) ? data : [];
+        if (tiers2.length === 0) {
+          return "This shop has no VIP tiers configured. Tier-related questions do not apply.";
+        }
+        const keys = [...TIER_KEYS.filter((key) => key !== "members"), "memberCount"];
+        const total = tiers2.reduce((sum, tier) => sum + (Number(tier.memberCount) || 0), 0);
+        const top = [...tiers2].sort((a, b) => (Number(b.memberCount) || 0) - (Number(a.memberCount) || 0))[0];
+        return summaryWithJson(`${tiers2.length} VIP tier(s), ${total} member(s) total \u2014 largest: "${String(top.name)}" (${Number(top.memberCount) || 0} members).`, tiers2.map((tier) => compact(tier, keys)));
+      }
+      const tiers = await getTiersCached(ctx);
+      if (tiers.length === 0) {
+        return "This shop has no VIP tiers configured. Tier-related questions do not apply.";
+      }
+      return summaryWithJson(`${tiers.length} VIP tier(s) configured.`, tiers.map((tier) => compact(tier, TIER_KEYS)));
+    }
+  });
+}
+function registerTierWriteTools(server, ctx) {
+  registerWriteTool(server, ctx, {
+    name: "joy_set_member_tier",
+    title: "Set a member's VIP tier",
+    description: "WRITE \u2014 manually moves ONE member to a VIP tier (may trigger tier rewards for the member). Find valid tier IDs via joy_list_tiers first. Setting the tier the member already has is a safe no-op. admin_note is recorded on the tier-change activity.",
+    inputSchema: {
+      ...memberIdentifierSchema,
+      tier_id: z2.string().describe("Target tier ID (from joy_list_tiers)."),
+      reason: z2.string().min(3).describe("Why the tier is being changed \u2014 REQUIRED, recorded on the tier-change activity."),
+      admin_note: z2.string().optional().describe("Optional extra note for the merchant team.")
+    },
+    destructiveHint: true,
+    idempotentHint: true,
+    handler: async (args) => {
+      const member = await resolveMember(ctx.api, args);
+      if (member.tierId === args.tier_id) {
+        return `${memberDisplayName(member)} is already in tier ${String(member.tierName ?? args.tier_id)} \u2014 no change made.`;
+      }
+      const result = await ctx.api.mutateData(`/customers/external/${encodeURIComponent(String(member.shopifyCustomerId))}/tier`, {
+        method: "PUT",
+        timeoutMs: 15e3,
+        body: {
+          tierId: args.tier_id,
+          source: "mcp",
+          // Tier endpoint has no dedicated reason field — the audited note carries it
+          adminNote: args.admin_note ? `${args.reason} \u2014 ${args.admin_note}` : args.reason
+        }
+      });
+      const tierName = result?.tierName ? String(result.tierName) : args.tier_id;
+      return summaryWithJson(`Moved ${memberDisplayName(member)} to tier "${tierName}".`, compact(result ?? {}, ["id", "shopifyCustomerId", "tierId", "tierName", "tierPoint", "tierUpdatedAt"]));
+    }
+  });
+}
+
+// ../mcp-core/build/tools/programs.js
+import { z as z3 } from "zod";
+var EARNING_KEYS = [
+  "id",
+  "event",
+  "title",
+  "status",
+  "type",
+  "earnBy",
+  "rateMoney",
+  "earnPoint",
+  "earnPointsTiers",
+  "conditions",
+  "typeMilestone",
+  "milestones",
+  "startDate",
+  "endDate",
+  "priority",
+  "isDraft",
+  "expired"
+];
+var SPENDING_KEYS = [
+  "id",
+  "title",
+  "type",
+  "event",
+  "status",
+  "spendPoint",
+  "earnAmount",
+  "redeemType",
+  "minSpendPoint",
+  "maxSpendPoint",
+  "hasMinSpend",
+  "hasMaxSpend",
+  "expiredAfter",
+  "expiredTime",
+  "limitRedeem",
+  "conditions",
+  "priority",
+  // Free shipping fields — not covered by earnAmount/redeemType above
+  "shippingDiscountType",
+  "shippingDiscountAmount",
+  "hasLimitShipping",
+  "limitShipping",
+  "enableMaxCapShipping",
+  "maxCapShipping"
+];
+function registerProgramTools(server, ctx) {
+  registerReadTool(server, {
+    name: "joy_list_earning_rules",
+    title: "List point-earning rules",
+    description: 'List the ways customers EARN points (place order, sign up, birthday, social follows\u2026). Use to answer "how do customers get points?". IMPORTANT: when a rule has earnPointsTiers, the per-VIP-tier multipliers there override the flat earnPoint \u2014 quote the tiered values, not just the base rate.',
+    inputSchema: {},
+    handler: async () => {
+      const { data } = await ctx.api.getData("/programs/earning");
+      const programs = Array.isArray(data) ? data : [];
+      if (programs.length === 0) {
+        return "No earning rules configured \u2014 customers currently have no way to earn points.";
+      }
+      return summaryWithJson(`${programs.length} earning rule(s) configured.`, programs.map((program) => compact(program, EARNING_KEYS)));
+    }
+  });
+  registerReadTool(server, {
+    name: "joy_list_redemption_rules",
+    title: "List point-redemption rules",
+    description: 'List the ways customers SPEND points (discount amount, percentage off, free shipping, free gift\u2026), including point costs (spendPoint) and min/max limits. Use to answer "what can customers redeem?" and to find the programId for a redemption. For USAGE questions \u2014 "which reward is redeemed most?", "how many times was program X redeemed?" \u2014 set include_redeem_counts to get redeemCount (all-time REDEMPTIONS, not unique customers) per rule in the same call. Redeeming itself is a separate write operation, not available through this tool.',
+    inputSchema: {
+      include_redeem_counts: z3.boolean().optional().describe("Set true ONLY when the merchant asks about usage/popularity \u2014 adds redeemCount (all-time number of redemptions) to each rule. Leave unset for pure configuration questions; counting costs extra database reads.")
+    },
+    handler: async (args) => {
+      const withCounts = args.include_redeem_counts === true;
+      const { data } = await ctx.api.getData("/programs/redemption", {
+        query: withCounts ? { hasCount: true } : {}
+      });
+      const programs = Array.isArray(data) ? data : [];
+      if (programs.length === 0) {
+        return "No redemption rules configured \u2014 customers currently cannot spend their points.";
+      }
+      const keys = withCounts ? [...SPENDING_KEYS, "redeemCount"] : SPENDING_KEYS;
+      let summary = `${programs.length} redemption rule(s) configured.`;
+      if (withCounts) {
+        const total = programs.reduce((sum, program) => sum + (Number(program.redeemCount) || 0), 0);
+        const top = [...programs].sort((a, b) => (Number(b.redeemCount) || 0) - (Number(a.redeemCount) || 0))[0];
+        summary = `${programs.length} redemption rule(s), ${total} redemption(s) all-time \u2014 most redeemed: "${String(top.title)}" (${Number(top.redeemCount) || 0}).`;
+      }
+      return summaryWithJson(summary, programs.map((program) => compact(program, keys)));
+    }
+  });
+}
+
+// ../mcp-core/build/tools/referrals.js
+import { z as z4 } from "zod";
+var REFERRAL_ACTIVITY_KEYS = [
+  "id",
+  "email",
+  "referralCustomerEmail",
+  "statusReferral",
+  "couponCode",
+  "createdAt"
+];
+var REFERRAL_PROGRAM_KEYS = [
+  "status",
+  "title",
+  "customerRewardEarnAmount",
+  "customerRewardDiscountType",
+  "customerRewardExpiredAfter",
+  "customerRewardOrderReq",
+  "customerRewardOrderReqAmount",
+  "isAppliedVipTier",
+  "earnPointsTiers",
+  "friendRewardEarnAmount",
+  "friendRewardDiscountType",
+  "friendRewardExpiredAfter",
+  "friendRewardOrderReq",
+  "friendRewardOrderReqAmount",
+  "maxReferralsPerCustomer",
+  "referralLimitType",
+  "referralEligibilityType",
+  "restrictReferralAccessByTags",
+  "enableAntiCheat",
+  "referralSharingMode",
+  "autoRevokeReferrerReward"
+];
+function formatReferralReward(amount, type) {
+  if (amount === void 0 || amount === null)
+    return "not configured";
+  if (type === "percentage")
+    return `${String(amount)}% off`;
+  if (type === "point")
+    return `${String(amount)} points`;
+  if (type === "amount")
+    return `${String(amount)} off (fixed amount)`;
+  return `${String(amount)} (${String(type ?? "unknown type")})`;
+}
+function registerReferralTools(server, ctx) {
+  registerReadTool(server, {
+    name: "joy_get_referral_program",
+    title: "Get referral program status & configuration",
+    description: 'Whether the referral program is ENABLED plus its reward configuration \u2014 use this FIRST for "is the referral program on or off?", "what do referrers/friends get?". `status` is the on/off toggle: true = customers can refer friends, false = the program is turned off. Field naming: customerReward* = what the REFERRER (the advocate) gets; friendReward* = what the referred FRIEND gets; reward type may be "percentage", "amount" (fixed discount), "point", or store-credit. When isAppliedVipTier is true, earnPointsTiers overrides the flat referrer reward per VIP tier. For usage numbers use joy_get_referral_performance; for one member\'s results use joy_get_member_referrals.',
+    inputSchema: {},
+    handler: async () => {
+      let program;
+      try {
+        const { data } = await ctx.api.getData("/referrals/program");
+        program = data ?? {};
+      } catch (error) {
+        if (error instanceof JoyApiError && error.kind === "not_found") {
+          return "The referral program has never been set up on this shop \u2014 it is OFF; customers cannot refer friends.";
+        }
+        throw error;
+      }
+      const enabled = program.status === true;
+      const referrerReward = formatReferralReward(program.customerRewardEarnAmount, program.customerRewardDiscountType);
+      const friendReward = formatReferralReward(program.friendRewardEarnAmount, program.friendRewardDiscountType);
+      return summaryWithJson(`Referral program is ${enabled ? "ENABLED (ON)" : "DISABLED (OFF)"} \u2014 referrer gets ${referrerReward}, referred friend gets ${friendReward}.`, compact(program, REFERRAL_PROGRAM_KEYS));
+    }
+  });
+  registerReadTool(server, {
+    name: "joy_get_referral_performance",
+    title: "Get referral program performance",
+    description: "Shop-level referral analytics. NOTE: the underlying API currently reports one metric only \u2014 how many referral coupon codes were used (i.e. completed referrals). It does NOT report clicks, signups, or revenue, and it does NOT tell you whether the program is enabled \u2014 use joy_get_referral_program for status/config. Optionally filter by date range.",
+    inputSchema: {
+      start_date: z4.string().optional().describe("ISO date (YYYY-MM-DD), inclusive start of the range."),
+      end_date: z4.string().optional().describe("ISO date (YYYY-MM-DD), inclusive end of the range.")
+    },
+    handler: async (args) => {
+      const { data } = await ctx.api.getData("/referrals/analytics", {
+        query: { startDate: args.start_date, endDate: args.end_date }
+      });
+      const range = args.start_date || args.end_date ? ` between ${args.start_date ?? "the beginning"} and ${args.end_date ?? "now"}` : "";
+      const count = data?.countCouponCodeUsage ?? 0;
+      return summaryWithJson(`${count} referral coupon(s) were used${range} (completed referrals).`, compact(data ?? {}));
+    }
+  });
+  registerReadTool(server, {
+    name: "joy_get_member_referrals",
+    title: "Get one member's referral results",
+    description: "Referral results for ONE member (identified by email or Shopify customer ID). Returns (1) aggregate totals \u2014 coupons redeemed via their referrals and points they earned from referring \u2014 and (2) their recent referral activity records. To generate/fetch their personal invite LINK, use joy_create_referral_invite instead.",
+    inputSchema: memberIdentifierSchema,
+    handler: async (args) => {
+      const member = await resolveMember(ctx.api, args);
+      const memberId = encodeURIComponent(String(member.id));
+      const [summary, referrers] = await Promise.all([
+        ctx.api.getData(`/referrals/customers/${memberId}/summary`),
+        ctx.api.getData(`/referrals/customers/${memberId}/referrers`, {
+          query: { limit: 20 }
+        })
+      ]);
+      const activities = Array.isArray(referrers.data) ? referrers.data : [];
+      return summaryWithJson(`Referral results for ${String(member.email ?? member.id)} \u2014 ${activities.length} recent referral record(s).`, {
+        totals: compact(summary.data ?? {}),
+        recent_referrals: activities.map((activity) => compact(activity, REFERRAL_ACTIVITY_KEYS))
+      });
+    }
+  });
+}
+function registerReferralWriteTools(server, ctx) {
+  registerWriteTool(server, ctx, {
+    name: "joy_create_referral_invite",
+    title: "Generate a referral invite link",
+    description: "WRITE \u2014 generates a personal referral invite link for an email address. For an EXISTING member this just returns their own link (safe, cheap). For an email that is NOT yet a member, this CREATES A REAL SHOPIFY CUSTOMER RECORD \u2014 irreversible from this tool \u2014 and may trigger sign-up point rewards for them. Double-check the email spelling with the merchant before calling for a non-member; a typo creates a junk customer, not an error. Identify by email only (this can create a new record, so it never accepts shopify_customer_id).",
+    inputSchema: {
+      email: z4.string().email().describe("Email address to generate the invite link for. Must be a real, verified address \u2014 a typo creates a real customer record, not an error."),
+      use_marketing: z4.boolean().optional().describe("Marketing consent for a NEW customer record. Defaults to false (no consent). Only pass true if the person actually opted in to marketing \u2014 this can set real email-marketing-consent on their Shopify customer record.")
+    },
+    destructiveHint: false,
+    idempotentHint: false,
+    handler: async (args) => {
+      const result = await ctx.api.mutateData("/referrals/invitations", {
+        method: "POST",
+        timeoutMs: 15e3,
+        body: { email: args.email, useMarketing: args.use_marketing }
+      });
+      const isExisting = result?.isExistingCustomer ? "existing member" : "new prospect";
+      return summaryWithJson(`Generated referral invite link for ${args.email} (${isExisting}).`, compact(result ?? {}, ["urlReferral", "referralCode", "isExistingCustomer"]));
+    }
+  });
+}
+
+// ../mcp-core/build/tools/overview.js
+var OVERVIEW_TTL_MS = 15 * 60 * 1e3;
+function registerOverviewTools(server, ctx) {
+  registerReadTool(server, {
+    name: "joy_get_loyalty_overview",
+    title: "Get loyalty program overview",
+    description: 'Orient yourself: shop identity (name, domain, plan, currency, timezone) plus the loyalty program settings. Call this FIRST in a conversation before other Joy tools \u2014 it tells you which shop you are operating on and how its program is configured. Cached ~15 minutes; repeat calls within a conversation are free. This is configuration only \u2014 for performance numbers (revenue impact, points issued, member growth, program health) use the joy_get_* analytics report tools instead, and for "how many members does the shop have?" use joy_list_members with include_total_count.',
+    inputSchema: {},
+    handler: async () => {
+      const { shop, settings } = await ctx.cache.get("overview", OVERVIEW_TTL_MS, async () => {
+        const [shopResult, settingsResult] = await Promise.all([
+          ctx.api.getData("/whoami"),
+          ctx.api.getData("/shop/settings")
+        ]);
+        return {
+          shop: shopResult.data ?? {},
+          settings: settingsResult.data ?? {}
+        };
+      });
+      const shopName = String(shop.name ?? shop.domain ?? "shop");
+      const plan = shop.plan ? ` (plan: ${String(shop.plan)})` : "";
+      return summaryWithJson(`Operating on ${shopName}${plan}.`, {
+        shop: compact(shop, ["id", "name", "domain", "email", "plan", "currency", "timezone", "isInstalled"]),
+        settings: compact(settings)
+      });
+    }
+  });
+}
+
+// ../mcp-core/build/tools/analytics.js
+import { z as z5 } from "zod";
+function toDateRangeQuery(args) {
+  const query = {};
+  if (args.start_date !== void 0)
+    query.startDate = args.start_date;
+  if (args.end_date !== void 0)
+    query.endDate = args.end_date;
+  return query;
+}
+function toLoyaltyRevenueQuery(args) {
+  const query = { metric: args.metric, ...toDateRangeQuery(args) };
+  if (args.period !== void 0)
+    query.period = args.period;
+  if (args.compare_to_last_year !== void 0)
+    query.compareToLastYear = args.compare_to_last_year;
+  return query;
+}
+function toTierPerformanceQuery(args) {
+  return { metric: args.metric, ...toDateRangeQuery(args) };
+}
+function toV2ReportQuery(args) {
+  const query = {
+    reportType: args.report_type,
+    ...toDateRangeQuery(args)
+  };
+  if (args.unit !== void 0)
+    query.unit = args.unit;
+  return query;
+}
+var V2_REPORT_TYPES = [
+  "overview_kpis",
+  "members_overview",
+  "cohort_retention",
+  "participation_rate",
+  "customer_base",
+  "tier_performance",
+  "tier_trend",
+  "tier_transitions",
+  "wallet_adoption",
+  "reward_roi",
+  "points_economy",
+  "points_movement",
+  "top_programs_earned",
+  "top_programs_redeemed",
+  "coupon_usage",
+  "coupon_funnel",
+  "coupon_programs_earned",
+  "coupon_programs_redeemed",
+  "referral_summary",
+  "referral_funnel",
+  "referral_traffic",
+  "referral_conversion",
+  "referred_customer",
+  "order_referred",
+  "sale_referred",
+  "loyalty_impact",
+  "member_comparison",
+  "redeemer_comparison",
+  "revenue_by_channel",
+  "assisted_revenue",
+  "assisted_revenue_orders"
+];
+var V2_REPORT_MENU = `Report menu (pick the closest reportType):
+- overview_kpis: top-line KPIs \u2014 members, points earned/redeemed, redemption rate, redeem & referral revenue, enrollment & repeat rates, with period-over-period trends. Best FIRST call for broad questions.
+- members_overview: membership composition, lifecycle funnel, activation/enrollment/retention rates, new members.
+- cohort_retention: monthly signup-cohort retention matrix (M0..M11).
+- participation_rate: daily enrollment-rate & redeemer-rate trend.
+- customer_base: cumulative customer-base growth (members vs guests).
+- tier_performance: per-VIP-tier member count, AOV, repeat rate, revenue.
+- tier_trend: member count over time per tier.
+- tier_transitions: tier upgrades/downgrades/new enrollments/net movement.
+- wallet_adoption: Apple/Google Wallet card adoption (all-time snapshot).
+- reward_roi: reward cost vs revenue and ROI KPIs.
+- points_economy: points earned vs redeemed (and losses) over time.
+- points_movement: totals & series for earned/redeemed/expired/refunded/adjusted points, balance, liability, redemption rate \u2014 use for "points issued/redeemed in <month>".
+- top_programs_earned / top_programs_redeemed: program rankings by points earned / redeemed.
+- coupon_usage: coupons generated vs used, usage rate.
+- coupon_funnel: generated \u2192 used \u2192 drove an order.
+- coupon_programs_earned / coupon_programs_redeemed: coupon programs ranked.
+- referral_summary: referral KPIs and top referrers.
+- referral_funnel: traffic \u2192 signed up \u2192 purchased.
+- referral_traffic / referral_conversion / referred_customer: referral clicks, conversion metrics, referred customers over time.
+- order_referred / sale_referred: orders / revenue driven by referrals over time.
+- loyalty_impact / member_comparison / redeemer_comparison: members-vs-non-members and redeemers-vs-non comparisons (AOV, repeat rate, revenue, CLV).
+- revenue_by_channel: loyalty revenue split by sales channel.
+- assisted_revenue / assisted_revenue_orders: Joy-assisted revenue vs total store revenue / assisted orders detail.`;
+var LOYALTY_REVENUE_KEYS = [
+  "metric",
+  "period",
+  "value",
+  "previousValue",
+  "deltaPercent",
+  "rows"
+];
+var TIER_PERFORMANCE_KEYS = ["metric", "period", "rows", "topGroup"];
+var HEALTH_CHECK_KEYS = ["healthScore", "flagCount", "flags", "snapshot"];
+var reportDateRangeSchema = {
+  start_date: z5.string().optional().describe("ISO date (YYYY-MM-DD), inclusive start of the report window. Defaults to 30 days ago. Effective range max 366 days."),
+  end_date: z5.string().optional().describe("ISO date (YYYY-MM-DD), inclusive end of the report window. Defaults to today.")
+};
+var SCOPE_HELP = "A 403 mentioning read_reports means the MERCHANT has not granted Shopify reports access to Joy \u2014 not a credential problem, do not retry; ask them to grant it from Joy settings.";
+function withScopeGuidance(error) {
+  if (error instanceof JoyApiError && error.status === 403 && /read_reports/i.test(error.message)) {
+    return new JoyApiError("forbidden", "This report needs the Shopify read_reports permission, which the merchant has not granted to Joy yet. This is NOT a credential problem \u2014 do NOT retry. Ask the merchant to grant reports access from the Joy admin settings, then call again.", 403);
+  }
+  return error;
+}
+function withV2EnablementGuidance(error) {
+  if (error instanceof JoyApiError && error.status === 409 && /Analytics V2 is not enabled/i.test(error.message)) {
+    return new JoyApiError("conflict", "This shop is still on Analytics V1 \u2014 Analytics V2 report data does not exist yet, so there are NO numbers to quote (do not report zeros). Ask the merchant if they want to switch to the new Analytics; switching also backfills their historical data. If they agree and the joy_enable_analytics_v2 tool is available, call it; otherwise tell them to switch in Joy admin \u2192 Analytics. Do not retry this report until V2 is enabled.", 409);
+  }
+  return error;
+}
+function formatEnableStatus(data) {
+  const status = String(data.status ?? "unknown");
+  if (status === "started") {
+    return "Analytics V2 is now ENABLED and the historical data backfill has started in the background. It can take from a few minutes to a few tens of minutes depending on data volume. Tell the merchant it is underway; call this tool again later to check progress \u2014 analytics answers may be incomplete until it finishes.";
+  }
+  if (status === "running") {
+    const steps = Array.isArray(data.steps) ? data.steps : [];
+    const done = steps.filter((step) => step.status === "completed").length;
+    const progress = steps.length ? ` (${done}/${steps.length} steps completed)` : "";
+    return `The Analytics V2 backfill is STILL RUNNING${progress} \u2014 current step: ${String(data.currentStep ?? "?")}. Do not re-trigger it; tell the merchant it is in progress and analytics numbers may be incomplete until it finishes. Check again in a few minutes.`;
+  }
+  if (status === "failed") {
+    return `The Analytics V2 backfill STOPPED ON AN ERROR at step "${String(data.currentStep ?? "?")}". Historical numbers may be incomplete. Tell the merchant to contact Joy support to resume it \u2014 do not re-trigger it yourself.`;
+  }
+  if (status === "already_enabled") {
+    return "Analytics V2 is already enabled for this shop" + (data.completedAt ? ` (backfill completed ${String(data.completedAt)})` : "") + " \u2014 analytics reports are available via joy_get_analytics_report.";
+  }
+  return `Enable request returned an unrecognized status "${status}" \u2014 report this to Joy support.`;
+}
+async function getScopedReport(ctx, path, options = {}) {
+  try {
+    const { data } = await ctx.api.getData(path, options);
+    return data ?? {};
+  } catch (error) {
+    throw withScopeGuidance(error);
+  }
+}
+function registerAnalyticsTools(server, ctx) {
+  registerReadTool(server, {
+    name: "joy_get_analytics_report",
+    title: "Loyalty analytics report (Analytics V2)",
+    description: 'THE primary tool for loyalty analytics questions \u2014 members, VIP tiers, points economy, rewards ROI, coupons, referrals, and loyalty revenue impact. Retrieves any Analytics V2 report using the SAME data and cache as the Analytics dashboard the merchant sees in the Joy admin, so your numbers always match theirs. Joy-internal data \u2014 no Shopify permission needed. Defaults to the last 30 days (max 366-day range, cached server-side ~1h). Returns a pre-digested text summary (time series are collapsed to count/total/latest; tables capped at 8 rows). A 409 error means the shop is still on Analytics V1 (no V2 data exists \u2014 follow the error guidance about migrating, never report zeros); a summary starting with "WARNING: \u2026 backfill" means the historical backfill is unfinished and numbers may be incomplete \u2014 relay that caveat. For Shopify-sales-attributed revenue (order-tag attribution) use joy_get_loyalty_revenue_report instead \u2014 a DIFFERENT data source whose numbers may legitimately differ from assisted_revenue.\n' + V2_REPORT_MENU,
+    inputSchema: {
+      report_type: z5.enum(V2_REPORT_TYPES).describe("Which Analytics V2 loyalty report to retrieve (see the menu in the tool description)."),
+      ...reportDateRangeSchema,
+      unit: z5.enum(["day", "month"]).optional().describe("Time grain for trend reports. Defaults by range size (\u2264100 days \u2192 day, else month).")
+    },
+    handler: async (args) => {
+      let report;
+      try {
+        const { data } = await ctx.api.getData("/analytics/report", {
+          query: toV2ReportQuery(args),
+          timeoutMs: 3e4
+        });
+        report = data ?? {};
+      } catch (error) {
+        throw withV2EnablementGuidance(error);
+      }
+      const period = report.period;
+      const header = `Analytics V2 \u2014 ${args.report_type} (${String(period?.fromDate ?? "?")} to ${String(period?.toDate ?? "?")}, unit ${String(report.unit ?? "?")}):`;
+      const summary = typeof report.summary === "string" && report.summary.length > 0 ? report.summary : JSON.stringify(compact(report, ["report"]));
+      return clampText(`${header}
+
+${summary}`);
+    }
+  });
+  registerReadTool(server, {
+    name: "joy_get_loyalty_revenue_report",
+    title: "Loyalty revenue impact (Shopify sales data)",
+    description: `Loyalty revenue impact measured from SHOPIFY'S OWN sales dataset (ShopifyQL), attributed by the shop's "Joy assisted" order tag. Use for: loyalty ROI, "how much revenue does the loyalty program drive?", "is the program making money?", loyalty AOV, year-over-year (YoY) comparison. Metrics: total_sales = revenue from orders tagged "Joy assisted"; aov = average order value of those orders; returning_rate = returning-customer rate among customers tagged as active redeemers; orders = count of Joy-assisted orders. compare_to_last_year applies to total_sales ONLY and is IGNORED when a custom range is given. Custom range = BOTH start_date and end_date (ISO YYYY-MM-DD), max 366 days, not in the future. ` + SCOPE_HELP + " joy_get_analytics_report (reportType assisted_revenue) measures assisted revenue from Joy's own event log \u2014 a DIFFERENT data source with different attribution; the two numbers may legitimately disagree.",
+    inputSchema: {
+      metric: z5.enum(["total_sales", "aov", "returning_rate", "orders"]).describe("Which revenue metric to compute (see description for definitions)."),
+      period: z5.enum(["last_7d", "last_30d", "last_90d", "last_1y", "this_month"]).optional().describe("Relative reporting period. Default last_30d. Ignored when start_date/end_date are given."),
+      compare_to_last_year: z5.boolean().optional().describe("Add previous-year comparison (previousValue + deltaPercent). total_sales only; ignored with a custom date range."),
+      start_date: z5.string().optional().describe("ISO date (YYYY-MM-DD) \u2014 custom range start. Requires end_date too; max 366 days."),
+      end_date: z5.string().optional().describe("ISO date (YYYY-MM-DD) \u2014 custom range end. Requires start_date too; not in the future.")
+    },
+    handler: async (args) => {
+      const data = await getScopedReport(ctx, "/analytics/loyalty-revenue", {
+        query: toLoyaltyRevenueQuery(args),
+        timeoutMs: 3e4
+      });
+      const summary = typeof data.summary === "string" ? data.summary : `${args.metric} for ${String(data.period ?? "the requested period")}: ${String(data.value ?? "no data")}.`;
+      return summaryWithJson(summary, compact(data, LOYALTY_REVENUE_KEYS));
+    }
+  });
+  registerReadTool(server, {
+    name: "joy_get_tier_performance_breakdown",
+    title: "Sales performance by VIP tier",
+    description: 'Shopify sales performance broken down by VIP tier (ShopifyQL, grouped by the Joy tier metafield). Use for: "which tier spends the most?", "revenue by tier", "AOV per tier", "orders per customer by tier". Default window is ALL-TIME; pass BOTH start_date and end_date (YYYY-MM-DD, max 366 days) to bound it. Rows are tier names sorted by value; "(unassigned)" = customers without a tier. A 422 METAFIELD_NOT_CONFIGURED error means the Joy tier metafield definition is DISABLED on this shop \u2014 that is a setup gate, NOT empty data; ask the merchant to enable it in Joy \u2192 Settings \u2192 General \u2192 Metafield section. For loyalty-side tier reports (member counts, upgrades/downgrades) use joy_get_analytics_report with tier_performance / tier_trend / tier_transitions. ' + SCOPE_HELP,
+    inputSchema: {
+      metric: z5.enum(["total_sales", "aov", "orders_per_customer", "spend_per_customer"]).describe("Which per-tier metric to compute."),
+      start_date: z5.string().optional().describe("ISO date (YYYY-MM-DD) \u2014 custom range start. Requires end_date too; max 366 days. Omit both for all-time."),
+      end_date: z5.string().optional().describe("ISO date (YYYY-MM-DD) \u2014 custom range end. Requires start_date too.")
+    },
+    handler: async (args) => {
+      let data;
+      try {
+        data = await getScopedReport(ctx, "/analytics/tier-performance", {
+          query: toTierPerformanceQuery(args),
+          timeoutMs: 3e4
+        });
+      } catch (error) {
+        if (error instanceof JoyApiError && error.status === 422) {
+          throw new JoyApiError("validation", "Tier performance needs the Joy tier metafield definition, which is currently DISABLED on this shop. This is a setup gate, not empty data and not a parameter problem \u2014 do not retry. Ask the merchant to enable it in Joy \u2192 Settings \u2192 General \u2192 Metafield section, then call again.", 422);
+        }
+        throw error;
+      }
+      const top = data.topGroup;
+      const summary = typeof data.summary === "string" ? data.summary : `${args.metric} by tier${top ? ` \u2014 top: ${String(top.group)} (${String(top.value)})` : ""}.`;
+      return summaryWithJson(summary, compact(data, TIER_PERFORMANCE_KEYS));
+    }
+  });
+  registerReadTool(server, {
+    name: "joy_get_loyalty_health_check",
+    title: "Loyalty program health check",
+    description: `Loyalty program health diagnostic \u2014 use FIRST for open-ended questions: "how is my loyalty program doing?", "is anything wrong?", "why aren't customers earning points?". Compares the current window (default last 30 days) against the equal-length prior window using Joy-internal data only \u2014 aggregate numbers, no customer PII, and NO Shopify permission needed. healthScore = 100 minus a penalty per flag (low 5, medium 15, high 25; floor 0): >=80 Healthy, 60-79 Watch, <60 Needs attention. Flags check: sandbox/test earning mode (real orders are NOT earning points \u2014 the most urgent flag), redemption rate, points-earned trend, redeem-revenue trend, data availability, and tier concentration. Pass start_date+end_date (both, YYYY-MM-DD) to move the current window. For the underlying detail behind a flag, follow up with joy_get_analytics_report.`,
+    inputSchema: {
+      start_date: z5.string().optional().describe("ISO date (YYYY-MM-DD) \u2014 custom current-window start. Requires end_date too."),
+      end_date: z5.string().optional().describe("ISO date (YYYY-MM-DD) \u2014 custom current-window end. Requires start_date too.")
+    },
+    handler: async (args) => {
+      const { data } = await ctx.api.getData("/analytics/health-check", {
+        query: toDateRangeQuery(args),
+        timeoutMs: 2e4
+      });
+      const report = data ?? {};
+      const summary = typeof report.summary === "string" ? report.summary : `Loyalty health score: ${String(report.healthScore ?? "?")}/100.`;
+      return summaryWithJson(summary, compact(report, HEALTH_CHECK_KEYS));
+    }
+  });
+}
+function registerAnalyticsWriteTools(server, ctx) {
+  registerWriteTool(server, ctx, {
+    name: "joy_enable_analytics_v2",
+    title: "Switch the shop to Analytics V2 (starts data backfill)",
+    description: 'WRITE \u2014 enables the new Analytics V2 for this shop and starts the historical data backfill in the background. Call this when joy_get_analytics_report returned the "shop is still on Analytics V1" error AND the merchant has EXPLICITLY agreed to switch \u2014 never call it unprompted: it changes the default Analytics experience in their Joy admin and runs a data migration that can take from a few minutes to a few tens of minutes. IDEMPOTENT and doubles as a STATUS CHECK: calling it again never restarts a running backfill \u2014 it returns progress (running/failed/already enabled) instead, so use it to answer "is the migration done yet?".',
+    inputSchema: {
+      merchant_confirmed: z5.literal(true).describe("Must be true \u2014 pass it ONLY after the merchant explicitly agreed to switch to the new Analytics. If they have not been asked yet, ask first instead of calling this tool.")
+    },
+    destructiveHint: false,
+    idempotentHint: true,
+    handler: async () => {
+      const { data } = await ctx.api.mutateData("/analytics/enable-v2", {
+        method: "POST",
+        timeoutMs: 2e4,
+        body: {}
+      });
+      return formatEnableStatus(data ?? {});
+    }
+  });
+}
+
+// ../mcp-core/build/tools/points.js
+import { z as z6 } from "zod";
+
+// ../mcp-core/build/tools/writeSupport.js
+import { randomUUID } from "node:crypto";
+function resolveIdempotencyKey(provided) {
+  const trimmed = provided?.trim();
+  return trimmed || randomUUID();
+}
+function rethrowWithRetryKey(error, idempotencyKey) {
+  if (error instanceof JoyApiError && (error.kind === "timeout" || error.kind === "network" || error.kind === "server")) {
+    throw new JoyApiError(error.kind, `${error.modelMessage} IMPORTANT: this was a write \u2014 it may or may not have been applied. Do NOT assume failure and do NOT retry with a fresh call. To retry safely, call the same tool again with idempotency_key: "${idempotencyKey}" within 24 hours (keys expire after that) \u2014 the backend will return the original result instead of applying the change twice.`, error.status);
+  }
+  throw error;
+}
+function rethrowRedeemUncertain(error) {
+  if (error instanceof JoyApiError && (error.kind === "timeout" || error.kind === "network" || error.kind === "server")) {
+    throw new JoyApiError(error.kind, `The redeem request failed with an UNCERTAIN outcome (${error.kind}) \u2014 it may have completed anyway, and redeem has NO retry protection. Do NOT retry now. First call joy_get_member_activity for this member and check for a redemption in the last few minutes: if one exists, the redeem succeeded (do not repeat it); only if none exists is it safe to try again.`, error.status);
+  }
+  throw error;
+}
+function rethrowRefundUncertain(error) {
+  if (error instanceof JoyApiError && (error.kind === "timeout" || error.kind === "network" || error.kind === "server")) {
+    throw new JoyApiError(error.kind, `The refund request failed with an UNCERTAIN outcome (${error.kind}) \u2014 it may have completed anyway, and refund has NO retry protection. Do NOT retry now. First call joy_get_member_activity for this member and look for a refund_point_redeem entry with this coupon code: if one exists, the refund succeeded and points were already restored (do not award them again). If the retry itself returns "coupon does not exist or has expired", that most likely means the first attempt SUCCEEDED \u2014 a revoked coupon no longer shows up in lookups.`, error.status);
+  }
+  throw error;
+}
+function buildBalancePreview(params) {
+  const { memberLabel, currentBalance, delta, toolName } = params;
+  const resulting = currentBalance + delta;
+  const negativeWarning = resulting < 0 ? ` WARNING: this would drive the balance NEGATIVE (${resulting.toLocaleString("en-US")}) \u2014 confirm with the merchant that this is intended.` : "";
+  return {
+    summary: `DRY RUN \u2014 no points were changed. ${memberLabel}: ${currentBalance.toLocaleString("en-US")} \u2192 ${resulting.toLocaleString("en-US")} (${delta >= 0 ? "+" : ""}${delta.toLocaleString("en-US")}).${negativeWarning}`,
+    payload: {
+      dry_run: true,
+      member: memberLabel,
+      current_balance: currentBalance,
+      change: delta,
+      resulting_balance: resulting,
+      ...resulting < 0 ? { warning: "resulting balance would be NEGATIVE" } : {},
+      next_step: `If this is correct, call ${toolName} again with the same arguments plus apply: true.`
+    }
+  };
+}
+function needsDeductPreview(params) {
+  const { points, threshold, currentBalance, apply } = params;
+  if (apply === true)
+    return false;
+  return points > threshold || currentBalance - points < 0;
+}
+
+// ../mcp-core/build/tools/points.js
+var MUTATION_RESULT_KEYS = [
+  "id",
+  "type",
+  "event",
+  "oldPoint",
+  "newPoint",
+  "pointChange",
+  "earnPoint",
+  "spendPoint",
+  "reason",
+  "source",
+  "createdAt"
+];
+var writeArgsSchema = {
+  ...memberIdentifierSchema,
+  reason: z6.string().min(3).describe("Why this change is being made \u2014 REQUIRED, recorded permanently in the audit trail."),
+  admin_note: z6.string().optional().describe("Optional internal note for the merchant team."),
+  idempotency_key: z6.string().max(255).optional().describe("Only pass this when RETRYING an uncertain outcome: reuse the exact key from the previous error message so the backend replays instead of applying twice. Omit for a new operation.")
+};
+async function executePointMutation(params) {
+  const { ctx, path, member, point, reason, adminNote, idempotencyKey } = params;
+  try {
+    return await ctx.api.mutateData(path, {
+      method: "POST",
+      timeoutMs: 15e3,
+      headers: { "Idempotency-Key": idempotencyKey },
+      body: {
+        shopifyCustomerId: String(member.shopifyCustomerId),
+        point,
+        reason,
+        source: "mcp",
+        ...adminNote ? { adminNote } : {}
+      }
+    });
+  } catch (error) {
+    rethrowWithRetryKey(error, idempotencyKey);
+  }
+}
+function registerPointWriteTools(server, ctx) {
+  registerWriteTool(server, ctx, {
+    name: "joy_award_points",
+    title: "Award points to a member",
+    description: "WRITE \u2014 gives points to ONE loyalty member (points are merchant money; the host will ask the user to approve). Identify the member by email or Shopify customer ID. reason is required and goes to the permanent audit trail. The operation is protected by an idempotency key, so a confirmed retry with the returned key can never double-award.",
+    inputSchema: {
+      ...writeArgsSchema,
+      points: z6.number().int().positive().describe("Points to add (positive integer).")
+    },
+    destructiveHint: false,
+    idempotentHint: false,
+    handler: async (args) => {
+      const member = await resolveMember(ctx.api, args);
+      const idempotencyKey = resolveIdempotencyKey(args.idempotency_key);
+      const result = await executePointMutation({
+        ctx,
+        path: "/transactions/points/award",
+        member,
+        point: args.points,
+        reason: args.reason,
+        adminNote: args.admin_note,
+        idempotencyKey
+      });
+      return summaryWithJson(`Awarded ${formatPoints(args.points)} points to ${memberDisplayName(member)} \u2014 balance ${formatPoints(result.oldPoint)} \u2192 ${formatPoints(result.newPoint)}.`, compact(result, MUTATION_RESULT_KEYS));
+    }
+  });
+  registerWriteTool(server, ctx, {
+    name: "joy_deduct_points",
+    title: "Deduct points from a member",
+    description: `WRITE, destructive \u2014 removes points from ONE member (points are merchant money; cannot be undone except by a compensating award). reason is required and audited. Deductions larger than ${ctx.config.deductDryRunThreshold} points return a DRY-RUN preview first \u2014 call again with apply: true to execute. Idempotency-protected.`,
+    inputSchema: {
+      ...writeArgsSchema,
+      points: z6.number().int().positive().describe("Points to remove (positive integer)."),
+      apply: z6.boolean().optional().describe(`Required (true) to EXECUTE a deduction above ${ctx.config.deductDryRunThreshold} points after reviewing the dry-run preview.`)
+    },
+    destructiveHint: true,
+    idempotentHint: false,
+    handler: async (args) => {
+      const member = await resolveMember(ctx.api, args);
+      const currentBalance = Number(member.point ?? 0);
+      const mustPreview = needsDeductPreview({
+        points: args.points,
+        threshold: ctx.config.deductDryRunThreshold,
+        currentBalance,
+        apply: args.apply
+      });
+      if (mustPreview) {
+        const preview = buildBalancePreview({
+          memberLabel: memberDisplayName(member),
+          currentBalance,
+          delta: -args.points,
+          toolName: "joy_deduct_points"
+        });
+        return summaryWithJson(preview.summary, preview.payload);
+      }
+      const idempotencyKey = resolveIdempotencyKey(args.idempotency_key);
+      const result = await executePointMutation({
+        ctx,
+        path: "/transactions/points/deduct",
+        member,
+        point: args.points,
+        reason: args.reason,
+        adminNote: args.admin_note,
+        idempotencyKey
+      });
+      return summaryWithJson(`Deducted ${formatPoints(args.points)} points from ${memberDisplayName(member)} \u2014 balance ${formatPoints(result.oldPoint)} \u2192 ${formatPoints(result.newPoint)}.`, compact(result, MUTATION_RESULT_KEYS));
+    }
+  });
+  registerWriteTool(server, ctx, {
+    name: "joy_adjust_points",
+    title: "Adjust a member's points balance",
+    description: "WRITE, destructive \u2014 corrects a member's balance by a signed delta (points are merchant money). ALWAYS dry-runs first: the initial call returns a preview of current \u2192 resulting balance WITHOUT changing anything; call again with apply: true to execute. reason is required and audited. Idempotency-protected.",
+    inputSchema: {
+      ...writeArgsSchema,
+      points_delta: z6.number().int().refine((value) => value !== 0, { message: "points_delta must not be 0" }).describe("Signed change: positive adds, negative removes."),
+      apply: z6.boolean().optional().describe("Must be true to EXECUTE. Omit (or false) to get the dry-run preview.")
+    },
+    destructiveHint: true,
+    idempotentHint: false,
+    handler: async (args) => {
+      const member = await resolveMember(ctx.api, args);
+      const currentBalance = Number(member.point ?? 0);
+      if (args.apply !== true) {
+        const preview = buildBalancePreview({
+          memberLabel: memberDisplayName(member),
+          currentBalance,
+          delta: args.points_delta,
+          toolName: "joy_adjust_points"
+        });
+        return summaryWithJson(preview.summary, preview.payload);
+      }
+      const idempotencyKey = resolveIdempotencyKey(args.idempotency_key);
+      const result = await executePointMutation({
+        ctx,
+        path: "/transactions/points/adjust",
+        member,
+        point: args.points_delta,
+        reason: args.reason,
+        adminNote: args.admin_note,
+        idempotencyKey
+      });
+      return summaryWithJson(`Adjusted ${memberDisplayName(member)}'s balance by ${args.points_delta >= 0 ? "+" : "-"}${formatPoints(Math.abs(args.points_delta))} \u2014 ${formatPoints(result.oldPoint)} \u2192 ${formatPoints(result.newPoint)}.`, compact(result, MUTATION_RESULT_KEYS));
+    }
+  });
+  registerWriteTool(server, ctx, {
+    name: "joy_redeem_reward",
+    title: "Redeem points for a reward",
+    description: "WRITE, destructive \u2014 spends a member's points on a redemption program and returns the issued coupon code. Find the program_id via joy_list_redemption_rules first. Can take up to ~30s (a Shopify discount is minted inline). NO server-side retry protection yet: if the outcome is uncertain (timeout), verify via joy_get_member_activity BEFORE any retry \u2014 a blind retry can double-spend.",
+    inputSchema: {
+      ...memberIdentifierSchema,
+      program_id: z6.string().describe("Redemption program ID (from joy_list_redemption_rules)."),
+      redeem_points: z6.number().int().positive().describe("Points to spend on this redemption.")
+    },
+    destructiveHint: true,
+    idempotentHint: false,
+    handler: async (args) => {
+      const member = await resolveMember(ctx.api, args);
+      let result;
+      try {
+        result = await ctx.api.mutateData("/redeem", {
+          method: "POST",
+          timeoutMs: 3e4,
+          body: {
+            programId: args.program_id,
+            customerId: String(member.id),
+            redeemPoint: args.redeem_points
+          }
+        });
+      } catch (error) {
+        rethrowRedeemUncertain(error);
+      }
+      const discount = result?.discount ?? {};
+      const customer = result?.customer ?? {};
+      if (!discount.code) {
+        throw new JoyApiError("server", "The redeem response did not include a coupon code \u2014 treat this redemption as NOT completed. Common causes: insufficient points, program unavailable, or gift out of stock. Check the member balance and program via joy_find_member / joy_list_redemption_rules, and verify no redemption was recorded via joy_get_member_activity before trying again.");
+      }
+      return summaryWithJson(`Redeemed ${formatPoints(args.redeem_points)} points from ${memberDisplayName(member)} for coupon "${String(discount.code)}" \u2014 balance now ${formatPoints(customer.point)}.`, {
+        coupon: compact(discount, ["code", "title", "expiredAt"]),
+        member_balance: customer.point
+      });
+    }
+  });
+}
+
+// ../mcp-core/build/tools/rewards.js
+import { z as z7 } from "zod";
+function registerRewardWriteTools(server, ctx) {
+  registerWriteTool(server, ctx, {
+    name: "joy_refund_coupon",
+    title: "Refund / revoke / cancel a redeemed coupon",
+    description: 'WRITE \u2014 refunds, revokes, cancels, voids, or undoes a coupon a member redeemed with points (use this for ANY request to "revoke", "disable", "cancel", "void", or "undo" a point-redeemed coupon/discount code). IMPORTANT: this AUTOMATICALLY credits the spent points back to the member as part of the refund (a refund_point_redeem activity is recorded with your reason) \u2014 do NOT also call joy_award_points afterward, that would double-credit them. Only coupons that came from a POINT REDEMPTION can be refunded this way (not coupons from other sources, e.g. manual discounts). Identify the member by email or Shopify customer ID \u2014 do not ask the caller for a raw customer ID.',
+    inputSchema: {
+      ...memberIdentifierSchema,
+      coupon_code: z7.string().describe("The discount code to refund (from joy_get_member_rewards or joy_get_member_activity)."),
+      reason: z7.string().min(3).describe("Why this coupon is being refunded \u2014 REQUIRED, recorded in the audit trail.")
+    },
+    destructiveHint: true,
+    idempotentHint: false,
+    handler: async (args) => {
+      const member = await resolveMember(ctx.api, args);
+      try {
+        await ctx.api.mutateData("/rewards/coupons/refund", {
+          method: "POST",
+          timeoutMs: 15e3,
+          body: {
+            discountCode: args.coupon_code,
+            shopifyCustomerId: String(member.shopifyCustomerId),
+            reason: args.reason
+          }
+        });
+      } catch (error) {
+        rethrowRefundUncertain(error);
+      }
+      const updated = await resolveMember(ctx.api, args).catch(() => member);
+      return summaryWithJson(`Refunded coupon "${args.coupon_code}" for ${memberDisplayName(member)} \u2014 points were automatically credited back, balance now ${formatPoints(updated.point)}. Do not award points separately for this.`, compact(updated, ["id", "shopifyCustomerId", "point"]));
+    }
+  });
+}
+
+// ../mcp-core/build/tools/retention.js
+import { z as z8 } from "zod";
+var POINTS_EXPIRING_KEYS = [
+  "customerId",
+  "name",
+  "email",
+  "shopifyCustomerId",
+  "point",
+  "expiredAt",
+  "daysUntilExpiry"
+];
+var TIER_DROP_RISK_KEYS = [
+  "customerId",
+  "name",
+  "email",
+  "shopifyCustomerId",
+  "tierId",
+  "tierName",
+  "lastOrderAt",
+  "daysUntilDemotion",
+  "demotion"
+];
+function toRetentionRiskQuery(args) {
+  const query = {};
+  if (args.signal !== void 0)
+    query.signal = args.signal;
+  if (args.window_days !== void 0)
+    query.windowDays = args.window_days;
+  if (args.tier_id !== void 0)
+    query.tierId = args.tier_id;
+  if (args.limit !== void 0)
+    query.limit = args.limit;
+  return query;
+}
+function registerRetentionTools(server, ctx) {
+  registerReadTool(server, {
+    name: "joy_get_retention_risk_members",
+    title: "Find members at risk of losing points or dropping a VIP tier",
+    description: 'READ-ONLY retention/outreach tool \u2014 "which members are about to lose points or drop a VIP tier, so I can proactively reach out?" Two independent signals via `signal`: "points_expiring" = members with points expiring within `window_days` (ONLY covers shops on earn-time/FIFO point expiration \u2014 shops using all-at-once expiration are not covered by this signal, so an empty result here does not mean no one is losing points); "tier_drop_risk" = members the REAL tier-demotion engine will demote soon \u2014 Joy demotes on INACTIVITY (no order since the tier program\'s configured demotion window), so a member is at risk when their last order is already past that cutoff (`daysUntilDemotion: 0` = demotable on the very next demotion run) or will pass it within `window_days` unless they order again; each row carries `demotion`: "down_one_tier" or "reset_to_lowest_tier" per the program\'s setting. A shop can also (or instead) run a SCHEDULED STORE-WIDE reset on a fixed calendar day \u2014 then the response carries `tier_scheduled_reset` (resetAt + daysUntilReset): EVERY member resets to the lowest tier on that date at once, so the correct answer is that DATE, not a per-member list. If the shop has tier demotion disabled, the response includes `tierDropRiskNote` saying the signal does not apply \u2014 report that note, never conclude "no one is at risk" from the empty list. Known limit: shops using assessment-based demotion (periodic spending re-evaluation) are not predicted by this signal. Optionally scope to one tier with `tier_id` (the lowest tier is never at risk \u2014 nothing to drop to). Default "both" returns both signals in one call. Results are HARD-CAPPED: window_days max 30, limit max 50 per signal (values above the cap are silently clamped, not rejected) \u2014 this is a shortlist for outreach, never the full at-risk population. Returns only the fields needed to act (name/email, expiring points/days, last-order date/days-until-demotion) plus has_more \u2014 never the member\'s full activity history.',
+    inputSchema: {
+      signal: z8.enum(["points_expiring", "tier_drop_risk", "both"]).optional().describe('Which retention-risk signal to check. "points_expiring" for expiring-points questions, "tier_drop_risk" for tier-downgrade-risk questions, "both" (default) when the merchant asks broadly (e.g. "who is at risk of leaving?").'),
+      window_days: z8.number().int().min(1).max(30).optional().describe("Lookahead for BOTH signals (default 7, hard-capped at 30 \u2014 larger values are clamped, not rejected): points_expiring = points expiring within this many days; tier_drop_risk = members who are already demotable or become demotable within this many days."),
+      tier_id: z8.string().optional().describe("For tier_drop_risk: scope to one VIP tier ID (from joy_list_tiers). Omit to check every non-exclusive tier above the lowest \u2014 the result limit is split evenly across tiers."),
+      limit: z8.number().int().min(1).max(50).optional().describe("Max members per signal (default 20, hard-capped at 50).")
+    },
+    handler: async (args) => {
+      const { data } = await ctx.api.getData("/customers/retention-risk", {
+        query: toRetentionRiskQuery(args)
+      });
+      const result = data ?? {};
+      const pointsExpiring = Array.isArray(result.pointsExpiring) ? result.pointsExpiring : [];
+      const tierDropRisk = Array.isArray(result.tierDropRisk) ? result.tierDropRisk : [];
+      const signal = typeof result.signal === "string" ? result.signal : args.signal ?? "both";
+      const tierDropRiskNote = typeof result.tierDropRiskNote === "string" ? result.tierDropRiskNote : void 0;
+      const scheduledReset = result.tierScheduledReset && typeof result.tierScheduledReset === "object" ? result.tierScheduledReset : void 0;
+      const scheduledResetLine = scheduledReset ? `store-wide scheduled tier reset: ALL members reset to the lowest tier on ${scheduledReset.resetAt} (in ${scheduledReset.daysUntilReset} day(s))` : void 0;
+      if (pointsExpiring.length === 0 && tierDropRisk.length === 0) {
+        if (scheduledResetLine) {
+          return `No per-member retention-risk list for the requested signal(s), but note the ${scheduledResetLine}.`;
+        }
+        return tierDropRiskNote ? `No members currently at retention risk for the requested signal(s). Note on the tier signal: ${tierDropRiskNote}` : "No members currently at retention risk for the requested signal(s).";
+      }
+      const summaryParts = [];
+      if (signal !== "tier_drop_risk") {
+        summaryParts.push(`${pointsExpiring.length} member(s) with points expiring soon`);
+      }
+      if (signal !== "points_expiring") {
+        summaryParts.push(tierDropRiskNote ? `tier signal not applicable (${tierDropRiskNote})` : `${tierDropRisk.length} member(s) at risk of dropping a VIP tier`);
+        if (scheduledResetLine)
+          summaryParts.push(scheduledResetLine);
+      }
+      return summaryWithJson(`${summaryParts.join(", ")}.`, {
+        signal,
+        pointsExpiring: pointsExpiring.map((item) => compact(item, POINTS_EXPIRING_KEYS)),
+        tierDropRisk: tierDropRisk.map((item) => compact(item, TIER_DROP_RISK_KEYS)),
+        ...tierDropRiskNote ? { tier_drop_risk_note: tierDropRiskNote } : {},
+        ...scheduledReset ? { tier_scheduled_reset: scheduledReset } : {},
+        has_more: result.hasMore === true
+      });
+    }
+  });
+}
+
+// ../mcp-core/build/tools/risk.js
+var REDEMPTION_KEYS = ["id", "couponCode", "programTitle", "createdAt"];
+var FLAG_LABELS = {
+  referral_email_similarity: "referred someone with a highly similar email address",
+  referral_device_match: "shares a last-known IP/device value with their referrer",
+  referee_had_prior_order: "already had an order before being referred (not actually a new customer)",
+  high_daily_redemptions: "redeemed an unusually high number of rewards today"
+};
+function describeFlags(flags) {
+  return flags.map((flag) => FLAG_LABELS[flag] ?? flag).join("; ");
+}
+function shapeSupportingData(supportingData) {
+  const shaped = {};
+  if (Array.isArray(supportingData.similarEmailReferrals)) {
+    shaped.similarEmailReferrals = supportingData.similarEmailReferrals.map((item) => ({ email: item.email }));
+  }
+  if (supportingData.referralDeviceMatch) {
+    const source = supportingData.referralDeviceMatch;
+    shaped.referralDeviceMatch = { matchedReferrerDevice: source.matchedReferrerDevice === true };
+  }
+  if (supportingData.priorOrderBeforeReferral) {
+    const source = supportingData.priorOrderBeforeReferral;
+    shaped.priorOrderBeforeReferral = { latestOrderActivity: source.latestOrderActivity };
+  }
+  if (Array.isArray(supportingData.todaysRedemptions)) {
+    shaped.todaysRedemptions = supportingData.todaysRedemptions.map((item) => compact(item, REDEMPTION_KEYS));
+  }
+  return shaped;
+}
+function registerRiskTools(server, ctx) {
+  registerReadTool(server, {
+    name: "joy_investigate_member_risk",
+    title: "Investigate a member for referral/redemption abuse risk",
+    description: `READ-ONLY fraud/abuse investigation for ONE member \u2014 "is this member doing anything suspicious?" Checks a FIXED, hard-coded set of flags (the same rules run every time, not a judgment call): referral_email_similarity (this member referred someone whose email closely matches their own \u2014 e.g. john+1@/john+2@ patterns); referral_device_match (this member's CURRENT last-known IP/device value matches their referrer's CURRENT last-known value); referee_had_prior_order (this member already had an order before being referred, so was not actually a new customer); high_daily_redemptions (redeemed more than a fixed threshold of rewards today). The response includes supporting data ONLY for flags that actually fired (e.g. the masked similar-email referrals, or today's redemption list) \u2014 if nothing is flagged, no supporting data is returned; this is NOT a full activity/history dump, so do not ask follow-up questions expecting more raw data from this same call. CRITICAL DATA LIMITS \u2014 do not claim more than this: there is NO IP/device HISTORY anywhere in Joy, only a single last-known value per customer that gets overwritten on every storefront visit \u2014 so referral_device_match is a live snapshot comparison, NOT a check of what the IP/device was at the actual moment the referral was claimed (that comparison happens live during the claim and is never stored). Do NOT say things like "this customer used N different IPs" or "here is their IP address" \u2014 that data does not exist and IPs are never returned, only a boolean match. Redemption velocity is checked at DAY granularity only \u2014 there is no minute/hour-level velocity check, so do not claim to detect rapid-fire redemption bursts within a single day. This tool never locks accounts, cancels rewards, or takes any action \u2014 it only surfaces flags for the merchant to review and decide next steps.`,
+    inputSchema: memberIdentifierSchema,
+    handler: async (args) => {
+      const member = await resolveMember(ctx.api, args);
+      const who = memberDisplayName(member);
+      const { data } = await ctx.api.getData(`/customers/${encodeURIComponent(String(member.id))}/risk-assessment`);
+      const result = data ?? {};
+      const flags = Array.isArray(result.flags) ? result.flags : [];
+      const supportingData = result.supportingData ?? {};
+      const limitations = Array.isArray(result.limitations) ? result.limitations : [];
+      if (flags.length === 0) {
+        return summaryWithJson(`No risk flags for ${who} \u2014 none of the checked signals fired.`, {
+          flags: [],
+          limitations
+        });
+      }
+      return summaryWithJson(`${who}: ${flags.length} risk flag(s) \u2014 ${describeFlags(flags)}.`, {
+        flags,
+        supportingData: shapeSupportingData(supportingData),
+        limitations
+      });
+    }
+  });
+}
+
+// ../mcp-core/build/tools/orderExplain.js
+import { z as z9 } from "zod";
+var RULE_KEYS = ["programId", "title", "priority", "matched", "earnedPoints", "reasons"];
+function describeRule(rule) {
+  const title = typeof rule.title === "string" ? rule.title : String(rule.programId ?? "rule");
+  if (rule.matched === null)
+    return `${title}: not evaluated (a higher-priority rule stopped processing)`;
+  if (rule.matched === true)
+    return `${title}: matched, +${rule.earnedPoints ?? 0} pts`;
+  const reasons = Array.isArray(rule.reasons) ? rule.reasons.join("; ") : "";
+  return `${title}: did not match${reasons ? ` (${reasons})` : ""}`;
+}
+function registerOrderExplainTools(server, ctx) {
+  registerReadTool(server, {
+    name: "joy_explain_order_points",
+    title: "Explain why an order did or didn't earn points",
+    description: "READ-ONLY explanation of the loyalty points earning rule engine for ONE order \u2014 \"why did/didn't this order earn points (or earn fewer than expected)?\" The response's `explainSource` field tells you which of two modes produced it: `recorded` means the answer comes from the decision-time trace the REAL earn pipeline stored on the order's activity when it was processed (historical ground truth \u2014 per-rule pass/fail with the exact condition fields that failed, recorded at `recordedAt`); `replay` means no stored trace exists (order processed before tracing shipped, or a legacy calculation path) and this is a RECONSTRUCTION run against the order's CURRENT Shopify snapshot, reusing the exact same gate and rule-matching functions the real earn pipeline uses \u2014 NOT a historical record. If the order was modified after points were originally calculated (e.g. a partial refund applied after the initial award), this tool reports against the order's current state, which may not match what was actually awarded at the time \u2014 do not present this as infallible ground truth for what happened historically; treat it as \"what the rules say NOW\". Evaluation order: (1) pre-rule-engine gates \u2014 no customer matched on the order, guest checkout not opted in, customer left the loyalty program, order not paid/fulfilled per the shop's setting, order fully refunded, or an update arriving after the order was already closed; if any gate blocks, `blockedByGate` explains which one and no rules were evaluated. (2) If gates pass, every active place-order earning rule is evaluated in priority order (`rules`), each with `matched` true/false/null and human-readable `reasons` \u2014 `matched: null` means the rule was NEVER evaluated because a higher-priority rule matched first with \"stop processing\" enabled (distinct from `false`, which means it WAS evaluated and did not match). (3) `maxTheoreticalPoints` is the total before the global per-customer/tier earning cap; `totalEarnedPoints` is after; `cappedBy` is set only when that cap actually reduced the total. Scope: covers the place_order (checkout) earning event only \u2014 birthday, sign-up, and milestone rewards are NOT covered by this tool.",
+    inputSchema: {
+      order_id: z9.string().describe('The order to explain \u2014 either the internal Shopify order ID (numeric) or the order name as shown to the merchant, e.g. "#1234".')
+    },
+    handler: async (args) => {
+      const { data } = await ctx.api.getData(`/orders/${encodeURIComponent(args.order_id)}/points-explanation`);
+      const result = data ?? {};
+      const explainSource = typeof result.explainSource === "string" ? result.explainSource : "replay";
+      const recordedAt = typeof result.recordedAt === "string" ? result.recordedAt : null;
+      const sourceNote = explainSource === "recorded" ? ` [from the recorded decision-time trace${recordedAt ? `, ${recordedAt}` : ""}]` : " [reconstructed against the current order state]";
+      if (result.blockedByGate) {
+        const blockedRules = Array.isArray(result.rules) ? result.rules : [];
+        return summaryWithJson(`This order did not earn points: ${result.blockedByGate}${sourceNote}`, {
+          blockedByGate: result.blockedByGate,
+          rules: blockedRules.map((rule) => compact(rule, RULE_KEYS)),
+          totalEarnedPoints: 0,
+          explainSource,
+          recordedAt
+        });
+      }
+      const rules = Array.isArray(result.rules) ? result.rules : [];
+      const totalEarnedPoints = typeof result.totalEarnedPoints === "number" ? result.totalEarnedPoints : 0;
+      const maxTheoreticalPoints = typeof result.maxTheoreticalPoints === "number" ? result.maxTheoreticalPoints : 0;
+      const cappedBy = result.cappedBy ?? null;
+      const summaryLines = [
+        `Order earned ${totalEarnedPoints} point(s)${cappedBy ? ` (capped down from ${maxTheoreticalPoints} by the global earning limit)` : ""}.${sourceNote}`,
+        ...rules.map((rule) => `- ${describeRule(rule)}`)
+      ];
+      return summaryWithJson(summaryLines.join("\n"), {
+        blockedByGate: null,
+        rules: rules.map((rule) => compact(rule, RULE_KEYS)),
+        totalEarnedPoints,
+        maxTheoreticalPoints,
+        cappedBy,
+        explainSource,
+        recordedAt
+      });
+    }
+  });
+}
+
+// ../mcp-core/build/tools/activityAudit.js
+import { z as z10 } from "zod";
+var AUDIT_GROUPS = [
+  "tier_downgraded",
+  "tier_upgraded",
+  "points_earned",
+  "points_redeemed",
+  "points_refunded",
+  "points_expired",
+  "points_adjusted",
+  "referral",
+  "members_joined"
+];
+var AUDIT_ITEM_KEYS = [
+  "type",
+  "customerId",
+  "email",
+  "shopifyCustomerId",
+  "point",
+  "orderId",
+  "orderName",
+  "programId",
+  "programTitle",
+  "couponCode",
+  "oldTierName",
+  "newTierName",
+  "referralCustomerEmail",
+  "source",
+  "createdAt"
+];
+function toActivityAuditQuery(args) {
+  const query = { group: args.group };
+  if (args.program_id !== void 0)
+    query.programId = args.program_id;
+  if (args.from_date !== void 0)
+    query.fromDate = args.from_date;
+  if (args.to_date !== void 0)
+    query.toDate = args.to_date;
+  if (args.limit !== void 0)
+    query.limit = args.limit;
+  return query;
+}
+function registerActivityAuditTools(server, ctx) {
+  registerReadTool(server, {
+    name: "joy_list_activities",
+    title: "List loyalty activities across members (audit by activity group)",
+    description: 'READ-ONLY shop-wide activity audit \u2014 "WHICH members did X in this period", the cross-member counterpart of joy_get_member_activity (one member\'s history) and of joy_get_analytics_report report_type=tier_transitions (aggregate COUNTS only, no names). Use this when the merchant asks WHO, use analytics when they ask HOW MANY. One semantic `group` per call, each spanning every raw activity type that feature area produces: "tier_downgraded" covers ALL THREE demotion mechanisms (reassessment demote_tier, inactivity downgrade_tier, relaunch reset_tier \u2014 never query one of these alone or you will miss mechanisms); "tier_upgraded" = tier upgrades; "points_earned" = program point earns (rows include orderName when the earn came from an order); "points_redeemed" = redemptions web + POS (each row carries programId/programTitle \u2014 combine with `program_id` for "who redeemed program A?"); "points_refunded" / "points_expired" / "points_adjusted" = the corresponding point movements; "referral" = referral outcomes (referred members, referred orders, referral rewards + revocations \u2014 rows carry referralCustomerEmail linking referrer and referee); "members_joined" = joins/rejoins. Time range: from_date/to_date (defaults to the last 30 days, range hard-capped at 366 days \u2014 an over-wide range is clamped to the most recent 366 days, not rejected). Results are a HARD-CAPPED shortlist: limit max 50 (default 20), newest first, plus has_more \u2014 never the full population; treat has_more:true as "narrow the range or filter, do not page exhaustively".',
+    inputSchema: {
+      group: z10.enum(AUDIT_GROUPS).describe('Which activity group to audit. Pick by merchant intent: "who dropped a tier" \u2192 tier_downgraded; "who redeemed (program A)" \u2192 points_redeemed (+ program_id); "who earned points from orders" \u2192 points_earned; "who referred people" \u2192 referral.'),
+      program_id: z10.string().optional().describe("Scope to one program (from joy_list_earning_rules / joy_list_redemption_rules), e.g. redemptions of one specific reward. Applied as a post-filter \u2014 a sparse program in a busy shop may fill fewer rows than `limit`."),
+      from_date: z10.string().optional().describe("Start of the period, ISO date (e.g. 2026-07-01). Default: 30 days before to_date."),
+      to_date: z10.string().optional().describe("End of the period, ISO date. Default: now."),
+      limit: z10.number().int().min(1).max(50).optional().describe("Max rows (default 20, hard-capped at 50).")
+    },
+    handler: async (args) => {
+      const { data } = await ctx.api.getData("/activities/audit", {
+        query: toActivityAuditQuery(args)
+      });
+      const result = data ?? {};
+      const items = Array.isArray(result.items) ? result.items : [];
+      if (items.length === 0) {
+        return `No "${args.group}" activities found between ${result.fromDate} and ${result.toDate}${args.program_id ? ` for program ${args.program_id}` : ""}.`;
+      }
+      return summaryWithJson(`${items.length} "${args.group}" activit${items.length === 1 ? "y" : "ies"} between ${result.fromDate} and ${result.toDate}${result.hasMore === true ? " (more exist beyond the cap \u2014 narrow the range to see the rest)" : ""}.`, {
+        group: result.group,
+        from_date: result.fromDate,
+        to_date: result.toDate,
+        items: items.map((item) => compact(item, AUDIT_ITEM_KEYS)),
+        has_more: result.hasMore === true
+      });
+    }
+  });
+}
+
+// ../mcp-core/build/tools/tierUpgrade.js
+import { z as z11 } from "zod";
+var UPGRADE_ITEM_KEYS = [
+  "customerId",
+  "name",
+  "email",
+  "shopifyCustomerId",
+  "tierId",
+  "tierName",
+  "tierPoint",
+  "nextTierId",
+  "nextTierName",
+  "nextTierTarget",
+  "pointsToNextTier"
+];
+function toTierUpgradeQuery(args) {
+  const query = {};
+  if (args.tier_id !== void 0)
+    query.tierId = args.tier_id;
+  if (args.margin_points !== void 0)
+    query.marginPoints = args.margin_points;
+  if (args.limit !== void 0)
+    query.limit = args.limit;
+  return query;
+}
+function registerTierUpgradeTools(server, ctx) {
+  registerReadTool(server, {
+    name: "joy_get_tier_upgrade_candidates",
+    title: "Find members close to reaching the next VIP tier",
+    description: 'READ-ONLY growth/upsell outreach tool \u2014 "which members are ABOUT TO reach the next VIP tier, so I can nudge them over the line?" (e.g. "kh\xE1ch n\xE0o s\u1EAFp l\xEAn Gold?"). The mirror of joy_get_retention_risk_members\' tier_drop_risk signal: that one finds members about to FALL, this one finds members about to CLIMB. Upgrades in Joy apply immediately when tierPoint reaches the next tier\'s threshold, so distance-to-threshold is the exact signal \u2014 each row reports the member\'s current tier, tierPoint, the next tier and its threshold, and `pointsToNextTier` (how little they still need). Sorted closest-first. `margin_points` defines "close" (default: 10% of the next tier\'s own threshold, so it scales with the shop); note tierPoint is measured in the tier program\'s entry metric \u2014 points, money spent, or order count depending on the program setup \u2014 so quote distances in that unit, not always "points". Optionally scope to one CURRENT tier with `tier_id` (from joy_list_tiers); the highest tier is never a candidate (nothing to climb to), exclusive/VIP-deal tiers are excluded on both ends. Results are a HARD-CAPPED shortlist (limit max 50, default 20, split evenly across tiers when unscoped) plus has_more \u2014 never the full population. For ONE member\'s own distance to the next tier, prefer joy_find_member (field pointsRemain) instead.',
+    inputSchema: {
+      tier_id: z11.string().optional().describe("Scope to members currently in this VIP tier ID (from joy_list_tiers). Omit to check every climbable tier \u2014 the result limit is split evenly across tiers."),
+      margin_points: z11.number().min(1).optional().describe(`How close (in the tier program's entry metric) counts as "near the next tier". Default: 10% of the next tier's threshold. Use an explicit value when the merchant names one ("within 100 points of Gold").`),
+      limit: z11.number().int().min(1).max(50).optional().describe("Max members returned (default 20, hard-capped at 50).")
+    },
+    handler: async (args) => {
+      const { data } = await ctx.api.getData("/customers/tier-upgrade-candidates", {
+        query: toTierUpgradeQuery(args)
+      });
+      const result = data ?? {};
+      const items = Array.isArray(result.items) ? result.items : [];
+      if (items.length === 0) {
+        return "No members are currently within the margin of their next VIP tier. Consider widening margin_points, or check the tier setup with joy_list_tiers.";
+      }
+      return summaryWithJson(`${items.length} member(s) close to reaching their next VIP tier (closest first)${result.hasMore === true ? " \u2014 more exist beyond the cap" : ""}.`, {
+        items: items.map((item) => compact(item, UPGRADE_ITEM_KEYS)),
+        has_more: result.hasMore === true
+      });
+    }
+  });
+}
+
+// ../mcp-core/build/prompts.js
+import { z as z12 } from "zod";
+function registerAllPrompts(server) {
+  server.registerPrompt("support_missing_points", {
+    title: "Investigate missing points for an order",
+    description: "Support workflow: verify whether a customer really is missing points for an order, explain why, and prepare a compensation proposal with a proper audit reason.",
+    argsSchema: {
+      email: z12.string().describe("Customer's email address"),
+      order_number: z12.string().optional().describe("Order name/number the customer says earned nothing, e.g. #1234")
+    }
+  }, ({ email, order_number }) => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: [
+            `A customer (${email}) reports they did not receive loyalty points${order_number ? ` for order ${order_number}` : ""}. Investigate before changing anything:`,
+            "",
+            "1. Look up the member with joy_find_member \u2014 flag anything unusual (disabled state, guest, recently created).",
+            `2. Check joy_get_member_activity for an earn entry matching the order${order_number ? "" : " they describe (ask me for the order number if you cannot identify it)"}.`,
+            order_number ? `3. Run joy_explain_order_points for ${order_number} \u2014 it re-runs the actual earning engine and reports which gate or rule condition blocked earning, if any.` : "3. Once the order is identified, run joy_explain_order_points on it \u2014 it re-runs the actual earning engine and reports which gate or rule condition blocked earning, if any.",
+            "4. Conclude with exactly one of: (a) points were already awarded (show the activity entry), (b) points were correctly not awarded (show the blocking gate/rule \u2014 cite its configured threshold or condition, do not paraphrase from memory), or (c) points are genuinely missing.",
+            "5. Only for case (c): state the exact number of points owed and propose a joy_award_points call with a reason that names the order and the root cause. Wait for my explicit confirmation before executing \u2014 never award in the same turn as the diagnosis.",
+            "",
+            "Caveat to include when you rely on joy_explain_order_points: it recomputes against the order as it exists now \u2014 if the order changed after the original webhook (e.g. partial refund), the explanation reflects the current state, not the historical moment."
+          ].join("\n")
+        }
+      }
+    ]
+  }));
+  server.registerPrompt("program_review", {
+    title: "Loyalty program review (health + revenue + tiers + referral)",
+    description: "Periodic business review: program health check, revenue impact, tier performance, and referral results \u2014 with data-source rules so numbers from different systems are never mixed.",
+    argsSchema: {
+      period: z12.string().optional().describe("Reporting period, e.g. 'last 30 days', 'last month', 'this quarter'. Defaults to last 30 days.")
+    }
+  }, ({ period }) => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: [
+            `Review my loyalty program for ${period ?? "the last 30 days"}. Run, in parallel where possible:`,
+            "",
+            "1. joy_get_loyalty_health_check \u2014 overall score and flags.",
+            "2. joy_get_loyalty_revenue_report \u2014 revenue impact (Shopify sales data).",
+            "3. joy_get_tier_performance_breakdown \u2014 which VIP tier earns its keep.",
+            "4. joy_get_analytics_report with report_type referral_summary, and points_movement for the same period.",
+            "",
+            "Data-source rules (important):",
+            "- joy_get_loyalty_revenue_report and joy_get_tier_performance_breakdown read Shopify sales data (ShopifyQL); joy_get_analytics_report reads the Joy event log (BigQuery). These measure differently \u2014 label the source of every figure and never combine numbers across the two sources into one derived metric.",
+            "- If a ShopifyQL tool returns a 403 about the read_reports scope, relay its grant instructions instead of substituting numbers from the other source.",
+            "- If any response carries a backfill WARNING, repeat that caveat next to the affected numbers \u2014 do not present them as final.",
+            "",
+            "Format: a 3-sentence executive summary first, then anomalies worth my attention (with the flag or figure that triggered each), then exactly one concrete recommended action. Skip metrics that are unremarkable."
+          ].join("\n")
+        }
+      }
+    ]
+  }));
+  server.registerPrompt("investigate_member", {
+    title: "Investigate a member for abuse risk",
+    description: "Fraud/abuse triage for one member: risk flags, point activity, and referral history \u2014 with the mandatory caveat about signal limitations and no punitive action.",
+    argsSchema: {
+      email: z12.string().describe("Email of the member to investigate")
+    }
+  }, ({ email }) => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: [
+            `I suspect member ${email} may be abusing the loyalty program (referral self-dealing, unusual redemptions, or similar). Investigate:`,
+            "",
+            "1. joy_find_member \u2014 profile basics and state.",
+            "2. joy_investigate_member_risk \u2014 the pre-defined abuse flags. For every flag that fires, show the concrete supporting data the tool returns; do not add suspicions of your own beyond the flags.",
+            "3. joy_get_member_activity and joy_get_member_referrals \u2014 recent point movements and referral results, to give the flags context.",
+            "",
+            "Mandatory caveat in your answer: device/IP matching compares the MOST RECENT values only \u2014 there is no full history over time \u2014 so these flags are advisory signals to support my judgement, not proof of abuse.",
+            "",
+            "End with: which flags fired (if any), what specific records I should open in the Joy admin to verify each one, and your read on severity. Do NOT deduct points, refund coupons, or take any corrective action \u2014 this session is investigation only; I will decide separately."
+          ].join("\n")
+        }
+      }
+    ]
+  }));
+}
+
+// ../mcp-core/build/registry.js
+function registerAllTools(server, ctx) {
+  registerOverviewTools(server, ctx);
+  registerAnalyticsTools(server, ctx);
+  registerMemberTools(server, ctx);
+  registerTierTools(server, ctx);
+  registerProgramTools(server, ctx);
+  registerReferralTools(server, ctx);
+  registerRetentionTools(server, ctx);
+  registerRiskTools(server, ctx);
+  registerOrderExplainTools(server, ctx);
+  registerActivityAuditTools(server, ctx);
+  registerTierUpgradeTools(server, ctx);
+  if (ctx.config.writesEnabled) {
+    registerPointWriteTools(server, ctx);
+    registerTierWriteTools(server, ctx);
+    registerRewardWriteTools(server, ctx);
+    registerReferralWriteTools(server, ctx);
+    registerAnalyticsWriteTools(server, ctx);
+    log.info("write tools ENABLED (award/deduct/adjust/redeem/set-tier/refund-coupon/create-referral-invite/enable-analytics-v2). Requires the deployed REST v2 write-path (reason/source/Idempotency-Key support) \u2014 against an older backend, reason/source are silently dropped and idempotency is not enforced.");
+  }
+}
+
+// src/index.ts
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
+async function main() {
+  const config = loadConfig();
+  const api = new JoyApi(config);
+  const server = new McpServer({ name: "joy-loyalty", version });
+  registerAllTools(server, { api, config, cache: new TtlCache() });
+  registerAllPrompts(server);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  log.info(
+    `joy-mcp v${version} ready \u2014 mode=${config.mode}, tools=${config.writesEnabled ? "read+write" : "read-only"}, api=${config.apiBaseUrl}`
+  );
+}
+main().catch((error) => {
+  if (error instanceof ConfigError) {
+    log.error(error.message);
+  } else {
+    log.error(`fatal: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  process.exit(1);
+});