Skip to content

feat!: version 7, a typed PlaceOS client generated from the OpenAPI documents - #36

Open
MrYuion wants to merge 27 commits into
nextfrom
feat/openapi-client-v2
Open

MrYuion wants to merge 27 commits into
nextfrom
feat/openapi-client-v2

Conversation

@MrYuion

@MrYuion MrYuion commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

The 6.x client is written by hand, so its types drift from the API and nothing checks what the server sends. This replaces it with version 7, which generates its types and request functions from the rest-api and staff-api OpenAPI documents.

configure({ base_url: '', auth: { kind: 'bearer', token: getToken } });
const result = await zones.show({ id: 'zone-1234' });
if (result.ok) result.value.data.name; // typed `Zone`

Release

  • The 7.x client is the package at the repository root. The 6.x source, tests and build config are removed here. The new 6.x branch keeps them, and a fix pushed there publishes a 6.x release, such as 6.13.1.
  • This PR targets next, not master. Merging it publishes 7.0.0-next.1 under the npm tag next, and latest stays 6.13.0. A semantic-release dry run on this branch gives 7.0.0-next.1, from the BREAKING CHANGE: footer of the move commit. When apps have tried it, merging next into master publishes 7.0.0.
  • Release workflow: bun for the checks, then semantic-release from master, next and the maintenance branches (release in package.json). npm publishing still uses trusted publishing.
  • Names: variables, options, fields and namespaces are snake_case, as the data of the server is (base_url, timeout_ms, next_offset, alert_dashboards). Functions and methods are camelCase (createAuthSession, zones.showInstance). The rename used the TypeScript language service, and the generator writes the new names.
  • API docs: typedoc does not support TypeScript 7, so deno doc --html makes the GitHub Pages docs, from master only.
  • Migration map: scripts/v1-map.ts reads the 6.x source from the 6.13.0 npm package (the dev dependency placeos-ts-client-6), so the repository no longer needs the 6.x code. The map is unchanged.

How it works

  • bun run generate downloads the document from rest-api master and writes src/generated. There is one namespace per controller: 376 operations, 166 schemas.

  • Each response is parsed against its schema. A mismatch is a response_invalid error with a path such as $.items[3].name, not a bad value later in the app.

  • Request bodies are checked before they are sent. A misspelled field throws.

  • Calls return a Result: http, network, timeout, aborted, response_too_large, response_invalid or auth_missing. Every request has a timeout and a body size limit.

  • No runtime dependencies. The generated calls are marked /* @__PURE__ */, so bundlers drop the operations and schemas an app doesn't use. Gzip sizes with esbuild, 6.x → 7:

    App uses 6.x 7
    zones query + show 13.1 KB 5.2 KB
    systems query + show 13.4 KB 6.5 KB
    Login only 10.3 KB 8.9 KB
    Realtime bind + exec 13.6 KB 5.1 KB
    Login + zones + systems + realtime 17.7 KB 16.4 KB
    Whole library (export *) 33.3 KB 34.3 KB
  • configure() sets the default client. A single call can pass its own in options.client, and tests pass a fake fetch that way.

Login

createAuthSession ports the 6.x OAuth flow and gives the client its credential:

const session = createAuthSession({ base_url: '', redirect_uri: `${location.origin}/oauth-resp.html`, scope: 'public', grant: { kind: 'code' } });
configure({ base_url: '', auth: session.client_auth, headers: { 'X-App-Id': session.client_id } });
await session.start();
  • Grants: code with PKCE, implicit, password and Entra. Also covers hidden-iframe login, deep links (handleRedirect), the foreground re-check, and API keys for fixed devices.
  • Compatible with 6.x: same client ID (md5(redirect_uri)) and the same storage keys, so users stay signed in when an app upgrades.
  • With the client: a 401 renews the token and retries the request once. Parallel requests share one renewal.
  • Changes from 6.x:
    • Token requests send their parameters in the body, not the URL, so the password is no longer in the URL.
    • The default token path is /auth/oauth/token. auth.cr and the Ruby auth both serve it; the Ruby auth returns 404 for /auth/token.
    • A consent denial or a refused code stops the login until start() is called again. 6.x kept redirecting.
    • Relative login and logout URLs resolve against base_url. 6.x used the authority's domain, which has no port.
    • Frame logins check state, so apps need the new oauth-resp.html.
    • x-api-key is removed from the URL after it's read.
    • Loading /auth/authority gets 5 attempts instead of retrying forever.
    • A logout ends any login, renewal or deep link still in progress.
  • Checked against PlaceOS/auth.cr: read from source. Authority, authorize (code and implicit), token form body, PKCE S256, the error format and logout all match. auth.cr disables the password grant, so it only works with older auth services.
  • Not ported: revokeToken, authorise(state) and the ACA Engine path.

Realtime

createRealtime ports the 6.x WebSocket client: one socket to systems/control, using the server's protocol.

const realtime = createRealtime({ base_url: '', auth: session.client_auth });
const release = realtime.bind({ sys, mod: 'Display', name: 'power' }, (state) => { /* ... */ });
const result = await realtime.exec({ sys, mod: 'Display', name: 'power' }, [true]);
  • Bindings: counted per variable, and bound again after every reconnect. Incoming messages are handled in batches, and listeners get the latest value of each variable once per batch.
  • Results: exec returns a Result. A call the server already received fails with disconnected if the socket drops; 6.x never settled those.
  • Limits: pending calls, the inbox, keep-alive (a socket silent for 60 seconds is dropped), connect timeout, and reconnect backoff with a maximum number of attempts.
  • Changes from 6.x: identical exec calls are no longer merged, error codes are read from the right field, and iface is supported.

Migrate from 6.x

npx -p @placeos/ts-client@next placeos-migrate [--write] src rewrites the 6.x calls in a project. It runs dry by default and writes only with --write.

// 6.x
const zone = await showZone(id, { complete: true });
// after the tool
const zone = await zones.show({ id, complete: true }).then(orThrow);
  • What it changes: the 322 mapped REST functions, the 6.x class types (PlaceZone → Zone) and the 6.x enum imports. orThrow, orThrowPage and the enums (with their 7.x values) are in the new @placeos/ts-client/compat entry.
  • What it leaves: auth, realtime, raw HTTP, new PlaceX(), test mocks and arguments that have no place in 7.x. Each one keeps its 6.x import, so the compiler flags it, and the tool lists it with a hint. A second run changes nothing.
  • How the map is built: scripts/v1-map.ts calls each 6.x function with marker arguments, records the request and matches it to a 7.x operation. CI runs v1-map:check.
  • Test doubles: vi.mocked, expect, vi.spyOn, mock values, argument checks and vi.mock factories are rewritten to the 7.x calls; fromV1Mock keeps 6.x mock implementations working. On a copy of backoffice, 329 of 399 specs pass after the tool (394 on 6.x). The rest use 6.x classes, 6.x next() pagination or createSignal, which the tool reports.
  • Tried on backoffice (a copy): 734 calls rewritten in 135 files, and 876 uses left for a person (most are HTTP mocks in specs). A dry run on user-interfaces rewrites 1,060 calls in 234 files.
  • Bug found: without strictNullChecks, as in backoffice, every 7.x operation asked for a body. That is fixed, and test/loose now type-checks the published types without strict.

Staff API

  • @placeos/ts-client/staff is generated from PlaceOS/staff-api: 145 operations, 87 schemas (bookings, events, guests, desks, spaces, surveys, tenants…).
  • staff-api numbers alternative routes of one action (show_2, check_in_4). PATCH/PUT pairs still become one update, alias paths (checkin beside check_in) are dropped, and longer paths get names from their segments (bookings.showInstance).
  • Live test against a local stack: 34 checks pass, including a booking create, show and destroy. The calendar endpoints return 500 there because the stack has no calendar backend.

