@freecorps/ember-push 0.2.0 → 0.3.0

package/README.md

@@ -117,8 +117,26 @@ Urgency follows Brigade's relay as its README documents it (Brigade's `low`/`hig
   tried first, then the other one after `BadDeviceToken`. The one that works is recorded.
 - The APNs provider token (ES256 over the `.p8`) is reused for 40 minutes. The FCM access token (RS256
   service-account assertion) is kept until 5 minutes before it expires; concurrent sends share one exchange, and a
-  401 refetches it.
+  401 refetches it once for every send that saw the same token.
+- The token layer is usable on its own, around an app's own payloads: `apnsProviderToken(credentials, now, force)`
+  and `fcmAccessToken(options, force, signal)`. `force` is `true` (always new) or the token the provider just refused
+  (new only if the cache still holds it, so concurrent sends refresh once and a token another send already replaced
+  is reused).
 - 429 and 5xx answers and network errors are retried twice with backoff (`Retry-After` is honoured).
+- `timeoutMs` is a deadline for each send, retries and the token it needs included; `signal` aborts it. Either way the
+  ticket is `RequestFailed`. A caller's deadline only stops that caller waiting for a token exchange other sends share.
+- **An app's own payload** (its envelope, its keys): `AddressedPushMessage.payload = { apns?, fcmData? }` is sent as
+  given. `apns` is the whole JSON body (`aps` included; a body that is only `content-available` goes as a background
+  push); `fcmData` is a data message's `data`, string values only. Ember still sets the headers (push type, priority,
+  expiration, collapse id), the token, retries and error mapping. With `sendToDevices` and the component, a
+  `seal(device, message, provider)` hook in `PushTransports` returns that payload per direct device, or `null` for
+  Ember's own envelope; for the component, `setPushSeal(seal, installName?)` in the entry module (a function cannot
+  be part of the install config). Expo devices never reach it.
+- `sound: { critical: true, name?, volume? }` rings as an iOS Critical Alert (APNs' sound dictionary and
+  `interruption-level: critical`; needs Apple's entitlement); Android and Expo play `name`.
+- Error tickets from a direct send carry the provider's own `reason` (APNs' `reason`, FCM's `errorCode` or error
+  `status`) and `httpStatus`, for rules the codes below fold together (a token of another topic, a token FCM calls
+  malformed).
 
 | Answer | Code | Device |
 |---|---|---|

package/dist/apns.js

@@ -8,7 +8,7 @@
  * HTTP/2: APNs speaks nothing else. A deployed Worker's `fetch` reaches it (Brigade spike S1, Ember ops E2E R12);
  * local workerd (`ember dev`) does not, and fails with a network error. Test locally with a fake `fetch`.
  */
-import { DEFAULT_PUSH_FALLBACK, byteLength, fetchWithRetry, mapLimit, resolveInterruptionLevel, resolveTtlSeconds, resolveUrgency } from "./delivery.js";
+import { DEFAULT_PUSH_FALLBACK, apnsSound, byteLength, deadlineSignal, fetchWithRetry, mapLimit, resolveInterruptionLevel, resolveTtlSeconds, resolveUrgency, untilAborted } from "./delivery.js";
 import { importSigningKey, signJwt } from "./jwt.js";
 export const APNS_PRODUCTION_URL = "https://api.push.apple.com";
 export const APNS_SANDBOX_URL = "https://api.sandbox.push.apple.com";
@@ -96,6 +96,12 @@ export function clearApnsTokenCache() {
 export function apnsPushType(m) {
     if (m.voip)
         return "voip";
+    if (m.payload?.apns) {
+        // The app's own body: an alert unless it is only `content-available`.
+        const aps = (m.payload.apns.aps ?? {});
+        const shows = aps.alert !== undefined || aps.sound !== undefined || aps.badge !== undefined;
+        return !shows && aps["content-available"] === 1 ? "background" : "alert";
+    }
     if (m.sealed)
         return "alert";
     const visible = !!(m.title || m.subtitle || m.body || m.sound || m.badge !== undefined);
@@ -107,6 +113,9 @@ export function apnsPushType(m) {
  * Notification Service Extension runs) and the envelope under `ember`.
  */
 export function apnsPayload(m, fallback = DEFAULT_PUSH_FALLBACK) {
+    // The app built its own body (its envelope, its keys): sent as given.
+    if (m.payload?.apns)
+        return m.payload.apns;
     if (m.voip) {
         const out = { aps: {} };
         if (m.sealed)
@@ -142,8 +151,9 @@ export function apnsPayload(m, fallback = DEFAULT_PUSH_FALLBACK) {
         if (m.mutableContent)
             aps["mutable-content"] = 1;
     }
-    if (m.sound)
-        aps.sound = m.sound;
+    const sound = apnsSound(m.sound);
+    if (sound)
+        aps.sound = sound;
     if (m.badge !== undefined)
         aps.badge = m.badge;
     if (m.threadId)
@@ -191,12 +201,12 @@ export async function sendApns(messages, o) {
         throw new Error("@freecorps/ember-push: no fetch available; pass options.fetch");
     const now = o.now ?? Date.now;
     const urlFor = (env) => (env === "sandbox" ? (o.sandboxUrl ?? APNS_SANDBOX_URL) : (o.productionUrl ?? APNS_PRODUCTION_URL));
-    const attempt = async (m, env, body) => {
+    const attempt = async (m, env, body, signal) => {
         let refreshed = false;
         let stale = false;
         for (;;) {
-            const jwt = await apnsProviderToken(o, now(), stale);
-            const res = await fetchWithRetry(fetchFn, `${urlFor(env)}/3/device/${m.to}`, () => ({ method: "POST", headers: { ...apnsHeaders(m, o.topic, now()), authorization: `bearer ${jwt}` }, body }), o);
+            const jwt = await untilAborted(apnsProviderToken(o, now(), stale), signal);
+            const res = await fetchWithRetry(fetchFn, `${urlFor(env)}/3/device/${m.to}`, () => ({ method: "POST", headers: { ...apnsHeaders(m, o.topic, now()), authorization: `bearer ${jwt}` }, body }), o, signal);
             const id = res.headers.get("apns-id") ?? undefined;
             if (res.ok) {
                 await res.body?.cancel().catch(() => { });
@@ -231,11 +241,13 @@ export async function sendApns(messages, o) {
         const env = m.environment ?? o.environment ?? "production";
         let r;
         let usedEnv = env;
+        // One deadline for the whole send, both hosts included.
+        const signal = deadlineSignal(o);
         try {
-            r = await attempt(m, env, body);
+            r = await attempt(m, env, body, signal);
             if (!m.environment && r.reason === "BadDeviceToken") {
                 const other = env === "production" ? "sandbox" : "production";
-                const second = await attempt(m, other, body);
+                const second = await attempt(m, other, body, signal);
                 if (second.status === 200 || second.reason !== "BadDeviceToken") {
                     r = second;
                     usedEnv = other;
@@ -255,7 +267,14 @@ export async function sendApns(messages, o) {
                 ticket.environment = usedEnv;
             return ticket;
         }
-        return { token: m.to, status: "error", error: apnsErrorCode(r.status, r.reason), message: `APNs ${r.status} ${r.reason ?? ""}`.trim() };
+        return {
+            token: m.to,
+            status: "error",
+            error: apnsErrorCode(r.status, r.reason),
+            message: `APNs ${r.status} ${r.reason ?? ""}`.trim(),
+            ...(r.reason ? { reason: r.reason } : {}),
+            httpStatus: r.status,
+        };
     };
     return mapLimit(messages, o.concurrency ?? 10, sendOne);
 }

package/dist/component.d.ts

@@ -19,6 +19,7 @@
 import { type FunctionReference } from "@freecorps/ember-server";
 import type { ApnsOptions } from "./apns.ts";
 import { type PushDevice, type RegisterPushDeviceInput } from "./devices.ts";
+import { type PushTransports } from "./direct.ts";
 import type { FcmOptions } from "./fcm.ts";
 import type { ApnsEnvironment, PushEncryption, PushFallback, PushMessage } from "./types.ts";
 export type PushInstallConfig = {
@@ -59,6 +60,12 @@ export type PushInstallConfig = {
     /** What sealed pushes show in clear (default "New notification" / "Open the app to see it."). */
     fallback?: PushFallback;
 };
+/**
+ * An app with its own envelope: `seal` builds each direct (APNs/FCM) device's payload for the push component installed
+ * as `installName` (default `"push"`), as `PushTransports.seal` does for `sendToDevices`. Call it in the Worker's entry
+ * module, next to `createEmberWorker`; `null` removes it.
+ */
+export declare function setPushSeal(seal: PushTransports["seal"] | null, installName?: string): void;
 /** APNs options from the install config and the env, or the names of what is missing. */
 export declare function apnsOptionsFromEnv(env: Record<string, unknown>, c?: PushInstallConfig["apns"]): ApnsOptions | {
     missing: string[];

package/dist/component.js

@@ -21,6 +21,19 @@ import { pushDevicesForUser, pushDevicesForUsers, pushDevicesTable, pushTokensFo
 import { sendToDevices } from "./direct.js";
 import { checkPushReceipts } from "./expo.js";
 const schema = defineSchema({ tables: { devices: pushDevicesTable() } });
+/** Seal hooks by install name (`setPushSeal`): a function cannot be part of the install config, which holds values. */
+const sealHooks = new Map();
+/**
+ * An app with its own envelope: `seal` builds each direct (APNs/FCM) device's payload for the push component installed
+ * as `installName` (default `"push"`), as `PushTransports.seal` does for `sendToDevices`. Call it in the Worker's entry
+ * module, next to `createEmberWorker`; `null` removes it.
+ */
+export function setPushSeal(seal, installName = "push") {
+    if (seal)
+        sealHooks.set(installName, seal);
+    else
+        sealHooks.delete(installName);
+}
 const { query, mutation, action, internalAction, internalMutation, internalQuery } = componentBuilders();
 const TABLE = "devices";
 const RECEIPTS_DELAY = 15 * 60_000;
@@ -91,6 +104,9 @@ function transports(ctx, providers) {
         t.encryption = c.encryption;
     if (c.fallback)
         t.fallback = c.fallback;
+    const seal = sealHooks.get(ctx.component.name ?? "push");
+    if (seal)
+        t.seal = seal;
     return t;
 }
 const deviceArgs = {

package/dist/delivery.d.ts

@@ -4,7 +4,7 @@
  * TTL 15 min for its `page`, 1 h for `high`, 4 h for `low`, at most 30 days, 0 = try once; priority 5 only for `low`;
  * `time-sensitive` only for `page`. Ember names them `high`, `normal`, `low`.
  */
-import type { PushFallback, PushInterruptionLevel, PushMessage, PushUrgency } from "./types.ts";
+import type { PushCriticalSound, PushFallback, PushInterruptionLevel, PushMessage, PushUrgency } from "./types.ts";
 /** What a device shows for a sealed push it cannot open (and, with `encryption: "required"`, a device with no key). */
 export declare const DEFAULT_PUSH_FALLBACK: Required<Pick<PushFallback, "title" | "body">>;
 export declare const PUSH_TTL_DEFAULTS: Readonly<Record<PushUrgency, number>>;
@@ -13,7 +13,13 @@ export declare const PUSH_MAX_TTL_SECONDS: number;
 export declare function resolveUrgency(m: Pick<PushMessage, "urgency" | "priority">): PushUrgency;
 /** Seconds the push service keeps trying: `ttl` if given (clamped to 0..30 days), else the urgency's default. */
 export declare function resolveTtlSeconds(m: Pick<PushMessage, "urgency" | "priority" | "ttl">): number;
-export declare function resolveInterruptionLevel(m: Pick<PushMessage, "urgency" | "priority" | "interruptionLevel">): PushInterruptionLevel | undefined;
+export declare function resolveInterruptionLevel(m: Pick<PushMessage, "urgency" | "priority" | "interruptionLevel" | "sound">): PushInterruptionLevel | undefined;
+/** Whether `sound` asks for a Critical Alert. */
+export declare function isCriticalSound(sound: PushMessage["sound"]): sound is PushCriticalSound;
+/** APNs' `sound` value: the name, or the critical-sound dictionary. */
+export declare function apnsSound(sound: PushMessage["sound"]): string | Record<string, unknown> | undefined;
+/** The sound name for transports with no critical alerts (Android, Expo). */
+export declare function soundName(sound: PushMessage["sound"]): string | undefined;
 export declare const byteLength: (s: string) => number;
 /** Runs `fn` over `items` with at most `limit` in flight, keeping the result order. */
 export declare function mapLimit<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
@@ -22,9 +28,20 @@ export interface RetryOptions {
     retries?: number;
     retryDelayMs?: number;
     sleep?: (ms: number) => Promise<void>;
+    /** Aborts a send: every try and the waits between them. A send that stops this way answers `RequestFailed`. */
+    signal?: AbortSignal;
+    /**
+     * A deadline for each send, retries and the token it needs included (past it, the send stops with `RequestFailed`).
+     * A token exchange shared with other sends is not cut short by one caller's deadline: that caller stops waiting.
+     */
+    timeoutMs?: number;
 }
+/** The signal a send runs under: `signal` and `timeoutMs` together (undefined when neither is set). */
+export declare function deadlineSignal(o: Pick<RetryOptions, "signal" | "timeoutMs">): AbortSignal | undefined;
+/** `p`, or a rejection with `signal`'s reason once it aborts (`p` itself goes on; its outcome is still observed). */
+export declare function untilAborted<T>(p: Promise<T>, signal: AbortSignal | undefined): Promise<T>;
 /**
  * `fetch` with retries for transient answers. A `Retry-After` header (seconds) wins over the backoff. The last
  * response is returned whatever its status; a network error on the last try throws.
  */
-export declare function fetchWithRetry(fetchFn: typeof fetch, url: string, init: () => RequestInit, o?: RetryOptions): Promise<Response>;
+export declare function fetchWithRetry(fetchFn: typeof fetch, url: string, init: () => RequestInit, o?: RetryOptions, deadline?: AbortSignal | null | undefined): Promise<Response>;

package/dist/delivery.js

@@ -17,8 +17,29 @@ export function resolveTtlSeconds(m) {
 export function resolveInterruptionLevel(m) {
     if (m.interruptionLevel)
         return m.interruptionLevel;
+    if (isCriticalSound(m.sound))
+        return "critical";
     return resolveUrgency(m) === "high" ? "time-sensitive" : undefined;
 }
+/** Whether `sound` asks for a Critical Alert. */
+export function isCriticalSound(sound) {
+    return typeof sound === "object" && sound !== null && sound.critical === true;
+}
+/** APNs' `sound` value: the name, or the critical-sound dictionary. */
+export function apnsSound(sound) {
+    if (!sound)
+        return undefined;
+    if (!isCriticalSound(sound))
+        return sound;
+    const volume = sound.volume === undefined ? 1 : Math.min(1, Math.max(0, sound.volume));
+    return { critical: 1, name: sound.name ?? "default", volume };
+}
+/** The sound name for transports with no critical alerts (Android, Expo). */
+export function soundName(sound) {
+    if (!sound)
+        return undefined;
+    return isCriticalSound(sound) ? (sound.name ?? "default") : sound;
+}
 const utf8 = new TextEncoder();
 export const byteLength = (s) => utf8.encode(s).length;
 /** Runs `fn` over `items` with at most `limit` in flight, keeping the result order. */
@@ -37,22 +58,58 @@ export async function mapLimit(items, limit, fn) {
     return out;
 }
 const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** The signal a send runs under: `signal` and `timeoutMs` together (undefined when neither is set). */
+export function deadlineSignal(o) {
+    const parts = [];
+    if (o.signal)
+        parts.push(o.signal);
+    if (o.timeoutMs !== undefined)
+        parts.push(AbortSignal.timeout(Math.max(0, o.timeoutMs)));
+    if (parts.length <= 1)
+        return parts[0];
+    return AbortSignal.any(parts);
+}
+/** `p`, or a rejection with `signal`'s reason once it aborts (`p` itself goes on; its outcome is still observed). */
+export function untilAborted(p, signal) {
+    if (!signal)
+        return p;
+    if (signal.aborted) {
+        p.catch(() => { });
+        return Promise.reject(signal.reason);
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener("abort", onAbort, { once: true });
+        p.then((v) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(v);
+        }, (e) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(e);
+        });
+    });
+}
 /**
  * `fetch` with retries for transient answers. A `Retry-After` header (seconds) wins over the backoff. The last
  * response is returned whatever its status; a network error on the last try throws.
  */
-export async function fetchWithRetry(fetchFn, url, init, o = {}) {
+export async function fetchWithRetry(fetchFn, url, init, o = {}, 
+// `null`: no deadline at all (a token exchange other sends share, which has its own); omitted: `o`'s.
+deadline = deadlineSignal(o)) {
+    const signal = deadline ?? undefined;
     const retries = o.retries ?? 2;
-    const sleep = o.sleep ?? defaultSleep;
+    const sleep = (ms) => untilAborted((o.sleep ?? defaultSleep)(ms), signal);
     let delay = o.retryDelayMs ?? 1000;
     for (let attempt = 0;; attempt++) {
+        signal?.throwIfAborted();
         let res;
         try {
-            res = await fetchFn(url, init());
+            res = await fetchFn(url, signal ? { ...init(), signal } : init());
         }
         catch (e) {
-            if (attempt >= retries)
-                throw e;
+            // Aborted (the caller's signal or deadline): not a network error to retry.
+            if (signal?.aborted || attempt >= retries)
+                throw signal?.aborted ? signal.reason : e;
             await sleep(delay);
             delay *= 2;
             continue;

package/dist/direct.d.ts

@@ -15,7 +15,7 @@
 import { type ApnsOptions } from "./apns.ts";
 import { type ExpoPushOptions } from "./expo.ts";
 import { type FcmOptions } from "./fcm.ts";
-import type { ApnsEnvironment, PushEncryption, PushFallback, PushMessage, PushTicket } from "./types.ts";
+import type { ApnsEnvironment, PushEncryption, PushFallback, PushMessage, PushPayload, PushTicket } from "./types.ts";
 /** What `sendToDevices` needs of a device (a `PushDevice` row fits). */
 export interface PushTarget {
     token: string;
@@ -37,6 +37,12 @@ export interface PushTransports {
     encryption?: PushEncryption;
     /** What sealed pushes show in clear (and `required` sends to devices without a key). */
     fallback?: PushFallback;
+    /**
+     * An app with its own envelope: called for every direct (APNs/FCM) device, it returns the payload to send as given
+     * (`PushPayload`), or `null` for Ember's usual handling (its envelope, encryption mode and fallback). A throw is that
+     * device's `RequestFailed` ticket. Expo devices never reach it.
+     */
+    seal?: (device: PushTarget, message: PushMessage, provider: "apns" | "fcm") => PushPayload | null | Promise<PushPayload | null>;
     now?: () => number;
 }
 export interface DeviceSendResult {

package/dist/direct.js

@@ -73,6 +73,20 @@ export async function sendToDevices(targets, message, t = {}) {
         if (provider === "apns" && (target.environment === "sandbox" || target.environment === "production"))
             m.environment = target.environment;
         const direct = provider === "apns" || provider === "fcm";
+        if (direct && t.seal) {
+            let own;
+            try {
+                own = await t.seal(target, message, provider);
+            }
+            catch (e) {
+                tickets[i] = { token: to, status: "error", error: "RequestFailed", message: `seal hook: ${e.message}` };
+                return;
+            }
+            if (own) {
+                groups[provider].push({ i, m: { ...m, payload: own } });
+                return;
+            }
+        }
         const sealable = direct && !message.voip && hasVisibleContent(message);
         if (mode !== "off" && sealable && target.publicKey) {
             try {

package/dist/expo.d.ts

@@ -1,8 +1,3 @@
-/**
- * Expo Push Service client (plain HTTPS + JSON, so it runs in a Worker action). Facts (docs.expo.dev, checked in
- * CLOUDFLARE.md §8): 100 messages per request, 600 notifications/s per project, 4096-byte payload, receipts kept
- * 24 h, optional access token ("enhanced push security").
- */
 import type { AddressedPushMessage, PushMessage, PushProvider, PushTicket, ReceiptCheck, SendPushResult } from "./types.ts";
 export declare const EXPO_PUSH_URL = "https://exp.host/--/api/v2/push/send";
 export declare const EXPO_RECEIPTS_URL = "https://exp.host/--/api/v2/push/getReceipts";

package/dist/expo.js

@@ -1,3 +1,9 @@
+/**
+ * Expo Push Service client (plain HTTPS + JSON, so it runs in a Worker action). Facts (docs.expo.dev, checked in
+ * CLOUDFLARE.md §8): 100 messages per request, 600 notifications/s per project, 4096-byte payload, receipts kept
+ * 24 h, optional access token ("enhanced push security").
+ */
+import { soundName } from "./delivery.js";
 export const EXPO_PUSH_URL = "https://exp.host/--/api/v2/push/send";
 export const EXPO_RECEIPTS_URL = "https://exp.host/--/api/v2/push/getReceipts";
 /** Messages per `send` request. */
@@ -21,11 +27,15 @@ export function isExpoPushToken(token) {
  * else `high`).
  */
 export function toExpoMessage(m) {
-    const { contentAvailable, urgency, encryption, voip, environment, sealed, ...rest } = m;
+    const { contentAvailable, urgency, encryption, voip, environment, sealed, payload, ...rest } = m;
+    void payload; // the app's own APNs/FCM payload: Expo builds its own
     const out = {};
     for (const [k, val] of Object.entries(rest))
         if (val !== undefined)
             out[k] = val;
+    // Expo takes a sound name: a Critical Alert sound plays its name there.
+    if (typeof out.sound === "object" && out.sound !== null)
+        out.sound = soundName(out.sound) ?? "default";
     if (contentAvailable)
         out._contentAvailable = true;
     if (urgency && out.priority === undefined)

package/dist/fcm.d.ts

@@ -17,6 +17,11 @@ export declare const FCM_MAX_PAYLOAD = 4096;
 export declare const FCM_MAX_TTL_SECONDS: number;
 /** An access token is refetched this long before it expires. */
 export declare const FCM_TOKEN_MARGIN_MS: number;
+/**
+ * The longest a token exchange may take, retries included. It is shared by every send waiting for it, so it has its
+ * own limit, never a caller's `timeoutMs` or `signal` (a caller with a short deadline only stops its own wait).
+ */
+export declare const FCM_EXCHANGE_TIMEOUT_MS = 30000;
 /** The fields of a Google service-account JSON key that sending needs. */
 export interface ServiceAccount {
     project_id: string;
@@ -48,9 +53,13 @@ export declare function fcmErrorCode(status: number, errorCode: string | undefin
 export declare function clearFcmTokenCache(): void;
 /**
  * An OAuth access token for the service account (scope `firebase.messaging`): an RS256 assertion exchanged at the
- * token endpoint, cached per isolate until `FCM_TOKEN_MARGIN_MS` before it expires.
+ * token endpoint, cached per isolate until `FCM_TOKEN_MARGIN_MS` before it expires. `force` exchanges again: `true`
+ * always; a token string only if the cache still holds that token (after FCM answered 401 to it, so concurrent sends
+ * that saw the same refused token exchange once, and a token another send already replaced is used as is).
+ * Concurrent callers share one exchange. `signal` (default: `o.signal` and `o.timeoutMs`) bounds this caller's wait
+ * only; the shared exchange runs under its own `FCM_EXCHANGE_TIMEOUT_MS`, whoever started it.
  */
-export declare function fcmAccessToken(o: FcmOptions, force?: boolean): Promise<string>;
+export declare function fcmAccessToken(o: FcmOptions, force?: boolean | string, signal?: AbortSignal | undefined): Promise<string>;
 /**
  * The v1 `message` for one push. In clear: a `notification` (title/body; the system shows it while the app is in the
  * background) and `data.body` = JSON of `data`, where expo-notifications reads it on Android. Sealed: a data-only

package/dist/fcm.js

@@ -7,7 +7,7 @@
  *
  * FCM speaks HTTP/1.1, so unlike APNs this also works from local workerd (`ember dev`).
  */
-import { DEFAULT_PUSH_FALLBACK, byteLength, fetchWithRetry, mapLimit, resolveTtlSeconds, resolveUrgency } from "./delivery.js";
+import { DEFAULT_PUSH_FALLBACK, byteLength, deadlineSignal, soundName, fetchWithRetry, mapLimit, resolveTtlSeconds, resolveUrgency, untilAborted } from "./delivery.js";
 import { isExpoPushToken } from "./expo.js";
 import { importSigningKey, signJwt } from "./jwt.js";
 export const FCM_SEND_URL = (projectId) => `https://fcm.googleapis.com/v1/projects/${encodeURIComponent(projectId)}/messages:send`;
