@beignet/core 0.0.53 → 0.0.55

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @beignet/core
 
+## 0.0.55
+
+### Patch Changes
+
+- a3085a6: Allow broadcast connections to configure lifetimes up to one hour while keeping
+  the 60-second default. Browser clients honor the server's advertised lifetime
+  with bounded watchdog grace, preserve heartbeat timeouts, and reconcile on
+  renewal. Align CLI diagnostics and hosting guidance with configurable lifetimes.
+- a3085a6: Coordinate broadcast refreshes with matching pending mutations or custom write
+  gates. Add connection admission with automatic resource cleanup, and expose
+  connection/reconciliation reasons. Keep the 60-second default, require valid
+  lifetime metadata, and use explicit connection-wide renewal control frames.
+
+## 0.0.54
+
+### Patch Changes
+
+- b71b34f: Add typed, authorized browser broadcasting with bounded SSE connections, memory
+  and Redis providers, reconnect reconciliation, React Query invalidation,
+  initiating-client exclusion, notification delivery, and transactional inbox
+  scaffolding. Raw routes now preserve context added by route hooks.
+
 ## 0.0.53
 
 ### Patch Changes

package/README.md

@@ -11,7 +11,7 @@
 This package provides Beignet's framework primitives: contracts, server runtime,
 typed client, use cases, agent capabilities, ports, domain helpers, app errors, config, events,
 idempotency, locks, outbox, mail, notifications, payments, search, webhooks,
-feature flags, error reporting, encryption, schedules, uploads, entitlements, pagination
+feature flags, error reporting, encryption, broadcasting, schedules, uploads, entitlements, pagination
 helpers, testing helpers, and OpenAPI generation.
 
 ## Installation
@@ -50,6 +50,9 @@ name the framework area they depend on.
 | --- | --- |
 | `@beignet/core/agent-capabilities` | Typed agent capability definitions, registries, validation, and execution |
 | `@beignet/core/application` | Use case builder and test helpers |
+| `@beignet/core/broadcasting` | Browser-safe typed channel definitions and transport validation |
+| `@beignet/core/broadcasting/server` | BroadcastPort, authorization bindings, registry, and authenticated origins |
+| `@beignet/core/broadcasting/client` | Multiplexed streaming browser client with reconnect reconciliation |
 | `@beignet/core/client` | Typed HTTP client |
 | `@beignet/core/client-only` | Static lint marker for modules intended for client-side imports |
 | `@beignet/core/config` | Environment config validation |
@@ -1176,7 +1179,7 @@ contracts should stay on explicit paths; catch-all contract patterns such as
 For routes that cannot be contracts at all — third-party callback endpoints
 with externally defined request shapes, signature-verified webhooks,
 streaming endpoints that own body consumption —
-`server.rawRoute({ name, method, path, metadata }).handle(fn)` builds a
+`server.rawRoute({ name, method, path, metadata, hooks }).handle(fn)` builds a
 handler that still runs the whole pipeline (hooks, context creation,
 instrumentation, framework error mapping) without contract parsing or
 validation. The request body stays unconsumed for the handler, `metadata`
