@chidchanun/bcp 0.2.12 → 0.2.13

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 (13) hide show
  1. package/README.md +179 -224
  2. package/docs/README.md +40 -54
  3. package/docs/api-manifest.json +24 -71
  4. package/docs/api-reference.md +65 -56
  5. package/docs/docs-web-manifest.json +5 -3
  6. package/docs/platform-manifest.json +15 -4
  7. package/docs/realtime-platform.md +447 -0
  8. package/docs/releases/0.2.13.md +122 -0
  9. package/package.json +6 -1
  10. package/packages/bundler/src/client-boundary.ts +1 -0
  11. package/packages/client/src/realtime.mjs +936 -0
  12. package/packages/client/src/realtime.ts +31 -0
  13. package/packages/server/src/realtime.ts +1464 -0
package/docs/README.md CHANGED
@@ -2,14 +2,12 @@
2
2
 
3
3
  The `docs/` directory is the documentation source of truth for BCP Framework and is organized for **`bcp-docs-web`**.
4
4
 
5
- > **Documentation target:** BCP Framework `0.2.12 — Transactional Outbox & Events`
5
+ > **Documentation target:** BCP Framework `0.2.13 — Realtime Platform`
6
6
  >
7
7
  > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
8
8
 
9
9
  ## Documentation architecture
10
10
 
11
- BCP uses three machine-readable contracts:
12
-
13
11
  ```text
14
12
  docs/docs-web-manifest.json
15
13
  -> website navigation, routes, Markdown sources and release routes
@@ -40,54 +38,57 @@ Framework source and tests remain authoritative for runtime behavior.
40
38
  | `0.2.10` | Durable Jobs Platform |
41
39
  | `0.2.11` | Workflow Orchestration |
42
40
  | `0.2.12` | Transactional Outbox & Events |
41
+ | `0.2.13` | Realtime Platform |
43
42
 
44
- ## 0.2.12 — Transactional Outbox & Events
43
+ ## 0.2.13 — Realtime Platform
45
44
 
46
- `0.2.12` adds the server-only `bcp/events` public entrypoint.
45
+ `0.2.13` adds the server-only `bcp/realtime` public entrypoint.
47
46
 
48
47
  Primary APIs:
49
48
 
50
49
  ```ts
51
50
  import {
52
- createEventBus,
53
- createMemoryOutboxStore,
54
- createOutboxDispatcher,
55
- createOutboxMigrationSql,
56
- createSqlOutboxStore,
57
- createTransactionalOutbox,
58
- } from "bcp/events";
51
+ createMemoryRealtimeBroker,
52
+ createMemoryRealtimePresenceStore,
53
+ createRealtime,
54
+ createRealtimeSseResponse,
55
+ } from "bcp/realtime";
59
56
  ```
60
57
 
61
- The central write model is:
58
+ Runtime model:
62
59
 
63
60
  ```text
