honeybook-mcp 0.3.6 → 0.4.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "HoneyBook client-portal tools for Claude Code",
-    "version": "0.3.6"
+    "version": "0.4.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "HoneyBook",
       "source": "./",
       "description": "HoneyBook client-portal MCP for Claude — view wedding-vendor contracts and invoices via MCP",
-      "version": "0.3.6",
+      "version": "0.4.0",
       "author": {
         "name": "Chris Chall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "honeybook",
   "displayName": "HoneyBook",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "HoneyBook client-portal MCP for Claude — view wedding-vendor contracts and invoices via MCP",
   "author": {
     "name": "Chris Chall",

package/dist/bundle.js

@@ -35071,6 +35071,7 @@ var KNOWN_CAPABILITIES = /* @__PURE__ */ new Set([
   "capture_request_header",
   "capture_redirect",
   "read_indexed_db",
+  "read_dom",
   "download"
 ]);
 
@@ -35372,6 +35373,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;
@@ -35447,6 +35486,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");
@@ -35681,6 +35723,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) {
@@ -35706,7 +35763,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)) {
@@ -35791,6 +35848,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");
@@ -36130,6 +36194,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;
 }
 
@@ -36219,7 +36290,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;
@@ -36454,6 +36526,7 @@ async function startPeer(opts) {
     sessionStorageKeys: opts.sessionStorageKeys,
     captureHeaders: opts.captureHeaders,
     indexedDbScopes: opts.indexedDbScopes,
+    domSelectors: opts.domSelectors,
     localStoragePointers: opts.localStoragePointers,
     sessionStoragePointers: opts.sessionStoragePointers
   });
