Skip to content

Commit 42a5488

Browse files
committed
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
1 parent 7b55ea9 commit 42a5488

37 files changed

Lines changed: 2344 additions & 78 deletions
Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
'@objectstack/service-push': minor
3+
'@objectstack/service-messaging': minor
4+
'@objectstack/spec': patch
5+
---
6+
7+
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.

‎.changeset/config.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@
4949
"@objectstack/plugin-security",
5050
"@objectstack/plugin-sharing",
5151
"@objectstack/service-sms",
52+
"@objectstack/service-push",
5253
"@objectstack/plugin-webhooks",
5354
"@objectstack/trigger-record-change",
5455
"@objectstack/trigger-api",

‎CONTRIBUTING.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -416,6 +416,7 @@ start when you add a component.
416416
| [`@objectstack/service-i18n`](packages/services/service-i18n) | Internationalization |
417417
| [`@objectstack/service-messaging`](packages/services/service-messaging) | Outbound notification dispatch across channels |
418418
| [`@objectstack/service-sms`](packages/services/service-sms) | SMS delivery (Aliyun, Twilio, log) |
419+
| [`@objectstack/service-push`](packages/services/service-push) | Mobile push delivery (APNs, FCM) |
419420
| [`@objectstack/service-knowledge`](packages/services/service-knowledge) | Knowledge / RAG orchestration over pluggable adapters |
420421
| [`@objectstack/service-package`](packages/services/service-package) | Package registry — publish, install, manage metadata packages |
421422
| [`@objectstack/cloud-connection`](packages/cloud-connection) | Runtime-side client for an ObjectStack cloud control plane |

‎content/docs/plugins/packages.mdx‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ ObjectStack is organized into package manifests across multiple categories. This
1515
| **Framework adapters** | 1 | `hono` (other frameworks: build a thin adapter on `HttpDispatcher` — see below) |
1616
| **Drivers** | 5 | `driver-memory`, `driver-sql`, `driver-sqlite-wasm`, `driver-mongodb`, `driver-turso` |
1717
| **Plugins** | 17 | `plugin-auth`, `plugin-security`, `plugin-audit`, `plugin-approvals`, `plugin-sharing`, `plugin-email`, `plugin-webhooks`, `plugin-hono-server`, `plugin-dev`, `plugin-pinyin-search`, `mcp`, trigger plugins (`trigger-api`, `trigger-record-change`, `trigger-schedule`), and knowledge/embedder plugins (`knowledge-memory`, `knowledge-ragflow`, `embedder-openai`) |
18-
| **Platform services** | 17 | `service-analytics`, `service-automation`, `service-cache`, `service-cluster`, `service-cluster-redis`, `service-datasource`, `service-i18n`, `service-job`, `service-knowledge`, `service-messaging`, `service-package`, `service-print`, `service-queue`, `service-realtime`, `service-settings`, `service-sms`, `service-storage` |
18+
| **Platform services** | 18 | `service-analytics`, `service-automation`, `service-cache`, `service-cluster`, `service-cluster-redis`, `service-datasource`, `service-i18n`, `service-job`, `service-knowledge`, `service-messaging`, `service-package`, `service-print`, `service-push`, `service-queue`, `service-realtime`, `service-settings`, `service-sms`, `service-storage` |
1919

2020

2121
## Core Packages
@@ -240,7 +240,7 @@ All services implement contracts from `@objectstack/spec/contracts` and are kern
240240

241241
**Messaging Service** — Outbound notification dispatch (ADR-0012).
242242

243-
- **Features**: `MessagingChannel` registry, `emit()` fan-out, always-on inbox channel; email/webhook/push/IM channels plug in
243+
- **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
244244
- **When to use**: Notifying users across channels from flows, hooks, and plugins
245245

246246
### @objectstack/service-sms
@@ -250,6 +250,13 @@ All services implement contracts from `@objectstack/spec/contracts` and are kern
250250
- **Features**: Provider adapters (Aliyun SMS, Twilio), `sms` settings namespace with live rebind, backs phone-number OTP sign-in/reset and the messaging `sms` channel
251251
- **When to use**: Phone OTP first-login / self-service reset, SMS notifications
252252

253+
### @objectstack/service-push
254+
255+
**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+
253260
### @objectstack/service-print
254261

255262
**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).

‎content/docs/references/api/push-delivery.mdx‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,10 @@ vendor payload. On FCM (HTTP v1) these members go in `message.data`, a map
1818
of string values. On APNs they sit at the top level of the payload, beside
1919
`aps`, and never under a `data` key.
2020