Mocks

  • Typed mocks (@placeos/ts-client/mock): mockEndpoint('zones.show', (input) => ({ id: input.id })). The compiler checks the endpoint name, the input and the data. The client checks the input and parses the data as it would a server response; missing required fields get empty values. respond(data, { status, total }) and httpError(404) cover pages and errors.
  • 6.x mocks (@placeos/ts-client/compat): registerMockEndpoint with mockFetch, and registerSystem with mockRealtimeEnvironment(). missing_fields: 'zero' fills the fields that 6.x mock data leaves out. With it, backoffice's demo mocks (204 endpoints) serve 27 of 28 7.x calls; the one failure is a mock-data bug (features is a string, not an array).
  • Short type names: User, System, Application, Domain, Metadata, ShortUrl and SignageTemplateMapping alias the odd spec names.

Debug logs

  • configure, createAuthSession and createRealtime take an optional log function. Without it, nothing is logged.
  • Inside the library, each part logs through a scoped logger. Its methods take the same arguments as the console methods (error, warn, info, debug, print, group, groupEnd).
  • consoleLog in @placeos/ts-client/compat prints the 6.x format ([PlaceOS][Auth] the authority is loaded) through the console method of the level, while window.debug is set.
  • No entry has a token, API key, cookie, request body or input value. 6.x logged the socket cookie, token included.

Where the spec is wrong

The generator patches these, with a comment for each in scripts/generate.ts:

  • Time fields: most model timestamps (created_at, last_login, expires_at, …) are listed as ISO date-time, but the server sends Unix seconds. The spec generator drops the type: "integer" hint on PgORM attributes. The patch table comes from the PlaceOS/models source. PgORM::Timestamps models (groups, signage templates, pending mails) really are strings. The generator stops on any time field that isn't classified.
  • required describes responses: for example, a metadata PATCH would "require" created_at. Body fields are optional in input types and the server validates them. Path and query parameters keep their required flags.
  • Enum numbers: Driver.role, Module.role, Settings.encryption_level, Broker.auth_type and the playlist animations arrive as numbers, but the spec lists names. The values come from the PlaceOS/models source, and a live server confirmed them.
  • Duplicates and gaps: each PUT/PATCH update pair becomes one update that sends PATCH. The execute and state_value endpoints return JSON but have no schema in the spec. The 7 WebSocket endpoints are skipped.

Keeping the generated code current

  • The generated code stays in the repository, so each API change is a reviewable diff, and a commit always records the API version it was built from.
  • A daily Regenerate workflow regenerates from master. When the output changes, it opens a PR with the diff and the check results, closes older regeneration PRs, and deletes regeneration branches that have no open PR.
  • It runs only from master, so it starts after next merges into master. For the default token, "Allow GitHub Actions to create and approve pull requests" must be on. A REGENERATE_TOKEN secret makes the regular checks run on those PRs.

Not in this PR

  • The model classes from 6.x.
  • A rewrite of 6.x auth and realtime calls. The migration tool lists them.
  • Nothing checks that the committed generated code still matches rest-api. bun run generate:check does it on demand.

Testing

  • bun run check: strict type check of the library, tests and scripts, plus a separate check without Bun types.
  • bun test: 130 tests, including the migration tool and the mocks. They cover the parser, the client error paths, pagination and configure; every login path and its races, against a fake browser and server; the realtime protocol on fake sockets with a manual clock; MD5/SHA-256 test vectors; and a style guard against any, ! and unlisted casts.
  • Live test against a local PlaceOS stack (Ruby auth): all 70 checks pass. That covers PKCE login, query and show on every namespace with real data, a zone create/update/delete, a forced 401 renewal, realtime bind and exec, and logout.
  • The packed tarball type-checks in a separate project under nodenext and bundler resolution.
  • Browser test against the same stack, in Chromium 152 through a dev proxy, as the apps run: 68 checks pass and 0 fail. It covers the login page and the OAuth redirect, the hidden-frame login, every query and show, a zone write round trip, the staff API, abort and timeout, a 401 renewal, and the realtime socket with the token in a cookie. The 5 skips are 4 operations that need path parameters and uploads, which returns a 500 from the server.
  • .github/workflows/ci.yml runs the map check, the types, the tests and the build on every PR.