64
- BCP Database transaction
65
- |
66
- +-- business data
67
- +-- SQL outbox event
68
- |
69
- COMMIT
70
- |
71
- v
72
- Outbox Dispatcher
73
- |
74
- +-- bcp/jobs
75
- +-- custom publisher
76
- +-- local EventBus
61
+ client connection
62
+ |
63
+ v
64
+ RealtimeHub
65
+ |
66
+ +-- channels / rooms
67
+ +-- auth / channel authorization
68
+ +-- presence
69
+ +-- heartbeat
70
+ |
71
+ +-- RealtimeBroker
72
+ | -> cross-hub delivery
73
+ |
74
+ +-- RealtimeSocket
75
+ | -> WebSocket provider adapter
76
+ |
77
+ +-- SSE Response
77
78
  ```
78
79
 
79
- `createSqlOutboxStore()` supports MySQL, PostgreSQL and SQLite and writes the event using the caller-provided `TransactionDatabase`. The dispatcher adds leasing, stale recovery, retry/backoff and terminal failure handling after commit.
80
+ The memory broker/presence store are process-local. Multi-instance deployments should provide shared implementations.
80
81
 
81
- New/updated documentation sources:
82
+ New/updated sources:
82
83
 
83
84
  | Source | Purpose |
84
85
  | --- | --- |
85
- | `transactional-outbox-events.md` | Transactional publishing, SQL migration, dispatcher lifecycle and delivery guarantees |
86
- | `api-reference.md` | `bcp/events` public APIs |
87
- | `platform-manifest.json` | Events capability flags and public entrypoint |
88
- | `api-manifest.json` | `bcp/events` source/guide ownership |
89
- | `docs-web-manifest.json` | Outbox docs navigation and `0.2.12` release route |
90
- | `releases/0.2.12.md` | Transactional Outbox & Events release notes |
86
+ | `realtime-platform.md` | Channels, presence, WebSocket adapter, SSE, heartbeat and broker model |
87
+ | `api-reference.md` | `bcp/realtime` public APIs |
88
+ | `platform-manifest.json` | Realtime capability flags and public entrypoint |
89
+ | `api-manifest.json` | `bcp/realtime` source/guide ownership |
90
+ | `docs-web-manifest.json` | Realtime docs navigation and `0.2.13` release route |
91
+ | `releases/0.2.13.md` | Realtime Platform release notes |
91
92
 
92
93
  ## Update rule
93
94
 
@@ -107,16 +108,14 @@ When framework behavior or public surface changes:
107
108
  | Website route | Markdown source |
108
109
  | --- | --- |
109
110
  | `/docs/authentication` | `authentication.md` |
110
- | `/docs/authorization-security` | `authorization-security.md` |
111
111
  | `/docs/observability` | `observability.md` |
112
112
  | `/docs/background-jobs` | `background-jobs.md` |
113
- | `/docs/job-scheduling` | `job-scheduling.md` |
114
113
  | `/docs/durable-jobs` | `durable-jobs.md` |
115
114
  | `/docs/workflow-orchestration` | `workflow-orchestration.md` |
116
115
  | `/docs/transactional-outbox-events` | `transactional-outbox-events.md` |
117
- | `/docs/database` | `database.md` |
116
+ | `/docs/realtime-platform` | `realtime-platform.md` |
118
117
  | `/docs/api-reference` | `api-reference.md` |
119
- | `/releases/0.2.12` | `releases/0.2.12.md` |
118
+ | `/releases/0.2.13` | `releases/0.2.13.md` |
120
119
 
121
120
  Every route/source pair is validated by unit tests.
122
121
 
@@ -134,6 +133,7 @@ bcp/auth
134
133
  bcp/jobs
135
134
  bcp/workflow
136
135
  bcp/events
136
+ bcp/realtime
137
137
  bcp/observability
138
138
  bcp/server
139
139
  bcp/server-only
@@ -144,7 +144,7 @@ The API-manifest entrypoint set must match the platform public-entrypoint set ex
144
144
 
145
145
  ## Release validation
146
146
 
147
- Before publishing `0.2.12`:
147
+ Before publishing `0.2.13`:
148
148
 
149
149
  ```bash
150
150
  npm run typecheck
@@ -155,20 +155,6 @@ npm run test:package
155
155
  npm run rc:check
