planday-bridge CLAUDE.md

planday-bridge

AGENTS.md is the canonical context file — architecture, the traps, and the rules that must not be weakened. Read it before changing anything.

Setting this up for someone (agent playbook)

If a user has just arrived here and asked you to get it working, this is the sequence. Most of it you can do; two steps you cannot, and should hand back.

Prerequisites: Node 20 or newer. pnpm is what the lockfile is for, but npm install works fine — check which is available rather than assuming.

Step 1 — prove it runs locally, before any credentials.

pnpm install && pnpm dummy     # or: npm install && npm run dummy

Expect a table and ~626 rows of sample data. If that works, the whole pipeline works and anything that fails later is configuration, not code.

Step 2 — the user must fetch their own Planday credentials. You cannot.

It needs an admin login to their Planday portal in a browser. Ask them to go to Settings → Integrations → API Access → Create App, tick the scopes listed in SETUP.md, click Authorise, and copy the Client ID and Refresh Token.

Do not ask them to paste those values into the chat. A Planday refresh token grants access to staff and payroll data and does not expire on its own. Instead, create the file for them and have them fill it in:

cp .env.example .env && open -e .env    # or: code .env

Then run pnpm doctor. It checks environment, configuration, connection, every Planday scope separately, and a real report build, reporting each layer in order - fix the first FAIL, since later checks depend on earlier ones. Its output contains no credentials or staff data, so it is safe to quote back to the user or paste into an issue. Read the output, never the token.

Step 3 — deploy. You can drive this, but the secrets step is theirs.

The README has a one-click Vercel button, which is the better route for a non-technical user. From a terminal:

npm i -g vercel
vercel login
vercel link                                    # creates the project

# Ask the user to run these three themselves and type the values at the prompt,
# so the secrets never enter this transcript or their shell history.
vercel env add PLANDAY_CLIENT_ID production
vercel env add PLANDAY_REFRESH_TOKEN production
vercel env add BRIDGE_KEY production           # any long random password they choose

vercel deploy --prod