@quickback-dev/cli 0.48.0 → 0.48.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.
Files changed (31) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +13 -2
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/commands/migrations.d.ts +10 -0
  5. package/dist/commands/migrations.d.ts.map +1 -1
  6. package/dist/commands/migrations.js +113 -79
  7. package/dist/commands/migrations.js.map +1 -1
  8. package/dist/commands/migrations.test.js +96 -1
  9. package/dist/commands/migrations.test.js.map +1 -1
  10. package/dist/docs/content.js +9 -9
  11. package/dist/docs/content.js.map +1 -1
  12. package/dist/index.js +1 -1
  13. package/dist/skill/docs/changelog.md +84 -0
  14. package/dist/skill/docs/compiler/config/providers.md +23 -2
  15. package/dist/skill/docs/compiler/definitions/actions.md +12 -2
  16. package/dist/skill/docs/compiler/definitions/encryption.md +2 -0
  17. package/dist/skill/docs/compiler/definitions/schema.md +2 -0
  18. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +306 -35
  19. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +14 -8
  20. package/dist/skill/docs/stack/realtime/durable-objects.md +143 -4
  21. package/dist/skill/docs/stack/webhooks/outbound.md +23 -0
  22. package/package.json +1 -1
  23. package/src/skill/docs/changelog.md +84 -0
  24. package/src/skill/docs/compiler/config/providers.md +23 -2
  25. package/src/skill/docs/compiler/definitions/actions.md +12 -2
  26. package/src/skill/docs/compiler/definitions/encryption.md +2 -0
  27. package/src/skill/docs/compiler/definitions/schema.md +2 -0
  28. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +306 -35
  29. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +14 -8
  30. package/src/skill/docs/stack/realtime/durable-objects.md +143 -4
  31. package/src/skill/docs/stack/webhooks/outbound.md +23 -0
@@ -245,9 +245,16 @@ await realtime.broadcast('screening-complete', {
245
245
  applicationId: 'app_123',
246
246
  candidateId: 'cnd_456',
247
247
  stage: 'interview'
248
- }, ctx.activeOrgId!);
248
+ }, ctx.activeOrgId!, {
249
+ targetRoles: ['AUTHENTICATED'],
250
+ });
249
251
  ```
250
252
 
253
+ **Every send needs an audience.** Delivery is fail-closed: a broadcast whose
254
+ `targetRoles` is omitted or empty reaches **nobody**. "Everyone in the room" is
255
+ spelled explicitly — `targetRoles: ['AUTHENTICATED']` (any authenticated
256
+ subscriber) or `['PUBLIC']`.
257
+
251
258
  Broadcasts:
252
259
  ```json