156
156
  ```
157
157
 
158
- Transactional Outbox & Events validation covers:
159
-
160
- - transaction-bound SQL outbox insertion,
161
- - queue handoff,
162
- - custom/event-bus delivery,
163
- - retry and terminal failure,
164
- - dispatcher lease recovery,
165
- - MySQL/PostgreSQL/SQLite migration generation,
166
- - server-only browser boundary enforcement,
167
- - compiled `events.mjs` package execution,
168
- - docs/platform/API version parity.
158
+ Realtime validation covers broker broadcasts, presence, authentication/channel authorization, socket protocol, heartbeat cleanup, SSE streaming, server-only boundaries, compiled `realtime.mjs` package execution and docs/platform/API parity.
169
159
 
170
160
  The final release tag must point to the exact commit that passed the complete RC sequence.
171
-
172
- ## Repository authority
173
-
174
- The framework repository remains authoritative for source, public exports, tests, Markdown docs, manifests and release notes. `bcp-docs-web` remains the presentation/search/navigation layer.
package/docs/api-manifest.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "framework": "bcp",
4
- "version": "0.2.12",
4
+ "version": "0.2.13",
5
5
  "releaseState": "unreleased",
6
6
  "coverage": "public-entrypoints",
7
7
  "entrypoints": [
@@ -11,12 +11,7 @@
11
11
  "environment": "universal",
12
12
  "route": "/docs/api-reference#bcp",
13
13
  "summary": "React application APIs for routing, links, forms, loader/guard data, islands, metadata and route error handling.",
14
- "guides": [
15
- "/docs/routing",
16
- "/docs/server-data-loaders",
17
- "/docs/route-guards",
18
- "/docs/form-actions"
19
- ]
14
+ "guides": ["/docs/routing", "/docs/server-data-loaders", "/docs/route-guards", "/docs/form-actions"]
20
15
  },
21
16
  {
22
17
  "package": "bcp/island",
@@ -24,9 +19,7 @@
24
19
  "environment": "universal",
25
20
  "route": "/docs/api-reference#bcp-island",
26
21
  "summary": "Partial-hydration island creation and island loading strategy types.",
27
- "guides": [
28
- "/docs/hydration"
29
- ]
22
+ "guides": ["/docs/hydration"]
30
23
  },
31
24
  {
32
25
  "package": "bcp/cache",
@@ -34,9 +27,7 @@
34
27
  "environment": "server-preferred",
35
28
  "route": "/docs/api-reference#bcp-cache",
36
29
  "summary": "Cache, deduplication, statistics and path/tag revalidation primitives.",
37
- "guides": [
38
- "/docs/caching"
39
- ]
30
+ "guides": ["/docs/caching"]
40
31
  },
41
32
  {
42
33
  "package": "bcp/config",
@@ -44,10 +35,7 @@
44
35
  "environment": "server",
45
36
  "route": "/docs/api-reference#bcp-config",
46
37
  "summary": "Typed BCP configuration, environment-schema validation and configuration diagnostics APIs.",
47
- "guides": [
48
- "/docs/configuration",
49
- "/docs/environment-validation"
50
- ]
38
+ "guides": ["/docs/configuration", "/docs/environment-validation"]
51
39
  },
52
40
  {
53
41
  "package": "bcp/validation",
@@ -55,9 +43,7 @@
55
43
  "environment": "universal",
56
44
  "route": "/docs/api-reference#bcp-validation",
57
45
  "summary": "Typed validators, parse helpers and structured validation errors.",
58
- "guides": [
59
- "/docs/validation"
60
- ]
46
+ "guides": ["/docs/validation"]
61
47
  },
62
48
  {
63
49
  "package": "bcp/error",
@@ -65,9 +51,7 @@
65
51
  "environment": "universal",
66
52
  "route": "/docs/api-reference#bcp-error",
67
53
  "summary": "Structured HTTP error creation, classification and response helpers.",
68
- "guides": [
69
- "/docs/error-handling"
70
- ]
54
+ "guides": ["/docs/error-handling"]
71
55
  },
72
56
  {
73
57
  "package": "bcp/database",
@@ -75,11 +59,7 @@
75
59
  "environment": "server",
76
60
  "route": "/docs/api-reference#bcp-database",
77
61
  "summary": "Provider-neutral MySQL, PostgreSQL and SQLite query, transaction, lifecycle and migration primitives.",
78
- "guides": [
79
- "/docs/database",
80
- "/docs/database-migrations",
81
- "/docs/transactional-outbox-events"
82
- ]
62
+ "guides": ["/docs/database", "/docs/database-migrations", "/docs/transactional-outbox-events"]
83
63
  },
84
64
  {
85
65
  "package": "bcp/auth",
@@ -87,13 +67,7 @@
87
67
  "environment": "server",
88
68
  "route": "/docs/api-reference#bcp-auth",
89
69
  "summary": "Authentication Platform v2 plus permission checks, authorization policies and auth/guest/role/permission route guards.",
90
- "guides": [
91
- "/docs/authentication",
92
- "/docs/auth-session-store",
93
- "/docs/auth-route-guards",
94
- "/docs/authorization-security",
95
- "/docs/session-auth"
96
- ]
70
+ "guides": ["/docs/authentication", "/docs/auth-session-store", "/docs/auth-route-guards", "/docs/authorization-security", "/docs/session-auth"]
97
71
  },
98
72
  {
99
73
  "package": "bcp/jobs",
@@ -101,13 +75,7 @@
101
75
  "environment": "server",
102
76
  "route": "/docs/api-reference#bcp-jobs",
103
77
  "summary": "Background queues and schedules with visibility leases, heartbeats, stale recovery, DLQ maintenance and Redis-compatible durable adapters.",
104
- "guides": [
105
- "/docs/background-jobs",
106
- "/docs/job-scheduling",
107
- "/docs/durable-jobs",
108
- "/docs/transactional-outbox-events",
109
- "/docs/observability"
110
- ]
78
+ "guides": ["/docs/background-jobs", "/docs/job-scheduling", "/docs/durable-jobs", "/docs/transactional-outbox-events", "/docs/realtime-platform", "/docs/observability"]
111
79
  },
112
80
  {
113
81
  "package": "bcp/workflow",
@@ -115,11 +83,7 @@
115
83
  "environment": "server",
116
84
  "route": "/docs/api-reference#bcp-workflow",
117
85
  "summary": "Persistent workflow orchestration with sequential and parallel steps, retries, delays, compensation, run leases and optional durable queue execution.",
118
- "guides": [
119
- "/docs/workflow-orchestration",
120
- "/docs/durable-jobs",
121
- "/docs/observability"
122
- ]
86
+ "guides": ["/docs/workflow-orchestration", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/observability"]
123
87
  },
124
88
  {
125
89
  "package": "bcp/events",
@@ -127,12 +91,15 @@
127
91
  "environment": "server",
128
92
  "route": "/docs/api-reference#bcp-events",
129
93
  "summary": "Transactional outbox and event delivery APIs with SQL persistence, dispatcher leases, retries, stale recovery, queue handoff and in-process event bus delivery.",
130
- "guides": [
131
- "/docs/transactional-outbox-events",
132
- "/docs/database",
133
- "/docs/durable-jobs",
134
- "/docs/observability"
135
- ]
94
+ "guides": ["/docs/transactional-outbox-events", "/docs/database", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/observability"]
95
+ },
96
+ {
97
+ "package": "bcp/realtime",
98
+ "source": "packages/client/src/realtime.ts",
99
+ "environment": "server",
100
+ "route": "/docs/api-reference#bcp-realtime",
101
+ "summary": "Realtime channels, cross-hub broker delivery, presence, channel authorization, WebSocket adapter integration, heartbeat handling and built-in Server-Sent Events responses.",
102
+ "guides": ["/docs/realtime-platform", "/docs/authentication", "/docs/observability"]
136
103
  },
137
104
  {
138
105
  "package": "bcp/observability",
@@ -140,10 +107,7 @@
140
107
  "environment": "server",
141
108
  "route": "/docs/api-reference#bcp-observability",
142
109
  "summary": "In-process metrics, Prometheus exposition, request metrics middleware and health/readiness checks.",
143
- "guides": [
144
- "/docs/observability",
145
- "/docs/development-logging"
146
- ]
110
+ "guides": ["/docs/observability", "/docs/development-logging"]
147
111
  },
148
112
  {
149
113
  "package": "bcp/server",
@@ -151,14 +115,7 @@
151
115
  "environment": "server",
152
116
  "route": "/docs/api-reference#bcp-server",
153
117
  "summary": "Request context, cookies, CSRF/same-origin protection, logging, production hardening, upload, storage, response and session APIs.",
154
- "guides": [
155
- "/docs/server-request-apis",
156
- "/docs/authorization-security",
157
- "/docs/file-upload",
158
- "/docs/storage",
159
- "/docs/storage-ecosystem",
160
- "/docs/production-hardening"
161
- ]
118
+ "guides": ["/docs/server-request-apis", "/docs/authorization-security", "/docs/file-upload", "/docs/storage", "/docs/storage-ecosystem", "/docs/production-hardening"]
162
119
  },
163
120
  {
164
121
  "package": "bcp/server-only",
@@ -166,9 +123,7 @@
166
123
  "environment": "server-marker",
167
124
  "route": "/docs/api-reference#bcp-server-only",
168
125
  "summary": "Server-only module boundary marker that prevents accidental browser inclusion.",
169
- "guides": [
170
- "/docs/application-modules"
171
- ]
126
+ "guides": ["/docs/application-modules"]
172
127
  },
173
128
  {
174
129
  "package": "bcp/middleware",
@@ -176,9 +131,7 @@
176
131
  "environment": "server",
177
132
  "route": "/docs/api-reference#bcp-middleware",
178
133
  "summary": "Middleware System v2 request/response pipeline types and helpers.",
179
- "guides": [
180
- "/docs/middleware"
181
- ]
134
+ "guides": ["/docs/middleware"]
182
135
  }
183
136
  ]
184
137
  }
package/docs/api-reference.md CHANGED
@@ -78,7 +78,7 @@ BCP does not install a Redis library and does not create the connection. Applica
78
78
 
79
79
  The processing model is at-least-once. Handlers that perform non-idempotent external side effects should use application-level idempotency protection.
80
80
 
81
- Related guides: [Background Jobs Platform](background-jobs.md), [Job Scheduling Platform](job-scheduling.md), [Durable Jobs Platform](durable-jobs.md), [Transactional Outbox & Events](transactional-outbox-events.md), [Observability Platform v2](observability.md).
81
+ Related guides: [Background Jobs Platform](background-jobs.md), [Job Scheduling Platform](job-scheduling.md), [Durable Jobs Platform](durable-jobs.md), [Transactional Outbox & Events](transactional-outbox-events.md), [Realtime Platform](realtime-platform.md), [Observability Platform v2](observability.md).
82
82
 
83
83
  ## `bcp/workflow`
84
84
 
@@ -111,7 +111,7 @@ When an existing `BackgroundJobQueue` is supplied, workflow execution and delay
111
111
 
112
112
  `WorkflowStore.claim()` / `release()` form the run-level lease boundary for multi-instance stores.
113
113
 
114
- Related guides: [Workflow Orchestration](workflow-orchestration.md), [Durable Jobs Platform](durable-jobs.md), [Observability Platform v2](observability.md).
114
+ Related guides: [Workflow Orchestration](workflow-orchestration.md), [Durable Jobs Platform](durable-jobs.md), [Realtime Platform](realtime-platform.md), [Observability Platform v2](observability.md).
115
115
 
116
116
  ## `bcp/events`
117
117
 
@@ -125,81 +125,90 @@ import {
125
125
  createOutboxMigrationSql,
126
126
  createSqlOutboxStore,
127
127
  createTransactionalOutbox,
128
- type ClaimOutboxEventsOptions,
129
- type CleanupOutboxOptions,
130
- type EventBus,
131
- type FailOutboxEventOptions,
132
- type MemoryOutboxStore,
133
- type OutboxDispatcher,
134
- type OutboxDispatcherOptions,
135
- type OutboxDispatcherRunner,
136
- type OutboxEventHandler,
137
- type OutboxEventHandlerContext,
138
- type OutboxEventRecord,
139
- type OutboxEventState,
140
- type OutboxRetryDelay,
141
- type OutboxStats,
142
- type OutboxStore,
143
- type PublishOutboxEventOptions,
144
- type SqlOutboxStore,
145
- type SqlOutboxStoreOptions,
146
- type TransactionalOutbox,
147
- type TransactionalOutboxOptions,
148
128
  } from "bcp/events";
149
129
  ```