21-
**Declared ahead of its producer.** No push channel 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.
2525

2626
**What `route` is — the inbox's `actionUrl`, derived, never authored.**
2727
There is no `notify` key for it. It is the value the inbox already serves:
@@ -71,7 +71,7 @@ const result = PushDeliveryDataSchema.parse(data);
7171

7272
## PushDeliveryData
7373

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
7575

7676
### Properties
7777

‎content/docs/references/system/push-config.mdx‎

Lines changed: 20 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,45 @@
11
---
22
title: Push Config schema — System Protocol reference
33
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."
55
---
66

77
{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
88

99
Push Service Configuration Protocol — the push channel's transports.
1010

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.
1516

1617
Operator-facing configuration for the `push` channel ADR-0012 §4 ships in
1718
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
1921
`EmailServiceConfigSchema` (`email-config.zod.ts`), the declaration of
2022
the email channel's transport selection.
2123

2224
**Secrets are references, never values (ADR-0143 D3, ADR-0097 §3).** Each
2325
transport has one secret — the APNs `.p8` signing key and the FCM
2426
service-account JSON — and each is named by a `credentialRef`, the same key
2527
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
2830
refused two ways: written under a key an operator would reach for (`key`,
2931
`privateKey`, `serviceAccount`, …), it is refused by name with
3032
`credentialRef` as the prescription; written into the reference itself, it
3133
is refused because a reference is one token — a PEM block carries
3234
whitespace and a JSON document carries braces, and a name carries neither.
3335

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.
4143

4244
Out of scope here: a hosted (cloud-side) configuration surface, and the
4345
other vendors ADR-0012 §6 routes to alternate channel plugins (HMS,
@@ -61,7 +63,7 @@ const result = ApnsTransportConfigSchema.parse(data);
6163

6264
## ApnsTransportConfig
6365

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)
6567

6668
### Properties
6769

@@ -78,7 +80,7 @@ const result = ApnsTransportConfigSchema.parse(data);
7880

7981
## FcmTransportConfig
8082

81-
[PLANNED — not yet read] FCM HTTP v1 transport (service-account JSON by reference)
83+
FCM HTTP v1 transport (service-account JSON by reference)
8284

8385
### Properties
8486

@@ -92,7 +94,7 @@ const result = ApnsTransportConfigSchema.parse(data);
9294

9395
## PushServiceConfig
9496

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
9698

9799
### Properties
98100

‎docs/adr/0012-notification-platform.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# ADR-0012: Messaging Platform — Outbound Notifications on a Generalized Outbox
22

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.
44
**Authors**: Platform team — surfaced from GitHub Issue #1292 ("[P0] notification: no outbound notification channel")
55
**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
66
**Sibling**: [ADR-0013 — Bidirectional Messaging & Conversational Channels](./0013-bidirectional-messaging.md)
@@ -306,7 +306,7 @@ These cost ~5 columns and one empty table in M1. They are non-negotiable: introd
306306
| `inbox` | `plugin-notification-inbox` | Writes to `sys_inbox_message`; fires `service-realtime` event for online users | **MUST ship M1** |
307307
| `email` | `plugin-notification-email` (replaces `plugin-email`) | SMTP + transport plugins (SendGrid baseline) | **MUST ship M1** |
308308
| `webhook` | `plugin-notification-webhook` (extracted from `plugin-webhooks`) | HTTP POST with HMAC | **MUST ship M1** (port existing) |
309-
| `push` | `plugin-notification-push` | APNs (HTTP/2) + FCM (HTTP v1) | **MUST ship M1** |
309+
| `push` | `service-push` (transports) + `push-channel.ts` in `service-messaging` (channel); amended 2026-11-03, #29041 | APNs (HTTP/2, token auth) + FCM (HTTP v1) | Shipped (#29041) |
310310

311311
All four bind into `channel-registry` during `onEnable`.
312312

@@ -375,7 +375,8 @@ Lifecycle hooks:
375375

376376
* Client SDK calls `POST /api/v1/notifications/devices` on login → `device-registry.upsert(...)`.
377377
* 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.
379380

380381
### 7. Topic + Preference matrix
381382

‎packages/services/service-automation/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@
4545
"@objectstack/refd-timer-testkit": "workspace:*",
4646
"@objectstack/service-job": "workspace:*",
4747
"@objectstack/service-messaging": "workspace:*",
48+
"@objectstack/service-push": "workspace:*",
4849
"@types/node": "^26.6.5",
4950
"tsx": "^4.23.15",
5051
"typescript": "^6.0.3",

0 commit comments

Comments
 (0)