Milestone 0: import zappier billing, Verae middleware, and Zapier research

Compose-ready workspace: packages/zappier (rate card, portal, Stripe), packages/verae-zapier-middleware (timestamp + NATS), packages/verae-zapier (CLI app), vendor/zapier-platform, and research/zapier vendor corpus. Gate 0 structure checks pass. Product code and research are not yet wired.
2026-09-09 02:37:36 -04:00 · 2026-09-09 02:37:36 -04:00 · b4150c8250
commit b4150c8250
1364 changed files with 6814366 additions and 0 deletions
--- a/packages/verae-zapier-middleware/.env.example
+++ b/packages/verae-zapier-middleware/.env.example
@ -0,0 +1,30 @@
+# HTTP
+PORT=3100
+HOST=0.0.0.0
+
+# Upstream Verae
+VERAE_API_BASE_URL=https://api.veraetime.net
+MOCK_VERAE=false
+
+# NATS (Phase 7+)
+NATS_ENABLED=false
+NATS_URL=nats://127.0.0.1:4222
+
+# Security
+TOKEN_SECRET=change-me-in-production
+ADMIN_SECRET=change-me-admin
+
+# Job polling
+JOB_POLL_INTERVAL_MS=2000
+JOB_POLL_MAX_ATTEMPTS=60
+
+# Store
+STORE_PATH=./data/store.json
+
+# Billing UX
+UPGRADE_URL=https://veraetime.net/billing
+
+# Runtime debug (see docs/developer/debugging.md)
+# DEBUG_VERAE=auth,nats,jobs,webhooks,http,billing
+# DEBUG_VERAE_LEVEL=debug
+# DEBUG_VERAE_FILE=/tmp/verae-zapier-debug.log
--- a/packages/verae-zapier-middleware/Dockerfile
+++ b/packages/verae-zapier-middleware/Dockerfile
@ -0,0 +1,8 @@
+FROM node:22-alpine
+WORKDIR /app
+COPY package.json ./
+RUN npm install --omit=dev
+COPY src ./src
+ENV PORT=3100
+EXPOSE 3100
+CMD ["node", "src/index.js"]
--- a/packages/verae-zapier-middleware/package-lock.json
+++ b/packages/verae-zapier-middleware/package-lock.json
@ -0,0 +1,870 @@
+{
+  "name": "verae-zapier-middleware",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "verae-zapier-middleware",
+      "version": "0.1.0",
+      "license": "UNLICENSED",
+      "dependencies": {
+        "express": "^4.21.2",
+        "nats": "^2.28.2"
+      },
+      "engines": {
+        "node": ">=22.0.0"
+      },
+      "optionalDependencies": {
+        "nats": "^2.28.2"
+      }
+    },
+    "node_modules/accepts": {
+      "version": "1.3.8",
+      "resolved": "https://registry.npmjs.org/accepts/-/accepts-1.3.8.tgz",
+      "integrity": "sha512-PYAthTa2m2VKxuvSD3DPC/Gy+U+sOA1LAuT8mkmRuvw+NACSaeXEQ+NHcVF7rONl6qcaxV3Uuemwawk+7+SJLw==",
+      "license": "MIT",
+      "dependencies": {
+        "mime-types": "~2.1.34",
+        "negotiator": "0.6.3"
+      },
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/array-flatten": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/array-flatten/-/array-flatten-1.1.1.tgz",
+      "integrity": "sha512-PCVAQswWemu6UdxsDFFX/+gVeYqKAod3D3UVm91jHwynguOwAvYPhx8nNlM++NqRcK6CxxpUafjmhIdKiHibqg==",
+      "license": "MIT"
+    },
+    "node_modules/body-parser": {
+      "version": "1.20.6",
+      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.6.tgz",
+      "integrity": "sha512-p5tAzS57i5MV9fZFDj9LeIiTZEufbSe2eDozP+ElheSUq1m74CRq1jI4mYNDdVs9vQztXFLuk/Gd6BWTdwRJ5g==",
+      "license": "MIT",
+      "dependencies": {
+        "bytes": "~3.1.2",
+        "content-type": "~1.0.5",
+        "debug": "2.6.9",
+        "depd": "2.0.0",
+        "destroy": "~1.2.0",
+        "http-errors": "~2.0.1",
+        "iconv-lite": "~0.4.24",
+        "on-finished": "~2.4.1",
+        "qs": "~6.15.1",
+        "raw-body": "~2.5.3",
+        "type-is": "~1.6.18",
+        "unpipe": "~1.0.0"
+      },
+      "engines": {
+        "node": ">= 0.8",
+        "npm": "1.2.8000 || >= 1.4.16"
+      }
+    },
+    "node_modules/bytes": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz",
+      "integrity": "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/call-bind-apply-helpers": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz",
+      "integrity": "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==",
+      "license": "MIT",
+      "dependencies": {
+        "es-errors": "^1.3.0",
+        "function-bind": "^1.1.2"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/call-bound": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/call-bound/-/call-bound-1.0.4.tgz",
+      "integrity": "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==",
+      "license": "MIT",
+      "dependencies": {
+        "call-bind-apply-helpers": "^1.0.2",
+        "get-intrinsic": "^1.3.0"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/content-disposition": {
+      "version": "0.5.4",
+      "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-0.5.4.tgz",
+      "integrity": "sha512-FveZTNuGw04cxlAiWbzi6zTAL/lhehaWbTtgluJh4/E95DqMwTmha3KZN1aAWA8cFIhHzMZUvLevkw5Rqk+tSQ==",
+      "license": "MIT",
+      "dependencies": {
+        "safe-buffer": "5.2.1"
+      },
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/content-type": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/content-type/-/content-type-1.0.5.tgz",
+      "integrity": "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/cookie": {
+      "version": "0.7.2",
+      "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.2.tgz",
+      "integrity": "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/cookie-signature": {
+      "version": "1.0.7",
+      "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.0.7.tgz",
+      "integrity": "sha512-NXdYc3dLr47pBkpUCHtKSwIOQXLVn8dZEuywboCOJY/osA0wFSLlSawr3KN8qXJEyX66FcONTH8EIlVuK0yyFA==",
+      "license": "MIT"
+    },
+    "node_modules/debug": {
+      "version": "2.6.9",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz",
+      "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==",
+      "license": "MIT",
+      "dependencies": {
+        "ms": "2.0.0"
+      }
+    },
+    "node_modules/depd": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz",
+      "integrity": "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/destroy": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/destroy/-/destroy-1.2.0.tgz",
+      "integrity": "sha512-2sJGJTaXIIaR1w4iJSNoN0hnMY7Gpc/n8D4qSCJw8QqFWXf7cuAgnEHxBpweaVcPevC2l3KpjYCx3NypQQgaJg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8",
+        "npm": "1.2.8000 || >= 1.4.16"
+      }
+    },
+    "node_modules/dunder-proto": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
+      "integrity": "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==",
+      "license": "MIT",
+      "dependencies": {
+        "call-bind-apply-helpers": "^1.0.1",
+        "es-errors": "^1.3.0",
+        "gopd": "^1.2.0"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/ee-first": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/ee-first/-/ee-first-1.1.1.tgz",
+      "integrity": "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==",
+      "license": "MIT"
+    },
+    "node_modules/encodeurl": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/encodeurl/-/encodeurl-2.0.0.tgz",
+      "integrity": "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/es-define-property": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
+      "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/es-errors": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz",
+      "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/es-object-atoms": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.2.tgz",
+      "integrity": "sha512-HWcBoN6NileqtSydK2FqHbS/LoDd2pqrnQHLyJzBj4kOp/ky2MWMN694xOfkK8/SnUsW2DH7EfyVlydKCsm1Zw==",
+      "license": "MIT",
+      "dependencies": {
+        "es-errors": "^1.3.0"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/escape-html": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz",
+      "integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==",
+      "license": "MIT"
+    },
+    "node_modules/etag": {
+      "version": "1.8.1",
+      "resolved": "https://registry.npmjs.org/etag/-/etag-1.8.1.tgz",
+      "integrity": "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/express": {
+      "version": "4.22.2",
+      "resolved": "https://registry.npmjs.org/express/-/express-4.22.2.tgz",
+      "integrity": "sha512-IuL+Elrou2ZvCFHs18/CIzy2Nzvo25nZ1/D2eIZlz7c+QUayAcYoiM2BthCjs+EBHVpjYjcuLDAiCWgeIX3X1Q==",
+      "license": "MIT",
+      "dependencies": {
+        "accepts": "~1.3.8",
+        "array-flatten": "1.1.1",
+        "body-parser": "~1.20.5",
+        "content-disposition": "~0.5.4",
+        "content-type": "~1.0.4",
+        "cookie": "~0.7.1",
+        "cookie-signature": "~1.0.6",
+        "debug": "2.6.9",
+        "depd": "2.0.0",
+        "encodeurl": "~2.0.0",
+        "escape-html": "~1.0.3",
+        "etag": "~1.8.1",
+        "finalhandler": "~1.3.1",
+        "fresh": "~0.5.2",
+        "http-errors": "~2.0.0",
+        "merge-descriptors": "1.0.3",
+        "methods": "~1.1.2",
+        "on-finished": "~2.4.1",
+        "parseurl": "~1.3.3",
+        "path-to-regexp": "~0.1.12",
+        "proxy-addr": "~2.0.7",
+        "qs": "~6.15.1",
+        "range-parser": "~1.2.1",
+        "safe-buffer": "5.2.1",
+        "send": "~0.19.0",
+        "serve-static": "~1.16.2",
+        "setprototypeof": "1.2.0",
+        "statuses": "~2.0.1",
+        "type-is": "~1.6.18",
+        "utils-merge": "1.0.1",
+        "vary": "~1.1.2"
+      },
+      "engines": {
+        "node": ">= 0.10.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
+    "node_modules/finalhandler": {
+      "version": "1.3.2",
+      "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-1.3.2.tgz",
+      "integrity": "sha512-aA4RyPcd3badbdABGDuTXCMTtOneUCAYH/gxoYRTZlIJdF0YPWuGqiAsIrhNnnqdXGswYk6dGujem4w80UJFhg==",
+      "license": "MIT",
+      "dependencies": {
+        "debug": "2.6.9",
+        "encodeurl": "~2.0.0",
+        "escape-html": "~1.0.3",
+        "on-finished": "~2.4.1",
+        "parseurl": "~1.3.3",
+        "statuses": "~2.0.2",
+        "unpipe": "~1.0.0"
+      },
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/forwarded": {
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz",
+      "integrity": "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/fresh": {
+      "version": "0.5.2",
+      "resolved": "https://registry.npmjs.org/fresh/-/fresh-0.5.2.tgz",
+      "integrity": "sha512-zJ2mQYM18rEFOudeV4GShTGIQ7RbzA7ozbU9I/XBpm7kqgMywgmylMwXHxZJmkVoYkna9d2pVXVXPdYTP9ej8Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/function-bind": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz",
+      "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/get-intrinsic": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz",
+      "integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==",
+      "license": "MIT",
+      "dependencies": {
+        "call-bind-apply-helpers": "^1.0.2",
+        "es-define-property": "^1.0.1",
+        "es-errors": "^1.3.0",
+        "es-object-atoms": "^1.1.1",
+        "function-bind": "^1.1.2",
+        "get-proto": "^1.0.1",
+        "gopd": "^1.2.0",
+        "has-symbols": "^1.1.0",
+        "hasown": "^2.0.2",
+        "math-intrinsics": "^1.1.0"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/get-proto": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz",
+      "integrity": "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==",
+      "license": "MIT",
+      "dependencies": {
+        "dunder-proto": "^1.0.1",
+        "es-object-atoms": "^1.0.0"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/gopd": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
+      "integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/has-symbols": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz",
+      "integrity": "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/hasown": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.4.tgz",
+      "integrity": "sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==",
+      "license": "MIT",
+      "dependencies": {
+        "function-bind": "^1.1.2"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/http-errors": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz",
+      "integrity": "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==",
+      "license": "MIT",
+      "dependencies": {
+        "depd": "~2.0.0",
+        "inherits": "~2.0.4",
+        "setprototypeof": "~1.2.0",
+        "statuses": "~2.0.2",
+        "toidentifier": "~1.0.1"
+      },
+      "engines": {
+        "node": ">= 0.8"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
+    "node_modules/iconv-lite": {
+      "version": "0.4.24",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.4.24.tgz",
+      "integrity": "sha512-v3MXnZAcvnywkTUEZomIActle7RXXeedOR31wwl7VlyoXO4Qi9arvSenNQWne1TcRwhCL1HwLI21bEqdpj8/rA==",
+      "license": "MIT",
+      "dependencies": {
+        "safer-buffer": ">= 2.1.2 < 3"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/inherits": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
+      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
+      "license": "ISC"
+    },
+    "node_modules/ipaddr.js": {
+      "version": "1.9.1",
+      "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz",
+      "integrity": "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.10"
+      }
+    },
+    "node_modules/math-intrinsics": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
+      "integrity": "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/media-typer": {
+      "version": "0.3.0",
+      "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-0.3.0.tgz",
+      "integrity": "sha512-dq+qelQ9akHpcOl/gUVRTxVIOkAJ1wR3QAvb4RsVjS8oVoFjDGTc679wJYmUmknUF5HwMLOgb5O+a3KxfWapPQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/merge-descriptors": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/merge-descriptors/-/merge-descriptors-1.0.3.tgz",
+      "integrity": "sha512-gaNvAS7TZ897/rVaZ0nMtAyxNyi/pdbjbAwUpFQpN70GqnVfOiXpeUUMKRBmzXaSQ8DdTX4/0ms62r2K+hE6mQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/methods": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/methods/-/methods-1.1.2.tgz",
+      "integrity": "sha512-iclAHeNqNm68zFtnZ0e+1L2yUIdvzNoauKU4WBA3VvH/vPFieF7qfRlwUZU+DA9P9bPXIS90ulxoUoCH23sV2w==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/mime": {
+      "version": "1.6.0",
+      "resolved": "https://registry.npmjs.org/mime/-/mime-1.6.0.tgz",
+      "integrity": "sha512-x0Vn8spI+wuJ1O6S7gnbaQg8Pxh4NNHb7KSINmEWKiPE4RKOplvijn+NkmYmmRgP68mc70j2EbeTFRsrswaQeg==",
+      "license": "MIT",
+      "bin": {
+        "mime": "cli.js"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/mime-db": {
+      "version": "1.52.0",
+      "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz",
+      "integrity": "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/mime-types": {
+      "version": "2.1.35",
+      "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-2.1.35.tgz",
+      "integrity": "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==",
+      "license": "MIT",
+      "dependencies": {
+        "mime-db": "1.52.0"
+      },
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/ms": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz",
+      "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==",
+      "license": "MIT"
+    },
+    "node_modules/nats": {
+      "version": "2.28.2",
+      "resolved": "https://registry.npmjs.org/nats/-/nats-2.28.2.tgz",
+      "integrity": "sha512-02cvR8EPach+0BfVaQjPgsbPFn6uMjEQAuvXS2ppg8jiWEm2KYdfmeFmtshiU9b2+kFh3LSEKMEaIfRgk3K8tw==",
+      "deprecated": "Package moved. Use @nats-io/transport-node from https://github.com/nats-io/nats.js",
+      "license": "Apache-2.0",
+      "optional": true,
+      "dependencies": {
+        "nkeys.js": "1.1.0"
+      },
+      "engines": {
+        "node": ">= 14.0.0"
+      }
+    },
+    "node_modules/negotiator": {
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-0.6.3.tgz",
+      "integrity": "sha512-+EUsqGPLsM+j/zdChZjsnX51g4XrHFOIXwfnCVPGlQk/k5giakcKsuxCObBRu6DSm9opw/O6slWbJdghQM4bBg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/nkeys.js": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/nkeys.js/-/nkeys.js-1.1.0.tgz",
+      "integrity": "sha512-tB/a0shZL5UZWSwsoeyqfTszONTt4k2YS0tuQioMOD180+MbombYVgzDUYHlx+gejYK6rgf08n/2Df99WY0Sxg==",
+      "license": "Apache-2.0",
+      "optional": true,
+      "dependencies": {
+        "tweetnacl": "1.0.3"
+      },
+      "engines": {
+        "node": ">=10.0.0"
+      }
+    },
+    "node_modules/object-inspect": {
+      "version": "1.13.4",
+      "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz",
+      "integrity": "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/on-finished": {
+      "version": "2.4.1",
+      "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz",
+      "integrity": "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==",
+      "license": "MIT",
+      "dependencies": {
+        "ee-first": "1.1.1"
+      },
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/parseurl": {
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz",
+      "integrity": "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/path-to-regexp": {
+      "version": "0.1.13",
+      "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-0.1.13.tgz",
+      "integrity": "sha512-A/AGNMFN3c8bOlvV9RreMdrv7jsmF9XIfDeCd87+I8RNg6s78BhJxMu69NEMHBSJFxKidViTEdruRwEk/WIKqA==",
+      "license": "MIT"
+    },
+    "node_modules/proxy-addr": {
+      "version": "2.0.7",
+      "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz",
+      "integrity": "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==",
+      "license": "MIT",
+      "dependencies": {
+        "forwarded": "0.2.0",
+        "ipaddr.js": "1.9.1"
+      },
+      "engines": {
+        "node": ">= 0.10"
+      }
+    },
+    "node_modules/qs": {
+      "version": "6.15.3",
+      "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.3.tgz",
+      "integrity": "sha512-O9gl3zCl5h5blw1KGUzQKhA5oUXSl8rwUIM5o0S3nCXMliSvy5Dzx7/DJcI+SwgICv+IneSZwhBh1oSyEHA71A==",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "es-define-property": "^1.0.1",
+        "side-channel": "^1.1.1"
+      },
+      "engines": {
+        "node": ">=0.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/range-parser": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.2.1.tgz",
+      "integrity": "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/raw-body": {
+      "version": "2.5.3",
+      "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-2.5.3.tgz",
+      "integrity": "sha512-s4VSOf6yN0rvbRZGxs8Om5CWj6seneMwK3oDb4lWDH0UPhWcxwOWw5+qk24bxq87szX1ydrwylIOp2uG1ojUpA==",
+      "license": "MIT",
+      "dependencies": {
+        "bytes": "~3.1.2",
+        "http-errors": "~2.0.1",
+        "iconv-lite": "~0.4.24",
+        "unpipe": "~1.0.0"
+      },
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/safe-buffer": {
+      "version": "5.2.1",
+      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
+      "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/safer-buffer": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
+      "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
+      "license": "MIT"
+    },
+    "node_modules/send": {
+      "version": "0.19.2",
+      "resolved": "https://registry.npmjs.org/send/-/send-0.19.2.tgz",
+      "integrity": "sha512-VMbMxbDeehAxpOtWJXlcUS5E8iXh6QmN+BkRX1GARS3wRaXEEgzCcB10gTQazO42tpNIya8xIyNx8fll1OFPrg==",
+      "license": "MIT",
+      "dependencies": {
+        "debug": "2.6.9",
+        "depd": "2.0.0",
+        "destroy": "1.2.0",
+        "encodeurl": "~2.0.0",
+        "escape-html": "~1.0.3",
+        "etag": "~1.8.1",
+        "fresh": "~0.5.2",
+        "http-errors": "~2.0.1",
+        "mime": "1.6.0",
+        "ms": "2.1.3",
+        "on-finished": "~2.4.1",
+        "range-parser": "~1.2.1",
+        "statuses": "~2.0.2"
+      },
+      "engines": {
+        "node": ">= 0.8.0"
+      }
+    },
+    "node_modules/send/node_modules/ms": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+      "license": "MIT"
+    },
+    "node_modules/serve-static": {
+      "version": "1.16.3",
+      "resolved": "https://registry.npmjs.org/serve-static/-/serve-static-1.16.3.tgz",
+      "integrity": "sha512-x0RTqQel6g5SY7Lg6ZreMmsOzncHFU7nhnRWkKgWuMTu5NN0DR5oruckMqRvacAN9d5w6ARnRBXl9xhDCgfMeA==",
+      "license": "MIT",
+      "dependencies": {
+        "encodeurl": "~2.0.0",
+        "escape-html": "~1.0.3",
+        "parseurl": "~1.3.3",
+        "send": "~0.19.1"
+      },
+      "engines": {
+        "node": ">= 0.8.0"
+      }
+    },
+    "node_modules/setprototypeof": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz",
+      "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==",
+      "license": "ISC"
+    },
+    "node_modules/side-channel": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.1.tgz",
+      "integrity": "sha512-6x6dK6zJdpTzF4sQeNYxwtvBzf6Eg4GtlesS94HOvTudUeyK2WXAaIfmDgsyslYrRBeFIlsi54AYsFGUuhmvrQ==",
+      "license": "MIT",
+      "dependencies": {
+        "es-errors": "^1.3.0",
+        "object-inspect": "^1.13.4",
+        "side-channel-list": "^1.0.1",
+        "side-channel-map": "^1.0.1",
+        "side-channel-weakmap": "^1.0.2"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/side-channel-list": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.1.tgz",
+      "integrity": "sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==",
+      "license": "MIT",
+      "dependencies": {
+        "es-errors": "^1.3.0",
+        "object-inspect": "^1.13.4"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/side-channel-map": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/side-channel-map/-/side-channel-map-1.0.1.tgz",
+      "integrity": "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==",
+      "license": "MIT",
+      "dependencies": {
+        "call-bound": "^1.0.2",
+        "es-errors": "^1.3.0",
+        "get-intrinsic": "^1.2.5",
+        "object-inspect": "^1.13.3"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/side-channel-weakmap": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/side-channel-weakmap/-/side-channel-weakmap-1.0.2.tgz",
+      "integrity": "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==",
+      "license": "MIT",
+      "dependencies": {
+        "call-bound": "^1.0.2",
+        "es-errors": "^1.3.0",
+        "get-intrinsic": "^1.2.5",
+        "object-inspect": "^1.13.3",
+        "side-channel-map": "^1.0.1"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/statuses": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz",
+      "integrity": "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/toidentifier": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz",
+      "integrity": "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.6"
+      }
+    },
+    "node_modules/tweetnacl": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/tweetnacl/-/tweetnacl-1.0.3.tgz",
+      "integrity": "sha512-6rt+RN7aOi1nGMyC4Xa5DdYiukl2UWCbcJft7YhxReBGQD7OAM8Pbxw6YMo4r2diNEA8FEmu32YOn9rhaiE5yw==",
+      "license": "Unlicense",
+      "optional": true
+    },
+    "node_modules/type-is": {
+      "version": "1.6.18",
+      "resolved": "https://registry.npmjs.org/type-is/-/type-is-1.6.18.tgz",
+      "integrity": "sha512-TkRKr9sUTxEH8MdfuCSP7VizJyzRNMjj2J2do2Jr3Kym598JVdEksuzPQCnlFPW4ky9Q+iA+ma9BGm06XQBy8g==",
+      "license": "MIT",
+      "dependencies": {
+        "media-typer": "0.3.0",
+        "mime-types": "~2.1.24"
+      },
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/unpipe": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz",
+      "integrity": "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/utils-merge": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/utils-merge/-/utils-merge-1.0.1.tgz",
+      "integrity": "sha512-pMZTvIkT1d+TFGvDOqodOclx0QWkkgi6Tdoa8gC8ffGAAqz9pzPTZWAybbsHHoED/ztMtkv/VoYTYyShUn81hA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4.0"
+      }
+    },
+    "node_modules/vary": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz",
+      "integrity": "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    }
+  }
+}
--- a/packages/verae-zapier-middleware/package.json
+++ b/packages/verae-zapier-middleware/package.json
@ -0,0 +1,37 @@
+{
+  "name": "verae-zapier-middleware",
+  "version": "0.1.0",
+  "description": "HTTP edge + NATS workers bridging Zapier and api.veraetime.net",
+  "type": "module",
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "test": "MOCK_VERAE=true NATS_ENABLED=false node --test test/unit/**/*.test.js test/integration/auth.test.js test/integration/http-api.test.js",
+    "test:unit": "MOCK_VERAE=true NATS_ENABLED=false node --test test/unit/**/*.test.js",
+    "test:gate1": "node --test test/unit/debug.test.js",
+    "test:gate2": "MOCK_VERAE=true node --test test/unit/config.test.js test/unit/app.test.js",
+    "test:gate3": "MOCK_VERAE=true NATS_ENABLED=false node --test test/unit/store.test.js",
+    "test:gate4": "MOCK_VERAE=true NATS_ENABLED=false node --test test/unit/tokens.test.js test/unit/veraeClient.test.js",
+    "test:gate5": "MOCK_VERAE=true NATS_ENABLED=false node --test test/integration/auth.test.js",
+    "test:gate6": "MOCK_VERAE=true NATS_ENABLED=false JOB_POLL_INTERVAL_MS=20 JOB_POLL_MAX_ATTEMPTS=50 node --test test/integration/http-api.test.js",
+    "test:gate7": "MOCK_VERAE=true NATS_ENABLED=true NATS_FORCE_CONNECT=1 NATS_URL=nats://127.0.0.1:4222 node --test test/integration/nats.test.js",
+    "test:gate8": "MOCK_VERAE=true NATS_ENABLED=true NATS_FORCE_CONNECT=1 NATS_URL=nats://127.0.0.1:4222 JOB_POLL_INTERVAL_MS=50 node --test test/integration/nats-workers.test.js",
+    "test:gate10": "MOCK_VERAE=true NATS_ENABLED=false node --test test/integration/tenants.test.js"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "express": "^4.21.2",
+    "nats": "^2.28.2"
+  },
+  "keywords": [
+    "verae",
+    "zapier",
+    "middleware",
+    "nats",
+    "timestamping"
+  ],
+  "license": "UNLICENSED"
+}
--- a/packages/verae-zapier-middleware/src/app.js
+++ b/packages/verae-zapier-middleware/src/app.js
@ -0,0 +1,50 @@
+/**
+ * @fileoverview Express application factory for the Zapier-facing HTTP edge.
+ * @module app
+ */
+
+import express from 'express';
+import { sendError } from './errors.js';
+import { createDebugger } from './debug/logger.js';
+import { traceMiddleware } from './debug/trace.js';
+import { apiRoutes } from './routes/index.js';
+import { loadStore } from './store/db.js';
+
+const log = createDebugger('app');
+
+/**
+ * Create the Express app (does not listen).
+ *
+ * @param {{ load?: boolean }} [options]
+ * @returns {import('express').Express}
+ */
+export function createApp(options = {}) {
+  if (options.load !== false) {
+    loadStore();
+  }
+
+  const app = express();
+  app.disable('x-powered-by');
+
+  app.use(express.json({ limit: '1mb' }));
+  app.use(traceMiddleware);
+
+  /**
+   * Liveness probe.
+   */
+  app.get('/health', (_req, res) => {
+    res.json({
+      status: 'ok',
+      service: 'verae-zapier-middleware',
+    });
+  });
+
+  app.use('/zapier', apiRoutes);
+
+  app.use((err, _req, res, _next) => {
+    sendError(res, err);
+  });
+
+  log.info('express app created');
+  return app;
+}
--- a/packages/verae-zapier-middleware/src/clients/veraeClient.js
+++ b/packages/verae-zapier-middleware/src/clients/veraeClient.js
@ -0,0 +1,287 @@
+/**
+ * @fileoverview HTTP client for api.veraetime.net (with mock mode).
+ * @module clients/veraeClient
+ */
+
+import { randomUUID } from 'node:crypto';
+import { config } from '../config.js';
+import { AppError } from '../errors.js';
+import { createDebugger } from '../debug/logger.js';
+
+const log = createDebugger('http');
+
+const mockJobs = new Map();
+
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function mockLogin({ username, password }) {
+  if (!username || !password) {
+    throw new AppError('Invalid credentials', { status: 401, code: 'UNAUTHORIZED' });
+  }
+  const expiresAt = new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString();
+  return {
+    token: `mock-jwt-${username}`,
+    expiresAt,
+    user: {
+      id: randomUUID(),
+      username,
+      role: username.includes('admin') ? 'admin' : 'user',
+    },
+  };
+}
+
+async function mockValidate(token) {
+  if (!token?.startsWith('mock-jwt-')) {
+    throw new AppError('Invalid or expired token', { status: 401, code: 'UNAUTHORIZED' });
+  }
+  const username = token.replace('mock-jwt-', '');
+  return {
+    valid: true,
+    userId: randomUUID(),
+    username,
+    role: 'user',
+    expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
+  };
+}
+
+async function mockCreateTimestamp({ data, hashAlg }) {
+  if (!data) {
+    throw new AppError('Invalid input data', { status: 400, code: 'VALIDATION_ERROR' });
+  }
+  const jobId = randomUUID();
+  mockJobs.set(jobId, {
+    id: jobId,
+    status: 'pending',
+    createdAt: Date.now(),
+    data,
+    hashAlg: hashAlg ?? 'SHA256',
+  });
+
+  setTimeout(() => {
+    const job = mockJobs.get(jobId);
+    if (!job) return;
+    job.status = 'completed';
+    job.result = `mock-cert-${jobId}`;
+    job.completedAt = new Date().toISOString();
+    job.metadata = {
+      blockIndex: 42,
+      timestamp: job.completedAt,
+      certificate: job.result,
+    };
+  }, 150);
+
+  return { jobId };
+}
+
+async function mockGetStatus(jobId) {
+  const job = mockJobs.get(jobId);
+  if (!job) {
+    throw new AppError('Job not found', { status: 404, code: 'NOT_FOUND' });
+  }
+  return {
+    id: job.id,
+    status: job.status,
+    result: job.result,
+    completedAt: job.completedAt,
+    metadata: job.metadata,
+    error: job.error,
+  };
+}
+
+async function mockVerify({ certificate }) {
+  if (!certificate) {
+    throw new AppError('Invalid input data', { status: 400, code: 'VALIDATION_ERROR' });
+  }
+  const valid = certificate.startsWith('mock-cert-') || certificate.startsWith('eyJ');
+  return valid
+    ? { valid: true, timestamp: new Date().toISOString(), blockIndex: 42 }
+    : { valid: false };
+}
+
+/**
+ * Low-level fetch to Verae API.
+ * @param {string} path
+ * @param {{ method?: string, token?: string, body?: unknown }} [options]
+ * @returns {Promise<any>}
+ */
+async function request(path, { method = 'GET', token, body } = {}) {
+  const url = `${config.veraeApiBaseUrl}${path}`;
+  const headers = { Accept: 'application/json' };
+
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+  if (body !== undefined) {
+    headers['Content-Type'] = 'application/json';
+  }
+
+  const started = Date.now();
+  log.debug('verae request', { method, path, hasToken: Boolean(token) });
+
+  const response = await fetch(url, {
+    method,
+    headers,
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+
+  let payload = null;
+  const text = await response.text();
+  if (text) {
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      payload = { error: text };
+    }
+  }
+
+  log.debug('verae response', {
+    method,
+    path,
+    status: response.status,
+    durationMs: Date.now() - started,
+  });
+
+  if (!response.ok) {
+    throw new AppError(payload?.error ?? `Verae API error (${response.status})`, {
+      status: response.status,
+      code: payload?.code ?? 'VERAE_API_ERROR',
+      details: payload,
+    });
+  }
+
+  return payload;
+}
+
+/**
+ * Verae API client (mock when config.mockVerae is true).
+ */
+export const veraeClient = {
+  /**
+   * @param {{ username: string, password: string }} credentials
+   */
+  async login(credentials) {
+    if (config.mockVerae) return mockLogin(credentials);
+    return request('/auth/login', { method: 'POST', body: credentials });
+  },
+
+  /**
+   * @param {string} token
+   */
+  async validate(token) {
+    if (config.mockVerae) return mockValidate(token);
+    return request('/auth/validate', { token });
+  },
+
+  /**
+   * @param {string} token
+   * @param {{ data: string, hashAlg?: string }} body
+   */
+  async createTimestamp(token, body) {
+    if (config.mockVerae) return mockCreateTimestamp(body);
+    return request('/api/timestamp', { method: 'POST', token, body });
+  },
+
+  /**
+   * @param {string} token
+   * @param {{ items: Array<{ data: string, hashAlg?: string }> }} body
+   */
+  async createBatchTimestamp(token, body) {
+    if (config.mockVerae) {
+      const jobIds = [];
+      for (const item of body.items ?? []) {
+        const res = await mockCreateTimestamp(item);
+        jobIds.push(res.jobId);
+      }
+      return { jobIds };
+    }
+    return request('/api/batch/timestamp', { method: 'POST', token, body });
+  },
+
+  /**
+   * @param {string} token
+   * @param {string} jobId
+   */
+  async getStatus(token, jobId) {
+    if (config.mockVerae) return mockGetStatus(jobId);
+    return request(`/api/status/${encodeURIComponent(jobId)}`, { token });
+  },
+
+  /**
+   * @param {string} token
+   * @param {{ jobIds: string[] }} body
+   */
+  async getBatchStatus(token, body) {
+    if (config.mockVerae) {
+      const results = {};
+      for (const jobId of body.jobIds ?? []) {
+        results[jobId] = await mockGetStatus(jobId);
+      }
+      return { results };
+    }
+    return request('/api/batch/status', { method: 'POST', token, body });
+  },
+
+  /**
+   * @param {string} token
+   * @param {{ certificate: string }} body
+   */
+  async verify(token, body) {
+    if (config.mockVerae) return mockVerify(body);
+    return request('/api/verify', { method: 'POST', token, body });
+  },
+
+  /**
+   * @param {string} token
+   * @param {{ certificates: string[] }} body
+   */
+  async verifyBatch(token, body) {
+    if (config.mockVerae) {
+      const results = [];
+      for (const certificate of body.certificates ?? []) {
+        results.push(await mockVerify({ certificate }));
+      }
+      return { results };
+    }
+    return request('/api/batch/verify', { method: 'POST', token, body });
+  },
+
+  /**
+   * @param {string} token
+   * @param {string} jobId
+   */
+  async getJobVerification(token, jobId) {
+    if (config.mockVerae) return mockGetStatus(jobId);
+    return request(`/api/verify/${encodeURIComponent(jobId)}`, { token });
+  },
+
+  /**
+   * Poll until completed/failed or timeout.
+   * @param {string} token
+   * @param {string} jobId
+   * @param {{ maxAttempts: number, intervalMs: number }} options
+   */
+  async waitForJob(token, jobId, { maxAttempts, intervalMs }) {
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      const status = await this.getStatus(token, jobId);
+      if (status.status === 'completed' || status.status === 'failed') {
+        return status;
+      }
+      await delay(intervalMs);
+    }
+    throw new AppError(`Job ${jobId} timed out`, { status: 504, code: 'GATEWAY_TIMEOUT' });
+  },
+};
+
+/**
+ * Clear mock jobs (tests only).
+ * @returns {void}
+ */
+export function clearMockJobs() {
+  mockJobs.clear();
+}
--- a/packages/verae-zapier-middleware/src/config.js
+++ b/packages/verae-zapier-middleware/src/config.js
@ -0,0 +1,142 @@
+/**
+ * @fileoverview Process configuration for the Verae Zapier middleware.
+ * @module config
+ *
+ * Loads optional `.env` then exports typed settings used by HTTP, NATS, and workers.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createDebugger } from './debug/logger.js';
+
+const log = createDebugger('app');
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const rootDir = resolve(__dirname, '..');
+
+/**
+ * Load KEY=VALUE pairs from `.env` without overriding existing process.env keys.
+ * @returns {void}
+ */
+export function loadEnvFile() {
+  const envPath = resolve(rootDir, '.env');
+  if (!existsSync(envPath)) return;
+
+  for (const line of readFileSync(envPath, 'utf8').split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    const value = trimmed.slice(eq + 1).trim();
+    if (!(key in process.env)) {
+      process.env[key] = value;
+    }
+  }
+}
+
+loadEnvFile();
+
+/**
+ * @param {string|undefined} value
+ * @param {boolean} [fallback=false]
+ * @returns {boolean}
+ */
+function bool(value, fallback = false) {
+  if (value === undefined) return fallback;
+  return ['1', 'true', 'yes', 'on'].includes(String(value).toLowerCase());
+}
+
+/**
+ * @param {string|undefined} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+function int(value, fallback) {
+  const parsed = Number.parseInt(value ?? '', 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+/**
+ * Runtime configuration object.
+ * @type {{
+ *   port: number,
+ *   host: string,
+ *   veraeApiBaseUrl: string,
+ *   mockVerae: boolean,
+ *   natsEnabled: boolean,
+ *   natsUrl: string,
+ *   tokenSecret: string,
+ *   jobPollIntervalMs: number,
+ *   jobPollMaxAttempts: number,
+ *   storePath: string,
+ *   upgradeUrl: string,
+ *   adminSecret: string,
+ * }}
+ */
+export const config = {
+  port: int(process.env.PORT, 3100),
+  host: process.env.HOST ?? '0.0.0.0',
+  veraeApiBaseUrl: (process.env.VERAE_API_BASE_URL ?? 'http://localhost:8080').replace(
+    /\/$/,
+    '',
+  ),
+  mockVerae: bool(process.env.MOCK_VERAE, false),
+  natsEnabled: bool(process.env.NATS_ENABLED, false),
+  natsUrl: process.env.NATS_URL ?? 'nats://127.0.0.1:4222',
+  tokenSecret: process.env.TOKEN_SECRET ?? 'dev-secret-change-me',
+  jobPollIntervalMs: int(process.env.JOB_POLL_INTERVAL_MS, 2000),
+  jobPollMaxAttempts: int(process.env.JOB_POLL_MAX_ATTEMPTS, 60),
+  storePath: resolve(rootDir, process.env.STORE_PATH ?? './data/store.json'),
+  upgradeUrl: process.env.UPGRADE_URL ?? 'https://veraetime.net/billing',
+  adminSecret: process.env.ADMIN_SECRET ?? 'change-me-admin',
+};
+
+/**
+ * Default plan limits. `null` numeric fields mean unlimited.
+ * @type {Record<string, {
+ *   timestamps: number|null,
+ *   verifications: number|null,
+ *   batch: boolean,
+ *   batchMaxItems: number|null,
+ *   requestsPerMinute: number
+ * }>}
+ */
+export const PLAN_LIMITS = {
+  free: {
+    timestamps: 50,
+    verifications: 50,
+    batch: false,
+    batchMaxItems: 0,
+    requestsPerMinute: 30,
+  },
+  starter: {
+    timestamps: 500,
+    verifications: 500,
+    batch: true,
+    batchMaxItems: 10,
+    requestsPerMinute: 120,
+  },
+  pro: {
+    timestamps: 5000,
+    verifications: 5000,
+    batch: true,
+    batchMaxItems: 100,
+    requestsPerMinute: 600,
+  },
+  enterprise: {
+    timestamps: null,
+    verifications: null,
+    batch: true,
+    batchMaxItems: null,
+    requestsPerMinute: 3000,
+  },
+};
+
+log.info('config loaded', {
+  veraeApiBaseUrl: config.veraeApiBaseUrl,
+  mockVerae: config.mockVerae,
+  natsEnabled: config.natsEnabled,
+  natsUrl: config.natsUrl,
+  port: config.port,
+});
--- a/packages/verae-zapier-middleware/src/debug/config.js
+++ b/packages/verae-zapier-middleware/src/debug/config.js
@ -0,0 +1,106 @@
+/**
+ * @fileoverview Runtime debug configuration.
+ *
+ * Reads process environment at call time of {@link loadDebugConfig} so tests can
+ * mutate `process.env` between cases. Production servers typically load once at boot.
+ *
+ * @module debug/config
+ */
+
+/**
+ * @typedef {Object} DebugConfig
+ * @property {boolean} enabled - True when any debug output should be produced.
+ * @property {Set<string>|null} namespaces - Allowed namespaces; `null` means all.
+ * @property {'debug'|'info'|'warn'|'error'} level - Minimum severity to emit.
+ * @property {string|null} filePath - Optional secondary log file path.
+ */
+
+const LEVEL_ORDER = { debug: 10, info: 20, warn: 30, error: 40 };
+
+/**
+ * Parse `DEBUG_VERAE` into an enabled flag and optional namespace allow-list.
+ *
+ * @param {string|undefined} raw - Raw env value (e.g. `"1"`, `"*"`, `"auth,nats"`).
+ * @returns {{ enabled: boolean, namespaces: Set<string>|null }}
+ *
+ * @example
+ * parseDebugVeraeEnv('auth,jobs'); // { enabled: true, namespaces: Set{'auth','jobs'} }
+ * parseDebugVeraeEnv(undefined);   // { enabled: false, namespaces: null }
+ */
+export function parseDebugVeraeEnv(raw) {
+  if (raw === undefined || raw === null) {
+    return { enabled: false, namespaces: null };
+  }
+
+  const trimmed = String(raw).trim();
+  if (!trimmed || trimmed === '0' || trimmed.toLowerCase() === 'false' || trimmed.toLowerCase() === 'off') {
+    return { enabled: false, namespaces: null };
+  }
+
+  if (trimmed === '1' || trimmed === '*' || trimmed.toLowerCase() === 'true' || trimmed.toLowerCase() === 'all') {
+    return { enabled: true, namespaces: null };
+  }
+
+  const parts = trimmed
+    .split(',')
+    .map((p) => p.trim().toLowerCase())
+    .filter(Boolean);
+
+  if (parts.length === 0) {
+    return { enabled: false, namespaces: null };
+  }
+
+  return { enabled: true, namespaces: new Set(parts) };
+}
+
+/**
+ * Normalize a level string to a known level.
+ *
+ * @param {string|undefined} raw - Env level value.
+ * @param {'debug'|'info'|'warn'|'error'} [fallback='debug'] - Default level.
+ * @returns {'debug'|'info'|'warn'|'error'}
+ */
+export function parseLevel(raw, fallback = 'debug') {
+  const value = String(raw ?? fallback).toLowerCase();
+  if (value in LEVEL_ORDER) return /** @type {'debug'|'info'|'warn'|'error'} */ (value);
+  return fallback;
+}
+
+/**
+ * Load full debug configuration from `process.env`.
+ *
+ * Environment variables:
+ * - `DEBUG_VERAE` — enable + namespaces (see {@link parseDebugVeraeEnv})
+ * - `DEBUG_VERAE_LEVEL` — minimum level
+ * - `DEBUG_VERAE_FILE` — optional log file path
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env] - Environment map (injectable for tests).
+ * @returns {DebugConfig}
+ */
+export function loadDebugConfig(env = process.env) {
+  const { enabled, namespaces } = parseDebugVeraeEnv(env.DEBUG_VERAE);
+  return {
+    enabled,
+    namespaces,
+    level: parseLevel(env.DEBUG_VERAE_LEVEL, 'debug'),
+    filePath: env.DEBUG_VERAE_FILE ? String(env.DEBUG_VERAE_FILE) : null,
+  };
+}
+
+/**
+ * Whether a message at `messageLevel` in `namespace` should be emitted.
+ *
+ * @param {DebugConfig} config - Active config.
+ * @param {string} namespace - Logger namespace (e.g. `auth`).
+ * @param {'debug'|'info'|'warn'|'error'} messageLevel - Message severity.
+ * @returns {boolean}
+ */
+export function shouldLog(config, namespace, messageLevel) {
+  if (!config.enabled) return false;
+  if (config.namespaces && !config.namespaces.has(String(namespace).toLowerCase())) {
+    return false;
+  }
+  return LEVEL_ORDER[messageLevel] >= LEVEL_ORDER[config.level];
+}
+
+export { LEVEL_ORDER };
--- a/packages/verae-zapier-middleware/src/debug/index.js
+++ b/packages/verae-zapier-middleware/src/debug/index.js
@ -0,0 +1,24 @@
+/**
+ * @fileoverview Public exports for the runtime debug facility.
+ * @module debug
+ */
+
+export {
+  loadDebugConfig,
+  parseDebugVeraeEnv,
+  parseLevel,
+  shouldLog,
+  LEVEL_ORDER,
+} from './config.js';
+
+export { createDebugger, formatLogLine, setDebugTestSink } from './logger.js';
+
+export { redact, redactString } from './redact.js';
+
+export {
+  generateTraceId,
+  getTraceId,
+  getTraceContext,
+  withTrace,
+  traceMiddleware,
+} from './trace.js';
--- a/packages/verae-zapier-middleware/src/debug/logger.js
+++ b/packages/verae-zapier-middleware/src/debug/logger.js
@ -0,0 +1,121 @@
+/**
+ * @fileoverview Namespaced debug logger with runtime enable/disable.
+ * @module debug/logger
+ */
+
+import { appendFileSync } from 'node:fs';
+import { loadDebugConfig, shouldLog } from './config.js';
+import { redact } from './redact.js';
+import { getTraceId } from './trace-context.js';
+
+/**
+ * @typedef {Object} Debugger
+ * @property {(msg: string, meta?: Record<string, unknown>) => void} debug
+ * @property {(msg: string, meta?: Record<string, unknown>) => void} info
+ * @property {(msg: string, meta?: Record<string, unknown>) => void} warn
+ * @property {(msg: string, meta?: Record<string, unknown>) => void} error
+ * @property {string} namespace
+ */
+
+/**
+ * Optional sink for tests — when set, lines go here instead of/in addition to stderr.
+ * @type {null|((line: string) => void)}
+ */
+let testSink = null;
+
+/**
+ * Install a test sink that captures formatted log lines.
+ * Used only by unit tests; do not use in production code.
+ *
+ * @param {null|((line: string) => void)} sink - Callback or null to clear.
+ * @returns {void}
+ */
+export function setDebugTestSink(sink) {
+  testSink = sink;
+}
+
+/**
+ * Format a single log line.
+ *
+ * @param {object} parts
+ * @param {string} parts.level
+ * @param {string} parts.namespace
+ * @param {string} parts.message
+ * @param {Record<string, unknown>|undefined} parts.meta
+ * @param {string|null} parts.traceId
+ * @returns {string}
+ */
+export function formatLogLine({ level, namespace, message, meta, traceId }) {
+  const ts = new Date().toISOString();
+  const tracePart = traceId ? ` [trace=${traceId}]` : '';
+  const metaPart =
+    meta && Object.keys(meta).length > 0 ? ` ${JSON.stringify(redact(meta))}` : '';
+  return `${ts} ${level.toUpperCase()} ${namespace}${tracePart} ${message}${metaPart}`;
+}
+
+/**
+ * Emit a log line to stderr, optional file, and optional test sink.
+ *
+ * @param {string} line - Full formatted line.
+ * @param {string|null} filePath - Optional file from config.
+ * @returns {void}
+ */
+function emit(line, filePath) {
+  if (testSink) {
+    testSink(line);
+  } else {
+    // eslint-disable-next-line no-console
+    console.error(line);
+  }
+  if (filePath) {
+    try {
+      appendFileSync(filePath, `${line}\n`, 'utf8');
+    } catch {
+      // ignore file errors in debug path
+    }
+  }
+}
+
+/**
+ * Create a namespaced debugger bound to current env configuration.
+ *
+ * Configuration is re-read on every log call so tests can toggle `DEBUG_VERAE`
+ * without reloading modules. Slight cost is acceptable for debug-only paths.
+ *
+ * @param {string} namespace - Namespace such as `auth`, `nats`, `jobs`.
+ * @returns {Debugger} Logger with debug/info/warn/error methods.
+ *
+ * @example
+ * const log = createDebugger('jobs');
+ * log.debug('poll start', { jobId: 'abc' });
+ */
+export function createDebugger(namespace) {
+  const ns = String(namespace || 'app').toLowerCase();
+
+  /**
+   * @param {'debug'|'info'|'warn'|'error'} level
+   * @param {string} message
+   * @param {Record<string, unknown>} [meta]
+   */
+  function write(level, message, meta) {
+    const config = loadDebugConfig();
+    if (!shouldLog(config, ns, level)) return;
+
+    const line = formatLogLine({
+      level,
+      namespace: ns,
+      message: String(message),
+      meta,
+      traceId: getTraceId(),
+    });
+    emit(line, config.filePath);
+  }
+
+  return {
+    namespace: ns,
+    debug: (message, meta) => write('debug', message, meta),
+    info: (message, meta) => write('info', message, meta),
+    warn: (message, meta) => write('warn', message, meta),
+    error: (message, meta) => write('error', message, meta),
+  };
+}
--- a/packages/verae-zapier-middleware/src/debug/redact.js
+++ b/packages/verae-zapier-middleware/src/debug/redact.js
@ -0,0 +1,93 @@
+/**
+ * @fileoverview Secret redaction for debug logs.
+ * @module debug/redact
+ */
+
+const SENSITIVE_KEYS = new Set([
+  'password',
+  'veraepassword',
+  'token',
+  'veraetoken',
+  'accesstoken',
+  'apikey',
+  'api_key',
+  'secret',
+  'authorization',
+  'x-api-key',
+  'cookie',
+  'sessionkey',
+]);
+
+const BEARER_RE = /^Bearer\s+.+/i;
+const API_KEY_RE = /^zmw_[A-Za-z0-9_-]+/;
+const SESSION_RE = /^zmt_[A-Za-z0-9_.-]+/;
+const JWT_RE = /^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/;
+
+/**
+ * Redact a single string value if it looks like a secret.
+ *
+ * @param {string} value - Raw string.
+ * @returns {string} Original or `[REDACTED]`.
+ */
+export function redactString(value) {
+  if (typeof value !== 'string') return value;
+  if (
+    BEARER_RE.test(value) ||
+    API_KEY_RE.test(value) ||
+    SESSION_RE.test(value) ||
+    JWT_RE.test(value)
+  ) {
+    return '[REDACTED]';
+  }
+  return value;
+}
+
+/**
+ * Deep-clone plain data structures while redacting sensitive keys and values.
+ *
+ * @param {unknown} input - Any JSON-like value.
+ * @param {number} [depth=0] - Recursion depth guard.
+ * @returns {unknown} Redacted structure safe for logging.
+ *
+ * @example
+ * redact({ password: 'x', jobId: '1' }); // { password: '[REDACTED]', jobId: '1' }
+ */
+export function redact(input, depth = 0) {
+  if (depth > 8) return '[MaxDepth]';
+
+  if (input === null || input === undefined) return input;
+
+  if (typeof input === 'string') return redactString(input);
+
+  if (typeof input === 'number' || typeof input === 'boolean') return input;
+
+  if (input instanceof Error) {
+    return { name: input.name, message: redactString(input.message), stack: undefined };
+  }
+
+  if (Array.isArray(input)) {
+    return input.map((item) => redact(item, depth + 1));
+  }
+
+  if (typeof input === 'object') {
+    /** @type {Record<string, unknown>} */
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+      if (SENSITIVE_KEYS.has(key.toLowerCase())) {
+        out[key] = '[REDACTED]';
+      } else if (key.toLowerCase() === 'targeturl' && typeof value === 'string') {
+        try {
+          const u = new URL(value);
+          out[key] = `${u.origin}${u.pathname}`;
+        } catch {
+          out[key] = '[REDACTED_URL]';
+        }
+      } else {
+        out[key] = redact(value, depth + 1);
+      }
+    }
+    return out;
+  }
+
+  return String(input);
+}
--- a/packages/verae-zapier-middleware/src/debug/trace-context.js
+++ b/packages/verae-zapier-middleware/src/debug/trace-context.js
@ -0,0 +1,39 @@
+/**
+ * @fileoverview AsyncLocalStorage-backed trace context (no logger dependency).
+ * Split from trace.js to avoid circular imports with logger.js.
+ * @module debug/trace-context
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomBytes } from 'node:crypto';
+
+/**
+ * @typedef {Object} TraceContext
+ * @property {string} traceId
+ * @property {string} [span]
+ */
+
+/** @type {AsyncLocalStorage<TraceContext>} */
+export const traceStorage = new AsyncLocalStorage();
+
+/**
+ * Generate a short opaque trace id (16 hex chars).
+ * @returns {string}
+ */
+export function generateTraceId() {
+  return randomBytes(8).toString('hex');
+}
+
+/**
+ * @returns {string|null}
+ */
+export function getTraceId() {
+  return traceStorage.getStore()?.traceId ?? null;
+}
+
+/**
+ * @returns {TraceContext|null}
+ */
+export function getTraceContext() {
+  return traceStorage.getStore() ?? null;
+}
--- a/packages/verae-zapier-middleware/src/debug/trace.js
+++ b/packages/verae-zapier-middleware/src/debug/trace.js
@ -0,0 +1,95 @@
+/**
+ * @fileoverview Correlation / trace IDs for failure tracing across HTTP and NATS.
+ * @module debug/trace
+ */
+
+import { createDebugger } from './logger.js';
+import {
+  traceStorage,
+  generateTraceId,
+  getTraceId,
+  getTraceContext,
+} from './trace-context.js';
+
+export { generateTraceId, getTraceId, getTraceContext };
+
+const log = createDebugger('trace');
+
+/**
+ * Run `fn` within a trace context. Nested calls inherit the same `traceId`
+ * unless `traceId` is explicitly overridden.
+ *
+ * @template T
+ * @param {object|(() => T|Promise<T>)} options - Options or the callback itself.
+ * @param {string} [options.traceId] - Existing id (e.g. from `X-Trace-Id` header).
+ * @param {string} [options.span] - Human label for this span (logged when debug on).
+ * @param {() => T|Promise<T>} [fn] - Work to execute inside the context when options is an object.
+ * @returns {T|Promise<T>} Return value of `fn`.
+ *
+ * @example
+ * await withTrace({ span: 'timestamp.wait', traceId: req.headers['x-trace-id'] }, async () => {
+ *   // getTraceId() is stable here and in awaited children
+ * });
+ */
+export function withTrace(options, fn) {
+  const opts = typeof options === 'function' ? {} : options ?? {};
+  const callback = typeof options === 'function' ? options : fn;
+
+  if (typeof callback !== 'function') {
+    throw new TypeError('withTrace requires a function to execute');
+  }
+
+  const parent = traceStorage.getStore();
+  const traceId = opts.traceId || parent?.traceId || generateTraceId();
+  const span = opts.span || parent?.span || 'root';
+
+  const ctx = { traceId, span };
+
+  return traceStorage.run(ctx, () => {
+    log.debug('span enter', { span });
+    try {
+      const result = callback();
+      if (result && typeof result.then === 'function') {
+        return result.then(
+          (value) => {
+            log.debug('span exit', { span, ok: true });
+            return value;
+          },
+          (err) => {
+            log.debug('span exit', { span, ok: false, error: err?.message });
+            throw err;
+          },
+        );
+      }
+      log.debug('span exit', { span, ok: true });
+      return result;
+    } catch (err) {
+      log.debug('span exit', { span, ok: false, error: err?.message });
+      throw err;
+    }
+  });
+}
+
+/**
+ * Express middleware that establishes a trace context per request.
+ *
+ * Reads `X-Trace-Id` when present; otherwise generates a new id.
+ * Sets `req.traceId` and response header `X-Trace-Id`.
+ *
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {import('express').NextFunction} next
+ * @returns {void}
+ */
+export function traceMiddleware(req, res, next) {
+  const incoming = req.headers['x-trace-id'];
+  const traceId =
+    typeof incoming === 'string' && incoming.trim() ? incoming.trim() : generateTraceId();
+
+  req.traceId = traceId;
+  res.setHeader('X-Trace-Id', traceId);
+
+  withTrace({ traceId, span: `${req.method} ${req.path}` }, () => {
+    next();
+  });
+}
--- a/packages/verae-zapier-middleware/src/errors.js
+++ b/packages/verae-zapier-middleware/src/errors.js
@ -0,0 +1,75 @@
+/**
+ * @fileoverview Structured errors and Express helpers.
+ * @module errors
+ */
+
+import { createDebugger } from './debug/logger.js';
+import { getTraceId } from './debug/trace-context.js';
+
+const log = createDebugger('app');
+
+/**
+ * Operational error with HTTP status and machine-readable code.
+ */
+export class AppError extends Error {
+  /**
+   * @param {string} message - Human-readable error.
+   * @param {object} [options]
+   * @param {number} [options.status=500] - HTTP status code.
+   * @param {string} [options.code='INTERNAL_ERROR'] - Machine code.
+   * @param {unknown} [options.details] - Optional structured details (safe for clients).
+   */
+  constructor(message, { status = 500, code = 'INTERNAL_ERROR', details } = {}) {
+    super(message);
+    this.name = 'AppError';
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+}
+
+/**
+ * Wrap an async Express handler so rejected promises reach the error middleware.
+ *
+ * @param {(req: import('express').Request, res: import('express').Response, next: import('express').NextFunction) => Promise<unknown>} fn
+ * @returns {import('express').RequestHandler}
+ */
+export function asyncHandler(fn) {
+  return (req, res, next) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+}
+
+/**
+ * Send a JSON error response. Logs server errors when debug is enabled.
+ *
+ * @param {import('express').Response} res
+ * @param {Error|AppError} err
+ * @returns {void}
+ */
+export function sendError(res, err) {
+  const status = err instanceof AppError ? err.status : 500;
+  const code = err instanceof AppError ? err.code : 'INTERNAL_ERROR';
+  const message = err?.message || 'Internal server error';
+  const details = err instanceof AppError ? err.details : undefined;
+  const traceId = getTraceId();
+
+  if (status >= 500) {
+    log.error('request failed', {
+      status,
+      code,
+      message,
+      traceId,
+      stack: err?.stack,
+    });
+  } else {
+    log.debug('client error', { status, code, message, traceId });
+  }
+
+  res.status(status).json({
+    error: message,
+    code,
+    ...(details !== undefined ? { details } : {}),
+    ...(traceId ? { traceId } : {}),
+  });
+}
--- a/packages/verae-zapier-middleware/src/index.js
+++ b/packages/verae-zapier-middleware/src/index.js
@ -0,0 +1,51 @@
+/**
+ * @fileoverview Process entrypoint: HTTP listen + optional in-process poller.
+ * @module index
+ */
+
+import { createApp } from './app.js';
+import { config } from './config.js';
+import { createDebugger } from './debug/logger.js';
+import { startInProcessJobPoller } from './workers/inProcessJobPoller.js';
+import { connectNats, ensureStreams } from './nats/connection.js';
+import { startJobPollerWorker } from './workers/jobPollerWorker.js';
+import { startWebhookWorker } from './workers/webhookWorker.js';
+
+const log = createDebugger('app');
+
+/**
+ * Start the HTTP server and background workers.
+ * @returns {import('http').Server}
+ */
+export function startServer() {
+  const app = createApp();
+
+  if (config.natsEnabled) {
+    connectNats()
+      .then(({ jsm }) => ensureStreams(jsm))
+      .then(() => Promise.all([startJobPollerWorker(), startWebhookWorker()]))
+      .then(() => log.info('NATS workers started'))
+      .catch((err) => log.error('NATS worker start failed', { error: err.message }));
+  } else {
+    startInProcessJobPoller();
+  }
+
+  const server = app.listen(config.port, config.host, () => {
+    log.info('middleware listening', {
+      host: config.host,
+      port: config.port,
+      veraeApiBaseUrl: config.veraeApiBaseUrl,
+      mockVerae: config.mockVerae,
+      natsEnabled: config.natsEnabled,
+    });
+    // eslint-disable-next-line no-console
+    console.log(
+      `Verae Zapier middleware listening on http://${config.host}:${config.port}`,
+    );
+  });
+  return server;
+}
+
+if (process.argv[1]?.includes('index.js')) {
+  startServer();
+}
--- a/packages/verae-zapier-middleware/src/lib/tokens.js
+++ b/packages/verae-zapier-middleware/src/lib/tokens.js
@ -0,0 +1,97 @@
+/**
+ * @fileoverview API keys and HMAC session tokens for the middleware auth bridge.
+ * @module lib/tokens
+ */
+
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { config } from '../config.js';
+
+const TOKEN_PREFIX = 'zmt_';
+const API_KEY_PREFIX = 'zmw_';
+
+/**
+ * @param {string} payload
+ * @returns {string}
+ */
+function sign(payload) {
+  return createHmac('sha256', config.tokenSecret).update(payload).digest('base64url');
+}
+
+/**
+ * Issue a signed middleware session token embedding tenant + Verae JWT.
+ *
+ * @param {object} params
+ * @param {string} params.tenantId
+ * @param {string} params.veraeToken
+ * @param {string} [params.expiresAt]
+ * @returns {string} Token string starting with `zmt_`
+ */
+export function issueSessionToken({ tenantId, veraeToken, expiresAt }) {
+  const payload = Buffer.from(
+    JSON.stringify({
+      tenantId,
+      veraeToken,
+      expiresAt,
+      nonce: randomBytes(8).toString('hex'),
+    }),
+  ).toString('base64url');
+  const signature = sign(payload);
+  return `${TOKEN_PREFIX}${payload}.${signature}`;
+}
+
+/**
+ * Parse and verify a session token.
+ *
+ * @param {string} token
+ * @returns {{ tenantId: string, veraeToken: string, expiresAt?: string, nonce?: string }|null}
+ */
+export function parseSessionToken(token) {
+  if (!token?.startsWith(TOKEN_PREFIX)) return null;
+
+  const raw = token.slice(TOKEN_PREFIX.length);
+  const dot = raw.lastIndexOf('.');
+  if (dot === -1) return null;
+
+  const payload = raw.slice(0, dot);
+  const signature = raw.slice(dot + 1);
+  const expected = sign(payload);
+
+  const sigBuf = Buffer.from(signature);
+  const expBuf = Buffer.from(expected);
+  if (sigBuf.length !== expBuf.length || !timingSafeEqual(sigBuf, expBuf)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Generate a new public API key (`zmw_…`).
+ * @returns {string}
+ */
+export function generateApiKey() {
+  return `${API_KEY_PREFIX}${randomBytes(24).toString('base64url')}`;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isApiKey(value) {
+  return typeof value === 'string' && value.startsWith(API_KEY_PREFIX);
+}
+
+/**
+ * Extract bearer credential from an Authorization header.
+ * @param {string|undefined} header
+ * @returns {string|null}
+ */
+export function extractBearerToken(header) {
+  if (!header) return null;
+  const match = String(header).match(/^Bearer\s+(.+)$/i);
+  return match?.[1] ?? null;
+}
--- a/packages/verae-zapier-middleware/src/middleware/authenticate.js
+++ b/packages/verae-zapier-middleware/src/middleware/authenticate.js
@ -0,0 +1,27 @@
+/**
+ * @fileoverview Express auth middleware — populates req.auth.
+ * @module middleware/authenticate
+ */
+
+import { extractBearerToken } from '../lib/tokens.js';
+import { resolveAuthContext } from '../services/authService.js';
+import { asyncHandler } from '../errors.js';
+import { createDebugger } from '../debug/logger.js';
+
+const log = createDebugger('auth');
+
+/**
+ * Resolve Bearer or x-api-key into `req.auth`.
+ */
+export const authenticate = asyncHandler(async (req, res, next) => {
+  const rawToken =
+    extractBearerToken(req.headers.authorization) ?? req.headers['x-api-key'] ?? null;
+
+  req.auth = await resolveAuthContext(rawToken);
+  log.debug('authenticated', {
+    tenantId: req.auth.tenantId,
+    method: req.auth.authMethod,
+    plan: req.auth.tenant?.plan,
+  });
+  next();
+});
--- a/packages/verae-zapier-middleware/src/middleware/rateLimit.js
+++ b/packages/verae-zapier-middleware/src/middleware/rateLimit.js
@ -0,0 +1,56 @@
+/**
+ * @fileoverview Simple in-memory per-tenant rate limiter.
+ * @module middleware/rateLimit
+ */
+
+import { AppError, asyncHandler } from '../errors.js';
+import { getTenant, resolveLimits } from '../store/tenants.js';
+import { createDebugger } from '../debug/logger.js';
+
+const log = createDebugger('billing');
+
+/** @type {Map<string, { windowStart: number, count: number }>} */
+const windows = new Map();
+
+/**
+ * Reset rate limit windows (tests).
+ * @returns {void}
+ */
+export function resetRateLimitWindows() {
+  windows.clear();
+}
+
+/**
+ * Enforce plan requestsPerMinute using a 60s sliding fixed window.
+ */
+export const rateLimit = asyncHandler(async (req, res, next) => {
+  const tenantId = req.auth?.tenantId;
+  if (!tenantId) return next();
+
+  const tenant = getTenant(tenantId);
+  const limits = tenant
+    ? resolveLimits(tenant)
+    : { requestsPerMinute: 30 };
+
+  const rpm = limits.requestsPerMinute ?? 30;
+  const now = Date.now();
+  const windowMs = 60_000;
+
+  let entry = windows.get(tenantId);
+  if (!entry || now - entry.windowStart >= windowMs) {
+    entry = { windowStart: now, count: 0 };
+    windows.set(tenantId, entry);
+  }
+
+  entry.count += 1;
+  if (entry.count > rpm) {
+    log.debug('rate limited', { tenantId, count: entry.count, rpm });
+    throw new AppError('Rate limit exceeded', {
+      status: 429,
+      code: 'RATE_LIMITED',
+      details: { requestsPerMinute: rpm },
+    });
+  }
+
+  next();
+});
--- a/packages/verae-zapier-middleware/src/nats/connection.js
+++ b/packages/verae-zapier-middleware/src/nats/connection.js
@ -0,0 +1,111 @@
+/**
+ * @fileoverview NATS + JetStream connection lifecycle.
+ * @module nats/connection
+ */
+
+import { createDebugger } from '../debug/logger.js';
+import { config } from '../config.js';
+import { SUBJECTS, STREAMS } from './subjects.js';
+
+const log = createDebugger('nats');
+
+/** @type {import('nats').NatsConnection|null} */
+let nc = null;
+/** @type {import('nats').JetStreamClient|null} */
+let js = null;
+/** @type {import('nats').JetStreamManager|null} */
+let jsm = null;
+
+/**
+ * Connect to NATS and return JetStream handles.
+ *
+ * @param {string} [url=config.natsUrl]
+ * @returns {Promise<{ nc: import('nats').NatsConnection, js: import('nats').JetStreamClient, jsm: import('nats').JetStreamManager }>}
+ */
+export async function connectNats(url = config.natsUrl) {
+  if (!config.natsEnabled && process.env.NATS_FORCE_CONNECT !== '1') {
+    log.debug('connect skipped — NATS_ENABLED=false');
+    throw new Error('NATS is disabled (NATS_ENABLED=false)');
+  }
+
+  if (nc && js && jsm) {
+    return { nc, js, jsm };
+  }
+
+  log.info('connecting to NATS', { url });
+
+  const { connect } = await import('nats');
+  nc = await connect({ servers: url, name: 'verae-zapier-middleware' });
+  js = nc.jetstream();
+  jsm = await nc.jetstreamManager();
+
+  log.info('NATS connected', { url });
+  return { nc, js, jsm };
+}
+
+/**
+ * Idempotently create JetStream streams required by this middleware.
+ *
+ * @param {import('nats').JetStreamManager} [manager]
+ * @returns {Promise<void>}
+ */
+export async function ensureStreams(manager) {
+  const m = manager ?? jsm;
+  if (!m) {
+    throw new Error('JetStream manager not available — call connectNats first');
+  }
+
+  /** @type {Array<{ name: string, subjects: string[] }>} */
+  const defs = [
+    { name: STREAMS.ZAPIER_JOBS, subjects: [SUBJECTS.JOBS_WATCH] },
+    { name: STREAMS.ZAPIER_EVENTS, subjects: [SUBJECTS.JOBS_EVENTS] },
+    { name: STREAMS.ZAPIER_WEBHOOKS, subjects: [SUBJECTS.WEBHOOKS_DELIVER] },
+  ];
+
+  for (const def of defs) {
+    try {
+      await m.streams.info(def.name);
+      log.debug('stream exists', { stream: def.name });
+    } catch {
+      await m.streams.add({
+        name: def.name,
+        subjects: def.subjects,
+        retention: 'limits',
+        storage: 'file',
+        max_age: 24 * 60 * 60 * 1e9, // 24h in ns
+        num_replicas: 1,
+      });
+      log.info('stream created', { stream: def.name, subjects: def.subjects });
+    }
+  }
+}
+
+/**
+ * Close the shared NATS connection if open.
+ * @returns {Promise<void>}
+ */
+export async function closeNats() {
+  if (!nc) {
+    log.debug('closeNats: no active connection');
+    return;
+  }
+  log.info('closing NATS connection');
+  await nc.drain();
+  nc = null;
+  js = null;
+  jsm = null;
+}
+
+/**
+ * @returns {import('nats').JetStreamClient|null}
+ */
+export function getJetStream() {
+  return js;
+}
+
+/**
+ * @returns {boolean}
+ */
+export function isNatsConnected() {
+  return Boolean(nc && !nc.isClosed());
+}
--- a/packages/verae-zapier-middleware/src/nats/publishers.js
+++ b/packages/verae-zapier-middleware/src/nats/publishers.js
@ -0,0 +1,95 @@
+/**
+ * @fileoverview JetStream publishers for jobs, events, and webhooks.
+ * @module nats/publishers
+ */
+
+import { createDebugger } from '../debug/logger.js';
+import { getTraceId } from '../debug/trace-context.js';
+import { SUBJECTS } from './subjects.js';
+import { getJetStream, connectNats } from './connection.js';
+
+const log = createDebugger('nats');
+
+/**
+ * @returns {Promise<import('nats').JetStreamClient>}
+ */
+async function requireJs() {
+  let js = getJetStream();
+  if (!js) {
+    const handles = await connectNats();
+    js = handles.js;
+  }
+  return js;
+}
+
+/**
+ * @param {object} partial
+ * @returns {Promise<{ seq: number }>}
+ */
+export async function enqueueWatch(partial) {
+  const msg = {
+    attempt: 0,
+    enqueuedAt: new Date().toISOString(),
+    traceId: getTraceId() || 'no-trace',
+    ...partial,
+  };
+
+  log.debug('enqueueWatch', {
+    subject: SUBJECTS.JOBS_WATCH,
+    tenantId: msg.tenantId,
+    jobId: msg.jobId,
+    attempt: msg.attempt,
+    traceId: msg.traceId,
+  });
+
+  const js = await requireJs();
+  const ack = await js.publish(SUBJECTS.JOBS_WATCH, JSON.stringify(msg));
+  return { seq: Number(ack.seq) };
+}
+
+/**
+ * @param {object} partial
+ * @returns {Promise<{ seq: number }>}
+ */
+export async function publishJobEvent(partial) {
+  const msg = {
+    emittedAt: new Date().toISOString(),
+    traceId: getTraceId() || 'no-trace',
+    ...partial,
+  };
+
+  log.debug('publishJobEvent', {
+    subject: SUBJECTS.JOBS_EVENTS,
+    event: msg.event,
+    jobId: msg.jobId,
+    tenantId: msg.tenantId,
+  });
+
+  const js = await requireJs();
+  const ack = await js.publish(SUBJECTS.JOBS_EVENTS, JSON.stringify(msg));
+  return { seq: Number(ack.seq) };
+}
+
+/**
+ * @param {object} partial
+ * @returns {Promise<{ seq: number }>}
+ */
+export async function enqueueWebhook(partial) {
+  const msg = {
+    attempt: 1,
+    traceId: getTraceId() || 'no-trace',
+    ...partial,
+  };
+
+  log.debug('enqueueWebhook', {
+    subject: SUBJECTS.WEBHOOKS_DELIVER,
+    hookId: msg.hookId,
+    tenantId: msg.tenantId,
+    event: msg.event,
+    targetUrl: msg.targetUrl,
+  });
+
+  const js = await requireJs();
+  const ack = await js.publish(SUBJECTS.WEBHOOKS_DELIVER, JSON.stringify(msg));
+  return { seq: Number(ack.seq) };
+}
--- a/packages/verae-zapier-middleware/src/nats/subjects.js
+++ b/packages/verae-zapier-middleware/src/nats/subjects.js
@ -0,0 +1,43 @@
+/**
+ * @fileoverview NATS subject and stream name constants.
+ * @module nats/subjects
+ *
+ * See docs/architecture/nats-subjects.md for payload schemas.
+ */
+
+/**
+ * Subject strings used by publishers and consumers.
+ * @readonly
+ */
+export const SUBJECTS = Object.freeze({
+  /** Work queue: poll Verae job status */
+  JOBS_WATCH: 'verae.zapier.jobs.watch',
+  /** Terminal job outcomes */
+  JOBS_EVENTS: 'verae.zapier.jobs.events',
+  /** Work queue: HTTP POST to Zapier REST Hooks */
+  WEBHOOKS_DELIVER: 'verae.zapier.webhooks.deliver',
+  /** Optional metering stream */
+  USAGE: 'verae.zapier.usage',
+});
+
+/**
+ * JetStream stream names.
+ * @readonly
+ */
+export const STREAMS = Object.freeze({
+  ZAPIER_JOBS: 'ZAPIER_JOBS',
+  ZAPIER_EVENTS: 'ZAPIER_EVENTS',
+  ZAPIER_WEBHOOKS: 'ZAPIER_WEBHOOKS',
+  ZAPIER_USAGE: 'ZAPIER_USAGE',
+});
+
+/**
+ * Durable consumer names (queue groups).
+ * @readonly
+ */
+export const CONSUMERS = Object.freeze({
+  JOB_POLLER: 'job-poller',
+  EVENT_WEBHOOK_ROUTER: 'event-webhook-router',
+  WEBHOOK_DELIVER: 'webhook-deliver',
+  USAGE_WRITER: 'usage-writer',
+});
--- a/packages/verae-zapier-middleware/src/routes/authRoutes.js
+++ b/packages/verae-zapier-middleware/src/routes/authRoutes.js
@ -0,0 +1,57 @@
+/**
+ * @fileoverview Auth routes under /zapier/v1/auth
+ * @module routes/authRoutes
+ */
+
+import { Router } from 'express';
+import { asyncHandler, AppError } from '../errors.js';
+import { loginWithCredentials, loginWithApiKey, validateSession } from '../services/authService.js';
+import { getUsageSummary } from '../store/usage.js';
+import { getTenant } from '../store/tenants.js';
+import { extractBearerToken } from '../lib/tokens.js';
+
+export const authRoutes = Router();
+
+authRoutes.post(
+  '/login',
+  asyncHandler(async (req, res) => {
+    const { username, password, api_key: apiKey } = req.body ?? {};
+
+    if (apiKey) {
+      const session = await loginWithApiKey(apiKey);
+      return res.json(session);
+    }
+
+    if (!username || !password) {
+      throw new AppError('username and password are required', {
+        status: 400,
+        code: 'VALIDATION_ERROR',
+      });
+    }
+
+    const session = await loginWithCredentials({ username, password });
+    res.json(session);
+  }),
+);
+
+authRoutes.get(
+  '/me',
+  asyncHandler(async (req, res) => {
+    const rawToken =
+      extractBearerToken(req.headers.authorization) ?? req.headers['x-api-key'] ?? null;
+
+    if (!rawToken) {
+      throw new AppError('Missing authorization token', { status: 401, code: 'UNAUTHORIZED' });
+    }
+
+    const validation = await validateSession(rawToken);
+    const tenant = getTenant(validation.tenantId);
+    const usage = getUsageSummary(validation.tenantId);
+
+    res.json({
+      ...validation,
+      plan: tenant?.plan ?? validation.plan ?? 'free',
+      usage,
+    });
+  }),
+);
--- a/packages/verae-zapier-middleware/src/routes/index.js
+++ b/packages/verae-zapier-middleware/src/routes/index.js
@ -0,0 +1,33 @@
+/**
+ * @fileoverview Mount all /zapier routes.
+ * @module routes/index
+ */
+
+import { Router } from 'express';
+import { authRoutes } from './authRoutes.js';
+import { timestampRoutes } from './timestampRoutes.js';
+import { verifyRoutes } from './verifyRoutes.js';
+import { statusRoutes } from './statusRoutes.js';
+import { webhookRoutes } from './webhookRoutes.js';
+import { publicTenantRoutes, adminTenantRoutes } from './tenantRoutes.js';
+import { authenticate } from '../middleware/authenticate.js';
+import { rateLimit } from '../middleware/rateLimit.js';
+
+export const apiRoutes = Router();
+
+// Public
+apiRoutes.use('/v1/auth', authRoutes);
+apiRoutes.use('/v1', publicTenantRoutes);
+apiRoutes.use('/v1/admin', adminTenantRoutes);
+
+// Protected
+const protectedRoutes = Router();
+protectedRoutes.use(authenticate);
+protectedRoutes.use(rateLimit);
+
+protectedRoutes.use('/timestamp', timestampRoutes);
+protectedRoutes.use('/verify', verifyRoutes);
+protectedRoutes.use('/status', statusRoutes);
+protectedRoutes.use('/webhooks', webhookRoutes);
+
+apiRoutes.use('/v1', protectedRoutes);
--- a/packages/verae-zapier-middleware/src/routes/statusRoutes.js
+++ b/packages/verae-zapier-middleware/src/routes/statusRoutes.js
@ -0,0 +1,46 @@
+/**
+ * @module routes/statusRoutes
+ */
+
+import { Router } from 'express';
+import { asyncHandler, AppError } from '../errors.js';
+import {
+  getJobStatus,
+  getBatchJobStatus,
+  getJobVerification,
+} from '../services/timestampService.js';
+
+export const statusRoutes = Router();
+
+// Static/more-specific routes first
+statusRoutes.post(
+  '/batch',
+  asyncHandler(async (req, res) => {
+    const { jobIds } = req.body ?? {};
+    if (!Array.isArray(jobIds) || jobIds.length === 0) {
+      throw new AppError('jobIds array is required', { status: 400, code: 'VALIDATION_ERROR' });
+    }
+    const result = await getBatchJobStatus(req.auth, { jobIds });
+    res.json(result);
+  }),
+);
+
+statusRoutes.get(
+  '/:jobId/verification',
+  asyncHandler(async (req, res) => {
+    const result = await getJobVerification(req.auth, req.params.jobId);
+    res.json(result);
+  }),
+);
+
+statusRoutes.get(
+  '/:jobId',
+  asyncHandler(async (req, res) => {
+    const { jobId } = req.params;
+    if (!jobId) {
+      throw new AppError('jobId is required', { status: 400, code: 'VALIDATION_ERROR' });
+    }
+    const result = await getJobStatus(req.auth, jobId);
+    res.json(result);
+  }),
+);
--- a/packages/verae-zapier-middleware/src/routes/tenantRoutes.js
+++ b/packages/verae-zapier-middleware/src/routes/tenantRoutes.js
@ -0,0 +1,46 @@
+/**
+ * @module routes/tenantRoutes
+ */
+
+import { Router } from 'express';
+import { asyncHandler, AppError } from '../errors.js';
+import {
+  selfServeSignup,
+  provisionTenant,
+  listProvisionedTenants,
+} from '../services/tenantService.js';
+import { config } from '../config.js';
+
+export const publicTenantRoutes = Router();
+export const adminTenantRoutes = Router();
+
+publicTenantRoutes.post(
+  '/signup',
+  asyncHandler(async (req, res) => {
+    const result = await selfServeSignup(req.body ?? {});
+    res.status(201).json(result);
+  }),
+);
+
+adminTenantRoutes.use((req, _res, next) => {
+  const secret = req.headers['x-admin-secret'];
+  if (secret !== config.adminSecret) {
+    return next(new AppError('Invalid admin secret', { status: 403, code: 'FORBIDDEN' }));
+  }
+  next();
+});
+
+adminTenantRoutes.post(
+  '/tenants',
+  asyncHandler(async (req, res) => {
+    const result = await provisionTenant(req.body ?? {});
+    res.status(201).json(result);
+  }),
+);
+
+adminTenantRoutes.get(
+  '/tenants',
+  asyncHandler(async (_req, res) => {
+    res.json({ tenants: listProvisionedTenants() });
+  }),
+);
--- a/packages/verae-zapier-middleware/src/routes/timestampRoutes.js
+++ b/packages/verae-zapier-middleware/src/routes/timestampRoutes.js
@ -0,0 +1,49 @@
+/**
+ * @module routes/timestampRoutes
+ */
+
+import { Router } from 'express';
+import { asyncHandler, AppError } from '../errors.js';
+import {
+  createTimestamp,
+  createTimestampAndWait,
+  createBatchTimestamp,
+} from '../services/timestampService.js';
+
+export const timestampRoutes = Router();
+
+timestampRoutes.post(
+  '/',
+  asyncHandler(async (req, res) => {
+    const { data, hashAlg } = req.body ?? {};
+    if (!data) {
+      throw new AppError('data is required', { status: 400, code: 'VALIDATION_ERROR' });
+    }
+    const result = await createTimestamp(req.auth, { data, hashAlg });
+    res.status(202).json(result);
+  }),
+);
+
+timestampRoutes.post(
+  '/wait',
+  asyncHandler(async (req, res) => {
+    const { data, hashAlg } = req.body ?? {};
+    if (!data) {
+      throw new AppError('data is required', { status: 400, code: 'VALIDATION_ERROR' });
+    }
+    const result = await createTimestampAndWait(req.auth, { data, hashAlg });
+    res.json(result);
+  }),
+);
+
+timestampRoutes.post(
+  '/batch',
+  asyncHandler(async (req, res) => {
+    const { items } = req.body ?? {};
+    if (!Array.isArray(items) || items.length === 0) {
+      throw new AppError('items array is required', { status: 400, code: 'VALIDATION_ERROR' });
+    }
+    const result = await createBatchTimestamp(req.auth, { items });
+    res.status(202).json(result);
+  }),
+);
--- a/packages/verae-zapier-middleware/src/routes/verifyRoutes.js
+++ b/packages/verae-zapier-middleware/src/routes/verifyRoutes.js
@ -0,0 +1,36 @@
+/**
+ * @module routes/verifyRoutes
+ */
+
+import { Router } from 'express';
+import { asyncHandler, AppError } from '../errors.js';
+import { verifyTimestamp, verifyBatch } from '../services/verifyService.js';
+
+export const verifyRoutes = Router();
+
+verifyRoutes.post(
+  '/',
+  asyncHandler(async (req, res) => {
+    const { certificate } = req.body ?? {};
+    if (!certificate) {
+      throw new AppError('certificate is required', { status: 400, code: 'VALIDATION_ERROR' });
+    }
+    const result = await verifyTimestamp(req.auth, { certificate });
+    res.json(result);
+  }),
+);
+
+verifyRoutes.post(
+  '/batch',
+  asyncHandler(async (req, res) => {
+    const { certificates } = req.body ?? {};
+    if (!Array.isArray(certificates) || certificates.length === 0) {
+      throw new AppError('certificates array is required', {
+        status: 400,
+        code: 'VALIDATION_ERROR',
+      });
+    }
+    const result = await verifyBatch(req.auth, { certificates });
+    res.json(result);
+  }),
+);
--- a/packages/verae-zapier-middleware/src/routes/webhookRoutes.js
+++ b/packages/verae-zapier-middleware/src/routes/webhookRoutes.js
@ -0,0 +1,44 @@
+/**
+ * @module routes/webhookRoutes
+ */
+
+import { Router } from 'express';
+import { asyncHandler, AppError } from '../errors.js';
+import { subscribe, unsubscribe } from '../services/webhookService.js';
+import { listWebhooksForTenant } from '../store/webhooks.js';
+
+export const webhookRoutes = Router();
+
+webhookRoutes.post(
+  '/subscribe',
+  asyncHandler(async (req, res) => {
+    const { targetUrl, event = 'timestamp.completed' } = req.body ?? {};
+    try {
+      const hook = subscribe(req.auth, { targetUrl, event });
+      res.status(201).json(hook);
+    } catch (err) {
+      throw new AppError(err.message, { status: 400, code: 'VALIDATION_ERROR' });
+    }
+  }),
+);
+
+webhookRoutes.delete(
+  '/unsubscribe',
+  asyncHandler(async (req, res) => {
+    const { hookId, targetUrl } = req.body ?? req.query ?? {};
+    try {
+      const result = unsubscribe(req.auth, { hookId, targetUrl });
+      res.json(result);
+    } catch (err) {
+      throw new AppError(err.message, { status: 404, code: 'NOT_FOUND' });
+    }
+  }),
+);
+
+webhookRoutes.get(
+  '/',
+  asyncHandler(async (req, res) => {
+    const hooks = listWebhooksForTenant(req.auth.tenantId);
+    res.json({ webhooks: hooks });
+  }),
+);
--- a/packages/verae-zapier-middleware/src/services/authService.js
+++ b/packages/verae-zapier-middleware/src/services/authService.js
@ -0,0 +1,141 @@
+/**
+ * @fileoverview Auth bridge: API keys / sessions → Verae JWT context.
+ * @module services/authService
+ */
+
+import { veraeClient } from '../clients/veraeClient.js';
+import { getTenantByApiKey, getTenant } from '../store/tenants.js';
+import { issueSessionToken, parseSessionToken, isApiKey } from '../lib/tokens.js';
+import { AppError } from '../errors.js';
+import { createDebugger } from '../debug/logger.js';
+
+const log = createDebugger('auth');
+
+/**
+ * Login with Verae username/password and issue middleware session token.
+ *
+ * @param {object} params
+ * @param {string} params.username
+ * @param {string} params.password
+ * @param {object} [params.tenant]
+ * @returns {Promise<{ accessToken: string, expiresAt: string, tenant: object, user: object }>}
+ */
+export async function loginWithCredentials({ username, password, tenant }) {
+  log.debug('loginWithCredentials', { username, tenantId: tenant?.id });
+
+  const verae = await veraeClient.login({ username, password });
+
+  if (tenant?.veraeUsername && tenant.veraeUsername !== username) {
+    throw new AppError('Credentials do not match tenant account', {
+      status: 403,
+      code: 'FORBIDDEN',
+    });
+  }
+
+  const tenantId = tenant?.id ?? `user:${verae.user.username}`;
+  const accessToken = issueSessionToken({
+    tenantId,
+    veraeToken: verae.token,
+    expiresAt: verae.expiresAt,
+  });
+
+  return {
+    accessToken,
+    expiresAt: verae.expiresAt,
+    tenant: tenant
+      ? { id: tenant.id, name: tenant.name, plan: tenant.plan }
+      : { id: tenantId, name: verae.user.username, plan: 'free' },
+    user: verae.user,
+  };
+}
+
+/**
+ * Resolve API key to tenant and login with stored Verae credentials.
+ * @param {string} apiKey
+ * @returns {Promise<Awaited<ReturnType<typeof loginWithCredentials>>>}
+ */
+export async function loginWithApiKey(apiKey) {
+  const tenant = getTenantByApiKey(apiKey);
+  if (!tenant) {
+    log.debug('invalid api key');
+    throw new AppError('Invalid API key', { status: 401, code: 'UNAUTHORIZED' });
+  }
+
+  if (!tenant.veraeUsername || !tenant.veraePassword) {
+    throw new AppError('Tenant is missing Verae credentials', {
+      status: 500,
+      code: 'TENANT_MISCONFIGURED',
+    });
+  }
+
+  log.debug('loginWithApiKey', { tenantId: tenant.id, plan: tenant.plan });
+  return loginWithCredentials({
+    username: tenant.veraeUsername,
+    password: tenant.veraePassword,
+    tenant,
+  });
+}
+
+/**
+ * Resolve bearer credential into request auth context.
+ *
+ * @param {string|null} rawToken
+ * @returns {Promise<{ tenantId: string, tenant: object, veraeToken: string, authMethod: string }>}
+ */
+export async function resolveAuthContext(rawToken) {
+  if (!rawToken) {
+    throw new AppError('Missing authorization token', { status: 401, code: 'UNAUTHORIZED' });
+  }
+
+  if (isApiKey(rawToken)) {
+    const session = await loginWithApiKey(rawToken);
+    const parsed = parseSessionToken(session.accessToken);
+    const tenant = getTenant(session.tenant.id) ?? session.tenant;
+    return {
+      tenantId: session.tenant.id,
+      tenant: { id: session.tenant.id, name: session.tenant.name, plan: session.tenant.plan },
+      veraeToken: parsed.veraeToken,
+      authMethod: 'api_key',
+      fullTenant: tenant,
+    };
+  }
+
+  const parsed = parseSessionToken(rawToken);
+  if (!parsed?.veraeToken) {
+    throw new AppError('Invalid or expired session token', { status: 401, code: 'UNAUTHORIZED' });
+  }
+
+  if (parsed.expiresAt && Date.parse(parsed.expiresAt) < Date.now()) {
+    throw new AppError('Session token expired', { status: 401, code: 'TOKEN_EXPIRED' });
+  }
+
+  const tenant = getTenant(parsed.tenantId);
+  log.debug('session auth', { tenantId: parsed.tenantId });
+  return {
+    tenantId: parsed.tenantId,
+    tenant: tenant
+      ? { id: tenant.id, name: tenant.name, plan: tenant.plan }
+      : { id: parsed.tenantId, plan: 'free' },
+    veraeToken: parsed.veraeToken,
+    authMethod: 'session',
+    fullTenant: tenant,
+  };
+}
+
+/**
+ * Validate auth and optionally ping Verae /auth/validate.
+ * @param {string} rawToken
+ * @returns {Promise<object>}
+ */
+export async function validateSession(rawToken) {
+  const context = await resolveAuthContext(rawToken);
+  const validation = await veraeClient.validate(context.veraeToken);
+
+  return {
+    valid: true,
+    tenantId: context.tenantId,
+    plan: context.tenant.plan,
+    authMethod: context.authMethod,
+    user: validation,
+  };
+}
--- a/packages/verae-zapier-middleware/src/services/entitlementService.js
+++ b/packages/verae-zapier-middleware/src/services/entitlementService.js
@ -0,0 +1,160 @@
+/**
+ * @fileoverview Plan quotas and usage recording.
+ * @module services/entitlementService
+ */
+
+import { config } from '../config.js';
+import { AppError } from '../errors.js';
+import { getTenant, resolveLimits } from '../store/tenants.js';
+import { getUsage, incrementUsage } from '../store/usage.js';
+import { createDebugger } from '../debug/logger.js';
+
+const log = createDebugger('billing');
+
+function isUnlimited(value) {
+  return value === null || value === undefined;
+}
+
+function quotaExceeded({ limit, used, allowOverage }) {
+  if (isUnlimited(limit)) return false;
+  if (used < limit) return false;
+  return !allowOverage;
+}
+
+/**
+ * Ensure tenant may perform an action under plan limits.
+ *
+ * @param {string} tenantId
+ * @param {'timestamp'|'verify'|'batch_timestamp'} action
+ * @param {{ amount?: number }} [options]
+ * @returns {{ tenant: object, limits: object, usage: object }}
+ */
+export function checkEntitlement(tenantId, action, { amount = 1 } = {}) {
+  const tenant = getTenant(tenantId);
+  if (!tenant) {
+    throw new AppError('Unknown tenant', { status: 401, code: 'UNAUTHORIZED' });
+  }
+
+  const limits = resolveLimits(tenant);
+  const usage = getUsage(tenantId);
+
+  log.debug('checkEntitlement', {
+    tenantId,
+    action,
+    plan: tenant.plan,
+    amount,
+    timestampsUsed: usage.timestamps,
+    timestampsLimit: limits.timestamps,
+  });
+
+  if (action === 'batch_timestamp') {
+    if (!limits.batch) {
+      throw new AppError('Batch timestamps require a paid plan', {
+        status: 403,
+        code: 'PLAN_UPGRADE_REQUIRED',
+        details: { upgradeUrl: config.upgradeUrl },
+      });
+    }
+    if (!isUnlimited(limits.batchMaxItems) && amount > limits.batchMaxItems) {
+      throw new AppError(`Batch size exceeds plan limit of ${limits.batchMaxItems}`, {
+        status: 403,
+        code: 'BATCH_LIMIT_EXCEEDED',
+        details: { upgradeUrl: config.upgradeUrl, limit: limits.batchMaxItems },
+      });
+    }
+  }
+
+  if (action === 'timestamp') {
+    if (
+      quotaExceeded({
+        limit: limits.timestamps,
+        used: usage.timestamps,
+        allowOverage: limits.allowOverage,
+      })
+    ) {
+      const err = new AppError('Monthly timestamp quota exceeded', {
+        status: 402,
+        code: 'QUOTA_EXCEEDED',
+        details: {
+          limit: limits.timestamps,
+          used: usage.timestamps,
+          period: 'monthly',
+          upgradeUrl: config.upgradeUrl,
+        },
+      });
+      throw err;
+    }
+  }
+
+  if (action === 'verify') {
+    if (
+      quotaExceeded({
+        limit: limits.verifications,
+        used: usage.verifications,
+        allowOverage: limits.allowOverage,
+      })
+    ) {
+      throw new AppError('Monthly verification quota exceeded', {
+        status: 402,
+        code: 'QUOTA_EXCEEDED',
+        details: {
+          limit: limits.verifications,
+          used: usage.verifications,
+          period: 'monthly',
+          upgradeUrl: config.upgradeUrl,
+        },
+      });
+    }
+  }
+
+  return { tenant, limits, usage };
+}
+
+/**
+ * Record usage after a successful action.
+ *
+ * @param {string} tenantId
+ * @param {string} action
+ * @param {{ amount?: number }} [options]
+ * @returns {void}
+ */
+export function recordUsage(tenantId, action, { amount = 1 } = {}) {
+  const tenant = getTenant(tenantId);
+  if (!tenant) return;
+
+  const limits = resolveLimits(tenant);
+  const usage = getUsage(tenantId);
+
+  if (action === 'timestamp') {
+    if (
+      !isUnlimited(limits.timestamps) &&
+      usage.timestamps >= limits.timestamps &&
+      limits.allowOverage
+    ) {
+      incrementUsage(tenantId, 'overage.timestamps', amount);
+    }
+    incrementUsage(tenantId, 'timestamps', amount);
+  }
+
+  if (action === 'verify') {
+    if (
+      !isUnlimited(limits.verifications) &&
+      usage.verifications >= limits.verifications &&
+      limits.allowOverage
+    ) {
+      incrementUsage(tenantId, 'overage.verifications', amount);
+    }
+    incrementUsage(tenantId, 'verifications', amount);
+  }
+
+  if (action === 'status') {
+    incrementUsage(tenantId, 'statusChecks', amount);
+  }
+
+  if (action === 'batch_timestamp') {
+    incrementUsage(tenantId, 'batchTimestamps', amount);
+    incrementUsage(tenantId, 'timestamps', amount);
+  }
+
+  log.debug('recordUsage', { tenantId, action, amount });
+}
--- a/packages/verae-zapier-middleware/src/services/tenantService.js
+++ b/packages/verae-zapier-middleware/src/services/tenantService.js
@ -0,0 +1,137 @@
+/**
+ * @fileoverview Self-serve signup and admin tenant provisioning.
+ * @module services/tenantService
+ */
+
+import { randomUUID } from 'node:crypto';
+import { createTenant, getTenant, listTenants } from '../store/tenants.js';
+import { veraeClient } from '../clients/veraeClient.js';
+import { AppError } from '../errors.js';
+import { createDebugger } from '../debug/logger.js';
+
+const log = createDebugger('auth');
+const ALLOWED_PLANS = new Set(['free', 'starter', 'pro', 'enterprise']);
+
+function slugify(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 48);
+}
+
+async function validateVeraeCredentials(username, password) {
+  try {
+    await veraeClient.login({ username, password });
+    return true;
+  } catch (err) {
+    throw new AppError('Invalid Verae credentials', {
+      status: 400,
+      code: 'INVALID_VERAE_CREDENTIALS',
+      details: { message: err.message },
+    });
+  }
+}
+
+/**
+ * Public free-tier signup.
+ * @param {{ email: string, name: string, veraeUsername: string, veraePassword: string }} params
+ */
+export async function selfServeSignup({ email, name, veraeUsername, veraePassword }) {
+  if (!email || !name || !veraeUsername || !veraePassword) {
+    throw new AppError('email, name, veraeUsername, and veraePassword are required', {
+      status: 400,
+      code: 'VALIDATION_ERROR',
+    });
+  }
+
+  await validateVeraeCredentials(veraeUsername, veraePassword);
+
+  const id = `tenant-${slugify(email)}-${randomUUID().slice(0, 8)}`;
+  const { tenant, apiKey } = createTenant({
+    id,
+    name,
+    plan: 'free',
+    veraeUsername,
+    veraePassword,
+    contract: null,
+    metadata: { email, audience: 'self-serve', createdVia: 'signup' },
+  });
+
+  log.info('self-serve signup', { tenantId: tenant.id });
+
+  return {
+    tenant: { id: tenant.id, name: tenant.name, plan: tenant.plan, email },
+    apiKey,
+    zapierSetup: {
+      authType: 'custom',
+      field: 'api_key',
+      middlewareUrl: '/zapier/v1/auth/me',
+    },
+  };
+}
+
+/**
+ * Admin provision (internal / enterprise).
+ */
+export async function provisionTenant({
+  id,
+  name,
+  plan,
+  veraeUsername,
+  veraePassword,
+  contract = null,
+  metadata = {},
+  audience = 'admin',
+}) {
+  if (!name || !plan || !veraeUsername || !veraePassword) {
+    throw new AppError('name, plan, veraeUsername, and veraePassword are required', {
+      status: 400,
+      code: 'VALIDATION_ERROR',
+    });
+  }
+
+  if (!ALLOWED_PLANS.has(plan)) {
+    throw new AppError(`Invalid plan: ${plan}`, { status: 400, code: 'VALIDATION_ERROR' });
+  }
+
+  if (plan === 'enterprise' && !contract) {
+    throw new AppError('enterprise tenants require a contract object', {
+      status: 400,
+      code: 'VALIDATION_ERROR',
+    });
+  }
+
+  await validateVeraeCredentials(veraeUsername, veraePassword);
+
+  const tenantId = id ?? `tenant-${slugify(name)}-${randomUUID().slice(0, 8)}`;
+  if (getTenant(tenantId)) {
+    throw new AppError('Tenant already exists', { status: 409, code: 'CONFLICT' });
+  }
+
+  const { tenant, apiKey } = createTenant({
+    id: tenantId,
+    name,
+    plan,
+    veraeUsername,
+    veraePassword,
+    contract,
+    metadata: { ...metadata, audience, createdVia: 'provision' },
+  });
+
+  log.info('tenant provisioned', { tenantId: tenant.id, plan, audience });
+  return { tenant: { id: tenant.id, name: tenant.name, plan: tenant.plan }, apiKey };
+}
+
+/**
+ * @returns {Array<object>}
+ */
+export function listProvisionedTenants() {
+  return listTenants().map((tenant) => ({
+    id: tenant.id,
+    name: tenant.name,
+    plan: tenant.plan,
+    audience: tenant.metadata?.audience ?? 'unknown',
+    createdAt: tenant.createdAt,
+  }));
+}
--- a/packages/verae-zapier-middleware/src/services/timestampService.js
+++ b/packages/verae-zapier-middleware/src/services/timestampService.js
@ -0,0 +1,122 @@
+/**
+ * @fileoverview Timestamp create/status operations with billing + job enqueue.
+ * @module services/timestampService
+ */
+
+import { config } from '../config.js';
+import { veraeClient } from '../clients/veraeClient.js';
+import { enqueueJob } from '../store/jobWatchers.js';
+import { checkEntitlement, recordUsage } from './entitlementService.js';
+import { createDebugger } from '../debug/logger.js';
+import { getTraceId } from '../debug/trace-context.js';
+
+const log = createDebugger('jobs');
+
+/**
+ * Enqueue async job watch via NATS or in-process store.
+ * @param {object} ctx
+ * @param {string} jobId
+ */
+async function enqueueWatchForJob(ctx, jobId) {
+  const traceId = getTraceId() ?? undefined;
+
+  if (config.natsEnabled) {
+    const { enqueueWatch } = await import('../nats/publishers.js');
+    await enqueueWatch({
+      tenantId: ctx.tenantId,
+      jobId,
+      // Prefer re-login in worker; include token for MVP simplicity when mock
+      veraeToken: ctx.veraeToken,
+      maxAttempts: config.jobPollMaxAttempts,
+      intervalMs: config.jobPollIntervalMs,
+      traceId,
+    });
+    log.debug('watch enqueued on NATS', { jobId, tenantId: ctx.tenantId });
+    return;
+  }
+
+  enqueueJob({
+    tenantId: ctx.tenantId,
+    jobId,
+    veraeToken: ctx.veraeToken,
+    traceId,
+  });
+}
+
+/**
+ * @param {object} ctx - Auth context with tenantId, veraeToken
+ * @param {{ data: string, hashAlg?: string }} body
+ * @returns {Promise<{ jobId: string }>}
+ */
+export async function createTimestamp(ctx, body) {
+  checkEntitlement(ctx.tenantId, 'timestamp');
+  const result = await veraeClient.createTimestamp(ctx.veraeToken, body);
+  recordUsage(ctx.tenantId, 'timestamp');
+
+  await enqueueWatchForJob(ctx, result.jobId);
+
+  log.debug('timestamp created', { jobId: result.jobId, tenantId: ctx.tenantId });
+  return result;
+}
+
+/**
+ * @param {object} ctx
+ * @param {{ data: string, hashAlg?: string }} body
+ * @returns {Promise<object>} StatusResponse
+ */
+export async function createTimestampAndWait(ctx, body) {
+  const created = await createTimestamp(ctx, body);
+  const status = await veraeClient.waitForJob(ctx.veraeToken, created.jobId, {
+    maxAttempts: config.jobPollMaxAttempts,
+    intervalMs: config.jobPollIntervalMs,
+  });
+  recordUsage(ctx.tenantId, 'status');
+  return status;
+}
+
+/**
+ * @param {object} ctx
+ * @param {{ items: Array<{ data: string, hashAlg?: string }> }} body
+ */
+export async function createBatchTimestamp(ctx, body) {
+  const itemCount = body.items?.length ?? 0;
+  checkEntitlement(ctx.tenantId, 'batch_timestamp', { amount: itemCount });
+  const result = await veraeClient.createBatchTimestamp(ctx.veraeToken, body);
+  recordUsage(ctx.tenantId, 'batch_timestamp', { amount: itemCount });
+
+  for (const jobId of result.jobIds ?? []) {
+    await enqueueWatchForJob(ctx, jobId);
+  }
+
+  return result;
+}
+
+/**
+ * @param {object} ctx
+ * @param {string} jobId
+ */
+export async function getJobStatus(ctx, jobId) {
+  const status = await veraeClient.getStatus(ctx.veraeToken, jobId);
+  recordUsage(ctx.tenantId, 'status');
+  return status;
+}
+
+/**
+ * @param {object} ctx
+ * @param {{ jobIds: string[] }} body
+ */
+export async function getBatchJobStatus(ctx, body) {
+  const status = await veraeClient.getBatchStatus(ctx.veraeToken, body);
+  recordUsage(ctx.tenantId, 'status', { amount: body.jobIds?.length ?? 1 });
+  return status;
+}
+
+/**
+ * @param {object} ctx
+ * @param {string} jobId
+ */
+export async function getJobVerification(ctx, jobId) {
+  const status = await veraeClient.getJobVerification(ctx.veraeToken, jobId);
+  recordUsage(ctx.tenantId, 'status');
+  return status;
+}
--- a/packages/verae-zapier-middleware/src/services/verifyService.js
+++ b/packages/verae-zapier-middleware/src/services/verifyService.js
@ -0,0 +1,34 @@
+/**
+ * @fileoverview Certificate verification with usage metering.
+ * @module services/verifyService
+ */
+
+import { veraeClient } from '../clients/veraeClient.js';
+import { checkEntitlement, recordUsage } from './entitlementService.js';
+import { createDebugger } from '../debug/logger.js';
+
+const log = createDebugger('jobs');
+
+/**
+ * @param {object} ctx
+ * @param {{ certificate: string }} body
+ */
+export async function verifyTimestamp(ctx, body) {
+  checkEntitlement(ctx.tenantId, 'verify');
+  const result = await veraeClient.verify(ctx.veraeToken, body);
+  recordUsage(ctx.tenantId, 'verify');
+  log.debug('verify result', { tenantId: ctx.tenantId, valid: result.valid });
+  return result;
+}
+
+/**
+ * @param {object} ctx
+ * @param {{ certificates: string[] }} body
+ */
+export async function verifyBatch(ctx, body) {
+  const amount = body.certificates?.length ?? 1;
+  checkEntitlement(ctx.tenantId, 'verify', { amount });
+  const result = await veraeClient.verifyBatch(ctx.veraeToken, body);
+  recordUsage(ctx.tenantId, 'verify', { amount });
+  return result;
+}
--- a/packages/verae-zapier-middleware/src/services/webhookService.js
+++ b/packages/verae-zapier-middleware/src/services/webhookService.js
@ -0,0 +1,70 @@
+/**
+ * @fileoverview REST Hook subscribe/unsubscribe and HTTP delivery.
+ * @module services/webhookService
+ */
+
+import { createWebhook, deleteWebhook } from '../store/webhooks.js';
+import { createDebugger } from '../debug/logger.js';
+
+const log = createDebugger('webhooks');
+
+const ALLOWED_EVENTS = new Set(['timestamp.completed', 'timestamp.failed']);
+
+/**
+ * @param {object} ctx - auth context
+ * @param {{ targetUrl: string, event: string }} params
+ */
+export function subscribe(ctx, { targetUrl, event }) {
+  if (!targetUrl) {
+    throw new Error('targetUrl is required');
+  }
+  if (!ALLOWED_EVENTS.has(event)) {
+    throw new Error(`Unsupported event: ${event}`);
+  }
+
+  return createWebhook({
+    tenantId: ctx.tenantId,
+    targetUrl,
+    event,
+  });
+}
+
+/**
+ * @param {object} ctx
+ * @param {{ hookId?: string, targetUrl?: string }} params
+ */
+export function unsubscribe(ctx, { hookId, targetUrl }) {
+  const removed = deleteWebhook({
+    tenantId: ctx.tenantId,
+    hookId,
+    targetUrl,
+  });
+
+  if (!removed) {
+    throw new Error('Webhook subscription not found');
+  }
+
+  return { removed: true };
+}
+
+/**
+ * POST payload to Zapier target URL.
+ * @param {string} targetUrl
+ * @param {object} payload
+ * @returns {Promise<{ ok: boolean, status: number }>}
+ */
+export async function deliverWebhook(targetUrl, payload) {
+  log.debug('deliverWebhook', { targetUrl, event: payload?.event });
+
+  const response = await fetch(targetUrl, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'User-Agent': 'Verae-Zapier-Middleware/1.0',
+    },
+    body: JSON.stringify(payload),
+  });
+
+  log.debug('deliverWebhook result', { status: response.status, ok: response.ok });
+  return { ok: response.ok, status: response.status };
+}
--- a/packages/verae-zapier-middleware/src/store/db.js
+++ b/packages/verae-zapier-middleware/src/store/db.js
@ -0,0 +1,114 @@
+/**
+ * @fileoverview JSON file-backed in-memory store (MVP persistence).
+ * @module store/db
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { config } from '../config.js';
+import { createDebugger } from '../debug/logger.js';
+
+const log = createDebugger('app');
+
+/**
+ * @typedef {Object} StoreShape
+ * @property {Record<string, object>} tenants
+ * @property {Record<string, string>} apiKeys - apiKey → tenantId
+ * @property {Record<string, object>} usage - tenantId → counters
+ * @property {object[]} webhooks
+ * @property {object[]} jobWatchers
+ */
+
+/** @type {StoreShape|null} */
+let store = null;
+
+/**
+ * Create an empty store document.
+ * @returns {StoreShape}
+ */
+export function emptyStore() {
+  return {
+    tenants: {},
+    apiKeys: {},
+    usage: {},
+    webhooks: [],
+    jobWatchers: [],
+  };
+}
+
+/**
+ * Load store from disk into memory (or create empty if missing).
+ * @param {string} [path=config.storePath]
+ * @returns {StoreShape}
+ */
+export function loadStore(path = config.storePath) {
+  if (store) return store;
+
+  if (existsSync(path)) {
+    try {
+      const raw = readFileSync(path, 'utf8');
+      const parsed = JSON.parse(raw);
+      store = {
+        ...emptyStore(),
+        ...parsed,
+        tenants: parsed.tenants ?? {},
+        apiKeys: parsed.apiKeys ?? {},
+        usage: parsed.usage ?? {},
+        webhooks: Array.isArray(parsed.webhooks) ? parsed.webhooks : [],
+        jobWatchers: Array.isArray(parsed.jobWatchers) ? parsed.jobWatchers : [],
+      };
+      log.debug('store loaded', { path, tenants: Object.keys(store.tenants).length });
+    } catch (err) {
+      log.error('store load failed, using empty', { path, error: err.message });
+      store = emptyStore();
+    }
+  } else {
+    store = emptyStore();
+    log.debug('store initialized empty', { path });
+  }
+
+  return store;
+}
+
+/**
+ * Access the in-memory store (loads if needed).
+ * @returns {StoreShape}
+ */
+export function getStore() {
+  if (!store) return loadStore();
+  return store;
+}
+
+/**
+ * Replace the in-memory store (tests only).
+ * @param {StoreShape|null} next
+ * @returns {void}
+ */
+export function setStoreForTests(next) {
+  store = next;
+}
+
+/**
+ * Persist the in-memory store to disk.
+ * @param {string} [path=config.storePath]
+ * @returns {void}
+ */
+export function persist(path = config.storePath) {
+  const data = getStore();
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(path, JSON.stringify(data, null, 2), 'utf8');
+  log.debug('store persisted', { path });
+}
+
+/**
+ * Force reload from disk (drops memory).
+ * @param {string} [path=config.storePath]
+ * @returns {StoreShape}
+ */
+export function reloadStore(path = config.storePath) {
+  store = null;
+  return loadStore(path);
+}
--- a/packages/verae-zapier-middleware/src/store/jobWatchers.js
+++ b/packages/verae-zapier-middleware/src/store/jobWatchers.js
@ -0,0 +1,89 @@
+/**
+ * @fileoverview In-process job watch queue (NATS_ENABLED=false path).
+ * @module store/jobWatchers
+ */
+
+import { randomUUID } from 'node:crypto';
+import { getStore, persist } from './db.js';
+import { createDebugger } from '../debug/logger.js';
+
+const log = createDebugger('jobs');
+
+/**
+ * @typedef {Object} JobWatcher
+ * @property {string} id
+ * @property {string} tenantId
+ * @property {string} jobId
+ * @property {string} veraeToken
+ * @property {string} status
+ * @property {number} attempts
+ * @property {string} createdAt
+ * @property {string} updatedAt
+ * @property {string} [traceId]
+ */
+
+/**
+ * @param {object} params
+ * @param {string} params.tenantId
+ * @param {string} params.jobId
+ * @param {string} params.veraeToken
+ * @param {string} [params.traceId]
+ * @returns {JobWatcher}
+ */
+export function enqueueJob({ tenantId, jobId, veraeToken, traceId }) {
+  /** @type {JobWatcher} */
+  const watcher = {
+    id: randomUUID(),
+    tenantId,
+    jobId,
+    veraeToken,
+    status: 'pending',
+    attempts: 0,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    traceId,
+  };
+
+  const store = getStore();
+  store.jobWatchers.push(watcher);
+  persist();
+  log.debug('job enqueued', { watcherId: watcher.id, jobId, tenantId });
+  return watcher;
+}
+
+/**
+ * @returns {JobWatcher[]}
+ */
+export function listPendingJobs() {
+  return getStore().jobWatchers.filter((job) => job.status === 'pending');
+}
+
+/**
+ * @param {string} id
+ * @param {Partial<JobWatcher>} patch
+ * @returns {JobWatcher|null}
+ */
+export function updateJobWatcher(id, patch) {
+  const store = getStore();
+  const index = store.jobWatchers.findIndex((job) => job.id === id);
+  if (index === -1) return null;
+
+  store.jobWatchers[index] = {
+    ...store.jobWatchers[index],
+    ...patch,
+    updatedAt: new Date().toISOString(),
+  };
+  persist();
+  return store.jobWatchers[index];
+}
+
+/**
+ * @param {string} id
+ * @returns {void}
+ */
+export function removeJobWatcher(id) {
+  const store = getStore();
+  store.jobWatchers = store.jobWatchers.filter((job) => job.id !== id);
+  persist();
+  log.debug('job watcher removed', { id });
+}
--- a/packages/verae-zapier-middleware/src/store/tenants.js
+++ b/packages/verae-zapier-middleware/src/store/tenants.js
@ -0,0 +1,137 @@
+/**
+ * @fileoverview Tenant and API key persistence.
+ * @module store/tenants
+ */
+
+import { getStore, persist } from './db.js';
+import { generateApiKey } from '../lib/tokens.js';
+import { PLAN_LIMITS } from '../config.js';
+import { createDebugger } from '../debug/logger.js';
+
+const log = createDebugger('billing');
+
+/**
+ * @typedef {Object} Tenant
+ * @property {string} id
+ * @property {string} name
+ * @property {string} plan
+ * @property {string} veraeUsername
+ * @property {string} veraePassword
+ * @property {object|null} contract
+ * @property {object} [metadata]
+ * @property {string} createdAt
+ */
+
+/**
+ * @param {string} tenantId
+ * @returns {Tenant|null}
+ */
+export function getTenant(tenantId) {
+  return getStore().tenants[tenantId] ?? null;
+}
+
+/**
+ * @param {string} apiKey
+ * @returns {Tenant|null}
+ */
+export function getTenantByApiKey(apiKey) {
+  const store = getStore();
+  const tenantId = store.apiKeys[apiKey];
+  return tenantId ? store.tenants[tenantId] ?? null : null;
+}
+
+/**
+ * @returns {Tenant[]}
+ */
+export function listTenants() {
+  return Object.values(getStore().tenants);
+}
+
+/**
+ * @param {Tenant} tenant
+ * @returns {Tenant}
+ */
+export function upsertTenant(tenant) {
+  const store = getStore();
+  store.tenants[tenant.id] = tenant;
+  persist();
+  log.debug('tenant upserted', { tenantId: tenant.id, plan: tenant.plan });
+  return tenant;
+}
+
+/**
+ * Create a tenant and bind a new API key.
+ *
+ * @param {object} params
+ * @param {string} params.id
+ * @param {string} params.name
+ * @param {string} [params.plan='free']
+ * @param {string} params.veraeUsername
+ * @param {string} params.veraePassword
+ * @param {object|null} [params.contract=null]
+ * @param {string} [params.apiKey]
+ * @param {object} [params.metadata]
+ * @returns {{ tenant: Tenant, apiKey: string }}
+ */
+export function createTenant({
+  id,
+  name,
+  plan = 'free',
+  veraeUsername,
+  veraePassword,
+  contract = null,
+  apiKey = generateApiKey(),
+  metadata = {},
+}) {
+  const store = getStore();
+  /** @type {Tenant} */
+  const tenant = {
+    id,
+    name,
+    plan,
+    veraeUsername,
+    veraePassword,
+    contract,
+    metadata,
+    createdAt: new Date().toISOString(),
+  };
+
+  store.tenants[id] = tenant;
+  store.apiKeys[apiKey] = id;
+  persist();
+
+  log.info('tenant created', { tenantId: id, plan, audience: metadata.audience });
+  return { tenant, apiKey };
+}
+
+/**
+ * Resolve effective limits for a tenant (plan defaults or enterprise contract).
+ *
+ * @param {Tenant} tenant
+ * @returns {{
+ *   timestamps: number|null,
+ *   verifications: number|null,
+ *   batch: boolean,
+ *   batchMaxItems: number|null,
+ *   requestsPerMinute: number,
+ *   allowOverage: boolean,
+ *   overageRates: object
+ * }}
+ */
+export function resolveLimits(tenant) {
+  if (tenant.plan === 'enterprise' && tenant.contract) {
+    return {
+      timestamps: tenant.contract.includedTimestamps ?? null,
+      verifications: tenant.contract.includedVerifications ?? null,
+      batch: tenant.contract.batch !== false,
+      batchMaxItems: tenant.contract.batchMaxItems ?? null,
+      requestsPerMinute:
+        tenant.contract.requestsPerMinute ?? PLAN_LIMITS.enterprise.requestsPerMinute,
+      allowOverage: tenant.contract.allowOverage ?? false,
+      overageRates: tenant.contract.overageRates ?? {},
+    };
+  }
+
+  const base = PLAN_LIMITS[tenant.plan] ?? PLAN_LIMITS.free;
+  return { ...base, allowOverage: false, overageRates: {} };
+}
--- a/packages/verae-zapier-middleware/src/store/usage.js
+++ b/packages/verae-zapier-middleware/src/store/usage.js
@ -0,0 +1,102 @@
+/**
+ * @fileoverview Per-tenant usage metering counters.
+ * @module store/usage
+ */
+
+import { getStore, persist } from './db.js';
+import { getTenant, resolveLimits } from './tenants.js';
+import { createDebugger } from '../debug/logger.js';
+
+const log = createDebugger('billing');
+
+/**
+ * @returns {string} YYYY-MM period key
+ */
+function currentPeriod() {
+  const d = new Date();
+  return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`;
+}
+
+/**
+ * @param {string} tenantId
+ * @returns {{ period: string, timestamps: number, verifications: number, statusChecks: number, batchTimestamps: number, overage: object }}
+ */
+function emptyUsage(tenantId) {
+  return {
+    tenantId,
+    period: currentPeriod(),
+    timestamps: 0,
+    verifications: 0,
+    statusChecks: 0,
+    batchTimestamps: 0,
+    overage: { timestamps: 0, verifications: 0 },
+  };
+}
+
+/**
+ * Get usage for tenant, rolling period if month changed.
+ * @param {string} tenantId
+ * @returns {ReturnType<typeof emptyUsage>}
+ */
+export function getUsage(tenantId) {
+  const store = getStore();
+  let usage = store.usage[tenantId];
+  const period = currentPeriod();
+
+  if (!usage || usage.period !== period) {
+    usage = emptyUsage(tenantId);
+    store.usage[tenantId] = usage;
+  }
+
+  return usage;
+}
+
+/**
+ * Public summary for /auth/me.
+ * @param {string} tenantId
+ * @returns {object}
+ */
+export function getUsageSummary(tenantId) {
+  const usage = getUsage(tenantId);
+  const tenant = getTenant(tenantId);
+  const limits = tenant ? resolveLimits(tenant) : null;
+
+  return {
+    period: usage.period,
+    timestamps: usage.timestamps,
+    verifications: usage.verifications,
+    statusChecks: usage.statusChecks,
+    batchTimestamps: usage.batchTimestamps,
+    limits: limits
+      ? {
+          timestamps: limits.timestamps,
+          verifications: limits.verifications,
+          batch: limits.batch,
+          batchMaxItems: limits.batchMaxItems,
+        }
+      : null,
+  };
+}
+
+/**
+ * Increment a usage metric.
+ *
+ * @param {string} tenantId
+ * @param {string} metric - e.g. `timestamps`, `verifications`, `statusChecks`, `batchTimestamps`, `overage.timestamps`
+ * @param {number} [amount=1]
+ * @returns {void}
+ */
+export function incrementUsage(tenantId, metric, amount = 1) {
+  const usage = getUsage(tenantId);
+
+  if (metric.startsWith('overage.')) {
+    const key = metric.slice('overage.'.length);
+    usage.overage[key] = (usage.overage[key] ?? 0) + amount;
+  } else {
+    usage[metric] = (usage[metric] ?? 0) + amount;
+  }
+
+  getStore().usage[tenantId] = usage;
+  persist();
+  log.debug('usage incremented', { tenantId, metric, amount, value: usage[metric] ?? usage.overage });
+}
--- a/packages/verae-zapier-middleware/src/store/webhooks.js
+++ b/packages/verae-zapier-middleware/src/store/webhooks.js
@ -0,0 +1,91 @@
+/**
+ * @fileoverview REST Hook subscription storage.
+ * @module store/webhooks
+ */
+
+import { randomUUID } from 'node:crypto';
+import { getStore, persist } from './db.js';
+import { createDebugger } from '../debug/logger.js';
+
+const log = createDebugger('webhooks');
+
+/**
+ * @typedef {Object} Webhook
+ * @property {string} id
+ * @property {string} tenantId
+ * @property {string} targetUrl
+ * @property {string} event
+ * @property {string} createdAt
+ */
+
+/**
+ * @param {object} params
+ * @param {string} params.tenantId
+ * @param {string} params.targetUrl
+ * @param {string} params.event
+ * @returns {Webhook}
+ */
+export function createWebhook({ tenantId, targetUrl, event }) {
+  /** @type {Webhook} */
+  const hook = {
+    id: randomUUID(),
+    tenantId,
+    targetUrl,
+    event,
+    createdAt: new Date().toISOString(),
+  };
+
+  const store = getStore();
+  store.webhooks.push(hook);
+  persist();
+  log.info('webhook created', { hookId: hook.id, tenantId, event });
+  return hook;
+}
+
+/**
+ * Delete a webhook for a tenant by id and/or targetUrl.
+ *
+ * @param {object} params
+ * @param {string} params.tenantId
+ * @param {string} [params.hookId]
+ * @param {string} [params.targetUrl]
+ * @returns {boolean} True if at least one webhook was removed.
+ */
+export function deleteWebhook({ tenantId, hookId, targetUrl }) {
+  if (!hookId && !targetUrl) return false;
+
+  const store = getStore();
+  const before = store.webhooks.length;
+
+  store.webhooks = store.webhooks.filter((hook) => {
+    if (hook.tenantId !== tenantId) return true;
+    if (hookId && hook.id === hookId) return false;
+    if (!hookId && targetUrl && hook.targetUrl === targetUrl) return false;
+    return true;
+  });
+
+  const removedCount = before - store.webhooks.length;
+  if (removedCount > 0) {
+    persist();
+    log.info('webhook deleted', { tenantId, hookId, removedCount });
+    return true;
+  }
+  return false;
+}
+
+/**
+ * @param {string} tenantId
+ * @param {string} event
+ * @returns {Webhook[]}
+ */
+export function getActiveWebhooks(tenantId, event) {
+  return getStore().webhooks.filter((h) => h.tenantId === tenantId && h.event === event);
+}
+
+/**
+ * @param {string} tenantId
+ * @returns {Webhook[]}
+ */
+export function listWebhooksForTenant(tenantId) {
+  return getStore().webhooks.filter((h) => h.tenantId === tenantId);
+}
--- a/packages/verae-zapier-middleware/src/workers/inProcessJobPoller.js
+++ b/packages/verae-zapier-middleware/src/workers/inProcessJobPoller.js
@ -0,0 +1,108 @@
+/**
+ * @fileoverview In-process job poller when NATS_ENABLED=false.
+ * @module workers/inProcessJobPoller
+ */
+
+import { config } from '../config.js';
+import { veraeClient } from '../clients/veraeClient.js';
+import {
+  listPendingJobs,
+  updateJobWatcher,
+  removeJobWatcher,
+} from '../store/jobWatchers.js';
+import { getActiveWebhooks } from '../store/webhooks.js';
+import { deliverWebhook } from '../services/webhookService.js';
+import { createDebugger } from '../debug/logger.js';
+
+const log = createDebugger('jobs');
+
+let timer = null;
+let running = false;
+
+/**
+ * @param {import('../store/jobWatchers.js').JobWatcher} job
+ */
+async function processJob(job) {
+  const attempts = job.attempts + 1;
+  updateJobWatcher(job.id, { attempts });
+
+  if (attempts > config.jobPollMaxAttempts) {
+    updateJobWatcher(job.id, { status: 'timeout' });
+    removeJobWatcher(job.id);
+    log.warn('job timeout', { jobId: job.jobId });
+    return;
+  }
+
+  let status;
+  try {
+    status = await veraeClient.getStatus(job.veraeToken, job.jobId);
+  } catch (err) {
+    log.debug('poll error', { jobId: job.jobId, error: err.message });
+    return;
+  }
+
+  if (status.status === 'pending') {
+    return;
+  }
+
+  const event = status.status === 'completed' ? 'timestamp.completed' : 'timestamp.failed';
+  const hooks = getActiveWebhooks(job.tenantId, event);
+
+  for (const hook of hooks) {
+    try {
+      await deliverWebhook(hook.targetUrl, {
+        event,
+        jobId: job.jobId,
+        tenantId: job.tenantId,
+        status,
+      });
+    } catch (err) {
+      log.error('webhook deliver failed', { hookId: hook.id, error: err.message });
+    }
+  }
+
+  updateJobWatcher(job.id, { status: status.status });
+  removeJobWatcher(job.id);
+  log.debug('job terminal', { jobId: job.jobId, status: status.status, hooks: hooks.length });
+}
+
+async function tick() {
+  if (running) return;
+  running = true;
+  try {
+    const jobs = listPendingJobs();
+    await Promise.all(jobs.map((job) => processJob(job)));
+  } finally {
+    running = false;
+  }
+}
+
+/**
+ * Start interval poller (no-op if already started or NATS enabled).
+ * @returns {void}
+ */
+export function startInProcessJobPoller() {
+  if (config.natsEnabled) {
+    log.info('in-process poller skipped (NATS_ENABLED=true)');
+    return;
+  }
+  if (timer) return;
+
+  const interval = config.jobPollIntervalMs;
+  timer = setInterval(() => {
+    tick().catch((err) => log.error('poller tick failed', { error: err.message }));
+  }, interval);
+
+  log.info('in-process job poller started', { intervalMs: interval });
+}
+
+/**
+ * Stop interval poller.
+ * @returns {void}
+ */
+export function stopInProcessJobPoller() {
+  if (!timer) return;
+  clearInterval(timer);
+  timer = null;
+  log.info('in-process job poller stopped');
+}
--- a/packages/verae-zapier-middleware/src/workers/jobPollerWorker.js
+++ b/packages/verae-zapier-middleware/src/workers/jobPollerWorker.js
@ -0,0 +1,158 @@
+/**
+ * @fileoverview JetStream consumer that polls Verae job status.
+ * @module workers/jobPollerWorker
+ */
+
+import { createDebugger } from '../debug/logger.js';
+import { config } from '../config.js';
+import { SUBJECTS, CONSUMERS, STREAMS } from '../nats/subjects.js';
+import { connectNats, ensureStreams } from '../nats/connection.js';
+import { publishJobEvent } from '../nats/publishers.js';
+import { veraeClient } from '../clients/veraeClient.js';
+import { getTenant } from '../store/tenants.js';
+import { withTrace } from '../debug/trace.js';
+
+const log = createDebugger('jobs');
+
+let running = false;
+/** @type {AbortController|null} */
+let abort = null;
+
+/**
+ * Resolve a Verae token for polling (re-login via tenant if needed).
+ * @param {object} msg
+ * @returns {Promise<string>}
+ */
+async function resolveVeraeToken(msg) {
+  if (msg.veraeToken) return msg.veraeToken;
+
+  const tenant = getTenant(msg.tenantId);
+  if (!tenant?.veraeUsername) {
+    throw new Error(`Cannot resolve token for tenant ${msg.tenantId}`);
+  }
+  const login = await veraeClient.login({
+    username: tenant.veraeUsername,
+    password: tenant.veraePassword,
+  });
+  return login.token;
+}
+
+/**
+ * Process one watch message.
+ * @param {object} data
+ * @param {{ ack: () => Promise<void>, nak: (delay?: number) => Promise<void> }} ctrl
+ */
+async function handleWatch(data, ctrl) {
+  await withTrace({ traceId: data.traceId, span: 'job-poll' }, async () => {
+    const attempt = (data.attempt ?? 0) + 1;
+    const maxAttempts = data.maxAttempts ?? config.jobPollMaxAttempts;
+
+    if (attempt > maxAttempts) {
+      await publishJobEvent({
+        event: 'timestamp.timeout',
+        tenantId: data.tenantId,
+        jobId: data.jobId,
+        status: { id: data.jobId, status: 'timeout' },
+        traceId: data.traceId,
+      });
+      await ctrl.ack();
+      return;
+    }
+
+    const token = await resolveVeraeToken(data);
+    let status;
+    try {
+      status = await veraeClient.getStatus(token, data.jobId);
+    } catch (err) {
+      log.debug('poll error, nak', { jobId: data.jobId, error: err.message });
+      await ctrl.nak(config.jobPollIntervalMs);
+      return;
+    }
+
+    log.debug('poll status', { jobId: data.jobId, status: status.status, attempt });
+
+    if (status.status === 'pending') {
+      await ctrl.nak(config.jobPollIntervalMs);
+      return;
+    }
+
+    const event =
+      status.status === 'completed' ? 'timestamp.completed' : 'timestamp.failed';
+
+    await publishJobEvent({
+      event,
+      tenantId: data.tenantId,
+      jobId: data.jobId,
+      status,
+      traceId: data.traceId,
+    });
+    await ctrl.ack();
+  });
+}
+
+/**
+ * Start the durable job-poller worker loop.
+ * @returns {Promise<{ stop: () => Promise<void> }>}
+ */
+export async function startJobPollerWorker() {
+  if (running) {
+    return { stop: async () => stopJobPollerWorker() };
+  }
+
+  const { nc, js, jsm } = await connectNats();
+  await ensureStreams(jsm);
+
+  // Ensure durable consumer (workqueue-style via filter + durable name)
+  try {
+    await jsm.consumers.add(STREAMS.ZAPIER_JOBS, {
+      durable_name: CONSUMERS.JOB_POLLER,
+      ack_policy: 'explicit',
+      filter_subject: SUBJECTS.JOBS_WATCH,
+      max_deliver: config.jobPollMaxAttempts + 5,
+      ack_wait: 30_000_000_000, // 30s ns
+    });
+  } catch (err) {
+    // already exists
+    log.debug('consumer may exist', { error: err.message });
+  }
+
+  const consumer = await js.consumers.get(STREAMS.ZAPIER_JOBS, CONSUMERS.JOB_POLLER);
+  abort = new AbortController();
+  running = true;
+  log.info('job poller worker started', { consumer: CONSUMERS.JOB_POLLER });
+
+  (async () => {
+    const messages = await consumer.consume({ max_messages: 10 });
+    for await (const msg of messages) {
+      if (abort?.signal.aborted) break;
+      try {
+        const data = JSON.parse(msg.string());
+        await handleWatch(data, {
+          ack: () => msg.ack(),
+          nak: (delayMs = 1000) => msg.nak(delayMs),
+        });
+      } catch (err) {
+        log.error('job poller handle failed', { error: err.message });
+        try {
+          msg.nak(1000);
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+  })().catch((err) => log.error('job poller loop failed', { error: err.message }));
+
+  return {
+    stop: async () => stopJobPollerWorker(),
+  };
+}
+
+/**
+ * @returns {Promise<void>}
+ */
+export async function stopJobPollerWorker() {
+  abort?.abort();
+  abort = null;
+  running = false;
+  log.info('job poller worker stopped');
+}
--- a/packages/verae-zapier-middleware/src/workers/webhookWorker.js
+++ b/packages/verae-zapier-middleware/src/workers/webhookWorker.js
@ -0,0 +1,138 @@
+/**
+ * @fileoverview JetStream consumer that POSTs Zapier REST Hook payloads.
+ * @module workers/webhookWorker
+ */
+
+import { createDebugger } from '../debug/logger.js';
+import { SUBJECTS, CONSUMERS, STREAMS } from '../nats/subjects.js';
+import { connectNats, ensureStreams } from '../nats/connection.js';
+import { deliverWebhook } from '../services/webhookService.js';
+import { getActiveWebhooks } from '../store/webhooks.js';
+import { withTrace } from '../debug/trace.js';
+
+const log = createDebugger('webhooks');
+
+let running = false;
+/** @type {AbortController|null} */
+let abort = null;
+
+/**
+ * Route job events → per-hook deliver messages (inline or via re-publish).
+ * Also handles direct deliver subjects.
+ *
+ * @param {object} data
+ * @param {{ ack: () => Promise<void>, nak: (d?: number) => Promise<void> }} ctrl
+ */
+async function handleDeliver(data, ctrl) {
+  await withTrace({ traceId: data.traceId, span: 'webhook-deliver' }, async () => {
+    // Event router path: expand tenant hooks
+    if (data.event && data.jobId && !data.targetUrl) {
+      const hooks = getActiveWebhooks(data.tenantId, data.event);
+      for (const hook of hooks) {
+        await deliverWebhook(hook.targetUrl, {
+          event: data.event,
+          jobId: data.jobId,
+          tenantId: data.tenantId,
+          status: data.status,
+        });
+      }
+      await ctrl.ack();
+      return;
+    }
+
+    if (!data.targetUrl) {
+      log.warn('deliver missing targetUrl', { dataKeys: Object.keys(data) });
+      await ctrl.ack();
+      return;
+    }
+
+    const result = await deliverWebhook(data.targetUrl, data.payload ?? data);
+    if (result.ok) {
+      await ctrl.ack();
+    } else {
+      log.debug('deliver non-2xx, nak', { status: result.status });
+      await ctrl.nak(2000);
+    }
+  });
+}
+
+/**
+ * Start webhook delivery worker (consumes WEBHOOKS stream + optional events).
+ * @returns {Promise<{ stop: () => Promise<void> }>}
+ */
+export async function startWebhookWorker() {
+  if (running) {
+    return { stop: async () => stopWebhookWorker() };
+  }
+
+  const { js, jsm } = await connectNats();
+  await ensureStreams(jsm);
+
+  // Events consumer → deliver
+  try {
+    await jsm.consumers.add(STREAMS.ZAPIER_EVENTS, {
+      durable_name: CONSUMERS.EVENT_WEBHOOK_ROUTER,
+      ack_policy: 'explicit',
+      filter_subject: SUBJECTS.JOBS_EVENTS,
+      max_deliver: 10,
+    });
+  } catch (err) {
+    log.debug('events consumer may exist', { error: err.message });
+  }
+
+  try {
+    await jsm.consumers.add(STREAMS.ZAPIER_WEBHOOKS, {
+      durable_name: CONSUMERS.WEBHOOK_DELIVER,
+      ack_policy: 'explicit',
+      filter_subject: SUBJECTS.WEBHOOKS_DELIVER,
+      max_deliver: 10,
+    });
+  } catch (err) {
+    log.debug('webhook consumer may exist', { error: err.message });
+  }
+
+  abort = new AbortController();
+  running = true;
+  log.info('webhook worker started');
+
+  const runConsumer = async (stream, durable) => {
+    const consumer = await js.consumers.get(stream, durable);
+    const messages = await consumer.consume({ max_messages: 10 });
+    for await (const msg of messages) {
+      if (abort?.signal.aborted) break;
+      try {
+        const data = JSON.parse(msg.string());
+        await handleDeliver(data, {
+          ack: () => msg.ack(),
+          nak: (d = 1000) => msg.nak(d),
+        });
+      } catch (err) {
+        log.error('webhook handle failed', { error: err.message });
+        try {
+          msg.nak(1000);
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+  };
+
+  runConsumer(STREAMS.ZAPIER_EVENTS, CONSUMERS.EVENT_WEBHOOK_ROUTER).catch((err) =>
+    log.error('events consumer failed', { error: err.message }),
+  );
+  runConsumer(STREAMS.ZAPIER_WEBHOOKS, CONSUMERS.WEBHOOK_DELIVER).catch((err) =>
+    log.error('webhooks consumer failed', { error: err.message }),
+  );
+
+  return { stop: async () => stopWebhookWorker() };
+}
+
+/**
+ * @returns {Promise<void>}
+ */
+export async function stopWebhookWorker() {
+  abort?.abort();
+  abort = null;
+  running = false;
+  log.info('webhook worker stopped');
+}
--- a/packages/verae-zapier-middleware/test/helpers.js
+++ b/packages/verae-zapier-middleware/test/helpers.js
@ -0,0 +1,93 @@
+/**
+ * Shared test helpers — isolated store + seed tenants.
+ */
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setStoreForTests, loadStore, emptyStore, persist, getStore } from '../src/store/db.js';
+import { createTenant } from '../src/store/tenants.js';
+import { config } from '../src/config.js';
+
+/**
+ * Point store at a temp file and reset memory.
+ * @returns {{ dir: string, storePath: string, cleanup: () => void }}
+ */
+export function useTempStore() {
+  const dir = mkdtempSync(join(tmpdir(), 'verae-mw-'));
+  const storePath = join(dir, 'store.json');
+  config.storePath = storePath;
+  setStoreForTests(null);
+  loadStore(storePath);
+  // ensure empty
+  setStoreForTests(emptyStore());
+  persist(storePath);
+
+  return {
+    dir,
+    storePath,
+    cleanup: () => {
+      setStoreForTests(null);
+      try {
+        rmSync(dir, { recursive: true, force: true });
+      } catch {
+        /* ignore */
+      }
+    },
+  };
+}
+
+/**
+ * Seed a free-plan tenant with known credentials (mock Verae).
+ * @param {object} [overrides]
+ * @returns {{ tenant: object, apiKey: string }}
+ */
+export function seedFreeTenant(overrides = {}) {
+  return createTenant({
+    id: overrides.id ?? 'tenant-test-free',
+    name: overrides.name ?? 'Test Free',
+    plan: 'free',
+    veraeUsername: overrides.veraeUsername ?? 'zapuser',
+    veraePassword: overrides.veraePassword ?? 'zappass',
+    metadata: { audience: 'test' },
+    ...overrides,
+  });
+}
+
+/**
+ * Seed a pro tenant (batch allowed).
+ */
+export function seedProTenant() {
+  return createTenant({
+    id: 'tenant-test-pro',
+    name: 'Test Pro',
+    plan: 'pro',
+    veraeUsername: 'prouser',
+    veraePassword: 'propass',
+    metadata: { audience: 'test' },
+  });
+}
+
+/**
+ * Seed enterprise with contract.
+ */
+export function seedEnterpriseTenant() {
+  return createTenant({
+    id: 'tenant-test-ent',
+    name: 'Test Enterprise',
+    plan: 'enterprise',
+    veraeUsername: 'entuser',
+    veraePassword: 'entpass',
+    contract: {
+      includedTimestamps: 10,
+      includedVerifications: 10,
+      batch: true,
+      batchMaxItems: 5,
+      requestsPerMinute: 100,
+      allowOverage: false,
+    },
+    metadata: { audience: 'enterprise' },
+  });
+}
+
+export { getStore, config };
--- a/packages/verae-zapier-middleware/test/integration/auth.test.js
+++ b/packages/verae-zapier-middleware/test/integration/auth.test.js
@ -0,0 +1,76 @@
+/**
+ * GATE 5 — Auth + entitlement HTTP tests
+ */
+
+import { describe, it, before, after, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { createApp } from '../../src/app.js';
+import { useTempStore, seedFreeTenant } from '../helpers.js';
+import { incrementUsage } from '../../src/store/usage.js';
+import { PLAN_LIMITS } from '../../src/config.js';
+import { checkEntitlement } from '../../src/services/entitlementService.js';
+import { AppError } from '../../src/errors.js';
+
+describe('auth + entitlements HTTP', () => {
+  /** @type {ReturnType<typeof useTempStore>} */
+  let ctx;
+  /** @type {import('http').Server} */
+  let server;
+  /** @type {number} */
+  let port;
+  /** @type {string} */
+  let apiKey;
+
+  before(() => {
+    ctx = useTempStore();
+    const seeded = seedFreeTenant();
+    apiKey = seeded.apiKey;
+
+    const app = createApp({ load: false });
+    return new Promise((resolve) => {
+      server = app.listen(0, '127.0.0.1', () => {
+        port = server.address().port;
+        resolve();
+      });
+    });
+  });
+
+  after(async () => {
+    await new Promise((resolve) => server.close(resolve));
+    ctx.cleanup();
+  });
+
+  it('GET /zapier/v1/auth/me with valid API key', async () => {
+    const res = await fetch(`http://127.0.0.1:${port}/zapier/v1/auth/me`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    assert.equal(res.status, 200);
+    const body = await res.json();
+    assert.equal(body.valid, true);
+    assert.equal(body.plan, 'free');
+    assert.ok(body.tenantId);
+    assert.ok(body.usage);
+  });
+
+  it('invalid key returns 401', async () => {
+    const res = await fetch(`http://127.0.0.1:${port}/zapier/v1/auth/me`, {
+      headers: { Authorization: 'Bearer zmw_invalidkeyxxxxxxxxxxxxxxxx' },
+    });
+    assert.equal(res.status, 401);
+    const body = await res.json();
+    assert.equal(body.code, 'UNAUTHORIZED');
+  });
+
+  it('exceeding free timestamp quota throws 402 QUOTA_EXCEEDED', () => {
+    const tenantId = 'tenant-test-free';
+    const limit = PLAN_LIMITS.free.timestamps;
+    // force usage to limit
+    for (let i = 0; i < limit; i += 1) {
+      incrementUsage(tenantId, 'timestamps', 1);
+    }
+    assert.throws(
+      () => checkEntitlement(tenantId, 'timestamp'),
+      (err) => err instanceof AppError && err.status === 402 && err.code === 'QUOTA_EXCEEDED',
+    );
+  });
+});
--- a/packages/verae-zapier-middleware/test/integration/http-api.test.js
+++ b/packages/verae-zapier-middleware/test/integration/http-api.test.js
@ -0,0 +1,164 @@
+/**
+ * GATE 6 — Full HTTP middleware (NATS off, MOCK_VERAE on)
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { createApp } from '../../src/app.js';
+import { useTempStore, seedProTenant } from '../helpers.js';
+import { config } from '../../src/config.js';
+import { startInProcessJobPoller, stopInProcessJobPoller } from '../../src/workers/inProcessJobPoller.js';
+import { getActiveWebhooks } from '../../src/store/webhooks.js';
+
+describe('HTTP API (mock verae, nats off)', () => {
+  /** @type {ReturnType<typeof useTempStore>} */
+  let ctx;
+  /** @type {import('http').Server} */
+  let server;
+  /** @type {number} */
+  let port;
+  /** @type {string} */
+  let apiKey;
+  /** @type {object[]} */
+  let webhookDeliveries;
+  /** @type {import('http').Server} */
+  let hookServer;
+  /** @type {number} */
+  let hookPort;
+
+  before(async () => {
+    assert.equal(config.mockVerae, true);
+    assert.equal(config.natsEnabled, false);
+
+    // Fast poll for wait path
+    config.jobPollIntervalMs = 20;
+    config.jobPollMaxAttempts = 50;
+
+    ctx = useTempStore();
+    const seeded = seedProTenant();
+    apiKey = seeded.apiKey;
+
+    webhookDeliveries = [];
+    await new Promise((resolve) => {
+      hookServer = http.createServer((req, res) => {
+        let body = '';
+        req.on('data', (c) => {
+          body += c;
+        });
+        req.on('end', () => {
+          webhookDeliveries.push(JSON.parse(body || '{}'));
+          res.writeHead(200);
+          res.end('ok');
+        });
+      });
+      hookServer.listen(0, '127.0.0.1', () => {
+        hookPort = hookServer.address().port;
+        resolve();
+      });
+    });
+
+    const app = createApp({ load: false });
+    await new Promise((resolve) => {
+      server = app.listen(0, '127.0.0.1', () => {
+        port = server.address().port;
+        resolve();
+      });
+    });
+
+    startInProcessJobPoller();
+  });
+
+  after(async () => {
+    stopInProcessJobPoller();
+    await new Promise((resolve) => server.close(resolve));
+    await new Promise((resolve) => hookServer.close(resolve));
+    ctx.cleanup();
+  });
+
+  function authHeaders() {
+    return {
+      Authorization: `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+    };
+  }
+
+  it('POST /zapier/v1/timestamp → 202 + jobId', async () => {
+    const res = await fetch(`http://127.0.0.1:${port}/zapier/v1/timestamp`, {
+      method: 'POST',
+      headers: authHeaders(),
+      body: JSON.stringify({ data: 'payload-async' }),
+    });
+    assert.equal(res.status, 202);
+    const body = await res.json();
+    assert.ok(body.jobId);
+  });
+
+  it('POST /zapier/v1/timestamp/wait → completed status', async () => {
+    const res = await fetch(`http://127.0.0.1:${port}/zapier/v1/timestamp/wait`, {
+      method: 'POST',
+      headers: authHeaders(),
+      body: JSON.stringify({ data: 'payload-wait', hashAlg: 'SHA256' }),
+    });
+    assert.equal(res.status, 200);
+    const body = await res.json();
+    assert.equal(body.status, 'completed');
+    assert.ok(body.result);
+    assert.ok(body.metadata?.certificate || body.result);
+  });
+
+  it('POST /zapier/v1/verify → valid true', async () => {
+    const waitRes = await fetch(`http://127.0.0.1:${port}/zapier/v1/timestamp/wait`, {
+      method: 'POST',
+      headers: authHeaders(),
+      body: JSON.stringify({ data: 'to-verify' }),
+    });
+    const done = await waitRes.json();
+
+    const res = await fetch(`http://127.0.0.1:${port}/zapier/v1/verify`, {
+      method: 'POST',
+      headers: authHeaders(),
+      body: JSON.stringify({ certificate: done.result }),
+    });
+    assert.equal(res.status, 200);
+    const body = await res.json();
+    assert.equal(body.valid, true);
+  });
+
+  it('webhook subscribe stores targetUrl; complete delivers', async () => {
+    const sub = await fetch(`http://127.0.0.1:${port}/zapier/v1/webhooks/subscribe`, {
+      method: 'POST',
+      headers: authHeaders(),
+      body: JSON.stringify({
+        targetUrl: `http://127.0.0.1:${hookPort}/hook`,
+        event: 'timestamp.completed',
+      }),
+    });
+    assert.equal(sub.status, 201);
+    const hook = await sub.json();
+    assert.ok(hook.id);
+
+    const hooks = getActiveWebhooks('tenant-test-pro', 'timestamp.completed');
+    assert.ok(hooks.some((h) => h.id === hook.id));
+
+    webhookDeliveries.length = 0;
+
+    const create = await fetch(`http://127.0.0.1:${port}/zapier/v1/timestamp`, {
+      method: 'POST',
+      headers: authHeaders(),
+      body: JSON.stringify({ data: 'webhook-trigger-me' }),
+    });
+    const { jobId } = await create.json();
+    assert.ok(jobId);
+
+    // Wait for in-process poller to deliver
+    const deadline = Date.now() + 5000;
+    while (webhookDeliveries.length === 0 && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 50));
+    }
+
+    assert.ok(webhookDeliveries.length >= 1, 'expected webhook delivery');
+    assert.equal(webhookDeliveries[0].event, 'timestamp.completed');
+    assert.equal(webhookDeliveries[0].jobId, jobId);
+  });
+});
--- a/packages/verae-zapier-middleware/test/integration/nats-workers.test.js
+++ b/packages/verae-zapier-middleware/test/integration/nats-workers.test.js
@ -0,0 +1,108 @@
+/**
+ * GATE 8 — Job poller worker + webhook via NATS events
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { config } from '../../src/config.js';
+import { useTempStore, seedProTenant } from '../helpers.js';
+import { connectNats, ensureStreams, closeNats } from '../../src/nats/connection.js';
+import { enqueueWatch } from '../../src/nats/publishers.js';
+import { startJobPollerWorker, stopJobPollerWorker } from '../../src/workers/jobPollerWorker.js';
+import { startWebhookWorker, stopWebhookWorker } from '../../src/workers/webhookWorker.js';
+import { createWebhook } from '../../src/store/webhooks.js';
+import { veraeClient, clearMockJobs } from '../../src/clients/veraeClient.js';
+
+describe('NATS workers', () => {
+  /** @type {ReturnType<typeof useTempStore>} */
+  let ctx;
+  /** @type {object[]} */
+  let deliveries;
+  /** @type {import('http').Server} */
+  let hookServer;
+  /** @type {number} */
+  let hookPort;
+  /** @type {string} */
+  let tenantId;
+
+  before(async () => {
+    assert.equal(config.mockVerae, true);
+    config.natsEnabled = true;
+    process.env.NATS_FORCE_CONNECT = '1';
+    config.natsUrl = process.env.NATS_URL || 'nats://127.0.0.1:4222';
+    config.jobPollIntervalMs = 50;
+    config.jobPollMaxAttempts = 40;
+
+    clearMockJobs();
+    ctx = useTempStore();
+    const { tenant } = seedProTenant();
+    tenantId = tenant.id;
+
+    deliveries = [];
+    await new Promise((resolve) => {
+      hookServer = http.createServer((req, res) => {
+        let body = '';
+        req.on('data', (c) => {
+          body += c;
+        });
+        req.on('end', () => {
+          deliveries.push(JSON.parse(body || '{}'));
+          res.writeHead(200);
+          res.end('ok');
+        });
+      });
+      hookServer.listen(0, '127.0.0.1', () => {
+        hookPort = hookServer.address().port;
+        resolve();
+      });
+    });
+
+    createWebhook({
+      tenantId,
+      targetUrl: `http://127.0.0.1:${hookPort}/hook`,
+      event: 'timestamp.completed',
+    });
+
+    await connectNats(config.natsUrl);
+    await ensureStreams();
+    await startJobPollerWorker();
+    await startWebhookWorker();
+  });
+
+  after(async () => {
+    await stopJobPollerWorker();
+    await stopWebhookWorker();
+    await closeNats();
+    await new Promise((r) => hookServer.close(r));
+    ctx.cleanup();
+    process.env.NATS_FORCE_CONNECT = '';
+  });
+
+  it('watch → poll → event → webhook delivery', async () => {
+    const login = await veraeClient.login({
+      username: 'prouser',
+      password: 'propass',
+    });
+    const { jobId } = await veraeClient.createTimestamp(login.token, {
+      data: 'nats-worker-test',
+    });
+
+    await enqueueWatch({
+      tenantId,
+      jobId,
+      veraeToken: login.token,
+      maxAttempts: 40,
+      intervalMs: 50,
+    });
+
+    const deadline = Date.now() + 8000;
+    while (deliveries.length === 0 && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 50));
+    }
+
+    assert.ok(deliveries.length >= 1, 'expected webhook from NATS path');
+    assert.equal(deliveries[0].event, 'timestamp.completed');
+    assert.equal(deliveries[0].jobId, jobId);
+  });
+});
--- a/packages/verae-zapier-middleware/test/integration/nats.test.js
+++ b/packages/verae-zapier-middleware/test/integration/nats.test.js
@ -0,0 +1,117 @@
+/**
+ * GATE 7 — NATS streams + publish/consume
+ * Requires nats-server with JetStream on NATS_URL (default 127.0.0.1:4222)
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { config } from '../../src/config.js';
+import { SUBJECTS, STREAMS } from '../../src/nats/subjects.js';
+import {
+  connectNats,
+  ensureStreams,
+  closeNats,
+  isNatsConnected,
+} from '../../src/nats/connection.js';
+import { enqueueWatch, publishJobEvent } from '../../src/nats/publishers.js';
+
+describe('NATS infrastructure', () => {
+  before(async () => {
+    // Force connect even if NATS_ENABLED was false at boot — re-set for this process
+    config.natsEnabled = true;
+    process.env.NATS_FORCE_CONNECT = '1';
+    config.natsUrl = process.env.NATS_URL || 'nats://127.0.0.1:4222';
+
+    try {
+      await connectNats(config.natsUrl);
+      await ensureStreams();
+    } catch (err) {
+      assert.fail(
+        `NATS not available at ${config.natsUrl}: ${err.message}. Start: nats-server -js -p 4222`,
+      );
+    }
+  });
+
+  after(async () => {
+    await closeNats();
+    process.env.NATS_FORCE_CONNECT = '';
+  });
+
+  it('connects and reports connected', () => {
+    assert.equal(isNatsConnected(), true);
+  });
+
+  it('ensures streams exist (idempotent)', async () => {
+    await ensureStreams();
+    const { jsm } = await connectNats();
+    for (const name of [STREAMS.ZAPIER_JOBS, STREAMS.ZAPIER_EVENTS, STREAMS.ZAPIER_WEBHOOKS]) {
+      const info = await jsm.streams.info(name);
+      assert.equal(info.config.name, name);
+    }
+  });
+
+  it('publish + pull consume one watch message', async () => {
+    const { js, jsm } = await connectNats();
+
+    // Avoid consuming leftover messages from prior runs
+    await jsm.streams.purge(STREAMS.ZAPIER_JOBS);
+
+    const durable = `test-pull-${Date.now()}`;
+    await jsm.consumers.add(STREAMS.ZAPIER_JOBS, {
+      durable_name: durable,
+      ack_policy: 'explicit',
+      filter_subject: SUBJECTS.JOBS_WATCH,
+      deliver_policy: 'all',
+    });
+
+    const jobId = `job-${Date.now()}`;
+    const pub = await enqueueWatch({
+      tenantId: 'tenant-nats-test',
+      jobId,
+      maxAttempts: 5,
+      intervalMs: 100,
+    });
+    assert.ok(pub.seq >= 0);
+
+    const consumer = await js.consumers.get(STREAMS.ZAPIER_JOBS, durable);
+    const messages = await consumer.fetch({ max_messages: 5, expires: 5000 });
+    let got = null;
+    for await (const msg of messages) {
+      const data = JSON.parse(msg.string());
+      msg.ack();
+      if (data.jobId === jobId) {
+        got = data;
+        break;
+      }
+    }
+
+    assert.ok(got, 'expected a message for our jobId');
+    assert.equal(got.jobId, jobId);
+    assert.equal(got.tenantId, 'tenant-nats-test');
+  });
+
+  it('publishJobEvent works', async () => {
+    const result = await publishJobEvent({
+      event: 'timestamp.completed',
+      tenantId: 't1',
+      jobId: 'j1',
+      status: { id: 'j1', status: 'completed' },
+    });
+    assert.ok(result.seq >= 0);
+  });
+});
+
+describe('NATS disabled path', () => {
+  it('connectNats throws when disabled and not forced', async () => {
+    const prev = config.natsEnabled;
+    const force = process.env.NATS_FORCE_CONNECT;
+    config.natsEnabled = false;
+    process.env.NATS_FORCE_CONNECT = '';
+    // close existing so we hit the disabled check on a fresh call path
+    // Note: if already connected, connectNats returns cached — test isolation via disabled only when no cache
+    // This tests the disabled branch of a new process conceptually; here we only assert flag behavior:
+    assert.equal(config.natsEnabled, false);
+    config.natsEnabled = prev;
+    process.env.NATS_FORCE_CONNECT = force;
+  });
+});
--- a/packages/verae-zapier-middleware/test/integration/tenants.test.js
+++ b/packages/verae-zapier-middleware/test/integration/tenants.test.js
@ -0,0 +1,93 @@
+/**
+ * GATE 10 — Signup and admin provision
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { createApp } from '../../src/app.js';
+import { useTempStore } from '../helpers.js';
+import { config } from '../../src/config.js';
+
+describe('tenancy', () => {
+  let ctx;
+  let server;
+  let port;
+
+  before(async () => {
+    ctx = useTempStore();
+    const app = createApp({ load: false });
+    await new Promise((resolve) => {
+      server = app.listen(0, '127.0.0.1', () => {
+        port = server.address().port;
+        resolve();
+      });
+    });
+  });
+
+  after(async () => {
+    await new Promise((r) => server.close(r));
+    ctx.cleanup();
+  });
+
+  it('POST /zapier/v1/signup returns free plan + apiKey', async () => {
+    const res = await fetch(`http://127.0.0.1:${port}/zapier/v1/signup`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        email: 'user@example.com',
+        name: 'Self Serve Co',
+        veraeUsername: 'selfuser',
+        veraePassword: 'selfpass',
+      }),
+    });
+    assert.equal(res.status, 201);
+    const body = await res.json();
+    assert.equal(body.tenant.plan, 'free');
+    assert.ok(body.apiKey.startsWith('zmw_'));
+  });
+
+  it('enterprise without contract rejected', async () => {
+    const res = await fetch(`http://127.0.0.1:${port}/zapier/v1/admin/tenants`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'x-admin-secret': config.adminSecret,
+      },
+      body: JSON.stringify({
+        name: 'Ent Co',
+        plan: 'enterprise',
+        veraeUsername: 'e',
+        veraePassword: 'p',
+      }),
+    });
+    assert.equal(res.status, 400);
+    const body = await res.json();
+    assert.equal(body.code, 'VALIDATION_ERROR');
+  });
+
+  it('admin list does not leak passwords', async () => {
+    const create = await fetch(`http://127.0.0.1:${port}/zapier/v1/admin/tenants`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'x-admin-secret': config.adminSecret,
+      },
+      body: JSON.stringify({
+        name: 'Pro Co',
+        plan: 'pro',
+        veraeUsername: 'puser',
+        veraePassword: 'ppass',
+      }),
+    });
+    assert.equal(create.status, 201);
+
+    const res = await fetch(`http://127.0.0.1:${port}/zapier/v1/admin/tenants`, {
+      headers: { 'x-admin-secret': config.adminSecret },
+    });
+    assert.equal(res.status, 200);
+    const body = await res.json();
+    const json = JSON.stringify(body);
+    assert.doesNotMatch(json, /ppass/);
+    assert.doesNotMatch(json, /veraePassword/);
+  });
+});
--- a/packages/verae-zapier-middleware/test/unit/app.test.js
+++ b/packages/verae-zapier-middleware/test/unit/app.test.js
@ -0,0 +1,46 @@
+/**
+ * GATE 2 (partial) — HTTP shell health endpoint.
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { createApp } from '../../src/app.js';
+
+describe('createApp', () => {
+  /** @type {import('http').Server} */
+  let server;
+  /** @type {number} */
+  let port;
+
+  before(async () => {
+    const app = createApp();
+    await new Promise((resolve) => {
+      server = app.listen(0, '127.0.0.1', resolve);
+    });
+    port = server.address().port;
+  });
+
+  after(async () => {
+    await new Promise((resolve) => server.close(resolve));
+  });
+
+  it('GET /health returns ok', async () => {
+    const res = await fetch(`http://127.0.0.1:${port}/health`);
+    assert.equal(res.status, 200);
+    const body = await res.json();
+    assert.equal(body.status, 'ok');
+    assert.equal(body.service, 'verae-zapier-middleware');
+    assert.ok(res.headers.get('x-trace-id'));
+  });
+
+  it('protected /zapier path requires auth', async () => {
+    const res = await fetch(`http://127.0.0.1:${port}/zapier/v1/timestamp`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: '{}',
+    });
+    assert.equal(res.status, 401);
+    const body = await res.json();
+    assert.equal(body.code, 'UNAUTHORIZED');
+  });
+});
--- a/packages/verae-zapier-middleware/test/unit/config.test.js
+++ b/packages/verae-zapier-middleware/test/unit/config.test.js
@ -0,0 +1,33 @@
+/**
+ * GATE 2 (partial) — config exports.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { config, PLAN_LIMITS } from '../../src/config.js';
+
+describe('config', () => {
+  it('exposes required keys for HTTP and NATS', () => {
+    for (const key of [
+      'port',
+      'host',
+      'veraeApiBaseUrl',
+      'mockVerae',
+      'natsEnabled',
+      'natsUrl',
+      'tokenSecret',
+      'jobPollIntervalMs',
+      'jobPollMaxAttempts',
+      'storePath',
+    ]) {
+      assert.notEqual(config[key], undefined, `missing config.${key}`);
+    }
+  });
+
+  it('defines plan limits for free through enterprise', () => {
+    for (const plan of ['free', 'starter', 'pro', 'enterprise']) {
+      assert.ok(PLAN_LIMITS[plan], plan);
+      assert.equal(typeof PLAN_LIMITS[plan].requestsPerMinute, 'number');
+    }
+  });
+});
--- a/packages/verae-zapier-middleware/test/unit/debug.test.js
+++ b/packages/verae-zapier-middleware/test/unit/debug.test.js
@ -0,0 +1,165 @@
+/**
+ * GATE 1 — Debug facility unit tests.
+ * Must pass before Phase 2.
+ */
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  parseDebugVeraeEnv,
+  loadDebugConfig,
+  shouldLog,
+  createDebugger,
+  setDebugTestSink,
+  redact,
+  withTrace,
+  getTraceId,
+  generateTraceId,
+} from '../../src/debug/index.js';
+
+describe('parseDebugVeraeEnv', () => {
+  it('disables when unset or empty', () => {
+    assert.equal(parseDebugVeraeEnv(undefined).enabled, false);
+    assert.equal(parseDebugVeraeEnv('').enabled, false);
+    assert.equal(parseDebugVeraeEnv('off').enabled, false);
+  });
+
+  it('enables all namespaces for 1 or *', () => {
+    const a = parseDebugVeraeEnv('1');
+    assert.equal(a.enabled, true);
+    assert.equal(a.namespaces, null);
+
+    const b = parseDebugVeraeEnv('*');
+    assert.equal(b.enabled, true);
+    assert.equal(b.namespaces, null);
+  });
+
+  it('parses comma-separated namespaces', () => {
+    const { enabled, namespaces } = parseDebugVeraeEnv('auth, NATS, jobs');
+    assert.equal(enabled, true);
+    assert.ok(namespaces.has('auth'));
+    assert.ok(namespaces.has('nats'));
+    assert.ok(namespaces.has('jobs'));
+    assert.equal(namespaces.has('webhooks'), false);
+  });
+});
+
+describe('shouldLog', () => {
+  it('respects level thresholds', () => {
+    const config = {
+      enabled: true,
+      namespaces: null,
+      level: 'warn',
+      filePath: null,
+    };
+    assert.equal(shouldLog(config, 'app', 'debug'), false);
+    assert.equal(shouldLog(config, 'app', 'warn'), true);
+    assert.equal(shouldLog(config, 'app', 'error'), true);
+  });
+
+  it('filters by namespace', () => {
+    const config = {
+      enabled: true,
+      namespaces: new Set(['auth']),
+      level: 'debug',
+      filePath: null,
+    };
+    assert.equal(shouldLog(config, 'auth', 'debug'), true);
+    assert.equal(shouldLog(config, 'nats', 'debug'), false);
+  });
+});
+
+describe('redact', () => {
+  it('redacts sensitive keys and token-like strings', () => {
+    const out = redact({
+      password: 'secret',
+      apiKey: 'zmw_abc123def456ghi789jkl',
+      jobId: 'keep-me',
+      authorization: 'Bearer eyJhbGciOiJIUzI1NiJ9.aaa.bbb',
+      nested: { veraeToken: 'zmt_payload.sig' },
+    });
+
+    assert.equal(out.password, '[REDACTED]');
+    assert.equal(out.apiKey, '[REDACTED]');
+    assert.equal(out.jobId, 'keep-me');
+    assert.equal(out.authorization, '[REDACTED]');
+    assert.equal(out.nested.veraeToken, '[REDACTED]');
+  });
+});
+
+describe('createDebugger', () => {
+  /** @type {string[]} */
+  let lines;
+  const prev = { ...process.env };
+
+  beforeEach(() => {
+    lines = [];
+    setDebugTestSink((line) => lines.push(line));
+  });
+
+  afterEach(() => {
+    setDebugTestSink(null);
+    for (const key of Object.keys(process.env)) {
+      if (!(key in prev)) delete process.env[key];
+    }
+    Object.assign(process.env, prev);
+  });
+
+  it('is silent when DEBUG_VERAE is unset', () => {
+    delete process.env.DEBUG_VERAE;
+    const log = createDebugger('auth');
+    log.debug('should not appear', { x: 1 });
+    assert.equal(lines.length, 0);
+  });
+
+  it('emits only selected namespaces', () => {
+    process.env.DEBUG_VERAE = 'auth';
+    createDebugger('auth').debug('auth-line');
+    createDebugger('nats').debug('nats-line');
+    assert.equal(lines.length, 1);
+    assert.match(lines[0], /auth-line/);
+    assert.doesNotMatch(lines[0], /nats-line/);
+  });
+
+  it('redacts secrets in meta', () => {
+    process.env.DEBUG_VERAE = 'auth';
+    createDebugger('auth').debug('login', {
+      password: 'hunter2',
+      token: 'zmw_supersecretvaluehere12',
+    });
+    assert.equal(lines.length, 1);
+    assert.doesNotMatch(lines[0], /hunter2/);
+    assert.doesNotMatch(lines[0], /zmw_supersecret/);
+    assert.match(lines[0], /REDACTED/);
+  });
+});
+
+describe('withTrace', () => {
+  it('propagates traceId to nested async work', async () => {
+    const outerId = generateTraceId();
+    let innerId = null;
+
+    await withTrace({ traceId: outerId, span: 'outer' }, async () => {
+      assert.equal(getTraceId(), outerId);
+      await withTrace({ span: 'inner' }, async () => {
+        innerId = getTraceId();
+      });
+    });
+
+    assert.equal(innerId, outerId);
+    assert.equal(getTraceId(), null);
+  });
+});
+
+describe('loadDebugConfig', () => {
+  it('reads level and file from env', () => {
+    process.env.DEBUG_VERAE = '1';
+    process.env.DEBUG_VERAE_LEVEL = 'error';
+    process.env.DEBUG_VERAE_FILE = '/tmp/verae-debug.log';
+    const cfg = loadDebugConfig(process.env);
+    assert.equal(cfg.enabled, true);
+    assert.equal(cfg.level, 'error');
+    assert.equal(cfg.filePath, '/tmp/verae-debug.log');
+  });
+});
--- a/packages/verae-zapier-middleware/test/unit/store.test.js
+++ b/packages/verae-zapier-middleware/test/unit/store.test.js
@ -0,0 +1,105 @@
+/**
+ * GATE 3 — Store unit tests
+ */
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  useTempStore,
+  seedFreeTenant,
+  seedEnterpriseTenant,
+} from '../helpers.js';
+import { getTenantByApiKey, resolveLimits, getTenant } from '../../src/store/tenants.js';
+import {
+  createWebhook,
+  getActiveWebhooks,
+  listWebhooksForTenant,
+  deleteWebhook,
+} from '../../src/store/webhooks.js';
+import { getUsage, incrementUsage } from '../../src/store/usage.js';
+import { reloadStore, getStore } from '../../src/store/db.js';
+
+describe('stores', () => {
+  /** @type {ReturnType<typeof useTempStore>} */
+  let ctx;
+
+  beforeEach(() => {
+    ctx = useTempStore();
+  });
+
+  afterEach(() => {
+    ctx.cleanup();
+  });
+
+  it('create tenant → API key resolves to same tenant', () => {
+    const { tenant, apiKey } = seedFreeTenant();
+    const found = getTenantByApiKey(apiKey);
+    assert.ok(found);
+    assert.equal(found.id, tenant.id);
+    assert.equal(found.plan, 'free');
+  });
+
+  it('free plan limits applied; enterprise contract overrides', () => {
+    const { tenant: free } = seedFreeTenant();
+    const freeLimits = resolveLimits(free);
+    assert.equal(freeLimits.timestamps, 50);
+    assert.equal(freeLimits.batch, false);
+
+    const { tenant: ent } = seedEnterpriseTenant();
+    const entLimits = resolveLimits(ent);
+    assert.equal(entLimits.timestamps, 10);
+    assert.equal(entLimits.batch, true);
+    assert.equal(entLimits.batchMaxItems, 5);
+  });
+
+  it('webhook isolation per tenant', () => {
+    seedFreeTenant({ id: 'a' });
+    seedFreeTenant({ id: 'b', veraeUsername: 'u2' });
+
+    createWebhook({
+      tenantId: 'a',
+      targetUrl: 'https://hooks.example/a',
+      event: 'timestamp.completed',
+    });
+    createWebhook({
+      tenantId: 'b',
+      targetUrl: 'https://hooks.example/b',
+      event: 'timestamp.completed',
+    });
+
+    const aHooks = listWebhooksForTenant('a');
+    const bHooks = getActiveWebhooks('b', 'timestamp.completed');
+    assert.equal(aHooks.length, 1);
+    assert.equal(aHooks[0].targetUrl, 'https://hooks.example/a');
+    assert.equal(bHooks.length, 1);
+    assert.equal(bHooks[0].tenantId, 'b');
+  });
+
+  it('persist + reload round-trip preserves data', () => {
+    const { tenant, apiKey } = seedFreeTenant({ id: 'persist-me' });
+    incrementUsage(tenant.id, 'timestamps', 3);
+    createWebhook({
+      tenantId: tenant.id,
+      targetUrl: 'https://hooks.example/x',
+      event: 'timestamp.completed',
+    });
+
+    reloadStore(ctx.storePath);
+
+    assert.equal(getTenant('persist-me')?.name, tenant.name);
+    assert.equal(getTenantByApiKey(apiKey)?.id, 'persist-me');
+    assert.equal(getUsage('persist-me').timestamps, 3);
+    assert.equal(getStore().webhooks.length, 1);
+  });
+
+  it('deleteWebhook removes by id', () => {
+    seedFreeTenant({ id: 'w' });
+    const hook = createWebhook({
+      tenantId: 'w',
+      targetUrl: 'https://hooks.example/w',
+      event: 'timestamp.completed',
+    });
+    assert.equal(deleteWebhook({ tenantId: 'w', hookId: hook.id }), true);
+    assert.equal(listWebhooksForTenant('w').length, 0);
+  });
+});
--- a/packages/verae-zapier-middleware/test/unit/tokens.test.js
+++ b/packages/verae-zapier-middleware/test/unit/tokens.test.js
@ -0,0 +1,55 @@
+/**
+ * GATE 4 — Token tests
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  issueSessionToken,
+  parseSessionToken,
+  generateApiKey,
+  isApiKey,
+  extractBearerToken,
+} from '../../src/lib/tokens.js';
+import { config } from '../../src/config.js';
+
+describe('tokens', () => {
+  it('issues and parses session tokens', () => {
+    const token = issueSessionToken({
+      tenantId: 't1',
+      veraeToken: 'mock-jwt-user',
+      expiresAt: '2099-01-01T00:00:00Z',
+    });
+    assert.ok(token.startsWith('zmt_'));
+    const parsed = parseSessionToken(token);
+    assert.equal(parsed.tenantId, 't1');
+    assert.equal(parsed.veraeToken, 'mock-jwt-user');
+  });
+
+  it('rejects forged session tokens', () => {
+    const token = issueSessionToken({
+      tenantId: 't1',
+      veraeToken: 'secret',
+    });
+    const forged = token.slice(0, -4) + 'xxxx';
+    assert.equal(parseSessionToken(forged), null);
+  });
+
+  it('rejects tokens signed with wrong secret', () => {
+    const token = issueSessionToken({
+      tenantId: 't1',
+      veraeToken: 'secret',
+    });
+    const original = config.tokenSecret;
+    config.tokenSecret = 'other-secret';
+    assert.equal(parseSessionToken(token), null);
+    config.tokenSecret = original;
+  });
+
+  it('generates api keys and extracts bearer', () => {
+    const key = generateApiKey();
+    assert.ok(isApiKey(key));
+    assert.equal(extractBearerToken(`Bearer ${key}`), key);
+    assert.equal(extractBearerToken(undefined), null);
+  });
+});
--- a/packages/verae-zapier-middleware/test/unit/veraeClient.test.js
+++ b/packages/verae-zapier-middleware/test/unit/veraeClient.test.js
@ -0,0 +1,64 @@
+/**
+ * GATE 4 — Mock Verae client lifecycle
+ */
+
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { veraeClient, clearMockJobs } from '../../src/clients/veraeClient.js';
+import { config } from '../../src/config.js';
+import { setDebugTestSink, createDebugger } from '../../src/debug/index.js';
+
+describe('veraeClient mock', () => {
+  beforeEach(() => {
+    clearMockJobs();
+    // ensure mock mode (set at process start via env in gate script)
+    assert.equal(config.mockVerae, true, 'MOCK_VERAE must be true for unit tests');
+  });
+
+  it('create → wait → completed', async () => {
+    const login = await veraeClient.login({ username: 'u', password: 'p' });
+    assert.ok(login.token.startsWith('mock-jwt-'));
+
+    const { jobId } = await veraeClient.createTimestamp(login.token, {
+      data: 'hello',
+      hashAlg: 'SHA256',
+    });
+    assert.ok(jobId);
+
+    const status = await veraeClient.waitForJob(login.token, jobId, {
+      maxAttempts: 40,
+      intervalMs: 20,
+    });
+    assert.equal(status.status, 'completed');
+    assert.ok(status.result.startsWith('mock-cert-'));
+  });
+
+  it('verify accepts mock certificates', async () => {
+    const login = await veraeClient.login({ username: 'u', password: 'p' });
+    const { jobId } = await veraeClient.createTimestamp(login.token, { data: 'x' });
+    const status = await veraeClient.waitForJob(login.token, jobId, {
+      maxAttempts: 40,
+      intervalMs: 20,
+    });
+    const result = await veraeClient.verify(login.token, { certificate: status.result });
+    assert.equal(result.valid, true);
+  });
+
+  it('debug http logs do not include Authorization values', () => {
+    const lines = [];
+    setDebugTestSink((line) => lines.push(line));
+    process.env.DEBUG_VERAE = 'http';
+    const log = createDebugger('http');
+    log.debug('verae request', {
+      method: 'POST',
+      path: '/api/timestamp',
+      authorization: 'Bearer super-secret-token-value',
+      hasToken: true,
+    });
+    setDebugTestSink(null);
+    delete process.env.DEBUG_VERAE;
+    assert.equal(lines.length, 1);
+    assert.doesNotMatch(lines[0], /super-secret-token-value/);
+    assert.match(lines[0], /REDACTED|hasToken/);
+  });
+});
--- a/packages/verae-zapier/README.md
+++ b/packages/verae-zapier/README.md
@ -0,0 +1,34 @@
+# verae-zapier
+
+Zapier Platform CLI app for Verae. **Phase 11** in [../TODO.md](../TODO.md).
+
+## Role
+
+Runs on **Zapier’s servers**. Calls only the middleware HTTPS API (`MIDDLEWARE_BASE_URL`), never NATS and never `api.veraetime.net` directly.
+
+## Planned modules
+
+| File | Purpose |
+|------|---------|
+| `authentication.js` | Custom API key auth → `GET /zapier/v1/auth/me` |
+| `index.js` | App definition, beforeRequest, afterResponse error mapping |
+| `creates/timestamp_and_wait.js` | Primary action |
+| `creates/create_timestamp.js` | Async jobId action |
+| `creates/verify_timestamp.js` | Verify certificate |
+| `creates/batch_timestamp.js` | Batch create |
+| `searches/job_status.js` | Lookup by jobId |
+| `triggers/timestamp_completed.js` | REST Hook |
+
+See [../docs/developer/modules/function-reference.md](../docs/developer/modules/function-reference.md) for I/O contracts.
+
+## Env
+
+```bash
+export MIDDLEWARE_BASE_URL=https://your-middleware.example.com
+```
+
+## Gate
+
+```bash
+npm run gate:11   # from monorepo root, after Phase 11 implementation
+```
--- a/packages/verae-zapier/authentication.js
+++ b/packages/verae-zapier/authentication.js
@ -0,0 +1,38 @@
+/**
+ * Custom API key auth against Verae middleware.
+ * @module authentication
+ */
+
+const middlewareBase = () =>
+  process.env.MIDDLEWARE_BASE_URL || 'http://127.0.0.1:3100';
+
+/**
+ * Zapier connection test — validates API key.
+ * @param {object} z
+ * @param {object} bundle
+ */
+const testAuth = async (z, bundle) => {
+  const response = await z.request({
+    url: `${middlewareBase()}/zapier/v1/auth/me`,
+    headers: {
+      Authorization: `Bearer ${bundle.authData.api_key}`,
+    },
+  });
+  return response.data;
+};
+
+module.exports = {
+  type: 'custom',
+  fields: [
+    {
+      key: 'api_key',
+      type: 'string',
+      required: true,
+      label: 'API Key',
+      helpText:
+        'Your Verae API key (zmw_…) from signup or admin provisioning.',
+    },
+  ],
+  test: testAuth,
+  connectionLabel: '{{tenantId}} ({{plan}})',
+};
--- a/packages/verae-zapier/creates/batch_timestamp.js
+++ b/packages/verae-zapier/creates/batch_timestamp.js
@ -0,0 +1,39 @@
+const base = () => process.env.MIDDLEWARE_BASE_URL || 'http://127.0.0.1:3100';
+
+const perform = async (z, bundle) => {
+  const items = (bundle.inputData.items || '')
+    .split('\n')
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((data) => ({ data }));
+
+  const response = await z.request({
+    method: 'POST',
+    url: `${base()}/zapier/v1/timestamp/batch`,
+    body: { items },
+  });
+  return response.data;
+};
+
+module.exports = {
+  key: 'batch_timestamp',
+  noun: 'Timestamp',
+  display: {
+    label: 'Create Batch Timestamps',
+    description: 'Submit multiple data lines for timestamping (paid plans).',
+  },
+  operation: {
+    inputFields: [
+      {
+        key: 'items',
+        label: 'Data Lines',
+        type: 'text',
+        required: true,
+        helpText: 'One payload per line.',
+      },
+    ],
+    perform,
+    sample: { jobIds: ['id-1', 'id-2'] },
+    outputFields: [{ key: 'jobIds', label: 'Job IDs' }],
+  },
+};
--- a/packages/verae-zapier/creates/create_timestamp.js
+++ b/packages/verae-zapier/creates/create_timestamp.js
@ -0,0 +1,37 @@
+const base = () => process.env.MIDDLEWARE_BASE_URL || 'http://127.0.0.1:3100';
+
+const perform = async (z, bundle) => {
+  const response = await z.request({
+    method: 'POST',
+    url: `${base()}/zapier/v1/timestamp`,
+    body: {
+      data: bundle.inputData.data,
+      hashAlg: bundle.inputData.hashAlg || undefined,
+    },
+  });
+  return response.data;
+};
+
+module.exports = {
+  key: 'create_timestamp',
+  noun: 'Timestamp',
+  display: {
+    label: 'Create Timestamp (Async)',
+    description: 'Submits data for timestamping and returns a job ID.',
+  },
+  operation: {
+    inputFields: [
+      { key: 'data', label: 'Data', type: 'string', required: true },
+      {
+        key: 'hashAlg',
+        label: 'Hash Algorithm',
+        type: 'string',
+        required: false,
+        default: 'SHA256',
+      },
+    ],
+    perform,
+    sample: { jobId: '550e8400-e29b-41d4-a716-446655440000' },
+    outputFields: [{ key: 'jobId', label: 'Job ID' }],
+  },
+};
--- a/packages/verae-zapier/creates/timestamp_and_wait.js
+++ b/packages/verae-zapier/creates/timestamp_and_wait.js
@ -0,0 +1,54 @@
+const base = () => process.env.MIDDLEWARE_BASE_URL || 'http://127.0.0.1:3100';
+
+const perform = async (z, bundle) => {
+  const response = await z.request({
+    method: 'POST',
+    url: `${base()}/zapier/v1/timestamp/wait`,
+    body: {
+      data: bundle.inputData.data,
+      hashAlg: bundle.inputData.hashAlg || undefined,
+    },
+  });
+  return response.data;
+};
+
+module.exports = {
+  key: 'timestamp_and_wait',
+  noun: 'Timestamp',
+  display: {
+    label: 'Create Timestamp and Wait',
+    description:
+      'Submits data for blockchain timestamping and waits for the certificate.',
+  },
+  operation: {
+    inputFields: [
+      {
+        key: 'data',
+        label: 'Data',
+        type: 'string',
+        required: true,
+        helpText: 'Content to timestamp on the blockchain.',
+      },
+      {
+        key: 'hashAlg',
+        label: 'Hash Algorithm',
+        type: 'string',
+        required: false,
+        default: 'SHA256',
+      },
+    ],
+    perform,
+    sample: {
+      id: '550e8400-e29b-41d4-a716-446655440000',
+      status: 'completed',
+      result: 'mock-cert-example',
+      completedAt: '2023-01-01T12:05:00Z',
+    },
+    outputFields: [
+      { key: 'id', label: 'Job ID' },
+      { key: 'status', label: 'Status' },
+      { key: 'result', label: 'Certificate' },
+      { key: 'completedAt', label: 'Completed At', type: 'datetime' },
+    ],
+  },
+};
--- a/packages/verae-zapier/creates/verify_timestamp.js
+++ b/packages/verae-zapier/creates/verify_timestamp.js
@ -0,0 +1,36 @@
+const base = () => process.env.MIDDLEWARE_BASE_URL || 'http://127.0.0.1:3100';
+
+const perform = async (z, bundle) => {
+  const response = await z.request({
+    method: 'POST',
+    url: `${base()}/zapier/v1/verify`,
+    body: { certificate: bundle.inputData.certificate },
+  });
+  return response.data;
+};
+
+module.exports = {
+  key: 'verify_timestamp',
+  noun: 'Verification',
+  display: {
+    label: 'Verify Timestamp',
+    description: 'Verify a timestamp certificate.',
+  },
+  operation: {
+    inputFields: [
+      {
+        key: 'certificate',
+        label: 'Certificate',
+        type: 'text',
+        required: true,
+      },
+    ],
+    perform,
+    sample: { valid: true, timestamp: '2023-01-01T12:00:00Z', blockIndex: 42 },
+    outputFields: [
+      { key: 'valid', label: 'Valid', type: 'boolean' },
+      { key: 'timestamp', label: 'Timestamp', type: 'datetime' },
+      { key: 'blockIndex', label: 'Block Index', type: 'integer' },
+    ],
+  },
+};
--- a/packages/verae-zapier/index.js
+++ b/packages/verae-zapier/index.js
@ -0,0 +1,76 @@
+/**
+ * Verae Zapier Platform app definition.
+ * @module index
+ */
+
+const authentication = require('./authentication');
+const timestampAndWait = require('./creates/timestamp_and_wait');
+const createTimestamp = require('./creates/create_timestamp');
+const verifyTimestamp = require('./creates/verify_timestamp');
+const batchTimestamp = require('./creates/batch_timestamp');
+const jobStatus = require('./searches/job_status');
+const timestampCompleted = require('./triggers/timestamp_completed');
+
+/**
+ * Attach middleware API key to every outbound request.
+ * @param {object} request
+ * @param {object} _z
+ * @param {object} bundle
+ */
+const addApiKey = (request, _z, bundle) => {
+  request.headers = request.headers || {};
+  request.headers.Authorization = `Bearer ${bundle.authData.api_key}`;
+  return request;
+};
+
+/**
+ * Map middleware billing errors to Zapier errors.
+ * @param {object} response
+ * @param {object} z
+ */
+const mapMiddlewareErrors = (response, z) => {
+  if (response.status === 402) {
+    throw new z.errors.Error(
+      `${response.data?.error ?? 'Quota exceeded'}. Upgrade at ${response.data?.details?.upgradeUrl ?? response.data?.upgradeUrl ?? 'your billing portal'}.`,
+      'QuotaExceeded',
+      402,
+    );
+  }
+
+  if (response.status === 403 && response.data?.code === 'PLAN_UPGRADE_REQUIRED') {
+    throw new z.errors.Error(
+      response.data?.error ?? 'This action requires a paid plan.',
+      'PlanUpgradeRequired',
+      403,
+    );
+  }
+
+  return response;
+};
+
+let platformVersion = '15.19.0';
+try {
+  platformVersion = require('zapier-platform-core').version;
+} catch {
+  // optional for unit tests without full install
+}
+
+module.exports = {
+  version: require('./package.json').version,
+  platformVersion,
+  authentication,
+  beforeRequest: [addApiKey],
+  afterResponse: [mapMiddlewareErrors],
+  triggers: {
+    [timestampCompleted.key]: timestampCompleted,
+  },
+  creates: {
+    [timestampAndWait.key]: timestampAndWait,
+    [createTimestamp.key]: createTimestamp,
+    [verifyTimestamp.key]: verifyTimestamp,
+    [batchTimestamp.key]: batchTimestamp,
+  },
+  searches: {
+    [jobStatus.key]: jobStatus,
+  },
+};
--- a/packages/verae-zapier/package.json
+++ b/packages/verae-zapier/package.json
@ -0,0 +1,17 @@
+{
+  "name": "verae-zapier",
+  "version": "1.0.0",
+  "description": "Zapier CLI app for Verae Timestamping via middleware",
+  "main": "index.js",
+  "scripts": {
+    "test": "node --test test/**/*.test.js"
+  },
+  "engines": {
+    "node": ">=18",
+    "npm": ">=5.6.0"
+  },
+  "dependencies": {
+    "zapier-platform-core": "15.19.0"
+  },
+  "private": true
+}
--- a/packages/verae-zapier/searches/job_status.js
+++ b/packages/verae-zapier/searches/job_status.js
@ -0,0 +1,33 @@
+const base = () => process.env.MIDDLEWARE_BASE_URL || 'http://127.0.0.1:3100';
+
+const perform = async (z, bundle) => {
+  const response = await z.request({
+    url: `${base()}/zapier/v1/status/${encodeURIComponent(bundle.inputData.jobId)}`,
+  });
+  return [response.data];
+};
+
+module.exports = {
+  key: 'job_status',
+  noun: 'Job',
+  display: {
+    label: 'Find Job Status',
+    description: 'Look up a timestamp job by ID.',
+  },
+  operation: {
+    inputFields: [
+      { key: 'jobId', label: 'Job ID', type: 'string', required: true },
+    ],
+    perform,
+    sample: {
+      id: '550e8400-e29b-41d4-a716-446655440000',
+      status: 'completed',
+      result: 'mock-cert',
+    },
+    outputFields: [
+      { key: 'id', label: 'Job ID' },
+      { key: 'status', label: 'Status' },
+      { key: 'result', label: 'Result' },
+    ],
+  },
+};
--- a/packages/verae-zapier/test/app.test.js
+++ b/packages/verae-zapier/test/app.test.js
@ -0,0 +1,92 @@
+/**
+ * GATE 11 — Zapier package shape tests (no live Zapier CLI required)
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+
+const App = require('../index');
+const authentication = require('../authentication');
+const timestampAndWait = require('../creates/timestamp_and_wait');
+const createTimestamp = require('../creates/create_timestamp');
+const verifyTimestamp = require('../creates/verify_timestamp');
+const batchTimestamp = require('../creates/batch_timestamp');
+const jobStatus = require('../searches/job_status');
+const timestampCompleted = require('../triggers/timestamp_completed');
+
+describe('verae-zapier app definition', () => {
+  it('exports authentication with api_key field', () => {
+    assert.equal(authentication.type, 'custom');
+    assert.ok(authentication.fields.some((f) => f.key === 'api_key'));
+  });
+
+  it('wires creates, searches, triggers', () => {
+    assert.ok(App.creates.timestamp_and_wait);
+    assert.ok(App.creates.create_timestamp);
+    assert.ok(App.creates.verify_timestamp);
+    assert.ok(App.creates.batch_timestamp);
+    assert.ok(App.searches.job_status);
+    assert.ok(App.triggers.timestamp_completed);
+  });
+
+  it('create actions target middleware paths', () => {
+    process.env.MIDDLEWARE_BASE_URL = 'https://mw.example.com';
+    const urls = [];
+    const z = {
+      request: async (opts) => {
+        urls.push(opts.url);
+        return { data: { ok: true } };
+      },
+    };
+    const bundle = {
+      authData: { api_key: 'zmw_test' },
+      inputData: { data: 'x', certificate: 'c', items: 'a\nb', jobId: 'j1' },
+    };
+
+    return Promise.all([
+      timestampAndWait.operation.perform(z, bundle),
+      createTimestamp.operation.perform(z, bundle),
+      verifyTimestamp.operation.perform(z, bundle),
+      batchTimestamp.operation.perform(z, bundle),
+      jobStatus.operation.perform(z, bundle),
+    ]).then(() => {
+      assert.ok(urls.some((u) => u.endsWith('/zapier/v1/timestamp/wait')));
+      assert.ok(urls.some((u) => u.endsWith('/zapier/v1/timestamp')));
+      assert.ok(urls.some((u) => u.endsWith('/zapier/v1/verify')));
+      assert.ok(urls.some((u) => u.endsWith('/zapier/v1/timestamp/batch')));
+      assert.ok(urls.some((u) => u.includes('/zapier/v1/status/')));
+    });
+  });
+
+  it('trigger subscribe/unsubscribe shapes', async () => {
+    process.env.MIDDLEWARE_BASE_URL = 'https://mw.example.com';
+    const calls = [];
+    const z = {
+      request: async (opts) => {
+        calls.push(opts);
+        return { data: { id: 'hook-1' } };
+      },
+    };
+
+    const id = await timestampCompleted.operation.performSubscribe(z, {
+      targetUrl: 'https://hooks.zapier.com/x',
+      authData: { api_key: 'k' },
+    });
+    assert.equal(id, 'hook-1');
+    assert.equal(calls[0].method, 'POST');
+    assert.match(calls[0].url, /webhooks\/subscribe$/);
+    assert.equal(calls[0].body.event, 'timestamp.completed');
+
+    await timestampCompleted.operation.performUnsubscribe(z, {
+      subscribeData: 'hook-1',
+      authData: { api_key: 'k' },
+    });
+    assert.equal(calls[1].method, 'DELETE');
+    assert.match(calls[1].url, /webhooks\/unsubscribe$/);
+  });
+
+  it('beforeRequest adds Authorization bearer', () => {
+    const req = App.beforeRequest[0]({}, null, { authData: { api_key: 'zmw_abc' } });
+    assert.equal(req.headers.Authorization, 'Bearer zmw_abc');
+  });
+});
--- a/packages/verae-zapier/triggers/timestamp_completed.js
+++ b/packages/verae-zapier/triggers/timestamp_completed.js
@ -0,0 +1,53 @@
+const base = () => process.env.MIDDLEWARE_BASE_URL || 'http://127.0.0.1:3100';
+
+const subscribeHook = async (z, bundle) => {
+  const response = await z.request({
+    method: 'POST',
+    url: `${base()}/zapier/v1/webhooks/subscribe`,
+    body: {
+      targetUrl: bundle.targetUrl,
+      event: 'timestamp.completed',
+    },
+  });
+  return response.data.id;
+};
+
+const unsubscribeHook = async (z, bundle) => {
+  await z.request({
+    method: 'DELETE',
+    url: `${base()}/zapier/v1/webhooks/unsubscribe`,
+    body: {
+      hookId: bundle.subscribeData,
+    },
+  });
+  return {};
+};
+
+const perform = async (z, bundle) => [bundle.cleanedRequest];
+
+const performList = async () => [];
+
+module.exports = {
+  key: 'timestamp_completed',
+  noun: 'Timestamp',
+  display: {
+    label: 'Timestamp Completed',
+    description: 'Triggers when a blockchain timestamp job completes.',
+  },
+  operation: {
+    type: 'hook',
+    perform,
+    performList,
+    performSubscribe: subscribeHook,
+    performUnsubscribe: unsubscribeHook,
+    sample: {
+      event: 'timestamp.completed',
+      jobId: '550e8400-e29b-41d4-a716-446655440000',
+      status: { id: '550e8400-e29b-41d4-a716-446655440000', status: 'completed' },
+    },
+    outputFields: [
+      { key: 'event', label: 'Event' },
+      { key: 'jobId', label: 'Job ID' },
+    ],
+  },
+};
--- a/packages/zappier/.env.example
+++ b/packages/zappier/.env.example
@ -0,0 +1,5 @@
+# Copy to .env (gitignored) and fill in your real Stripe secret key.
+# The billing job (src/jobs/report-usage.ts) loads this via dotenv.
+STRIPE_SECRET_KEY=sk_test_replace_me
+# Optional: override the SQLite database location (default: zappier.db)
+# ZAPPIER_DB=/absolute/path/to/zappier.db
--- a/packages/zappier/.gitignore
+++ b/packages/zappier/.gitignore
@ -0,0 +1,5 @@
+node_modules/
+dist/
+.env
+zappier.db
+zappier.db-journal
--- a/packages/zappier/README.md
+++ b/packages/zappier/README.md
@ -0,0 +1,134 @@
+# Zappier
+
+Metered API platform: per-endpoint pricing, customer types with multipliers and
+monthly credits, a usage ledger, Stripe metered billing, purchase-order
+invoicing, a company admin console, a self-service customer portal, and a
+Zapier integration.
+
+## Documentation
+
+- **[docs/USER-MANUAL.md](docs/USER-MANUAL.md)** — operations & usage manual
+- **[docs/ACCOUNTING.md](docs/ACCOUNTING.md)** — company accounting: invoices, PO billing, reports, CSV
+- **[docs/USER-MANAGEMENT.md](docs/USER-MANAGEMENT.md)** — pricing, customer types, customer accounts
+- **[docs/CUSTOMER-PORTAL.md](docs/CUSTOMER-PORTAL.md)** — end-user portal: signup, 2FA, reloads, invoices
+- **[docs/DEVELOPER.md](docs/DEVELOPER.md)** — full developer documentation
+- **[docs/WALKTHROUGH.md](docs/WALKTHROUGH.md)** — original step-by-step pricing walkthrough
+
+## Surfaces
+
+| Surface | URL | Audience |
+|---|---|---|
+| Public API | `/v1/*` | API customers (`x-api-key`) |
+| Interactive API docs | `/docs` | Integrating developers |
+| Admin console | `/admin` | Company ops & accounting |
+| Customer portal | `/portal` | End-user customers (signup, 2FA, billing) |
+| Zapier app | `zapier-app/` | No-code users via Zapier |
+
+## Pricing model
+
+`openapi.yaml` defines the API surface; each `operationId` is a rate-card key.
+Endpoints carry **list prices** (seed: `src/pricing.ts` → `DEFAULT_RATE_CARD`).
+Customer types are **tier configs** (`DEFAULT_TIERS`) with a `multiplier`, a
+`monthlyCreditCents` quota, and an optional `defaultRule` for endpoints not on the card.
+Individual customers can carry a `multiplierOverride`.
+Billed price = `round(list price × multiplier)`; usage up to the monthly credit is free.
+Pricing is editable at runtime in the admin console.
+
+### Seed rate card (list prices, cents per call)
+
+| Endpoint       | Model    | List price                                   |
+| -------------- | -------- | -------------------------------------------- |
+| `status`       | free     | 0                                            |
+| `storage-list` | free     | 0                                            |
+| `transform`    | fixed    | 4                                            |
+| `storage`      | variable | 10 + 1 per KB metadata + 50 per MB attached  |
+
+### Seed customer types
+
+| Tier       | Multiplier | Monthly credit | Default rule (unlisted endpoints) |
+| ---------- | ---------- | -------------- | --------------------------------- |
+| `free`     | 1.0        | 100 cents      | none — call rejected with 403     |
+| `pro`      | 0.5        | 1000 cents     | fixed 8 list → 4 billed           |
+| `business` | 0.25       | 10000 cents    | fixed 8 list → 2 billed           |
+
+Adding a new API call = add it to `openapi.yaml`, then price it in the admin UI.
+Adding a customer type = create it in the admin UI. Variable pricing = base per call +
+metadata size (rounded up to KB) + attachment size (rounded up to MB), then the multiplier.
+
+## Quickstart
+
+```sh
+npm install
+npm run dev
+```
+
+The server starts on port 3000. API docs at
+[http://localhost:3000/docs](http://localhost:3000/docs), admin console at
+`/admin`, customer portal at `/portal`.
+
+## Deploying
+
+```sh
+npm ci && npm run build
+node dist/index.js        # runs from ANY working directory
+```
+
+All runtime paths (SQLite default, `.env`, OpenAPI spec, static assets)
+resolve from the installation root, so the compiled server works under
+systemd, Docker, or cron regardless of cwd. `PORT` and `ZAPPIER_DB` remain
+environment-overridable.
+
+## Environment variables
+
+| Variable            | Default        | Purpose                                             |
+| ------------------- | -------------- | --------------------------------------------------- |
+| `PORT`              | `3000`         | HTTP port the server listens on                     |
+| `ZAPPIER_DB`        | `<root>/zappier.db` | SQLite database file path                       |
+| `ADMIN_KEY`         | `admin-dev-key`| Admin UI / admin API key — **set a real secret in production** |
+| `ADMIN_USER`        | `admin`        | Admin UI primary login username                     |
+| `DEMO_ADMIN_USER`   | `demo`         | Admin UI demo login username                        |
+| `DEMO_ADMIN_PASSWORD` | `$$$Adm1n###` | Demo login password — **override in production**    |
+| `STRIPE_SECRET_KEY` | _(none)_       | Stripe secret key — billing job and portal reloads  |
+
+## Billing
+
+Usage is reported to Stripe by a job (loads `STRIPE_SECRET_KEY` from `.env`):
+
+```sh
+npx ts-node src/jobs/report-usage.ts
+```
+
+The job sums each customer's usage since the first of the current month (UTC),
+applies the tier's monthly credit, and reports only the **delta** above what was
+already reported — re-runs are safe. Idempotency comes from three layers: a
+`billing_reports` ledger (cumulative cents per customer per month), an atomic
+`job_locks` run guard (1 h TTL), and a deterministic Stripe event `identifier`
+(`customer:period:billable`) that dedupes crash retries. It requires a Stripe
+meter named `zappier.api_cents` with Sum aggregation over the `value` field.
+
+A Kimi cron job ("Zappier billing · report usage to Stripe") runs it daily at
+06:17 America/New_York with a completion notification.
+
+Purchase-order customers are invoiced manually from the admin console
+(**Invoices** tab); prepaid balances from the customer portal are drawn down
+automatically at invoice issue. See `docs/ACCOUNTING.md`.
+
+## Zapier app
+
+The companion Zapier integration lives in `zapier-app/`:
+
+```sh
+cd zapier-app
+npm install
+npm test
+```
+
+To deploy it, create a Zapier developer account, run `zapier login`, then
+`zapier push` from the `zapier-app/` directory.
+
+## Testing
+
+```sh
+npm test                    # root API/service suite (jest, 165 tests)
+cd zapier-app && npm test   # Zapier integration suite (mocha, 4 tests)
+```
--- a/packages/zappier/admin/app.js
+++ b/packages/zappier/admin/app.js
@ -0,0 +1,672 @@
+const state = { pricing: null, customers: [], invoices: [], report: null, trend: null, system: null, users: [] };
+const TOKEN_KEY = 'zappier-admin-token';
+
+/* ---------------- auth ---------------- */
+
+function token() {
+  return localStorage.getItem(TOKEN_KEY);
+}
+
+function showLogin(message = '') {
+  document.getElementById('shell').classList.remove('on');
+  document.getElementById('login').style.display = 'grid';
+  document.getElementById('login-error').textContent = message;
+}
+
+function showShell() {
+  document.getElementById('login').style.display = 'none';
+  document.getElementById('shell').classList.add('on');
+}
+
+document.getElementById('login-form').addEventListener('submit', async (e) => {
+  e.preventDefault();
+  const username = document.getElementById('login-username').value.trim();
+  const password = document.getElementById('login-password').value;
+  try {
+    const res = await fetch('/admin/api/login', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ username, password }),
+    });
+    if (!res.ok) throw new Error((await res.json()).error || 'Login failed');
+    const { token: t } = await res.json();
+    localStorage.setItem(TOKEN_KEY, t);
+    showShell();
+    load().catch((err) => say(err.message, true));
+  } catch (err) {
+    showLogin(err.message);
+  }
+});
+
+document.getElementById('logout').addEventListener('click', () => {
+  localStorage.removeItem(TOKEN_KEY);
+  location.reload();
+});
+
+/* ---------------- api + status ---------------- */
+
+async function api(path, options = {}) {
+  const res = await fetch(`/admin/api${path}`, {
+    ...options,
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${token()}` },
+  });
+  if (res.status === 403) {
+    localStorage.removeItem(TOKEN_KEY);
+    showLogin('Session expired — sign in again.');
+    throw new Error('Session expired.');
+  }
+  if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
+  return res.json();
+}
+
+let statusTimer;
+function say(msg, isError = false) {
+  const el = document.getElementById('status');
+  el.textContent = msg;
+  el.classList.toggle('error', isError);
+  el.classList.add('show');
+  clearTimeout(statusTimer);
+  statusTimer = setTimeout(() => el.classList.remove('show'), 4000);
+}
+
+/* ---------------- shared helpers ---------------- */
+
+const fmt = (cents) =>
+  (cents < 0 ? '-$' : '$') + (Math.abs(cents) / 100).toFixed(2);
+const fmtDate = (ms) => (ms ? new Date(ms).toISOString().slice(0, 10) : '—');
+const customerName = (id) => state.customers.find((c) => c.id === id)?.name ?? id;
+
+function customerOptions(selected, includeAll = false) {
+  const all = includeAll ? `<option value="">All customers</option>` : '';
+  return (
+    all +
+    state.customers
+      .map((c) => `<option value="${c.id}" ${c.id === selected ? 'selected' : ''}>${c.name} (${c.id})</option>`)
+      .join('')
+  );
+}
+
+function currentPeriod() {
+  return new Date().toISOString().slice(0, 7);
+}
+
+async function load() {
+  state.pricing = await api('/pricing');
+  state.customers = (await api('/customers')).customers;
+  state.invoices = (await api('/invoices')).invoices;
+  state.users = (await api('/users')).users;
+  renderEndpoints();
+  renderTiers();
+  renderCustomers();
+  renderInvoices();
+  renderReports();
+  renderSystem();
+  renderUsers();
+}
+
+/* ---------------- rate card ---------------- */
+
+function ruleInputs(id, rule) {
+  const fields =
+    rule.kind === 'fixed'
+      ? { fixedCents: rule.fixedCents }
+      : rule.kind === 'variable'
+        ? { baseCents: rule.baseCents, perKbCents: rule.perKbCents, perMbCents: rule.perMbCents }
+        : {};
+  return Object.entries(fields)
+    .map(
+      ([k, v]) =>
+        `<label class="field"><span>${k}</span><input data-endpoint="${id}" data-field="${k}" type="number" step="any" value="${v}" size="6"></label>`,
+    )
+    .join('');
+}
+
+function renderEndpoints() {
+  const rows = Object.entries(state.pricing.rateCard.endpoints)
+    .map(
+      ([id, rule]) => `<tr>
+        <td class="id">${id}</td>
+        <td><span class="pill ${rule.kind}">${rule.kind}</span></td>
+        <td><select data-endpoint-kind="${id}">
+          ${['free', 'fixed', 'variable'].map((k) => `<option ${k === rule.kind ? 'selected' : ''}>${k}</option>`).join('')}
+        </select></td>
+        <td>${ruleInputs(id, rule)}</td>
+        <td class="row-actions">
+          <button class="btn" onclick="saveEndpoint('${id}')">Save</button>
+          <button class="btn ghost" onclick="deleteEndpoint('${id}')">Delete</button>
+        </td>
+      </tr>`,
+    )
+    .join('');
+  document.getElementById('endpoints').innerHTML = `
+    <h2>Rate card</h2>
+    <p class="lede">Per-endpoint list prices, in cents. Changes apply to the next API call — no restart.</p>
+    <div class="card"><table>
+      <thead><tr><th>Endpoint (operationId)</th><th>Kind</th><th>Set kind</th><th>Prices (cents)</th><th></th></tr></thead>
+      <tbody>${rows}</tbody>
+    </table></div>
+    <div class="card">
+      <h3>Add endpoint</h3>
+      <input id="new-endpoint-id" placeholder="operationId">
+      <select id="new-endpoint-kind"><option>free</option><option selected>fixed</option><option>variable</option></select>
+      <button class="btn" onclick="addEndpoint()">Add</button>
+      <p class="hint">The operationId must match an operation in openapi.yaml.</p>
+    </div>`;
+}
+
+async function saveEndpoint(id) {
+  const kind = document.querySelector(`[data-endpoint-kind="${id}"]`).value;
+  const rule = { kind };
+  document.querySelectorAll(`input[data-endpoint="${id}"]`).forEach((el) => {
+    rule[el.dataset.field] = Number(el.value);
+  });
+  if (kind === 'fixed' && rule.fixedCents === undefined) rule.fixedCents = 0;
+  if (kind === 'variable') {
+    rule.baseCents = rule.baseCents ?? 0;
+    rule.perKbCents = rule.perKbCents ?? 0;
+    rule.perMbCents = rule.perMbCents ?? 0;
+  }
+  await api(`/endpoints/${id}`, { method: 'PUT', body: JSON.stringify(rule) });
+  say(`Saved ${id}.`);
+  await load();
+}
+
+async function deleteEndpoint(id) {
+  await api(`/endpoints/${id}`, { method: 'DELETE' });
+  say(`Deleted ${id} — calls to it now get 403 unless a tier has a default rule.`);
+  await load();
+}
+
+async function addEndpoint() {
+  const id = document.getElementById('new-endpoint-id').value.trim();
+  const kind = document.getElementById('new-endpoint-kind').value;
+  if (!id) return say('Endpoint id required.', true);
+  const rule =
+    kind === 'free'
+      ? { kind }
+      : kind === 'fixed'
+        ? { kind, fixedCents: 0 }
+        : { kind, baseCents: 0, perKbCents: 0, perMbCents: 0 };
+  await api(`/endpoints/${id}`, { method: 'PUT', body: JSON.stringify(rule) });
+  say(`Added ${id}.`);
+  await load();
+}
+
+/* ---------------- customer types ---------------- */
+
+function renderTiers() {
+  const rows = state.pricing.tiers
+    .map(
+      (t) => `<tr>
+        <td class="id">${t.id}</td>
+        <td><input data-tier="${t.id}" data-field="name" value="${t.name}"></td>
+        <td><input data-tier="${t.id}" data-field="multiplier" type="number" step="any" value="${t.multiplier}" size="5"></td>
+        <td><input data-tier="${t.id}" data-field="monthlyCreditCents" type="number" value="${t.monthlyCreditCents}" size="8"></td>
+        <td class="row-actions">
+          <button class="btn" onclick="saveTier('${t.id}')">Save</button>
+          <button class="btn ghost" onclick="deleteTier('${t.id}')">Delete</button>
+        </td>
+      </tr>`,
+    )
+    .join('');
+  document.getElementById('tiers').innerHTML = `
+    <h2>Customer types</h2>
+    <p class="lede">Multiplier scales every list price (0.5 = 50%). Monthly credit is free included usage, in cents.</p>
+    <div class="card"><table>
+      <thead><tr><th>Id</th><th>Name</th><th>Multiplier</th><th>Monthly credit (cents)</th><th></th></tr></thead>
+      <tbody>${rows}</tbody>
+    </table></div>
+    <div class="card">
+      <h3>Add customer type</h3>
+      <input id="new-tier-id" placeholder="id">
+      <input id="new-tier-name" placeholder="name">
+      <input id="new-tier-multiplier" type="number" step="any" value="1" size="5"> multiplier
+      <button class="btn" onclick="addTier()">Add</button>
+      <p class="hint">New types start with 0 monthly credit — edit after adding.</p>
+    </div>`;
+}
+
+async function saveTier(id) {
+  const body = { id };
+  document.querySelectorAll(`[data-tier="${id}"]`).forEach((el) => {
+    body[el.dataset.field] = el.type === 'number' ? Number(el.value) : el.value;
+  });
+  const existing = state.pricing.tiers.find((t) => t.id === id);
+  if (existing?.defaultRule) body.defaultRule = existing.defaultRule;
+  await api(`/tiers/${id}`, { method: 'PUT', body: JSON.stringify(body) });
+  say(`Saved tier ${id}.`);
+  await load();
+}
+
+async function deleteTier(id) {
+  await api(`/tiers/${id}`, { method: 'DELETE' });
+  say(`Deleted tier ${id}.`);
+  await load();
+}
+
+async function addTier() {
+  const id = document.getElementById('new-tier-id').value.trim();
+  const name = document.getElementById('new-tier-name').value.trim();
+  const multiplier = Number(document.getElementById('new-tier-multiplier').value);
+  if (!id || !name) return say('Tier id and name required.', true);
+  await api(`/tiers/${id}`, {
+    method: 'PUT',
+    body: JSON.stringify({ id, name, multiplier, monthlyCreditCents: 0 }),
+  });
+  say(`Added tier ${id}.`);
+  await load();
+}
+
+/* ---------------- customers ---------------- */
+
+function renderCustomers() {
+  const tierOptions = (selected) =>
+    state.pricing.tiers
+      .map((t) => `<option ${t.id === selected ? 'selected' : ''}>${t.id}</option>`)
+      .join('');
+  const btOptions = (selected) =>
+    ['stripe', 'purchase_order']
+      .map((b) => `<option value="${b}" ${b === (selected ?? 'stripe') ? 'selected' : ''}>${b === 'stripe' ? 'Stripe' : 'Purchase order'}</option>`)
+      .join('');
+  const rows = state.customers
+    .map(
+      (c) => `<tr>
+        <td class="id">${c.id}</td>
+        <td>${c.name}</td>
+        <td><input data-customer="${c.id}" data-field="email" type="email" size="18" value="${c.email ?? ''}" placeholder="—"></td>
+        <td><select data-customer="${c.id}" data-field="tierId">${tierOptions(c.tierId)}</select></td>
+        <td><input data-customer="${c.id}" data-field="multiplierOverride" type="number" step="any" size="5" value="${c.multiplierOverride ?? ''}" placeholder="—"></td>
+        <td><select data-customer="${c.id}" data-field="billingType">${btOptions(c.billingType)}</select></td>
+        <td class="row-actions"><button class="btn" onclick="saveCustomer('${c.id}')">Save</button></td>
+      </tr>`,
+    )
+    .join('');
+  document.getElementById('customers').innerHTML = `
+    <h2>Customers</h2>
+    <p class="lede">Assign types, billing method, and per-customer deals. A multiplier override replaces the type multiplier for that customer.</p>
+    <div class="card"><table>
+      <thead><tr><th>Id</th><th>Name</th><th>Email</th><th>Type</th><th>Multiplier override</th><th>Billing</th><th></th></tr></thead>
+      <tbody>${rows}</tbody>
+    </table></div>
+    <div class="card">
+      <h3>Add customer</h3>
+      <input id="new-customer-name" placeholder="name">
+      <select id="new-customer-tier">${tierOptions(state.pricing.tiers[0]?.id)}</select>
+      <button class="btn" onclick="addCustomer()">Create</button>
+      <p class="hint">The new customer's API key is shown once in the notification — copy it immediately. Set email and billing method after creating.</p>
+    </div>`;
+}
+
+async function saveCustomer(id) {
+  const body = {};
+  document.querySelectorAll(`[data-customer="${id}"]`).forEach((el) => {
+    if (el.value === '') return;
+    body[el.dataset.field] = el.type === 'number' ? Number(el.value) : el.value;
+  });
+  await api(`/customers/${id}`, { method: 'PUT', body: JSON.stringify(body) });
+  say(`Saved customer ${id}.`);
+  await load();
+}
+
+async function addCustomer() {
+  const name = document.getElementById('new-customer-name').value.trim();
+  const tierId = document.getElementById('new-customer-tier').value;
+  if (!name) return say('Customer name required.', true);
+  const created = await api('/customers', {
+    method: 'POST',
+    body: JSON.stringify({ name, tierId }),
+  });
+  say(`Created ${created.id} — API key: ${created.apiKey}`);
+  await load();
+}
+
+/* ---------------- invoices ---------------- */
+
+function renderInvoices() {
+  const rows = state.invoices
+    .slice()
+    .sort((a, b) => b.id.localeCompare(a.id))
+    .map((inv) => {
+      const actions = [];
+      actions.push(`<button class="btn ghost" onclick="viewInvoice('${inv.id}')">View</button>`);
+      if (inv.status === 'draft')
+        actions.push(`<button class="btn" onclick="invoiceAction('${inv.id}','issue')">Issue</button>`);
+      if (inv.status === 'issued')
+        actions.push(`<button class="btn" onclick="invoiceAction('${inv.id}','paid')">Mark paid</button>`);
+      return `<tr>
+        <td class="id">${inv.id}</td>
+        <td>${customerName(inv.customerId)}</td>
+        <td>${inv.period}</td>
+        <td><span class="pill ${inv.status}">${inv.status}</span></td>
+        <td><span class="pill ${inv.billingType}">${inv.billingType === 'stripe' ? 'Stripe' : 'PO'}</span>${inv.poNumber ? ` <span class="id">${inv.poNumber}</span>` : ''}</td>
+        <td class="money">${fmt(inv.totalCents)}</td>
+        <td class="money">${fmt(inv.creditCents)}</td>
+        <td class="money"><b>${fmt(inv.billableCents)}</b></td>
+        <td>${fmtDate(inv.dueAtMs)}</td>
+        <td class="row-actions">${actions.join('')}</td>
+      </tr>`;
+    })
+    .join('');
+  document.getElementById('invoices').innerHTML = `
+    <h2>Invoices</h2>
+    <p class="lede">Generate monthly invoices from metered usage, then issue and collect. Regenerating a period replaces drafts and skips issued/paid invoices.</p>
+    <div class="card">
+      <h3>Generate invoices</h3>
+      <div class="filterbar">
+        <label><span>Period</span><input id="gen-period" type="month" value="${currentPeriod()}"></label>
+        <label><span>Customer</span><select id="gen-customer">${customerOptions('', true)}</select></label>
+        <label><span>PO number (optional)</span><input id="gen-po" placeholder="PO-1234" size="12"></label>
+        <button class="btn" onclick="generateInvoices()">Generate</button>
+      </div>
+      <div id="gen-result"></div>
+    </div>
+    <div class="card">
+      <div class="filterbar">
+        <label><span>Customer</span><select id="inv-filter-customer" onchange="refreshInvoices()">${customerOptions('', true)}</select></label>
+        <label><span>Period</span><input id="inv-filter-period" type="month" onchange="refreshInvoices()"></label>
+        <label><span>Status</span><select id="inv-filter-status" onchange="refreshInvoices()">
+          <option value="">Any</option><option>draft</option><option>issued</option><option>paid</option>
+        </select></label>
+        <button class="btn ghost" onclick="refreshInvoices()">Refresh</button>
+      </div>
+      <table id="inv-table">
+        <thead><tr><th>Invoice</th><th>Customer</th><th>Period</th><th>Status</th><th>Billing</th><th>Total</th><th>Credit</th><th>Due amount</th><th>Due date</th><th></th></tr></thead>
+        <tbody>${rows || '<tr><td colspan="10" style="color:var(--muted)">No invoices yet — generate a period above.</td></tr>'}</tbody>
+      </table>
+    </div>`;
+}
+
+async function generateInvoices() {
+  const period = document.getElementById('gen-period').value;
+  const customerId = document.getElementById('gen-customer').value;
+  const poNumber = document.getElementById('gen-po').value.trim();
+  if (!period) return say('Pick a period first.', true);
+  const result = await api('/invoices/generate', {
+    method: 'POST',
+    body: JSON.stringify({
+      period,
+      ...(customerId ? { customerId } : {}),
+      ...(poNumber ? { poNumber } : {}),
+    }),
+  });
+  const skips = result.skipped
+    .map((s) => `<li>${customerName(s.customerId)}: ${s.reason}</li>`)
+    .join('');
+  document.getElementById('gen-result').innerHTML =
+    `<p class="hint">Generated ${result.generated.length}: ${result.generated.join(', ') || '—'}</p>` +
+    (skips ? `<ul class="skip-list">${skips}</ul>` : '');
+  say(`Generated ${result.generated.length} invoice(s), skipped ${result.skipped.length}.`);
+  await load();
+}
+
+async function refreshInvoices() {
+  const params = new URLSearchParams();
+  const customerId = document.getElementById('inv-filter-customer').value;
+  const period = document.getElementById('inv-filter-period').value;
+  const status = document.getElementById('inv-filter-status').value;
+  if (customerId) params.set('customerId', customerId);
+  if (period) params.set('period', period);
+  if (status) params.set('status', status);
+  state.invoices = (await api(`/invoices?${params}`)).invoices;
+  renderInvoices();
+}
+
+async function invoiceAction(id, action) {
+  await api(`/invoices/${id}/${action}`, { method: 'POST', body: '{}' });
+  say(action === 'issue' ? `Issued ${id}.` : `Marked ${id} paid.`);
+  await load();
+}
+
+async function viewInvoice(id) {
+  const res = await fetch(`/admin/api/invoices/${id}?format=html`, {
+    headers: { authorization: `Bearer ${token()}` },
+  });
+  if (!res.ok) return say(`Could not load ${id}.`, true);
+  const blob = await res.blob();
+  window.open(URL.createObjectURL(blob), '_blank');
+}
+
+/* ---------------- reports ---------------- */
+
+function renderReports() {
+  const periodStart = `${currentPeriod()}-01`;
+  document.getElementById('reports').innerHTML = `
+    <h2>Reports</h2>
+    <p class="lede">Billing and usage analytics across customers. All amounts in USD, converted from integer cents.</p>
+    <div class="card">
+      <h3>Billing report</h3>
+      <div class="filterbar">
+        <label><span>From</span><input id="rep-from" type="date" value="${periodStart}"></label>
+        <label><span>To</span><input id="rep-to" type="date"></label>
+        <label><span>Customer</span><select id="rep-customer">${customerOptions('', true)}</select></label>
+        <label><span>Billing type</span><select id="rep-billing-type">
+          <option value="">Any</option><option value="stripe">Stripe</option><option value="purchase_order">Purchase order</option>
+        </select></label>
+        <button class="btn" onclick="runReport()">Run</button>
+        <button class="btn ghost" onclick="downloadCsv()">Download CSV</button>
+      </div>
+      <div id="rep-summary"></div>
+      <table id="rep-table"></table>
+    </div>
+    <div class="card">
+      <h3>Usage trend</h3>
+      <div class="filterbar">
+        <label><span>Bucket</span><select id="trend-bucket" onchange="runTrend()">
+          <option value="day">Daily</option><option value="week">Weekly</option>
+        </select></label>
+      </div>
+      <div id="trend-chart"></div>
+    </div>`;
+  runReport().catch((err) => say(err.message, true));
+  runTrend().catch((err) => say(err.message, true));
+}
+
+function reportQuery() {
+  const params = new URLSearchParams();
+  const from = document.getElementById('rep-from').value;
+  const to = document.getElementById('rep-to').value;
+  const customerId = document.getElementById('rep-customer').value;
+  const billingType = document.getElementById('rep-billing-type').value;
+  if (from) params.set('from', from);
+  if (to) params.set('to', to);
+  if (customerId) params.set('customerId', customerId);
+  if (billingType) params.set('billingType', billingType);
+  return params;
+}
+
+async function runReport() {
+  const { rows } = await api(`/reports/billing?${reportQuery()}`);
+  state.report = rows;
+  const totals = rows.reduce(
+    (acc, r) => ({
+      calls: acc.calls + r.calls,
+      totalCents: acc.totalCents + r.totalCents,
+      creditCents: acc.creditCents + r.creditCents,
+      billableCents: acc.billableCents + r.billableCents,
+    }),
+    { calls: 0, totalCents: 0, creditCents: 0, billableCents: 0 },
+  );
+  document.getElementById('rep-summary').innerHTML = `
+    <div class="stat-grid">
+      <div class="stat"><div class="k">Calls</div><div class="v">${totals.calls.toLocaleString()}</div></div>
+      <div class="stat"><div class="k">Gross usage</div><div class="v">${fmt(totals.totalCents)}</div></div>
+      <div class="stat"><div class="k">Credits applied</div><div class="v">${fmt(totals.creditCents)}</div></div>
+      <div class="stat"><div class="k">Billable</div><div class="v">${fmt(totals.billableCents)}</div></div>
+    </div>`;
+  document.getElementById('rep-table').innerHTML = `
+    <thead><tr><th>Customer</th><th>Billing</th><th>Calls</th><th>Gross</th><th>Credit</th><th>Billable</th></tr></thead>
+    <tbody>${
+      rows
+        .map(
+          (r) => `<tr>
+        <td>${r.name} <span class="id">${r.customerId}</span></td>
+        <td><span class="pill ${r.billingType}">${r.billingType === 'stripe' ? 'Stripe' : 'PO'}</span></td>
+        <td class="money">${r.calls.toLocaleString()}</td>
+        <td class="money">${fmt(r.totalCents)}</td>
+        <td class="money">${fmt(r.creditCents)}</td>
+        <td class="money"><b>${fmt(r.billableCents)}</b></td>
+      </tr>`,
+        )
+        .join('') || '<tr><td colspan="6" style="color:var(--muted)">No usage in range.</td></tr>'
+    }</tbody>`;
+}
+
+async function downloadCsv() {
+  const params = reportQuery();
+  params.set('format', 'csv');
+  const res = await fetch(`/admin/api/reports/billing?${params}`, {
+    headers: { authorization: `Bearer ${token()}` },
+  });
+  if (!res.ok) return say('CSV download failed.', true);
+  const url = URL.createObjectURL(await res.blob());
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = 'billing-report.csv';
+  a.click();
+  URL.revokeObjectURL(url);
+  say('CSV downloaded.');
+}
+
+async function runTrend() {
+  const bucket = document.getElementById('trend-bucket').value;
+  const params = reportQuery();
+  params.delete('billingType');
+  params.set('bucket', bucket);
+  const { points } = await api(`/reports/usage-trend?${params}`);
+  state.trend = points;
+  document.getElementById('trend-chart').innerHTML = points.length
+    ? trendChart(points)
+    : '<p class="hint">No usage in range.</p>';
+}
+
+function trendChart(points) {
+  const W = 920;
+  const H = 220;
+  const padL = 8;
+  const padB = 34;
+  const padT = 10;
+  const max = Math.max(...points.map((p) => p.cents), 1);
+  const band = (W - padL) / points.length;
+  const barW = Math.max(4, Math.min(48, band * 0.62));
+  const bars = points
+    .map((p, i) => {
+      const h = ((H - padB - padT) * p.cents) / max;
+      const x = padL + i * band + (band - barW) / 2;
+      const y = H - padB - h;
+      const label =
+        points.length <= 31 || i % Math.ceil(points.length / 31) === 0
+          ? `<text x="${x + barW / 2}" y="${H - padB + 13}" text-anchor="middle">${p.bucket.slice(5)}</text>`
+          : '';
+      return `<rect class="bar" x="${x.toFixed(1)}" y="${y.toFixed(1)}" width="${barW.toFixed(1)}" height="${Math.max(h, p.cents > 0 ? 2 : 0).toFixed(1)}"><title>${p.bucket}: ${p.calls} calls, ${fmt(p.cents)}</title></rect>${label}`;
+    })
+    .join('');
+  return `<svg class="chart" viewBox="0 0 ${W} ${H}" role="img" aria-label="Usage trend">${bars}</svg>
+    <p class="hint">Hover a bar for exact calls and amount. Peak: ${fmt(max)}.</p>`;
+}
+
+/* ---------------- system ---------------- */
+
+function renderSystem() {
+  document.getElementById('system').innerHTML = `
+    <h2>System</h2>
+    <p class="lede">Integration health and current-period billing snapshot.</p>
+    <div class="card"><h3>Zapier integration</h3><div id="sys-zapier"><p class="hint">Loading…</p></div></div>
+    <div class="card"><h3>Current period (${currentPeriod()})</h3><div id="sys-period"><p class="hint">Loading…</p></div></div>`;
+  loadSystem().catch((err) => say(err.message, true));
+}
+
+async function loadSystem() {
+  const status = await api('/zapier/status');
+  state.system = status;
+  document.getElementById('sys-zapier').innerHTML = `
+    <dl class="kv">
+      <dt>App directory</dt><dd>${status.appDirPresent ? '✓ zapier-app/ found' : '✗ not found'}</dd>
+      <dt>Version</dt><dd>${status.version ?? '—'}</dd>
+      <dt>Triggers</dt><dd>${status.triggers.length ? status.triggers.join(', ') : '—'}</dd>
+      <dt>Creates</dt><dd>${status.creates.length ? status.creates.join(', ') : '—'}</dd>
+    </dl>`;
+
+  const params = new URLSearchParams({ from: `${currentPeriod()}-01` });
+  const { rows } = await api(`/reports/billing?${params}`);
+  const totals = rows.reduce(
+    (acc, r) => ({ calls: acc.calls + r.calls, billableCents: acc.billableCents + r.billableCents }),
+    { calls: 0, billableCents: 0 },
+  );
+  const unpaid = state.invoices.filter((i) => i.status === 'issued');
+  document.getElementById('sys-period').innerHTML = `
+    <div class="stat-grid">
+      <div class="stat"><div class="k">Calls this period</div><div class="v">${totals.calls.toLocaleString()}</div></div>
+      <div class="stat"><div class="k">Billable this period</div><div class="v">${fmt(totals.billableCents)}</div></div>
+      <div class="stat"><div class="k">Open invoices</div><div class="v">${unpaid.length}</div></div>
+      <div class="stat"><div class="k">Open amount</div><div class="v">${fmt(unpaid.reduce((s, i) => s + i.billableCents, 0))}</div></div>
+    </div>`;
+}
+
+/* ---------------- admin users ---------------- */
+
+function renderUsers() {
+  const rows = state.users
+    .slice()
+    .sort((a, b) => a.username.localeCompare(b.username))
+    .map(
+      (u) => `<tr>
+        <td class="id">${u.username}</td>
+        <td><span class="pill ${u.active ? 'paid' : 'draft'}">${u.active ? 'active' : 'inactive'}</span></td>
+        <td>${fmtDate(u.createdMs)}</td>
+        <td class="row-actions">
+          <button class="btn ${u.active ? 'ghost' : ''}" onclick="toggleUser('${u.username}', ${!u.active})">${u.active ? 'Deactivate' : 'Activate'}</button>
+        </td>
+      </tr>`,
+    )
+    .join('');
+  document.getElementById('users').innerHTML = `
+    <h2>Admin users</h2>
+    <p class="lede">Accounts that can sign in to this console. Passwords are stored as scrypt hashes — never in plain text. The last active admin cannot be deactivated.</p>
+    <div class="card"><table>
+      <thead><tr><th>Username</th><th>Status</th><th>Created</th><th></th></tr></thead>
+      <tbody>${rows}</tbody>
+    </table></div>
+    <div class="card">
+      <h3>Add admin user</h3>
+      <input id="new-user-name" placeholder="username" autocomplete="off">
+      <input id="new-user-password" type="password" placeholder="password (min 8 chars)" autocomplete="new-password">
+      <button class="btn" onclick="addUser()">Create</button>
+      <p class="hint">Usernames may contain letters, digits, dots, dashes, and underscores. Deactivated users are blocked from signing in immediately.</p>
+    </div>`;
+}
+
+async function addUser() {
+  const username = document.getElementById('new-user-name').value.trim();
+  const password = document.getElementById('new-user-password').value;
+  if (!username || !password) return say('Username and password required.', true);
+  await api('/users', { method: 'POST', body: JSON.stringify({ username, password }) });
+  say(`Created admin user ${username}.`);
+  await load();
+}
+
+async function toggleUser(username, activate) {
+  await api(`/users/${username}/${activate ? 'activate' : 'deactivate'}`, {
+    method: 'POST',
+    body: '{}',
+  });
+  say(`${activate ? 'Activated' : 'Deactivated'} ${username}.`);
+  await load();
+}
+
+/* ---------------- tabs + boot ---------------- */
+
+document.querySelectorAll('nav button').forEach((btn) =>
+  btn.addEventListener('click', () => {
+    document.querySelectorAll('nav button').forEach((b) => b.classList.remove('active'));
+    btn.classList.add('active');
+    document.querySelectorAll('main section').forEach((s) => (s.hidden = true));
+    document.getElementById(btn.dataset.tab).hidden = false;
+  }),
+);
+
+if (token()) {
+  showShell();
+  load().catch((err) => say(err.message, true));
+} else {
+  showLogin();
+}
--- a/packages/zappier/admin/index.html
+++ b/packages/zappier/admin/index.html
@ -0,0 +1,260 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Zappier Admin</title>
+    <style>
+      :root {
+        --bg: #f4f5fb;
+        --panel: #ffffff;
+        --ink: #171a26;
+        --muted: #6b7186;
+        --line: #e5e7f0;
+        --accent: #4f46e5;
+        --accent-ink: #ffffff;
+        --accent-soft: #eef0fe;
+        --danger: #dc2626;
+        --ok: #047857;
+        --radius: 12px;
+        --shadow: 0 1px 2px rgba(23, 26, 38, 0.05), 0 8px 24px rgba(23, 26, 38, 0.06);
+      }
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        font-family: -apple-system, "SF Pro Text", "Segoe UI", "PingFang SC", sans-serif;
+        background: var(--bg);
+        color: var(--ink);
+        font-size: 14px;
+      }
+
+      /* ---------- Login ---------- */
+      #login {
+        min-height: 100vh;
+        display: grid;
+        place-items: center;
+        background: linear-gradient(160deg, #312e81 0%, #4f46e5 55%, #7c74f0 100%);
+      }
+      #login .card {
+        width: 360px;
+        background: var(--panel);
+        border-radius: 16px;
+        box-shadow: 0 24px 64px rgba(17, 12, 60, 0.35);
+        padding: 2rem;
+      }
+      #login h1 { font-size: 1.35rem; margin: 0 0 0.25rem; }
+      #login p.sub { color: var(--muted); margin: 0 0 1.5rem; }
+      #login label { display: block; font-weight: 600; font-size: 0.8rem; margin: 0.9rem 0 0.3rem; }
+      #login input {
+        width: 100%;
+        padding: 0.6rem 0.75rem;
+        border: 1px solid var(--line);
+        border-radius: 8px;
+        font-size: 0.95rem;
+      }
+      #login input:focus { outline: 2px solid var(--accent); border-color: transparent; }
+      #login button {
+        width: 100%;
+        margin-top: 1.4rem;
+        padding: 0.65rem;
+        border: 0;
+        border-radius: 8px;
+        background: var(--accent);
+        color: var(--accent-ink);
+        font-weight: 700;
+        font-size: 0.95rem;
+        cursor: pointer;
+      }
+      #login button:hover { filter: brightness(1.08); }
+      #login-error { color: var(--danger); font-size: 0.85rem; min-height: 1.2em; margin: 0.6rem 0 0; }
+
+      /* ---------- Shell ---------- */
+      #shell { display: none; min-height: 100vh; }
+      #shell.on { display: grid; grid-template-columns: 232px 1fr; }
+      aside {
+        background: var(--panel);
+        border-right: 1px solid var(--line);
+        padding: 1.25rem 0.9rem;
+        display: flex;
+        flex-direction: column;
+        gap: 0.25rem;
+        position: sticky;
+        top: 0;
+        height: 100vh;
+      }
+      .brand { display: flex; align-items: center; gap: 0.6rem; padding: 0.25rem 0.6rem 1.1rem; }
+      .brand .dot {
+        width: 30px; height: 30px; border-radius: 9px;
+        background: linear-gradient(140deg, var(--accent), #8b85f2);
+        display: grid; place-items: center; color: #fff; font-weight: 800;
+      }
+      .brand b { font-size: 1.02rem; }
+      nav button {
+        display: flex; align-items: center; gap: 0.55rem;
+        width: 100%;
+        border: 0; background: none;
+        text-align: left;
+        padding: 0.55rem 0.7rem;
+        border-radius: 8px;
+        font-size: 0.92rem;
+        color: var(--muted);
+        cursor: pointer;
+      }
+      nav button:hover { background: var(--bg); color: var(--ink); }
+      nav button.active { background: var(--accent-soft); color: var(--accent); font-weight: 700; }
+      aside .spacer { flex: 1; }
+      #logout {
+        border: 1px solid var(--line); background: none; border-radius: 8px;
+        padding: 0.5rem; color: var(--muted); cursor: pointer; font-size: 0.85rem;
+      }
+      #logout:hover { color: var(--danger); border-color: var(--danger); }
+
+      main { padding: 1.75rem 2rem 3rem; max-width: 1080px; }
+      main h2 { margin: 0 0 0.25rem; font-size: 1.3rem; }
+      main .lede { color: var(--muted); margin: 0 0 1.25rem; }
+
+      .card {
+        background: var(--panel);
+        border: 1px solid var(--line);
+        border-radius: var(--radius);
+        box-shadow: var(--shadow);
+        padding: 1.1rem 1.25rem;
+        margin-bottom: 1.25rem;
+      }
+      .card h3 { margin: 0 0 0.9rem; font-size: 0.95rem; }
+
+      table { border-collapse: collapse; width: 100%; }
+      th {
+        text-align: left; font-size: 0.72rem; text-transform: uppercase;
+        letter-spacing: 0.04em; color: var(--muted);
+        border-bottom: 1px solid var(--line); padding: 0.45rem 0.6rem;
+      }
+      td { border-bottom: 1px solid var(--line); padding: 0.55rem 0.6rem; }
+      tr:last-child td { border-bottom: 0; }
+      tbody tr:hover { background: #fafaff; }
+      td.id { font-family: "SF Mono", Menlo, monospace; font-size: 0.82rem; font-weight: 600; }
+
+      input, select {
+        padding: 0.4rem 0.55rem;
+        border: 1px solid var(--line);
+        border-radius: 7px;
+        font-size: 0.88rem;
+        background: #fff;
+        color: var(--ink);
+      }
+      input:focus, select:focus { outline: 2px solid var(--accent); border-color: transparent; }
+      input[type="number"] { width: 90px; }
+      .field { display: inline-flex; align-items: center; gap: 0.35rem; margin-right: 0.7rem; }
+      .field span { color: var(--muted); font-size: 0.78rem; font-family: "SF Mono", Menlo, monospace; }
+
+      button.btn {
+        border: 0; border-radius: 7px; padding: 0.42rem 0.85rem;
+        font-size: 0.85rem; font-weight: 600; cursor: pointer;
+        background: var(--accent); color: var(--accent-ink);
+      }
+      button.btn:hover { filter: brightness(1.08); }
+      button.btn.ghost { background: none; border: 1px solid var(--line); color: var(--muted); }
+      button.btn.ghost:hover { color: var(--danger); border-color: var(--danger); }
+      .row-actions { white-space: nowrap; text-align: right; }
+      .row-actions button { margin-left: 0.35rem; }
+
+      .pill {
+        display: inline-block; padding: 0.1rem 0.55rem; border-radius: 999px;
+        font-size: 0.72rem; font-weight: 700;
+      }
+      .pill.free { background: #ecfdf5; color: var(--ok); }
+      .pill.fixed { background: var(--accent-soft); color: var(--accent); }
+      .pill.variable { background: #fff7ed; color: #c2410c; }
+      .pill.draft { background: #f1f5f9; color: #475569; }
+      .pill.issued { background: #fff7ed; color: #c2410c; }
+      .pill.paid { background: #ecfdf5; color: var(--ok); }
+      .pill.stripe { background: var(--accent-soft); color: var(--accent); }
+      .pill.purchase_order { background: #fdf4ff; color: #a21caf; }
+
+      /* ---------- Accounting tabs ---------- */
+      .filterbar {
+        display: flex; flex-wrap: wrap; align-items: end; gap: 0.8rem;
+        margin-bottom: 1rem;
+      }
+      .filterbar label { display: flex; flex-direction: column; gap: 0.25rem; }
+      .filterbar label span {
+        font-size: 0.72rem; text-transform: uppercase; letter-spacing: 0.04em;
+        color: var(--muted); font-weight: 600;
+      }
+      .money { font-variant-numeric: tabular-nums; text-align: right; }
+      .stat-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 0.9rem; margin-bottom: 1.25rem; }
+      .stat {
+        background: var(--panel); border: 1px solid var(--line);
+        border-radius: var(--radius); box-shadow: var(--shadow);
+        padding: 0.9rem 1.1rem;
+      }
+      .stat .k { font-size: 0.72rem; text-transform: uppercase; letter-spacing: 0.05em; color: var(--muted); }
+      .stat .v { font-size: 1.35rem; font-weight: 800; margin-top: 0.2rem; font-variant-numeric: tabular-nums; }
+      .chart { width: 100%; height: auto; display: block; }
+      .chart .bar { fill: var(--accent); }
+      .chart .bar:hover { fill: #3730a3; }
+      .chart text { fill: var(--muted); font-size: 10px; font-family: inherit; }
+      .skip-list { margin: 0.6rem 0 0; padding-left: 1.1rem; color: var(--muted); font-size: 0.85rem; }
+      .kv { display: grid; grid-template-columns: 160px 1fr; row-gap: 0.45rem; }
+      .kv dt { color: var(--muted); font-size: 0.82rem; }
+      .kv dd { margin: 0; font-weight: 600; }
+
+      #status {
+        position: fixed; right: 1.25rem; bottom: 1.25rem;
+        background: var(--ink); color: #fff;
+        padding: 0.7rem 1.1rem; border-radius: 10px;
+        box-shadow: var(--shadow);
+        font-size: 0.88rem;
+        opacity: 0; transform: translateY(8px);
+        transition: opacity 0.2s, transform 0.2s;
+        max-width: 420px;
+        pointer-events: none;
+      }
+      #status.show { opacity: 1; transform: none; }
+      #status.error { background: var(--danger); }
+      .hint { color: var(--muted); font-size: 0.82rem; margin-top: 0.8rem; }
+    </style>
+  </head>
+  <body>
+    <section id="login">
+      <form class="card" id="login-form">
+        <h1>Zappier Admin</h1>
+        <p class="sub">Sign in to manage pricing, customer types, and customers.</p>
+        <label for="login-username">Username</label>
+        <input id="login-username" autocomplete="username" required />
+        <label for="login-password">Password</label>
+        <input id="login-password" type="password" autocomplete="current-password" required />
+        <p id="login-error"></p>
+        <button type="submit">Sign in</button>
+      </form>
+    </section>
+
+    <div id="shell">
+      <aside>
+        <div class="brand"><span class="dot">Z</span><b>Zappier</b></div>
+        <nav>
+          <button data-tab="endpoints" class="active">▦&nbsp; Rate card</button>
+          <button data-tab="tiers">◈&nbsp; Customer types</button>
+          <button data-tab="customers">☺&nbsp; Customers</button>
+          <button data-tab="invoices">▤&nbsp; Invoices</button>
+          <button data-tab="reports">↗&nbsp; Reports</button>
+          <button data-tab="system">⚙&nbsp; System</button>
+          <button data-tab="users">♟&nbsp; Users</button>
+        </nav>
+        <div class="spacer"></div>
+        <button id="logout">Sign out</button>
+      </aside>
+      <main>
+        <section id="endpoints"></section>
+        <section id="tiers" hidden></section>
+        <section id="customers" hidden></section>
+        <section id="invoices" hidden></section>
+        <section id="reports" hidden></section>
+        <section id="system" hidden></section>
+        <section id="users" hidden></section>
+      </main>
+    </div>
+    <p id="status"></p>
+    <script src="app.js"></script>
+  </body>
+</html>
--- a/packages/zappier/docs/ACCOUNTING.md
+++ b/packages/zappier/docs/ACCOUNTING.md
@ -0,0 +1,126 @@
+# Company Accounting Walkthrough
+
+This guide covers the company-side accounting surface: invoicing, purchase-order
+billing, reports, trends, and CSV export. Everything here runs in the **admin
+console** at `/admin`.
+
+> Audience: operations and accounting staff. For pricing and customer setup see
+> `USER-MANAGEMENT.md`; for the end-user view see `CUSTOMER-PORTAL.md`.
+
+---
+
+## 1. Sign in
+
+Open `http://<host>:<port>/admin` and sign in. The development credentials are
+`demo` / `$$$Adm1n###` (override with `DEMO_ADMIN_USER` / `DEMO_ADMIN_PASSWORD`;
+the primary account is `ADMIN_USER` / `ADMIN_KEY`).
+
+![Admin login](screenshots/admin-login.png)
+
+---
+
+## 2. Billing identity per customer
+
+Before invoicing, each customer needs a **billing type** and an **email** — set
+on the **Customers** tab:
+
+- **Stripe** — metered usage is reported to Stripe by the daily billing job.
+- **Purchase order** — invoiced manually with a PO number; issued PO invoices
+  get a 30-day due date automatically.
+
+![Customers with billing types](screenshots/admin-customers.png)
+
+Customers can also carry a **prepaid balance** (funded from the customer
+portal). When an invoice is issued and the balance fully covers the billable
+amount, the balance is drawn down and the invoice goes straight to **paid**.
+Partial coverage is left untouched — there are no partial payments.
+
+---
+
+## 3. Generate invoices
+
+On the **Invoices** tab, pick a **period** (month), optionally narrow to one
+customer, optionally set a **PO number**, and click **Generate**.
+
+![Invoices tab](screenshots/admin-invoices.png)
+
+Generation rules:
+
+- One invoice per customer with usage in the period, grouped by endpoint.
+- The tier **monthly credit** is applied; only the remainder is billable.
+- Regenerating a period **replaces drafts** (e.g. after late-arriving usage)
+  and **skips issued/paid invoices** — the result panel lists who was skipped
+  and why.
+- Invoice ids are `INV-<period>-<sequence>`, e.g. `INV-2026-07-0002`.
+
+## 4. Issue, view, collect
+
+Each row shows status, billing type, totals, and due amount:
+
+- **Issue** (draft → issued) — finalizes the invoice; PO invoices get a due
+  date 30 days out. Balance-covered invoices skip straight to **paid**.
+- **View** — opens the print-ready invoice in a new tab. Use the browser's
+  **Print → Save as PDF** to produce a PDF for the customer.
+- **Mark paid** (issued → paid) — record collection for PO invoices.
+
+![Print-ready invoice](screenshots/admin-invoice-html.png)
+
+Filter the table by customer, period, or status with the filter bar.
+
+---
+
+## 5. Reports and trends
+
+The **Reports** tab answers "who owes what, and how is usage trending?"
+
+![Reports tab](screenshots/admin-reports.png)
+
+- **Billing report** — per-customer calls, gross usage, credits applied, and
+  billable amount for a date range. Filter by customer or billing type (all
+  Stripe customers, all PO customers, or one customer). Summary cards total
+  the selection.
+- **Download CSV** — the same rows as `billing-report.csv` with the active
+  filters, ready for the accounting package.
+- **Usage trend** — daily or weekly buckets as a bar chart; hover a bar for
+  exact calls and amount.
+
+The same data is available as JSON/CSV from the API:
+`GET /admin/api/reports/billing?from=…&to=…&customerId=…&billingType=…&format=csv`
+and `GET /admin/api/reports/usage-trend?bucket=day|week`.
+
+---
+
+## 6. System snapshot
+
+The **System** tab shows integration health (Zapier app directory, version,
+triggers, creates) and the current period at a glance: calls, billable amount,
+open invoice count, and open amount.
+
+![System tab](screenshots/admin-system.png)
+
+---
+
+## 7. Automated Stripe reporting
+
+A daily job (`src/jobs/report-usage.ts`, scheduled separately) reports the
+billable delta of every Stripe-billed customer to Stripe Billing meter events.
+It is idempotent: a ledger records the cumulative reported cents per customer
+per period, and only the delta since the last successful run is sent. PO
+customers are excluded by having no `stripeCustomerId`.
+
+Environment (`.env` at the project root):
+
+```
+STRIPE_SECRET_KEY=sk_live_or_test_...
+ZAPPIER_DB=/absolute/path/to/zappier.db   # optional
+```
+
+---
+
+## Data notes
+
+- Money is integer **cents** everywhere internally; the UI formats dollars.
+- All accounting data lives in the SQLite database (`zappier.db` by default):
+  `invoices`, `invoice_lines`, `billing_ledger`, `customers`.
+- The Stripe billing job and the admin console can run from any working
+  directory — all paths resolve from the installation root.
--- a/packages/zappier/docs/ACCOUNTING.pdf
+++ b/packages/zappier/docs/ACCOUNTING.pdf
--- a/packages/zappier/docs/CUSTOMER-PORTAL.md
+++ b/packages/zappier/docs/CUSTOMER-PORTAL.md
@ -0,0 +1,98 @@
+# Customer Portal Walkthrough
+
+The self-service portal for end-user customers at `/portal`: account setup,
+two-factor authentication, usage and balance, invoices, reloads, and API
+documentation.
+
+> Audience: your API customers. For the company side see `ACCOUNTING.md` and
+> `USER-MANAGEMENT.md`.
+
+---
+
+## 1. Create your account
+
+Open `http://<host>:<port>/portal` and choose **Create an account**.
+
+![Sign up](screenshots/portal-signup.png)
+
+- Name, email, and a password of at least 8 characters.
+- You start on the **Free** plan and get an **API key immediately**.
+- If the company already created an account for you (you received an API key
+  by email), sign up with the **same email address** — your existing account,
+  plan, and API key are kept and the password you choose is attached to it.
+
+Sign-in afterwards is email + password on the same screen.
+
+![Sign in](screenshots/portal-login.png)
+
+---
+
+## 2. Dashboard
+
+![Dashboard](screenshots/portal-dashboard.png)
+
+- **Usage this month** — gross usage since the 1st (UTC).
+- **Included credit** — how much of your plan's monthly credit was consumed.
+- **Billable** — what exceeds the credit (what you'd be invoiced today).
+- **Prepaid balance** — funds available for automatic invoice payment.
+- **Your API key** — copy it, or **regenerate** it. Regenerating invalidates
+  the old key immediately; use it as the `x-api-key` header.
+
+## 3. Usage & pricing
+
+The **API & pricing** tab shows the live rate card (free / fixed / variable
+per endpoint, with size-based pricing for storage) and every plan's multiplier
+and monthly credit — the same numbers the server bills from.
+
+![API & pricing](screenshots/portal-docs.png)
+
+The interactive API reference (Swagger UI) is linked at the top (`/docs`).
+
+## 4. Invoices
+
+![Invoices](screenshots/portal-invoices.png)
+
+Your invoice history with status (`draft`, `issued`, `paid`), totals, credit,
+amount due, and due date. **View / print** opens a print-ready invoice — use
+the browser's **Print → Save as PDF** for a copy.
+
+![Printable invoice](screenshots/portal-invoice-html.png)
+
+Only your own invoices are visible; other customers' ids return "not found".
+
+## 5. Billing: reloads & email invoicing
+
+![Billing](screenshots/portal-billing.png)
+
+- **Reload balance** — add $1–$10,000. Your prepaid balance is **drawn down
+  automatically** when an invoice is issued: if it fully covers the amount
+  due, the invoice is paid instantly.
+- **Email invoicing** — receive a copy of each new invoice by email.
+
+## 6. Security: two-factor authentication
+
+On the **Security** tab, click **Set up 2FA**:
+
+![2FA setup](screenshots/portal-2fa-setup.png)
+
+1. Scan the QR code with any authenticator app (or type the secret manually).
+2. Enter the 6-digit code it shows to enable 2FA.
+
+From then on, sign-in requires the password **and** the current code. You can
+disable 2FA with a valid code from the same tab. Sessions expire after 7 days.
+
+---
+
+## Portal API reference
+
+Session-based (`Authorization: Bearer <token>` from signup/login):
+
+- `POST /portal/api/signup` · `POST /portal/api/login` · `POST /portal/api/logout`
+- `GET /portal/api/me` · `POST /portal/api/api-key`
+- `GET /portal/api/usage` · `GET /portal/api/pricing`
+- `GET /portal/api/invoices` · `GET /portal/api/invoices/:id[?format=html]`
+- `POST /portal/api/2fa/setup|enable|disable`
+- `POST /portal/api/reload` · `PUT /portal/api/email-invoicing`
+
+Security notes: passwords are stored as scrypt hashes; TOTP secrets are only
+shown during setup; no hash or secret is ever returned by the API.
--- a/packages/zappier/docs/CUSTOMER-PORTAL.pdf
+++ b/packages/zappier/docs/CUSTOMER-PORTAL.pdf
--- a/packages/zappier/docs/DEVELOPER.md
+++ b/packages/zappier/docs/DEVELOPER.md
@ -0,0 +1,406 @@
+# Zappier — Developer Documentation
+
+**Version:** 0.2.0 · **Last updated:** 2026-07-28
+
+Metered API platform: per-endpoint pricing, per-tier multipliers, usage
+ledger, Stripe metered billing, purchase-order invoicing, a company admin
+console, a customer portal with TOTP 2FA, and a Zapier integration. This
+document is the full technical reference. For operations, see
+[USER-MANUAL.md](USER-MANUAL.md).
+
+---
+
+## Table of contents
+
+1. [Architecture](#1-architecture)
+2. [Module reference](#2-module-reference)
+3. [Pricing engine](#3-pricing-engine)
+4. [Request lifecycle](#4-request-lifecycle)
+5. [Persistence (SQLite)](#5-persistence-sqlite)
+6. [Billing pipeline](#6-billing-pipeline)
+7. [API reference](#7-api-reference)
+8. [Zapier app](#8-zapier-app)
+9. [Testing](#9-testing)
+10. [Configuration](#10-configuration)
+11. [Extending the system](#11-extending-the-system)
+
+---
+
+## 1. Architecture
+
+**Stack:** Node 20 · TypeScript (strict) · Express 4 · better-sqlite3 ·
+express-openapi-validator · swagger-ui-express · stripe SDK · Zapier Platform
+(core ^19) · jest + supertest (root) and mocha (zapier-app).
+
+```
+                         ┌────────────────────────────────────────────┐
+                         │                Express app                 │
+                         │                 (src/app.ts)               │
+                         │                                            │
+ Browser ── /admin ──────┼── static admin UI (admin/)                 │
+ Browser ── /admin/api ──┼── adminAuth → adminRouter (src/admin.ts)   │
+                         │      pricing · customers · invoices ·      │
+                         │      reports · zapier status               │
+ Browser ── /portal ─────┼── static portal SPA (portal/)              │
+ Browser ── /portal/api ─┼── portalRouter (src/portal.ts)             │
+                         │      signup/login+2FA · me · usage ·       │
+                         │      invoices · reload · prefs             │
+ Browser ── /docs ───────┼── swagger-ui (openapi.yaml)                │
+                         │                                            │
+ Client ──── /v1/* ──────┼── apiKeyAuth (src/auth.ts)                 │
+                         │     └─ OpenAPI request validation          │
+                         │     └─ meter() (src/meter.ts)              │
+                         │          ├─ quoteCall() (src/pricing.ts)   │
+                         │          └─ UsageRepo.record()             │
+                         └──────────────┬─────────────────────────────┘
+                                        │
+        ┌───────────────┬───────────────┼───────────────┬────────────┐
+        │               │               │               │            │
+ SqliteUsageRepo  SqliteCustomerRepo  SqlitePricingStore  SqliteInvoiceRepo
+ (usage_entries)  (customers)        (price_endpoints,   (invoices,
+        │               │             tiers)             invoice_lines)
+        │          SqliteSessionRepo (portal_sessions)        │
+        └───────────────┴───────────────┴───────────────┴────────────┘
+                                        │ zappier.db (SQLite)
+   Cron (daily 06:17 ET)                │
+   "Zappier billing · report usage"     │
+              │                         │
+              └─► src/jobs/report-usage.ts ── reportMonthlyUsage()
+                    ├─ computeBillableCents / computeDelta (src/billing/stripe.ts)
+                    ├─ SqliteBillingReportRepo (billing_reports, job_locks)
+                    └─ stripe.billing.meterEvents.create ──► Stripe
+```
+
+Design rules the codebase follows:
+
+- **Ports & adapters:** `UsageRepo`, `CustomerRepo`, `PricingStore`,
+  `MeterEventClient` are interfaces with in-memory adapters (tests) and SQLite
+  / Stripe adapters (production). Nothing outside `src/db/` and the job's
+  `main()` touches SQL or the Stripe SDK.
+- **Live pricing reads:** the `PricingContext` getters in `buildApp` read the
+  store on every quote, so admin edits apply without a restart.
+- **Money in integer cents everywhere.** No floats cross a boundary except
+  multipliers, which are applied once and rounded (`Math.round`).
+
+## 2. Module reference
+
+| File | Responsibility | Key exports |
+|---|---|---|
+| `src/index.ts` | Production entry: opens SQLite, wires repos, listens | — |
+| `src/app.ts` | `buildApp(deps)` — full Express wiring; `StoredItem`; `DEFAULT_CUSTOMERS` | `buildApp`, `AppDeps` |
+| `src/auth.ts` | Customer model + `x-api-key` middleware | `Customer`, `CustomerRepo`, `apiKeyAuth`, `InMemoryCustomerRepo` |
+| `src/pricing.ts` | Pricing domain: rules, tiers, quote algorithm, store port | `PriceRule`, `TierConfig`, `Quote`, `quoteCall`, `PricingStore`, `DEFAULT_RATE_CARD`, `DEFAULT_TIERS` |
+| `src/meter.ts` | Per-request metering middleware | `meter(endpointId, repo, pricing)` |
+| `src/usage.ts` | Usage ledger domain + summaries | `UsageEntry`, `UsageSummary`, `summarize`, `UsageRepo`, `InMemoryUsageRepo` |
+| `src/admin.ts` | Admin API (`/admin/api`) + admin-key guard | `adminAuth`, `adminRouter` |
+| `src/billing/credit.ts` | Monthly credit application | `applyMonthlyCredit`, `BilledSummary` |
+| `src/billing/stripe.ts` | Stripe-facing math + client port | `METER_EVENT_NAME`, `MeterEventClient`, `computeBillableCents`, `computeDelta`, `reportUsage` |
+| `src/billing/reload.ts` | Portal reloads via Stripe PaymentIntents | `stripePaymentClient`, `hasRealStripeKey` |
+| `src/accounts.ts` | Portal identity: scrypt passwords, RFC 6238 TOTP, sessions | `hashPassword`, `verifyPassword`, `totp`, `verifyTotp`, `generateTotpSecret`, `totpUri`, `SessionRepo`, `InMemorySessionRepo` |
+| `src/invoicing.ts` | Invoice domain + generation | `Invoice`, `InvoiceLine`, `buildInvoice`, `InvoiceRepo`, `InMemoryInvoiceRepo` |
+| `src/reports.ts` | Billing/usage aggregation + CSV | `billingRows`, `usageTrend`, `toCsv`, `BillingRow`, `TrendPoint` |
+| `src/portal.ts` | Customer portal API (`/portal/api`) | `portalRouter`, `PortalDeps`, `PaymentClient`, `PaymentResult` |
+| `src/paths.ts` | Installation-root resolution (cwd-independent) | `PROJECT_ROOT` |
+| `src/jobs/report-usage.ts` | Billing job: delta reporting to Stripe | `reportMonthlyUsage`, `firstOfMonthUtc`, `ReportUsageDeps` |
+| `src/db/usage-repo.ts` | SQLite adapter: `usage_entries` | `SqliteUsageRepo` |
+| `src/db/customer-repo.ts` | SQLite adapter: `customers` (seeds when empty; idempotent column migrations) | `SqliteCustomerRepo` |
+| `src/db/pricing-store.ts` | SQLite adapter: `price_endpoints`, `tiers` (seeds when empty) | `SqlitePricingStore` |
+| `src/db/billing-repo.ts` | SQLite adapter: `billing_reports`, `job_locks` | `SqliteBillingReportRepo`, `BillingReportRepo`, `JobLockRepo` |
+| `src/db/invoice-repo.ts` | SQLite adapter: `invoices`, `invoice_lines` | `SqliteInvoiceRepo` |
+| `src/db/session-repo.ts` | SQLite adapter: `portal_sessions` | `SqliteSessionRepo` |
+| `openapi.yaml` | Public API contract; drives validation and `/docs` | — |
+| `admin/` | Dependency-free admin SPA (`index.html`, `app.js`) | — |
+| `portal/` | Dependency-free customer portal SPA (`index.html`, `app.js`) | — |
+
+## 3. Pricing engine
+
+### Types (`src/pricing.ts`)
+
+```ts
+type PriceRule =
+  | { kind: 'free' }
+  | { kind: 'fixed'; fixedCents: number }
+  | { kind: 'variable'; baseCents: number; perKbCents: number; perMbCents: number };
+
+interface TierConfig {
+  id: string; name: string;
+  multiplier: number;           // e.g. 0.5 = 50% of list
+  monthlyCreditCents: number;   // free included usage per month
+  defaultRule?: PriceRule;      // fallback for endpoints with no rule
+}
+
+interface Quote {
+  endpointId: string;
+  listCents: number;            // before multiplier
+  totalCents: number;           // after multiplier — this is what is recorded
+  breakdown: { baseCents: number; metadataCents: number; attachmentCents: number };
+}
+```
+
+### `quoteCall(pricing, tierId, endpointId, usage, multiplierOverride?)`
+
+1. Resolve tier — throws `Unknown tier: <id>` (mapped to 403 by `meter`).
+2. Resolve rule: rate-card rule for `endpointId`, else the tier's
+   `defaultRule`, else throw `No price rule for <tier>/<endpoint>` (403).
+3. Compute breakdown:
+   - `free` → all zeros.
+   - `fixed` → `baseCents = fixedCents`.
+   - `variable` → `baseCents` + `perKbCents × ceil(metadataBytes/1024)` +
+     `perMbCents × ceil(attachmentBytes/1048576)`. Note the ceiling: 1 byte of
+     metadata bills a full KB unit; attachments bill per started MB.
+4. `listCents` = sum of breakdown; `multiplier = multiplierOverride ?? tier.multiplier`;
+   `totalCents = Math.round(listCents × multiplier)`.
+
+`totalCents` (never `listCents`) is what the usage ledger records and what the
+billing pipeline sums.
+
+## 4. Request lifecycle
+
+For `POST /v1/storage`:
+
+1. `express.json()` parses JSON bodies (multipart handled by the validator's
+   multer — 25 MB per-file cap).
+2. `apiKeyAuth` (`src/auth.ts`) — `x-api-key` → `Customer` on `req.customer`,
+   else 401.
+3. `express-openapi-validator` checks the request against `openapi.yaml`
+   (400 on violation). For `/v1/storage`, `parseMetadata` then JSON-parses the
+   `metadata` form field into `res.locals.parsedMetadata` (400 on bad JSON).
+4. `meter('storage', usage, pricing)` (`src/meter.ts`):
+   - measures `metadataBytes` (UTF-8 length of the JSON-stringified metadata)
+     and `attachmentBytes` (sum of multer file sizes),
+   - calls `quoteCall` — pricing errors become 403,
+   - records a `UsageEntry` with `cents = quote.totalCents`,
+   - stashes the quote in `res.locals.quote`.
+5. The route handler builds the `StoredItem` (in-memory list) and responds
+   `{ id, quote }`.
+
+`GET /v1/usage` is **not** metered; it summarizes the caller's month-to-date
+usage and applies the tier credit via `applyMonthlyCredit`.
+
+## 5. Persistence (SQLite)
+
+Single database file (`ZAPPIER_DB`, default `zappier.db`), WAL-agnostic
+better-sqlite3, all tables created with `CREATE TABLE IF NOT EXISTS` in the
+repo constructors. **Seeding rule:** `customers` and pricing tables seed from
+`DEFAULT_CUSTOMERS` / `DEFAULT_RATE_CARD` / `DEFAULT_TIERS` only when empty.
+
+| Table | Columns | Written by |
+|---|---|---|
+| `usage_entries` | `id`, `customer_id`, `endpoint_id`, `cents`, `metadata_bytes`, `attachment_bytes`, `timestamp_ms` | `meter()` on every priced call |
+| `customers` | `id` PK, `name`, `tier_id`, `api_key` UNIQUE, `stripe_customer_id`, `multiplier_override`, `billing_type`, `email`, `password_hash`, `totp_secret`, `totp_enabled`, `balance_cents`, `email_invoicing` | Admin API, portal API |
+| `price_endpoints` | `endpoint_id` PK, `rule_json` | Admin API |
+| `tiers` | `id` PK, `name`, `multiplier`, `monthly_credit_cents`, `default_rule_json` | Admin API |
+| `invoices` | `id` PK, `customer_id`, `period`, `status`, cents totals, `billing_type`, `po_number`, lifecycle timestamps | Admin API (generate/issue/paid + balance drawdown) |
+| `invoice_lines` | `invoice_id`, `endpoint_id`, `calls`, `cents` | Invoice generation |
+| `portal_sessions` | `token` PK, `customer_id`, `created_ms`, `expires_ms` | Portal auth |
+| `billing_reports` | `customer_id` + `period` PK, `reported_cents` (cumulative), `reported_at_ms` | Billing job, after each successful meter event |
+| `job_locks` | `name` PK, `acquired_at_ms` | Billing job run guard |
+
+New customer columns are added by **idempotent migrations** (`PRAGMA
+table_info` guard + `ALTER TABLE ADD COLUMN`) when the repo opens an older
+database — no manual migration step.
+
+In tests, every repo is constructed over `:memory:` databases.
+
+## 6. Billing pipeline
+
+### 6.1 Math (`src/billing/stripe.ts`)
+
+```ts
+computeBillableCents(entries, monthlyCreditCents)
+  = max(0, Σ entry.cents − monthlyCreditCents)
+
+computeDelta(billable, previouslyReported)
+  = max(0, billable − previouslyReported)
+```
+
+`reportUsage(client, stripeCustomerId, entries, monthlyCreditCents)` is the
+original whole-month reporter — **retained as public API**; the job uses the
+delta path instead.
+
+### 6.2 The job (`src/jobs/report-usage.ts`)
+
+`reportMonthlyUsage(deps)` per run:
+
+1. **Lock:** `locks.tryAcquireLock('report-usage', 1h TTL)` — a single atomic
+   `INSERT … ON CONFLICT … DO UPDATE … WHERE acquired_at_ms <= now − ttl`.
+   Failure aborts the run; release happens in `finally`. A crashed run's lock
+   is taken over after the TTL.
+2. **Window:** `since = firstOfMonthUtc(now)` (injectable via `deps.since` for
+   tests); `period = since.toISOString().slice(0, 7)` (`YYYY-MM`).
+3. Per customer with a `stripeCustomerId` (others skipped silently; unknown
+   `tierId` warns and skips):
+   - `entries = usage.listFor(customer.id, since)`
+   - `billable = computeBillableCents(entries, tier.monthlyCreditCents)`
+   - `prior = billingRepo.getReportedCents(customer.id, period)` (0 for a new
+     month — periods are isolated by the composite PK)
+   - `delta = computeDelta(billable, prior)`; `delta <= 0` → log skip, continue
+   - `createMeterEvent({ eventName: 'zappier.api_cents',
+     customerId: stripeCustomerId, value: String(delta),
+     identifier: `${stripeCustomerId}:${period}:${billable}` })`
+   - **only on success:** `upsertReportedCents(customer.id, period, billable)`
+     — cumulative, not the delta.
+
+**Idempotency guarantees (reviewed design):**
+
+- *Re-run safety:* second run with same usage → delta 0 → no Stripe call.
+- *Mid-month growth:* only the increase is sent; the identifier embeds the new
+  cumulative billable, so legitimate growth is never deduped away.
+- *Crash between Stripe success and ledger write:* retry sends a byte-identical
+  event; Stripe drops it via the `identifier` (uniqueness enforced within a
+  rolling 24 h window).
+- *Partial failure:* customer A's ledger write commits before customer B is
+  attempted; B's failure leaves A correctly recorded.
+
+CLI: `npx ts-node src/jobs/report-usage.ts` (guarded by
+`require.main === module`; loads `.env` via dotenv inside `main()`).
+Scheduled by the Kimi cron job "Zappier billing · report usage to Stripe"
+(`17 6 * * *`, America/New_York), which runs this command daily and reports
+the outcome.
+
+## 7. API reference
+
+### Public API (`/v1`, auth: `x-api-key`)
+
+Defined in `openapi.yaml`; interactive docs at `/docs`.
+
+| Operation | Method & path | Price | Notes |
+|---|---|---|---|
+| `status` | GET `/v1/status` | free | Health + quote echo |
+| `transform` | POST `/v1/transform` | fixed | `{text}` → `{output: TEXT, quote}` |
+| `storage` | POST `/v1/storage` | variable | multipart: `metadata` (JSON string), `attachments[]` (≤25 MB/file) → `{id, quote}` |
+| `storage-list` | GET `/v1/storage` | free | Caller's stored items |
+| `usage` | GET `/v1/usage` | unmetered | Month-to-date summary with credit applied |
+
+Error envelope: `{ "error": string }` with 400 (validation/metadata),
+401 (bad key), 403 (unknown tier / no price rule), 413 (file over 25 MB).
+
+### Admin API (`/admin/api`, auth: `x-admin-key` or login session)
+
+| Route | Purpose |
+|---|---|
+| POST `/login` | `{username, password}` → session token (accounts: `ADMIN_USER`/`ADMIN_KEY`, `DEMO_ADMIN_USER`/`DEMO_ADMIN_PASSWORD`) |
+| GET `/pricing` | `{ rateCard, tiers }` |
+| PUT `/endpoints/:id` | Upsert a `PriceRule` (validated: 400 on bad shape) |
+| DELETE `/endpoints/:id` | Remove a rule (endpoint becomes 403 for tiers without a default rule) |
+| PUT `/tiers/:id` | Upsert a `TierConfig` |
+| DELETE `/tiers/:id` | Remove a tier |
+| GET `/customers` | List customers **without** API keys |
+| POST `/customers` | Create `{name, tierId}` → full customer incl. generated `apiKey` (201, shown once) |
+| PUT `/customers/:id` | Patch `name` / `tierId` / `multiplierOverride` / `stripeCustomerId` / `billingType` / `email` |
+| POST `/invoices/generate` | `{period, customerId?, poNumber?}` — drafts per customer with usage; regenerating replaces drafts, skips issued/paid → `{generated, skipped}` |
+| GET `/invoices` | Filters: `customerId`, `period`, `status` |
+| GET `/invoices/:id` | JSON, or print-ready HTML with `?format=html` |
+| POST `/invoices/:id/issue` | draft → issued (PO gets 30-day due date). **Prepaid drawdown:** if the customer's `balanceCents` fully covers `billableCents`, the balance is deducted and the invoice is saved as paid instead |
+| POST `/invoices/:id/paid` | issued → paid |
+| GET `/reports/billing` | `from`/`to`/`customerId`/`billingType` filters; JSON rows or `format=csv` |
+| GET `/reports/usage-trend` | `bucket=day\|week`, same range filters |
+| GET `/zapier/status` | Zapier app dir presence, version, triggers, creates |
+
+### Portal API (`/portal/api`, auth: Bearer session)
+
+| Route | Purpose |
+|---|---|
+| POST `/signup` | `{name, email, password≥8}` → 201 `{token, customer}`. New customer on `free` with instant API key; an email match on a passwordless (admin-created) customer **claims** that account; 409 when the email already has a password |
+| POST `/login` | `{email, password, totpCode?}` → `{token, customer}`; 401 `totp_required` when 2FA is on and the code is missing/wrong |
+| POST `/logout` | Deletes the session |
+| GET `/me` | Public profile — never includes `passwordHash`/`totpSecret` |
+| POST `/api-key` | Regenerates the API key (old key dies immediately) |
+| GET `/usage` | Month-to-date summary with tier credit applied |
+| GET `/pricing` | Live rate card + tiers for the pricing page |
+| GET `/invoices` · GET `/invoices/:id` | Own invoices only (others 404); `?format=html` print view |
+| POST `/2fa/setup` | Generates + stores a TOTP secret (not yet enabled) → `{secret, uri, qr}` (QR as PNG data URL via `qrcode`) |
+| POST `/2fa/enable` · POST `/2fa/disable` | `{code}` verified against the stored secret |
+| POST `/reload` | `{amountCents}` integer $1–$10,000 via the injected `PaymentClient` — dev client credits instantly; Stripe client returns a `clientSecret` and credits on confirmation |
+| PUT `/email-invoicing` | `{enabled}` preference |
+
+Sessions live in `portal_sessions` (7-day TTL) and survive restarts.
+`src/accounts.ts` implements scrypt hashing (`scrypt:N:r:p:salt:hash`,
+timing-safe compare) and RFC 6238 TOTP (HMAC-SHA1, 30 s step, 6 digits,
+±1 step window) with no external crypto dependency.
+
+## 8. Zapier app
+
+`zapier-app/` — Zapier Platform (core ^19), CommonJS, mocha tests.
+
+| File | Purpose |
+|---|---|
+| `index.js` | App definition; wires auth, trigger, action |
+| `authentication.js` | API-key auth; test call against `/v1/status` |
+| `triggers/new_item.js` | Polling trigger: `GET /v1/storage`, newest first, dedupe by `id` |
+| `creates/store_data.js` | Action: multipart `POST /v1/storage` (form-data), fields: metadata JSON + optional files |
+| `test/` | mocha suite (4 tests): auth, trigger, action |
+
+Publish flow: `zapier login` → `zapier push` → invite users / submit for
+review. The app's base URL must point at a publicly reachable deployment of
+the API server.
+
+## 9. Testing
+
+```bash
+npm test                # jest, repo root — 165 tests / 22 suites
+npx tsc --noEmit        # type gate
+cd zapier-app && npm test   # mocha — 4 tests
+```
+
+Conventions:
+
+- **TDD** throughout; every module has in-memory adapters so tests never touch
+  disk or network.
+- HTTP tests use **supertest** against `buildApp()` with in-memory repos.
+- SQLite tests use `:memory:` databases.
+- Stripe is faked by implementing `MeterEventClient`; the idempotency suite
+  (`tests/report-usage-idempotency.test.ts`) simulates growth, re-runs, month
+  rollover, Stripe throws, lock contention, and partial failure.
+- The job is tested via the injectable `reportMonthlyUsage(deps)` — never by
+  executing `main()`.
+
+## 10. Configuration
+
+| Env var | Default | Used by |
+|---|---|---|
+| `PORT` | `3000` | `src/index.ts` |
+| `ZAPPIER_DB` | `<root>/zappier.db` | `src/index.ts`, billing job |
+| `ADMIN_KEY` | `admin-dev-key` | `adminAuth()` |
+| `ADMIN_USER` | `admin` | Admin login |
+| `DEMO_ADMIN_USER` / `DEMO_ADMIN_PASSWORD` | `demo` / `$$$Adm1n###` | Demo admin login |
+| `STRIPE_SECRET_KEY` | — | Billing job; portal reloads when it starts with `sk_` (otherwise a dev payment client credits instantly) |
+
+Both `src/index.ts` and the billing job load `.env` from the installation
+root (`src/paths.ts` `PROJECT_ROOT`) — never from the process cwd — so the
+compiled server and the job run from any working directory.
+`.env` is gitignored (`chmod 600`); `.env.example` documents the shape.
+Git identity is configured repo-local; `.gitignore` covers `node_modules/`,
+`dist/`, `.env`, `zappier.db*`.
+
+## 11. Extending the system
+
+**Add an API endpoint:**
+1. Add the path + `operationId` to `openapi.yaml` (validation & docs follow
+   automatically).
+2. Add the route in `src/app.ts`, wrapping the handler with
+   `meter('<operationId>', usage, pricing)`.
+3. Add a rate-card rule (admin UI or `PUT /admin/api/endpoints/<operationId>`)
+   — otherwise tiers without a `defaultRule` get 403.
+4. Write the failing test first; keep `npm test` + `tsc` green.
+
+**Add a customer type:** admin UI or `PUT /admin/api/tiers/:id`
+(`{name, multiplier, monthlyCreditCents, defaultRule?}`).
+
+**Swap the storage backend:** implement `UsageRepo` / `CustomerRepo` /
+`PricingStore` against your database and pass them to `buildApp({...})` — no
+other code changes. Same for `BillingReportRepo`/`JobLockRepo` in the job.
+
+**Change the billing cadence:** the job is safe at any frequency (delta +
+ledger + lock). The Kimi cron job controls scheduling; update its cron
+expression to change cadence.
+
+**Known intentional limitations:** stored items are in-memory (restart clears
+them; usage ledger is unaffected); `reportUsage` is retained but superseded by
+the delta path; Stripe identifier dedup covers a rolling 24 h window;
+`releaseLock` is not owner-scoped (harmless at this job's runtime); admin
+session tokens are in-memory (portal sessions are persisted); Stripe reloads
+credit the balance only after payment confirmation (no webhook endpoint yet —
+dev client credits instantly); email invoicing stores the preference but
+sending requires SMTP wiring (deferred); PO invoices with partial prepaid
+coverage are not partially paid by design.
--- a/packages/zappier/docs/DEVELOPER.pdf
+++ b/packages/zappier/docs/DEVELOPER.pdf
--- a/packages/zappier/docs/USER-MANAGEMENT.md
+++ b/packages/zappier/docs/USER-MANAGEMENT.md
@ -0,0 +1,111 @@
+# User Management Walkthrough
+
+How the company manages pricing, customer types, and customer accounts in the
+**admin console** at `/admin`.
+
+> Audience: operations staff. For invoicing/reports see `ACCOUNTING.md`; for
+> the end-user view see `CUSTOMER-PORTAL.md`.
+
+---
+
+## 1. Admin accounts
+
+Admin sign-ins live in the `admin_users` table — passwords are stored as
+**scrypt hashes**, never in plain text. On an empty database the table is
+seeded from the environment:
+
+| Account | Username | Password (dev default) | Env override |
+|---|---|---|---|
+| Primary admin | `admin` | `admin-dev-key` | `ADMIN_USER` / `ADMIN_KEY` |
+| Demo / stakeholder | `demo` | `$$$Adm1n###` | `DEMO_ADMIN_USER` / `DEMO_ADMIN_PASSWORD` |
+
+The seed runs **only when the table is empty** — after that, accounts are
+managed in the console and survive restarts (SQLite) and env changes.
+
+Sign-in issues a session token; API access is also possible with the
+`x-admin-key: $ADMIN_KEY` header (used by automation).
+
+## 2. Users tab (admin account management)
+
+The **Users** tab lists every admin account and manages their lifecycle:
+
+![Admin users](screenshots/admin-users.png)
+
+- **Create** — username (letters, digits, `.` `_` `-`) plus a password of at
+  least 8 characters. The new account can sign in immediately.
+- **Deactivate / Activate** — a deactivated account is blocked from signing in
+  right away (401), and reactivation restores access. Deactivation persists in
+  the database.
+- **Safety guard** — the console refuses to deactivate the **last active
+  admin**, so you can never lock everyone out.
+
+Existing sessions stay valid until sign-out or server restart; deactivation
+blocks *new* logins.
+
+## 3. Rate card (per-endpoint pricing)
+
+The **Rate card** tab sets list prices per API operation. Changes apply to the
+**next API call** — no restart.
+
+![Rate card](screenshots/admin-rate-card.png)
+
+Three price kinds:
+
+- **free** — never charged (e.g. `status`, `storage-list`).
+- **fixed** — a flat `fixedCents` per call (e.g. `transform` at 4¢).
+- **variable** — `baseCents` per call plus size-based charges:
+  `perKbCents` per KB of metadata and `perMbCents` per MB of file attachments
+  (e.g. `storage`: 10¢ + 1¢/KB + 50¢/MB). This is how storing data with
+  metadata or attachments is priced by size.
+
+Add an endpoint with its `operationId` from `openapi.yaml`. Deleting an
+endpoint makes calls to it fail with 403 unless the customer's type has a
+default rule.
+
+## 4. Customer types (tiers)
+
+The **Customer types** tab defines plans:
+
+![Customer types](screenshots/admin-tiers.png)
+
+- **Multiplier** — scales every list price (0.5 = 50% of list, 0.25 = 75% off).
+- **Monthly credit (cents)** — free included usage per month, consumed before
+  anything is billable.
+
+Defaults: `free` (1×, $1 credit), `pro` (0.5×, $10 credit, 8¢ default rule),
+`business` (0.25×, $100 credit, 8¢ default rule).
+
+## 5. Customers
+
+The **Customers** tab manages individual accounts:
+
+![Customers](screenshots/admin-customers.png)
+
+- **Type** — assign any tier.
+- **Multiplier override** — a per-customer deal that replaces the tier
+  multiplier (e.g. a strategic account at 0.2×).
+- **Email** — used for portal login/claiming and email invoicing.
+- **Billing** — `Stripe` (metered via the billing job) or `Purchase order`
+  (manual invoicing with PO numbers and 30-day terms).
+- **Create** — generates a customer id and API key. **The API key is shown
+  once** in the notification — copy it immediately.
+
+Customers created here can **claim** their portal account: the first signup at
+`/portal` with a matching email sets their password on the existing account
+instead of creating a new one.
+
+## 6. Admin API reference
+
+Everything the UI does is available over HTTP (`x-admin-key` or session
+Bearer):
+
+- `POST /admin/api/login`
+- `GET /admin/api/users` · `POST /admin/api/users`
+  · `POST /admin/api/users/:username/activate|deactivate`
+- `GET /admin/api/pricing` · `PUT/DELETE /admin/api/endpoints/:id`
+- `PUT/DELETE /admin/api/tiers/:id`
+- `GET/POST /admin/api/customers` · `PUT /admin/api/customers/:id`
+- `POST /admin/api/invoices/generate` · `GET /admin/api/invoices`
+  · `POST /admin/api/invoices/:id/issue|paid`
+- `GET /admin/api/reports/billing` · `GET /admin/api/reports/usage-trend`
+- `GET /admin/api/zapier/status`
--- a/packages/zappier/docs/USER-MANAGEMENT.pdf
+++ b/packages/zappier/docs/USER-MANAGEMENT.pdf
--- a/packages/zappier/docs/USER-MANUAL.md
+++ b/packages/zappier/docs/USER-MANUAL.md
@ -0,0 +1,348 @@
+# Zappier — Operations & Usage Manual
+
+**Version:** 0.2.0 · **Last updated:** 2026-07-28
+
+Zappier is a metered API platform: every API call your customers make is priced
+per endpoint, adjusted by their customer type, tracked in a usage ledger, and
+billed through Stripe once a day — or invoiced manually by purchase order.
+Customers self-serve through the portal at `/portal`. This manual covers
+running and operating the system. For internals, see
+[DEVELOPER.md](DEVELOPER.md); for accounting procedures see
+[ACCOUNTING.md](ACCOUNTING.md); for the end-user view see
+[CUSTOMER-PORTAL.md](CUSTOMER-PORTAL.md).
+
+---
+
+## Table of contents
+
+1. [Quick start](#1-quick-start)
+2. [The three surfaces](#2-the-three-surfaces)
+3. [How pricing works](#3-how-pricing-works)
+4. [Operating the Pricing Admin UI](#4-operating-the-pricing-admin-ui)
+5. [Using the public API](#5-using-the-public-api)
+6. [Billing operations (Stripe)](#6-billing-operations-stripe)
+7. [The Zapier integration](#7-the-zapier-integration)
+8. [Day-to-day runbook](#8-day-to-day-runbook)
+9. [Troubleshooting](#9-troubleshooting)
+
+---
+
+## 1. Quick start
+
+```bash
+cd /Users/marchon/zappier
+npm install
+npm run dev          # starts the API on http://localhost:3000
+```
+
+Environment variables (all optional except `STRIPE_SECRET_KEY` for billing):
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `PORT` | `3000` | HTTP port for the API server |
+| `ZAPPIER_DB` | `<install root>/zappier.db` | SQLite database file location |
+| `ADMIN_KEY` | `admin-dev-key` | Key for the admin console and admin API |
+| `ADMIN_USER` | `admin` | Admin console primary username |
+| `DEMO_ADMIN_USER` / `DEMO_ADMIN_PASSWORD` | `demo` / `$$$Adm1n###` | Demo sign-in — override in production |
+| `STRIPE_SECRET_KEY` | — (required for billing) | Billing job + portal reloads, loaded from `.env` |
+
+All runtime paths (database default, `.env`, OpenAPI spec, static assets)
+resolve from the installation root — the compiled server (`node
+dist/index.js`) runs from any working directory, under systemd, Docker, or cron.
+
+The `.env` file at the repo root holds `STRIPE_SECRET_KEY`. It is gitignored
+and owner-only (`chmod 600`). A template is in `.env.example`.
+
+On first start the database is created and seeded with:
+
+- **Rate card:** `status` (free), `storage-list` (free), `transform` (fixed 4¢),
+  `storage` (variable: 10¢ base + 1¢/KB metadata + 50¢/MB attachments)
+- **Customer types:** Free (×1.0, 100¢/month credit), Pro (×0.5, 1000¢ credit),
+  Business (×0.25, 10000¢ credit)
+- **Demo customers:** `key-ada` (Free), `key-grace` (Pro), `key-linus` (Business)
+
+> Seeding only happens into an **empty** database. Existing data is never
+> overwritten on restart.
+
+---
+
+## 2. The three surfaces
+
+| Surface | URL / location | Who it's for |
+|---|---|---|
+| **Public API** | `http://localhost:3000/v1/*` | Your API customers |
+| **Interactive API docs** | `http://localhost:3000/docs` | Developers integrating with you |
+| **Admin console** | `http://localhost:3000/admin` | You (operations & accounting) |
+| **Customer portal** | `http://localhost:3000/portal` | End-user customers (self-service) |
+| **Zapier app** | `zapier-app/` directory | No-code users via Zapier |
+
+![Interactive API docs](screenshots/api-docs.png)
+
+---
+
+## 3. How pricing works
+
+Every priced call returns its **quote** in the response, so customers always
+know what a call cost:
+
+```json
+{
+  "quote": {
+    "endpointId": "storage",
+    "listCents": 62,
+    "totalCents": 31,
+    "breakdown": { "baseCents": 10, "metadataCents": 2, "attachmentCents": 50 }
+  }
+}
+```
+
+The price of a call is computed in three steps:
+
+1. **Endpoint rule** (from the rate card):
+   - `free` — always 0¢
+   - `fixed` — a flat `fixedCents` per call
+   - `variable` — `baseCents` + `perKbCents` × ceil(metadata bytes / 1024)
+     + `perMbCents` × ceil(attachment bytes / 1 MB)
+2. **Customer-type multiplier** — `totalCents = round(listCents × multiplier)`.
+   A per-customer **multiplier override** (set in the Customers tab) wins over
+   the type multiplier — use it for negotiated enterprise deals.
+3. **Monthly credit** — at billing time, each customer's type credit
+   (e.g. Pro = 1000¢) is subtracted from their month-to-date total. Only the
+   excess is billed.
+
+**Worked example.** A Pro customer (×0.5) uploads a 1 MB file with 2 KB of
+metadata to `storage`:
+
+- list = 10¢ base + 2¢ metadata + 50¢ attachment = **62¢**
+- Pro multiplier: 62 × 0.5 = **31¢** charged to their usage ledger
+- If their month-to-date is 1500¢ and the Pro credit is 1000¢, the daily
+  billing job reports **500¢** to Stripe.
+
+---
+
+## 4. Operating the Pricing Admin UI
+
+Open `http://localhost:3000/admin` and sign in. Two accounts are available:
+
+| Username | Password | Purpose |
+|---|---|---|
+| `admin` | the `ADMIN_KEY` env value (default `admin-dev-key`) | Primary operator |
+| `demo` | `$$$Adm1n###` (env `DEMO_ADMIN_PASSWORD`) | Demo / stakeholder access |
+
+Sessions are token-based and remembered in browser local storage until you
+click **Sign out** or the server restarts (tokens are in-memory — just sign in
+again). The legacy `x-admin-key` header still works for scripts and curl.
+
+### 4.1 Rate card tab
+
+![Rate card](screenshots/admin-rate-card.png)
+
+One row per API endpoint (matched by OpenAPI `operationId`).
+
+- **Change a price:** edit the kind (`free` / `fixed` / `variable`) and the
+  cent fields, then click **Save**. Takes effect on the next API call — no
+  restart needed.
+- **Add an endpoint:** enter the `operationId` (must match `openapi.yaml`),
+  pick a kind, click **Add**.
+- **Delete** removes the rule. If an endpoint has no rule and the customer's
+  type has no default rule, calls to it are rejected with 403 — deletion is
+  how you turn an endpoint **off**.
+
+### 4.2 Customer types tab
+
+![Customer types](screenshots/admin-tiers.png)
+
+Types are your pricing tiers.
+
+- **Multiplier** scales every price for that type (0.5 = 50% of list).
+- **Monthly credit (cents)** is the free included usage per month.
+- **Add customer type:** id, name, multiplier. New types start with 0 credit;
+  edit after adding.
+
+### 4.3 Customers tab
+
+![Customers](screenshots/admin-customers.png)
+
+- **Create** a customer: name + type. **The API key is shown once** in the
+  status line at the bottom — copy it immediately and send it to the customer.
+- **Change type** with the dropdown, then **Save**.
+- **Email** — used for portal sign-in/claiming and email invoicing.
+- **Billing** — `Stripe` (metered by the daily job) or `Purchase order`
+  (manual invoicing with PO numbers; see [ACCOUNTING.md](ACCOUNTING.md)).
+- **Multiplier override**: a number here replaces the type multiplier for this
+  customer only. Leave blank to inherit from the type.
+- Stripe customer IDs are attached via the admin API
+  (`PUT /admin/api/customers/:id` with `{"stripeCustomerId": "cus_..."}`) —
+  see section 6.
+
+### 4.4 Invoices, Reports, System tabs
+
+The **Invoices** tab generates monthly invoices from metered usage (per period,
+optionally per customer, with optional PO number), walks them
+draft → issued → paid, and opens print-ready invoice pages. The **Reports** tab
+produces date-ranged billing reports (all customers, one customer, or one
+billing type) with CSV download, plus daily/weekly usage-trend charts. The
+**System** tab shows Zapier integration health and the current-period billing
+snapshot. Full procedures: [ACCOUNTING.md](ACCOUNTING.md).
+
+![Invoices](screenshots/admin-invoices.png)
+
+---
+
+## 4A. Customer portal
+
+Your customers self-serve at `http://localhost:3000/portal`: signup (or
+claiming an account you created, by email), sign-in with optional TOTP
+two-factor authentication, month-to-date usage, invoice history with print
+view, prepaid balance reloads (drawn down automatically at invoice issue),
+email-invoicing preferences, API-key regeneration, and live pricing. The full
+end-user guide is [CUSTOMER-PORTAL.md](CUSTOMER-PORTAL.md).
+
+---
+
+## 5. Using the public API
+
+All calls need the customer's API key in the `x-api-key` header. Interactive
+docs with a "Try it out" console are at `/docs`.
+
+```bash
+# Free status check
+curl -H 'x-api-key: key-ada' http://localhost:3000/v1/status
+
+# Fixed-price call (4¢ list)
+curl -X POST -H 'x-api-key: key-grace' -H 'content-type: application/json' \
+  -d '{"text":"hello"}' http://localhost:3000/v1/transform
+
+# Variable-price call: metadata + attachments
+curl -X POST -H 'x-api-key: key-grace' \
+  -F 'metadata={"title":"Q3 report"}' \
+  -F 'attachments=@report.pdf' \
+  http://localhost:3000/v1/storage
+
+# List your stored items (free)
+curl -H 'x-api-key: key-grace' http://localhost:3000/v1/storage
+
+# Your month-to-date usage, with credit applied
+curl -H 'x-api-key: key-grace' http://localhost:3000/v1/usage
+```
+
+Limits & validation: requests are validated against `openapi.yaml` (bad
+requests get 400); attachments are capped at **25 MB per file**; `metadata`
+must be valid JSON (400 otherwise).
+
+---
+
+## 6. Billing operations (Stripe)
+
+### 6.1 How it works
+
+A scheduled job runs the billing reporter **daily at 06:17 America/New_York**
+(Kimi cron job "Zappier billing · report usage to Stripe"). For each customer
+with a Stripe ID it:
+
+1. Sums their usage since the 1st of the month, subtracts their type's monthly
+   credit → **billable cents**.
+2. Reports only the **delta** above what was already reported this month to
+   Stripe as a meter event (`zappier.api_cents`, value = cents).
+3. Records the new cumulative total in the `billing_reports` ledger.
+
+Re-running is always safe: the ledger makes repeats no-ops, a per-run lock
+prevents overlapping executions, and a deterministic Stripe `identifier`
+(`customer:period:billable`) dedupes crash retries.
+
+### 6.2 One-time Stripe setup (test mode)
+
+1. Dashboard (test mode ON) → **Billing → Meters → Create meter**:
+   event name `zappier.api_cents`, aggregation **Sum** of `value`,
+   customer mapping `stripe_customer_id`.
+2. **Product catalog → Add product** "Zappier API usage" → price: recurring,
+   monthly, metered against that meter, **$0.01 per unit** (1 unit = 1 cent).
+3. For each billable customer: create the Stripe Customer, attach a payment
+   method, and add a **subscription** with the metered price. Meter events for
+   customers without a metered subscription are recorded but never invoiced.
+4. Put the `sk_test_...` key into `.env` (replace the placeholder).
+5. Attach Stripe IDs to Zappier customers:
+
+   ```bash
+   curl -X PUT -H 'x-admin-key: admin-dev-key' -H 'content-type: application/json' \
+     -d '{"stripeCustomerId":"cus_..."}' \
+     http://localhost:3000/admin/api/customers/cust_2
+   ```
+
+### 6.3 Verifying a run
+
+```bash
+npx ts-node src/jobs/report-usage.ts
+```
+
+Expected output per customer:
+
+- `skip <id> <period> (nothing to report)` — no billable usage yet
+- `skip <id> <period> (already reported Nc)` — no new usage since last run
+- `<id>: reported N billable cents to Stripe` — delta sent
+- `report-usage: another run holds the lock, abort run` — safe concurrent abort
+
+Then check the meter's **Events** tab in the Stripe dashboard and the test
+customer's **upcoming invoice**.
+
+### 6.4 Going live
+
+Repeat 6.2 steps 1–3 in live mode, replace `.env` with the `sk_live_...` key
+from the **same Stripe account**, and keep the same cron. The live product
+`prod_Uxv9SAeIOZzyx1` (currently deactivated) can be reactivated or recreated.
+
+---
+
+## 7. The Zapier integration
+
+The `zapier-app/` directory contains the Zapier Platform app:
+
+- **Authentication:** API key — the user pastes their API base URL
+  (e.g. `http://localhost:3000`) and their `key-...` customer key; the
+  connection is tested against `/v1/status`.
+- **Trigger "New Item":** polls `GET /v1/storage` for newly stored items.
+- **Action "Store Data":** calls `POST /v1/storage` with metadata and optional
+  file attachments — billed per the rate card.
+
+To publish: create a Zapier developer account, `cd zapier-app && npm install
+&& zapier login && zapier push`, then share the app or submit it to the Zapier
+marketplace.
+
+---
+
+## 8. Day-to-day runbook
+
+| Task | How |
+|---|---|
+| Change a price | Admin console → Rate card → Save |
+| Add a customer | Admin console → Customers → Create → copy the one-time API key |
+| Set a customer's billing type/email | Customers tab → Billing dropdown / Email field → Save |
+| Invoice a period | Invoices tab → Generate → Issue → Mark paid (ACCOUNTING.md) |
+| Export accounting data | Reports tab → filters → Download CSV |
+| Give a customer a deal | Customers tab → multiplier override, or a new customer type |
+| Turn an endpoint off | Rate card → Delete (calls get 403) |
+| Check a customer's usage | Their portal dashboard, `GET /v1/usage` with their key, or query `zappier.db` |
+| Check billing ran | Kimi notification after each 06:17 run; or run the job manually |
+| Backup | Copy `zappier.db` (SQLite, single file) |
+| Update dependencies | `npm outdated`, then `npm test` must stay green (165 tests) |
+
+---
+
+## 9. Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `401 invalid or missing API key` | Wrong/absent `x-api-key` | Re-issue key from Customers tab |
+| `403 No price rule for ...` | Endpoint deleted from rate card and tier has no default rule | Re-add the rule, or set a tier `defaultRule` |
+| `403 Unknown tier` | Customer's `tierId` doesn't exist | Fix the customer's type in the admin UI |
+| `400 invalid metadata JSON` | `metadata` form field isn't valid JSON | Send e.g. `{"key":"value"}` |
+| `413 ... file too large` | Attachment over 25 MB | Split or compress the file |
+| Billing run: Stripe auth error | Placeholder/wrong key in `.env`, or key from a different Stripe account | Use the `sk_test`/`sk_live` key from the account that holds the meter |
+| Stripe shows `METER_NOT_FOUND` invalid events | Meter missing or event name mismatch | Meter event name must be exactly `zappier.api_cents` |
+| `another run holds the lock, abort run` | Overlapping runs, or a crash left a stale lock | Safe by design; stale locks expire after 1 hour |
+| Admin UI: "invalid username or password" | Wrong credentials, or env overrides changed them | Check `ADMIN_KEY` / `DEMO_ADMIN_PASSWORD`; sign in again |
+| Admin UI: "Session expired" | Server restarted (admin tokens are in-memory) | Sign in again |
+| Portal login: `totp_required` | 2FA is enabled on the account | Enter the current 6-digit authenticator code |
+| Portal: "invalid or expired session" | 7-day session expired | Sign in again |
+| Portal reload didn't credit | Real `STRIPE_SECRET_KEY` configured → PaymentIntent awaits confirmation | Balance credits when the payment confirms; in dev (placeholder key) credit is instant |
+| Invoice went straight to `paid` on Issue | Customer's prepaid balance fully covered the amount due | Working as designed — balance was drawn down |
--- a/packages/zappier/docs/USER-MANUAL.pdf
+++ b/packages/zappier/docs/USER-MANUAL.pdf
--- a/packages/zappier/docs/WALKTHROUGH.md
+++ b/packages/zappier/docs/WALKTHROUGH.md
@ -0,0 +1,154 @@
+# Zappier — Step-by-Step Usage Walkthrough
+
+**Version:** 0.1.0 · **Last updated:** 2026-07-27
+
+A full guided tour: from starting the server to pricing changes, customer
+creation, and live API calls. Every step shows the real screen you should see.
+Companion documents: [USER-MANUAL.md](USER-MANUAL.md) ·
+[DEVELOPER.md](DEVELOPER.md).
+
+---
+
+## Step 1 — Start the server
+
+```bash
+cd /Users/marchon/zappier
+npm install   # first time only
+npm run dev
+```
+
+Wait for the two "listening" lines:
+
+![Start the server](walkthrough/01-start-server.png)
+
+---
+
+## Step 2 — Open the admin UI and sign in
+
+Go to **http://localhost:3000/admin**. You'll see the sign-in screen:
+
+![Sign in](walkthrough/02-login.png)
+
+Two accounts are available:
+
+| Username | Password | Purpose |
+|---|---|---|
+| `admin` | the `ADMIN_KEY` env value (default `admin-dev-key`) | Primary operator |
+| `demo` | `$$$Adm1n###` | Demo / stakeholder access |
+
+> Override either credential with the `ADMIN_USER`, `ADMIN_KEY`,
+> `DEMO_ADMIN_USER`, and `DEMO_ADMIN_PASSWORD` environment variables.
+
+---
+
+## Step 3 — The rate card
+
+After sign-in you land on the **Rate card** — one row per API endpoint with
+its price in cents:
+
+![Rate card](walkthrough/03-rate-card.png)
+
+- `status`, `storage-list` — **free**
+- `transform` — **fixed** price per call
+- `storage` — **variable**: base + per-KB metadata + per-MB attachments
+
+---
+
+## Step 4 — Change a price
+
+Edit any cent field — here `transform` is changed from **4¢ to 6¢** — and click
+**Save**. The change is live on the very next API call; no restart, no deploy.
+
+![Edit a price](walkthrough/04-edit-price.png)
+
+After saving, the table re-reads from the server and shows the new value:
+
+![Price saved](walkthrough/04b-saved-toast.png)
+
+---
+
+## Step 5 — Customer types
+
+Click **Customer types** in the sidebar. Each type is a pricing tier:
+a **multiplier** applied to every list price and a **monthly credit** of free
+included usage (cents).
+
+![Customer types](walkthrough/05-tiers.png)
+
+---
+
+## Step 6 — Add a customer type
+
+Fill the **Add customer type** form — here `edu` / Education / ×0.6 — and click
+**Add**. The new type appears immediately and can be assigned to customers.
+
+![Add customer type](walkthrough/06-add-tier.png)
+
+> New types start with 0 monthly credit — edit the row and **Save** to grant one.
+
+---
+
+## Step 7 — Customers
+
+Click **Customers** in the sidebar. This is where accounts live: their type,
+and an optional **multiplier override** for per-customer deals (blank =
+inherit from type).
+
+![Customers](walkthrough/07-customers.png)
+
+---
+
+## Step 8 — Create a customer and copy the API key
+
+Enter a name, pick a type, click **Create**. The API key appears **once** in
+the notification at the bottom-right — copy it and send it to the customer;
+it is never shown again.
+
+![API key shown once](walkthrough/08b-api-key-toast.png)
+
+The new customer appears in the table right away:
+
+![Customer created](walkthrough/08-create-customer.png)
+
+---
+
+## Step 9 — Explore the interactive API docs
+
+Open **http://localhost:3000/docs** — full Swagger docs with a "Try it out"
+console. Click **Authorize** and paste a customer API key to make live calls
+from the browser.
+
+![API docs](walkthrough/09-api-docs.png)
+
+---
+
+## Step 10 — Make an API call
+
+Call the API with a customer key. Every priced response includes its **quote**,
+so the cost of every call is transparent:
+
+![API call with quote](walkthrough/10-api-call.png)
+
+Note how the quote reflects the walkthrough itself: the 6¢ price set in step 4,
+halved to 3¢ by Grace's Pro multiplier.
+
+---
+
+## Step 11 — Check usage and credits
+
+Customers can check their own month-to-date usage anytime:
+
+![Usage summary](walkthrough/11-usage.png)
+
+`includedCents` is covered by the type's monthly credit; `billableCents` is
+what the daily billing job would report to Stripe right now.
+
+---
+
+## Where to go next
+
+- **Daily billing** runs automatically at 06:17 ET — see
+  [USER-MANUAL.md §6](USER-MANUAL.md#6-billing-operations-stripe) for the
+  Stripe meter/product/price setup and how to verify a run.
+- **Troubleshooting:** [USER-MANUAL.md §9](USER-MANUAL.md#9-troubleshooting).
+- **Internals:** [DEVELOPER.md](DEVELOPER.md).
--- a/packages/zappier/docs/WALKTHROUGH.pdf
+++ b/packages/zappier/docs/WALKTHROUGH.pdf
--- a/packages/zappier/docs/index.html
+++ b/packages/zappier/docs/index.html
@ -0,0 +1,115 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Zappier — Documentation</title>
+    <style>
+      :root {
+        --bg: #f4f5fb;
+        --panel: #ffffff;
+        --ink: #171a26;
+        --muted: #6b7186;
+        --line: #e5e7f0;
+        --accent: #4f46e5;
+        --accent-soft: #eef0fe;
+        --radius: 12px;
+        --shadow: 0 1px 2px rgba(23, 26, 38, 0.05), 0 8px 24px rgba(23, 26, 38, 0.06);
+      }
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        font-family: -apple-system, "SF Pro Text", "Segoe UI", "PingFang SC", sans-serif;
+        background: var(--bg);
+        color: var(--ink);
+        font-size: 15px;
+        line-height: 1.5;
+      }
+      header {
+        background: linear-gradient(160deg, #312e81 0%, #4f46e5 55%, #7c74f0 100%);
+        color: #fff;
+        padding: 3rem 1.5rem 2.5rem;
+        text-align: center;
+      }
+      header .dot {
+        width: 44px; height: 44px; border-radius: 12px;
+        background: rgba(255, 255, 255, 0.16);
+        display: inline-grid; place-items: center;
+        font-weight: 800; font-size: 1.3rem; margin-bottom: 0.75rem;
+      }
+      header h1 { margin: 0 0 0.35rem; font-size: 1.7rem; }
+      header p { margin: 0; opacity: 0.85; }
+      main { max-width: 880px; margin: 0 auto; padding: 2rem 1.5rem 4rem; }
+      h2 { font-size: 0.8rem; text-transform: uppercase; letter-spacing: 0.06em; color: var(--muted); margin: 2rem 0 0.9rem; }
+      .cards { display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 1rem; }
+      a.card {
+        display: block;
+        background: var(--panel);
+        border: 1px solid var(--line);
+        border-radius: var(--radius);
+        box-shadow: var(--shadow);
+        padding: 1.1rem 1.25rem;
+        text-decoration: none;
+        color: inherit;
+        transition: transform 0.12s ease, box-shadow 0.12s ease;
+      }
+      a.card:hover { transform: translateY(-2px); box-shadow: 0 4px 8px rgba(23,26,38,0.06), 0 16px 36px rgba(23,26,38,0.1); }
+      a.card h3 { margin: 0 0 0.35rem; font-size: 1.02rem; color: var(--accent); }
+      a.card p { margin: 0 0 0.7rem; color: var(--muted); font-size: 0.9rem; }
+      .fmt { display: inline-block; padding: 0.08rem 0.55rem; border-radius: 999px; font-size: 0.72rem; font-weight: 700; background: var(--accent-soft); color: var(--accent); margin-right: 0.3rem; }
+      .fmt.md { background: #f1f5f9; color: #475569; }
+      footer { text-align: center; color: var(--muted); font-size: 0.85rem; padding-bottom: 2rem; }
+    </style>
+  </head>
+  <body>
+    <header>
+      <span class="dot">Z</span>
+      <h1>Zappier Documentation</h1>
+      <p>Metered API platform — pricing, billing, invoicing, customer portal, and Zapier integration.</p>
+    </header>
+    <main>
+      <h2>Operations</h2>
+      <div class="cards">
+        <a class="card" href="USER-MANUAL.pdf">
+          <h3>Operations &amp; Usage Manual</h3>
+          <p>Running the system day to day: pricing, customers, billing operations, runbook, troubleshooting.</p>
+          <span class="fmt">PDF</span><span class="fmt">10 pages</span>
+        </a>
+        <a class="card" href="ACCOUNTING.pdf">
+          <h3>Company Accounting Walkthrough</h3>
+          <p>Invoices, purchase-order billing, prepaid drawdown, reports with CSV export, usage trends.</p>
+          <span class="fmt">PDF</span><span class="fmt">7 pages</span>
+        </a>
+        <a class="card" href="USER-MANAGEMENT.pdf">
+          <h3>User Management Walkthrough</h3>
+          <p>Admin accounts, rate card (free / fixed / variable pricing), customer types, customer accounts.</p>
+          <span class="fmt">PDF</span><span class="fmt">5 pages</span>
+        </a>
+      </div>
+
+      <h2>For your customers</h2>
+      <div class="cards">
+        <a class="card" href="CUSTOMER-PORTAL.pdf">
+          <h3>Customer Portal Walkthrough</h3>
+          <p>End-user guide: signup, two-factor authentication, usage dashboard, invoices, reloads, API &amp; pricing.</p>
+          <span class="fmt">PDF</span><span class="fmt">8 pages</span>
+        </a>
+      </div>
+
+      <h2>Technical</h2>
+      <div class="cards">
+        <a class="card" href="DEVELOPER.pdf">
+          <h3>Developer Documentation</h3>
+          <p>Architecture, module reference, pricing engine, billing pipeline, full API reference, extension guide.</p>
+          <span class="fmt">PDF</span><span class="fmt">9 pages</span>
+        </a>
+        <a class="card" href="WALKTHROUGH.pdf">
+          <h3>Step-by-Step Usage Walkthrough</h3>
+          <p>The original guided tour of the pricing admin UI with screenshots at every step.</p>
+          <span class="fmt">PDF</span><span class="fmt">13 pages</span>
+        </a>
+      </div>
+    </main>
+    <footer>Zappier · generated 2026-07-28</footer>
+  </body>
+</html>
--- a/packages/zappier/docs/screenshots/admin-customers.png
+++ b/packages/zappier/docs/screenshots/admin-customers.png
--- a/packages/zappier/docs/screenshots/admin-invoice-html.png
+++ b/packages/zappier/docs/screenshots/admin-invoice-html.png
--- a/packages/zappier/docs/screenshots/admin-invoices-generate.png
+++ b/packages/zappier/docs/screenshots/admin-invoices-generate.png
--- a/packages/zappier/docs/screenshots/admin-invoices.png
+++ b/packages/zappier/docs/screenshots/admin-invoices.png
--- a/packages/zappier/docs/screenshots/admin-login.png
+++ b/packages/zappier/docs/screenshots/admin-login.png
--- a/packages/zappier/docs/screenshots/admin-rate-card.png
+++ b/packages/zappier/docs/screenshots/admin-rate-card.png
--- a/packages/zappier/docs/screenshots/admin-reports.png
+++ b/packages/zappier/docs/screenshots/admin-reports.png
--- a/packages/zappier/docs/screenshots/admin-system.png
+++ b/packages/zappier/docs/screenshots/admin-system.png
--- a/packages/zappier/docs/screenshots/admin-tiers.png
+++ b/packages/zappier/docs/screenshots/admin-tiers.png
--- a/packages/zappier/docs/screenshots/admin-users.png
+++ b/packages/zappier/docs/screenshots/admin-users.png
--- a/packages/zappier/docs/screenshots/api-docs.png
+++ b/packages/zappier/docs/screenshots/api-docs.png
--- a/packages/zappier/docs/screenshots/portal-2fa-setup.png
+++ b/packages/zappier/docs/screenshots/portal-2fa-setup.png
--- a/packages/zappier/docs/screenshots/portal-billing.png
+++ b/packages/zappier/docs/screenshots/portal-billing.png
--- a/packages/zappier/docs/screenshots/portal-dashboard.png
+++ b/packages/zappier/docs/screenshots/portal-dashboard.png
--- a/packages/zappier/docs/screenshots/portal-docs.png
+++ b/packages/zappier/docs/screenshots/portal-docs.png
--- a/packages/zappier/docs/screenshots/portal-invoice-html.png
+++ b/packages/zappier/docs/screenshots/portal-invoice-html.png
--- a/packages/zappier/docs/screenshots/portal-invoices.png
+++ b/packages/zappier/docs/screenshots/portal-invoices.png
--- a/Show more
+++ b/Show more