150
130
 
151
- ### Transactional publishing
131
+ `createTransactionalOutbox()` writes an event through the same `TransactionDatabase` used by `db.transaction()`, allowing business rows and outbox rows to commit or roll back together.
152
132
 
153
- `createTransactionalOutbox()` exposes `publish(transaction, type, payload, options)`.
133
+ `createSqlOutboxStore()` supports MySQL, PostgreSQL and SQLite. `createOutboxMigrationSql()` generates the outbox table/index DDL.
154
134
 
155
- The supplied `TransactionDatabase` is the same object received inside `db.transaction()`, allowing the application row and outbox event row to commit or roll back together.
135
+ `createOutboxDispatcher()` supports batched claims, leases, stale recovery, retry/backoff, terminal failure, job-queue handoff, custom publishing, local event-bus delivery and runner lifecycle.
156
136
 
157
- ### SQL store
137
+ Delivery is at-least-once; consumers should use idempotency controls for non-repeatable side effects.
158
138
 
159
- `createSqlOutboxStore()` supports MySQL, PostgreSQL and SQLite through the existing BCP database abstraction.
139
+ Related guides: [Transactional Outbox & Events](transactional-outbox-events.md), [Database](database.md), [Durable Jobs Platform](durable-jobs.md), [Realtime Platform](realtime-platform.md), [Observability Platform v2](observability.md).
160
140
 
