@quickback-dev/cli 0.64.0 → 0.64.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.js +1 -1
- package/dist/skill/docs/configure/auth.md +7 -5
- package/dist/skill/docs/configure/index.md +4 -3
- package/dist/skill/docs/configure/providers.md +1 -1
- package/dist/skill/docs/define/changesets.md +8 -3
- package/dist/skill/docs/platform/auth/jwt-optimization.md +4 -2
- package/dist/skill/docs/platform/realtime/durable-objects.md +1 -1
- package/dist/skill/docs/platform/realtime/index.md +1 -1
- package/dist/skill/docs/platform/realtime/live-views.md +1 -1
- package/dist/skill/docs/platform/realtime/named-invalidations.md +1 -1
- package/dist/skill/docs/platform/realtime/using-realtime.md +1 -1
- package/dist/skill/docs/tooling/output.md +3 -2
- package/dist/skill/docs/ui/admin/connecting.md +1 -1
- package/package.json +1 -1
- package/src/skill/docs/configure/auth.md +7 -5
- package/src/skill/docs/configure/index.md +4 -3
- package/src/skill/docs/configure/providers.md +1 -1
- package/src/skill/docs/define/changesets.md +8 -3
- package/src/skill/docs/platform/auth/jwt-optimization.md +4 -2
- package/src/skill/docs/platform/realtime/durable-objects.md +1 -1
- package/src/skill/docs/platform/realtime/index.md +1 -1
- package/src/skill/docs/platform/realtime/live-views.md +1 -1
- package/src/skill/docs/platform/realtime/named-invalidations.md +1 -1
- package/src/skill/docs/platform/realtime/using-realtime.md +1 -1
- package/src/skill/docs/tooling/output.md +3 -2
- package/src/skill/docs/ui/admin/connecting.md +1 -1
package/dist/index.js
CHANGED
|
@@ -24,12 +24,14 @@ Lowest-to-highest privilege list. Lets access rules use `'role+'` shorthand to m
|
|
|
24
24
|
|
|
25
25
|
Quickback ships its own custom HMAC-SHA256 JWT (not Better Auth's JWT plugin) so it can embed `orgId` and `role` claims the fast-path needs to reconstruct `AppContext` without a database round-trip. The signing secret is shared with Better Auth (`BETTER_AUTH_SECRET`) by default — users only manage one secret.
|
|
26
26
|
|
|
27
|
-
> **
|
|
27
|
+
> **This JWT surface is opt-in by default**
|
|
28
28
|
>
|
|
29
|
-
>
|
|
30
|
-
> when `auth.jwt` is present. If it is omitted, generated output
|
|
31
|
-
> `/api/
|
|
32
|
-
>
|
|
29
|
+
> Contract v2 is the default since v0.64.0, and on it Quickback emits this custom
|
|
30
|
+
> JWT surface only when `auth.jwt` is present. If it is omitted, generated output
|
|
31
|
+
> has no generic `/api/v1/token` endpoint, no JWT middleware verify/mint
|
|
32
|
+
> fast-path, and no Quickback JWT imports. (`src/lib/jwt.ts` is still emitted when
|
|
33
|
+
> the project declares [`authz.scopes`](/define/scopes) — scope tokens are signed
|
|
34
|
+
> JWTs.) Pin `contract: { version: "v1" }` to emit it unconditionally. Generated `llms.txt` and RFC 8414 discovery metadata
|
|
33
35
|
> also omit Bearer-JWT instructions, token endpoints, and JWT scopes that do not
|
|
34
36
|
> exist. Better Auth cookie and signed session-token bearer authentication remain
|
|
35
37
|
> available.
|
|
@@ -499,12 +499,13 @@ A modern Quickback project runs on **one Cloudflare Worker** that serves multipl
|
|
|
499
499
|
|
|
500
500
|
When any subdomain is configured (`account.domain`, `cms.domain`, `auth.domain`, `api.domain`, `apps.<n>.domain`), the compiler always emits a unified backend host where **every compiler-emitted backend route** is reachable:
|
|
501
501
|
|
|
502
|
-
- `/api/v1/*` and `/auth/v1/*`
|
|
503
|
-
|
|
502
|
+
- `/api/v1/*` and `/auth/v1/*` by default, or `/api/v2/*` and `/auth/v2/*`
|
|
503
|
+
when `contract.routes` is `"v2"` (the URL axis — `contract.version` does
|
|
504
|
+
not move these)
|
|
504
505
|
- `/storage/*` — R2 file storage
|
|
505
506
|
- `/health`, `/openapi.json` — monitoring/discovery
|
|
506
507
|
- `/account/*`, `/cms/*` — bundled SPAs (when enabled)
|
|
507
|
-
- `/broadcast/v1/*` (realtime; `/broadcast/v2/*` under `contract.
|
|
508
|
+
- `/broadcast/v1/*` (realtime; `/broadcast/v2/*` under `contract.routes: 'v2'`), `/mcp` (MCP), etc.
|
|
508
509
|
|
|
509
510
|
The unified hostname is `quickback.{baseDomain}` by default (where baseDomain is extracted from your first configured subdomain). Override with `config.domain` if you prefer a different name.
|
|
510
511
|
|
|
@@ -215,7 +215,7 @@ providers: {
|
|
|
215
215
|
}
|
|
216
216
|
```
|
|
217
217
|
|
|
218
|
-
> The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.
|
|
218
|
+
> The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.routes: "v2"`. It tracks the URL axis, not `contract.version`.
|
|
219
219
|
|
|
220
220
|
`wsTicket` tells the compiler how to authorize `/broadcast/v1/ws-ticket` and what scope to stamp into the short-lived websocket ticket:
|
|
221
221
|
|
|
@@ -70,14 +70,19 @@ update: { access: { roles: ["member", "admin", "owner"] }, routes: false },
|
|
|
70
70
|
One blessed path — **RFC 5789 media-type dispatch** on the routes you already
|
|
71
71
|
have. No subpath.
|
|
72
72
|
|
|
73
|
-
|
|
73
|
+
Paths below use the default `/api/v1` prefix. Changesets are a contract-v2
|
|
74
|
+
**semantics** feature and v2 is the default, so they are available without
|
|
75
|
+
moving your URLs — set [`contract.routes`](/platform/api-contract#two-axes-semantics-and-routes)
|
|
76
|
+
to `"v2"` only if you also want the `/api/v2` prefix.
|
|
77
|
+
|
|
78
|
+
- `PATCH /api/v1/<resource>/:id` with
|
|
74
79
|
`Content-Type: application/vnd.quickback.changeset+json` — apply a changeset
|
|
75
80
|
to an existing root. Plain `application/json` keeps the flat-column PATCH.
|
|
76
|
-
- `POST /api/
|
|
81
|
+
- `POST /api/v1/<resource>` with the same media type — create the root and its
|
|
77
82
|
children in one changeset.
|
|
78
83
|
|
|
79
84
|
```jsonc
|
|
80
|
-
// PATCH /api/
|
|
85
|
+
// PATCH /api/v1/projects/prj_1 (Content-Type: application/vnd.quickback.changeset+json)
|
|
81
86
|
{
|
|
82
87
|
"patch": { "name": "Renamed" }, // sparse ROOT patch (optional)
|
|
83
88
|
"tasks": {
|
|
@@ -49,9 +49,11 @@ auth: {
|
|
|
49
49
|
},
|
|
50
50
|
```
|
|
51
51
|
|
|
52
|
-
> **
|
|
52
|
+
> **This surface is opt-in by default**
|
|
53
53
|
>
|
|
54
|
-
>
|
|
54
|
+
> Contract v2 is the default since v0.64.0, and on it the custom JWT surface is emitted only when `auth.jwt` is present. Omit it and the generated output has no token endpoint and no JWT fast-path — cookie and signed session-token bearer auth still work. Pin `contract: { version: "v1" }` to get it unconditionally. See [Auth & JWT config](/configure/auth).
|
|
55
|
+
>
|
|
56
|
+
> `src/lib/jwt.ts` is still emitted when the project declares [`authz.scopes`](/define/scopes): scope tokens are signed JWTs, so the helper is required for minting and verifying them even with no credential lane.
|
|
55
57
|
|
|
56
58
|
|
|
57
59
|
---
|
|
@@ -79,7 +79,7 @@ providers: {
|
|
|
79
79
|
}
|
|
80
80
|
```
|
|
81
81
|
|
|
82
|
-
That tells `/broadcast/v1/ws-ticket` (the broadcast surface tracks `contract.
|
|
82
|
+
That tells `/broadcast/v1/ws-ticket` (the broadcast surface tracks `contract.routes`, so `/broadcast/v2/ws-ticket` when that is `"v2"`) to authenticate with Better Auth, run the declared gate against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` lane. See [Realtime → Enabling Realtime](/platform/realtime#enabling-realtime) for the full per-arm semantics; all three forms fail closed at compile time (ambiguous names living in two vocabularies, missing `auth.roleHierarchy` for `+`, missing `authz.fga`, unknown FGA type/relation, missing organization column, non-tenant-scoped `scopeTable`).
|
|
83
83
|
|
|
84
84
|
### Namespace-backed tickets (per-matched-lane)
|
|
85
85
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Quickback ships **two parallel realtime primitives**, both backed by Cloudflare Durable Objects:
|
|
4
4
|
|
|
5
|
-
- **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.
|
|
5
|
+
- **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.routes` — set it to `"v2"` and the same surface mounts at `/broadcast/v2` (no hidden v1 alias). `contract.version` selects the frame FORMAT, not the path: on v2 semantics (the default) frames are [CloudEvents 1.0](/platform/api-contract#contract-version-matrix) envelopes regardless of which prefix you serve them on. Documented on this page. For **typed, targeted "this changed — refresh" signals** fired from an action after commit (with optional per-recipient narrowing), see [Named invalidations](/platform/realtime/named-invalidations).
|
|
6
6
|
- **`/realtime/<binding>/<room-id>` — bidirectional rooms.** One DO instance per room (per document, per interview, per game). Client↔client messages, presence, and CRDT-friendly state. Use these for collaborative editing. See [PartyServer rooms](/platform/realtime/partyserver-rooms).
|
|
7
7
|
|
|
8
8
|
Both share the same auth model and ride on the same compiled worker; they solve different problems.
|
|
@@ -157,7 +157,7 @@ function PersonDetail({ personId }: { personId: string }) {
|
|
|
157
157
|
Under the hood `useView` uses a **subscribe-then-snapshot** flow so no change
|
|
158
158
|
slips through the gap between reading the surface and the socket going live:
|
|
159
159
|
|
|
160
|
-
1. Requests a **view-scoped ws-ticket** (`POST /broadcast/v1/ws-ticket` — `/broadcast/v2/ws-ticket`
|
|
160
|
+
1. Requests a **view-scoped ws-ticket** (`POST /broadcast/v1/ws-ticket` — `/broadcast/v2/ws-ticket` when `contract.routes` is `"v2"` — with
|
|
161
161
|
`{ view, rootId }`) — gated by exactly the same `read.access` + firewall
|
|
162
162
|
checks as the read endpoint — and opens a WebSocket scoped to
|
|
163
163
|
`view:<view>:<rootId>`.
|
|
@@ -125,7 +125,7 @@ Each `invalidate.<binding>.<variant>(payload)` call queues **one** after-commit
|
|
|
125
125
|
|
|
126
126
|
## The wire frame
|
|
127
127
|
|
|
128
|
-
Clients receive a broadcast frame on `/broadcast/v{n}` (the
|
|
128
|
+
Clients receive a broadcast frame on `/broadcast/v{n}` (the segment tracks `contract.routes`):
|
|
129
129
|
|
|
130
130
|
```jsonc
|
|
131
131
|
{
|
|
@@ -8,7 +8,7 @@ Open a WebSocket connection to the realtime worker:
|
|
|
8
8
|
|
|
9
9
|
```typescript
|
|
10
10
|
const ws = new WebSocket("wss://api.yourdomain.com/broadcast/v1/websocket");
|
|
11
|
-
// Note: /broadcast/v1 tracks contract.
|
|
11
|
+
// Note: /broadcast/v1 tracks contract.routes — use /broadcast/v2 when that is "v2".
|
|
12
12
|
```
|
|
13
13
|
|
|
14
14
|
## Authentication
|
|
@@ -377,8 +377,9 @@ For each feature, the compiler generates a routes file at `src/features/{name}/r
|
|
|
377
377
|
| `POST /:id/{action}` | Record-based actions defined |
|
|
378
378
|
| `POST /{action}` | Standalone actions defined |
|
|
379
379
|
|
|
380
|
-
Routes are mounted under `/api/v1/{feature}`
|
|
381
|
-
`/api/v2/{feature}` when `contract: {
|
|
380
|
+
Routes are mounted under `/api/v1/{feature}` by default, or
|
|
381
|
+
`/api/v2/{feature}` when `contract: { routes: "v2" }` is set. `contract.version`
|
|
382
|
+
selects semantics and leaves these paths alone.
|
|
382
383
|
|
|
383
384
|
## Migrations
|
|
384
385
|
|
|
@@ -105,7 +105,7 @@ interface ListResult {
|
|
|
105
105
|
The client is constructed once from the resolved `apiUrl` and provided via React
|
|
106
106
|
context (`ApiClientContext`), available throughout the component tree. It reads
|
|
107
107
|
the Better Auth session cookie and calls the standard REST endpoints
|
|
108
|
-
(`/api/v1/{table}`, or `/api/v2/…`
|
|
108
|
+
(`/api/v1/{table}`, or `/api/v2/…` when `contract.routes` is `"v2"`).
|
|
109
109
|
|
|
110
110
|
## Embedded Mode (Recommended)
|
|
111
111
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.64.
|
|
3
|
+
"version": "0.64.1",
|
|
4
4
|
"description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
|
|
5
5
|
"author": "Kardoe Incorporated <paul@kardoe.com>",
|
|
6
6
|
"license": "MIT",
|
|
@@ -24,12 +24,14 @@ Lowest-to-highest privilege list. Lets access rules use `'role+'` shorthand to m
|
|
|
24
24
|
|
|
25
25
|
Quickback ships its own custom HMAC-SHA256 JWT (not Better Auth's JWT plugin) so it can embed `orgId` and `role` claims the fast-path needs to reconstruct `AppContext` without a database round-trip. The signing secret is shared with Better Auth (`BETTER_AUTH_SECRET`) by default — users only manage one secret.
|
|
26
26
|
|
|
27
|
-
> **
|
|
27
|
+
> **This JWT surface is opt-in by default**
|
|
28
28
|
>
|
|
29
|
-
>
|
|
30
|
-
> when `auth.jwt` is present. If it is omitted, generated output
|
|
31
|
-
> `/api/
|
|
32
|
-
>
|
|
29
|
+
> Contract v2 is the default since v0.64.0, and on it Quickback emits this custom
|
|
30
|
+
> JWT surface only when `auth.jwt` is present. If it is omitted, generated output
|
|
31
|
+
> has no generic `/api/v1/token` endpoint, no JWT middleware verify/mint
|
|
32
|
+
> fast-path, and no Quickback JWT imports. (`src/lib/jwt.ts` is still emitted when
|
|
33
|
+
> the project declares [`authz.scopes`](/define/scopes) — scope tokens are signed
|
|
34
|
+
> JWTs.) Pin `contract: { version: "v1" }` to emit it unconditionally. Generated `llms.txt` and RFC 8414 discovery metadata
|
|
33
35
|
> also omit Bearer-JWT instructions, token endpoints, and JWT scopes that do not
|
|
34
36
|
> exist. Better Auth cookie and signed session-token bearer authentication remain
|
|
35
37
|
> available.
|
|
@@ -499,12 +499,13 @@ A modern Quickback project runs on **one Cloudflare Worker** that serves multipl
|
|
|
499
499
|
|
|
500
500
|
When any subdomain is configured (`account.domain`, `cms.domain`, `auth.domain`, `api.domain`, `apps.<n>.domain`), the compiler always emits a unified backend host where **every compiler-emitted backend route** is reachable:
|
|
501
501
|
|
|
502
|
-
- `/api/v1/*` and `/auth/v1/*`
|
|
503
|
-
|
|
502
|
+
- `/api/v1/*` and `/auth/v1/*` by default, or `/api/v2/*` and `/auth/v2/*`
|
|
503
|
+
when `contract.routes` is `"v2"` (the URL axis — `contract.version` does
|
|
504
|
+
not move these)
|
|
504
505
|
- `/storage/*` — R2 file storage
|
|
505
506
|
- `/health`, `/openapi.json` — monitoring/discovery
|
|
506
507
|
- `/account/*`, `/cms/*` — bundled SPAs (when enabled)
|
|
507
|
-
- `/broadcast/v1/*` (realtime; `/broadcast/v2/*` under `contract.
|
|
508
|
+
- `/broadcast/v1/*` (realtime; `/broadcast/v2/*` under `contract.routes: 'v2'`), `/mcp` (MCP), etc.
|
|
508
509
|
|
|
509
510
|
The unified hostname is `quickback.{baseDomain}` by default (where baseDomain is extracted from your first configured subdomain). Override with `config.domain` if you prefer a different name.
|
|
510
511
|
|
|
@@ -215,7 +215,7 @@ providers: {
|
|
|
215
215
|
}
|
|
216
216
|
```
|
|
217
217
|
|
|
218
|
-
> The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.
|
|
218
|
+
> The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.routes: "v2"`. It tracks the URL axis, not `contract.version`.
|
|
219
219
|
|
|
220
220
|
`wsTicket` tells the compiler how to authorize `/broadcast/v1/ws-ticket` and what scope to stamp into the short-lived websocket ticket:
|
|
221
221
|
|
|
@@ -70,14 +70,19 @@ update: { access: { roles: ["member", "admin", "owner"] }, routes: false },
|
|
|
70
70
|
One blessed path — **RFC 5789 media-type dispatch** on the routes you already
|
|
71
71
|
have. No subpath.
|
|
72
72
|
|
|
73
|
-
|
|
73
|
+
Paths below use the default `/api/v1` prefix. Changesets are a contract-v2
|
|
74
|
+
**semantics** feature and v2 is the default, so they are available without
|
|
75
|
+
moving your URLs — set [`contract.routes`](/platform/api-contract#two-axes-semantics-and-routes)
|
|
76
|
+
to `"v2"` only if you also want the `/api/v2` prefix.
|
|
77
|
+
|
|
78
|
+
- `PATCH /api/v1/<resource>/:id` with
|
|
74
79
|
`Content-Type: application/vnd.quickback.changeset+json` — apply a changeset
|
|
75
80
|
to an existing root. Plain `application/json` keeps the flat-column PATCH.
|
|
76
|
-
- `POST /api/
|
|
81
|
+
- `POST /api/v1/<resource>` with the same media type — create the root and its
|
|
77
82
|
children in one changeset.
|
|
78
83
|
|
|
79
84
|
```jsonc
|
|
80
|
-
// PATCH /api/
|
|
85
|
+
// PATCH /api/v1/projects/prj_1 (Content-Type: application/vnd.quickback.changeset+json)
|
|
81
86
|
{
|
|
82
87
|
"patch": { "name": "Renamed" }, // sparse ROOT patch (optional)
|
|
83
88
|
"tasks": {
|
|
@@ -49,9 +49,11 @@ auth: {
|
|
|
49
49
|
},
|
|
50
50
|
```
|
|
51
51
|
|
|
52
|
-
> **
|
|
52
|
+
> **This surface is opt-in by default**
|
|
53
53
|
>
|
|
54
|
-
>
|
|
54
|
+
> Contract v2 is the default since v0.64.0, and on it the custom JWT surface is emitted only when `auth.jwt` is present. Omit it and the generated output has no token endpoint and no JWT fast-path — cookie and signed session-token bearer auth still work. Pin `contract: { version: "v1" }` to get it unconditionally. See [Auth & JWT config](/configure/auth).
|
|
55
|
+
>
|
|
56
|
+
> `src/lib/jwt.ts` is still emitted when the project declares [`authz.scopes`](/define/scopes): scope tokens are signed JWTs, so the helper is required for minting and verifying them even with no credential lane.
|
|
55
57
|
|
|
56
58
|
|
|
57
59
|
---
|
|
@@ -79,7 +79,7 @@ providers: {
|
|
|
79
79
|
}
|
|
80
80
|
```
|
|
81
81
|
|
|
82
|
-
That tells `/broadcast/v1/ws-ticket` (the broadcast surface tracks `contract.
|
|
82
|
+
That tells `/broadcast/v1/ws-ticket` (the broadcast surface tracks `contract.routes`, so `/broadcast/v2/ws-ticket` when that is `"v2"`) to authenticate with Better Auth, run the declared gate against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` lane. See [Realtime → Enabling Realtime](/platform/realtime#enabling-realtime) for the full per-arm semantics; all three forms fail closed at compile time (ambiguous names living in two vocabularies, missing `auth.roleHierarchy` for `+`, missing `authz.fga`, unknown FGA type/relation, missing organization column, non-tenant-scoped `scopeTable`).
|
|
83
83
|
|
|
84
84
|
### Namespace-backed tickets (per-matched-lane)
|
|
85
85
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Quickback ships **two parallel realtime primitives**, both backed by Cloudflare Durable Objects:
|
|
4
4
|
|
|
5
|
-
- **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.
|
|
5
|
+
- **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.routes` — set it to `"v2"` and the same surface mounts at `/broadcast/v2` (no hidden v1 alias). `contract.version` selects the frame FORMAT, not the path: on v2 semantics (the default) frames are [CloudEvents 1.0](/platform/api-contract#contract-version-matrix) envelopes regardless of which prefix you serve them on. Documented on this page. For **typed, targeted "this changed — refresh" signals** fired from an action after commit (with optional per-recipient narrowing), see [Named invalidations](/platform/realtime/named-invalidations).
|
|
6
6
|
- **`/realtime/<binding>/<room-id>` — bidirectional rooms.** One DO instance per room (per document, per interview, per game). Client↔client messages, presence, and CRDT-friendly state. Use these for collaborative editing. See [PartyServer rooms](/platform/realtime/partyserver-rooms).
|
|
7
7
|
|
|
8
8
|
Both share the same auth model and ride on the same compiled worker; they solve different problems.
|
|
@@ -157,7 +157,7 @@ function PersonDetail({ personId }: { personId: string }) {
|
|
|
157
157
|
Under the hood `useView` uses a **subscribe-then-snapshot** flow so no change
|
|
158
158
|
slips through the gap between reading the surface and the socket going live:
|
|
159
159
|
|
|
160
|
-
1. Requests a **view-scoped ws-ticket** (`POST /broadcast/v1/ws-ticket` — `/broadcast/v2/ws-ticket`
|
|
160
|
+
1. Requests a **view-scoped ws-ticket** (`POST /broadcast/v1/ws-ticket` — `/broadcast/v2/ws-ticket` when `contract.routes` is `"v2"` — with
|
|
161
161
|
`{ view, rootId }`) — gated by exactly the same `read.access` + firewall
|
|
162
162
|
checks as the read endpoint — and opens a WebSocket scoped to
|
|
163
163
|
`view:<view>:<rootId>`.
|
|
@@ -125,7 +125,7 @@ Each `invalidate.<binding>.<variant>(payload)` call queues **one** after-commit
|
|
|
125
125
|
|
|
126
126
|
## The wire frame
|
|
127
127
|
|
|
128
|
-
Clients receive a broadcast frame on `/broadcast/v{n}` (the
|
|
128
|
+
Clients receive a broadcast frame on `/broadcast/v{n}` (the segment tracks `contract.routes`):
|
|
129
129
|
|
|
130
130
|
```jsonc
|
|
131
131
|
{
|
|
@@ -8,7 +8,7 @@ Open a WebSocket connection to the realtime worker:
|
|
|
8
8
|
|
|
9
9
|
```typescript
|
|
10
10
|
const ws = new WebSocket("wss://api.yourdomain.com/broadcast/v1/websocket");
|
|
11
|
-
// Note: /broadcast/v1 tracks contract.
|
|
11
|
+
// Note: /broadcast/v1 tracks contract.routes — use /broadcast/v2 when that is "v2".
|
|
12
12
|
```
|
|
13
13
|
|
|
14
14
|
## Authentication
|
|
@@ -377,8 +377,9 @@ For each feature, the compiler generates a routes file at `src/features/{name}/r
|
|
|
377
377
|
| `POST /:id/{action}` | Record-based actions defined |
|
|
378
378
|
| `POST /{action}` | Standalone actions defined |
|
|
379
379
|
|
|
380
|
-
Routes are mounted under `/api/v1/{feature}`
|
|
381
|
-
`/api/v2/{feature}` when `contract: {
|
|
380
|
+
Routes are mounted under `/api/v1/{feature}` by default, or
|
|
381
|
+
`/api/v2/{feature}` when `contract: { routes: "v2" }` is set. `contract.version`
|
|
382
|
+
selects semantics and leaves these paths alone.
|
|
382
383
|
|
|
383
384
|
## Migrations
|
|
384
385
|
|
|
@@ -105,7 +105,7 @@ interface ListResult {
|
|
|
105
105
|
The client is constructed once from the resolved `apiUrl` and provided via React
|
|
106
106
|
context (`ApiClientContext`), available throughout the component tree. It reads
|
|
107
107
|
the Better Auth session cookie and calls the standard REST endpoints
|
|
108
|
-
(`/api/v1/{table}`, or `/api/v2/…`
|
|
108
|
+
(`/api/v1/{table}`, or `/api/v2/…` when `contract.routes` is `"v2"`).
|
|
109
109
|
|
|
110
110
|
## Embedded Mode (Recommended)
|
|
111
111
|
|