Reviewed with sol-loop: 14 rounds with gpt-6.1-sol, in four blocks. Sol verdict: core, generator and realtime approved. Auth used its full 5-round budget; the last fix (a one-line reorder, with a test) was not reviewed again.

Reviewed again with sol-loop for the migration tool, mocks, staff API and regeneration: 4 rounds with gpt-6.1-sol on xhigh, in two tracks (a direct review, and conformance to the code style rules). Sol verdict: approved on both. 21 findings fixed; one rare-case nit (a shadowed helper alias) is a follow-up.

Created with Claude Opus 5.5 in Claude Code.

🤖 Generated with Claude Code

The hand-written v1 client drifts from the API: types are guesses and
nothing checks the data the server sends. v2 generates its types and
request functions from the OpenAPI document of PlaceOS/rest-api, and
parses each response at the boundary, so a mismatch is a typed error
with a path instead of a bad value deep in an app.

v2 is a separate package in v2/ (Bun, no runtime dependencies) that
follows TigerStyle: errors are Result values, every request has a
timeout and a body size limit, and the types come from the schemas.

The generator patches the document where it is wrong, with a comment
for each patch: time fields that the server sends as Unix seconds,
request bodies whose fields the document marks as required, and the
PATCH/PUT duplicate of each update.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread v2/src/core/client.ts Fixed
MrYuion and others added 2 commits November 17, 2026 13:27
v2 had no login: an application had to get its own token. This ports
the v1 auth flow as createAuthSession, which gives the client its
credential and renews it after a 401.

It keeps the v1 client ID (md5 of the redirect URI) and storage keys,
so users stay logged in when an application changes to v2. It covers
the code grant with PKCE, the implicit, password and Entra grants,
login in a hidden frame, deep links, the foreground re-check and API
keys for fixed devices.

Differences from v1, for safety and bounds: token requests send their
parameters in the body (no password in the URL), frame logins check
the state, x-api-key is removed from the URL, and the authority load
has a bounded number of attempts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…eview

v2 had no realtime client, and its login and schemas had only been
checked against fakes. This ports the v1 WebSocket client as
createRealtime, then fixes what checking against real servers and a
review found.

Realtime: one socket to systems/control in the server's protocol,
counted bindings rebound after each reconnect, exec as a Result, and
named limits on calls, the inbox, keep-alive and reconnects.

Against PlaceOS/auth.cr (source) and a local stack (Ruby auth):
- the token path is /auth/oauth/token, as /auth/token is a 404 on the
  Ruby auth
- a consent denial or a refused code stops the login, and stays stopped
  until start(), so a request cannot restart a redirect loop
- relative login and logout URLs resolve on baseUrl, not the authority
  domain, which has no port
- enums that the server sends as numbers are patched in the generator

From review: call timeouts cover the credential wait, json() refuses
values that JSON.stringify would change, a logout ends pending work,
the storage wrapper sees other tabs, and stricter generator guards.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MrYuion MrYuion changed the title feat(v2): typed client generated from the rest-api OpenAPI document feat(v2): typed PlaceOS client from the OpenAPI document, with login and realtime Nov 17, 2026
MrYuion and others added 7 commits November 17, 2026 15:05
CodeQL flagged the path template regex of operation() as polynomial:
`[^}]+` also matches `{`, so a template with many braces backtracks.
`[^{}]+` cannot, so the match is linear. splitModuleId had the same
shape (`^(.+)_(\d+)$`) on caller input; it now splits on the last `_`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each generated operation and schema is a call that runs when its module
loads. A bundler must keep such a call, so an app that used one zones
operation shipped every zones operation and each schema they reach.