@@ -36861,6 +36934,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
@@ -36981,6 +37059,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));
@@ -37008,7 +37087,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(() => {
@@ -37983,6 +38063,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) {
@@ -38054,7 +38174,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`));
@@ -38412,7 +38532,7 @@ function bridgeErrorInfo(err) {
 // package.json
 var package_default = {
   name: "honeybook-mcp",
-  version: "0.3.6",
+  version: "0.4.0",
   mcpName: "io.github.chrischall/honeybook-mcp",
   description: "HoneyBook client-portal MCP server for Claude",
   author: "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -38452,7 +38572,7 @@ var package_default = {
     "test:watch": "vitest"
   },
   dependencies: {
-    "@chrischall/mcp-utils": "^0.12.0",
+    "@chrischall/mcp-utils": "^0.13.0",
     "@fetchproxy/bootstrap": "^1.0.0",
     "@fetchproxy/server": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -38463,7 +38583,7 @@ var package_default = {
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.7",
     esbuild: "^0.28.0",
-    typescript: "^6.0.3",
+    typescript: "^7.0.2",
     vitest: "^4.1.7"
   }
 };
@@ -39049,7 +39169,7 @@ var __dirname = dirname2(fileURLToPath(import.meta.url));
 await loadDotenvSafely({ path: join3(__dirname, "..", ".env"), override: false });
 await runMcp({
   name: "honeybook-mcp",
-  version: "0.3.6",
+  version: "0.4.0",
   // x-release-please-version
   tools: [
     registerSessionTools,

package/dist/index.js

@@ -11,7 +11,7 @@ import { registerContractTools } from './tools/contracts.js';
 import { registerInvoiceTools } from './tools/invoices.js';
 await runMcp({
     name: 'honeybook-mcp',
-    version: '0.3.6', // x-release-please-version
+    version: '0.4.0', // x-release-please-version
     tools: [
         registerSessionTools,
         registerWorkspaceFileTools,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "honeybook-mcp",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "mcpName": "io.github.chrischall/honeybook-mcp",
   "description": "HoneyBook client-portal MCP server for Claude",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -40,7 +40,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.12.0",
+    "@chrischall/mcp-utils": "^0.13.0",
     "@fetchproxy/bootstrap": "^1.0.0",
     "@fetchproxy/server": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -51,7 +51,7 @@
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.7",
     "esbuild": "^0.28.0",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.7"
   }
 }

package/server.json

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

package/skills/honeybook-fpx/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: honeybook-fpx
+description: >-
+  Read HoneyBook client-portal data (contracts, invoices, proposals, payment
+  methods, workspace status) from a shell with the fpx CLI (@fetchproxy/cli)
+  instead of running the honeybook-mcp server — capture a vendor session once
+  via the signed-in browser tab, then curl api.honeybook.com directly. Use
+  when you want HoneyBook data without the MCP, in a script, or on a machine
+  where the MCP isn't installed.
+---
+
+# HoneyBook via fpx + curl (no MCP)
+
+HoneyBook has **no server-side login** a script can drive — a client never
+gets a password, only a magic-link email per vendor. The credential is
+whatever the signed-in `*.hbportal.co` portal tab already holds: a bearer
+token + user id + device id in `localStorage["jStorage"]`, plus a per-device
+`hb-api-fingerprint` request header that only appears on a live outgoing
+`api.honeybook.com/api/v2/*` call (it's FingerprintJS, not stored anywhere).
+There's no bot wall on the API itself once you have those — `honeybook-mcp`'s
+own `client.ts` proves plain Node `fetch` works fine against
+`api.honeybook.com`. So this skill is **hybrid**: `fpx` captures the session
+**once** (per vendor), then plain `curl` does every read from then on.
+
+This mirrors `src/auth.ts` (`captureSessionViaFetchproxy`) and `src/client.ts`
+(`HoneyBookClient.request`) in `honeybook-mcp` — same headers, same base URL,
+same retry rules.
+
+## Multi-domain scope
+
+Two apexes are declared on one profile:
+- `hbportal.co` — the vendor's branded portal (e.g. `acme.hbportal.co`),
+  where `jStorage` lives.
+- `honeybook.com` — required so the extension is allowed to capture the
+  `hb-api-fingerprint` header off requests to `api.honeybook.com`.
+
+## One-time setup
+
+```sh
+npm install -g @fetchproxy/cli   # provides `fpx`
+fpx profile add honeybook --domain honeybook.com --domain hbportal.co
+fpx profile declare honeybook \
+  --local-storage jStorage \
+  --capture-header 'hb-api-fingerprint@api.honeybook.com/api/v2/*'
+fpx pair -p honeybook            # prints a pair code → approve in Transporter
+```
+
+Requirements: the **Transporter** browser extension installed, its Chrome
+**Site access** allowing both `honeybook.com` and `hbportal.co`, and a vendor
+magic-link URL already open (signed in) in that browser. Pairing persists —
+after the first approval every later `fpx` call reuses it.
+
+## Capture a vendor session (once per vendor, and again when it expires)
+
+1. Click the vendor's HoneyBook magic-link email in the browser with
+   Transporter installed. This signs you into `<vendor>.hbportal.co`.
+2. **While that tab is open**, run:
+
+```sh
+fpx session -p honeybook --storage-domain hbportal.co > /tmp/hb-session.json
+```
+
+**The fingerprint capture needs a FRESH request, not a loaded page.** A
+portal tab that finished loading and went idle has no outgoing
+`api.honeybook.com/api/v2/*` call left to sniff, so the capture times out.
+While `fpx session` is waiting (~30s window), refresh the portal tab or open
+a workspace/file so the page issues a new API call.
+
+3. Extract the fields `client.ts` needs (`jStorage` is one raw localStorage
+   value packing several keys as JSON — parse it with `fromjson`):
+
+```sh
+AUTH_TOKEN=$(jq -r '.localStorage.jStorage | fromjson | .HB_AUTH_TOKEN' /tmp/hb-session.json)
+USER_ID=$(jq -r '.localStorage.jStorage | fromjson | .HB_AUTH_USER_ID' /tmp/hb-session.json)
+TRUSTED_DEVICE=$(jq -r '.localStorage.jStorage | fromjson | .HB_TRUSTED_DEVICE' /tmp/hb-session.json)
+FINGERPRINT=$(jq -r '.capturedHeaders["hb-api-fingerprint"]' /tmp/hb-session.json)
+PORTAL_ORIGIN='https://<vendor>.hbportal.co'   # the magic-link URL's origin
+```
+
+If any of `AUTH_TOKEN`/`USER_ID`/`TRUSTED_DEVICE`/`FINGERPRINT` come back
+empty/`null`, the capture didn't see what it needed — re-open the magic link
+(or interact with the tab) and re-run step 2.
+
+With more than one vendor tab open at once, disambiguate with
+`--storage-subdomain <vendor>` (e.g. `--storage-subdomain acme`).
+
+4. Get the current API version (`client.ts`'s `fetchApiVersion` parses this
+   same endpoint):
+
+```sh
+API_VERSION=$(curl -s 'https://api.honeybook.com/api/gon?callback=parseGon' \
+  | grep -oE '"api_version":[[:space:]]*[0-9]+' | grep -oE '[0-9]+$')
+```
+
+## Core call pattern
+
+Every real request carries the same eight headers
+(`client.ts`'s `HoneyBookClient.request`):
+
+```sh
+curl -s "https://api.honeybook.com/api/v2/users/$USER_ID/workspace_files" \
+  -H 'accept: application/json, text/plain, */*' \
+  -H "hb-api-auth-token: $AUTH_TOKEN" \
+  -H "hb-api-user-id: $USER_ID" \
+  -H "hb-trusted-device: $TRUSTED_DEVICE" \
+  -H "hb-api-client-version: $API_VERSION" \
+  -H "hb-api-fingerprint: $FINGERPRINT" \
+  -H "hb-api-duplicate-calls-prevention-uuid: $(uuidgen)" \
+  -H 'hb-admin-login: false' \
+  | jq '.data'
+```
+
+`hb-api-duplicate-calls-prevention-uuid` must be a **fresh random UUID on
+every request** — the MCP mints one with `crypto.randomUUID()` per call, not
+once per session. Reusing a value risks HoneyBook treating a legitimate
+repeat as a duplicate.
+
+Ready-to-run commands for all four read endpoints are in
+`references/requests.md`.
+
+## The rules that matter
+
+- **401 → session expired.** Re-run the capture (magic link tab must still
+  be open and signed in).
+- **429 → rate limited.** `client.ts` waits 2s and retries once; do the same
+  before giving up.
+- **Body contains `"HBWrongAPIVersionError"` → stale `hb-api-client-version`.**
+  The error body itself carries the correct value at
+  `.error_data.server_api_version` — read that (or re-run the `/api/gon`
+  fetch above) and retry the SAME request with the fresh version.
+- **`sign_contract` / `pay_invoice` are not real API calls.** `honeybook-mcp`
+  can't replay HoneyBook's browser-side signing/SCA flow, so those tools just
+  return a deep link — `$PORTAL_ORIGIN/app/workspace_file/<file_id>/agreement`
+  (sign) or `/invoice` (pay) — for the user to open themselves. There's no
+  POST body to transcribe for either; don't invent one.
+
+## Output / exit-code contract
+
+- `fpx session`/`fpx pair`/`fpx health` are bridge round-trips: exit `0` on a
+  successful bridge read regardless of upstream status, `1` on a usage error
+  (bad flag, undeclared scope), `2` if the bridge/extension is unreachable or
+  pairing is still pending. There's no bot-wall (`3`)/upstream-HTTP (`4`)
+  exit code on these — HoneyBook's own API isn't bridge-walled.
+- The actual reads go through plain `curl` afterward — check the HTTP status
+  and the `HBWrongAPIVersionError` body text yourself, as above.
+
+## Notes
+
+- Session data (`AUTH_TOKEN`, `TRUSTED_DEVICE`, `FINGERPRINT`) is opaque and
+  long-lived server-side (no client-visible JWT expiry) — keep it in shell
+  variables, not a world-readable file, if you must persist it at all.
+- This project is developed and maintained by AI (Claude).

package/skills/honeybook-fpx/references/requests.md

@@ -0,0 +1,122 @@
+# HoneyBook requests for fpx + curl
+
+Ready-to-run commands for the four live read endpoints `honeybook-mcp`
+actually calls (from `src/tools/*.ts` + `src/client.ts`). All are
+`GET api.honeybook.com/api/v2/*`, carrying the eight headers built in
+`HoneyBookClient.request` — see `../SKILL.md` for how to capture
+`$AUTH_TOKEN`/`$USER_ID`/`$TRUSTED_DEVICE`/`$FINGERPRINT`/`$API_VERSION`
+first.
+
+```sh
+hb_get() {   # $1 = path (e.g. /api/v2/users/$USER_ID/workspace_files)
+  curl -s "https://api.honeybook.com$1" \
+    -H 'accept: application/json, text/plain, */*' \
+    -H "hb-api-auth-token: $AUTH_TOKEN" \
+    -H "hb-api-user-id: $USER_ID" \
+    -H "hb-trusted-device: $TRUSTED_DEVICE" \
+    -H "hb-api-client-version: $API_VERSION" \
+    -H "hb-api-fingerprint: $FINGERPRINT" \
+    -H "hb-api-duplicate-calls-prevention-uuid: $(uuidgen)" \
+    -H 'hb-admin-login: false'
+}
+```
+
+`sign_contract`/`pay_invoice` are **not** included below — the MCP itself
+doesn't call a signing/payment API; it returns a deep link
+(`$PORTAL_ORIGIN/app/workspace_file/<file_id>/agreement` or `/invoice`) for
+the user to open in their browser. There's no request shape to transcribe.
+
+---
+
+## 1. List a vendor's shared files
+
+`list_workspace_files` (`src/tools/workspace_files.ts`):
+
+```sh
+hb_get "/api/v2/users/$USER_ID/workspace_files" > /tmp/hb-files.json
+```
+
+Response envelope (`HBListEnvelope<T>`, `src/types.ts`):
+`{ data: [...], cur_page, last_page, last_id?, total_count? }`.
+**Pagination is not wired up** in the MCP either — if `last_page` is
+`false`, more results exist on later pages that neither the MCP nor this
+skill fetches.
+
+```sh
+# Filter to a file_type client-side (agreement | invoice | brochure | proposal)
+jq '[.data[] | select(.file_type == "agreement")]' /tmp/hb-files.json
+
+# Compact listing: id, type, title, accepted/paid flags
+jq -r '.data[] | [.["_id"], .file_type, .file_title, (.is_file_accepted|tostring), (.has_pending_payment|tostring)] | @tsv' /tmp/hb-files.json
+```
+
+## 2. Get one file's detail
+
+`get_workspace_file` (`src/tools/workspace_files.ts`):
+
+```sh
+hb_get "/api/v2/workspace_files/$FILE_ID" > /tmp/hb-file.json
+```
+
+The raw response is large on proposal-class files (a real one hit ~1.3 MB,
+mostly vendor-internal fields the MCP prunes off `company`:
+`vendor_emails`, `workflow_automation_infos`, `brochure_templates`,
+`questionnaires`, `lead_sources`, `proposals`, `agreements`, `invoices`,
+`vendor_packages`, `contact_forms`, `stripe_persons`,
+`user_pipeline_stages`, `project_types`, `company_assets`). Project what you
+need instead of dumping the whole body:
+
+```sh
+# Summary-equivalent: identity, status, vendor, event, pricing totals, payments
+jq '{
+  id: .["_id"], title: .file_title, type: .file_type,
+  status: .status_name, accepted: .is_file_accepted,
+  vendor: .company.company_name,
+  event: (.event | {date: .event_date, type, couple_names}),
+  total_price: .vendor_proposal.total_price,
+  payments: (.payments_container.payments // [] | map({due_date, amount, is_paid}))
+}' /tmp/hb-file.json
+
+# Full contract text + signatures (the "agreement" section)
+jq '.agreement' /tmp/hb-file.json
+
+# Full line items (the "pricing" section)
+jq '.vendor_proposal' /tmp/hb-file.json
+```
+
+## 3. Get a workspace (vendor project)
+
+`get_workspace` (`src/tools/workspaces.ts`) — `workspace_id` is
+`.workspace._id` on any workspace_file from endpoint 1 or 2:
+
+```sh
+hb_get "/api/v2/workspaces/$WORKSPACE_ID" \
+  | jq '{id: .["_id"], has_sent_files, has_signed_files, has_paid_payments}'
+```
+
+## 4. List saved payment methods
+
+`list_payment_methods` (`src/tools/payment_methods.ts`):
+
+```sh
+hb_get "/api/v2/users/$USER_ID/payment_methods" | jq '.'
+```
+
+Empty array (`[]`) if the client has no payment method saved with this
+vendor — not an error.
+
+---
+
+## Error shapes to check on every response
+
+```sh
+# Wrong API version — re-derive it from the error body itself (no /api/gon round-trip needed)
+jq -r 'select(type=="object") | .error_data.server_api_version // empty' /tmp/hb-resp.json
+
+# HTTP status: 401 = session expired (re-capture), 429 = rate limited (wait 2s, retry once)
+```
+
+A non-2xx HTTP status with a body matching `HBWrongAPIVersionError` means
+retry the *same* request with `hb-api-client-version` set to
+`.error_data.server_api_version` from the body (or a fresh `/api/gon` fetch,
+per `../SKILL.md`).