zola-mcp 1.4.3 → 1.5.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Zola wedding planning tools for Claude Code",
-    "version": "1.4.3"
+    "version": "1.5.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Zola",
       "source": "./",
       "description": "Zola wedding planning tools for Claude — vendors, budget, guests, seating, events, registry, inquiries, and more via MCP",
-      "version": "1.4.3",
+      "version": "1.5.0",
       "author": {
         "name": "Chris Chall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "zola",
   "displayName": "Zola",
-  "version": "1.4.3",
+  "version": "1.5.0",
   "description": "Zola wedding planning tools for Claude — vendors, budget, guests, seating, events, registry, inquiries, and more via MCP",
   "author": {
     "name": "Chris Chall",

package/dist/bundle.js

@@ -34728,8 +34728,12 @@ var API_KEY_RE = new RegExp([
   // webhook signing secret (Stripe-style)
 ].map((p) => `\\b${p}`).join("|"), "g");
 var QUERY_SECRET_RE = /([?&](?:access_token|refresh_token|client_secret|api_?key|signature|token|key|sig)=)[^&#\s"'<>`]+/gi;
+var AWS_SIGV4_RE = /([?&]X-Amz-(?:Signature|Security-Token|Credential)=)[^&#\s"'<>`]+/gi;
+var JSON_SECRET_KEYS = "access_token|refresh_token|client_secret|api_?key|password|passwd|secret|token";
+var JSON_SECRET_DQ_RE = new RegExp(`("(?:${JSON_SECRET_KEYS})"\\s*:\\s*")[^"]*(")`, "gi");
+var JSON_SECRET_SQ_RE = new RegExp(`('(?:${JSON_SECRET_KEYS})'\\s*:\\s*')[^']*(')`, "gi");
 function redactSecrets(text) {
-  return text.replace(BEARER_RE, "$1[REDACTED]").replace(BASIC_AUTH_RE, "$1[REDACTED]").replace(SET_COOKIE_RE, "$1$2=[REDACTED]").replace(COOKIE_HEADER_RE, (_m, prefix, pairs) => `${prefix}${pairs.replace(/=[^;,\s]*/g, "=[REDACTED]")}`).replace(API_KEY_RE, "[REDACTED]").replace(QUERY_SECRET_RE, "$1[REDACTED]").replace(JWT_RE, "[REDACTED]");
+  return text.replace(BEARER_RE, "$1[REDACTED]").replace(BASIC_AUTH_RE, "$1[REDACTED]").replace(SET_COOKIE_RE, "$1$2=[REDACTED]").replace(COOKIE_HEADER_RE, (_m, prefix, pairs) => `${prefix}${pairs.replace(/=[^;,\s]*/g, "=[REDACTED]")}`).replace(API_KEY_RE, "[REDACTED]").replace(QUERY_SECRET_RE, "$1[REDACTED]").replace(AWS_SIGV4_RE, "$1[REDACTED]").replace(JSON_SECRET_DQ_RE, "$1[REDACTED]$2").replace(JSON_SECRET_SQ_RE, "$1[REDACTED]$2").replace(JWT_RE, "[REDACTED]");
 }
 function truncateErrorMessage(text, max = DEFAULT_ERROR_MESSAGE_MAX) {
   const str = text === null || text === void 0 ? "" : String(text);
@@ -34865,6 +34869,41 @@ var pageSchema = {
   page_size: external_exports.number().int().min(1).max(200).default(50).describe("Number of items per page (1-200).")
 };
 
+// node_modules/@chrischall/mcp-utils/dist/auth/cached-token.js
+function createCachedTokenSource(opts) {
+  const now = opts.now ?? Date.now;
+  const bufferMs = opts.bufferMs ?? 6e4;
+  const defaultTtlMs = opts.defaultTtlMs ?? 36e5;
+  let cached2 = null;
+  let inFlight = null;
+  const expiryOf = (minted) => {
+    if (minted.expiresAt !== void 0) {
+      return minted.expiresAt instanceof Date ? minted.expiresAt.getTime() : minted.expiresAt;
+    }
+    return now() + (minted.ttlMs ?? defaultTtlMs);
+  };
+  return {
+    getToken() {
+      if (cached2 && cached2.expiresAt - bufferMs > now())
+        return Promise.resolve(cached2.token);
+      if (inFlight)
+        return inFlight;
+      const p = opts.mint().then((minted) => {
+        cached2 = { token: minted.token, expiresAt: expiryOf(minted) };
+        return minted.token;
+      }).finally(() => {
+        if (inFlight === p)
+          inFlight = null;
+      });
+      inFlight = p;
+      return p;
+    },
+    invalidate() {
+      cached2 = null;
+    }
+  };
+}
+
 // node_modules/@chrischall/mcp-utils/dist/auth/index.js
 function bridgeDownHintOf(err) {
   if (err instanceof Error && err.name === "FetchproxyBridgeDownError") {
@@ -34921,6 +34960,7 @@ var KNOWN_CAPABILITIES = /* @__PURE__ */ new Set([
   "capture_request_header",
   "capture_redirect",
   "read_indexed_db",
+  "read_dom",
   "download"
 ]);
 
@@ -35222,6 +35262,44 @@ function assertIndexedDbScopesArray(value, label) {
     }
   }
 }
+var DOM_SELECTOR_RE = /^[^-]{1,512}$/;
+var DOM_ATTRIBUTE_RE = /^[A-Za-z_:][A-Za-z0-9_:.\-]{0,127}$/;
+function assertDomSelectorsArray(value, label) {
+  if (!Array.isArray(value)) {
+    throw new ProtocolError(`${label}: expected array, got ${typeof value}`);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (let i = 0; i < value.length; i++) {
+    const entry = value[i];
+    assertObject(entry, `${label}[${i}]`);
+    if (entry.name === void 0) {
+      throw new ProtocolError(`${label}[${i}].name: missing`);
+    }
+    if (entry.selector === void 0) {
+      throw new ProtocolError(`${label}[${i}].selector: missing`);
+    }
+    if (typeof entry.name !== "string" || !SCOPE_KEY_RE.test(entry.name)) {
+      throw new ProtocolError(`${label}[${i}].name: invalid ${JSON.stringify(entry.name)}`);
+    }
+    if (typeof entry.selector !== "string" || !DOM_SELECTOR_RE.test(entry.selector)) {
+      throw new ProtocolError(`${label}[${i}].selector: invalid ${JSON.stringify(entry.selector)}`);
+    }
+    if (entry.attribute !== void 0) {
+      if (typeof entry.attribute !== "string" || !DOM_ATTRIBUTE_RE.test(entry.attribute)) {
+        throw new ProtocolError(`${label}[${i}].attribute: invalid ${JSON.stringify(entry.attribute)}`);
+      }
+    }
+    if (seen.has(entry.name)) {
+      throw new ProtocolError(`${label}: duplicate name ${JSON.stringify(entry.name)}`);
+    }
+    seen.add(entry.name);
+    for (const k of Object.keys(entry)) {
+      if (k !== "name" && k !== "selector" && k !== "attribute") {
+        throw new ProtocolError(`${label}[${i}]: unexpected field ${JSON.stringify(k)}`);
+      }
+    }
+  }
+}
 function validateFrame(raw) {
   assertObject(raw, "frame");
   const t = raw.type;
@@ -35297,6 +35375,9 @@ function validateHello(raw) {
     if (raw.sessionStoragePointers !== void 0) {
       assertStoragePointersArray(raw.sessionStoragePointers, "hello.sessionStoragePointers", raw.sessionStorageKeys);
     }
+    if (raw.domSelectors !== void 0) {
+      assertDomSelectorsArray(raw.domSelectors, "hello.domSelectors");
+    }
     assertBase64(raw.identityX25519Pub, "hello.identityX25519Pub");
     assertBase64(raw.identityEd25519Pub, "hello.identityEd25519Pub");
     assertBase64(raw.sessionNonce, "hello.sessionNonce");
@@ -35531,6 +35612,21 @@ function validateInnerRequest(raw) {
     }
     return raw;
   }
+  if (raw.op === "read_dom") {
+    assertObject(raw.init, "inner.init");
+    if (raw.init.origin === void 0)
+      throw new ProtocolError("inner.init.origin: missing");
+    if (raw.init.names === void 0)
+      throw new ProtocolError("inner.init.names: missing");
+    assertHttpsOriginOnly(raw.init.origin, "inner.init.origin");
+    assertNonEmptyKeyArray(raw.init.names, "inner.init.names");
+    for (const k of Object.keys(raw.init)) {
+      if (k !== "origin" && k !== "names") {
+        throw new ProtocolError(`inner.init: unexpected field ${JSON.stringify(k)} on read_dom`);
+      }
+    }
+    return raw;
+  }
   if (raw.op === "download") {
     assertObject(raw.init, "inner.init");
     if (raw.init.url === void 0) {
@@ -35556,7 +35652,7 @@ function validateInnerRequest(raw) {
     }
     return raw;
   }
-  throw new ProtocolError(`inner.op: must be one of "fetch", "read_cookies", "read_local_storage", "read_session_storage", "capture_request_header", "capture_redirect", "read_indexed_db", "download"; got ${JSON.stringify(raw.op)}`);
+  throw new ProtocolError(`inner.op: must be one of "fetch", "read_cookies", "read_local_storage", "read_session_storage", "capture_request_header", "capture_redirect", "read_indexed_db", "read_dom", "download"; got ${JSON.stringify(raw.op)}`);
 }
 function assertNonEmptyKeyArray(value, label) {
   if (!Array.isArray(value)) {
@@ -35641,6 +35737,13 @@ function validateInnerResponse(raw) {
       assertObject(raw.values, "inner.values");
       return raw;
     }
+    if (op === "read_dom") {
+      if (raw.values === void 0) {
+        throw new ProtocolError("inner.values: missing on read_dom response");
+      }
+      assertStringMap(raw.values, "inner.values");
+      return raw;
+    }
     if (op === "download") {
       assertObject(raw.value, "inner.value");
       assertString(raw.value.path, "inner.value.path");
@@ -35980,6 +36083,13 @@ async function buildServerHello(opts) {
       jsonPointer: d.jsonPointer
     }));
   }
+  if (opts.domSelectors && opts.domSelectors.length > 0) {
+    hello.domSelectors = opts.domSelectors.map((d) => ({
+      name: d.name,
+      selector: d.selector,
+      ...d.attribute !== void 0 ? { attribute: d.attribute } : {}
+    }));
+  }
   return hello;
 }
 
@@ -36069,7 +36179,8 @@ async function startHost(opts) {
     captureHeaders: opts.ownCaptureHeaders,
     indexedDbScopes: opts.ownIndexedDbScopes,
     localStoragePointers: opts.ownLocalStoragePointers,
-    sessionStoragePointers: opts.ownSessionStoragePointers
+    sessionStoragePointers: opts.ownSessionStoragePointers,
+    domSelectors: opts.ownDomSelectors
   });
   const ownSessionNonce = fromB64(ownHello.sessionNonce);
   let extensionWs = null;
@@ -36304,6 +36415,7 @@ async function startPeer(opts) {
     sessionStorageKeys: opts.sessionStorageKeys,
     captureHeaders: opts.captureHeaders,
     indexedDbScopes: opts.indexedDbScopes,
+    domSelectors: opts.domSelectors,
     localStoragePointers: opts.localStoragePointers,
     sessionStoragePointers: opts.sessionStoragePointers
   });
@@ -36711,6 +36823,11 @@ var FetchproxyServer = class {
         key: d.key,
         jsonPointer: d.jsonPointer
       })),
+      domSelectors: (opts.domSelectors ?? []).map((d) => ({
+        name: d.name,
+        selector: d.selector,
+        ...d.attribute !== void 0 ? { attribute: d.attribute } : {}
+      })),
       // 0.8.0+: timer + lazy-revive default to ON. Every realty MCP
       // adapter was about to set these to the same numbers anyway; the
       // back-door is `0` (explicit opt-out) if a caller genuinely wants
@@ -36831,6 +36948,7 @@ var FetchproxyServer = class {
         ownIndexedDbScopes: this.opts.indexedDbScopes,
         ownLocalStoragePointers: this.opts.localStoragePointers,
         ownSessionStoragePointers: this.opts.sessionStoragePointers,
+        ownDomSelectors: this.opts.domSelectors,
         onPairCode: this.opts.onPairCode
       });
       this.hostHandle.onOwnInner((inner) => this.onInner(inner));
@@ -36858,7 +36976,8 @@ var FetchproxyServer = class {
         captureHeaders: this.opts.captureHeaders,
         indexedDbScopes: this.opts.indexedDbScopes,
         localStoragePointers: this.opts.localStoragePointers,
-        sessionStoragePointers: this.opts.sessionStoragePointers
+        sessionStoragePointers: this.opts.sessionStoragePointers,
+        domSelectors: this.opts.domSelectors
       });
       this.peerHandle.onInner((inner) => this.onInner(inner));
       this.peerHandle.onRenegotiate(() => {
@@ -37833,6 +37952,46 @@ var FetchproxyServer = class {
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingIdb, id, origin);
   }
+  /**
+   * 1.4.0+: read declared DOM values from the user's signed-in tab.
+   * Requires `'read_dom'` in capabilities AND every requested `name` to
+   * match a declared `domSelectors` entry. The extension reads each
+   * declared selector from the matched tab's DOM (isolated-world
+   * `querySelector`, value or attribute) — no page-JS execution.
+   *
+   * Returns a `Record<string, string>` of `name → value`, with names
+   * whose element (or attribute) was absent omitted. Throws
+   * `FetchproxyProtocolError` on bridge failures and a plain `Error` on
+   * developer mistakes (undeclared capability, undeclared name).
+   */
+  async readDom(opts) {
+    if (!this.opts.capabilities.includes("read_dom")) {
+      throw new Error('FetchproxyServer.readDom(): MCP did not declare "read_dom" in capabilities');
+    }
+    await this.ensureConnected();
+    this.throwIfPendingPair();
+    if (!Array.isArray(opts.names) || opts.names.length === 0) {
+      throw new Error("FetchproxyServer.readDom: opts.names must be a non-empty array");
+    }
+    this.assertScopeSubset(opts.names, this.opts.domSelectors.map((d) => d.name), "domSelectors");
+    if (opts.subdomain !== void 0)
+      assertSubdomainLabel(opts.subdomain);
+    const baseDomain = this.resolveBaseDomain(opts.domain);
+    const host = opts.subdomain ? `${opts.subdomain}.${baseDomain}` : baseDomain;
+    const origin = `https://${host}`;
+    const id = this.nextRequestId++;
+    const inner = {
+      type: "request",
+      id,
+      op: "read_dom",
+      init: { origin, names: [...opts.names] }
+    };
+    const pending = new Promise((resolve, reject) => {
+      this.pendingStorage.set(id, { resolve, reject });
+    });
+    await this.sendInnerFrame(inner);
+    return this._withVerbTimeout(pending, this.pendingStorage, id, origin);
+  }
   assertScopeSubset(requested, declared, label) {
     const undeclared = undeclaredKeys(requested, declared);
     if (undeclared.length > 0) {
@@ -37904,7 +38063,7 @@ var FetchproxyServer = class {
     if (storageCb) {
       this.pendingStorage.delete(inner.id);
       if (inner.ok) {
-        if ((inner.op === "read_local_storage" || inner.op === "read_session_storage") && inner.values) {
+        if ((inner.op === "read_local_storage" || inner.op === "read_session_storage" || inner.op === "read_dom") && inner.values) {
           storageCb.resolve({ ...inner.values });
         } else {
           storageCb.reject(new FetchproxyProtocolError(`unexpected ${String(inner.op)} response on storage awaiter`));
@@ -38229,7 +38388,7 @@ var BootstrapDisabledError = class extends Error {
 // package.json
 var package_default = {
   name: "zola-mcp",
-  version: "1.4.3",
+  version: "1.5.0",
   mcpName: "io.github.chrischall/zola-mcp",
   description: "Zola wedding MCP server for Claude",
   author: "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -38275,7 +38434,7 @@ var package_default = {
     "test:watch": "vitest"
   },
   dependencies: {
-    "@chrischall/mcp-utils": "^0.10.3",
+    "@chrischall/mcp-utils": "^0.13.0",
     "@fetchproxy/bootstrap": "^1.3.0",
     "@fetchproxy/server": "^1.3.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -38286,7 +38445,7 @@ var package_default = {
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.8",
     esbuild: "^0.28.0",
-    typescript: "^6.0.3",
+    typescript: "^7.0.2",
     vitest: "^4.1.8"
   }
 };
@@ -38328,18 +38487,26 @@ async function resolveRefreshToken() {
 var __dirname = dirname(fileURLToPath(import.meta.url));
 await loadDotenvSafely({ path: join2(__dirname, "..", ".env"), override: false });
 var MOBILE_BASE_URL = "https://mobile-api.zola.com";
+var SESSION_REFRESH_BUFFER_MS = 5 * 60 * 1e3;
 var ZolaClient = class {
-  sessionToken = null;
-  sessionExpiry = null;
   cachedContext = null;
   // WAF requires x-zola-session-id on all mobile-api.zola.com requests
   deviceSessionId = crypto.randomUUID().toUpperCase();
+  // The `ZOLA_SESSION_TOKEN` seed is a cold-start-only shortcut, exactly as the
+  // old `ensureSession` gated it on `sessionToken === null`; a 401 re-mint goes
+  // straight to `refresh()`, never back to the env token.
+  triedEnvSeed = false;
+  // Single-flight cached mint: caches the 30-min session JWT until 5 min before
+  // its `exp`, coalesces concurrent mints, and re-mints on demand after a 401.
+  session = createCachedTokenSource({
+    mint: () => this.mintSession(),
+    bufferMs: SESSION_REFRESH_BUFFER_MS
+  });
   /**
    * Make a request to the Zola mobile API (mobile-api.zola.com).
    * Uses Bearer JWT auth with x-zola-session-id header.
    */
   async requestMobile(method, path, body) {
-    await this.ensureSession();
     return this.doRequest(method, path, body);
   }
   /**
@@ -38349,7 +38516,6 @@ var ZolaClient = class {
    * raw bytes and the server's content-type so callers can pass it through.
    */
   async requestMobileBinary(method, path, body) {
-    await this.ensureSession();
     const response = await this.sendWithRetry(method, path, body, false, false, "*/*");
     const contentType = response.headers.get("content-type") ?? "application/octet-stream";
     const bytes = new Uint8Array(await response.arrayBuffer());
@@ -38393,10 +38559,11 @@ var ZolaClient = class {
     return text ? JSON.parse(text) : null;
   }
   async sendWithRetry(method, path, body, isAuthRetry = false, isRateRetry = false, accept = "application/json") {
-    const sessionId = decodeJwtSessionId(this.sessionToken);
+    const token = await this.session.getToken();
+    const sessionId = decodeJwtSessionId(token);
     const headers = {
       accept,
-      authorization: `Bearer ${this.sessionToken}`,
+      authorization: `Bearer ${token}`,
       "x-zola-platform-type": "iphone_app",
       "x-zola-session-id": this.deviceSessionId,
       "user-agent": "Zola/42.5.0 (iPad; iOS 26.4; Scale/2.0)",
@@ -38409,9 +38576,7 @@ var ZolaClient = class {
       ...body !== void 0 ? { body: JSON.stringify(body) } : {}
     });
     if (response.status === 401 && !isAuthRetry) {
-      this.sessionToken = null;
-      this.sessionExpiry = null;
-      await this.refresh();
+      this.session.invalidate();
       return this.sendWithRetry(method, path, body, true, isRateRetry, accept);
     }
     if (response.status === 429) {
@@ -38429,30 +38594,33 @@ var ZolaClient = class {
     }
     return response;
   }
-  async ensureSession() {
-    if (this.sessionToken && this.sessionExpiry) {
-      if (this.sessionExpiry.getTime() - Date.now() > 5 * 60 * 1e3) return;
-    }
-    if (this.sessionToken === null) {
+  /**
+   * Mint a session token for the cache. On the very first mint, use a valid
+   * `ZOLA_SESSION_TOKEN` if present (a cold-start shortcut that skips the
+   * initial refresh); otherwise, and on every later mint, refresh via the
+   * mobile API. Returns `{ token, expiresAt }` so the cache serves it until
+   * `SESSION_REFRESH_BUFFER_MS` before the JWT's `exp`.
+   */
+  async mintSession() {
+    if (!this.triedEnvSeed) {
+      this.triedEnvSeed = true;
       const envSession = readEnvVar("ZOLA_SESSION_TOKEN");
       if (envSession) {
         try {
           const exp = decodeJwtExp(envSession);
-          if (exp * 1e3 - Date.now() > 5 * 60 * 1e3) {
-            this.sessionToken = envSession;
-            this.sessionExpiry = new Date(exp * 1e3);
-            return;
+          if (exp * 1e3 - Date.now() > SESSION_REFRESH_BUFFER_MS) {
+            return { token: envSession, expiresAt: exp * 1e3 };
           }
         } catch {
         }
       }
     }
-    await this.refresh();
+    return this.refresh();
   }
   /**
    * Refresh the session using the mobile API endpoint.
    * POST /v3/sessions/refresh with the refresh token JWT.
-   * Returns a new session_token (30-min) and optionally a new refresh_token.
+   * Returns a new session_token (30-min) as a {@link MintedToken}.
    *
    * The refresh token comes from `resolveRefreshToken()`, which tries
    * (1) ZOLA_REFRESH_TOKEN env var, then (2) the fetchproxy 0.3.0 extension's
@@ -38481,8 +38649,7 @@ To fix: set ZOLA_REFRESH_TOKEN, or install the fetchproxy extension and sign int
     const result = await response.json();
     const { session_token } = result.data;
     const exp = decodeJwtExp(session_token);
-    this.sessionToken = session_token;
-    this.sessionExpiry = new Date(exp * 1e3);
+    return { token: session_token, expiresAt: exp * 1e3 };
   }
 };
 var client = new ZolaClient();
@@ -40448,7 +40615,7 @@ function registerEventInvitationTools(server) {
 }
 
 // src/index.ts
-var VERSION = "1.4.3";
+var VERSION = "1.5.0";
 await runMcp({
   name: "zola-mcp",
   version: VERSION,

package/dist/client.js

@@ -1,6 +1,6 @@
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-import { readEnvVar, loadDotenvSafely, decodeJwtExp, decodeJwtSessionId, formatApiError, truncateErrorMessage, } from '@chrischall/mcp-utils';
+import { readEnvVar, loadDotenvSafely, decodeJwtExp, decodeJwtSessionId, formatApiError, truncateErrorMessage, createCachedTokenSource, } from '@chrischall/mcp-utils';
 import { resolveRefreshToken } from './auth.js';
 // Load `.env` next to the compiled entry point. `loadDotenvSafely` is a
 // no-throw loader: in bundled mode (no resolvable `dotenv`) it returns false
@@ -8,18 +8,29 @@ import { resolveRefreshToken } from './auth.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 await loadDotenvSafely({ path: join(__dirname, '..', '.env'), override: false });
 const MOBILE_BASE_URL = 'https://mobile-api.zola.com';
+// Refresh the session token this long before its JWT `exp` — the same 5-minute
+// comfort margin the hand-rolled cache used for both the "still valid" check and
+// the `ZOLA_SESSION_TOKEN` seed's freshness gate.
+const SESSION_REFRESH_BUFFER_MS = 5 * 60 * 1000;
 export class ZolaClient {
-    sessionToken = null;
-    sessionExpiry = null;
     cachedContext = null;
     // WAF requires x-zola-session-id on all mobile-api.zola.com requests
     deviceSessionId = crypto.randomUUID().toUpperCase();
+    // The `ZOLA_SESSION_TOKEN` seed is a cold-start-only shortcut, exactly as the
+    // old `ensureSession` gated it on `sessionToken === null`; a 401 re-mint goes
+    // straight to `refresh()`, never back to the env token.
+    triedEnvSeed = false;
+    // Single-flight cached mint: caches the 30-min session JWT until 5 min before
+    // its `exp`, coalesces concurrent mints, and re-mints on demand after a 401.
+    session = createCachedTokenSource({
+        mint: () => this.mintSession(),
+        bufferMs: SESSION_REFRESH_BUFFER_MS,
+    });
     /**
      * Make a request to the Zola mobile API (mobile-api.zola.com).
      * Uses Bearer JWT auth with x-zola-session-id header.
      */
     async requestMobile(method, path, body) {
-        await this.ensureSession();
         return this.doRequest(method, path, body);
     }
     /**
@@ -29,7 +40,6 @@ export class ZolaClient {
      * raw bytes and the server's content-type so callers can pass it through.
      */
     async requestMobileBinary(method, path, body) {
-        await this.ensureSession();
         const response = await this.sendWithRetry(method, path, body, false, false, '*/*');
         const contentType = response.headers.get('content-type') ?? 'application/octet-stream';
         const bytes = new Uint8Array(await response.arrayBuffer());
@@ -75,10 +85,14 @@ export class ZolaClient {
         return (text ? JSON.parse(text) : null);
     }
     async sendWithRetry(method, path, body, isAuthRetry = false, isRateRetry = false, accept = 'application/json') {
-        const sessionId = decodeJwtSessionId(this.sessionToken);
+        // Current session token from the cache (mints/refreshes as needed). The
+        // per-request `x-zola-user-session-id` is derived from it every call, so a
+        // re-minted token below carries its own session id on the replay.
+        const token = await this.session.getToken();
+        const sessionId = decodeJwtSessionId(token);
         const headers = {
             accept,
-            authorization: `Bearer ${this.sessionToken}`,
+            authorization: `Bearer ${token}`,
             'x-zola-platform-type': 'iphone_app',
             'x-zola-session-id': this.deviceSessionId,
             'user-agent': 'Zola/42.5.0 (iPad; iOS 26.4; Scale/2.0)',
@@ -92,9 +106,8 @@ export class ZolaClient {
             ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
         });
         if (response.status === 401 && !isAuthRetry) {
-            this.sessionToken = null;
-            this.sessionExpiry = null;
-            await this.refresh();
+            // Drop the cached token so the replay's getToken re-mints via refresh().
+            this.session.invalidate();
             return this.sendWithRetry(method, path, body, true, isRateRetry, accept);
         }
         if (response.status === 429) {
@@ -110,22 +123,24 @@ export class ZolaClient {
         }
         return response;
     }
-    async ensureSession() {
-        // Session still valid with comfortable margin
-        if (this.sessionToken && this.sessionExpiry) {
-            if (this.sessionExpiry.getTime() - Date.now() > 5 * 60 * 1000)
-                return;
-        }
-        // Check for session token in env (first load only)
-        if (this.sessionToken === null) {
+    /**
+     * Mint a session token for the cache. On the very first mint, use a valid
+     * `ZOLA_SESSION_TOKEN` if present (a cold-start shortcut that skips the
+     * initial refresh); otherwise, and on every later mint, refresh via the
+     * mobile API. Returns `{ token, expiresAt }` so the cache serves it until
+     * `SESSION_REFRESH_BUFFER_MS` before the JWT's `exp`.
+     */
+    async mintSession() {
+        // Cold-start seed: use ZOLA_SESSION_TOKEN if present and comfortably
+        // unexpired. Only attempted once — a 401 re-mint always goes to refresh().
+        if (!this.triedEnvSeed) {
+            this.triedEnvSeed = true;
             const envSession = readEnvVar('ZOLA_SESSION_TOKEN');
             if (envSession) {
                 try {
                     const exp = decodeJwtExp(envSession);
-                    if (exp * 1000 - Date.now() > 5 * 60 * 1000) {
-                        this.sessionToken = envSession;
-                        this.sessionExpiry = new Date(exp * 1000);
-                        return;
+                    if (exp * 1000 - Date.now() > SESSION_REFRESH_BUFFER_MS) {
+                        return { token: envSession, expiresAt: exp * 1000 };
                     }
                 }
                 catch {
@@ -133,12 +148,12 @@ export class ZolaClient {
                 }
             }
         }
-        await this.refresh();
+        return this.refresh();
     }
     /**
      * Refresh the session using the mobile API endpoint.
      * POST /v3/sessions/refresh with the refresh token JWT.
-     * Returns a new session_token (30-min) and optionally a new refresh_token.
+     * Returns a new session_token (30-min) as a {@link MintedToken}.
      *
      * The refresh token comes from `resolveRefreshToken()`, which tries
      * (1) ZOLA_REFRESH_TOKEN env var, then (2) the fetchproxy 0.3.0 extension's
@@ -168,8 +183,7 @@ export class ZolaClient {
         const result = (await response.json());
         const { session_token } = result.data;
         const exp = decodeJwtExp(session_token);
-        this.sessionToken = session_token;
-        this.sessionExpiry = new Date(exp * 1000);
+        return { token: session_token, expiresAt: exp * 1000 };
     }
 }
 export const client = new ZolaClient();

package/dist/index.js

@@ -12,7 +12,7 @@ import { registerWebsiteThemeTools } from './tools/website-theme.js';
 import { registerRegistryItemTools } from './tools/registry-items.js';
 import { registerInvitationTools } from './tools/invitations.js';
 import { registerEventInvitationTools } from './tools/event-invitations.js';
-const VERSION = '1.4.3'; // x-release-please-version
+const VERSION = '1.5.0'; // x-release-please-version
 await runMcp({
     name: 'zola-mcp',
     version: VERSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zola-mcp",
-  "version": "1.4.3",
+  "version": "1.5.0",
   "mcpName": "io.github.chrischall/zola-mcp",
   "description": "Zola wedding MCP server for Claude",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -46,7 +46,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.10.3",
+    "@chrischall/mcp-utils": "^0.13.0",
     "@fetchproxy/bootstrap": "^1.3.0",
     "@fetchproxy/server": "^1.3.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -57,7 +57,7 @@
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.8",
     "esbuild": "^0.28.0",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.8"
   }
 }

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/zola-mcp",
     "source": "github"
   },
-  "version": "1.4.3",
+  "version": "1.5.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "zola-mcp",
-      "version": "1.4.3",
+      "version": "1.5.0",
       "transport": {
         "type": "stdio"
       },

package/skills/zola-api/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: zola-api
+description: >-
+  Query or update Zola wedding-planning data (vendors, budget, guests, seating,
+  events/RSVPs, registry, gift tracker, inquiries, wedding website) straight
+  from a shell with curl against mobile-api.zola.com, instead of running the
+  zola-mcp server. Use when you want Zola data without the MCP, in a script,
+  or on a machine where the MCP isn't installed. Triggers on "check Zola",
+  "Zola vendors/budget/guests/RSVP/seating/registry", or any Zola wedding
+  data request that should hit the API directly.
+---
+
+# Zola mobile API via curl (no MCP)
+
+Zola's mobile API (`mobile-api.zola.com` — the same surface the iOS/iPad app
+and `zola-mcp` use) is a plain Bearer-JWT REST API reachable directly from a
+server or shell — no browser bridge needed. This skill shells out to `curl`
+with the JWT in an `Authorization: Bearer` header, exactly as
+`zola-mcp`'s `src/client.ts` does.
+
+## One-time setup: get the refresh token
+
+You need Zola's long-lived (~1 year) refresh JWT — the `usr` cookie from a
+signed-in `zola.com` session. Same credential `zola-mcp` uses:
+
+```sh
+# Prefer the env var zola-mcp itself reads (check its .env first):
+grep -h ZOLA_REFRESH_TOKEN ~/git/zola-mcp/.env 2>/dev/null
+export ZOLA_REFRESH_TOKEN='eyJhbGciOi...'   # or export directly if you have it
+```
+
+If you don't have it yet: sign into zola.com, open DevTools → Application →
+Cookies → `https://www.zola.com`, copy the `usr` value. (`zola-mcp` also has a
+fetchproxy fallback that reads this cookie from a signed-in browser tab — see
+its README — but that's the MCP's path, not this skill's; this skill assumes
+you already have the token in hand.)
+
+## Core call pattern
+
+Every mobile-api call needs a short-lived (30 min) **session token**, minted
+from the refresh token, plus a fixed set of headers (CloudFront WAF requires
+`x-zola-session-id` on every request — omit it and you get a 403).
+
+```sh
+BASE=https://mobile-api.zola.com
+DEVICE_SESSION_ID=$(uuidgen | tr 'a-z' 'A-Z')   # one per "session"; reuse across calls
+UA='Zola/42.5.0 (iPad; iOS 26.4; Scale/2.0)'
+
+# 1. Mint a 30-min session token from the refresh token
+SESSION_TOKEN=$(curl -sS -X POST "$BASE/v3/sessions/refresh" \
+  -H 'content-type: application/json' -H 'accept: application/json' \
+  -H "x-zola-platform-type: iphone_app" -H "x-zola-session-id: $DEVICE_SESSION_ID" \
+  -H "user-agent: $UA" \
+  -d "{\"token\":\"$ZOLA_REFRESH_TOKEN\"}" | jq -r '.data.session_token')
+
+# 2. Every subsequent call reuses $SESSION_TOKEN until it expires (~30 min),
+#    then re-run step 1. All calls carry the same 4 headers:
+curl -sS -X GET "$BASE/v3/users/me/context" \
+  -H "authorization: Bearer $SESSION_TOKEN" \
+  -H "x-zola-platform-type: iphone_app" -H "x-zola-session-id: $DEVICE_SESSION_ID" \
+  -H "user-agent: $UA" | jq '.data'
+```
+
+Wrap this in a shell function or export the 4 headers once — every recipe in
+`references/mobile-api-endpoints.md` reuses `$BASE`, `$SESSION_TOKEN`,
+`$DEVICE_SESSION_ID`, `$UA`. POST/PUT bodies additionally need
+`-H 'content-type: application/json'`.
+
+(The app also sends a fifth header, `x-zola-user-session-id`, derived from a
+claim inside the session JWT — `zola-mcp` only attaches it when the decode
+succeeds, so it's not load-bearing; every endpoint below works without it.)
+
+## The one rule: resolve context first
+
+Most write/list endpoints are scoped by numeric IDs, never inferred — call
+`GET /v3/users/me/context` once per session and keep the three IDs around:
+
+```sh
+CTX=$(curl -sS "$BASE/v3/users/me/context" -H "authorization: Bearer $SESSION_TOKEN" \
+  -H "x-zola-platform-type: iphone_app" -H "x-zola-session-id: $DEVICE_SESSION_ID" -H "user-agent: $UA")
+ACCT=$(jq -r '.data.wedding_account.wedding_account_id' <<<"$CTX")
+REG=$(jq -r '.data.registry.id' <<<"$CTX")
+WEDDING_ID=$(jq -r '.data.wedding.wedding_id' <<<"$CTX")
+```
+
+`ACCT` (`wedding_account_id`) feeds guest/event/website-content paths; `REG`
+(`registry_id`) feeds registry/gift-tracker paths.
+
+## Ready-to-run endpoints
+
+`references/mobile-api-endpoints.md` has real, ready-to-run `curl` + `jq`
+recipes for every one of the 30 `zola-mcp` tools' underlying calls
+(vendors, budget, guests, seating, inquiries, events/RSVPs/gifts/registry,
+discover/storefronts, registry items, invitations/card-projects, website
+pages, website theme/customization, website content). Transcribed straight
+from `src/tools/*.ts` — same paths, same request bodies.
+
+## Mutation gotcha: most writes are read-modify-write
+
+Zola's write endpoints replace whole objects, not deltas — the same tools
+that build a request first re-GET the current record and only patch the
+requested fields, or a full-state write can wipe unrelated fields.
+`docs/zola-api-quirks.md` in this repo documents the worst offenders (a
+`header_font` write nulling every other website color; guest writes needing
+to preserve `event_invitations` verbatim or lose them). Follow the
+read-modify-write shape shown per-endpoint in the references file — don't
+send a bare partial body to `PUT`/`POST` write endpoints.
+
+## Output / error contract
+
+- A 2xx body is `{"data": ...}` for nearly every endpoint — pipe to
+  `jq '.data'`.
+- `401` — session token expired; re-mint via `POST /v3/sessions/refresh`
+  (step 1 above) and retry once.
+- `429` — rate limited; back off ~2s and retry once.
+- Any other non-2xx — the body is a JSON error envelope; read it directly,
+  it is not redacted here (unlike the MCP, which redacts secrets from error
+  text — don't paste raw error bodies containing the session token anywhere
+  public).
+- This project (`zola-mcp`) is developed and maintained by AI (Claude).

package/skills/zola-api/references/mobile-api-endpoints.md

@@ -0,0 +1,444 @@
+# Zola mobile-api endpoints (curl + jq)
+
+All paths are relative to `$BASE=https://mobile-api.zola.com`. Every call
+carries `authorization: Bearer $SESSION_TOKEN`, `x-zola-platform-type:
+iphone_app`, `x-zola-session-id: $DEVICE_SESSION_ID`, `user-agent: $UA` (see
+`SKILL.md`); POST/PUT/DELETE-with-body also need `-H 'content-type:
+application/json'`. `$ACCT` = `wedding_account_id`, `$REG` = `registry_id`,
+`$WEDDING_ID` = `wedding_id`, all three from `GET /v3/users/me/context` (see
+`SKILL.md`'s "resolve context first" section). Response envelope is `{"data": ...}`
+unless noted. Paths/bodies below are transcribed from `src/tools/*.ts` —
+each section names its source file.
+
+Shorthand used below:
+
+```sh
+H=(-H "authorization: Bearer $SESSION_TOKEN" -H "x-zola-platform-type: iphone_app" \
+   -H "x-zola-session-id: $DEVICE_SESSION_ID" -H "user-agent: $UA")
+HJ=("${H[@]}" -H 'content-type: application/json')
+```
+
+---
+
+## Context (`src/client.ts`)
+
+```sh
+curl -sS "${H[@]}" "$BASE/v3/users/me/context" | jq '.data'
+# .data.user.id, .data.wedding_account.wedding_account_id,
+# .data.wedding.{wedding_id,wedding_date,slug}, .data.registry.id
+```
+
+---
+
+## Vendors (`src/tools/vendors.ts`)
+
+**List booked vendors** — `POST /v3/account-vendors/booked-list` body `{}`:
+
+```sh
+curl -sS "${HJ[@]}" -X POST "$BASE/v3/account-vendors/booked-list" -d '{}' \
+  | jq '.data.booked_vendors'
+```
+
+**Search vendors (typeahead)** — `POST /v3/reference-vendors/typeahead-taxonomy`:
+
+```sh
+curl -sS "${HJ[@]}" -X POST "$BASE/v3/reference-vendors/typeahead-taxonomy" \
+  -d '{"query":"Acme Photography","taxonomy_key":"wedding-photographers"}' | jq '.data'
+# taxonomy_key default: wedding-venues. Other keys: wedding-planners, wedding-bands-djs, ...
+```
+
+**Book a vendor** — find an unbooked slot from `booked-list` for the
+`vendor_type`, then `PUT /v5/account-vendors/vendor` (note: **v5**, not v3):
+
+```sh
+curl -sS "${HJ[@]}" -X PUT "$BASE/v5/account-vendors/vendor" -d '{
+  "uuid": "<slot-uuid-from-booked-list>", "id": 0, "vendor_type": "PHOTOGRAPHER",
+  "booked": true, "booking_source": "BOOKED_VENDORS",
+  "price_cents": 350000, "event_date": null,
+  "sync_with_budget_tool_enabled": true, "facet_keys": [],
+  "reference_vendor_request": {
+    "id": null, "name": "Acme Photography", "email": null, "phone": null,
+    "address": {"city": "Charlotte", "state_province_region": "NC"}
+  }
+}' | jq '.data'
+```
+
+**Update a booked vendor** — same `PUT /v5/account-vendors/vendor`, but
+read-modify-write: GET `booked-list`, find by `uuid`, keep `id`/`vendor_type`,
+only patch the fields you're changing (name/city/state/email/price/date
+default to the current value).
+
+**Unbook a vendor** — `POST /v3/account-vendors/vendor/unbook`:
+
+```sh
+curl -sS "${HJ[@]}" -X POST "$BASE/v3/account-vendors/vendor/unbook" \
+  -d '{"uuid":"<vendor-uuid>"}'
+```
+
+---
+
+## Budget (`src/tools/budget.ts`)
+
+**Get budget** — `GET /v3/budgets`:
+
+```sh
+curl -sS "${H[@]}" "$BASE/v3/budgets" | jq '{
+  budgeted_cents: .data.budgeted_cents, cost_cents: .data.cost_cents,
+  paid_cents: .data.paid_cents, balance_due_cents: .data.balance_due_cents,
+  items: [.data.taxonomy_nodes[].items[] | {uuid, title, cost_cents, paid_cents}]
+}'
+```
+
+**Update a budget item** — read-modify-write: `GET /v3/budgets`, find the item
+by `uuid`, then `PUT /v3/budgets/items` with every required field (server
+rejects a bare partial):
+
+```sh
+curl -sS "${HJ[@]}" -X PUT "$BASE/v3/budgets/items" -d '{
+  "item_uuid": "<uuid>", "taxonomy_node_uuid": "<from-get>",
+  "estimated_cost_cents": <from-get>, "actual_cost_cents": 250000,
+  "note": "Deposit paid", "item_type": "<from-get, e.g. VENUE>",
+  "title": "<from-get>"
+}' | jq '.data'
+```
+
+---
+
+## Guests (`src/tools/guests.ts`)
+
+**List guests** — `POST /v3/guestlists/directory/wedding-accounts/$ACCT` body
+`{"sort_by_name_asc": true}`. Guest shape is **flat** (fields directly on the
+guest object, no `{guest:{...}}` wrapper):
+
+```sh
+curl -sS "${HJ[@]}" -X POST "$BASE/v3/guestlists/directory/wedding-accounts/$ACCT" \
+  -d '{"sort_by_name_asc": true}' \
+  | jq '.data.guest_groups[] | {guest_group_id, guests: [.guests[] | {guest_id, first_name, family_name, rsvp}]}'
+```
+
+**Add a guest group** — `POST /v3/guestlists/groups`:
+
+```sh
+curl -sS "${HJ[@]}" -X POST "$BASE/v3/guestlists/groups" -d '{
+  "wedding_account_id": '"$ACCT"',
+  "guests": [{
+    "first_name": "Mike", "family_name": "Smith", "relationship_type": "PRIMARY",
+    "source": "IOS", "email_address": "", "mobile_phone": "", "affiliation": "PRIMARY_FRIEND",
+    "tier": "A", "country_code": "US", "prefix": "", "middle_name": "", "suffix": "",
+    "home_phone": "", "address1": "", "address2": "", "city": "", "state_province": "",
+    "postal_code": "", "event_invitations": [], "tags": []
+  }],
+  "guest_group_affiliation": "PRIMARY_FRIEND", "guest_group_tier": "A",
+  "guest_group_uuid": "", "envelope_recipient": "", "invited": true,
+  "invitation_sent": false, "save_the_date_sent": false,
+  "rsvp_question_answers": [], "gift_count": 0
+}' | jq '.data'
+```
+
+**Update a guest group's address** — read-modify-write via
+`PUT /v3/guestlists/groups/wedding-accounts/$ACCT/bulk/directory`. **Must**
+preserve each guest's existing `event_invitations` verbatim (a group that
+sends `event_invitations: []` wipes them, per `docs/zola-api-quirks.md` §5):
+
+```sh
+# 1. GET the directory (above), find the target group by guest_group_id,
+#    keep its `guests[]` array as-is except the address fields you're changing.
+curl -sS "${HJ[@]}" -X PUT "$BASE/v3/guestlists/groups/wedding-accounts/$ACCT/bulk/directory" \
+  -d '{"updated_guest_groups": [ <full-group-object-with-patched-guest-addresses> ]}' \
+  | jq '.data'
+```
+
+**Remove a guest group** — `PUT /v3/guestlists/groups/wedding-accounts/$ACCT/delete`:
+
+```sh
+curl -sS "${HJ[@]}" -X PUT "$BASE/v3/guestlists/groups/wedding-accounts/$ACCT/delete" \
+  -d '{"wedding_account_id": '"$ACCT"', "guest_group_ids": [<id>]}'
+```
+
+---
+
+## Seating (`src/tools/seating.ts`)
+
+```sh
+curl -sS "${H[@]}" "$BASE/v3/seating-charts/summaries" | jq '.'   # NOT wrapped in `data`
+curl -sS "${H[@]}" "$BASE/v3/seating-charts/<chart-uuid>" | jq '.'
+```
+
+**Unseated guests** — `POST /v3/guestlists/directory/wedding-accounts/$ACCT`
+(same call as guests list), filter client-side for
+`.guests[].seating_chart_seat == null`.
+
+**Assign a seat** — `PUT /v3/seating-charts/seats`:
+
+```sh
+curl -sS "${HJ[@]}" -X PUT "$BASE/v3/seating-charts/seats" -d '{
+  "guest_uuid": "<guest-uuid>", "seat_uuid": "<seat-uuid>",
+  "table_uuid": "<table-uuid>", "seating_chart_uuid": "<chart-uuid>"
+}' | jq '.'
+```
+
+---
+
+## Inquiries (`src/tools/inquiries.ts`)
+
+```sh
+curl -sS "${HJ[@]}" -X POST "$BASE/v3/inquiries/unified-inquiries" -d '{}' \
+  | jq '.data[].inquiry_summaries[] | {inquiry_uuid, vendor_name: .vendor_card.vendor_name, unread, status_text}'
+
+curl -sS "${H[@]}" "$BASE/v3/inquiries/<inquiry-uuid>/conversation" | jq '.data.messages'
+
+curl -sS "${H[@]}" -X PUT "$BASE/v3/inquiries/<inquiry-uuid>/conversation/read"
+```
+
+---
+
+## Events, RSVPs, gifts, registry (`src/tools/events.ts`)
+
+```sh
+curl -sS "${H[@]}" "$BASE/v3/websites/events/wedding-accounts/$ACCT/groups" \
+  | jq '.data[].events[]'   # event_entity_id, name, start_at, num_guests_*
+
+curl -sS "${H[@]}" "$BASE/v3/websites/events/track-rsvps" | jq '.data.modules'
+
+curl -sS "${H[@]}" "$BASE/v3/gift_tracker/$REG" | jq '.data | del(.info_modules)'
+
+curl -sS "${H[@]}" "$BASE/v4/shop/registry?registry_id=$REG&updated_modules=true" | jq '.data'
+```
+
+**Update an event** — read-modify-write: GET the groups above, find by
+`event_entity_id`, then `PUT /v3/websites/events/{event_id}` with the full
+event object (patch only the fields you're changing; everything else —
+`type`, `uuid`, `wedding_account_id`, counts, `meal_options` — round-trips
+from the GET):
+
+```sh
+curl -sS "${HJ[@]}" -X PUT "$BASE/v3/websites/events/<event_id>" -d '{
+  "event_entity_id": <event_id>, "uuid": "<from-get>", "wedding_account_id": '"$ACCT"',
+  "type": "<from-get>", "name": "Reception", "start_at": "<from-get>", "end_at": "<from-get>",
+  "timezone": "<from-get>", "venue_name": "The Grand Hall", "address1": "", "address2": "",
+  "city": "Charlotte", "state_province": "NC", "postal_code": "", "country_code": "US",
+  "note": "", "attire": "Black tie", "collect_rsvps": true, "public": <from-get>,
+  "display_order": 0, "num_guests_attending": <from-get>, "num_guests_declined": <from-get>,
+  "num_guests_not_responded": <from-get>, "meal_options": <from-get>,
+  "rsvp_questions": [], "add_booked_vendor": false
+}' | jq '.data'
+```
+
+**Event invitations (per-guest, read-modify-write)** — from
+`src/tools/event-invitations.ts`. Each guest carries an `event_invitations`
+array; invite = append `{"event_id":<id>,"id":null,"rsvp_type":"NO_RESPONSE"}`,
+uninvite = drop that element, **preserve every other element verbatim**
+(same wipe risk as the guest-address write above). Write through the same
+`PUT /v3/guestlists/groups/wedding-accounts/$ACCT/bulk/directory` used for
+guest writes, sending `{"updated_guest_groups": [...]}` with full group
+objects (each guest keeps its full shape, only `event_invitations` patched).
+
+---
+
+## Discover / storefronts (`src/tools/discover.ts`)
+
+```sh
+curl -sS "${H[@]}" "$BASE/v4/your-wedding" | jq '.data'
+
+curl -sS "${HJ[@]}" -X POST "$BASE/v3/storefronts/search" -d '{
+  "taxonomy_node_id": 2, "city": "Charlotte", "state": "NC",
+  "limit": 24, "offset": 0, "facets": {},
+  "metro_types": ["HOME","HOME_SERVICE","AWAY"], "metros": [],
+  "exclude_inquired_storefronts": false, "exclude_booked_storefronts": false,
+  "boost_featured_storefronts": false, "suggested_vendors_for_inquiry_limit": 12
+}' | jq '.data'
+# taxonomy_node_id: 1=Venues 2=Photographers 3=Florists 7=Planners 9=Bands/DJs
+
+curl -sS "${H[@]}" "$BASE/v3/storefronts/<storefront-uuid>" | jq '.data'
+curl -sS "${H[@]}" "$BASE/v3/favorites/" | jq '.data'
+```
+
+---
+
+## Registry items (`src/tools/registry-items.ts`)
+
+```sh
+curl -sS "${HJ[@]}" -X POST "$BASE/v3/categories/<category_id>/entities" \
+  -d '{"offset":0,"limit":50,"registry_id":"'"$REG"'"}' | jq '.data'
+
+# Default collection id: `.data.default_collection_id` from the registry GET
+# above, or the first `groups[].modules[]` entry with `type == "COLLECTION"`.
+curl -sS "${HJ[@]}" -X POST "$BASE/v3/registries/$REG/collections/<collection_id>" \
+  -d '{"sku_id":"<sku>","quantity":1,"most_wanted":false,"enable_group_gifting":false}' \
+  | jq '.data'
+
+# Full replace — all fields required:
+curl -sS "${HJ[@]}" -X PUT "$BASE/v3/registries/$REG/items/<collection_item_id>" -d '{
+  "quantity": 2, "group_gift": false, "marked_fulfilled": false,
+  "personal_note": "", "most_wanted": true, "collection_id": "<collection_id>"
+}' | jq '.data'
+
+curl -sS "${H[@]}" -X DELETE "$BASE/v3/registries/$REG/items/<collection_item_id>"
+```
+
+---
+
+## Website pages & settings (`src/tools/website.ts`)
+
+```sh
+curl -sS "${H[@]}" "$BASE/v3/websites/pages/wedding-accounts/full" | jq '.data'
+
+curl -sS "${H[@]}" -X PUT "$BASE/v3/websites/pages/<page_id>/hidden/true"  # or /false
+
+curl -sS "${HJ[@]}" -X PUT "$BASE/v3/websites/pages/wedding-accounts/$ACCT/reorder" \
+  -d '{"ids": [<page_id_1>, <page_id_2>, ...]}' | jq '.data'
+
+# Partial patch is fine here (unlike most write endpoints):
+curl -sS "${HJ[@]}" -X PUT "$BASE/v3/websites/pages-v2/<page_id>" \
+  -d '{"page_id": <page_id>, "title": "Our Story"}' | jq '.data'
+```
+
+**Wedding settings** — read via `GET /v3/users/me/context` → `.data.wedding`;
+write is read-modify-write (all fields required) to
+`PUT /v3/weddings/{wedding_id}`:
+
+```sh
+curl -sS "${HJ[@]}" -X PUT "$BASE/v3/weddings/$WEDDING_ID" -d '{
+  "wedding_id": '"$WEDDING_ID"', "account_id": '"$ACCT"',
+  "slug": "<from-get>", "owner_first_name": "<from-get>", "owner_last_name": "<from-get>",
+  "partner_first_name": "<from-get>", "partner_last_name": "<from-get>",
+  "title": "Alex & Jordan", "wedding_date": "<from-get>", "hashtag": "#alexandjordan2026",
+  "enable_search_engine": true, "enable_search_zola": true,
+  "city": "Charlotte", "state_province": "NC", "guest_count": 150
+}' | jq '.data'
+```
+
+---
+
+## Website theme & customization (`src/tools/website-theme.ts`)
+
+```sh
+curl -sS "${H[@]}" "$BASE/v3/themes/current" | jq '.data'
+curl -sS "${H[@]}" "$BASE/v3/websites/website-customizations/context" | jq '.data.current_style_customizations'
+
+curl -sS "${HJ[@]}" -X POST "$BASE/v3/themes/search" \
+  -d '{"limit":50,"offset":0,"theme_layout_types":["MULTI_PAGE"]}' | jq '.data'
+
+curl -sS "${HJ[@]}" -X PUT "$BASE/v3/themes/current" \
+  -d '{"theme_key":"galata","theme_layout_type":"MULTI_PAGE"}' | jq '.data'
+```
+
+**Update colors/fonts** — `POST /v3/websites/website-customizations/context`.
+**Gotcha (see `docs/zola-api-quirks.md` §1–4):** changing `header_font`
+(i.e. `header_font_family_id`) wipes every *other* active color unless you
+re-send them in the same POST — GET the current state first and bundle its
+non-null `accent_color` / `background_color` / `body.color` /
+`navigation_customization.background_color` into the body. `body_font`'s
+`font_family_id` only accepts `68` (Libre Baskerville) or `198` (Circular) —
+any other value 500s. `header_color` / `nav_font_color` are **not** writable
+on this API at all (web-api-only, cookie+CSRF auth — out of scope here).
+
+```sh
+curl -sS "${HJ[@]}" -X POST "$BASE/v3/websites/website-customizations/context" -d '{
+  "accent_color": "C9A66B",
+  "background_color": "FFFFFF",
+  "body_font": {"color": "222222"},
+  "navigation_customization": {"background_color": "FFFFFF"}
+}' | jq '.data'
+```
+
+---
+
+## Website content: FAQs / home sections / POIs / travel (`src/tools/website-content.ts`)
+
+All four follow the same list/add/update/remove shape;
+`{wedding_account_id: $ACCT}` and an `_entity_id: 0` (create) or the real id
+(update) prefix every write body. Deletes share one path shape:
+`DELETE /v3/websites/{pages}/{entities}/{entity_id}/wedding-accounts/$ACCT`
+where `{pages}` is looked up per-type from
+`GET /v3/websites/pages/wedding-accounts/full` (`.data.{home,faq,poi,travel}_page.page_id`).
+
+```sh
+# FAQs
+curl -sS "${H[@]}" "$BASE/v3/websites/faqs/wedding-accounts/$ACCT" | jq '.data'
+curl -sS "${HJ[@]}" -X POST "$BASE/v3/websites/faqs" -d '{
+  "wedding_account_id": '"$ACCT"', "faq_entity_id": 0,
+  "question": "What is the dress code?", "answer": "Cocktail attire", "display_order": 0
+}' | jq '.data'
+curl -sS "${HJ[@]}" -X PUT "$BASE/v3/websites/faqs/<faq_entity_id>" -d '{
+  "wedding_account_id": '"$ACCT"', "faq_entity_id": <faq_entity_id>,
+  "question": "...", "answer": "...", "display_order": 0
+}' | jq '.data'
+curl -sS "${H[@]}" -X DELETE "$BASE/v3/websites/pages/<faq_page_id>/entities/<faq_entity_id>/wedding-accounts/$ACCT"
+
+# Home page story sections — same shape, path `/v3/websites/home-sections[...]`,
+# id field `homepage_entity_id`, extra `hidden` boolean, `title`+`subtitle`+`description`.
+
+# Points of interest — `/v3/websites/points-of-interest[...]`, id field
+# `poi_entity_id`; fields: title, description, address1/2, city, state_province,
+# postal_code, country_code, latitude, longitude, google_place_id, contact_phone, url.
+
+# Travel items — `/v3/websites/travel[...]`, id field `travel_entity_id`;
+# fields: type (HOTEL|FLIGHT|TRAIN|BUS|CAR|OTHER), name, note, code,
+# address1/2, city, state_province, postal_code, country_code, latitude,
+# longitude, google_place_id, contact_number, email_address, url, source
+# (GOOGLE_PLACES|MANUAL), timezone, display_order.
+```
+
+Home-section/POI/travel `list`/`add`/`update`/`remove` all mirror the FAQ
+calls above 1:1 (same verbs, same `wedding_account_id` prefix, same delete
+shape) — see `src/tools/website-content.ts` for the exact field names per
+type if you need the full body.
+
+---
+
+## Invitations / card projects (`src/tools/invitations.ts`)
+
+```sh
+curl -sS "${HJ[@]}" -X POST "$BASE/v3/card-projects/search_request" -d '{
+  "completed": false, "limit": 30, "card_suite_uuids": [], "card_suite_ids": [],
+  "offset": 0, "fetch_customizations": true, "include_deleted": false,
+  "medium": ["PAPER","MAGNET","DIGITAL"], "single_sample": false
+}' | jq '.data'
+
+curl -sS "${H[@]}" "$BASE/v3/card-projects/<project_uuid>" | jq '.data'
+curl -sS "${H[@]}" "$BASE/v3/card-projects/<project_uuid>/validate" | jq '.data'
+curl -sS "${H[@]}" "$BASE/v3/card-projects/<project_uuid>/project-guest-groups" | jq '.data'
+curl -sS "${HJ[@]}" -X POST "$BASE/v4/card-catalog/suites/details/<suite_uuid>" | jq '.data'
+
+curl -sS "${HJ[@]}" -X POST "$BASE/v3/card-catalog/search/faceted" -d '{
+  "lead_card_types": [], "include_updated_proof_module": true, "limit": 50, "offset": 0,
+  "digital_suite": false, "include_lead_card_type_metadata": true,
+  "lead_card_type": "INVITATION", "include_module": true
+}' | jq '.data'
+
+curl -sS "${H[@]}" "$BASE/v3/favorites/card-suites/" | jq '.data'
+curl -sS "${H[@]}" "$BASE/v3/websites/rsvps/wedding-accounts/$ACCT" | jq '.data'
+
+curl -sS "${HJ[@]}" -X POST "$BASE/v3/card-projects" -d '{
+  "quantity": 150, "lead_variation_uuid": "<variation-uuid>",
+  "extra_customizable": false, "account_id": '"$ACCT"', "suite_uuid": "<suite-uuid>"
+}' | jq '.data'
+
+curl -sS "${HJ[@]}" -X PUT "$BASE/v3/card-projects/<project_uuid>" -d '{
+  "customizations": {"<customization_uuid>": {"variation_uuid": "<new-variation-uuid>"}}
+}' | jq '.data'
+
+curl -sS "${HJ[@]}" -X PUT "$BASE/v3/card-projects/<project_uuid>/project-guest-groups" -d '{
+  "guest_group_requests": [{"guest_group_id": <id>, "enabled": true}]
+}' | jq '.data'
+
+curl -sS "${HJ[@]}" -X POST "$BASE/v3/card-templates/preview" -d '{
+  "variation_uuids": ["<variation-uuid>"], "customizable": true,
+  "substitutions": {"first_name": "Alex", "wedding_date": "2026-10-17"}
+}' | jq '.data'
+```
+
+**QR code** — preview returns raw image bytes (Content-Type lies as
+`image/jpeg` even for a PNG — sniff magic bytes if scripting):
+
+```sh
+curl -sS "${HJ[@]}" -X PUT "$BASE/v3/card-projects/qrcode/preview" \
+  -H 'accept: */*' -d '{"dimension":"MEDIUM","url_type":"CUSTOM","enabled":true,"url":"https://example.com"}' \
+  -o qrcode.png
+
+curl -sS "${HJ[@]}" -X PUT "$BASE/v3/card-projects/<project_uuid>/customization/page/<page_uuid>/qrcode" -d '{
+  "dimension": "MEDIUM", "url_type": "CUSTOM", "color": "000000",
+  "enabled": true, "url": "https://example.com"
+}' | jq '.data'
+```