The generator now marks those calls /* @__PURE__ */. With esbuild,
zones index + show drops from 11.5 KB to 5.2 KB gzip (v1: 13.1 KB), and
an app with login, zones, systems and realtime from 21.6 KB to 16.4 KB
(v1: 17.7 KB). Rollup and Bun show the same.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ctNullChecks

A project on v1 must change each call to move to v2. backoffice has 734 calls in 135 files.

- `placeos-migrate` rewrites v1 REST calls to the v2 operations with `.then(orThrow)`, renames
  the v1 class types, and moves the v1 enum imports to `@placeos/ts-client/compat`. It does not
  change a use that it cannot rewrite safely, and it shows each one with a hint.
- `scripts/v1-map.ts` makes the v1 to v2 map: it calls each v1 function with marker arguments
  and matches the request to a v2 operation. CI checks that the map is up to date.
- `OperationInput` and `OperationData` checked `B extends AnySchema` first. Without
  `strictNullChecks`, `null` matches, so each operation asked for a body. `test/loose` now type
  checks the published types without `strict`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Apps on v1 mock the client in their tests and in a mock mode. After the migration, those mocks
no longer reached the v2 calls, and some v2 schema names did not say what they are.

- `@placeos/ts-client/mock`: `mockEndpoint('zones.show', handler)` answers the calls of one
  endpoint. The compiler checks the name, the input and the data. The client checks the input
  and parses the data as it does for a response. Operations now have a `name`, and the client
  has an optional `mock` hook.
- `@placeos/ts-client/compat` has the v1 mock endpoints (`registerMockEndpoint`, `mockFetch`)
  and mock systems (`registerSystem`, `mockRealtimeEnvironment`), and `missingFields: 'zero'`
  fills the required fields that mock data leaves out, as the v1 classes did.
- The migration tool rewrites test doubles: `vi.mocked`, `expect`, `vi.spyOn`, mock values,
  argument checks and `vi.mock` factories (with `fromV1Mock`). On a copy of backoffice, 329 of
  399 tests pass after the tool; the rest use v1 classes or v1 pagination, which it reports.
- Short names for odd schema names: `User`, `System`, `Application`, `Domain`, `Metadata`,
  `ShortUrl`, `SignageTemplateMapping`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Apps call the staff API (bookings, events, guests, surveys) as much as the REST API, and v2 had
no client for it.

- The generator also reads `OPENAPI_DOC.yml` of PlaceOS/staff-api and writes
  `src/generated/staff`, at `@placeos/ts-client/staff`: 145 operations, 87 schemas.
- Numbered routes of one action merge: PATCH and PUT stay one `update`, an alias path such as
  `checkin` is dropped, and a longer path gets a name from its segments, such as
  `bookings.showInstance`.
- The `body` query parameter of `events.book` is `body_text` in the input. Operations have
  `wireNames` for this.
- The staff time fields are classified from PlaceOS/models, PlaceOS/calendar and
  PlaceOS/office365.
- Typed mocks have the staff endpoints (`staff.bookings.show`), and the migration tool maps the
  v1 staff functions, such as `querySurveys`, to the staff client.
- The list operation of each controller is `query`, not `index`: `zones.query(...)`.

A live test against a local PlaceOS stack passes: 70 REST API checks and 34 staff API checks,
with a booking create, show and destroy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ion PRs

The generated client is in the repository, and nothing showed when the API documents on master
moved ahead of it.

- The `v2 regenerate` workflow runs `v2/scripts/regenerate-pr.sh` each day. When the output
  changes, it opens a PR on `bot/v2-regenerate-<hash>` with the diff and the check results.
- A newer regeneration closes the older PRs and deletes their branches. When master matches the
  documents, it closes all of them. Each run also deletes the regeneration branches without an
  open PR, such as the branch of a merged PR.
- The same change on a later day finds its open PR and does nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…and generator

A review of the changes since the last sol loop found silent wrong rewrites in the migration tool,
promises without a handler in the mock path, and data without limits.