@@ -2743,6 +2746,118 @@ field requiredness, descriptions, and constraints.
 - [`@beignet/nuqs`](https://beignetjs.com/nuqs) - URL query state integration with nuqs
 - [`@beignet/devtools`](https://beignetjs.com/devtools) - Local request, provider, and audit timeline
 
+## Broadcasting
+
+Define browser-safe channels with `defineChannel(name, { params, events })` from
+`@beignet/core/broadcasting`. Parameters parse to flat string records; event
+schemas produce stable canonical JSON. `BroadcastValidationError` rejects
+invalid data and non-idempotent transforms.
+
+On the server, import `BroadcastPort` and `createBroadcasting<AppContext>()`
+from `@beignet/core/broadcasting/server`. Its `defineChannelBinding` requires an
+explicit authorization callback for every channel, and `defineChannelRegistry`
+rejects duplicate names. Use memory or Redis providers and expose the registry
+with `createBroadcastRoute` from `@beignet/web` or `@beignet/next`.
+
+```ts
+import { defineChannel } from "@beignet/core/broadcasting";
+import { z } from "zod";
+
+export const changes = defineChannel("issues.changes", {
+  params: z.object({ workspaceId: z.string() }),
+  events: { changed: z.object({ issueId: z.string() }) },
+});
+```
+
+`broadcast.publish(changes, { params, event: "changed", data })` resolves on
+provider acceptance. `broadcast.subscribe(changes, { params, onEvent,
+onDisconnect })` returns `{ ready, unsubscribe }`; await readiness and cleanup.
+Publish after commit, or record a publication job in the transaction's outbox
+when the attempt must be retryable. Browser delivery is ephemeral.
+
+`createBroadcastClient({ url, headers?, credentials?, fetch? })` from
+`@beignet/core/broadcasting/client` shares one streaming Fetch connection.
+Subscribe with `{ params, onEvent, onSync, onError?, onStatusChange? }` and use
+`onSync` to refetch after initial readiness and recovery. Each subscription
+exposes `unsubscribe()` and `getStatus()`. The client also exposes `getStatus()`,
+`resume()`, `close()`, and `getRequestHeaders()` for opt-in origin exclusion.
+Create a fresh client on user/workspace changes. Callbacks that already started
+remain application-owned work after unsubscribe.
+
+`resolveBroadcastOrigin({ headers, principalId, tenantId, namespace })` binds
+the optional client header to authenticated server identity. Forward a captured
+origin through a job as `broadcastOrigin`, validate with `broadcastOriginSchema`
+when using Standard Schema directly, and pass it as `excludeOrigin` to publish.
+Use the same resolver on the stream endpoint. Missing, malformed, or anonymous
+origins disable exclusion. Default redaction hides origin headers and fields.
+
+`defineBroadcastNotificationChannel({ channel, render })` from
+`@beignet/core/notifications` publishes rendered notifications through the port;
+return `undefined` to skip. Existing preferences and per-channel retries apply.
+A sent result means provider acceptance. Persistent inbox writes and their
+publication jobs must share an app-owned transaction; independent notification
+channels have no execution ordering guarantee.
+
+The browser protocol has no replay IDs. Limits are 20 subscriptions, an 8 KiB
+encoded request, 64 KiB event data, 1 MiB buffers, 25-second heartbeats,
+10-second readiness waits, and a default stream lifetime of 60 seconds.
+`createBroadcastRoute` in `@beignet/next` or `@beignet/web` accepts
+`maxLifetimeMs` as a positive safe integer up to `3_600_000` (one hour), including
+`240_000` for four-minute streams. Leave setup/cleanup headroom below your
+hosting request deadline. Longer streams reduce renewal/refetch frequency and
+increase the interval between authorization checks.
+
+The client honors the lifetime advertised in the first readiness message,
+with five seconds of watchdog grace measured from streaming response receipt.
+Additional readiness messages and heartbeats never extend the connection
+deadline. Every readiness message must include a valid `maxLifetimeMs`;
+missing or invalid lifetimes block subscriptions. Heartbeat loss closes a stream
+after 55 seconds without data, independently of its lifetime. Planned renewals still invoke `onSync`
+because events can be missed during reconnection. Terminal 4xx
+responses block until explicit resume; 429/5xx retry with jitter and respect
+`Retry-After`. Retry deadlines survive subscription changes. See the
+[broadcasting guide](https://beignetjs.com/broadcasting).
+
+### Diagnose connection changes
+
+`onSync(info)` and `onStatusChange(status, info)` receive
+`BroadcastConnectionInfo` from `@beignet/core/broadcasting/client`. Callbacks
+may omit the metadata argument when they do not need it.
+`createBroadcastQuerySubscription` forwards status metadata and accepts an
+optional `onSync(info)` observer; its reconciliation is still scheduled even
+when that observer throws. This notification describes readiness, not completion
+of queued or gated query refreshes. Do not refetch from that observer to bypass
+the gate accidentally.
+
+| `info.reason` | What Beignet knows |
+| --- | --- |
+| `initial` | The first physical connection attempt. |
+| `planned-renewal` | The server explicitly announced renewal and then ended the stream normally without further traffic. |
+| `subscription-change` | Adding or removing a distinct channel restarted the multiplexed connection. |
+| `interruption` | A timeout, transport/protocol failure, or retryable rejection interrupted the connection. |
+| `unknown` | An unexplained EOF, explicit resume, or browser wakeup has no more precise known cause. |
+
+Readiness reports the reason for that physical connection; another observer
+joining an already-ready channel sees the same information. Reconnecting status
+reports the known reason for restarting. An elapsed lifetime alone never proves
+planned renewal. Servers send an explicit, connection-wide renewal control frame
+before closing normally. An unexplained EOF stays `unknown`. A renewal frame
+followed by a stall produces `interruption` when a watchdog fires. Further traffic
+after the frame makes a later EOF `unknown`, including an incomplete frame.
+Reconciliation continues after **every** renewal because events have no replay.
+Planned renewal is a lifecycle change, not an `onError` failure.
+
+Routes use the existing `broadcast` instrumentation watcher for admission,
+connection, and cleanup events. Server closure details report `planned-renewal`,
+`provider-disconnect`, `buffer-overflow`, `setup-failure`, or `unknown` as known
+locally; the server cannot infer why a browser cancelled. An optional
+`instrumentation` sink on `createBroadcastClient` uses the existing
+`ProviderInstrumentationPort` to record `broadcast.connecting`, `broadcast.ready`,
+and `broadcast.closed` with browser reasons. These events contain safe counts,
+durations, and reasons, never headers, credentials, payloads, or channel params.
+Keep custom logging equally restrained.
+
+
 ## License
 
 MIT

package/dist/broadcasting/client.d.ts

@@ -0,0 +1,45 @@
+import { type ProviderInstrumentationPort } from "../providers/instrumentation.js";
+import { type ChannelDefinition, type InferChannelEvent, type InferChannelParams } from "./index.js";
+export type BroadcastClientStatus = "connecting" | "connected" | "reconnecting" | "blocked" | "closed";
+/** Why this physical connection was opened, or why it is reconnecting. */
+export interface BroadcastConnectionInfo {
+    readonly reason: "initial" | "planned-renewal" | "subscription-change" | "interruption" | "unknown";
+}
+/** Safe connection/protocol failure; application callback errors are reported separately. */
+export declare class BroadcastClientError extends Error {
+    readonly retryable: boolean;
+    readonly status?: number | undefined;
+    constructor(message: string, retryable: boolean, status?: number | undefined);
+}
+export interface BroadcastClientSubscription {
+    unsubscribe(): void;
+    getStatus(): BroadcastClientStatus;
+}
+export interface BroadcastClient {
+    subscribe<C extends ChannelDefinition>(channel: C, options: {
+        params: InferChannelParams<C>;
+        onEvent: (event: InferChannelEvent<C>) => void | Promise<void>;
+        /** Refetch authoritative state after initial readiness and every recovered connection. */
+        onSync: (info: BroadcastConnectionInfo) => void | Promise<void>;
+        onError?: (error: unknown) => void;
+        onStatusChange?: (status: BroadcastClientStatus, info: BroadcastConnectionInfo) => void;
+    }): BroadcastClientSubscription;
+    /** Merge these optional headers into the app's typed HTTP client to opt into exclusion. */
+    getRequestHeaders(): Record<string, string>;
+    getStatus(): BroadcastClientStatus;
+    /** Explicit app action after credentials/access change. Renewals never unblock denied subscriptions. */
+    resume(): void;
+    close(): void;
+}
+export interface BroadcastClientOptions {
+    url: string;
+    /** Optional existing instrumentation sink; records causes and counts, never credentials or channel params. */
+    instrumentation?: ProviderInstrumentationPort;
+    /** Resolved afresh for every request. Never place credentials in the URL. */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    credentials?: RequestCredentials;
+    fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+}
+/** One multiplexed streaming Fetch connection per instance. Create an instance per app auth session. */
+export declare function createBroadcastClient(options: BroadcastClientOptions): BroadcastClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/broadcasting/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/broadcasting/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAGL,KAAK,iBAAiB,EAEtB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EAGxB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,qBAAqB,GAC7B,YAAY,GACZ,WAAW,GACX,cAAc,GACd,SAAS,GACT,QAAQ,CAAC;AAEb,0EAA0E;AAC1E,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EACX,SAAS,GACT,iBAAiB,GACjB,qBAAqB,GACrB,cAAc,GACd,SAAS,CAAC;CACf;AAED,6FAA6F;AAC7F,qBAAa,oBAAqB,SAAQ,KAAK;IAG3C,QAAQ,CAAC,SAAS,EAAE,OAAO;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;gBAFxB,OAAO,EAAE,MAAM,EACN,SAAS,EAAE,OAAO,EAClB,MAAM,CAAC,EAAE,MAAM,YAAA;CAK3B;AAED,MAAM,WAAW,2BAA2B;IAC1C,WAAW,IAAI,IAAI,CAAC;IACpB,SAAS,IAAI,qBAAqB,CAAC;CACpC;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,CAAC,SAAS,iBAAiB,EACnC,OAAO,EAAE,CAAC,EACV,OAAO,EAAE;QACP,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;QAC9B,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC/D,0FAA0F;QAC1F,MAAM,EAAE,CAAC,IAAI,EAAE,uBAAuB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAChE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;QACnC,cAAc,CAAC,EAAE,CACf,MAAM,EAAE,qBAAqB,EAC7B,IAAI,EAAE,uBAAuB,KAC1B,IAAI,CAAC;KACX,GACA,2BAA2B,CAAC;IAC/B,2FAA2F;IAC3F,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,SAAS,IAAI,qBAAqB,CAAC;IACnC,wGAAwG;IACxG,MAAM,IAAI,IAAI,CAAC;IACf,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,8GAA8G;IAC9G,eAAe,CAAC,EAAE,2BAA2B,CAAC;IAC9C,6EAA6E;IAC7E,OAAO,CAAC,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IACnE,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC7E;AA6DD,wGAAwG;AACxG,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,sBAAsB,GAC9B,eAAe,CAusBjB"}