161
- `createOutboxMigrationSql()` generates the outbox table/index DDL for those providers.
141
+ ## `bcp/realtime`
162
142
 
163
- The SQL store persists payload/metadata, correlation/causation/aggregate IDs, retry counts, state timestamps and dispatcher lease information.
143
+ Server-only Realtime Platform APIs added in `0.2.13`.
164
144
 
165
- ### Dispatcher
145
+ ```ts
146
+ import {
147
+ createMemoryRealtimeBroker,
148
+ createMemoryRealtimePresenceStore,
149
+ createRealtime,
150
+ createRealtimeSseResponse,
151
+ type RealtimeAuthenticate,
152
+ type RealtimeAuthorizeChannel,
153
+ type RealtimeBroker,
154
+ type RealtimeBroadcastOptions,
155
+ type RealtimeConnection,
156
+ type RealtimeEnvelope,
157
+ type RealtimeEventContext,
158
+ type RealtimeEventHandler,
159
+ type RealtimeHeartbeatOptions,
160
+ type RealtimeHeartbeatRunner,
161
+ type RealtimeHub,
162
+ type RealtimeJoinOptions,
163
+ type RealtimeOptions,
164
+ type RealtimePresenceMember,
165
+ type RealtimePresenceStore,
166
+ type RealtimeSocket,
167
+ type RealtimeSseOptions,
168
+ } from "bcp/realtime";
169
+ ```
166
170
 