- Migration: a v1 list that maps to a v2 record (listMetadata) is unmapped; `version` keeps the
  v1 `|| 0` fallback; a test double whose v1 arguments cannot be rebuilt stays v1 with a finding;
  factory values stay mocks; helper imports are reused or get an alias; the `vi.hoisted` line goes
  with the new imports; files deeper than AST_DEPTH_MAX and folder walks over ENTRIES_MAX stop.
- Client: a mock answer has the deadline, the signal and the size limit of a response, and starts
  inside `waitWithin`; `waitWithin` checks the signal again after `work()` starts.
- Schema: zero-fill picks the union variant that knows the most given fields.
- Compat: a string mock body is JSON; the realtime mock has one bounded outbox and named limits.
- Regeneration: new generated files are in the change hash.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@MrYuion MrYuion left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

🤖 Claude Opus 5.5 responding on behalf of Alex

I found no blocking issues in the core client, the auth session or the realtime client. I found one security bug (an API key goes to a redirect target), one data-loss bug in the migration map, and some smaller items. The details are in the inline comments.

What I ran at df6015ef: bun install --frozen-lockfile, bun run check, bun test (130 pass), bun run build, generate:check and v1-map:check. All of them pass. I reproduced each inline finding with a script on Bun, and on Node for the redirect.

CodeQL alert. Fixed. On 5fd840be, client.ts:212 had /\{([^}]+)\}/g. HEAD has /\{([^{}]+)\}/g at client.ts:262, which cannot backtrack across braces, and code scanning shows alert 43 as fixed on this branch. The input is a generated path constant, not user data. generate.ts:582 still has the old regex, but it reads only the API document, so that does not matter.

v2-regenerate workflow. The permissions are the minimum that the job needs: contents: write to push the branch and pull-requests: write for the PRs. The script closes and deletes only open PRs to master whose head starts with bot/v2-regenerate-, and only remote branches with that prefix. The inline comment on regenerate-pr.sh covers the fork and --limit cases. For hardening: the checks run the generated code while GH_TOKEN is set and while actions/checkout keeps the token in the git config. The generate.ts escape fix removes the obvious way in. A separate step without the token for the checks would remove more.

Type safety. The only any outside the generated code is in the compat mock types (MockHttpRequest.body, MockModule), which match the v1 types. That is correct for compat. The two casts in call and parseResponse have comments that explain them, and the tests cover the parser.

Ported from v1, not flagged. oauth-resp.html moves the hash parameters into the query of the app URL, and an implicit-grant access_token is one of them, so the token gets into the access log of the app server. Also, an x-api-key in any page URL becomes the stored API key. v1 does both. They could be a follow-up, but they are outside this PR.

Not run. The browser-only paths (frame login, the WebSocket cookie, localStorage), anything against a live PlaceOS server, and regenerate-pr.sh against GitHub.

Comment thread src/core/client.ts Resolved
Comment thread scripts/v1-map.ts Resolved
Comment thread src/migrate/cli.ts Resolved
Comment thread src/migrate/migrate.ts Resolved
Comment thread scripts/regenerate-pr.sh Resolved
Comment thread scripts/generate.ts Resolved
Comment thread src/core/client.ts Resolved
Comment thread src/migrate/migrate.ts Resolved
MrYuion and others added 2 commits November 18, 2026 13:14
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The 7.x client was in v2/, beside the 6.x client at the root. It is now the package: the
6.x source, tests and build config are gone from this branch, and the 6.x branch keeps them
for fixes.

- The 6.x to 7.x migration map reads the 6.x source from the 6.13.0 npm package.
- The release workflow uses bun, publishes from master, next (prereleases) and the
  maintenance branches, and makes the API docs with deno doc.
- The docs and comments name the versions 6.x and 7.x.

