planday-bridge: Instructions file for Codex

planday-bridge — context for AI coding agents

If you are an AI agent working in this repo, read this first. It carries the domain knowledge and the non-obvious traps, most of which cost real time to rediscover.

Humans: README.md for the developer tour, SETUP.md to just get it running.

What this is

Two things over the Planday workforce-management API:

1. A translator producing Planday's Timesheet Report — worked hours and staff cost per shift — which has no single endpoint and must be assembled from three.
2. An MCP server exposing all 125 Planday operations.

Architecture

Everything derives from the vendored OpenAPI specs. Do not hand-write endpoint wrappers — regenerate instead, or coverage silently rots.

specs/*.json          vendored from openapi.planday.com/{area}/swagger/v1.0/swagger.json
scripts/generate.ts   specs -> src/generated/operations.json   (pnpm gen)
src/generated/        125 operations, 294 schemas. COMMITTED - do not gitignore.
src/planday/          auth, http (+ offset loop), validation, invoke (the dispatcher)
src/timesheet/        columns -> transform (pure) -> build -> summarise -> csv
src/bridge/           handler + setup page, shared by both HTTP entrypoints
src/fixtures/         seeded sample portal + schema-driven synthesiser
src/source.ts         LiveSource | DummySource behind one interface
apps/mcp/             the MCP server (19 tools, 3 layers)
apps/bridge/          standalone HTTP server (local + Docker)
api/index.ts          serverless entrypoint; vercel.json rewrites everything here
powerquery/           Timesheet.pq (GENERATED), Timesheet-direct.pq (hand-written)

Every call goes through src/planday/invoke.ts. Both HTTP entrypoints delegate to src/bridge/handler.ts — never add a route to one without the other, or the hosted and local builds diverge.

Traps

Each of these was found the hard way.

• The spec URLs are undocumented. https://openapi.planday.com/{area}/swagger/v1.0/swagger.json for area in absence hr pay payroll portal punchclock reports revenue scheduling. Nothing on Planday's docs site links to them, and the docs site itself is a JS app that fetches them at runtime.
• openapi.planday.com/api/{area} is a documentation page, not an endpoint. Aiming Power Query or an HTTP client at one is the most common Planday integration mistake.
• Every request needs two headers, Authorization: Bearer and X-ClientId. Omitting the second gives a 401 that reads like a bad token. The spec mentions neither it nor a base URL — there is no servers block. Both are injected by src/planday/http.ts.
• limit is hard-capped at 50 on list endpoints (maximum: 50); raising it is silently ignored. Walk offset against paging.total. The paging envelope is { data, paging: { offset, limit, total } } and is identical across all nine areas. The three report endpoints are not paged — they are bulk date-range calls.
• 113 of 125 operations have no operationId. Ids are synthesised in scripts/generate.ts as {area}.{method}.{pathSlug}, purely from method + path so they stay stable across regeneration. Never make an id depend on ordering or a counter.
• Planday's date-time is a .NET DateTime. Its own documented example for the punch-clock parameters is 2025-01-01T00:00 - no seconds, no offset - which strict RFC 3339 rejects. Left on the ajv-formats default, our validator refused requests that Planday accepts, across 24 parameters in 6 operations. Overridden in validation.ts.
• format: time is a .NET TimeOnly, not RFC 3339. ajv-formats demands a timezone offset in both fast and full mode, which would reject every legitimate shift time — Planday pairs a local wall-clock time with a separate timeZone field. src/planday/validation.ts overrides time and date-span for this reason. Use createAjv() from there — never construct a bare Ajv, or tests will validate under looser rules than the dispatcher enforces.
• Two POSTs are reads. reports.post.schedulingHistory and absence.post.accounts.balance.employees are queries whose filters are too big for a query string. They are in READ_ONLY_POSTS in the generator; tiering by HTTP verb alone would put the entire Timesheet Report behind the write gate.
• firstApproved is a snapshot, not a timestamp. Planday exposes no approval time at all. The column is first_approved_hours; comparing it to approved is what surfaces edited_after_approval.
• shiftId is nullable for punch-clock entries never matched to a shift. The row key is shiftId ?? "pc-<punchclockId>". Power BI needs a real primary key, and this is the case a hand-rolled Power Query merge gets wrong.
• Salaried staff never appear in shiftsPayroll — only in salariedPayroll. Their shifts legitimately carry hours with no cost. Do not "fix" this.
• Never read a file relative to import.meta.url. It is undefined once the code is bundled into a serverless function, and the lambda dies at cold start while every local test stays green. This bit once — the operation catalogue was loaded that way. It is now import catalogue from "./operations.json" with { type: "json" } so bundlers inline it. test/deploy.test.ts is the only test that would catch a repeat.
• Planday gates each area by its own authorization policy. A perfectly valid token can be refused on payroll alone. Anything touching cost must degrade — payroll, then time-and-cost, then hours with no cost — never throw. pnpm whoami probes each area.