You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 42a5488
Browse filesBrowse the repository at this point in the historyBrowse files
feat(notifications): the push channel — service-push (APNs + FCM) and its channel shell in service-messaging
A notify node naming the push channel now reaches the recipient's registered
devices through APNs (HTTP/2, token auth) and FCM (HTTP v1); a token the vendor
reports dead is retired. Credentials only through credentialRef.
Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JQwxbWDV359nY4JGrtUq4P
feat(notifications): the `push` channel — a `notify` node naming `push` reaches the recipient's phones through APNs and FCM
8
+
9
+
Clause-②: yes (widening)
10
+
Metadata-protocol: none
11
+
12
+
-**New package `@objectstack/service-push`.**`PushServicePlugin` registers the kernel's `push` service: APNs over HTTP/2 with token-based auth (an ES256 provider token signed with the `.p8` key, reused for fifty minutes) and FCM over the HTTP v1 API (an OAuth access token from the service account). It reads `PushServiceConfigSchema` from its `config` option and refuses an inline secret at boot with the schema's guidance. Each secret is named by `credentialRef` and resolved when the transport first signs; in the open tier the reference is the name of an environment variable (ADR-0143 D3).
13
+
-**`@objectstack/service-messaging`: the `push` channel.** Mounted while a `push` service is registered, as the sms channel is while an `sms` service is. One delivery reaches every enabled device the recipient registered, on each vendor the push service has a transport for. The push carries the notification id and, when it is a same-server path (`PushRouteSchema`), the notification's `actionUrl` as `route`; any other `actionUrl` is left out and the delivery still goes. A token the vendor reports dead (APNs `BadDeviceToken` / `Unregistered`, FCM `UNREGISTERED`) is retired through `invalidateDeviceToken`: the device row is kept, disabled, and the user's other devices still get the push. A recipient with no enabled device, or whose every device was reported dead, is graded `invalid_recipient`; no push service is refused `transport_not_configured`, as the sms and email channels refuse it.
14
+
-**`@objectstack/spec`: description and comment text only.** The `[PLANNED]` markers come off `PushServiceConfigSchema`, `ApnsTransportConfigSchema`, `FcmTransportConfigSchema` and `PushDeliveryDataSchema`, which now have their reader and producer. `NotificationChannelSchema`'s JSDoc lists `push` among the registered channels, the docblocks name `@objectstack/service-push` where they named `plugin-notification-push`, and the `NOT_FOUND` synonym waiver's reason names service-messaging's own provenance row. No key, schema shape or export changes.
-**Features**: `MessagingChannel` registry, `emit()` fan-out, always-on inbox channel; the email, sms and push channels mount while their transport service is registered; the push device registry (`sys_user_device`, `/api/v1/notifications/devices`); webhook/IM channels plug in
244
244
-**When to use**: Notifying users across channels from flows, hooks, and plugins
245
245
246
246
### @objectstack/service-sms
@@ -250,6 +250,13 @@ All services implement contracts from `@objectstack/spec/contracts` and are kern
250
250
-**Features**: Provider adapters (Aliyun SMS, Twilio), `sms` settings namespace with live rebind, backs phone-number OTP sign-in/reset and the messaging `sms` channel
**Push Service** — Outbound mobile push through APNs and FCM (`push` service).
256
+
257
+
-**Features**: APNs over HTTP/2 with token-based auth (`.p8` signing key) and FCM over the HTTP v1 API (service account), configured by `PushServiceConfigSchema` with each secret named by `credentialRef`, never inline; backs the messaging `push` channel, which delivers to the recipient's registered devices, carries the notification's `route`, and retires a token the vendor reports dead
258
+
-**When to use**: Phone notifications from `notify` flow nodes and `emit()` — compose `new PushServicePlugin({ config })` beside `MessagingServicePlugin`
259
+
253
260
### @objectstack/service-print
254
261
255
262
**Print Service** — Prints a record's print page to a PDF in headless Chromium, as the requesting user, and archives it as a file attached to the record (`print` service).
Copy file name to clipboardExpand all lines: content/docs/references/api/push-delivery.mdx
+5-5Lines changed: 5 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,10 +18,10 @@ vendor payload. On FCM (HTTP v1) these members go in `message.data`, a map
18
18
of string values. On APNs they sit at the top level of the payload, beside
19
19
`aps`, and never under a `data` key.
20
20
21
-
**Declared ahead of its producer.**No pushchannel delivers yet, so
22
-
nothing produces this data today; `PushDeliveryDataSchema` carries a
23
-
`[PLANNED — not yet served]` marker in its `.describe()` until the push
24
-
channel ships. The route rule below is the contract that channel owes.
21
+
**Produced by the `push` channel**(`push-channel.ts` in
22
+
`@objectstack/service-messaging`), which builds it per delivery and hands it
23
+
to the push service's transports (`@objectstack/service-push`). The route
24
+
rule below is the contract that channel keeps.
25
25
26
26
**What `route` is — the inbox's `actionUrl`, derived, never authored.**
27
27
There is no `notify` key for it. It is the value the inbox already serves:
@@ -71,7 +71,7 @@ const result = PushDeliveryDataSchema.parse(data);
71
71
72
72
## PushDeliveryData
73
73
74
-
[PLANNED — not yet served]The data a push delivery carries to the shell: the notification id and its actionUrl as a same-server route. No push channel delivers yet
74
+
The data a push delivery carries to the shell: the notification id and its actionUrl as a same-server route
Copy file name to clipboardExpand all lines: content/docs/references/system/push-config.mdx
+20-18Lines changed: 20 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,43 +1,45 @@
1
1
---
2
2
title: Push Config schema — System Protocol reference
3
3
navTitle: Push Config
4
-
description: "Push Service Configuration Protocol — the push channel's transports. Declared ahead of its reader."
4
+
description: "Push Service Configuration Protocol — the push channel's transports. Read by @objectstack/service-push."
5
5
---
6
6
7
7
{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
8
8
9
9
Push Service Configuration Protocol — the push channel's transports.
10
10
11
-
**Declared ahead of its reader.** Every schema here carries a
12
-
`[PLANNED — not yet read]` marker in its `.describe()`: nothing reads this
13
-
shape until the push channel plugin lands, so a value written to it today
14
-
changes nothing. The marker comes off with the change that wires the reader.
11
+
**Read by `@objectstack/service-push`.**`PushServicePlugin` parses its
12
+
`config` option with `PushServiceConfigSchema` when it initialises and
13
+
builds one transport per block; the `push` channel in
14
+
`@objectstack/service-messaging` delivers through the push service it
15
+
registers.
15
16
16
17
Operator-facing configuration for the `push` channel ADR-0012 §4 ships in
17
18
core: Apple Push Notification service with token-based auth, and Firebase
18
-
Cloud Messaging over its HTTP v1 API. It sits beside
19
+
Cloud Messaging over its HTTP v1 API (ADR-0012, amended 2026-11-03: the
20
+
transports ship as `@objectstack/service-push`). It sits beside
19
21
`EmailServiceConfigSchema` (`email-config.zod.ts`), the declaration of
20
22
the email channel's transport selection.
21
23
22
24
**Secrets are references, never values (ADR-0143 D3, ADR-0097 §3).** Each
23
25
transport has one secret — the APNs `.p8` signing key and the FCM
24
26
service-account JSON — and each is named by a `credentialRef`, the same key
25
27
every other secret an author names is written under (ADR-0143 D3), which
26
-
the push channel resolves through the secrets layer when it sends (in the
27
-
open tier, the name of an environment variable). An inline secret is
28
+
the push transport resolves through the secrets layer when it first signs
29
+
(in the open tier, the name of an environment variable). An inline secret is
28
30
refused two ways: written under a key an operator would reach for (`key`,
29
31
`privateKey`, `serviceAccount`, …), it is refused by name with
30
32
`credentialRef` as the prescription; written into the reference itself, it
31
33
is refused because a reference is one token — a PEM block carries
32
34
whitespace and a JSON document carries braces, and a name carries neither.
33
35
34
-
**What reads it, and why it is not a stack key yet.**The push channel
35
-
plugin (`plugin-notification-push`, ADR-0012 §11) is its one reader, and it
36
-
is a later change than this declaration. The email transport selection it
37
-
sits beside is read from `config.email` of the stack definition
38
-
(`StackEmailConfigSchema`) and `OS_EMAIL_*`; this shape gets its own
39
-
configuration door in the change that ships the reader, not here, so a key
40
-
is never authorable before something honours it.
36
+
**What reads it, and why it is not a stack key.**`PushServicePlugin`
37
+
(`@objectstack/service-push`) is its one reader, through the plugin's
38
+
constructor: the host that composes the plugin hands it the value. The email
39
+
transport selection it sits beside is read from `config.email` of the stack
40
+
definition (`StackEmailConfigSchema`) and `OS_EMAIL_*`; this shape has no
41
+
stack-definition key and no `os serve` capability yet, so it is authorable
42
+
only where a host composes the plugin.
41
43
42
44
Out of scope here: a hosted (cloud-side) configuration surface, and the
43
45
other vendors ADR-0012 §6 routes to alternate channel plugins (HMS,
@@ -61,7 +63,7 @@ const result = ApnsTransportConfigSchema.parse(data);
61
63
62
64
## ApnsTransportConfig
63
65
64
-
[PLANNED — not yet read]APNs transport with token-based auth (.p8 signing key by reference)
66
+
APNs transport with token-based auth (.p8 signing key by reference)
65
67
66
68
### Properties
67
69
@@ -78,7 +80,7 @@ const result = ApnsTransportConfigSchema.parse(data);
78
80
79
81
## FcmTransportConfig
80
82
81
-
[PLANNED — not yet read]FCM HTTP v1 transport (service-account JSON by reference)
83
+
FCM HTTP v1 transport (service-account JSON by reference)
82
84
83
85
### Properties
84
86
@@ -92,7 +94,7 @@ const result = ApnsTransportConfigSchema.parse(data);
92
94
93
95
## PushServiceConfig
94
96
95
-
[PLANNED — not yet read]Push channel transport configuration: one optional block per vendor (apns, fcm). Nothing reads it until the push channel plugin ships
97
+
Push channel transport configuration: one optional block per vendor (apns, fcm), read by the push service
Copy file name to clipboardExpand all lines: docs/adr/0012-notification-platform.md
+4-3Lines changed: 4 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# ADR-0012: Messaging Platform — Outbound Notifications on a Generalized Outbox
2
2
3
-
**Status**: Draft (2026-05-25 · scope-revised 2026-05-26) · **Superseded by [ADR-0030](./0030-notification-platform-convergence.md)** (2026-06-01) — the M1 implementation drifted (two conflated inbox objects); ADR-0030 records the correction and realizes this layered model.
3
+
**Status**: Draft (2026-05-25 · scope-revised 2026-05-26) · **Superseded by [ADR-0030](./0030-notification-platform-convergence.md)** (2026-06-01) — the M1 implementation drifted (two conflated inbox objects); ADR-0030 records the correction and realizes this layered model. · **Amended (2026-11-03, #29041)**: push ships as `@objectstack/service-push` (the APNs and FCM transports, the kernel's `push` service) with its channel shell `push-channel.ts` in `@objectstack/service-messaging`, which also owns `sys_user_device`; every `plugin-notification-push` below reads that way. ADR-0030 is unchanged.
4
4
**Authors**: Platform team — surfaced from GitHub Issue #1292 ("[P0] notification: no outbound notification channel")
5
5
**Consumers**: `@objectstack/spec` (new `messaging/` domain), `@objectstack/service-messaging` (new), `@objectstack/plugin-notification-inbox` (new), `@objectstack/plugin-notification-email` (replaces `plugin-email`), `@objectstack/plugin-notification-webhook` (extracted from `plugin-webhooks`), `@objectstack/plugin-notification-push` (new), every flow that has a `notify` node, every template that ships notification rules
All four bind into `channel-registry` during `onEnable`.
312
312
@@ -375,7 +375,8 @@ Lifecycle hooks:
375
375
376
376
* Client SDK calls `POST /api/v1/notifications/devices` on login → `device-registry.upsert(...)`.
377
377
* APNs / FCM `BadDeviceToken` / `Unregistered` response → channel returns `classifyError = 'invalid_recipient'` → dispatcher calls `device-registry.invalidate(token)` (sets `invalidated_at`, `enabled=false`) without dead-lettering the notification (it just routes around the dead token).
378
-
* Domestic vendors (HMS / Xiaomi / OPPO / VIVO) plug in as **alternate channel implementations** (`plugin-notification-push-hms` etc.), not as transports — their on-device SDKs and quotas are too different to share a code path.
378
+
> Amended (2026-11-03, #29041): the push channel (`push-channel.ts` in service-messaging) retires the dead token itself, through `INotificationService.invalidateDeviceToken`, because one delivery fans out to all of the recipient's devices and only the channel knows which token died; the other devices still get the push. The delivery is graded `invalid_recipient` (suppressed, not dead-lettered) only when every device was reported dead. The shipped device shape is `UserDeviceSchema` in `packages/spec/src/system/push-device.zod.ts`, narrowed to `apns` | `fcm` and `ios` | `android` | `web`.
379
+
* Domestic vendors (HMS / Xiaomi / OPPO / VIVO) plug in as **alternate channel implementations** (one package each, named by kind like `service-push`), not as transports — their on-device SDKs and quotas are too different to share a code path.
0 commit comments