BREAKING CHANGE: version 7 is a new client with a different API. `npx -p
@placeos/ts-client@7 placeos-migrate` rewrites the 6.x calls of a project. See "Migrate from
6.x" in the README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MrYuion MrYuion changed the title feat(v2): typed PlaceOS client from the OpenAPI document, with login and realtime feat!: version 7, a typed PlaceOS client generated from the OpenAPI documents Nov 18, 2026
@MrYuion
MrYuion changed the base branch from master to next November 18, 2026 02:33
MrYuion and others added 7 commits November 18, 2026 14:23
A chore commit makes no release, so a merged regeneration did not reach npm.
The PR tells the reviewer to change the message to feat or add a BREAKING
CHANGE footer when the diff needs it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The options and fields of the client had camelCase names, while the data of the
server is snake_case. Variables, parameters, data properties and the namespaces
are now snake_case. Functions and methods keep camelCase. Names that outside code
fixes stay: server fields, the 6.x names of the migration map, vitest, OpenAPI
and browser names.

The rename used the TypeScript language service. The generator writes the new
names, and the 6.x migration map has the new namespaces.

BREAKING CHANGE: the options and fields are snake_case, for example `base_url`,
`timeout_ms`, `redirect_uri`, `session.client_auth` and `next_offset`. The
namespaces are snake_case, for example `alert_dashboards`, and so are the names
of the typed mocks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A paged call needed the offset from `pageInfo` and a second call with the same
input. The reply of each operation with an `offset` parameter now has `next()`:
the same input at the offset of the `Link` header, through the same client. It
gives `null` on the last page, and when the offset does not move forward, so a
loop over the pages ends.

`respond` of the typed mocks takes `next_offset`, and `mockPage` gives a reply
whose `next()` gives `null`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- A new import that clashes with a name of the file gets a suffix in the style
  of the name: `zones_v7`, `orThrowV7` and `SignagePluginV7`. It was `V2`.
- The CLI tells the project to install the version that made the changes, from
  its own package.json. `@7` does not install a prerelease, so the README uses
  `@next` until 7.0.0 is out.
- `fromV1Mock` takes its result type from the test double that holds it, so
  `vi.mocked(zones.show).mockImplementation(fromV1Mock(...))` type-checks. It
  also takes no input, as `zones.query()` does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
6.x wrote debug logs to the console when `window.debug` was set. 7.x wrote
nothing, so a login or a binding could not be traced.

- `configure`, `createAuthSession` and `createRealtime` take a `log` function.
  Without it, nothing is logged.
- Each part logs through a scoped logger, as `std.log.scoped` does in Zig. Its
  methods have the arguments of the console methods: error, warn, info, debug,
  print (`console.log`), group and groupEnd. An entry is `{ scope, level, args }`.
- `consoleLog` and `createConsoleLog({ colors })` of the compat module write the
  6.x format, `[PlaceOS][Auth] the authority is loaded`, with the console method
  of the level, when `window.debug` is set. A string first argument joins the
  prefix. The 6.x mock endpoints log through it, as in 6.x.
- An entry has no tokens, API keys, cookies, request bodies or input values.
  6.x logged the socket cookie with the token in it. A log function that throws
  does not change the caller.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The docs compared the logger to Zig and named TigerStyle as the code style.
They now describe the logger and the design rules directly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
PlaceOS/rest-api#469 documents the Unix-second timestamps as integers, so
the rest-api needs no epoch patch. The staff-api document is not
regenerated yet, so it keeps its list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@MrYuion MrYuion left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

🤖 Claude Opus 5.5 responding on behalf of Alex

Re-review of df6015e..7366c94. The move to the root, the snake_case rename and next() look correct to me. next() returns null when the Link offset does not move forward (client.ts:389), so a loop over the pages ends. The one real bug is in the test doubles of paged operations (inline on result.ts). The other inline comments are small.

What I ran at 7366c94: bun install --frozen-lockfile, bun run check, bun test (141 pass), bun run build, generate:check and v1-map:check. All pass. I checked the migration items with migrateSource.