253
260
  {
@@ -268,7 +275,8 @@ Target a specific user instead of the entire organization:
268
275
  ```typescript
269
276
  // Only this user receives the notification
270
277
  await realtime.insert('notifications', newNotification, ctx.activeOrgId!, {
271
- userId: ctx.userId
278
+ userId: ctx.userId,
279
+ targetRoles: ['AUTHENTICATED'],
272
280
  });
273
281
 
274
282
  // Notify a hiring manager of a new application
@@ -276,10 +284,16 @@ await realtime.broadcast('application-received', {
276
284
  applicationId: 'app_123',
277
285
  jobId: 'job_789'
278
286
  }, ctx.activeOrgId!, {
279
- userId: hiringManagerId
287
+ userId: hiringManagerId,
288
+ targetRoles: ['AUTHENTICATED'],
280
289
  });
281
290
  ```
282
291
 
292
+ `userId` targeting matches the **socket identity** — the Better Auth user id, or
293
+ the synthetic `scope:<subjectId>` principal for sessionless scope connections. If
294
+ the same person can connect through either door, prefer
295
+ [identity-tag targeting](#identity-tag-targeting) — one send reaches both.
296
+
283
297
  ## Role-Based Filtering
284
298
 
285
299
  Limit which roles receive a broadcast using `targetRoles`:
@@ -296,7 +310,132 @@ await realtime.update('applications', newRecord, oldRecord, ctx.activeOrgId!, {
296
310
  });
297
311
  ```
298
312
 
299
- If `targetRoles` is not specified, all authenticated subscribers in the chosen scope receive the broadcast.
313
+ **Fail-closed (v0.48+):** an omitted or empty `targetRoles` delivers to
314
+ **nobody** — there is no implicit "everyone" fallback. To reach every
315
+ authenticated subscriber in the scope, say so explicitly with
316
+ `targetRoles: ['AUTHENTICATED']`. UPPERCASE pseudo-roles (`PUBLIC`,
317
+ `AUTHENTICATED`, `USER`, `SYSADMIN`) are evaluated exactly as the REST access
318
+ evaluator does.
319
+
320
+ > **Migrating from pre-0.48:** custom `realtime.broadcast(...)` /
321
+ > `realtime.insert(...)` calls that omitted `targetRoles` used to fan out to
322
+ > everyone; they now silently deliver to nobody. Audit every manual send and add
323
+ > an explicit audience.
324
+
325
+ ## Identity-Tag Targeting
326
+
327
+ Every connection carries **identity tags**, proven at ticket mint and signed
328
+ into the ticket (never client-supplied):
329
+
330
+ - `user:<userId>` — every Better Auth caller
331
+ - `scope:<kind>:<subjectId>` — when a scope subject is proven, on **either**
332
+ door: a sessionless scope principal's verified claim, or a Better Auth caller
333
+ whose matched relationship lane maps to a scope kind with
334
+ `subject: 'supplied' | 'both'`. Both doors stamp the **identical** tag (the
335
+ subject row's id), which is the point.
336
+
337
+ Target them with `targetTags`:
338
+
339
+ ```typescript
340
+ // ONE send reaches this guest whether they're connected via their Better Auth
341
+ // session or a sessionless scope link — no per-identity double-send.
342
+ await realtime.broadcast('chat.frame', payload, { scopeKey }, {
343
+ targetTags: [`scope:guest:${guestId}`],
344
+ targetRoles: ['AUTHENTICATED'],
345
+ });
346
+
347
+ // Reach a person under either identity explicitly (deduped per socket):
348
+ await realtime.broadcast('rsvp.updated', payload, { scopeKey }, {
349
+ targetTags: [`scope:guest:${guestId}`, `user:${linkedUserId}`],
350
+ targetRoles: ['AUTHENTICATED'],
351
+ });
352
+ ```
353
+
354
+ Semantics:
355
+
356
+ - Delivery is the **deduplicated union** of the runtime's indexed tag lookup
357
+ (`getWebSockets(tag)`) — no attachment scan, and a dual-identity socket
358
+ matches once.
359
+ - `targetTags` **replaces the `userId` identity arm** when present; the
360
+ scope/org bind and the `targetRoles` audience still apply on top.
361
+ - **Fail-closed:** `targetTags: []` delivers to nobody.
362
+ - Tags are **immutable** for a socket's lifetime (a Workers hibernation-tag
363
+ constraint) — an identity change requires a reconnect.
364
+ - Limits: at most 10 tags per connection, 256 characters per tag. The mint
365
+ rejects violations; it never truncates.
366
+
367
+ ## Authorization Lease
368
+
369
+ The 60-second ws-ticket is verified once, at upgrade — but Durable Object
370
+ hibernation keeps sockets alive indefinitely. Without a lease, a ban, member
371
+ removal, or subject revocation (say, an organizer cancelling a guest) would
372
+ never affect an already-connected socket. The lease closes that gap:
373
+
374
+ - At upgrade, the connection stores `authExpiresAt = ticket.iat + lease`
375
+ (default **15 minutes**).
376
+ - The fan-out **skips expired connections** — they receive nothing — and closes
377
+ them with code **4401** so the client knows to re-ticket rather than blindly
378
+ reconnect. Inbound messages (even pings) are enforced the same way.
379
+ - Renewal happens at mint: `POST /broadcast/v1/ws-ticket` re-runs the full
380
+ authorization gate (session validity, revocation checks, relationship /
381
+ scope-claim probes), so a revoked principal simply can't obtain a renewal
382
+ ticket. Revocation propagates within one lease period with no polling.
383
+
384
+ Configure it on the realtime transport:
385
+
386
+ ```typescript
387
+ providers: {
388
+ database: {
389
+ config: {
390
+ realtime: {
391
+ enabled: true,
392
+ lease: '15m', // default; also '900s', '1h', or a number of seconds
393
+ // lease: false // disable (discouraged — reopens the revocation gap)
394
+ },
395
+ },
396
+ },
397
+ }
398
+ ```
399
+
400
+ The lease must be at least 60 seconds (the handshake-ticket TTL).
401
+
402
+ ### In-place renewal (`reauth`)
403
+
404
+ Instead of reconnecting every lease period, a client can renew in place: mint a
405
+ fresh ticket and send it over the open socket.
406
+
407
+ ```typescript
408
+ // On a timer comfortably inside the lease (e.g. every 10 min for a 15m lease):
409
+ const { wsTicket } = await mintTicket(); // POST /broadcast/v1/ws-ticket
410
+ ws.send(JSON.stringify({ type: 'reauth', ticket: wsTicket }));
411
+
412
+ ws.onmessage = (event) => {
413
+ const msg = JSON.parse(event.data);
414
+ if (msg.type === 'reauth_ok') {
415
+ scheduleNextRenewal(msg.authExpiresAt); // lease extended, roles refreshed
416
+ }
417
+ if (msg.type === 'error' && msg.code === 'REAUTH_FAILED') {
418
+ // Ticket invalid/expired — mint a fresh one and retry before the lease lapses.
419
+ }
420
+ };
421
+
422
+ ws.onclose = (event) => {
423
+ if (event.code === 4401) {
424
+ // Lease expired or identity drift: mint a fresh ticket and reconnect.
425
+ reconnectWithFreshTicket();
426
+ }
427
+ };
428
+ ```
429
+
430
+ Renewal is **strict**: the fresh ticket must carry the same `userId`,
431
+ `scopeKey`/`organizationId`, and the **exact same tag set** as the live socket
432
+ (tags are immutable). A renewal that matches extends the lease and refreshes
433
+ `role`/`roles` in place — live permission changes without socket churn. One
434
+ that doesn't closes the socket with 4401: reconnect fresh.
435
+
436
+ Clients that never send `reauth` still work — their socket is closed with 4401
437
+ once per lease and normal reconnect logic (with a fresh ticket) re-runs the
438
+ full gate. The lease is the server-side invariant either way.
300
439
 
301
440
  ## Per-Role Field Masking
302
441
 
@@ -275,6 +275,29 @@ database: defineDatabase("cloudflare-d1", {
275
275
 
276
276
  This generates the webhook database schema, routes, queue consumer, and all supporting code.
277
277
 
278
+ ### On Neon (Postgres)
279
+
280
+ Webhooks are supported on the `neon` provider too. `webhooksBinding` acts as a
281
+ pure enable flag — there is no separate webhooks database. The webhook tables
282
+ live in a dedicated `webhooks` Postgres schema of your single Neon database,
283
+ created by the standard drizzle migration set, and are locked down by an RLS
284
+ policy so only the Worker's internal service-role handle can touch them:
285
+
286
+ ```typescript
287
+ database: defineDatabase("neon", {
288
+ connectionMode: "http", // required for webhooks
289
+ webhooksBinding: "WEBHOOKS_DB", // enable flag; no D1 binding is emitted
290
+ // queue names stay configurable on any provider:
291
+ webhooksQueueName: "my-app-webhooks-queue",
292
+ webhooksDlqName: "my-app-webhooks-dlq",
293
+ })
294
+ ```
295
+
296
+ The D1-only keys `webhooksDatabaseId` / `webhooksDatabaseName` are rejected at
297
+ compile time on Neon, and webhooks require `connectionMode: 'http'` (the
298
+ Cloudflare default). Queue wiring (`WEBHOOKS_QUEUE`, the consumer, and the
299
+ dead letter queue) is identical across providers.
300
+
278
301
  ## See Also
279
302
 
280
303
  - [Inbound Webhooks](/stack/webhooks/inbound) — Receive webhooks from external services