167
- `createOutboxDispatcher()` supports:
171
+ ### Hub and channels
168
172
 
169
- ```text
170
- batched claim
171
- dispatcher lease
172
- stale recovery
173
- retry/backoff
174
- terminal failure
175
- durable job queue handoff
176
- custom publisher callback
177
- in-process EventBus delivery
178
- runner lifecycle
179
- ```
173
+ `createRealtime()` creates a server-side hub. Connections can `join()`, `leave()`, `emit()`, `send()`, `touch()` and `disconnect()`.
180
174
 
181
- With `queue` configured, event `order.created` is enqueued as `event.order.created` using stable job ID `outbox:<event-id>`.
175
+ `hub.broadcast(channel, event, payload)` delivers through the configured broker and reaches connections that joined the channel.
182
176
 
183
- ### Stores
177
+ ### Broker
184
178
 
185
- `OutboxStore` is the persistence and concurrency boundary.
179
+ `RealtimeBroker` is the cross-hub pub/sub boundary. The memory implementation is process-local; production multi-instance applications can provide a shared broker such as Redis Pub/Sub or NATS without changing the hub surface.
186
180
 
187
- `createMemoryOutboxStore()` is intended for tests and single-process development. It does not provide durable transactional persistence.
181
+ ### Presence
188
182
 