Fixed since the last review

  • From the test-pattern comment, a bare reference such as ids.map(showZone) now gets a finding.
  • CodeQL alert 43 was already fixed.

Still open at 7366c94, with no change in the code:

  • The API key goes to a redirect target. init at client.ts:453 has no redirect option, and short_url.redirect is still generated.
  • updateMetadata(id, data, 'patch') still becomes metadata.update with no finding.
  • The CLI still loads the typescript package of the project with require, so it stops on TS 7.
  • Of the test patterns, the spread that is not an identifier, the method in a factory and the double in a variable still give no finding.
  • open_prs in regenerate-pr.sh has no isCrossRepository check, and --limit still applies before the filter.
  • plan.path still goes into the output without escaping (generate.ts:1079).
  • . and .. path segments still pass the check at client.ts:581.
  • Unmapped names on a namespace import, such as client.authority(), still give no finding.

Comment thread src/compat/result.ts Resolved
Comment thread .github/workflows/regenerate.yml Resolved
Comment thread src/core/log.ts Resolved
Comment thread oauth-resp.html Resolved
Comment thread scripts/generate.ts Resolved
Comment thread src/compat/http-mock.ts Resolved
Comment thread src/core/client.ts Resolved
MrYuion and others added 2 commits November 19, 2026 10:11
The API documents type some string fields as object and leave out
read-only fields that the server sends. The client dropped those fields.
The generator now types the string fields and adds the missing fields.
Each patch asserts the document shape, so the generator stops when
upstream fixes it (PlaceOS/rest-api#470).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- With an API key, a call does not follow a redirect, because fetch keeps
  X-API-Key on a redirect to another origin. short_url.redirect is not
  generated.
- Path parameters cannot be . or ..
- mockReply gives next(), so it is a valid double of a paged operation.
- The rest-api time fields get the "Unix time in seconds." note again.
- plan.path is escaped in the generated code.
- The regenerate workflow runs on the branch of the run, with a branch
  prefix for each base. open_prs skips forks and stops on a full list.
- The migration tool gives findings for updateMetadata with a method,
  unnamed spreads and methods in mock factories, doubles in variables,
  and unmapped names on a namespace import. The CLI checks the
  TypeScript version and can use the TypeScript next to the tool.
- An aborted call logs at debug. The mock 404 log is in the default
  not-found handler, as in 6.x.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MrYuion and others added 6 commits November 19, 2026 14:12
PlaceOS/rest-api#471 and PlaceOS/staff-api#398 regenerated the API
documents, so the patches for string fields, missing read-only fields,
number enums and the staff-api time fields are gone.

- The time fields and the number enums keep their notes: the unit and
  the name of each number.
- The generator accepts `readOnly`, and a 204 next to the success
  response. The client gives `null` for a 204, so
  staff.calendars.availability has nullable data.
- The fields that refer back to Booking are `json()`, because the
  schemas cannot have a cycle.
- oauth_applications path IDs are integers. The inline enums of the
  documents are no longer named exports.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A schema with the same name in both APIs can have different fields, and
metadata has both update (PUT) and merge (PATCH). The mock system example
now compiles with strict types. Other sections get shorter sentences,
examples and lists.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The login comes before the mocks, the 6.x changes are in the migration
section, and the contributor sections are at the end. A new section
describes the fields of the result: the reply and each error kind.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An operation without a response schema now gives the body as a string,
for example the text of modules.logs, or '' for a destroy. The
operations that send files or images (the upload downloads, the URL
proxy, the PNG QR codes, the thumbnails and the staff photos and space
images) still give a Uint8Array. BYTES_RESPONSE_OPERATIONS in the
generator has the list, from the server source.

An operation declares `response: 'text'` or `response: 'bytes'` in place
of `null`. A typed mock of a text operation can give a string or nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The API calls a value such as `Display_2` a `module_slug`, so the
function and its parameter now use that name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The README said "the second argument" without an example of it. It now
lists the input and the options, and the systems.execute example passes
options.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants