@joy-loyalty/mcp 0.4.0 → 0.5.0

package/build/index.js

@@ -2,6 +2,7 @@
 
 // src/index.ts
 import { createRequire } from "node:module";
+import { randomUUID as randomUUID3 } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
@@ -67,17 +68,368 @@ function loadConfig(env = process.env) {
     deductDryRunThreshold
   };
 }
+var DEFAULT_TELEMETRY_MODE = "headers";
+function telemetryMode(env = process.env) {
+  const mode = (env.JOY_MCP_TELEMETRY ?? "").trim().toLowerCase();
+  const doNotTrack = (env.DO_NOT_TRACK ?? "").trim().toLowerCase();
+  if (["1", "true"].includes(doNotTrack) || ["off", "false", "0"].includes(mode)) return "off";
+  if (mode === "on") return "full";
+  return DEFAULT_TELEMETRY_MODE;
+}
+
+// ../mcp-core/build/telemetry/callContext.js
+import { AsyncLocalStorage } from "node:async_hooks";
+
+// ../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/telemetry/schema.js
+var SCHEMA_VERSION = 1;
+var UUID = "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$";
+var SHOP_ID = "^[A-Za-z0-9]{1,40}$";
+var SHOP_DOMAIN = "^[a-z0-9][a-z0-9.-]{0,254}$";
+var PLAN = "^[A-Za-z0-9_. -]{1,64}$";
+var VERSION = "^[A-Za-z0-9._+-]{1,64}$";
+var TOOL = "^[a-z0-9_]{1,64}$";
+var ERROR_CODE = "^[A-Za-z][A-Za-z0-9_]{0,63}$";
+var CLIENT_NAME = "^[\\x20-\\x7E]{1,64}$";
+var CLIENT_VERSION = "^[A-Za-z0-9._+-]{1,32}$";
+var CAPABILITIES = "^[a-z][a-zA-Z0-9_]{0,31}(,[a-z][a-zA-Z0-9_]{0,31}){0,9}$";
+var MAX_MS = 36e5;
+var MCP = ["remote", "stdio"];
+var REMOTE = ["remote"];
+var STDIO = ["stdio"];
+var BACKEND = ["backend"];
+var OUTCOMES = ["success", "tool_error", "rejected", "internal_error", "cancelled"];
+var ERROR_KINDS = [
+  // JoyApiError kinds (client/joyApi.ts ErrorKind)
+  "auth",
+  "plan_gate",
+  "forbidden",
+  "rate_limit",
+  "not_found",
+  "validation",
+  "conflict",
+  "server",
+  "timeout",
+  "network",
+  // handler / toolkit
+  "exception",
+  "store_mismatch",
+  "writes_disabled",
+  "config_writes_disabled",
+  // rejected before the handler ran
+  "invalid_input",
+  "tool_not_exposed",
+  "unknown_tool",
+  // recorder
+  "unclassified",
+  "jsonrpc_error",
+  "duplicate_request_id",
+  "client_cancelled",
+  "no_response"
+];
+function envelope(event, origins) {
+  return {
+    event: { type: "string", required: true, transports: origins, enum: [event] },
+    schema_version: { type: "integer", required: true, transports: origins, min: SCHEMA_VERSION, max: SCHEMA_VERSION },
+    event_id: { type: "string", required: true, transports: origins, pattern: UUID }
+  };
+}
+var MCP_IDENTITY = {
+  transport: { type: "string", required: true, transports: MCP, server_stamped: true, enum: ["remote", "stdio"] },
+  server_version: { type: "string", required: true, transports: MCP, pattern: VERSION },
+  shop_id: { type: "string", required: true, transports: MCP, server_stamped: true, pattern: SHOP_ID },
+  shop_domain: { type: "string", transports: MCP, server_stamped: true, pattern: SHOP_DOMAIN },
+  joy_plan: { type: "string", transports: MCP, server_stamped: true, pattern: PLAN },
+  shopify_plan: { type: "string", transports: MCP, server_stamped: true, pattern: PLAN },
+  auth_mode: { type: "string", required: true, transports: MCP, server_stamped: true, enum: ["oauth", "api_key", "private_bot"] },
+  access_scope: { type: "string", required: true, transports: MCP, server_stamped: true, enum: ["full", "read"] },
+  oauth_client_id: { type: "string", transports: REMOTE, pattern: "^[\\x21-\\x7E]{1,512}$" },
+  connection_id: { type: "string", transports: REMOTE, pattern: UUID },
+  user_id: { type: "string", transports: REMOTE, pattern: "^[A-Za-z0-9_-]{1,64}$" },
+  session_id: { type: "string", transports: STDIO, pattern: UUID },
+  connector_mode: { type: "string", transports: REMOTE, enum: ["soft", "strict"] }
+};
+var TELEMETRY_SCHEMA = {
+  schema_version: SCHEMA_VERSION,
+  ingest_events: ["mcp.tool_call", "mcp.session_start"],
+  forbidden_keys: [
+    "args",
+    "arguments",
+    "params",
+    "input",
+    "result",
+    "content",
+    "text",
+    "prompt",
+    "sql",
+    "query",
+    "message",
+    "severity",
+    "model_message",
+    "error_message",
+    "path",
+    "url",
+    "store_name",
+    "email",
+    "ip",
+    "user_agent",
+    "secret",
+    "secret_key",
+    "token",
+    "authorization"
+  ],
+  events: {
+    "mcp.tool_call": {
+      fields: {
+        ...envelope("mcp.tool_call", MCP),
+        ...MCP_IDENTITY,
+        mcp_client_name: { type: "string", transports: STDIO, pattern: CLIENT_NAME },
+        mcp_client_version: { type: "string", transports: STDIO, pattern: CLIENT_VERSION },
+        call_id: { type: "string", required: true, transports: MCP, pattern: UUID },
+        tool: { type: "string", required: true, transports: MCP, pattern: TOOL },
+        tool_kind: { type: "string", required: true, transports: MCP, enum: ["read", "write", "config_write", "unknown"] },
+        outcome: { type: "string", required: true, transports: MCP, enum: OUTCOMES },
+        error_kind: { type: "string", transports: MCP, enum: ERROR_KINDS },
+        error_code: { type: "string", transports: MCP, pattern: ERROR_CODE },
+        http_status: { type: "integer", transports: MCP, min: 100, max: 599 },
+        duration_ms: { type: "integer", required: true, transports: MCP, min: 0, max: MAX_MS },
+        pre_ms: { type: "integer", transports: REMOTE, min: 0, max: MAX_MS },
+        api_calls: { type: "integer", required: true, transports: MCP, min: 0, max: 1e4 },
+        api_ms: { type: "integer", required: true, transports: MCP, min: 0, max: MAX_MS },
+        result_bytes: { type: "integer", required: true, transports: MCP, min: 0, max: 1e9 }
+      }
+    },
+    "mcp.session_start": {
+      fields: {
+        ...envelope("mcp.session_start", MCP),
+        ...MCP_IDENTITY,
+        mcp_client_name: { type: "string", transports: MCP, pattern: CLIENT_NAME },
+        mcp_client_version: { type: "string", transports: MCP, pattern: CLIENT_VERSION },
+        protocol_version: { type: "string", transports: MCP, pattern: "^\\d{4}-\\d{2}-\\d{2}$" },
+        client_capabilities: { type: "string", transports: MCP, pattern: CAPABILITIES },
+        tools_exposed: { type: "integer", transports: MCP, min: 0, max: 1e4 }
+      }
+    },
+    "api.request": {
+      fields: {
+        ...envelope("api.request", BACKEND),
+        source: { type: "string", required: true, transports: BACKEND, enum: ["mcp", "direct_api", "private_bot", "internal"] },
+        call_id: { type: "string", transports: BACKEND, pattern: UUID },
+        tool: { type: "string", transports: BACKEND, pattern: TOOL },
+        transport: { type: "string", transports: BACKEND, enum: ["remote", "stdio"] },
+        server_version: { type: "string", transports: BACKEND, pattern: VERSION },
+        mcp_client_name: { type: "string", transports: BACKEND, pattern: CLIENT_NAME },
+        session_id: { type: "string", transports: BACKEND, pattern: UUID },
+        shop_verified: { type: "boolean", required: true, transports: BACKEND },
+        shop_id: { type: "string", transports: BACKEND, pattern: SHOP_ID },
+        claimed_shop_id: { type: "string", transports: BACKEND, pattern: SHOP_ID },
+        shop_domain: { type: "string", transports: BACKEND, pattern: SHOP_DOMAIN },
+        joy_plan: { type: "string", transports: BACKEND, pattern: PLAN },
+        shopify_plan: { type: "string", transports: BACKEND, pattern: PLAN },
+        auth_mode: { type: "string", transports: BACKEND, enum: ["api_key", "private_bot"] },
+        access_scope: { type: "string", transports: BACKEND, enum: ["full", "read"] },
+        access_policy: {
+          type: "string",
+          transports: BACKEND,
+          enum: ["plan_quota", "unlimited_plan", "manual_grant", "shop_override", "private_bot", "no_access"]
+        },
+        method: { type: "string", required: true, transports: BACKEND, enum: ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"] },
+        route: { type: "string", transports: BACKEND, pattern: "^/[A-Za-z0-9/:_.()*-]{0,199}$" },
+        http_status: { type: "integer", required: true, transports: BACKEND, min: 100, max: 599 },
+        error_code: { type: "string", transports: BACKEND, pattern: ERROR_CODE },
+        response_error: { type: "boolean", transports: BACKEND },
+        duration_ms: { type: "integer", required: true, transports: BACKEND, min: 0, max: MAX_MS },
+        bq_jobs: { type: "integer", transports: BACKEND, min: 0, max: 1e4 },
+        bq_bytes_processed: { type: "integer", transports: BACKEND, min: 0, max: 1e15 },
+        bq_bytes_billed_est: { type: "integer", transports: BACKEND, min: 0, max: 1e15 }
+      }
+    }
+  }
+};
+
+// ../mcp-core/build/telemetry/validate.js
+var patternCache = /* @__PURE__ */ new Map();
+function regexFor(pattern) {
+  let regex = patternCache.get(pattern);
+  if (!regex) {
+    regex = new RegExp(pattern);
+    patternCache.set(pattern, regex);
+  }
+  return regex;
+}
+function isValidValue(spec, value) {
+  if (spec.type === "boolean")
+    return typeof value === "boolean";
+  if (spec.type === "integer") {
+    if (typeof value !== "number" || !Number.isInteger(value))
+      return false;
+    if (spec.min !== void 0 && value < spec.min)
+      return false;
+    return spec.max === void 0 || value <= spec.max;
+  }
+  if (typeof value !== "string")
+    return false;
+  if (spec.maxLength !== void 0 && value.length > spec.maxLength)
+    return false;
+  if (spec.enum && !spec.enum.includes(value))
+    return false;
+  return !spec.pattern || regexFor(spec.pattern).test(value);
+}
+function own(table, key) {
+  return Object.prototype.hasOwnProperty.call(table, key) ? table[key] : void 0;
+}
+function isApplicable(spec, transport) {
+  return !transport || spec.transports.includes(transport);
+}
+function validateEvent(schema, event, options) {
+  const errors = [];
+  const cleaned = {};
+  if (!event || typeof event !== "object" || Array.isArray(event)) {
+    return { ok: false, event: cleaned, errors: ["not_an_object"] };
+  }
+  const record = event;
+  const spec = typeof record.event === "string" ? own(schema.events, record.event) : void 0;
+  if (!spec)
+    return { ok: false, event: cleaned, errors: ["unknown_event"] };
+  for (const key of schema.forbidden_keys) {
+    if (Object.prototype.hasOwnProperty.call(record, key))
+      errors.push(`forbidden:${key}`);
+  }
+  for (const [key, value] of Object.entries(record)) {
+    const field = own(spec.fields, key);
+    if (!field || !isApplicable(field, options.transport) || value === void 0)
+      continue;
+    if (isValidValue(field, value)) {
+      cleaned[key] = value;
+    } else {
+      errors.push(`invalid:${key}`);
+    }
+  }
+  for (const [key, field] of Object.entries(spec.fields)) {
+    if (!field.required || !isApplicable(field, options.transport))
+      continue;
+    if (options.mode === "client" && field.server_stamped)
+      continue;
+    if (!(key in cleaned) && !errors.includes(`invalid:${key}`))
+      errors.push(`missing:${key}`);
+  }
+  return { ok: errors.length === 0, event: cleaned, errors };
+}
+function sanitizeString(schema, eventName, field, value) {
+  const eventSpec = own(schema.events, eventName);
+  const spec = eventSpec ? own(eventSpec.fields, field) : void 0;
+  if (!spec || spec.type !== "string" || typeof value !== "string")
+    return void 0;
+  return isValidValue(spec, value) ? value : void 0;
+}
+
+// ../mcp-core/build/telemetry/callContext.js
+var als = new AsyncLocalStorage();
+var reported = /* @__PURE__ */ new Set();
+function reportOnce(message) {
+  if (reported.has(message))
+    return;
+  reported.add(message);
+  try {
+    log.error(message);
+  } catch {
+  }
+}
+function telemetrySafe(label, action) {
+  try {
+    return action();
+  } catch {
+    reportOnce(`Telemetry ${label} failed`);
+    return void 0;
+  }
+}
+function currentCall() {
+  return telemetrySafe("context", () => als.getStore());
+}
+function update(action) {
+  telemetrySafe("context", () => {
+    const record = currentCall();
+    if (record && !record.closed)
+      action(record);
+  });
+}
+function markEntered() {
+  update((record) => {
+    record.entered = true;
+  });
+}
+function setOutcome(value, kind) {
+  update((record) => {
+    record.outcome = value;
+    delete record.error_kind;
+    delete record.error_code;
+    delete record.http_status;
+    if (kind)
+      record.error_kind = kind;
+  });
+}
+function markSuccess() {
+  setOutcome("success");
+}
+function markRejected(kind) {
+  setOutcome("rejected", kind);
+}
+function markInternalError() {
+  setOutcome("internal_error", "exception");
+}
+function markToolError(error) {
+  update((record) => {
+    setOutcome("tool_error");
+    const kind = sanitizeString(TELEMETRY_SCHEMA, "mcp.tool_call", "error_kind", error.kind);
+    record.error_kind = kind ?? "unclassified";
+    const code = sanitizeString(TELEMETRY_SCHEMA, "mcp.tool_call", "error_code", error.serverCode);
+    if (code)
+      record.error_code = code;
+    const status = error.status;
+    if (typeof status === "number" && Number.isInteger(status) && status >= 100 && status <= 599) {
+      record.http_status = status;
+    }
+  });
+}
+function apiStart() {
+  update((record) => {
+    record.api_calls++;
+    if (record.api_inflight++ === 0)
+      record.api_busy_since = record.now();
+  });
+}
+function apiEnd() {
+  update((record) => {
+    if (record.api_inflight === 0)
+      return;
+    if (--record.api_inflight !== 0)
+      return;
+    record.api_ms_acc += Math.max(0, record.now() - (record.api_busy_since ?? record.now()));
+    delete record.api_busy_since;
+  });
+}
 
 // ../mcp-core/build/client/joyApi.js
 var JoyApiError = class extends Error {
   kind;
   modelMessage;
   status;
-  constructor(kind, modelMessage, status) {
+  serverCode;
+  constructor(kind, modelMessage, status, serverCode) {
     super(modelMessage);
     this.kind = kind;
     this.modelMessage = modelMessage;
     this.status = status;
+    this.serverCode = serverCode;
     this.name = "JoyApiError";
   }
 };
@@ -110,20 +462,20 @@ function extractServerCode(body) {
   }
   return void 0;
 }
-function classifyError(status, serverMessage, retryAfter, credentialHint) {
+function classifyError(status, serverMessage, retryAfter, credentialHint, serverCode) {
   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);
+    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, serverCode);
   }
   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("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, serverCode);
     }