189
- ### States
183
+ `RealtimePresenceStore` tracks per-channel connection presence. `hub.members(channel)` returns current presence records.
190
184
 
191
- ```text
192
- pending
193
- processing
194
- published
195
- failed
196
- ```
185
+ The memory store is intended for tests/single-process use. Shared deployments should use a shared presence adapter.
186
+
187
+ ### Authentication and channel authorization
188
+
189
+ `RealtimeOptions.authenticate` can resolve application user identity from a `Request`/connection data. `getUserId` maps that identity into presence records.
190
+
191
+ `RealtimeOptions.authorizeChannel` runs before `join()` completes and can enforce private-room access.
192
+
193
+ ### Socket adapter
194
+
195
+ BCP does not install a WebSocket provider. `RealtimeSocket` defines the minimal `send`, `close`, `onMessage`, `onClose` and optional `onError` surface consumed by `hub.attachSocket()`.
196
+
197
+ The built-in JSON protocol accepts `join`, `leave`, `event` and `ping` messages. `ping` receives a `realtime.pong` event.
198
+
199
+ ### Server-Sent Events
200
+
201
+ `hub.sse(channel, options)` and `createRealtimeSseResponse()` return Web-standard streaming `Response` objects using `text/event-stream`.
202
+
203
+ Options include abort signal integration, event filtering, retry hints, keep-alive timing and response headers.
204
+
205
+ ### Heartbeat
197
206
 
198
- `published` means the configured dispatcher destination accepted the event. It does not mean a downstream queued consumer has completed.
207
+ `hub.startHeartbeat()` sends `realtime.ping` messages and invokes stale connection cleanup. `hub.sweepStale()` is also public for deterministic infrastructure loops/tests.
199
208
 
200
- Delivery is at-least-once; consumers should use idempotency controls for non-repeatable external side effects.
209
+ Realtime delivery is transient. Use database/outbox/jobs/workflows for durable state and refetch durable state/history after reconnect when catch-up is required.
201
210
 
202
- Related guides: [Transactional Outbox & Events](transactional-outbox-events.md), [Database](database.md), [Durable Jobs Platform](durable-jobs.md), [Observability Platform v2](observability.md).
211
+ Related guides: [Realtime Platform](realtime-platform.md), [Authentication](authentication.md), [Observability Platform v2](observability.md).
203
212
 
204
213
  ## `bcp/observability`
205
214
 
package/docs/docs-web-manifest.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "framework": "bcp",
4
- "versionTarget": "0.2.12",
4
+ "versionTarget": "0.2.13",
5
5
  "releaseState": "unreleased",