@@ -18,6 +18,11 @@ export const FCM_MAX_PAYLOAD = 4096;
 export const FCM_MAX_TTL_SECONDS = 28 * 24 * 3600;
 /** An access token is refetched this long before it expires. */
 export const FCM_TOKEN_MARGIN_MS = 5 * 60_000;
+/**
+ * The longest a token exchange may take, retries included. It is shared by every send waiting for it, so it has its
+ * own limit, never a caller's `timeoutMs` or `signal` (a caller with a short deadline only stops its own wait).
+ */
+export const FCM_EXCHANGE_TIMEOUT_MS = 30_000;
 /** Parses and checks a service-account key; throws a message naming what is missing (never echoing the key). */
 export function parseServiceAccount(value) {
     let sa = value;
@@ -68,34 +73,38 @@ export function clearFcmTokenCache() {
 }
 /**
  * An OAuth access token for the service account (scope `firebase.messaging`): an RS256 assertion exchanged at the
- * token endpoint, cached per isolate until `FCM_TOKEN_MARGIN_MS` before it expires.
+ * token endpoint, cached per isolate until `FCM_TOKEN_MARGIN_MS` before it expires. `force` exchanges again: `true`
+ * always; a token string only if the cache still holds that token (after FCM answered 401 to it, so concurrent sends
+ * that saw the same refused token exchange once, and a token another send already replaced is used as is).
+ * Concurrent callers share one exchange. `signal` (default: `o.signal` and `o.timeoutMs`) bounds this caller's wait
+ * only; the shared exchange runs under its own `FCM_EXCHANGE_TIMEOUT_MS`, whoever started it.
  */
-export async function fcmAccessToken(o, force = false) {
+export async function fcmAccessToken(o, force = false, signal = deadlineSignal(o)) {
     const sa = parseServiceAccount(o.serviceAccount);
     const now = (o.now ?? Date.now)();
     const tokenUrl = o.tokenUrl ?? sa.token_uri ?? GOOGLE_TOKEN_URL;
     const cacheKey = `${sa.client_email}\u0000${sa.private_key_id ?? ""}\u0000${tokenUrl}`;
     const hit = accessTokens.get(cacheKey);
-    if (!force && hit && now < hit.expiresAt - FCM_TOKEN_MARGIN_MS)
+    const fresh = !!hit && now < hit.expiresAt - FCM_TOKEN_MARGIN_MS;
+    const refresh = force === true || (typeof force === "string" && hit?.token === force);
+    if (fresh && !refresh)
         return hit.token;
     // Concurrent sends share one exchange instead of each fetching a token.
-    const pending = inFlight.get(cacheKey);
-    if (pending)
-        return pending;
-    const p = exchange(o, sa, tokenUrl, now).then((t) => {
-        accessTokens.set(cacheKey, t);
-        return t.token;
-    });
-    inFlight.set(cacheKey, p);
-    try {
-        return await p;
-    }
-    finally {
-        inFlight.delete(cacheKey);
+    let p = inFlight.get(cacheKey);
+    if (!p) {
+        // Never the starter's deadline: other sends wait on this exchange too.
+        const started = exchange(o, sa, tokenUrl, now, AbortSignal.timeout(FCM_EXCHANGE_TIMEOUT_MS)).then((t) => {
+            accessTokens.set(cacheKey, t);
+            return t.token;
+        });
+        p = started;
+        inFlight.set(cacheKey, started);
+        started.then(() => inFlight.delete(cacheKey), () => inFlight.delete(cacheKey));
     }
+    return untilAborted(p, signal);
 }
 const inFlight = new Map();
-async function exchange(o, sa, tokenUrl, now) {
+async function exchange(o, sa, tokenUrl, now, signal) {
     const key = await importSigningKey(sa.private_key, "RS256");
     const iat = Math.floor(now / 1000);
     const assertion = await signJwt("RS256", key, { iss: sa.client_email, scope: FCM_SCOPE, aud: tokenUrl, iat, exp: iat + 3600 }, sa.private_key_id ? { kid: sa.private_key_id } : {});
@@ -104,7 +113,7 @@ async function exchange(o, sa, tokenUrl, now) {
         method: "POST",
         headers: { "content-type": "application/x-www-form-urlencoded" },
         body: new URLSearchParams({ grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer", assertion }).toString(),
-    }), o);
+    }), o, signal);
     const body = (await res.json().catch(() => ({})));
     if (!res.ok || !body.access_token) {
         throw Object.assign(new Error(`Google token endpoint: ${res.status} ${body.error ?? ""} ${body.error_description ?? ""}`.trim()), { credentials: res.status === 400 || res.status === 401 });
@@ -124,6 +133,11 @@ export function fcmMessage(m, fallback = DEFAULT_PUSH_FALLBACK) {
     if (m.collapseId)
         android.collapse_key = m.collapseId;
     const message = { token: m.to, android };
+    // The app built its own data message (its envelope, its keys): sent as given, with Ember's priority, TTL and collapse key.
+    if (m.payload?.fcmData) {
+        message.data = m.payload.fcmData;
+        return message;
+    }
     if (m.sealed) {
         const data = { ember: JSON.stringify(m.sealed), urgency };
         if (fallback.title)
@@ -147,8 +161,9 @@ export function fcmMessage(m, fallback = DEFAULT_PUSH_FALLBACK) {
         const an = {};
         if (m.channelId)
             an.channel_id = m.channelId;
-        if (m.sound)
-            an.sound = m.sound;
+        const sound = soundName(m.sound);
+        if (sound)
+            an.sound = sound;
         if (m.collapseId)
             an.tag = m.collapseId;
         if (m.badge !== undefined)
@@ -180,25 +195,39 @@ export async function sendFcm(messages, o) {
     const sendOne = async (m) => {
         if (!isFcmToken(m.to))
             return { token: String(m.to), status: "error", error: "InvalidToken", message: "not an FCM registration token" };
+        const own = m.payload?.fcmData;
+        if (own && Object.values(own).some((x) => typeof x !== "string")) {
+            return { token: m.to, status: "error", error: "InvalidArgument", message: "payload.fcmData values must be strings (FCM data messages)" };
+        }
         const message = fcmMessage(m, o.fallback);
         const body = JSON.stringify({ message });
         if (byteLength(JSON.stringify({ n: message.notification, d: message.data })) > FCM_MAX_PAYLOAD) {
             return { token: m.to, status: "error", error: "MessageTooBig", message: `FCM payload over ${FCM_MAX_PAYLOAD} bytes` };
         }
-        let refreshed = false;
+        // One deadline for the whole send: the access token and every try.
+        const signal = deadlineSignal(o);
+        let refused;
         try {
             for (;;) {
-                const access = await fcmAccessToken(o, refreshed);
-                const res = await fetchWithRetry(fetchFn, url, () => ({ method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${access}` }, body }), o);
+                const access = await fcmAccessToken(o, refused ?? false, signal);
+                const res = await fetchWithRetry(fetchFn, url, () => ({ method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${access}` }, body }), o, signal);
                 const json = (await res.json().catch(() => ({})));
                 if (res.ok)
                     return { token: m.to, status: "ok", id: json.name ?? "" };
-                if (res.status === 401 && !refreshed) {
-                    refreshed = true;
+                if (res.status === 401 && refused === undefined) {
+                    // A new token, unless another send already replaced this one; never this refused one again.
+                    refused = access;
                     continue;
                 }
                 const errorCode = json.error?.details?.find((d) => d.errorCode)?.errorCode ?? json.error?.status;
-                return { token: m.to, status: "error", error: fcmErrorCode(res.status, errorCode), message: `FCM ${res.status} ${errorCode ?? ""}: ${json.error?.message ?? ""}`.trim() };
+                return {
+                    token: m.to,
+                    status: "error",
+                    error: fcmErrorCode(res.status, errorCode),
+                    message: `FCM ${res.status} ${errorCode ?? ""}: ${json.error?.message ?? ""}`.trim(),
+                    ...(errorCode ? { reason: errorCode } : {}),
+                    httpStatus: res.status,
+                };
             }
         }
         catch (e) {

package/dist/index.d.ts

@@ -16,7 +16,7 @@ export { generateRecipient, importKeyPair, open, seal, P256_PUBLIC_KEY_LENGTH, t
 export { EMBER_PUSH_ENVELOPE_VERSION, EMBER_PUSH_HPKE_INFO, PUSH_KEY_ID, PUSH_PLAINTEXT_MAX_BYTES, isDevicePublicKey, openPushEnvelope, parseDevicePublicKey, parseOpenedContent, parsePushEnvelope, pushKeyId, sealPushContent, type EncryptedPushContent, type OpenedPushContent, type PushEnvelope, } from "./envelope.ts";
 export { EXPO_MAX_PAYLOAD, EXPO_PUSH_URL, EXPO_RECEIPTS_CHUNK, EXPO_RECEIPTS_URL, EXPO_SEND_CHUNK, checkPushReceipts, expoPushProvider, isExpoPushToken, payloadSize, sendExpoMessages, sendPush, toExpoMessage, type ExpoPushOptions, } from "./expo.ts";
 export { PUSH_DEVICES_TABLE, inferPushProvider, isPushProviderName, pushDevicesForUser, pushDevicesForUsers, pushDevicesTable, pushTokensForUsers, registerPushDevice, removePushTokens, removeVoipTokens, setPushDeviceEnvironment, unregisterPushDevice, type PushDevice, type PushProviderName, type RegisterPushDeviceInput, } from "./devices.ts";
-export { apnsOptionsFromEnv, fcmOptionsFromEnv, pushComponent, pushFunctions, PushNotifications, type PushComponentApi, type PushInstallConfig, type DeliveryResult } from "./component.ts";
+export { apnsOptionsFromEnv, fcmOptionsFromEnv, pushComponent, pushFunctions, PushNotifications, setPushSeal, type PushComponentApi, type PushInstallConfig, type DeliveryResult } from "./component.ts";
 export { decodeJwt, importSigningKey, pemToDer, signJwt, verifyJwt, type CredentialsError, type JwtAlgorithm } from "./jwt.ts";
 export { DEFAULT_PUSH_FALLBACK, PUSH_MAX_TTL_SECONDS, PUSH_TTL_DEFAULTS, resolveInterruptionLevel, resolveTtlSeconds, resolveUrgency } from "./delivery.ts";
 export { APNS_MAX_PAYLOAD, APNS_PRODUCTION_URL, APNS_SANDBOX_URL, APNS_TOKEN_REFRESH_MS, APNS_VOIP_MAX_PAYLOAD, apnsErrorCode, apnsHeaders, apnsPayload, apnsProviderToken, apnsPushProvider, apnsPushType, clearApnsTokenCache, isApnsToken, sendApns, type ApnsCredentials, type ApnsOptions, } from "./apns.ts";

package/dist/index.js

@@ -16,7 +16,7 @@ export { generateRecipient, importKeyPair, open, seal, P256_PUBLIC_KEY_LENGTH }
 export { EMBER_PUSH_ENVELOPE_VERSION, EMBER_PUSH_HPKE_INFO, PUSH_KEY_ID, PUSH_PLAINTEXT_MAX_BYTES, isDevicePublicKey, openPushEnvelope, parseDevicePublicKey, parseOpenedContent, parsePushEnvelope, pushKeyId, sealPushContent, } from "./envelope.js";
 export { EXPO_MAX_PAYLOAD, EXPO_PUSH_URL, EXPO_RECEIPTS_CHUNK, EXPO_RECEIPTS_URL, EXPO_SEND_CHUNK, checkPushReceipts, expoPushProvider, isExpoPushToken, payloadSize, sendExpoMessages, sendPush, toExpoMessage, } from "./expo.js";
 export { PUSH_DEVICES_TABLE, inferPushProvider, isPushProviderName, pushDevicesForUser, pushDevicesForUsers, pushDevicesTable, pushTokensForUsers, registerPushDevice, removePushTokens, removeVoipTokens, setPushDeviceEnvironment, unregisterPushDevice, } from "./devices.js";
-export { apnsOptionsFromEnv, fcmOptionsFromEnv, pushComponent, pushFunctions, PushNotifications } from "./component.js";
+export { apnsOptionsFromEnv, fcmOptionsFromEnv, pushComponent, pushFunctions, PushNotifications, setPushSeal } from "./component.js";
 export { decodeJwt, importSigningKey, pemToDer, signJwt, verifyJwt } from "./jwt.js";
 export { DEFAULT_PUSH_FALLBACK, PUSH_MAX_TTL_SECONDS, PUSH_TTL_DEFAULTS, resolveInterruptionLevel, resolveTtlSeconds, resolveUrgency } from "./delivery.js";
 export { APNS_MAX_PAYLOAD, APNS_PRODUCTION_URL, APNS_SANDBOX_URL, APNS_TOKEN_REFRESH_MS, APNS_VOIP_MAX_PAYLOAD, apnsErrorCode, apnsHeaders, apnsPayload, apnsProviderToken, apnsPushProvider, apnsPushType, clearApnsTokenCache, isApnsToken, sendApns, } from "./apns.js";

package/dist/types.d.ts

@@ -25,6 +25,27 @@ export type ApnsEnvironment = "sandbox" | "production";
  * - `required`: sealed; a device without a key (or an Expo token) gets only the fallback text.
  */
 export type PushEncryption = "off" | "auto" | "required";
+/**
+ * iOS Critical Alert sound (the app needs Apple's Critical Alerts entitlement): plays even on silent and through Focus.
+ * APNs gets `{ critical: 1, name, volume }` and `interruption-level: critical`; Android and Expo play `name`.
+ */
+export interface PushCriticalSound {
+    critical: true;
+    /** Sound file in the app bundle (default `"default"`). */
+    name?: string;
+    /** 0 to 1 (default 1). */
+    volume?: number;
+}
+/**
+ * A payload the app built itself (its own envelope and keys), sent as given by the direct transports. Ember still sets
+ * the headers (push type, priority, expiration, collapse id), the provider token, retries and error mapping.
+ * `apns`: the whole JSON body (`aps` included). `fcmData`: an FCM data message's `data` (string values only).
+ * A transport without its part builds the message from the other fields as usual; Expo ignores both.
+ */
+export interface PushPayload {
+    apns?: Record<string, unknown>;
+    fcmData?: Record<string, string>;
+}
 /** What a notification says. Fields a provider does not support are ignored by it. */
 export interface PushMessage {
     title?: string;
@@ -32,8 +53,8 @@ export interface PushMessage {
     body?: string;
     /** Delivered to the app (JSON object). Counts toward the 4 KiB payload limit. */
     data?: Record<string, unknown>;
-    /** `"default"` plays the default sound (iOS). */
-    sound?: "default" | null;
+    /** `"default"` plays the default sound (iOS); a `PushCriticalSound` rings as a Critical Alert. */
+    sound?: "default" | null | PushCriticalSound;
     /** iOS app icon badge; 0 clears it. */
     badge?: number;
     /** Android notification channel (created by the app, e.g. `registerForPush` creates `"default"`). */
@@ -73,6 +94,8 @@ export interface AddressedPushMessage extends PushMessage {
      * fallback text instead of title/subtitle/body/data.
      */
     sealed?: PushEnvelope;
+    /** The app's own payload for this device (see `PushPayload`); wins over `sealed` and the content fields. */
+    payload?: PushPayload;
 }
 /** What a device shows when an encrypted push cannot be opened (or, with `encryption: "required"`, has no key). */
 export interface PushFallback {
@@ -97,6 +120,14 @@ export type PushTicket =
     status: "error";
     message: string;
     error?: PushErrorCode;
+    /**
+     * The provider's own reason, as it said it (direct sends): APNs' `reason` (`DeviceTokenNotForTopic`,
+     * `BadDeviceToken`, …) or FCM's `errorCode` / error `status` (`UNREGISTERED`, `INVALID_ARGUMENT`, …). For
+     * rules Ember's codes fold together (a token of another topic, a token FCM calls malformed).
+     */
+    reason?: string;
+    /** The provider's HTTP status (direct sends). */
+    httpStatus?: number;
 };
 /** Final delivery outcome reported by the provider (Expo keeps receipts for 24 h). */
 export type PushReceipt = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freecorps/ember-push",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Push notifications for Ember: device registry, Expo Push, direct APNs + FCM, end-to-end encrypted payloads (HPKE), and a push component.",
   "keywords": [
     "apns",
@@ -45,7 +45,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@freecorps/ember-server": "0.2.0",
-    "@freecorps/ember-values": "0.2.0"
+    "@freecorps/ember-server": "0.3.0",
+    "@freecorps/ember-values": "0.3.0"
   }
 }