-    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);
+    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, serverCode);
   }
   if (status === 402) {
-    return new JoyApiError("plan_gate", `The shop's plan does not include REST API or MCP access.${detail} Do NOT retry \u2014 tell the merchant to upgrade their Joy plan; the response's upgrade_url links straight to their subscription page.`, status);
+    return new JoyApiError("plan_gate", `The shop's plan does not include REST API or MCP access.${detail} Do NOT retry \u2014 tell the merchant to upgrade their Joy plan; the response's upgrade_url links straight to their subscription page.`, status, serverCode);
   }
   if (status === 429) {
     const wait = retryAfter ? `${retryAfter} seconds` : "~10 seconds";
@@ -133,22 +485,23 @@ function classifyError(status, serverMessage, retryAfter, credentialHint) {
       // window and a daily quota), so any number written into this string is wrong for most
       // shops. The server states the real one in `detail`, and Retry-After carries the wait.
       `Rate limited by the Joy API.${detail} 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
+      status,
+      serverCode
     );
   }
   if (status === 404) {
     if (!serverMessage) {
-      return new JoyApiError("not_found", "This endpoint does not exist on the Joy backend this shop is connected to. Nothing is wrong with the arguments and there is no identifier to re-check \u2014 the shop is on a deployment older than this tool. Do NOT retry, do NOT try a lookup tool, and do NOT substitute data from another tool. Tell the merchant this feature is unavailable on their current Joy version.", status);
+      return new JoyApiError("not_found", "This endpoint does not exist on the Joy backend this shop is connected to. Nothing is wrong with the arguments and there is no identifier to re-check \u2014 the shop is on a deployment older than this tool. Do NOT retry, do NOT try a lookup tool, and do NOT substitute data from another tool. Tell the merchant this feature is unavailable on their current Joy version.", status, serverCode);
     }
-    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);
+    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, serverCode);
   }
   if (status === 400 || status === 422) {
-    return new JoyApiError("validation", `Invalid request.${detail} Fix the named parameter and call again.`, status);
+    return new JoyApiError("validation", `Invalid request.${detail} Fix the named parameter and call again.`, status, serverCode);
   }
   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("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, serverCode);
   }
-  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);
+  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, serverCode);
 }
 function errorFromOkBody(body) {
   if (!body || typeof body !== "object")
@@ -160,12 +513,28 @@ function errorFromOkBody(body) {
   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.");
+    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.", void 0, telemetryServerCode(record));
   }
   if (code === "VALIDATION_ERROR") {
-    return new JoyApiError("validation", `Invalid request${message ? `: "${message}"` : ""}. Fix the named parameter and call again.`);
+    return new JoyApiError("validation", `Invalid request${message ? `: "${message}"` : ""}. Fix the named parameter and call again.`, void 0, telemetryServerCode(record));
   }
-  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.`);
+  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.`, void 0, telemetryServerCode(record));
+}
+function telemetryServerCode(body) {
+  const record = body && typeof body === "object" ? body : {};
+  return sanitizeString(TELEMETRY_SCHEMA, "mcp.tool_call", "error_code", extractServerCode(body)) ?? sanitizeString(TELEMETRY_SCHEMA, "mcp.tool_call", "error_code", record.error);
+}
+function authHeaders(config) {
+  const headers = {
+    "Content-Type": "application/json",
+    "X-Joy-Loyalty-App-Key": config.appKey
+  };
+  if (config.privateBotKey) {
+    headers["X-Joy-Private-Bot-Key"] = config.privateBotKey;
+  } else if (config.secretKey) {
+    headers["X-Joy-Loyalty-Secret-Key"] = config.secretKey;
+  }
+  return headers;
 }
 var JoyApi = class {
   config;
@@ -176,16 +545,7 @@ var JoyApi = class {
     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;
+    return authHeaders(this.config);
   }
   async request(path, options = {}) {
     const { method = "GET", query, body, timeoutMs = DEFAULT_TIMEOUT_MS, headers } = options;
@@ -194,49 +554,57 @@ var JoyApi = class {
       if (value !== void 0)
         url.searchParams.set(key, String(value));
     }
-    let response;
+    const record = currentCall();
+    if (record)
+      apiStart();
     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. The first call after an idle period pays a Cloud Functions cold start, so a lone timeout is usually transient rather than an outage. Safe to retry ONCE; if it times out again, report the outage instead of retrying further.`);
+      let response;
+      try {
+        response = await fetch(url, {
+          method,
+          headers: { ...headers, ...record?.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. The first call after an idle period pays a Cloud Functions cold start, so a lone timeout is usually transient rather than an outage. 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.`);
       }
-      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());
+      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(), telemetryServerCode(parsed));
+      }
+      const okBodyError = errorFromOkBody(parsed);
+      if (okBodyError)
+        throw okBodyError;
+      return parsed ?? {};
+    } finally {
+      if (record)
+        apiEnd();
     }
-    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);
+    const envelope2 = await this.request(path, options);
     return {
-      data: envelope.data,
-      hasNext: envelope.meta?.pagination?.hasNext === true
+      data: envelope2.data,
+      hasNext: envelope2.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;
+    const envelope2 = await this.request(path, options);
+    return envelope2.data;
   }
 };
 
@@ -266,16 +634,6 @@ import { z as z2 } from "zod";
 // ../mcp-core/build/toolkit.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/store.js
 function displayName(store) {
   return store.name.replace(/[\u0000-\u001f\u007f[\]]+/g, " ").trim() || store.myshopifyDomain;
@@ -330,12 +688,15 @@ var STORE_ARG_DESCRIPTION = `The store the USER asked to change \u2014 its name
 async function runHandler(name, run, store) {
   try {
     const text = await run();
+    markSuccess();
     return { content: [{ type: "text", text: store ? stampResult(text, store) : text }] };
   } catch (error) {
     if (error instanceof JoyApiError) {
+      markToolError(error);
       const text2 = store ? stampResult(error.modelMessage, store) : error.modelMessage;
       return { isError: true, content: [{ type: "text", text: text2 }] };
     }
+    markInternalError();
     const message = error instanceof Error ? error.message : String(error);
     log.error(`${name} failed unexpectedly: ${message}`);
     const 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.`;
@@ -345,8 +706,17 @@ async function runHandler(name, run, store) {
     };
   }
 }
+function withTelemetry(ctx, name, callback) {
+  if (!ctx.telemetry)
+    return callback;
+  telemetrySafe("expose", () => ctx.telemetry?.expose(name));
+  return ((...args) => {
+    markEntered();
+    return callback(...args);
+  });
+}
 function registerReadTool(server, ctx, spec) {
-  const callback = (async (args) => runHandler(spec.name, () => spec.handler(args ?? {}), ctx.store));
+  const callback = withTelemetry(ctx, spec.name, (async (args) => runHandler(spec.name, () => spec.handler(args ?? {}), ctx.store)));
   server.registerTool(spec.name, {
     title: spec.title,
     description: ctx.store ? storeDescriptionPrefix(ctx.store) + spec.description : spec.description,
@@ -375,13 +745,16 @@ function stripStoreArg(args) {
 }
 function registerConfigWriteTool(server, ctx, spec) {
   const strictStore = ctx.store && ctx.requireStoreArg ? ctx.store : void 0;
-  const callback = (async (args) => {
+  const callback = withTelemetry(ctx, spec.name, (async (args) => {
     if (strictStore) {
       const mismatch = checkStoreMismatch(spec.name, args, strictStore);
-      if (mismatch)
+      if (mismatch) {
+        markRejected("store_mismatch");
         return mismatch;
+      }
     }
     if (!ctx.config.configWritesEnabled) {
+      markRejected("config_writes_disabled");
       const text = `${spec.name} is disabled: this server cannot change shop configuration. The merchant must set BOTH JOY_MCP_ENABLE_WRITES="true" and JOY_MCP_ENABLE_CONFIG_WRITES="true" (quoted strings, with their secret key) in the MCP config. Do not retry until they have \u2014 and do not fall back to a member-level write tool to approximate a configuration change.`;
       return {
         isError: true,
@@ -390,7 +763,7 @@ function registerConfigWriteTool(server, ctx, spec) {
     }
     const handlerArgs = strictStore ? stripStoreArg(args) : args ?? {};
     return runHandler(spec.name, () => spec.handler(handlerArgs), ctx.store);
-  });
+  }));
   const registration = {
     title: spec.title,
     description: ctx.store ? storeDescriptionPrefix(ctx.store) + spec.description : spec.description,
@@ -410,13 +783,16 @@ function registerConfigWriteTool(server, ctx, spec) {
 }
 function registerWriteTool(server, ctx, spec) {
   const strictStore = ctx.store && ctx.requireStoreArg ? ctx.store : void 0;
-  const callback = (async (args) => {
+  const callback = withTelemetry(ctx, spec.name, (async (args) => {
     if (strictStore) {
       const mismatch = checkStoreMismatch(spec.name, args, strictStore);
-      if (mismatch)
+      if (mismatch) {
+        markRejected("store_mismatch");
         return mismatch;
+      }
     }
     if (!ctx.config.writesEnabled) {
+      markRejected("writes_disabled");
       const 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 {
         isError: true,
@@ -425,7 +801,7 @@ function registerWriteTool(server, ctx, spec) {
     }
     const handlerArgs = strictStore ? stripStoreArg(args) : args ?? {};
     return runHandler(spec.name, () => spec.handler(handlerArgs), ctx.store);
-  });
+  }));
   server.registerTool(spec.name, {
     title: spec.title,
     description: ctx.store ? storeDescriptionPrefix(ctx.store) + spec.description : spec.description,
@@ -503,6 +879,9 @@ var MEMBER_DETAIL_KEYS = [
   "pointsRemain",
   "tierPoint",
   "pendingPoint",
+  // REST v2 detail fields, plus computed pointExpiration on the single-customer GETs.
+  "pointExpiration",
+  "pointExpirationUnavailable",
   "totalSpent",
   "totalEarnedPoints",
   "tierId",
@@ -545,6 +924,8 @@ var REWARD_KEYS = [
   "orderReqAmount",
   "expiredAt",
   "usedAt",
+  "isRevokedCode",
+  "revokedAt",
   "createdAt"
 ];
 var memberIdentifierSchema = {
@@ -592,13 +973,24 @@ function registerMemberTools(server, ctx) {
   registerReadTool(server, ctx, {
     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.',
+    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. "pointExpiration" is the NEXT scheduled expiry: nextExpiryAt (ISO date) and nextExpiryPoints (how many points expire then). It is omitted when the shop's points never expire, the balance is 0, or no expiry is scheduled. If "pointExpirationUnavailable" is true the expiry could not be loaded \u2014 do not claim points never expire.`,
     inputSchema: memberIdentifierSchema,
     handler: async (args) => {
-      const member = await resolveMember(ctx.api, args);
+      let member = await resolveMember(ctx.api, args);
+      if (!args.shopify_customer_id && member.id && !Object.hasOwn(member, "pointExpiration")) {
+        try {
+          const { data } = await ctx.api.getData(`/customers/${encodeURIComponent(String(member.id))}`);
+          if (data && typeof data === "object")
+            member = data;
+        } catch {
+          member = { ...member, pointExpirationUnavailable: true };
+        }
+      }
       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);
+      const pointExpiration = member.pointExpiration && typeof member.pointExpiration === "object" ? member.pointExpiration : void 0;
+      const expiry = pointExpiration && typeof pointExpiration.nextExpiryAt === "string" && typeof pointExpiration.nextExpiryPoints === "number" ? `, ${formatPoints(pointExpiration.nextExpiryPoints)} expire on ${pointExpiration.nextExpiryAt.slice(0, 10)}` : "";
+      return summaryWithJson(`Member ${memberDisplayName(member)}: ${formatPoints(member.point)} points${tier}${expiry}.`, shaped);
     }
   });
   registerReadTool(server, ctx, {
@@ -647,9 +1039,9 @@ function registerMemberTools(server, ctx) {
       const direction = args.direction ?? "desc";
       const withTotal = args.include_total_count === true;
       const sort = MEMBER_SORTS[sortBy];
-      let envelope;
+      let envelope2;
       try {
-        envelope = await ctx.api.request("/customers", {
+        envelope2 = await ctx.api.request("/customers", {
           query: {
             limit,
             after: args.after,
@@ -662,10 +1054,10 @@ function registerMemberTools(server, ctx) {
         reclassifyCursorError(error, args.after);
       }
       const result = {
-        data: envelope.data,
-        hasNext: envelope.meta?.pagination?.hasNext === true
+        data: envelope2.data,
+        hasNext: envelope2.meta?.pagination?.hasNext === true
       };
-      const totalMembers = withTotal ? envelope.meta?.pagination?.total : void 0;
+      const totalMembers = withTotal ? envelope2.meta?.pagination?.total : void 0;
       const members = Array.isArray(result.data) ? result.data : [];
       if (members.length === 0) {
         if (args.after)
@@ -730,7 +1122,7 @@ function registerMemberTools(server, ctx) {
   registerReadTool(server, ctx, {
     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?".`,
+    description: `Coupons and rewards ONE member has already redeemed \u2014 code, discount program, status (active/used/expired/revoked), expiry. A revoked coupon has discountStatus "revoked" plus isRevokedCode/revokedAt: its points were refunded and the code no longer works. 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: z2.number().int().min(1).max(50).optional().describe("Rewards per page (default 10, max 50)."),
@@ -1514,13 +1906,13 @@ var reportDateRangeSchema = {
 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 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, error.serverCode);
   }
   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 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, error.serverCode);
   }
   return error;
 }
@@ -1618,7 +2010,7 @@ ${summary}`);
         });
       } 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 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, error.serverCode);
         }
         throw error;
       }
@@ -1678,19 +2070,19 @@ function resolveIdempotencyKey(provided) {
 }
 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 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, error.serverCode);
   }
   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 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, error.serverCode);
   }
   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 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, error.serverCode);
   }
   throw error;
 }
@@ -2268,19 +2660,19 @@ import { z as z13 } from "zod";
 function summarizeDesign(data) {
   const sections = data.design?.sections ?? [];
   const on = sections.filter((section) => section.enabled !== false).map((section) => section.id);
-  const legacyWarning = data.renderPath === "legacy-blocks" ? `\u26A0 The storefront loyalty page renders through legacy blocks, so Loyalty Page V2 design changes will not appear there. The merchant must open ${data.v2BlockAddUrl || "the Loyalty Page V2 block link from joy_check_theme_setup"}, add the Loyalty Page V2 block, and save the theme. ` : "";
-  let live = "The shop still serves the older Loyalty Page V1, so changes here are not visible to customers yet.";
+  const legacyWarning = data.renderPath === "legacy-blocks" ? `\u26A0 The storefront loyalty page renders through legacy blocks, so new loyalty page design changes will not appear there. The merchant must open ${data.v2BlockAddUrl || "the new loyalty page block link from joy_check_theme_setup"}, add the Joy: New Loyalty Page block, and save the theme. ` : "";
+  let live = "The shop still serves the classic loyalty page, so changes here are not visible to customers yet.";
   if (data.pageVersionActive && (data.renderPath === "v2-block" || data.renderPath === void 0)) {
     live = "This page IS the shop\u2019s live loyalty page \u2014 changes are visible to customers.";
   }
   if (data.pageVersionActive && data.renderPath === "legacy-blocks") {
-    live = "Loyalty Page V2 is active for this shop.";
+    live = "The new loyalty page is active for this shop.";
   }
   if (data.pageVersionActive && data.renderPath === "none") {
-    live = "Loyalty Page V2 is active for this shop, but no loyalty page block was detected in the live theme, so changes are not visible to customers.";
+    live = "The new loyalty page is active for this shop, but no loyalty page block was detected in the live theme, so changes are not visible to customers.";
   }
   const css = data.canEditCustomCss ? "" : " Custom CSS is not available on this shop\u2019s plan.";
-  return `${legacyWarning}Loyalty Page V2 design. Sections on: ${on.join(", ") || "none"}. ${live}${css}`;
+  return `${legacyWarning}New loyalty page design. Sections on: ${on.join(", ") || "none"}. ${live}${css}`;
 }
 function summarizeAppliedChanges(applied2, published, warnings2 = []) {
   const headline = applied2.slice(0, 5).map((change) => `${change.field}: ${String(change.from ?? "\u2014")} \u2192 ${String(change.to)}`).join("; ");
@@ -2293,7 +2685,7 @@ function registerLoyaltyPageTools(server, ctx) {
   registerReadTool(server, ctx, {
     name: "joy_get_loyalty_page_design",
     title: "Get loyalty page design",
-    description: "Read the shop's Loyalty Page V2 appearance \u2014 page theme (colours, fonts, radii, widths), which sections are switched on, and each section's layout and card styling. It also audits whether the live theme renders this design through the V2 block, legacy blocks, or no loyalty page block; when legacy blocks are present, the result leads with the server-provided theme-editor link the merchant must use to add and save the V2 block. This read-only tool cannot add or enable a theme block itself. Also returns `writableFields`: the exact field names joy_update_loyalty_page_design accepts, per section. CALL THIS BEFORE any design change \u2014 the field vocabulary is large and specific, and guessing a name costs a failed call. This is appearance only: page text (headings, FAQ questions, program descriptions) is NOT here and cannot be changed through these tools.",
+    description: "Read the shop's new loyalty page appearance \u2014 page theme (colours, fonts, radii, widths), which sections are switched on, and each section's layout and card styling. It also audits whether the live theme renders this design through the new loyalty page block, legacy blocks, or no loyalty page block; when legacy blocks are present, the result leads with the server-provided theme-editor link the merchant must use to add and save the new loyalty page block. This read-only tool cannot add or enable a theme block itself. Also returns `writableFields`: the exact field names joy_update_loyalty_page_design accepts, per section. CALL THIS BEFORE any design change \u2014 the field vocabulary is large and specific, and guessing a name costs a failed call. This is appearance only: page text (headings, FAQ questions, program descriptions) is NOT here and cannot be changed through these tools.",
     inputSchema: {},
     handler: async () => {
       const { data } = await ctx.api.getData("/loyalty-page/design");
@@ -2310,7 +2702,7 @@ function registerLoyaltyPageWriteTools(server, ctx) {
     // identical call is not a no-op for what revert would restore.
     destructiveHint: false,
     idempotentHint: false,
-    description: "Change the appearance of the shop's Loyalty Page V2, including its media and program or tier artwork. Send ONLY the fields you are changing \u2014 anything you omit keeps its current value. WARNING: the `icons` branch has no draft \u2014 program and tier artwork is live data, so those changes reach shoppers immediately even when publish is false, and they also appear anywhere else that reads the program or tier. Tier artwork is dual-written to `imageBlock` for the loyalty page and `icon` for the tier-achieved email, membership card Widget V4, and account block: changing a tier icon changes those email and widget surfaces too, not just this page. For image artwork, first call joy_upload_image, then pass its returned URL to `hero.backgroundImage`, `hero.mobileBackgroundImage`, `inlineBanner.backgroundImage`, `inlineBanner.mobileBackgroundImage`, `earn.bannerImage`, `referral.image`, or `icons`; the other media fields are `hero.backgroundVideo` and `hero.mobileBackgroundVideo`. Image URLs must use http: or https: and contain no username or password; video URLs must use https: and end in .mp4. For a storefront-based starting point, send `applyScan` inside `design` in this tool \u2014 there is no separate apply-scan tool. Call joy_get_loyalty_page_design first and use the field names from its `writableFields`; a name outside that list is refused with the offending path rather than silently ignored. Saves to the DRAFT: the merchant sees it in their loyalty page editor immediately, and customers see it when they publish. Iterate freely here \u2014 refining a design costs nothing. Only pass publish=true when the merchant has asked for the change to go live, because publishing writes a Shopify metafield and re-syncs the FAQ projection every time. Undo with joy_revert_loyalty_page_design. Appearance only \u2014 this cannot change any text on the page.",
+    description: "Change the appearance of the shop's new loyalty page, including its media and program or tier artwork. Send ONLY the fields you are changing \u2014 anything you omit keeps its current value. WARNING: the `icons` branch has no draft \u2014 program and tier artwork is live data, so those changes reach shoppers immediately even when publish is false, and they also appear anywhere else that reads the program or tier. Tier artwork is dual-written to `imageBlock` for the loyalty page and `icon` for the tier-achieved email, membership card Widget V4, and account block: changing a tier icon changes those email and widget surfaces too, not just this page. For image artwork, first call joy_upload_image, then pass its returned URL to `hero.backgroundImage`, `hero.mobileBackgroundImage`, `inlineBanner.backgroundImage`, `inlineBanner.mobileBackgroundImage`, `earn.bannerImage`, `referral.image`, or `icons`; the other media fields are `hero.backgroundVideo` and `hero.mobileBackgroundVideo`. Image URLs must use http: or https: and contain no username or password; video URLs must use https: and end in .mp4. For a storefront-based starting point, send `applyScan` inside `design` in this tool \u2014 there is no separate apply-scan tool. Call joy_get_loyalty_page_design first and use the field names from its `writableFields`; a name outside that list is refused with the offending path rather than silently ignored. Saves to the DRAFT: the merchant sees it in their loyalty page editor immediately, and customers see it when they publish. Iterate freely here \u2014 refining a design costs nothing. Only pass publish=true when the merchant has asked for the change to go live, because publishing writes a Shopify metafield and re-syncs the FAQ projection every time. Undo with joy_revert_loyalty_page_design. Appearance only \u2014 this cannot change any text on the page.",
     inputSchema: {
       design: z13.record(z13.unknown()).describe('The fields to change, shaped like the `design` object from joy_get_loyalty_page_design. Branches: `theme` (page-wide tokens), `sections` (array of {id, enabled?, settings:{theme}}), `content` (per-section layout/style, keyed by section id), `advanced` ({customCss}), `icons` ({earning?:{...}, spending?:{...}, tiers?:{...}|[...]}, valued with an image URL or a built-in icon name), and `applyScan` ({url?: string, storefrontPassword?: string, colors?: boolean, images?: boolean}). Address earning/spending artwork by program id OR event; address tier artwork by tier id OR tier name (`name`/`title`), or pass an array in tier order. A tier artwork write updates both `imageBlock` (loyalty page) and `icon` (tier-achieved email, membership card Widget V4, and account block), so it changes email and widget surfaces too. Read current program artwork from joy_list_earning_rules / joy_list_redemption_rules. For `applyScan`, url defaults to this shop\'s storefront, storefrontPassword is only for a gated store, colors defaults to true, and images defaults to false so a scan does not unexpectedly replace artwork. If the scan returns 409 PASSWORD_REQUIRED, ask the merchant for the storefront password and pass it as `storefrontPassword`; never guess it. If it fails with 503, do not invent colours, fonts, or button styling; ask the merchant to retry later or configure the draft manually. Scan output is design input, not visual evidence of how the page looks after the change. NOTE on precedence: a value under `sections[].settings.theme` BEATS the same key in `theme`, so recolouring a page whose sections carry overrides means patching both. Example: {"theme":{"primary":"#0F4C3A"},"content":{"earn":{"columns":2}},"icons":{"earning":{"birthday":"https://cdn.../cake.png"}}}'),
       publish: z13.boolean().optional().describe("Default false \u2014 the change lands on the draft, which the merchant sees in the loyalty page editor and nobody else. Pass true only when they asked for it to go live; each publish costs a Shopify metafield write, so do not send it on every tweak.")
@@ -2369,13 +2761,13 @@ function registerLoyaltyPageTextTools(server, ctx) {
   registerReadTool(server, ctx, {
     name: "joy_get_loyalty_page_text",
     title: "Get loyalty page text",
-    description: "Loyalty Page V2 text has no draft: text edits are LIVE on the storefront immediately. Read the current text for one active locale, the placeholders each value must preserve, and the stable ids/keys for steps and tier benefits. CALL THIS BEFORE joy_update_loyalty_page_text; never guess keys or item positions. Editing the primary language automatically retranslates only those changed keys into every other active locale. `points.singular` and `points.plural` are shown for context but are read-only through this tool surface.",
+    description: "New loyalty page text has no draft: text edits are LIVE on the storefront immediately. Read the current text for one active locale, the placeholders each value must preserve, and the stable ids/keys for steps and tier benefits. CALL THIS BEFORE joy_update_loyalty_page_text; never guess keys or item positions. Editing the primary language automatically retranslates only those changed keys into every other active locale. `points.singular` and `points.plural` are shown for context but are read-only through this tool surface.",
     inputSchema: { locale: localeSchema },
     handler: async (args) => {
       const { data } = await ctx.api.getData("/loyalty-page/text", {
         query: { locale: args.locale }
       });
-      return summaryWithJson(`${Object.keys(data.values).length} live Loyalty Page V2 text values for ${data.locale}. Primary language: ${data.primaryLanguage}; active locales: ${data.activeLocales.join(", ")}.`, data);
+      return summaryWithJson(`${Object.keys(data.values).length} live new loyalty page text values for ${data.locale}. Primary language: ${data.primaryLanguage}; active locales: ${data.activeLocales.join(", ")}.`, data);
     }
   });
 }
@@ -2385,7 +2777,7 @@ function registerLoyaltyPageTextWriteTools(server, ctx) {
     title: "Update loyalty page text",
     destructiveHint: true,
     idempotentHint: false,
-    description: "Loyalty Page V2 text has no draft: every accepted change is LIVE on the storefront immediately. Update only exact keys returned by joy_get_loyalty_page_text; unknown or duplicate keys are skipped. Preserve every returned placeholder unless the merchant explicitly authored the replacement, in which case pass manual: true. Editing the primary language automatically retranslates the changed keys into every other active locale in the same operation; editing a secondary locale changes only that locale. This can replace merchant-authored translations for those same keys. Undo the latest text or design update with joy_revert_loyalty_page_design.",
+    description: "New loyalty page text has no draft: every accepted change is LIVE on the storefront immediately. Update only exact keys returned by joy_get_loyalty_page_text; unknown or duplicate keys are skipped. Preserve every returned placeholder unless the merchant explicitly authored the replacement, in which case pass manual: true. Editing the primary language automatically retranslates the changed keys into every other active locale in the same operation; editing a secondary locale changes only that locale. This can replace merchant-authored translations for those same keys. Undo the latest text or design update with joy_revert_loyalty_page_design.",
     inputSchema: {
       locale: localeSchema,
       changes: z14.array(z14.object({
@@ -2402,13 +2794,151 @@ function registerLoyaltyPageTextWriteTools(server, ctx) {
       });
       const propagation = result.translatedLocales.length ? ` Retranslated in ${result.translatedLocales.join(", ")}.` : "";
       const skipped = result.skipped.length ? ` ${result.skipped.length} change(s) skipped.` : "";
-      return summaryWithJson(`\u26A0 Loyalty Page V2 text has no draft \u2014 ${result.applied.length} text change(s) are LIVE now.${propagation}${skipped} Undo with joy_revert_loyalty_page_design.`, result);
+      return summaryWithJson(`\u26A0 New loyalty page text has no draft \u2014 ${result.applied.length} text change(s) are LIVE now.${propagation}${skipped} Undo with joy_revert_loyalty_page_design.`, result);
     }
   });
 }
 
-// ../mcp-core/build/tools/programsWrite.js
+// ../mcp-core/build/tools/loyaltyHub.js
 import { z as z15 } from "zod";
+function summarizeHubDesign(data) {
+  const sections = data.design?.sections ?? [];
+  const on = sections.filter((s) => s.enabled !== false).map((s) => s.id);
+  return `Loyalty Hub design. Sections on: ${on.join(", ") || "none"}. The Hub is LIVE \u2014 every logged-in customer sees changes immediately. Programs, tier icons and program icons are shared with the Loyalty Page, widget and emails.`;
+}
+function summarizeHubAppliedChanges(applied2, warnings2 = []) {
+  const headline = applied2.slice(0, 5).join("; ");
+  const more = applied2.length > 5 ? ` (+${applied2.length - 5} more)` : "";
+  const caveat = warnings2.length ? `\u26A0 ${warnings2.join(" \u26A0 ")} ` : "";
+  return `${caveat}${applied2.length} design field${applied2.length === 1 ? "" : "s"} changed \u2014 ${headline}${more}. LIVE now for every logged-in customer. Undo with joy_revert_loyalty_hub_design.`;
+}
+function registerLoyaltyHubTools(server, ctx) {
+  registerReadTool(server, ctx, {
+    name: "joy_get_loyalty_hub_design",
+    title: "Get Loyalty Hub design",
+    description: "Read the shop's Loyalty Hub appearance \u2014 which sections are switched on and their layout and styling, plus the shared program and tier icons. Also returns `writableFields`: the exact field names joy_update_loyalty_hub_design accepts, with the allowed values of each. redeemButtonVariant (secondary by default, or primary) changes only voucher-card Redeem buttons. Section card border overrides are rewardsCardBorderStyle (My coupons), earnCardBorderStyle (Ways to earn), redeemCardBorderStyle (Redeem), and vipCardBorderStyle (VIP); each accepts inherit (default), solid, or dashed. Inherit follows the global border style. IMPORTANT: the Loyalty Hub has NO draft \u2014 every change is LIVE for every logged-in customer immediately. Programs, program icons and tier icons are SHARED with the Loyalty Page, widget and emails: changing them here also changes those other surfaces. CALL THIS BEFORE any design change \u2014 the field vocabulary is large and specific, and guessing a name costs a failed call. This tool reads appearance only: Hub text (headings, descriptions) is read by joy_get_loyalty_hub_text.",
+    inputSchema: {},
+    handler: async () => {
+      const { data } = await ctx.api.getData("/loyalty-hub/design");
+      return summaryWithJson(summarizeHubDesign(data), data);
+    }
+  });
+}
+function registerLoyaltyHubWriteTools(server, ctx) {
+  registerWriteTool(server, ctx, {
+    name: "joy_update_loyalty_hub_design",
+    title: "Update Loyalty Hub design",
+    destructiveHint: false,
+    idempotentHint: true,
+    description: "Change the Loyalty Hub's appearance. WARNING: the Hub has NO draft \u2014 every accepted change is LIVE for every logged-in customer immediately. Send ONLY the fields you are changing; anything omitted keeps its current value. redeemButtonVariant (secondary by default, or primary) changes only voucher-card Redeem buttons. Section card border overrides: rewardsCardBorderStyle (My coupons), earnCardBorderStyle (Ways to earn), redeemCardBorderStyle (Redeem), vipCardBorderStyle (VIP). Each accepts inherit (default), solid, or dashed and changes only card border line style. Inherit follows the global border style; border width, radius, background, density, inner separators and current-tier highlights remain unchanged. Programs, tier icons and program icons are SHARED with the Loyalty Page, widget and emails \u2014 changing them here also changes those other surfaces. If the merchant has the Hub editor open, it will ask them to reload. Call joy_get_loyalty_hub_design first and use the field names from its `writableFields`; a name outside that list is refused with the offending path rather than silently ignored. Undo with joy_revert_loyalty_hub_design. Appearance only \u2014 this cannot change any text on the Hub.",
+    inputSchema: {
+      design: z15.record(z15.unknown()).describe('The fields to change. Flat Hub keys named in `writableFields` from joy_get_loyalty_hub_design (section switches, layouts, visible counts, hero image, Redeem-only redeemButtonVariant: secondary|primary, section border overrides rewardsCardBorderStyle/earnCardBorderStyle/redeemCardBorderStyle/vipCardBorderStyle: inherit|solid|dashed (default inherit follows global), and the Design tab: cardBorderWidth, cardBorderStyle, cardRadius, cardBackground, density, earnIconColor as #RRGGBB), plus optional `programs` ({earning?:[{id, showLoyaltyPage}], spending?:[...]}), `programOrder` ({earning?:[program ids], spending?:[...]}, position sets the order) and `icons` ({earning?:{...}, spending?:{...}, tiers?:{...}|[...]}, valued with an image URL or a built-in icon name; address earning/spending artwork by program id OR event, tiers by tier id, tier name or array position). Read current program artwork from joy_list_earning_rules / joy_list_redemption_rules. Example: {"cardRadius":"max","earnIconColor":"#0F4C3A","icons":{"earning":{"birthday":"https://cdn.../cake.png"}}}')
+    },
+    handler: async (args) => {
+      const result = await ctx.api.mutateData("/loyalty-hub/design", {
+        method: "PATCH",
+        timeoutMs: 2e4,
+        body: { design: args.design }
+      });
+      const applied2 = result?.applied ?? [];
+      if (!applied2.length) {
+        return "No change \u2014 every field you sent already had that value.";
+      }
+      const warnings2 = result?.warnings ?? [];
+      return summaryWithJson(summarizeHubAppliedChanges(applied2, warnings2), {
+        applied: applied2,
+        ...warnings2.length ? { warnings: warnings2 } : {}
+      });
+    }
+  });
+  registerWriteTool(server, ctx, {
+    name: "joy_revert_loyalty_hub_design",
+    title: "Revert the last Loyalty Hub design change",
+    destructiveHint: true,
+    idempotentHint: true,
+    description: "Undo the last design change made through joy_update_loyalty_hub_design, restoring the Hub exactly as it was before that call \u2014 LIVE immediately for every logged-in customer. ONE step only \u2014 a second call restores the same snapshot again rather than going further back. Program and tier icons go back LIVE immediately because they are shared data with no draft. WARNING: it restores a whole saved design, so any edit the merchant made in the Hub editor AFTER that update is discarded too \u2014 if they may have been editing, ask before calling this. Use it promptly; the next update overwrites the snapshot.",
+    inputSchema: {},
+    handler: async () => {
+      const result = await ctx.api.mutateData("/loyalty-hub/design/revert", {
+        method: "POST",
+        timeoutMs: 2e4,
+        body: {}
+      });
+      const programIcons = result?.programIconsRestored ?? 0;
+      const tierIcons = result?.tierIconsRestored ?? 0;
+      const icons = programIcons || tierIcons ? ` ${[
+        programIcons ? `${programIcons} program icon${programIcons === 1 ? "" : "s"}` : "",
+        tierIcons ? `${tierIcons} tier icon${tierIcons === 1 ? "" : "s"}` : ""
+      ].filter(Boolean).join(" and ")} restored \u2014 LIVE now (shared data, no draft).` : "";
+      return summaryWithJson(`Reverted to the Loyalty Hub design from before the last update. LIVE immediately for every logged-in customer.${icons}`, { design: result?.design, programIconsRestored: programIcons, tierIconsRestored: tierIcons });
+    }
+  });
+}
+
+// ../mcp-core/build/tools/loyaltyHubText.js
+import { z as z16 } from "zod";
+var localeSchema2 = z16.string().min(2).optional().describe("Active locale code. Omit to use the shop's primary language.");
+function registerLoyaltyHubTextTools(server, ctx) {
+  registerReadTool(server, ctx, {
+    name: "joy_get_loyalty_hub_text",
+    title: "Get Loyalty Hub text",
+    description: "Loyalty Hub text has no draft: text edits are LIVE on the Hub immediately. Read the current text for one active locale, the placeholders each value must preserve, and the stable ids/keys for steps and tier benefits. CALL THIS BEFORE joy_update_loyalty_hub_text; never guess keys or item positions. Editing the primary language automatically retranslates only those changed keys into every other active locale. `points.singular` and `points.plural` are shown for context but are read-only through this tool surface.",
+    inputSchema: { locale: localeSchema2 },
+    handler: async (args) => {
+      const { data } = await ctx.api.getData("/loyalty-hub/text", {
+        query: { locale: args.locale }
+      });
+      return summaryWithJson(`${Object.keys(data.values).length} live Loyalty Hub text values for ${data.locale}. Primary language: ${data.primaryLanguage}; active locales: ${data.activeLocales.join(", ")}.`, data);
+    }
+  });
+}
+function registerLoyaltyHubTextWriteTools(server, ctx) {
+  registerWriteTool(server, ctx, {
+    name: "joy_update_loyalty_hub_text",
+    title: "Update Loyalty Hub text",
+    destructiveHint: true,
+    idempotentHint: false,
+    description: "Loyalty Hub text has no draft: every accepted change is LIVE on the Hub immediately. Update only exact keys returned by joy_get_loyalty_hub_text; unknown or duplicate keys are skipped. Preserve every returned placeholder unless the merchant explicitly authored the replacement, in which case pass manual: true. Editing the primary language automatically retranslates the changed keys into every other active locale in the same operation; editing a secondary locale changes only that locale. This can replace merchant-authored translations for those same keys. Undo the latest Hub text change with joy_revert_loyalty_hub_text.",
+    inputSchema: {
+      locale: localeSchema2,
+      changes: z16.array(z16.object({
+        key: z16.string().min(1),
+        value: z16.string(),
+        manual: z16.boolean().optional().describe("Set true only when the merchant authored this exact replacement.")
+      })).min(1).describe("Exact key/value edits from joy_get_loyalty_hub_text.")
+    },
+    handler: async (args) => {
+      const result = await ctx.api.mutateData("/loyalty-hub/text", {
+        method: "PATCH",
+        timeoutMs: 12e4,
+        body: { changes: args.changes, ...args.locale ? { locale: args.locale } : {} }
+      });
+      const propagation = result.translatedLocales.length ? ` Retranslated in ${result.translatedLocales.join(", ")}.` : "";
+      const skipped = result.skipped.length ? ` ${result.skipped.length} change(s) skipped.` : "";
+      return summaryWithJson(`\u26A0 Loyalty Hub text has no draft \u2014 ${result.applied.length} text change(s) are LIVE now.${propagation}${skipped} Undo with joy_revert_loyalty_hub_text.`, result);
+    }
+  });
+  registerWriteTool(server, ctx, {
+    name: "joy_revert_loyalty_hub_text",
+    title: "Revert the last Loyalty Hub text change",
+    destructiveHint: true,
+    idempotentHint: true,
+    description: "Undo the last text change made through joy_update_loyalty_hub_text, restoring the Loyalty Hub text exactly as it was before that call \u2014 LIVE immediately. ONE step only \u2014 a second call restores the same snapshot again rather than going further back. This undoes Hub text only; use joy_revert_loyalty_hub_design to undo Hub design changes.",
+    inputSchema: {},
+    handler: async () => {
+      const result = await ctx.api.mutateData("/loyalty-hub/text/revert", {
+        method: "POST",
+        timeoutMs: 2e4,
+        body: {}
+      });
+      const count = result?.textKeysRestored ?? 0;
+      return summaryWithJson(`Reverted Loyalty Hub text \u2014 ${count} value${count === 1 ? "" : "s"} restored. LIVE immediately.`, result);
+    }
+  });
+}
+
+// ../mcp-core/build/tools/programsWrite.js
+import { z as z17 } from "zod";
 var PROGRAM_TYPE_BY_KIND = {
   earning: "earning",
   redemption: "spending"
@@ -2436,7 +2966,7 @@ var REVIEW_APPS = [
   "okendoApp",
   "ReviewsIoApp",
   "growaveApp",
-  "typdalApp"
+  "segunoReviewApp"
 ];
 var REVIEW_FLOW_APPS = /* @__PURE__ */ new Set([
   "stampedApp",
@@ -2444,6 +2974,7 @@ var REVIEW_FLOW_APPS = /* @__PURE__ */ new Set([
   "okendoApp",
   "ReviewsIoApp",
   "growaveApp",
+  "segunoReviewApp",
   "typdalApp"
 ]);
 var REVIEW_PHOTO_VIDEO_APPS = /* @__PURE__ */ new Set(["reviewRocketApp", "looxApp"]);
@@ -2511,8 +3042,8 @@ var REDEMPTION_FIELDS = [
 function withoutUnsetFields(body) {
   return Object.fromEntries(Object.entries(body).filter(([, value]) => value !== void 0));
 }
-function missingFields(event, fields) {
-  return { ok: false, error: `Creating ${event} requires: ${fields.join(", ")}.` };
+function missingFields(event, fields2) {
+  return { ok: false, error: `Creating ${event} requires: ${fields2.join(", ")}.` };
 }
 function unsupportedCreate(event) {
   return {
@@ -2805,45 +3336,45 @@ function isProgramChangeNoop(current, prepared) {
   return diffFields(current, prepared.body).length === 0;
 }
 var programConfigInputSchema = {
-  program_id: z15.string().min(1).optional().describe("Existing Joy program ID. Omit to create a new program."),
-  event: z15.string().optional().describe("Program event. Required for create; optional for update."),
-  title: z15.string().min(1).optional().describe("Customer-facing program title."),
-  status: z15.boolean().optional().describe("Set false to disable this rule instead of deleting it."),
-  priority: z15.number().int().optional().describe("Optional program priority."),
-  start_date: z15.string().optional().describe("Optional ISO start date."),
-  end_date: z15.string().optional().describe("Optional ISO end date."),
-  earn_by: z15.enum(["price", "fixed_order", "quantity", "order"]).optional(),
-  rate_money: z15.number().optional(),
-  rate_item: z15.number().optional(),
-  earn_point: z15.number().optional(),
-  date_format: z15.enum(["MM/DD", "DD/MM", "MM/DD/YYYY", "DD/MM/YYYY", "YYYY/MM/DD"]).optional(),
-  type_reward_timing: z15.enum(["exact_birthday", "begin_of_month", "around_birthday"]).optional(),
-  limit_unit: z15.string().optional(),
-  limit_interval: z15.number().int().positive().optional(),
-  url_account: z15.string().regex(/^https?:\/\//, "url_account must start with http:// or https://").optional().describe("REQUIRED when creating a social rule (follow_instagram, subscribe_youtube, like_facebook, follow_tiktok, follow_twitter, follow_pinterest, join_discord, join_telegram, join_reddit). The full URL of the shop's profile on that network \u2014 customers are sent here to complete the action."),
-  review_app: z15.enum(REVIEW_APPS).optional().describe("REQUIRED when creating a write_review rule: the review app the shop actually runs. Points cannot be awarded for reviews unless this matches the installed app."),
-  description_review: z15.string().optional().describe("Required only when review_app is a Shopify Flow app (stampedApp, looxApp, okendoApp, ReviewsIoApp, growaveApp, typdalApp) \u2014 the merchant-facing note describing how the Flow awards points."),
-  extra_points_for_images: z15.number().int().nonnegative().optional().describe("Bonus points for a review with a photo. Only reviewRocketApp and looxApp report photos; ignored for every other review app."),
-  extra_points_for_videos: z15.number().int().nonnegative().optional().describe("Bonus points for a review with a video. Only reviewRocketApp and looxApp report videos; ignored for every other review app."),
-  spend_point: z15.number().int().positive().optional(),
-  earn_amount: z15.number().optional(),
-  shipping_discount_type: z15.enum(["percentage", "fixedAmount"]).optional(),
-  shipping_discount_amount: z15.number().optional(),
-  applied_to: z15.enum(FREE_GIFT_PROGRAM_APPLIED_TO).optional().describe("free_gift only \u2014 sf_product, specific, or exclude_collection. This is a program-level enum and differs from tier rewards; it has no all value."),
-  specific_products: z15.array(z15.unknown()).optional().describe("free_gift with applied_to sf_product only \u2014 the merchant-provided product records/IDs. Do not invent product IDs."),
-  specific_collections: z15.array(z15.unknown()).optional(),
-  applied_collection_ids: z15.array(z15.string()).optional().describe("free_gift with applied_to specific or exclude_collection only \u2014 merchant-provided collection IDs."),
-  collection_quantity: z15.number().int().positive().optional().describe("Required for collection-based free_gift rules (applied_to specific or exclude_collection)."),
-  product_url: z15.array(z15.string()).optional().describe("free_gift with applied_to sf_product only \u2014 Shopify product URLs to resolve into product IDs. Accepts /products/<handle> or /collections/<collection>/products/<handle>; do not invent IDs."),
-  applied_place_order_to: z15.enum(["all", "vip-tier", "member_and_guest"]).optional().describe('place_order "Who to reward" radio: all = All loyalty members, vip-tier = VIP Tier only, member_and_guest = All customers. The admin UI and the earning engine both key off this field, not is_applied_vip_tier. Enabling is_applied_vip_tier or earn_points_tiers FORCES vip-tier \u2014 sending all here is why per-tier rates can save while the radio stays on All loyalty members.'),
-  is_applied_vip_tier: z15.boolean().optional().describe("Turn per-VIP-tier earning on for this rule. MUST be true for earn_points_tiers to have any effect \u2014 the backend reads the per-tier map only when this flag is set, and otherwise silently uses the flat earn_point."),
-  earn_points_tiers: z15.record(z15.object({
-    earn_point: z15.number().optional().describe("Points this tier earns, replacing the flat earn_point."),
-    rate_money: z15.number().optional().describe("place_order only: money amount that earns earn_point for this tier."),
-    type_earn: z15.enum(["point", "store_credit"]).optional()
+  program_id: z17.string().min(1).optional().describe("Existing Joy program ID. Omit to create a new program."),
+  event: z17.string().optional().describe("Program event. Required for create; optional for update."),
+  title: z17.string().min(1).optional().describe("Customer-facing program title."),
+  status: z17.boolean().optional().describe("Set false to disable this rule instead of deleting it."),
+  priority: z17.number().int().optional().describe("Optional program priority."),
+  start_date: z17.string().optional().describe("Optional ISO start date."),
+  end_date: z17.string().optional().describe("Optional ISO end date."),
+  earn_by: z17.enum(["price", "fixed_order", "quantity", "order"]).optional(),
+  rate_money: z17.number().optional(),
+  rate_item: z17.number().optional(),
+  earn_point: z17.number().optional(),
+  date_format: z17.enum(["MM/DD", "DD/MM", "MM/DD/YYYY", "DD/MM/YYYY", "YYYY/MM/DD"]).optional(),
+  type_reward_timing: z17.enum(["exact_birthday", "begin_of_month", "around_birthday"]).optional(),
+  limit_unit: z17.string().optional(),
+  limit_interval: z17.number().int().positive().optional(),
+  url_account: z17.string().regex(/^https?:\/\//, "url_account must start with http:// or https://").optional().describe("REQUIRED when creating a social rule (follow_instagram, subscribe_youtube, like_facebook, follow_tiktok, follow_twitter, follow_pinterest, join_discord, join_telegram, join_reddit). The full URL of the shop's profile on that network \u2014 customers are sent here to complete the action."),
+  review_app: z17.enum(REVIEW_APPS).optional().describe("REQUIRED when creating a write_review rule: the review app the shop actually runs. Points cannot be awarded for reviews unless this matches the installed app."),
+  description_review: z17.string().optional().describe("Required only when review_app is a Shopify Flow app (stampedApp, looxApp, okendoApp, ReviewsIoApp, growaveApp, segunoReviewApp, typdalApp) \u2014 the merchant-facing note describing how the Flow awards points."),
+  extra_points_for_images: z17.number().int().nonnegative().optional().describe("Bonus points for a review with a photo. Only reviewRocketApp and looxApp report photos; ignored for every other review app."),
+  extra_points_for_videos: z17.number().int().nonnegative().optional().describe("Bonus points for a review with a video. Only reviewRocketApp and looxApp report videos; ignored for every other review app."),
+  spend_point: z17.number().int().positive().optional(),
+  earn_amount: z17.number().optional(),
+  shipping_discount_type: z17.enum(["percentage", "fixedAmount"]).optional(),
+  shipping_discount_amount: z17.number().optional(),
+  applied_to: z17.enum(FREE_GIFT_PROGRAM_APPLIED_TO).optional().describe("free_gift only \u2014 sf_product, specific, or exclude_collection. This is a program-level enum and differs from tier rewards; it has no all value."),
+  specific_products: z17.array(z17.unknown()).optional().describe("free_gift with applied_to sf_product only \u2014 the merchant-provided product records/IDs. Do not invent product IDs."),
+  specific_collections: z17.array(z17.unknown()).optional(),
+  applied_collection_ids: z17.array(z17.string()).optional().describe("free_gift with applied_to specific or exclude_collection only \u2014 merchant-provided collection IDs."),
+  collection_quantity: z17.number().int().positive().optional().describe("Required for collection-based free_gift rules (applied_to specific or exclude_collection)."),
+  product_url: z17.array(z17.string()).optional().describe("free_gift with applied_to sf_product only \u2014 Shopify product URLs to resolve into product IDs. Accepts /products/<handle> or /collections/<collection>/products/<handle>; do not invent IDs."),
+  applied_place_order_to: z17.enum(["all", "vip-tier", "member_and_guest"]).optional().describe('place_order "Who to reward" radio: all = All loyalty members, vip-tier = VIP Tier only, member_and_guest = All customers. The admin UI and the earning engine both key off this field, not is_applied_vip_tier. Enabling is_applied_vip_tier or earn_points_tiers FORCES vip-tier \u2014 sending all here is why per-tier rates can save while the radio stays on All loyalty members.'),
+  is_applied_vip_tier: z17.boolean().optional().describe("Turn per-VIP-tier earning on for this rule. MUST be true for earn_points_tiers to have any effect \u2014 the backend reads the per-tier map only when this flag is set, and otherwise silently uses the flat earn_point."),
+  earn_points_tiers: z17.record(z17.object({
+    earn_point: z17.number().optional().describe("Points this tier earns, replacing the flat earn_point."),
+    rate_money: z17.number().optional().describe("place_order only: money amount that earns earn_point for this tier."),
+    type_earn: z17.enum(["point", "store_credit"]).optional()
   })).optional().describe("Per-VIP-tier earning, keyed by TIER ID (from joy_list_tiers) \u2014 not tier name. For place_order a \xD71.25 multiplier on a 1-point-per-$1 base is earn_point 1.25, not 1.25 as a factor: the value REPLACES the base rate. Requires is_applied_vip_tier: true."),
-  reason: z15.string().min(3).describe("Why the merchant wants this configuration change."),
-  apply: z15.boolean().optional().describe("Set true only after reviewing this tool's dry-run preview.")
+  reason: z17.string().min(3).describe("Why the merchant wants this configuration change."),
+  apply: z17.boolean().optional().describe("Set true only after reviewing this tool's dry-run preview.")
 };
 var PLACE_ORDER_EVENTS = /* @__PURE__ */ new Set(["place_order", "place_order_subscription"]);
 function placeOrderVipTierPatch(event, args) {
@@ -2987,7 +3518,7 @@ function registerProgramConfigTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/tiersWrite.js
-import { z as z16 } from "zod";
+import { z as z18 } from "zod";
 var TIER_THRESHOLD_WARNING = "Threshold changes are STAGED, not live. Members are not re-evaluated until the merchant relaunches tiers in Joy admin \u2014 this tool cannot trigger that.";
 var ENTRY_METHOD_WARNING = "Level-up rule (entryMethod) is saved immediately. NEW points, spend, and orders start counting in the new unit at once. Existing members keep their current tierPoint until the merchant relaunches tiers in Joy admin \u2014 this tool cannot trigger that. Review each tier threshold (target_point): 0/150/350 means points, currency, or orders depending on this rule.";
 var START_DATE_WARNING = "Program start date (startDate) is saved immediately and is the calculation window for NEW activity. Existing members keep their current tierPoint until the merchant relaunches tiers in Joy admin \u2014 this tool cannot trigger that. This is the VIP program start date, not reset_start_date.";
@@ -3076,7 +3607,7 @@ var TIER_SETTINGS_FIELDS = [
   "notificationDowngradeBefore",
   "notificationDowngradeBeforeUnit"
 ];
-var rewardEventSchema = z16.enum([
+var rewardEventSchema = z18.enum([
   "amount_discount",
   "percentage_discount",
   "free_shipping",
@@ -3084,101 +3615,101 @@ var rewardEventSchema = z16.enum([
   "bonus_point",
   "buy_x_get_y"
 ]);
-var finiteNumber = () => z16.number().finite();
-var tierRewardInputSchema = z16.object({
+var finiteNumber = () => z18.number().finite();
+var tierRewardInputSchema = z18.object({
   event: rewardEventSchema.describe("Required reward kind."),
-  title: z16.string().min(1).optional(),
-  type: z16.enum(["tier_spending", "tier_privileges", "pre_tier_reward"]).optional(),
-  status: z16.boolean().optional(),
+  title: z18.string().min(1).optional(),
+  type: z18.enum(["tier_spending", "tier_privileges", "pre_tier_reward"]).optional(),
+  status: z18.boolean().optional(),
   earn_amount: finiteNumber().optional(),
   spend_point: finiteNumber().optional(),
   bonus_points: finiteNumber().optional(),
-  code_name: z16.string().optional(),
-  redeem_type: z16.string().optional(),
-  applied_to: z16.enum(["all", "specific_product", "specific"]).optional().describe("Tier-reward scope only: all, specific_product, or specific. These literals differ from program-level reward tools."),
-  order_req: z16.enum(["none", "min_amount", "min_quantity"]).optional(),
+  code_name: z18.string().optional(),
+  redeem_type: z18.string().optional(),
+  applied_to: z18.enum(["all", "specific_product", "specific"]).optional().describe("Tier-reward scope only: all, specific_product, or specific. These literals differ from program-level reward tools."),
+  order_req: z18.enum(["none", "min_amount", "min_quantity"]).optional(),
   order_req_amount: finiteNumber().optional(),
   min_spend_point: finiteNumber().optional(),
   max_spend_point: finiteNumber().optional(),
-  specific_products: z16.array(z16.unknown()).optional(),
-  specific_collections: z16.array(z16.unknown()).optional(),
-  applied_collection_ids: z16.array(z16.unknown()).optional(),
-  combined_with: z16.array(z16.enum(["orderDiscounts", "shippingDiscounts", "productDiscounts"])).optional(),
-  has_limit_shipping: z16.boolean().optional(),
+  specific_products: z18.array(z18.unknown()).optional(),
+  specific_collections: z18.array(z18.unknown()).optional(),
+  applied_collection_ids: z18.array(z18.unknown()).optional(),
+  combined_with: z18.array(z18.enum(["orderDiscounts", "shippingDiscounts", "productDiscounts"])).optional(),
+  has_limit_shipping: z18.boolean().optional(),
   limit_shipping: finiteNumber().optional(),
   expired_after: finiteNumber().optional(),
-  expired_unit: z16.enum(["day", "month"]).optional(),
-  is_refund_coupon: z16.boolean().optional(),
+  expired_unit: z18.enum(["day", "month"]).optional(),
+  is_refund_coupon: z18.boolean().optional(),
   priority: finiteNumber().optional(),
-  show_loyalty_page: z16.boolean().optional(),
-  perk_title_language: z16.record(z16.unknown()).optional(),
-  reward_product_selection_mode: z16.string().optional(),
+  show_loyalty_page: z18.boolean().optional(),
+  perk_title_language: z18.record(z18.unknown()).optional(),
+  reward_product_selection_mode: z18.string().optional(),
   reward_product_quantity: finiteNumber().optional()
 });
 var tierConfigInputSchema = {
-  tier_id: z16.string().min(1).optional().describe("Existing tier ID. Omit to create a tier."),
-  name: z16.string().min(1).optional(),
+  tier_id: z18.string().min(1).optional().describe("Existing tier ID. Omit to create a tier."),
+  name: z18.string().min(1).optional(),
   target_point: finiteNumber().nonnegative().optional().describe("Tier threshold. On an existing tier this is staged; it does not immediately re-evaluate members."),
-  icon: z16.string().optional(),
-  icon_custom: z16.string().optional(),
-  bg_image: z16.string().optional().describe("Membership card background image URL for this ONE tier. Pass bg_type: 'image' alongside bg_image for it to show, or '' to clear. Use a durable URL the merchant controls; joy_upload_image uploads to their Shopify Files CDN and returns one. Widget-wide membershipCard.beforeSignIn.bgImage and membershipCard.afterSignIn.bgImage are different fields, managed by joy_set_widget_fields."),
-  default_avatar: z16.string().optional().describe("Membership card avatar image URL for members in this ONE tier. Pass '' to clear. Use a durable URL the merchant controls; joy_upload_image uploads to their Shopify Files CDN and returns one. Widget-wide membershipCard.beforeSignIn.bgImage and membershipCard.afterSignIn.bgImage are different fields, managed by joy_set_widget_fields."),
-  image_block: z16.string().optional(),
-  is_exclusive_tier: z16.boolean().optional(),
-  hide_default_tier: z16.boolean().optional(),
-  text_color: z16.string().optional(),
-  progress_bar_color: z16.string().optional(),
-  box_bg_color: z16.string().optional(),
-  box_text_color: z16.string().optional(),
-  bg_card_color: z16.string().optional(),
+  icon: z18.string().optional(),
+  icon_custom: z18.string().optional(),
+  bg_image: z18.string().optional().describe("Membership card background image URL for this ONE tier. Pass bg_type: 'image' alongside bg_image for it to show, or '' to clear. Use a durable URL the merchant controls; joy_upload_image uploads to their Shopify Files CDN and returns one. Widget-wide membershipCard.beforeSignIn.bgImage and membershipCard.afterSignIn.bgImage are different fields, managed by joy_set_widget_fields."),
+  default_avatar: z18.string().optional().describe("Membership card avatar image URL for members in this ONE tier. Pass '' to clear. Use a durable URL the merchant controls; joy_upload_image uploads to their Shopify Files CDN and returns one. Widget-wide membershipCard.beforeSignIn.bgImage and membershipCard.afterSignIn.bgImage are different fields, managed by joy_set_widget_fields."),
+  image_block: z18.string().optional(),
+  is_exclusive_tier: z18.boolean().optional(),
+  hide_default_tier: z18.boolean().optional(),
+  text_color: z18.string().optional(),
+  progress_bar_color: z18.string().optional(),
+  box_bg_color: z18.string().optional(),
+  box_text_color: z18.string().optional(),
+  bg_card_color: z18.string().optional(),
   card_opacity: finiteNumber().optional(),
-  icon_color: z16.string().optional(),
-  bg_type: z16.string().optional(),
-  tier_names_language: z16.record(z16.unknown()).optional(),
-  rewards: z16.array(tierRewardInputSchema).optional().describe("Optional rewards to create with a NEW tier in this one configuration write."),
-  reason: z16.string().min(3).describe("Why the merchant wants this tier configuration."),
-  apply: z16.boolean().optional().describe("Set true only after the dry-run preview is approved.")
+  icon_color: z18.string().optional(),
+  bg_type: z18.string().optional(),
+  tier_names_language: z18.record(z18.unknown()).optional(),
+  rewards: z18.array(tierRewardInputSchema).optional().describe("Optional rewards to create with a NEW tier in this one configuration write."),
+  reason: z18.string().min(3).describe("Why the merchant wants this tier configuration."),
+  apply: z18.boolean().optional().describe("Set true only after the dry-run preview is approved.")
 };
 var tierRewardToolInputSchema = {
-  tier_id: z16.string().min(1).describe("Tier ID from joy_list_tiers."),
-  reward_id: z16.string().min(1).optional().describe("Existing reward ID. Omit to create."),
+  tier_id: z18.string().min(1).describe("Tier ID from joy_list_tiers."),
+  reward_id: z18.string().min(1).optional().describe("Existing reward ID. Omit to create."),
   ...tierRewardInputSchema.shape,
-  product_url: z16.array(z16.string()).optional().describe("free_gift with applied_to specific_product only \u2014 Shopify product URLs to resolve into product IDs. Accepts /products/<handle> or /collections/<collection>/products/<handle>; do not invent IDs."),
-  reason: z16.string().min(3).describe("Why the merchant wants this reward configuration."),
-  apply: z16.boolean().optional().describe("Set true only after the dry-run preview is approved.")
+  product_url: z18.array(z18.string()).optional().describe("free_gift with applied_to specific_product only \u2014 Shopify product URLs to resolve into product IDs. Accepts /products/<handle> or /collections/<collection>/products/<handle>; do not invent IDs."),
+  reason: z18.string().min(3).describe("Why the merchant wants this reward configuration."),
+  apply: z18.boolean().optional().describe("Set true only after the dry-run preview is approved.")
 };
 var tierSettingsInputSchema = {
-  entry_method: z16.enum(["pointEarned", "moneySpent", "numberOfOrders"]).optional().describe("Tier calculation / level-up rule: how members climb the ladder. pointEarned = points earned, moneySpent = amount spent, numberOfOrders = number of orders. Saved immediately \u2014 NEW activity counts in the new unit at once. Existing members keep their current tierPoint until the merchant relaunches in Joy admin; this tool cannot trigger that. After changing, review each tier's target_point: the same 0/150/350 numbers mean points, currency, or orders depending on this rule."),
-  start_date: z16.string().min(1).optional().describe('VIP program start date \u2014 the calculation window in the admin "Tier calculation" card (ISO date, YYYY-MM-DD). Distinct from reset_start_date, which is the custom reset-cycle anchor. Saved immediately; members keep their current tierPoint until the merchant relaunches in Joy admin.'),
-  prefix: z16.string().optional().describe("Custom discount-code prefix for tier rewards. Supports {{tier_name}}. Pair with use_prefix_discount_code: true, or the custom prefix is stored but unused."),
-  use_prefix_discount_code: z16.boolean().optional().describe("When true, tier reward codes use prefix instead of the shop default."),
-  show_tier_point_settings: z16.boolean().optional().describe("Show tier-point editing on the customer admin page."),
-  allow_give_entry_reward_again: z16.boolean().optional().describe("When true (Joy default), a member who is demoted and later re-enters a tier can receive that tier entry reward again. False grants it only once."),
-  use_demotion_tier: z16.boolean().optional(),
-  type_demotion: z16.enum(["downgrade_tier", "reset_tier"]).optional(),
-  downgrade_after: z16.number().int().positive().optional(),
-  downgrade_after_unit: z16.enum(["day", "month", "year"]).optional(),
-  use_reset_tier: z16.boolean().optional(),
-  reset_after: z16.number().int().positive().optional(),
-  reset_after_unit: z16.enum(["day", "month", "year"]).optional(),
-  reset_frequency: z16.enum(["monthly", "quarterly", "half_yearly", "yearly", "custom"]).optional(),
-  reset_interval_value: z16.number().int().positive().optional(),
-  reset_interval_unit: z16.enum(["day", "month", "year"]).optional(),
-  reset_start_date: z16.string().min(1).optional(),
-  month_reset_tier: z16.number().int().min(1).max(12).optional(),
-  day_reset_tier: z16.number().int().min(1).max(31).optional(),
-  is_sync_tags_customer_tier: z16.boolean().optional(),
-  customer_tier_tag_prefix: z16.string().optional(),
-  notification_downgrade_before: z16.number().int().positive().optional(),
-  notification_downgrade_before_unit: z16.enum(["day", "month"]).optional(),
-  reason: z16.string().min(3).describe("Why the merchant wants these tier settings."),
-  apply: z16.boolean().optional().describe("Set true only after the dry-run preview is approved.")
+  entry_method: z18.enum(["pointEarned", "moneySpent", "numberOfOrders"]).optional().describe("Tier calculation / level-up rule: how members climb the ladder. pointEarned = points earned, moneySpent = amount spent, numberOfOrders = number of orders. Saved immediately \u2014 NEW activity counts in the new unit at once. Existing members keep their current tierPoint until the merchant relaunches in Joy admin; this tool cannot trigger that. After changing, review each tier's target_point: the same 0/150/350 numbers mean points, currency, or orders depending on this rule."),
+  start_date: z18.string().min(1).optional().describe('VIP program start date \u2014 the calculation window in the admin "Tier calculation" card (ISO date, YYYY-MM-DD). Distinct from reset_start_date, which is the custom reset-cycle anchor. Saved immediately; members keep their current tierPoint until the merchant relaunches in Joy admin.'),
+  prefix: z18.string().optional().describe("Custom discount-code prefix for tier rewards. Supports {{tier_name}}. Pair with use_prefix_discount_code: true, or the custom prefix is stored but unused."),
+  use_prefix_discount_code: z18.boolean().optional().describe("When true, tier reward codes use prefix instead of the shop default."),
+  show_tier_point_settings: z18.boolean().optional().describe("Show tier-point editing on the customer admin page."),
+  allow_give_entry_reward_again: z18.boolean().optional().describe("When true (Joy default), a member who is demoted and later re-enters a tier can receive that tier entry reward again. False grants it only once."),
+  use_demotion_tier: z18.boolean().optional(),
+  type_demotion: z18.enum(["downgrade_tier", "reset_tier"]).optional(),
+  downgrade_after: z18.number().int().positive().optional(),
+  downgrade_after_unit: z18.enum(["day", "month", "year"]).optional(),
+  use_reset_tier: z18.boolean().optional(),
+  reset_after: z18.number().int().positive().optional(),
+  reset_after_unit: z18.enum(["day", "month", "year"]).optional(),
+  reset_frequency: z18.enum(["monthly", "quarterly", "half_yearly", "yearly", "custom"]).optional(),
+  reset_interval_value: z18.number().int().positive().optional(),
+  reset_interval_unit: z18.enum(["day", "month", "year"]).optional(),
+  reset_start_date: z18.string().min(1).optional(),
+  month_reset_tier: z18.number().int().min(1).max(12).optional(),
+  day_reset_tier: z18.number().int().min(1).max(31).optional(),
+  is_sync_tags_customer_tier: z18.boolean().optional(),
+  customer_tier_tag_prefix: z18.string().optional(),
+  notification_downgrade_before: z18.number().int().positive().optional(),
+  notification_downgrade_before_unit: z18.enum(["day", "month"]).optional(),
+  reason: z18.string().min(3).describe("Why the merchant wants these tier settings."),
+  apply: z18.boolean().optional().describe("Set true only after the dry-run preview is approved.")
 };
 var tierPerksInputSchema = {
-  tier_id: z16.string().min(1).describe("Tier ID from joy_list_tiers."),
-  perks: z16.array(z16.string().min(1)).describe("The COMPLETE replacement list of display-only perks. Include every existing perk that should remain; omitted entries are removed, and [] clears the list. Each entry is perk text or an http(s) URL rendered as a tick/cross icon in the storefront benefits table."),
-  reason: z16.string().min(3).describe("Why the merchant wants to replace this tier perk list."),
-  apply: z16.boolean().optional().describe("Set true only after the dry-run preview is approved.")
+  tier_id: z18.string().min(1).describe("Tier ID from joy_list_tiers."),
+  perks: z18.array(z18.string().min(1)).describe("The COMPLETE replacement list of display-only perks. Include every existing perk that should remain; omitted entries are removed, and [] clears the list. Each entry is perk text or an http(s) URL rendered as a tick/cross icon in the storefront benefits table."),
+  reason: z18.string().min(3).describe("Why the merchant wants to replace this tier perk list."),
+  apply: z18.boolean().optional().describe("Set true only after the dry-run preview is approved.")
 };
 function tierFreeGiftSelectionError(args, requireAppliedTo = false) {
   if (args.event !== "free_gift")
@@ -3277,7 +3808,7 @@ function buildTierConfigPreview(params) {
 }
 function rethrowTierCreateConflict(error) {
   if (error instanceof JoyApiError && error.status === 409) {
-    throw new JoyApiError("conflict", "Cannot create this tier because another tier already has this name or target_point. Call joy_list_tiers, then update the existing tier with tier_id instead of retrying the create.", error.status);
+    throw new JoyApiError("conflict", "Cannot create this tier because another tier already has this name or target_point. Call joy_list_tiers, then update the existing tier with tier_id instead of retrying the create.", error.status, error.serverCode);
   }
   throw error;
 }
@@ -3597,7 +4128,7 @@ async function readTierSettings(ctx) {
 }
 function rethrowTierSettingsNotLaunched(error) {
   if (error instanceof JoyApiError && error.kind === "not_found") {
-    throw new JoyApiError("not_found", "This shop has never launched tiers, so tier settings do not exist yet. Launch the tier program in Joy admin first; this MCP tool cannot launch it.", error.status);
+    throw new JoyApiError("not_found", "This shop has never launched tiers, so tier settings do not exist yet. Launch the tier program in Joy admin first; this MCP tool cannot launch it.", error.status, error.serverCode);
   }
   throw error;
 }
@@ -3787,7 +4318,7 @@ function isAfterOrEqual(candidate, cursor, inclusive) {
 }
 
 // ../mcp-core/build/tools/shopConfig.js
-import { z as z17 } from "zod";
+import { z as z19 } from "zod";
 var SHOP_SETTINGS_FIELDS = [
   "primaryLanguageInApp",
   "dateFormat",
@@ -3885,8 +4416,8 @@ function toShopSettingsBody(args) {
 function getDroppedShopSettingsFields(args) {
   return getUnknownArguments(args, SHOP_SETTINGS_VALID_ARGUMENTS);
 }
-function selectedFields(body, fields) {
-  const selected = fields.filter((field) => body[field] !== void 0);
+function selectedFields(body, fields2) {
+  const selected = fields2.filter((field) => body[field] !== void 0);
   return selected.length > 0 ? selected.join(", ") : "none selected";
 }
 function buildShopSettingsPreview(current, args) {
@@ -3930,20 +4461,20 @@ function registerShopConfigTools(server, ctx) {
     title: "Configure safe shop-level loyalty settings",
     description: "WRITE \u2014 updates a deliberately limited set of shop-level loyalty settings. The backend splits this request between the shops collection and a separate settings document without atomic rollback, so a partial failure is possible. SSO controls, tier-specific earning limits, and weekly-report BCC recipients are intentionally unavailable through this tool.",
     inputSchema: {
-      primary_language_in_app: z17.enum(["en", "en-US", "fr", "es", "de", "it", "ja", "id", "zh-CN"]).optional(),
-      date_format: z17.enum(["MM/DD/YYYY", "DD/MM/YYYY", "YYYY/MM/DD", "YYYY-MM-DD"]).optional(),
-      date_format_for_activity: z17.enum(["HH:mm", "hh:mm A"]).optional(),
-      point_position: z17.enum(["before", "after"]).optional(),
-      customer_apply_discount_behavior: z17.enum(["stay_current", "go_to_cart", "open_cart_drawer"]).optional(),
-      customer_redeem_coupon_behavior: z17.enum(["auto_apply", "save_for_later"]).optional(),
-      customer_free_gift_behavior: z17.enum(["manual_add_to_cart", "auto_add_to_cart"]).optional(),
-      status_for_review: z17.enum(["pending", "approveAuto"]).optional(),
-      earn_by_order_status: z17.enum(["financial_status", "fulfillment_status"]).optional(),
-      enable_global_earning_limit: z17.boolean().optional(),
-      global_earning_limit_timeframe: z17.enum(["yearly", "monthly", "rolling"]).optional(),
-      global_earning_limit_rolling_days: z17.number().int().min(1).max(365).optional(),
-      reason: z17.string().min(3).describe("Why the merchant wants these shop-wide settings changed."),
-      apply: z17.boolean().optional().describe("Set true only after the merchant has approved the dry-run preview.")
+      primary_language_in_app: z19.enum(["en", "en-US", "fr", "es", "de", "it", "ja", "id", "zh-CN"]).optional(),
+      date_format: z19.enum(["MM/DD/YYYY", "DD/MM/YYYY", "YYYY/MM/DD", "YYYY-MM-DD"]).optional(),
+      date_format_for_activity: z19.enum(["HH:mm", "hh:mm A"]).optional(),
+      point_position: z19.enum(["before", "after"]).optional(),
+      customer_apply_discount_behavior: z19.enum(["stay_current", "go_to_cart", "open_cart_drawer"]).optional(),
+      customer_redeem_coupon_behavior: z19.enum(["auto_apply", "save_for_later"]).optional(),
+      customer_free_gift_behavior: z19.enum(["manual_add_to_cart", "auto_add_to_cart"]).optional(),
+      status_for_review: z19.enum(["pending", "approveAuto"]).optional(),
+      earn_by_order_status: z19.enum(["financial_status", "fulfillment_status"]).optional(),
+      enable_global_earning_limit: z19.boolean().optional(),
+      global_earning_limit_timeframe: z19.enum(["yearly", "monthly", "rolling"]).optional(),
+      global_earning_limit_rolling_days: z19.number().int().min(1).max(365).optional(),
+      reason: z19.string().min(3).describe("Why the merchant wants these shop-wide settings changed."),
+      apply: z19.boolean().optional().describe("Set true only after the merchant has approved the dry-run preview.")
     },
     destructiveHint: false,
     strictArguments: true,
@@ -3965,10 +4496,10 @@ function registerShopConfigTools(server, ctx) {
     title: "Add a storefront translation language",
     description: "WRITE \u2014 adds one storefront language by machine-translating the shop's entire existing primary-language content. This can be expensive and is hard to undo, so it always requires a dry-run preview and explicit approval before applying.",
     inputSchema: {
-      primary_language: z17.enum(TRANSLATION_LOCALES),
-      additional_language: z17.enum(TRANSLATION_LOCALES),
-      reason: z17.string().min(3).describe("Why the merchant wants this storefront language added."),
-      apply: z17.boolean().optional().describe("Set true only after the merchant has approved the dry-run preview.")
+      primary_language: z19.enum(TRANSLATION_LOCALES),
+      additional_language: z19.enum(TRANSLATION_LOCALES),
+      reason: z19.string().min(3).describe("Why the merchant wants this storefront language added."),
+      apply: z19.boolean().optional().describe("Set true only after the merchant has approved the dry-run preview.")
     },
     destructiveHint: false,
     strictArguments: true,
@@ -3987,7 +4518,7 @@ function registerShopConfigTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/brandingWrite.js
-import { z as z18 } from "zod";
+import { z as z20 } from "zod";
 var WIDGET_DRAFT_SAVED_MESSAGE = "Saved to the V4 draft. The storefront is unchanged until you publish it in Joy admin.";
 var HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
 var COLOR_ROLE_PATHS = {
@@ -4030,26 +4561,26 @@ var BUTTON_STYLE_VALUES = ["store", "preset", "custom"];
 var CONTENT_STYLE_VALUES = ["icons_and_text", "text_only"];
 var DISPLAY_TYPE_VALUES = ["widget", "drawer", "floating-drawer"];
 var widgetDraftInputSchema = {
-  version: z18.enum(["v3", "v4"]).describe("Widget version to change. A live target is accepted only when this is the shop\u2019s currently live version."),
-  target: z18.enum(["draft", "live"]).default("draft").describe("Draft by default. Set live only after the merchant approves a dry-run preview of the immediate storefront change."),
-  apply_scan: z18.boolean().optional().describe("Apply a storefront scan through Joy\u2019s shared backend design merge. Omit scan_url to scan this shop\u2019s own storefront."),
-  scan_url: z18.string().url().startsWith("https://").optional().describe("Optional public HTTPS storefront URL to scan when apply_scan is true."),
-  storefront_password: z18.string().min(1).optional().describe("Optional storefront password used only when apply_scan is true. It is sent only in the PUT body and is never returned."),
-  apply_images: z18.boolean().optional().describe("When apply_scan is true, also replace detected logo and card imagery. Defaults to false."),
-  color_overrides: z18.record(z18.string()).optional().describe(`Optional hex overrides for supported V4 color roles: ${COLOR_ROLES.join(", ")}.`),
-  design_overrides: z18.object({
-    corner_radius: z18.enum(CORNER_RADIUS_VALUES).optional().describe("Corner style. radiusNone is square/not rounded; radiusExtra is the most rounded."),
-    button_style: z18.enum(BUTTON_STYLE_VALUES).optional().describe("store matches the storefront, custom uses the widget\u2019s own button colours."),
-    content_style: z18.enum(CONTENT_STYLE_VALUES).optional().describe("text_only removes the icons beside earn/redeem rows; icons_and_text shows them."),
-    display_type: z18.enum(DISPLAY_TYPE_VALUES).optional().describe("widget is the inline panel; drawer slides in from the edge; floating-drawer is the floating panel with a launcher button.")
+  version: z20.enum(["v3", "v4"]).describe("Widget version to change. A live target is accepted only when this is the shop\u2019s currently live version."),
+  target: z20.enum(["draft", "live"]).default("draft").describe("Draft by default. Set live only after the merchant approves a dry-run preview of the immediate storefront change."),
+  apply_scan: z20.boolean().optional().describe("Apply a storefront scan through Joy\u2019s shared backend design merge. Omit scan_url to scan this shop\u2019s own storefront."),
+  scan_url: z20.string().url().startsWith("https://").optional().describe("Optional public HTTPS storefront URL to scan when apply_scan is true."),
+  storefront_password: z20.string().min(1).optional().describe("Optional storefront password used only when apply_scan is true. It is sent only in the PUT body and is never returned."),
+  apply_images: z20.boolean().optional().describe("When apply_scan is true, also replace detected logo and card imagery. Defaults to false."),
+  color_overrides: z20.record(z20.string()).optional().describe(`Optional hex overrides for supported V4 color roles: ${COLOR_ROLES.join(", ")}.`),
+  design_overrides: z20.object({
+    corner_radius: z20.enum(CORNER_RADIUS_VALUES).optional().describe("Corner style. radiusNone is square/not rounded; radiusExtra is the most rounded."),
+    button_style: z20.enum(BUTTON_STYLE_VALUES).optional().describe("store matches the storefront, custom uses the widget\u2019s own button colours."),
+    content_style: z20.enum(CONTENT_STYLE_VALUES).optional().describe("text_only removes the icons beside earn/redeem rows; icons_and_text shows them."),
+    display_type: z20.enum(DISPLAY_TYPE_VALUES).optional().describe("widget is the inline panel; drawer slides in from the edge; floating-drawer is the floating panel with a launcher button.")
   }).optional().describe("Optional non-colour design settings. Values are enums, not numbers or CSS lengths."),
-  font_overrides: z18.object({ heading: z18.string().min(1).optional(), body: z18.string().min(1).optional() }).optional().describe("Optional heading and body font overrides."),
-  reason: z18.string().min(3).describe("Why the merchant wants this widget draft."),
-  apply: z18.boolean().optional().describe("Omit or set false for a dry run. Set true only after the merchant approves the preview.")
+  font_overrides: z20.object({ heading: z20.string().min(1).optional(), body: z20.string().min(1).optional() }).optional().describe("Optional heading and body font overrides."),
+  reason: z20.string().min(3).describe("Why the merchant wants this widget draft."),
+  apply: z20.boolean().optional().describe("Omit or set false for a dry run. Set true only after the merchant approves the preview.")
 };
 var brandScanInputSchema = {
-  url: z18.string().url().startsWith("https://").optional().describe("Optional public HTTPS storefront URL. Omit it to scan this shop\u2019s own storefront."),
-  storefront_password: z18.string().min(1).optional().describe("Optional storefront password for a gated shop. It is sent only in the POST body and is never returned.")
+  url: z20.string().url().startsWith("https://").optional().describe("Optional public HTTPS storefront URL. Omit it to scan this shop\u2019s own storefront."),
+  storefront_password: z20.string().min(1).optional().describe("Optional storefront password for a gated shop. It is sent only in the POST body and is never returned.")
 };
 function isHexColor(value) {
   return typeof value === "string" && HEX_COLOR.test(value);
@@ -4074,19 +4605,19 @@ function brandingErrorGuidance(error, operation, target = "draft") {
   const passwordIncorrect = errorCode === "PASSWORD_INCORRECT" || /PASSWORD_INCORRECT|storefront password (?:did not unlock|was not accepted)|incorrect storefront password/i.test(error.modelMessage);
   const passwordRequired = errorCode === "PASSWORD_REQUIRED" || error.status === 409 || /PASSWORD_REQUIRED|storefront is password-protected|storefront password is required/i.test(error.modelMessage);
   if (operation === "scan" && passwordIncorrect) {
-    return new JoyApiError("validation", "The storefront password was not accepted. Ask the merchant to verify the storefront password, then pass the corrected value as storefront_password. Do not guess it.", error.status);
+    return new JoyApiError("validation", "The storefront password was not accepted. Ask the merchant to verify the storefront password, then pass the corrected value as storefront_password. Do not guess it.", error.status, error.serverCode);
   }
   if (operation === "scan" && passwordRequired) {
-    return new JoyApiError("conflict", "The storefront is password-protected. Ask the merchant for the storefront password, then pass it as storefront_password to joy_scan_brand_design. Do not guess the password, and do not invent colors or fonts.", error.status);
+    return new JoyApiError("conflict", "The storefront is password-protected. Ask the merchant for the storefront password, then pass it as storefront_password to joy_scan_brand_design. Do not guess the password, and do not invent colors or fonts.", error.status, error.serverCode);
   }
   if (operation === "scan" && error.status === 503) {
-    return new JoyApiError("server", "Joy could not complete the storefront design scan. No design has been returned, so do not invent colors, fonts, or button styling. Ask the merchant to retry later or configure the draft manually.", error.status);
+    return new JoyApiError("server", "Joy could not complete the storefront design scan. No design has been returned, so do not invent colors, fonts, or button styling. Ask the merchant to retry later or configure the draft manually.", error.status, error.serverCode);
   }
   if (operation === "draft" && target === "live" && error.status === 409) {
-    return new JoyApiError("conflict", "The live widget document exists only for the version the shop is currently using. This target: 'live' request used a non-live version and was refused. Check which widget version is currently live before retrying; do not blindly retry the other version.", error.status);
+    return new JoyApiError("conflict", "The live widget document exists only for the version the shop is currently using. This target: 'live' request used a non-live version and was refused. Check which widget version is currently live before retrying; do not blindly retry the other version.", error.status, error.serverCode);
   }
   if (operation === "draft" && error.status === 409) {
-    return new JoyApiError("conflict", "The requested widget version is currently live. This tool only writes the non-live draft so it cannot alter the storefront. Choose the other version or edit the live widget manually in Joy admin.", error.status);
+    return new JoyApiError("conflict", "The requested widget version is currently live. This tool only writes the non-live draft so it cannot alter the storefront. Choose the other version or edit the live widget manually in Joy admin.", error.status, error.serverCode);
   }
   return void 0;
 }
@@ -4149,7 +4680,7 @@ function errorWithoutCredential(error, credential) {
   if (!credential)
     return error;
   if (error instanceof JoyApiError) {
-    return new JoyApiError(error.kind, redactCredential(error.modelMessage, credential), error.status);
+    return new JoyApiError(error.kind, redactCredential(error.modelMessage, credential), error.status, error.serverCode);
   }
   if (error instanceof Error)
     return new Error(redactCredential(error.message, credential));
@@ -4390,13 +4921,13 @@ ${WIDGET_DRAFT_SAVED_MESSAGE}` : ""}`;
 
 // ../mcp-core/build/tools/widgetFields.js
 import { isDeepStrictEqual } from "node:util";
-import { z as z19 } from "zod";
+import { z as z21 } from "zod";
 var fieldsPath = "/shop/branding/widget/fields";
 var HIDE_MASTER = "display.hideWidgetButton";
 var HIDE_ALL = "launcher.hideCompletely";
 var HIDE_MOBILE = "launcher.hideOnMobile";
-function expandLauncherHideFields(fields, current) {
-  const byPath = new Map(fields.map(({ path, value }) => [path, value]));
+function expandLauncherHideFields(fields2, current) {
+  const byPath = new Map(fields2.map(({ path, value }) => [path, value]));
   const currentOf = (path) => current.find((field) => field.path === path)?.current;
   const get = (path) => byPath.has(path) ? byPath.get(path) : currentOf(path);
   const hideMaster = get(HIDE_MASTER);
@@ -4410,20 +4941,20 @@ function expandLauncherHideFields(fields, current) {
   }
   return [...byPath.entries()].map(([path, value]) => ({ path, value }));
 }
-var versionSchema = z19.literal("v4").default("v4").describe("Widget version. Field discovery currently supports V4.");
+var versionSchema = z21.literal("v4").default("v4").describe("Widget version. Field discovery currently supports V4.");
 var widgetFieldsInputSchema = {
   version: versionSchema,
-  target: z19.enum(["draft", "live"]).default("draft").describe("Draft by default. Use live only when the merchant explicitly requests and approves the immediate storefront change; there is no undo."),
-  fields: z19.array(z19.object({
-    path: z19.string().min(1),
-    value: z19.unknown().refine((value) => value !== void 0, "Each field must include a value; use null to clear it.")
+  target: z21.enum(["draft", "live"]).default("draft").describe("Draft by default. Use live only when the merchant explicitly requests and approves the immediate storefront change; there is no undo."),
+  fields: z21.array(z21.object({
+    path: z21.string().min(1),
+    value: z21.unknown().refine((value) => value !== void 0, "Each field must include a value; use null to clear it.")
   })).min(1).describe("Paths and values to set. Discover paths and allowed values with joy_get_widget_fields. The server validates every value."),
-  reason: z19.string().min(3).describe("Why the merchant wants these widget changes."),
-  apply: z19.boolean().optional().describe("Omit or set false for a dry run. Set true only after the merchant approves the preview.")
+  reason: z21.string().min(3).describe("Why the merchant wants these widget changes."),
+  apply: z21.boolean().optional().describe("Omit or set false for a dry run. Set true only after the merchant approves the preview.")
 };
 var MAX_FIELD_RESPONSE_CHARS = 12e3;
-function estimateSize(fields) {
-  return fields.reduce((total, field) => total + field.path.length + field.label.length + 60 + (field.values?.join("").length ?? 0), 0);
+function estimateSize(fields2) {
+  return fields2.reduce((total, field) => total + field.path.length + field.label.length + 60 + (field.values?.join("").length ?? 0), 0);
 }
 async function getWidgetFields(ctx, version2) {
   const { data } = await ctx.api.getData(fieldsPath, { query: { version: version2 } });
@@ -4439,24 +4970,24 @@ function registerWidgetFieldReadTools(server, ctx) {
     description: "READ \u2014 discovers settable V4 widget fields. With no arguments it returns the group index (names, counts, example paths); pass group or search to get those fields with merchant-facing labels, paths, types, current values and allowed enum values. Call before joy_set_widget_fields; never guess a field path or enum value.",
     inputSchema: {
       version: versionSchema,
-      group: z19.string().optional().describe("Return only this group. Omit to get the group index first."),
-      search: z19.string().optional().describe('Return only fields whose label or path contains this text, e.g. "corner" or "launcher".')
+      group: z21.string().optional().describe("Return only this group. Omit to get the group index first."),
+      search: z21.string().optional().describe('Return only fields whose label or path contains this text, e.g. "corner" or "launcher".')
     },
     handler: async (args) => {
-      const fields = await getWidgetFields(ctx, args.version);
+      const fields2 = await getWidgetFields(ctx, args.version);
       const term = args.search?.trim().toLocaleLowerCase();
-      const matched = fields.filter((field) => (args.group === void 0 || field.group === args.group) && (term === void 0 || term === "" || field.label.toLocaleLowerCase().includes(term) || field.path.toLocaleLowerCase().includes(term)));
+      const matched = fields2.filter((field) => (args.group === void 0 || field.group === args.group) && (term === void 0 || term === "" || field.label.toLocaleLowerCase().includes(term) || field.path.toLocaleLowerCase().includes(term)));
       const wouldNotFit = estimateSize(matched) > MAX_FIELD_RESPONSE_CHARS;
       if (args.group === void 0 && !term && wouldNotFit) {
         const index = {};
-        for (const field of fields) {
+        for (const field of fields2) {
           const entry = index[field.group] ?? { fields: 0, examples: [] };
           entry.fields += 1;
           if (entry.examples.length < 2)
             entry.examples.push(field.path);
           index[field.group] = entry;
         }
-        return summaryWithJson(`${fields.length} settable ${args.version.toUpperCase()} widget fields across ${Object.keys(index).length} groups. Call again with group: "<name>" or search: "<text>" to see fields and their allowed values.`, { groups: index });
+        return summaryWithJson(`${fields2.length} settable ${args.version.toUpperCase()} widget fields across ${Object.keys(index).length} groups. Call again with group: "<name>" or search: "<text>" to see fields and their allowed values.`, { groups: index });
       }
       if (matched.length === 0) {
         return `No ${args.version.toUpperCase()} widget field matches ${args.group === void 0 ? `search "${args.search}"` : `group "${args.group}"`}. Call joy_get_widget_fields with no arguments to list the groups.`;
@@ -4467,7 +4998,7 @@ function registerWidgetFieldReadTools(server, ctx) {
         entries.push({ label, path, type, current, ...values === void 0 ? {} : { values } });
         groups.set(group, entries);
       }
-      return summaryWithJson(`${matched.length} of ${fields.length} settable ${args.version.toUpperCase()} widget fields. Use the server-provided paths and values when preparing changes.`, { groups: Object.fromEntries(groups) });
+      return summaryWithJson(`${matched.length} of ${fields2.length} settable ${args.version.toUpperCase()} widget fields. Use the server-provided paths and values when preparing changes.`, { groups: Object.fromEntries(groups) });
     }
   });
 }
@@ -4481,8 +5012,8 @@ function registerWidgetFieldWriteTools(server, ctx) {
     destructiveHint: true,
     handler: async (args) => {
       const current = await getWidgetFields(ctx, args.version);
-      const fields = expandLauncherHideFields(args.fields, current);
-      const changes = fields.map(({ path, value }) => ({
+      const fields2 = expandLauncherHideFields(args.fields, current);
+      const changes = fields2.map(({ path, value }) => ({
         path,
         from: current.find((field) => field.path === path)?.current,
         to: value
@@ -4497,7 +5028,7 @@ The server will validate every requested path and value when applied; this previ
         result = await ctx.api.mutateData(fieldsPath, {
           method: "PUT",
           query: { version: args.version, target: args.target },
-          body: { fields }
+          body: { fields: fields2 }
         });
       } catch (error) {
         throw brandingErrorGuidance(error, "draft", args.target) ?? error;
@@ -4512,7 +5043,7 @@ The server will validate every requested path and value when applied; this previ
       const refusedPaths = new Set(result.refused.map((field) => field.path));
       const applied2 = [];
       const unconfirmed = [];
-      for (const field of fields) {
+      for (const field of fields2) {
         if (refusedPaths.has(field.path))
           continue;
         const accepted = result.applied.find((entry) => entry.path === field.path);
@@ -4540,7 +5071,7 @@ Do not report refused or unconfirmed fields as saved. Inspect the current widget
 }
 
 // ../mcp-core/build/tools/referralBrandingWrite.js
-import { z as z20 } from "zod";
+import { z as z22 } from "zod";
 var POPUP_DISPLAY_TYPES = ["auto_show_popup", "show_bubble_teaser", "do_not_show"];
 var REFERRAL_WIDGET_ARGUMENTS = {
   brand_color: "brandColor",
@@ -4556,24 +5087,24 @@ var REFERRAL_WIDGET_ARGUMENTS = {
   frequency_show_popup: "frequencyShowPopup",
   is_show_subscribe_newsletter: "isShowSubscribeNewsletter"
 };
-var hexColor = (description) => z20.string().refine(isHexColor, { message: "Must be a 3- or 6-digit hex color such as #123 or #112233." }).optional().describe(description);
+var hexColor = (description) => z22.string().refine(isHexColor, { message: "Must be a 3- or 6-digit hex color such as #123 or #112233." }).optional().describe(description);
 var referralWidgetInputShape = {
   brand_color: hexColor("Primary accent color for the referral widget."),
   text_color: hexColor("Main referral-widget text color."),
   action_bg_color: hexColor("Referral-widget action button background color."),
   action_text_color: hexColor("Referral-widget action button text color."),
-  color_type: z20.enum(["template", "custom-solid", "custom-gradient"]).optional().describe("Color mode. This endpoint can select an existing template or gradient, but cannot define gradient stops."),
+  color_type: z22.enum(["template", "custom-solid", "custom-gradient"]).optional().describe("Color mode. This endpoint can select an existing template or gradient, but cannot define gradient stops."),
   custom_solid_color: hexColor("Custom solid background color used when color_type is custom-solid."),
-  theme_text_font: z20.string().trim().min(1).optional().describe("Referral-widget font family, for example Open+Sans."),
-  type_show_popup: z20.enum(POPUP_DISPLAY_TYPES).optional().describe("How the referral popup appears: automatically, as a bubble teaser, or not at all."),
-  is_auto_close_pop_up: z20.boolean().optional().describe("Whether an automatically shown referral popup closes itself."),
-  closing_pop_up_time: z20.number().int().min(1).optional().describe("Auto-close delay in seconds; must be a positive integer."),
-  frequency_show_popup: z20.number().int().min(1).max(10).optional().describe("Number of automatic popup displays, from 1 through 10. The admin UI stores this as an integer."),
-  is_show_subscribe_newsletter: z20.boolean().optional().describe("Show the newsletter subscription option in the referral popup."),
-  reason: z20.string().min(3).describe("Why the merchant wants the live referral widget changed."),
-  apply: z20.boolean().optional().describe("Set true only after the merchant has approved the dry-run preview.")
+  theme_text_font: z22.string().trim().min(1).optional().describe("Referral-widget font family, for example Open+Sans."),
+  type_show_popup: z22.enum(POPUP_DISPLAY_TYPES).optional().describe("How the referral popup appears: automatically, as a bubble teaser, or not at all."),
+  is_auto_close_pop_up: z22.boolean().optional().describe("Whether an automatically shown referral popup closes itself."),
+  closing_pop_up_time: z22.number().int().min(1).optional().describe("Auto-close delay in seconds; must be a positive integer."),
+  frequency_show_popup: z22.number().int().min(1).max(10).optional().describe("Number of automatic popup displays, from 1 through 10. The admin UI stores this as an integer."),
+  is_show_subscribe_newsletter: z22.boolean().optional().describe("Show the newsletter subscription option in the referral popup."),
+  reason: z22.string().min(3).describe("Why the merchant wants the live referral widget changed."),
+  apply: z22.boolean().optional().describe("Set true only after the merchant has approved the dry-run preview.")
 };
-var referralWidgetArgsSchema = z20.object(referralWidgetInputShape).strict();
+var referralWidgetArgsSchema = z22.object(referralWidgetInputShape).strict();
 function parseReferralWidgetArgs(input) {
   const parsed = referralWidgetArgsSchema.safeParse(input);
   if (parsed.success)
@@ -4640,7 +5171,7 @@ function registerReferralBrandingWriteTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/redeemInCart.js
-import { z as z21 } from "zod";
+import { z as z23 } from "zod";
 var PATH = "/shop/branding/redeem-inline";
 var styles = [
   "minimal",
@@ -4654,18 +5185,18 @@ var styles = [
 ];
 var fills = ["solid", "gradient-br", "gradient-r", "gradient-b", "radial"];
 var gradients = ["gradient-br", "gradient-r", "gradient-b", "radial"];
-var hex = z21.string().refine((value) => value === "" || isHexColor(value), "Use a hex color or an empty string to clear.");
-var https = z21.string().refine((value) => value === "" || (() => {
+var hex = z23.string().refine((value) => value === "" || isHexColor(value), "Use a hex color or an empty string to clear.");
+var https = z23.string().refine((value) => value === "" || (() => {
   try {
     return new URL(value).protocol === "https:";
   } catch {
     return false;
   }
 })(), "Use an HTTPS URL or an empty string to clear.");
-var fill = z21.object({
-  fillType: z21.enum(fills).optional(),
-  colors: z21.array(z21.string()).min(1).max(2).optional(),
-  lastGradient: z21.enum(gradients).optional()
+var fill = z23.object({
+  fillType: z23.enum(fills).optional(),
+  colors: z23.array(z23.string()).min(1).max(2).optional(),
+  lastGradient: z23.enum(gradients).optional()
 }).strict();
 var colorFields = [
   "text",
@@ -4680,12 +5211,12 @@ var colorFields = [
   "icon",
   "dropdownAccent"
 ];
-var colorsSchema = z21.object({
+var colorsSchema = z23.object({
   background: fill.optional(),
   button: fill.optional(),
   ...Object.fromEntries(colorFields.map((key) => [key, hex.optional()])),
-  buttonBorder: z21.string().optional(),
-  buttonHoverBorder: z21.string().optional()
+  buttonBorder: z23.string().optional(),
+  buttonHoverBorder: z23.string().optional()
 }).strict();
 var cssShapeFields = [
   "buttonHoverOpacity",
@@ -4708,20 +5239,20 @@ var cssShapeFields = [
   "buttonSweepEasing"
 ];
 var fonts = ["default", "inter", "space-grotesk", "playfair", "pt-serif", "nunito"];
-var shapeSchema = z21.object({
-  ...Object.fromEntries(cssShapeFields.map((key) => [key, z21.string().optional()])),
+var shapeSchema = z23.object({
+  ...Object.fromEntries(cssShapeFields.map((key) => [key, z23.string().optional()])),
   borderColor: hex.optional(),
   patternColor: hex.optional(),
   dividerColor: hex.optional(),
-  borderRadius: z21.enum(["none", "sharp", "soft", "rounded", "extra"]).optional(),
-  backgroundPattern: z21.enum(["none", "diagonal", "crosshatch", "grid", "column"]).optional(),
-  headingFont: z21.enum(fonts).optional(),
-  bodyFont: z21.enum(["", ...fonts]).optional(),
-  buttonFont: z21.enum(["", ...fonts]).optional(),
-  applyLoadingStyle: z21.enum(["spinner", "spinner-label", "dots"]).optional(),
-  buttonHoverEffect: z21.enum(["auto", "color", "fade", "lift", "none", "sweep"]).optional(),
-  boxShadow: z21.enum(["none", "small", "medium", "large", "hard"]).optional(),
-  iconName: z21.enum([
+  borderRadius: z23.enum(["none", "sharp", "soft", "rounded", "extra"]).optional(),
+  backgroundPattern: z23.enum(["none", "diagonal", "crosshatch", "grid", "column"]).optional(),
+  headingFont: z23.enum(fonts).optional(),
+  bodyFont: z23.enum(["", ...fonts]).optional(),
+  buttonFont: z23.enum(["", ...fonts]).optional(),
+  applyLoadingStyle: z23.enum(["spinner", "spinner-label", "dots"]).optional(),
+  buttonHoverEffect: z23.enum(["auto", "color", "fade", "lift", "none", "sweep"]).optional(),
+  boxShadow: z23.enum(["none", "small", "medium", "large", "hard"]).optional(),
+  iconName: z23.enum([
     "gift",
     "crown",
     "shopping-bag",
@@ -4734,9 +5265,9 @@ var shapeSchema = z21.object({
   ]).optional(),
   iconImage: https.optional(),
   backgroundImage: https.optional(),
-  backgroundImageOverlay: z21.number().min(0).max(100).optional(),
-  dividerWidth: z21.enum(["thin", "medium", "thick"]).optional(),
-  dividerStyle: z21.enum(["solid", "dashed", "dotted"]).optional()
+  backgroundImageOverlay: z23.number().min(0).max(100).optional(),
+  dividerWidth: z23.enum(["thin", "medium", "thick"]).optional(),
+  dividerStyle: z23.enum(["solid", "dashed", "dotted"]).optional()
 }).strict();
 var behaviorFields = {
   hide_for_guest: "hideForGuest",
@@ -4749,18 +5280,18 @@ var behaviorFields = {
   show_earn_back: "showEarnBack",
   has_reload_page: "hasReloadPage"
 };
-var behaviorInput = Object.fromEntries(Object.keys(behaviorFields).map((key) => [key, z21.boolean().optional()]));
-var common = { reason: z21.string().min(3), apply: z21.boolean().optional() };
-var behaviorArgs = z21.object({
+var behaviorInput = Object.fromEntries(Object.keys(behaviorFields).map((key) => [key, z23.boolean().optional()]));
+var common = { reason: z23.string().min(3), apply: z23.boolean().optional() };
+var behaviorArgs = z23.object({
   ...behaviorInput,
-  position_mode: z21.enum(["above_cart_summary", "custom"]).optional(),
-  custom_type: z21.enum(["snippet", "selector"]).optional(),
-  css_selector: z21.string().optional(),
+  position_mode: z23.enum(["above_cart_summary", "custom"]).optional(),
+  custom_type: z23.enum(["snippet", "selector"]).optional(),
+  css_selector: z23.string().optional(),
   ...common
 }).strict();
-var designArgs = z21.object({
-  style: z21.enum(styles).optional(),
-  set_active: z21.boolean().optional(),
+var designArgs = z23.object({
+  style: z23.enum(styles).optional(),
+  set_active: z23.boolean().optional(),
   colors: colorsSchema.optional(),
   shape: shapeSchema.optional(),
   ...common
@@ -4809,7 +5340,7 @@ function applied(changes, data) {
   });
 }
 async function getRedeemInCart(ctx, input) {
-  const args = parse(z21.object({ style: z21.enum(styles).optional() }).strict(), input);
+  const args = parse(z23.object({ style: z23.enum(styles).optional() }).strict(), input);
   const { data: raw } = await ctx.api.getData(PATH);
   const data = raw ?? {};
   const active = data.design?.activeStyle ?? "minimal";
@@ -4977,7 +5508,7 @@ function registerRedeemInCartReadTools(server, ctx) {
     name: "joy_get_redeem_in_cart",
     title: "Read Redeem-in-Cart settings",
     description: 'Read all effective behavior flags, position, active preset, its resolved colors and shape, and stored per-preset overrides. Admin "Redeem in cart V2" uses the internal V4 engine (redeemCartV4Ready); availability requires metafield publish and the app embed. Pass style to inspect one preset, including read-only legacy earnBack.show.',
-    inputSchema: { style: z21.enum(styles).optional() },
+    inputSchema: { style: z23.enum(styles).optional() },
     handler: (args) => getRedeemInCart(ctx, args)
   });
 }
@@ -5061,26 +5592,26 @@ function registerThemeSetupTools(server, ctx) {
 }
 
 // ../mcp-core/build/tools/imageUpload.js
-import { z as z22 } from "zod";
+import { z as z24 } from "zod";
 var imageUploadInputSchema = {
-  source_url: z22.string().url().optional().describe("Public URL of an already hosted image. Provide exactly one of source_url or data_url."),
-  data_url: z22.string().optional().describe("Image bytes as a data URL, for example an image the agent generated. Provide exactly one of data_url or source_url."),
-  filename: z22.string().min(1).max(200).optional().describe("Filename to use for the uploaded image."),
-  alt: z22.string().max(512).optional().describe("Merchant-provided alternative text for the image."),
-  reason: z22.string().min(3).describe("Why the merchant wants this image uploaded."),
-  apply: z22.boolean().optional().describe("Omit or set false for a dry run. Set true only after the merchant approves the preview.")
+  source_url: z24.string().url().optional().describe("Public URL of an already hosted image. Provide exactly one of source_url or data_url."),
+  data_url: z24.string().optional().describe("Image bytes as a data URL, for example an image the agent generated. Provide exactly one of data_url or source_url."),
+  filename: z24.string().min(1).max(200).optional().describe("Filename to use for the uploaded image."),
+  alt: z24.string().max(512).optional().describe("Merchant-provided alternative text for the image."),
+  reason: z24.string().min(3).describe("Why the merchant wants this image uploaded."),
+  apply: z24.boolean().optional().describe("Omit or set false for a dry run. Set true only after the merchant approves the preview.")
 };
 function imageUploadErrorGuidance(error) {
   if (!(error instanceof JoyApiError))
     return void 0;
   if (error.status === 400) {
-    return new JoyApiError("validation", "The image source was rejected (not an image, unsupported type, or a blocked URL). Do not retry the same input.", error.status);
+    return new JoyApiError("validation", "The image source was rejected (not an image, unsupported type, or a blocked URL). Do not retry the same input.", error.status, error.serverCode);
   }
   if (error.status === 413) {
-    return new JoyApiError("validation", "The image is too large; the upload cap is 20 MB. Resize or compress it before trying again.", error.status);
+    return new JoyApiError("validation", "The image is too large; the upload cap is 20 MB. Resize or compress it before trying again.", error.status, error.serverCode);
   }
   if (error.status === 502) {
-    return new JoyApiError("server", "Shopify rejected the upload or the file never went live. Safe to retry ONCE; if it fails again, stop and report the failure to the merchant.", error.status);
+    return new JoyApiError("server", "Shopify rejected the upload or the file never went live. Safe to retry ONCE; if it fails again, stop and report the failure to the merchant.", error.status, error.serverCode);
   }
   return void 0;
 }
@@ -5113,14 +5644,14 @@ function registerImageUploadTools(server, ctx) {
 }
 
 // ../mcp-core/build/prompts.js
-import { z as z23 } from "zod";
+import { z as z25 } 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: z23.string().describe("Customer's email address"),
-      order_number: z23.string().optional().describe("Order name/number the customer says earned nothing, e.g. #1234")
+      email: z25.string().describe("Customer's email address"),
+      order_number: z25.string().optional().describe("Order name/number the customer says earned nothing, e.g. #1234")
     }
   }, ({ email, order_number }) => ({
     messages: [
@@ -5147,7 +5678,7 @@ function registerAllPrompts(server) {
     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: z23.string().optional().describe("Reporting period, e.g. 'last 30 days', 'last month', 'this quarter'. Defaults to last 30 days.")
+      period: z25.string().optional().describe("Reporting period, e.g. 'last 30 days', 'last month', 'this quarter'. Defaults to last 30 days.")
     }
   }, ({ period }) => ({
     messages: [
@@ -5178,7 +5709,7 @@ function registerAllPrompts(server) {
     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: z23.string().describe("Email of the member to investigate")
+      email: z25.string().describe("Email of the member to investigate")
     }
   }, ({ email }) => ({
     messages: [
@@ -5205,8 +5736,8 @@ function registerAllPrompts(server) {
     title: "Set up a loyalty program safely",
     description: "Guided loyalty-program setup: inspect the current configuration, propose a minimal program, and make each approved configuration change one at a time.",
     argsSchema: {
-      business_type: z23.string().optional().describe("Business type, e.g. 'fashion' or 'coffee shop'."),
-      goal: z23.string().optional().describe("Primary loyalty goal, e.g. 'increase repeat purchases'.")
+      business_type: z25.string().optional().describe("Business type, e.g. 'fashion' or 'coffee shop'."),
+      goal: z25.string().optional().describe("Primary loyalty goal, e.g. 'increase repeat purchases'.")
     }
   }, ({ business_type, goal }) => ({
     messages: [
@@ -5231,7 +5762,7 @@ function registerAllPrompts(server) {
     title: "Apply storefront branding to a widget draft",
     description: "Guided widget-branding workflow: scan the storefront, explain the detected design, get approval, and save the approved changes to the V4 draft for the merchant to review and publish manually.",
     argsSchema: {
-      preferences: z23.string().optional().describe("Optional brand preferences or constraints, e.g. 'keep the current heading font' or 'use a softer button color'.")
+      preferences: z25.string().optional().describe("Optional brand preferences or constraints, e.g. 'keep the current heading font' or 'use a softer button color'.")
     }
   }, ({ preferences }) => ({
     messages: [
@@ -5258,7 +5789,7 @@ function registerAllPrompts(server) {
     title: "Set up the storefront loyalty widget",
     description: "Guided theme-setup workflow: audit the live theme, explain each missing Joy embed or block, and hand the merchant server-provided deep links to finish setup manually.",
     argsSchema: {
-      focus: z23.string().optional().describe("Optional setup focus, e.g. 'loyalty widget', 'points calculator', or 'loyalty page'.")
+      focus: z25.string().optional().describe("Optional setup focus, e.g. 'loyalty widget', 'points calculator', or 'loyalty page'.")
     }
   }, ({ focus }) => ({
     messages: [
@@ -5298,6 +5829,8 @@ function registerAllTools(server, ctx) {
   registerTierUpgradeTools(server, ctx);
   registerLoyaltyPageTools(server, ctx);
   registerLoyaltyPageTextTools(server, ctx);
+  registerLoyaltyHubTools(server, ctx);
+  registerLoyaltyHubTextTools(server, ctx);
   registerThemeSetupTools(server, ctx);
   registerBrandingReadTools(server, ctx);
   registerWidgetFieldReadTools(server, ctx);
@@ -5310,7 +5843,9 @@ function registerAllTools(server, ctx) {
     registerAnalyticsWriteTools(server, ctx);
     registerLoyaltyPageWriteTools(server, ctx);
     registerLoyaltyPageTextWriteTools(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.");
+    registerLoyaltyHubWriteTools(server, ctx);
+    registerLoyaltyHubTextWriteTools(server, ctx);
+    log.info("write tools ENABLED (award/deduct/adjust/redeem/set-tier/refund-coupon/create-referral-invite/enable-analytics-v2/loyalty-hub-design/loyalty-hub-text). 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.");
   }
   if (ctx.config.configWritesEnabled) {
     registerProgramConfigTools(server, ctx);
@@ -5326,19 +5861,486 @@ function registerAllTools(server, ctx) {
   }
 }
 
+// ../mcp-core/build/telemetry/knownTools.js
+var KNOWN_TOOLS = Object.freeze({
+  joy_add_translation_language: "config_write",
+  joy_adjust_points: "write",
+  joy_award_points: "write",
+  joy_check_theme_setup: "read",
+  joy_configure_earning_program: "config_write",
+  joy_configure_redeem_in_cart: "config_write",
+  joy_configure_redeem_in_cart_design: "config_write",
+  joy_configure_redemption_program: "config_write",
+  joy_configure_referral_program: "config_write",
+  joy_configure_referral_widget: "config_write",
+  joy_configure_shop_settings: "config_write",
+  joy_configure_tier: "config_write",
+  joy_configure_tier_perks: "config_write",
+  joy_configure_tier_reward: "config_write",
+  joy_configure_tier_settings: "config_write",
+  joy_configure_widget_draft: "config_write",
+  joy_create_referral_invite: "write",
+  joy_deduct_points: "write",
+  joy_enable_analytics_v2: "write",
+  joy_explain_order_points: "read",
+  joy_find_member: "read",
+  joy_get_analytics_report: "read",
+  joy_get_loyalty_health_check: "read",
+  joy_get_loyalty_hub_design: "read",
+  joy_get_loyalty_hub_text: "read",
+  joy_get_loyalty_overview: "read",
+  joy_get_loyalty_page_design: "read",
+  joy_get_loyalty_page_text: "read",
+  joy_get_loyalty_revenue_report: "read",
+  joy_get_member_activity: "read",
+  joy_get_member_referrals: "read",
+  joy_get_member_rewards: "read",
+  joy_get_member_store_credit: "read",
+  joy_get_redeem_in_cart: "read",
+  joy_get_referral_performance: "read",
+  joy_get_referral_program: "read",
+  joy_get_retention_risk_members: "read",
+  joy_get_tier_performance_breakdown: "read",
+  joy_get_tier_upgrade_candidates: "read",
+  joy_get_widget_fields: "read",
+  joy_investigate_member_risk: "read",
+  joy_list_activities: "read",
+  joy_list_earning_rules: "read",
+  joy_list_members: "read",
+  joy_list_redemption_rules: "read",
+  joy_list_tiers: "read",
+  joy_redeem_reward: "write",
+  joy_refund_coupon: "write",
+  joy_revert_loyalty_hub_design: "write",
+  joy_revert_loyalty_hub_text: "write",
+  joy_revert_loyalty_page_design: "write",
+  joy_scan_brand_design: "read",
+  joy_set_member_tier: "write",
+  joy_set_widget_fields: "config_write",
+  joy_update_loyalty_hub_design: "write",
+  joy_update_loyalty_hub_text: "write",
+  joy_update_loyalty_page_design: "write",
+  joy_update_loyalty_page_text: "write",
+  joy_upload_image: "config_write"
+});
+
+// ../mcp-core/build/telemetry/recorder.js
+import { randomUUID as randomUUID2 } from "node:crypto";
+var fields = TELEMETRY_SCHEMA.events["mcp.tool_call"].fields;
+var toMillis = (value) => Math.min(36e5, Math.max(0, Math.round(value)));
+function classify(record, response, { exposed, known = KNOWN_TOOLS }) {
+  let outcome = record.outcome ?? "internal_error";
+  let error_kind = record.error_kind;
+  if ("error" in response) {
+    outcome = "internal_error";
+    error_kind = "jsonrpc_error";
+  } else if (!record.entered && "result" in response && response.result.isError) {
+    outcome = "rejected";
+    error_kind = exposed.has(record.tool) ? "invalid_input" : Object.hasOwn(known, record.tool) ? "tool_not_exposed" : "unknown_tool";
+  } else if (!record.outcome) {
+    error_kind = "unclassified";
+  }
+  const result = "result" in response ? response.result : void 0;
+  const content = Array.isArray(result?.content) ? result.content : [];
+  const result_bytes = content.reduce((sum, item) => sum + (typeof item?.text === "string" ? Buffer.byteLength(item.text, "utf8") : 0), 0);
+  return {
+    tool_kind: Object.hasOwn(known, record.tool) ? known[record.tool] : "unknown",
+    outcome,
+    ...outcome !== "success" && error_kind ? { error_kind } : {},
+    ...outcome === "tool_error" && record.error_code ? { error_code: record.error_code } : {},
+    ...outcome === "tool_error" && record.http_status ? { http_status: record.http_status } : {},
+    result_bytes: Math.min(1e9, result_bytes)
+  };
+}
+function createRecorder({ sink, base: inputBase, receivedAt, sweepTtlMs, now = performance.now.bind(performance) }) {
+  const base = {};
+  telemetrySafe("base", () => {
+    for (const [key, value] of Object.entries(inputBase)) {
+      const clean = sanitizeString(TELEMETRY_SCHEMA, "mcp.session_start", key, value);
+      if (clean !== void 0)
+        base[key] = clean;
+    }
+  });
+  const pending = /* @__PURE__ */ new Map();
+  const exposed = /* @__PURE__ */ new Set();
+  const instrumented = /* @__PURE__ */ new WeakSet();
+  let closed = false;
+  let initialized = false;
+  function emit(event) {
+    const transport = inputBase.transport;
+    const checked = validateEvent(TELEMETRY_SCHEMA, event, { mode: transport === "stdio" ? "client" : "full", transport });
+    if (!checked.ok) {
+      reportOnce(`invalid ${checked.errors[0]}`);
+      return;
+    }
+    sink.emit(checked.event);
+  }
+  function finish(id, record, response) {
+    if (record.closed || pending.get(id) !== record)
+      return;
+    record.closed = true;
+    pending.delete(id);
+    const elapsed = now();
+    const duration_ms = toMillis(elapsed - record.t0);
+    const busy = record.api_inflight ? elapsed - (record.api_busy_since ?? elapsed) : 0;
+    emit({
+      ...base,
+      event: "mcp.tool_call",
+      schema_version: 1,
+      event_id: randomUUID2(),
+      call_id: record.call_id,
+      tool: record.tool,
+      ...classify(record, response, { exposed }),
+      duration_ms,
+      ...base.transport === "remote" && receivedAt !== void 0 ? { pre_ms: toMillis(record.t0 - receivedAt) } : {},
+      api_calls: Math.min(1e4, record.api_calls),
+      api_ms: Math.min(duration_ms, toMillis(record.api_ms_acc + busy))
+    });
+  }
+  function cancel(id, record, outcome, kind) {
+    record.outcome = outcome;
+    record.error_kind = kind;
+    finish(id, record, { jsonrpc: "2.0", id, result: {} });
+  }
+  function buildHeaders(call_id, tool) {
+    const values = { call_id, tool, ...base };
+    const mapping = {
+      call_id: "Call-Id",
+      tool: "Tool",
+      transport: "Transport",
+      server_version: "Version",
+      ...base.transport === "stdio" ? { mcp_client_name: "Client", session_id: "Session" } : {}
+    };
+    const result = {};
+    for (const [field, suffix] of Object.entries(mapping)) {
+      const value = sanitizeString(TELEMETRY_SCHEMA, "mcp.tool_call", field, values[field]);
+      if (value !== void 0)
+        result[`X-Joy-Mcp-${suffix}`] = value;
+    }
+    return Object.freeze(result);
+  }
+  const timer = sweepTtlMs === void 0 ? void 0 : setInterval(() => {
+    for (const [id, record] of pending) {
+      telemetrySafe("sweep", () => {
+        if (now() - record.t0 >= sweepTtlMs)
+          cancel(id, record, "cancelled", "no_response");
+      });
+    }
+  }, 6e4);
+  timer?.unref();
+  return {
+    expose(name) {
+      telemetrySafe("expose", () => {
+        if (sanitizeString(TELEMETRY_SCHEMA, "mcp.tool_call", "tool", name))
+          exposed.add(name);
+      });
+    },
+    instrumentTransport(transport) {
+      telemetrySafe("instrument", () => {
+        if (instrumented.has(transport))
+          return;
+        instrumented.add(transport);
+        if (!transport.onmessage)
+          reportOnce("instrumentTransport called before connect");
+        const onmessage = transport.onmessage;
+        const send = transport.send;
+        transport.onmessage = function(message, extra) {
+          const record = telemetrySafe("receive", () => {
+            if (closed || !("method" in message))
+              return;
+            const params = message.params;
+            if (message.method === "initialize" && !(base.transport === "stdio" && initialized)) {
+              initialized = true;
+              const info = params?.clientInfo;
+              const session = {
+                ...base,
+                event: "mcp.session_start",
+                schema_version: 1,
+                event_id: randomUUID2(),
+                tools_exposed: exposed.size
+              };
+              const capabilities = Object.keys(params?.capabilities ?? {}).filter((key) => /^[a-z][a-zA-Z0-9_]{0,31}$/.test(key)).sort().slice(0, 10).join(",");
+              for (const [key, value] of Object.entries({
+                mcp_client_name: info?.name,
+                mcp_client_version: info?.version,
+                protocol_version: params?.protocolVersion,
+                client_capabilities: capabilities
+              })) {
+                const clean = sanitizeString(TELEMETRY_SCHEMA, "mcp.session_start", key, value);
+                if (clean === void 0)
+                  continue;
+                session[key] = clean;
+                if (base.transport === "stdio" && fields[key])
+                  base[key] = clean;
+              }
+              emit(session);
+            }
+            if (message.method === "notifications/cancelled" && base.transport === "stdio") {
+              const id = params?.requestId;
+              const previous2 = pending.get(id);
+              if (previous2)
+                cancel(id, previous2, "cancelled", "client_cancelled");
+            }
+            if (message.method !== "tools/call" || !("id" in message))
+              return;
+            const previous = pending.get(message.id);
+            if (previous)
+              telemetrySafe("duplicate", () => cancel(message.id, previous, "internal_error", "duplicate_request_id"));
+            const tool = sanitizeString(TELEMETRY_SCHEMA, "mcp.tool_call", "tool", params?.name) ?? "invalid_name";
+            const call_id = randomUUID2();
+            const record2 = {
+              call_id,
+              tool,
+              t0: now(),
+              entered: false,
+              closed: false,
+              api_calls: 0,
+              api_inflight: 0,
+              api_ms_acc: 0,
+              headers: buildHeaders(call_id, tool),
+              now
+            };
+            pending.set(message.id, record2);
+            return record2;
+          });
+          if (record)
+            return als.run(record, () => onmessage?.call(this, message, extra));
+          return onmessage?.call(this, message, extra);
+        };
+        transport.send = function(...args) {
+          telemetrySafe("send", () => {
+            const message = args[0];
+            if (!("id" in message) || message.id === void 0 || !("result" in message || "error" in message))
+              return;
+            const record = currentCall() ?? pending.get(message.id);
+            if (record)
+              finish(message.id, record, message);
+          });
+          return send.apply(this, args);
+        };
+      });
+    },
+    close() {
+      closed = true;
+      if (timer)
+        clearInterval(timer);
+      for (const [id, record] of pending) {
+        telemetrySafe("close", () => cancel(id, record, "cancelled", "no_response"));
+      }
+    }
+  };
+}
+
+// ../mcp-core/build/telemetry/sinks.js
+var noopSink = { emit() {
+} };
+function createRelaySink({ apiBaseUrl, authHeaders: authHeaders2, fetchImpl = fetch, now = Date.now, timers = globalThis }) {
+  const queue = [];
+  let disabled = false;
+  let dueAt = 0;
+  let timer;
+  let active;
+  let flushing;
+  const headers = { "Content-Type": "application/json" };
+  telemetrySafe("relay_headers", () => {
+    for (const [key, value] of Object.entries(authHeaders2)) {
+      if (["x-joy-loyalty-app-key", "x-joy-loyalty-secret-key", "x-joy-private-bot-key"].includes(key.toLowerCase()))
+        headers[key] = value;
+    }
+  });
+  function clearTimer() {
+    if (timer)
+      timers.clearTimeout(timer);
+    timer = void 0;
+  }
+  function schedule() {
+    if (disabled || flushing || queue.length === 0)
+      return;
+    if (!active && queue.length >= 20) {
+      startBatch();
+      return;
+    }
+    if (timer)
+      return;
+    timer = timers.setTimeout(() => {
+      timer = void 0;
+      telemetrySafe("relay_timer", () => {
+        if (!active)
+          startBatch();
+      });
+    }, Math.max(0, dueAt - now()));
+    timer.unref();
+  }
+  function startBatch() {
+    if (active)
+      return active.done;
+    if (disabled || queue.length === 0)
+      return Promise.resolve();
+    clearTimer();
+    const events = queue.splice(0, 50);
+    const controller = new AbortController();
+    let release;
+    const cancelled = new Promise((resolve) => {
+      release = resolve;
+    });
+    const abort = () => {
+      controller.abort();
+      release();
+    };
+    const timeout = timers.setTimeout(abort, 15e3);
+    timeout.unref();
+    const request = Promise.resolve().then(async () => {
+      if (controller.signal.aborted)
+        return;
+      const response = await fetchImpl(`${apiBaseUrl.replace(/\/$/, "")}/rest_api/v2/internal/mcp-telemetry`, {
+        method: "POST",
+        redirect: "error",
+        headers,
+        body: JSON.stringify({ schema_version: 1, events }),
+        signal: controller.signal
+      });
+      let dailyQuotaExceeded = false;
+      if (response.status === 429) {
+        const body = await response.json().catch(() => void 0);
+        dailyQuotaExceeded = body !== null && typeof body === "object" && "error" in body && body.error === "daily_quota_exceeded";
+      }
+      if ([401, 403, 404, 410].includes(response.status) || dailyQuotaExceeded) {
+        disabled = true;
+        queue.length = 0;
+        clearTimer();
+      }
+      if (!response.ok)
+        throw new Error("relay rejected");
+      await response.body?.cancel();
+    }).catch(() => {
+      telemetrySafe("relay_request", () => {
+        throw new Error("relay request failed");
+      });
+    });
+    const done = Promise.race([request, cancelled]).then(() => {
+      timers.clearTimeout(timeout);
+      active = void 0;
+      telemetrySafe("relay_schedule", schedule);
+    });
+    active = { done, abort };
+    return done;
+  }
+  async function flush(deadlineMs) {
+    clearTimer();
+    const deadline = now() + Math.max(0, deadlineMs);
+    let expired = false;
+    let release;
+    const timeout = new Promise((resolve) => {
+      release = resolve;
+    });
+    const end = timers.setTimeout(() => {
+      expired = true;
+      queue.length = 0;
+      active?.abort();
+      release();
+    }, Math.max(0, deadlineMs));
+    try {
+      while (!expired && !disabled && (active || queue.length)) {
+        if (now() >= deadline) {
+          queue.length = 0;
+          active?.abort();
+          break;
+        }
+        await Promise.race([active?.done ?? startBatch(), timeout]);
+      }
+    } finally {
+      timers.clearTimeout(end);
+    }
+  }
+  return {
+    get disabled() {
+      return disabled;
+    },
+    emit(event) {
+      telemetrySafe("relay_emit", () => {
+        if (disabled)
+          return;
+        if (!TELEMETRY_SCHEMA.ingest_events.includes(event.event))
+          return;
+        const fields2 = TELEMETRY_SCHEMA.events[event.event].fields;
+        const client = Object.fromEntries(Object.entries(event).filter(([key]) => !fields2[key]?.server_stamped));
+        const checked = validateEvent(TELEMETRY_SCHEMA, client, { mode: "client", transport: "stdio" });
+        if (!checked.ok)
+          return;
+        if (queue.length >= 200)
+          queue.shift();
+        if (queue.length === 0)
+          dueAt = now() + 1e4;
+        queue.push(checked.event);
+        schedule();
+      });
+    },
+    flushNow(deadlineMs) {
+      if (flushing)
+        return flushing;
+      flushing = Promise.resolve().then(() => flush(deadlineMs)).catch(() => {
+        telemetrySafe("relay_flush", () => {
+          throw new Error("relay flush failed");
+        });
+      }).finally(() => {
+        flushing = void 0;
+      });
+      return flushing;
+    }
+  };
+}
+
 // 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 mode = telemetryMode();
+  const relay = mode === "full" ? createRelaySink({ apiBaseUrl: config.apiBaseUrl, authHeaders: authHeaders(config) }) : void 0;
+  const telemetry = mode === "off" ? void 0 : createRecorder({
+    sink: relay ?? noopSink,
+    base: { transport: "stdio", server_version: version, session_id: randomUUID3() },
+    sweepTtlMs: 6e5
+  });
+  if (relay) {
+    let exiting = false;
+    let exitWork;
+    const shutdown = async (signal = false) => {
+      if (!exiting) {
+        exiting = true;
+        telemetry?.close();
+        exitWork = relay.flushNow(2e3);
+      }
+      if (signal) {
+        await exitWork;
+        process.exit(0);
+      }
+    };
+    process.stdin.on("end", () => {
+      void shutdown();
+    });
+    process.stdin.on("close", () => {
+      void shutdown();
+    });
+    process.on("beforeExit", () => {
+      void shutdown();
+    });
+    process.on("SIGINT", () => {
+      void shutdown(true);
+    });
+    process.on("SIGTERM", () => {
+      void shutdown(true);
+    });
+  }
   const server = new McpServer({ name: "joy-loyalty", version });
-  registerAllTools(server, { api, config, cache: new TtlCache() });
+  registerAllTools(server, { api, config, cache: new TtlCache(), telemetry });
   registerAllPrompts(server);
   const transport = new StdioServerTransport();
   await server.connect(transport);
+  telemetry?.instrumentTransport(transport);
   log.info(
-    `joy-mcp v${version} ready \u2014 mode=${config.mode}, tools=${config.writesEnabled ? "read+write" : "read-only"}, api=${config.apiBaseUrl}`
+    `joy-mcp v${version} ready \u2014 mode=${config.mode}, tools=${config.writesEnabled ? "read+write" : "read-only"}, api=${config.apiBaseUrl}, telemetry=${mode}`
   );
 }
 main().catch((error) => {