6
6
  "sections": [
7
7
  {
@@ -58,7 +58,7 @@
58
58
  {
59
59
  "id": "runtime",
60
60
  "title": "Runtime & Infrastructure",
61
- "description": "Middleware, durable background jobs, scheduling, workflow orchestration, event delivery, observability, logging, caching, security and production hardening.",
61
+ "description": "Middleware, jobs, scheduling, workflows, event delivery, realtime channels, observability, caching, security and production hardening.",
62
62
  "pages": [
63
63
  { "route": "/docs/middleware", "source": "middleware.md", "title": "Middleware" },
64
64
  { "route": "/docs/hydration", "source": "hydration.md", "title": "Hydration" },
@@ -68,6 +68,7 @@
68
68
  { "route": "/docs/job-scheduling", "source": "job-scheduling.md", "title": "Job Scheduling Platform" },
69
69
  { "route": "/docs/durable-jobs", "source": "durable-jobs.md", "title": "Durable Jobs Platform" },
70
70
  { "route": "/docs/workflow-orchestration", "source": "workflow-orchestration.md", "title": "Workflow Orchestration" },
71
+ { "route": "/docs/realtime-platform", "source": "realtime-platform.md", "title": "Realtime Platform" },
71
72
  { "route": "/docs/caching", "source": "caching.md", "title": "Caching" },
72
73
  { "route": "/docs/security", "source": "security.md", "title": "Security" },
73
74
  { "route": "/docs/production-hardening", "source": "production-hardening.md", "title": "Production Hardening" }
@@ -113,7 +114,8 @@
113
114
  }
114
115
  ],
115
116
  "releases": [
116
- { "route": "/releases/0.2.12", "source": "releases/0.2.12.md", "version": "0.2.12", "state": "unreleased" },
117
+ { "route": "/releases/0.2.13", "source": "releases/0.2.13.md", "version": "0.2.13", "state": "unreleased" },
118
+ { "route": "/releases/0.2.12", "source": "releases/0.2.12.md", "version": "0.2.12" },
117
119
  { "route": "/releases/0.2.11", "source": "releases/0.2.11.md", "version": "0.2.11" },
118
120
  { "route": "/releases/0.2.10", "source": "releases/0.2.10.md", "version": "0.2.10" },
119
121
  { "route": "/releases/0.2.9", "source": "releases/0.2.9.md", "version": "0.2.9" },
package/docs/platform-manifest.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "framework": "bcp",
4
- "version": "0.2.12",
4
+ "version": "0.2.13",
5
5
  "releaseState": "unreleased",
6
- "baseline": "transactional-outbox-events",
6
+ "baseline": "realtime-platform",
7
7
  "runtime": {
8
8
  "node": ">=24.11.0",
9
9
  "react": "19",
@@ -22,6 +22,7 @@
22
22
  "bcp/jobs",
23
23
  "bcp/workflow",
24
24
  "bcp/events",
25
+ "bcp/realtime",
25
26
  "bcp/observability",
26
27
  "bcp/server",
27
28
  "bcp/server-only",
@@ -111,6 +112,15 @@
111
112
  "outboxStatistics": true,
112
113
  "eventBus": true,
113
114
  "outboxJobDelivery": true,
115
+ "realtimePlatform": true,
116
+ "realtimeBrokerContract": true,
117
+ "realtimePresenceStore": true,
118
+ "realtimeChannels": true,
119
+ "realtimeChannelAuthorization": true,
120
+ "realtimeSocketAdapter": true,
121
+ "realtimeServerSentEvents": true,
122
+ "realtimeHeartbeats": true,
123
+ "realtimeCrossHubBroadcast": true,
114
124
  "databaseMigrations": true,
115
125
  "databaseAdapterContract": true,
116
126
  "databasePostgresql": true,
@@ -150,7 +160,7 @@
150
160
  "s3-compatible"
151
161
  ],
152
162
  "compatibility": {
153
- "previousBaseline": "0.2.11",
163
+ "previousBaseline": "0.2.12",
154
164
  "intentionalBreakingChangesFromPreviousBaseline": false,
155
165
  "migrationGuide": "migration-0.2.md"
156
166
  },
@@ -172,7 +182,8 @@
172
182
  "durableJobs": "durable-jobs.md",
173
183
  "workflowOrchestration": "workflow-orchestration.md",
174
184
  "transactionalOutboxEvents": "transactional-outbox-events.md",
185
+ "realtimePlatform": "realtime-platform.md",
175
186
  "migrationGuide": "migration-0.2.md",
176
- "releaseNotes": "releases/0.2.12.md"
187
+ "releaseNotes": "releases/0.2.13.md"
177
188
  }
178
189
  }