diff --git a/.changeset/29960-push-vendor-docblocks.md b/.changeset/29960-push-vendor-docblocks.md new file mode 100644 index 00000000000..3d5038e5c02 --- /dev/null +++ b/.changeset/29960-push-vendor-docblocks.md @@ -0,0 +1,10 @@ +--- +'@objectstack/spec': patch +--- + +docs(spec): the push vendor docblocks read ADR-0012 §6.1 as amended + +Clause-②: no +Metadata-protocol: none + +The `PushVendorSchema` docblock and the push transport and stored device docblocks (`system/push-config.zod.ts`, `system/push-device.zod.ts`) no longer say the domestic Android vendors plug in as alternate channel plugins. They now say what ADR-0012 §6.1 decides: `vendor` is the token type the sender routes on (the direct transport today, the hosted relay, the default, once served), core ships `apns` and `fcm`, and phase 2 adds HMS / Honor / Xiaomi / OPPO / vivo behind the relay, with no per-vendor plugin and no per-vendor channel. A new `PushVendorSchema` value is still a spec change made together with the relay's routing for that vendor. Comment text only: no schema, `.describe()`, export or default changes, and `PushVendorSchema` stays `apns | fcm`. diff --git a/content/docs/kernel/runtime-services/push-service.mdx b/content/docs/kernel/runtime-services/push-service.mdx index 4c977e6d152..c2833d010bd 100644 --- a/content/docs/kernel/runtime-services/push-service.mdx +++ b/content/docs/kernel/runtime-services/push-service.mdx @@ -85,8 +85,11 @@ service its server gets. Each vendor block is optional, and at least one is required. A vendor with no block is a vendor this deployment does not push to; devices registered on it are -skipped. Other Android vendors (HMS, Xiaomi, OPPO, vivo) are not transports of -this service: they plug in as separate channel implementations. +skipped. Only `apns` and `fcm` ship today. The other Android vendors (HMS / +Honor / Xiaomi / OPPO / vivo) are planned for a later phase behind the hosted +relay (below), as further values of `vendor`, the token type the sender routes +on (this service's transports today, the relay once it is served), and not as +plugins or channels of their own. ### Credential references diff --git a/content/docs/references/system/push-config.mdx b/content/docs/references/system/push-config.mdx index 5ccd654f6eb..c79d137a31f 100644 --- a/content/docs/references/system/push-config.mdx +++ b/content/docs/references/system/push-config.mdx @@ -82,8 +82,10 @@ constructor instead. No `OS_PUSH_*` environment variable carries any of it: the vendor blocks hold no secret to override, and each `credentialRef` already names one. -Out of scope here: the other vendors ADR-0012 §6 routes to alternate -channel plugins (HMS, Xiaomi, OPPO, vivo). +Out of scope here: the domestic Android vendors (HMS / Honor / Xiaomi / +OPPO / vivo). ADR-0012 §6.1 has the hosted relay front them in phase 2, as +further values of `vendor`, the token type the sender routes on; there is +no per-vendor plugin and no per-vendor channel. **Source:** `packages/spec/src/system/push-config.zod.ts` diff --git a/packages/spec/src/api/register-device-request.test.ts b/packages/spec/src/api/register-device-request.test.ts index 634859e1675..54e1a06bcd6 100644 --- a/packages/spec/src/api/register-device-request.test.ts +++ b/packages/spec/src/api/register-device-request.test.ts @@ -4,8 +4,9 @@ // §6): it gains an optional `vendor`, `appId` and `locale`. Pure widening, so // the body every client sends today must keep parsing unchanged, and the new // members are optional. The one value the widening refuses is a vendor -// outside the pair core delivers through (`apns` / `fcm`); other vendors are -// alternate channel plugins (ADR-0012 §6), not values of this field. +// outside the pair core delivers through (`apns` / `fcm`); the domestic +// Android vendors arrive in phase 2 as further values of `PushVendorSchema`, +// routed by the hosted relay (ADR-0012 §6.1), not as channel plugins. import { describe, it, expect } from 'vitest'; import { diff --git a/packages/spec/src/system/push-config.zod.ts b/packages/spec/src/system/push-config.zod.ts index 662359ef7f4..cbda375977c 100644 --- a/packages/spec/src/system/push-config.zod.ts +++ b/packages/spec/src/system/push-config.zod.ts @@ -82,16 +82,22 @@ import { strictObject } from '../shared/strict-object'; * it: the vendor blocks hold no secret to override, and each `credentialRef` * already names one. * - * Out of scope here: the other vendors ADR-0012 §6 routes to alternate - * channel plugins (HMS, Xiaomi, OPPO, vivo). + * Out of scope here: the domestic Android vendors (HMS / Honor / Xiaomi / + * OPPO / vivo). ADR-0012 §6.1 has the hosted relay front them in phase 2, as + * further values of `vendor`, the token type the sender routes on; there is + * no per-vendor plugin and no per-vendor channel. */ /** * Push vendors core delivers through: `apns` (Apple) and `fcm` (Firebase). * - * Closed on purpose. ADR-0012 §6 plugs the domestic Android vendors in as - * alternate channel implementations, not as transports of this channel, so a - * new value here is a spec change made together with its transport. + * Closed on purpose. `vendor` is the token type the sender routes on: the + * direct transport today, the hosted relay (the default) once served (ADR-0012 + * §6.1). Phase 1 routes these two, and phase 2 adds the domestic Android + * vendors (HMS / Honor / Xiaomi / OPPO / vivo) behind the relay, with no + * per-vendor plugin and no per-vendor channel. So a new value here is + * a spec change made together with its transport: the relay's routing for + * that vendor. */ export const PushVendorSchema = z.enum(['apns', 'fcm']) .describe('Push vendor core delivers through: apns (Apple Push Notification service) or fcm (Firebase Cloud Messaging HTTP v1)'); diff --git a/packages/spec/src/system/push-device.zod.ts b/packages/spec/src/system/push-device.zod.ts index 9fcde1a3b58..3e39a9d8c29 100644 --- a/packages/spec/src/system/push-device.zod.ts +++ b/packages/spec/src/system/push-device.zod.ts @@ -46,8 +46,11 @@ import { PUSH_SERVER_ORIGIN_MESSAGE, PUSH_SERVER_ORIGIN_PATTERN } from './push-s * row, and a later registration of the same device re-enables it and clears * `invalidatedAt`. * - * Narrowed from ADR-0012 §6: `vendor` is the core pair (`apns` | `fcm`; the - * domestic Android vendors plug in as alternate channel implementations) and + * Narrowed from the ADR-0012 §6 sketch: `vendor` is the core pair (`apns` | + * `fcm`; it is the token type the sender routes on: the direct transport + * today, the hosted relay (the default) once served, and the domestic Android + * vendors (HMS / Honor / Xiaomi / OPPO / vivo) join it in phase 2 behind the + * relay, ADR-0012 §6.1) and * `platform` is the registration's own three (`ios` | `android` | `web`). */ export const UserDeviceSchema = lazySchema(() => z.object({