@freecorps/ember-push 0.1.0 → 0.3.0

package/dist/delivery.js

@@ -0,0 +1,126 @@
+/** What a device shows for a sealed push it cannot open (and, with `encryption: "required"`, a device with no key). */
+export const DEFAULT_PUSH_FALLBACK = { title: "New notification", body: "Open the app to see it." };
+export const PUSH_TTL_DEFAULTS = { low: 4 * 3600, normal: 3600, high: 15 * 60 };
+/** APNs keeps an undelivered push about 30 days at most (and FCM's limit is 28 days, which `fcm.ts` clamps to). */
+export const PUSH_MAX_TTL_SECONDS = 30 * 24 * 3600;
+export function resolveUrgency(m) {
+    if (m.urgency)
+        return m.urgency;
+    return m.priority === "normal" ? "low" : "normal";
+}
+/** Seconds the push service keeps trying: `ttl` if given (clamped to 0..30 days), else the urgency's default. */
+export function resolveTtlSeconds(m) {
+    if (m.ttl === undefined || m.ttl === null || !Number.isFinite(m.ttl))
+        return PUSH_TTL_DEFAULTS[resolveUrgency(m)];
+    return Math.min(PUSH_MAX_TTL_SECONDS, Math.max(0, Math.floor(m.ttl)));
+}
+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. */
+export async function mapLimit(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            out[i] = await fn(items[i], i);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
+    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 = {}, 
+// `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 = (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, signal ? { ...init(), signal } : init());
+        }
+        catch (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;
+        }
+        if ((res.status === 429 || res.status >= 500) && attempt < retries) {
+            const ra = Number(res.headers.get("retry-after"));
+            await res.body?.cancel().catch(() => { });
+            await sleep(Number.isFinite(ra) && ra > 0 ? ra * 1000 : delay);
+            delay *= 2;
+            continue;
+        }
+        return res;
+    }
+}

package/dist/devices.d.ts

@@ -1,5 +1,13 @@
+import type { ApnsEnvironment } from "./types.ts";
 export declare const PUSH_DEVICES_TABLE = "pushDevices";
-/** `{ userId, token, provider, platform?, deviceName?, updatedAt }` with `by_user` and `by_token` indexes. */
+export type PushProviderName = "expo" | "apns" | "fcm";
+/** Whether `p` is a provider `sendToDevices` knows (`expo`, `apns`, `fcm`; exact case). */
+export declare function isPushProviderName(p: unknown): p is PushProviderName;
+/**
+ * `{ userId, token, provider, platform?, deviceName?, environment?, voipToken?, publicKey?, updatedAt }` with
+ * `by_user` and `by_token` indexes. The direct-transport fields are optional, so an existing table gains them with no
+ * migration.
+ */
 export declare function pushDevicesTable(): import("@freecorps/ember-server").TableDefinition<import("@freecorps/ember-values").ObjectValidator<{
     userId: import("@freecorps/ember-values").Validator<string, "required", never>;
     token: import("@freecorps/ember-values").Validator<string, "required", never>;
@@ -7,6 +15,12 @@ export declare function pushDevicesTable(): import("@freecorps/ember-server").Ta
     provider: import("@freecorps/ember-values").Validator<string, "required", never>;
     platform: import("@freecorps/ember-values").Validator<string, "optional", never>;
     deviceName: import("@freecorps/ember-values").Validator<string, "optional", never>;
+    /** APNs environment of an iOS token: "sandbox" | "production". */
+    environment: import("@freecorps/ember-values").Validator<string, "optional", never>;
+    /** iOS PushKit token (VoIP pushes, `voip: true`). */
+    voipToken: import("@freecorps/ember-values").Validator<string, "optional", never>;
+    /** Device public key for sealed pushes (uncompressed P-256, base64url). */
+    publicKey: import("@freecorps/ember-values").Validator<string, "optional", never>;
     /** ms since epoch of the last registration (stale devices can be pruned). */
     updatedAt: import("@freecorps/ember-values").Validator<number, "required", never>;
 }>, {
@@ -21,6 +35,9 @@ export interface PushDevice {
     provider: string;
     platform?: string;
     deviceName?: string;
+    environment?: ApnsEnvironment;
+    voipToken?: string;
+    publicKey?: string;
     updatedAt: number;
 }
 /**
@@ -43,13 +60,20 @@ type WriterDb = Db & {
 export interface RegisterPushDeviceInput {
     userId: string;
     token: string;
+    /** Default: inferred from the token (Expo token → `expo`, hex → `apns`, `platform: "android"` → `fcm`), else `expo`. */
     provider?: string;
     platform?: string;
     deviceName?: string;
+    environment?: string;
+    voipToken?: string;
+    publicKey?: string;
 }
+/** The provider a token belongs to when the caller did not say. */
+export declare function inferPushProvider(token: string, platform?: string): PushProviderName;
 /**
  * Upserts a device by token. A token re-registered by another user (shared device, account switch) moves to that
- * user. Returns the device id.
+ * user. Fields left out keep their stored value. Returns the device id. Throws for an `environment` other than
+ * `sandbox`/`production`, a `provider` other than `expo`/`apns`/`fcm` or a malformed `publicKey`, so a bad registration fails at the client instead of at send time.
  */
 export declare function registerPushDevice(ctx: {
     db: WriterDb;
@@ -59,7 +83,19 @@ export declare function registerPushDevice(ctx: {
 export declare function unregisterPushDevice(db: WriterDb, token: string, table?: string): boolean;
 /** Removes every device with one of `tokens` (e.g. `unregisteredTokens` from `sendPush`/`checkPushReceipts`). */
 export declare function removePushTokens(db: WriterDb, tokens: Iterable<string>, table?: string): number;
+/** Clears dead VoIP tokens (`unregisteredVoipTokens` from `sendToDevices`); the devices keep their push token. */
+export declare function removeVoipTokens(db: WriterDb, entries: Iterable<{
+    userId: string;
+    voipToken: string;
+}>, table?: string): number;
+/** Records the APNs environment a send discovered for a device registered without one. */
+export declare function setPushDeviceEnvironment(db: WriterDb, token: string, environment: ApnsEnvironment, table?: string): boolean;
 export declare function pushDevicesForUser(db: Db, userId: string, table?: string): PushDevice[];
+/** Devices of these users (one per token), optionally of one provider: what `sendToDevices` takes. */
+export declare function pushDevicesForUsers(db: Db, userIds: Iterable<string>, opts?: {
+    provider?: string;
+    table?: string;
+}): PushDevice[];
 /** Distinct tokens of these users, optionally of one provider. */
 export declare function pushTokensForUsers(db: Db, userIds: Iterable<string>, opts?: {
     provider?: string;

package/dist/devices.js

@@ -10,11 +10,26 @@
  *     args: { token: v.string(), platform: v.optional(v.string()) },
  *     handler: (ctx, args) => registerPushDevice(ctx, { userId: requireUser(ctx).subject, ...args }),
  *   });
+ *
+ * A device is one push token: an Expo token (`provider: "expo"`), or a native one for the direct transport (`apns`
+ * with its `environment`, `fcm`). Direct devices may also carry a PushKit `voipToken` and the `publicKey` their pushes
+ * are sealed to (end-to-end encryption, `@freecorps/ember-expo-push`).
  */
 import { defineTable } from "@freecorps/ember-server";
 import { v } from "@freecorps/ember-values";
+import { isApnsToken } from "./apns.js";
+import { isDevicePublicKey } from "./envelope.js";
+import { isExpoPushToken } from "./expo.js";
 export const PUSH_DEVICES_TABLE = "pushDevices";
-/** `{ userId, token, provider, platform?, deviceName?, updatedAt }` with `by_user` and `by_token` indexes. */
+/** Whether `p` is a provider `sendToDevices` knows (`expo`, `apns`, `fcm`; exact case). */
+export function isPushProviderName(p) {
+    return p === "expo" || p === "apns" || p === "fcm";
+}
+/**
+ * `{ userId, token, provider, platform?, deviceName?, environment?, voipToken?, publicKey?, updatedAt }` with
+ * `by_user` and `by_token` indexes. The direct-transport fields are optional, so an existing table gains them with no
+ * migration.
+ */
 export function pushDevicesTable() {
     return defineTable({
         userId: v.string(),
@@ -23,6 +38,12 @@ export function pushDevicesTable() {
         provider: v.string(),
         platform: v.optional(v.string()),
         deviceName: v.optional(v.string()),
+        /** APNs environment of an iOS token: "sandbox" | "production". */
+        environment: v.optional(v.string()),
+        /** iOS PushKit token (VoIP pushes, `voip: true`). */
+        voipToken: v.optional(v.string()),
+        /** Device public key for sealed pushes (uncompressed P-256, base64url). */
+        publicKey: v.optional(v.string()),
         /** ms since epoch of the last registration (stale devices can be pruned). */
         updatedAt: v.number(),
     })
@@ -30,23 +51,42 @@ export function pushDevicesTable() {
         .index("by_token", ["token"]);
 }
 const byToken = (db, table, token) => db.query(table).withIndex("by_token", (q) => q.eq("token", token)).unique();
+/** The provider a token belongs to when the caller did not say. */
+export function inferPushProvider(token, platform) {
+    if (isExpoPushToken(token))
+        return "expo";
+    if (isApnsToken(token))
+        return "apns";
+    if (platform === "android")
+        return "fcm";
+    return "expo";
+}
 /**
  * Upserts a device by token. A token re-registered by another user (shared device, account switch) moves to that
- * user. Returns the device id.
+ * user. Fields left out keep their stored value. Returns the device id. Throws for an `environment` other than
+ * `sandbox`/`production`, a `provider` other than `expo`/`apns`/`fcm` or a malformed `publicKey`, so a bad registration fails at the client instead of at send time.
  */
 export function registerPushDevice(ctx, input, table = PUSH_DEVICES_TABLE) {
     if (!input.token)
         throw new Error("registerPushDevice: empty token");
+    if (input.environment !== undefined && input.environment !== "sandbox" && input.environment !== "production") {
+        throw new Error(`registerPushDevice: environment must be "sandbox" or "production", got ${JSON.stringify(input.environment)}`);
+    }
+    if (input.provider !== undefined && !isPushProviderName(input.provider)) {
+        throw new Error(`registerPushDevice: provider must be "expo", "apns" or "fcm", got ${JSON.stringify(input.provider)}`);
+    }
+    if (input.publicKey !== undefined && !isDevicePublicKey(input.publicKey)) {
+        throw new Error("registerPushDevice: publicKey must be an uncompressed P-256 point (65 bytes, base64url)");
+    }
     const fields = {
         userId: input.userId,
         token: input.token,
-        provider: input.provider ?? "expo",
+        provider: input.provider ?? inferPushProvider(input.token, input.platform),
         updatedAt: ctx.now,
     };
-    if (input.platform !== undefined)
-        fields.platform = input.platform;
-    if (input.deviceName !== undefined)
-        fields.deviceName = input.deviceName;
+    for (const f of ["platform", "deviceName", "environment", "voipToken", "publicKey"])
+        if (input[f] !== undefined)
+            fields[f] = input[f];
     const existing = byToken(ctx.db, table, input.token);
     if (existing) {
         ctx.db.patch(existing._id, fields);
@@ -69,15 +109,40 @@ export function removePushTokens(db, tokens, table = PUSH_DEVICES_TABLE) {
             n++;
     return n;
 }
+/** Clears dead VoIP tokens (`unregisteredVoipTokens` from `sendToDevices`); the devices keep their push token. */
+export function removeVoipTokens(db, entries, table = PUSH_DEVICES_TABLE) {
+    let n = 0;
+    for (const e of entries) {
+        for (const d of pushDevicesForUser(db, e.userId, table)) {
+            if (d.voipToken !== e.voipToken)
+                continue;
+            db.patch(d._id, { voipToken: undefined }); // undefined removes the field (Convex semantics)
+            n++;
+        }
+    }
+    return n;
+}
+/** Records the APNs environment a send discovered for a device registered without one. */
+export function setPushDeviceEnvironment(db, token, environment, table = PUSH_DEVICES_TABLE) {
+    const existing = byToken(db, table, token);
+    if (!existing || existing.environment === environment)
+        return false;
+    db.patch(existing._id, { environment });
+    return true;
+}
 export function pushDevicesForUser(db, userId, table = PUSH_DEVICES_TABLE) {
     return db.query(table).withIndex("by_user", (q) => q.eq("userId", userId)).collect();
 }
-/** Distinct tokens of these users, optionally of one provider. */
-export function pushTokensForUsers(db, userIds, opts = {}) {
-    const out = new Set();
+/** Devices of these users (one per token), optionally of one provider: what `sendToDevices` takes. */
+export function pushDevicesForUsers(db, userIds, opts = {}) {
+    const out = new Map();
     for (const u of new Set(userIds))
         for (const d of pushDevicesForUser(db, u, opts.table))
             if (!opts.provider || d.provider === opts.provider)
-                out.add(d.token);
-    return [...out];
+                out.set(d.token, d);
+    return [...out.values()];
+}
+/** Distinct tokens of these users, optionally of one provider. */
+export function pushTokensForUsers(db, userIds, opts = {}) {
+    return pushDevicesForUsers(db, userIds, opts).map((d) => d.token);
 }

package/dist/direct.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Sending to registered devices through whichever transport each one uses: Expo Push for Expo tokens, APNs or FCM
+ * directly for native tokens (`provider` in the device table). Content is sealed per device when the device has a
+ * public key and encryption allows it (see `PushEncryption`); APNs and FCM then see only the envelope and the fallback
+ * text.
+ *
+ *   const devices = await ctx.runQuery(internal.push.devicesOf, { userIds });
+ *   const r = await sendToDevices(devices, { title: "Ana Souza", body: "Re: orçamento", urgency: "high" }, {
+ *     apns: { keyId: env.APNS_KEY_ID, teamId: env.APNS_TEAM_ID, key: env.APNS_KEY, topic: "com.acme.mail" },
+ *     fcm: { serviceAccount: env.FCM_SERVICE_ACCOUNT },
+ *     encryption: "required",
+ *   });
+ *   // r.unregisteredTokens / r.unregisteredVoipTokens → prune; r.environments → record; r.expoTickets → receipts later
+ */
+import { type ApnsOptions } from "./apns.ts";
+import { type ExpoPushOptions } from "./expo.ts";
+import { type FcmOptions } from "./fcm.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;
+    provider?: string;
+    platform?: string;
+    environment?: string;
+    publicKey?: string;
+    voipToken?: string;
+    userId?: string;
+}
+export interface PushTransports {
+    /** Expo Push options; `false` refuses Expo devices. Default `{}` (enabled, no access token). */
+    expo?: ExpoPushOptions | false;
+    /** Direct APNs; without it, `apns` devices get `ProviderNotConfigured` tickets (never pruned). */
+    apns?: ApnsOptions;
+    /** Direct FCM; without it, `fcm` devices get `ProviderNotConfigured` tickets. */
+    fcm?: FcmOptions;
+    /** Default `auto`; a message's `encryption` wins. */
+    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 {
+    /** One per target (VoIP sends: one per target with a VoIP token), in order. */
+    tickets: PushTicket[];
+    /** Push tokens to delete (`DeviceNotRegistered` or a malformed token). */
+    unregisteredTokens: string[];
+    /** VoIP tokens APNs no longer accepts: clear them (`removeVoipTokens`), the device keeps its push token. */
+    unregisteredVoipTokens: Array<{
+        userId: string;
+        voipToken: string;
+    }>;
+    /** APNs environments discovered for devices registered without one: record them (`setPushDeviceEnvironment`). */
+    environments: Array<{
+        token: string;
+        environment: ApnsEnvironment;
+    }>;
+    /** Expo `ok` tickets, for `checkPushReceipts` later (APNs/FCM answers are final). */
+    expoTickets: PushTicket[];
+}
+/**
+ * Sends `message` to every target (duplicate tokens once). Never throws for per-device failures: they come back as
+ * error tickets (a provider other than `expo`/`apns`/`fcm` is `ProviderNotConfigured`, like one with no credentials). Encryption, per device:
+ * - `off`: clear;
+ * - `auto`: sealed when the device is `apns`/`fcm` and registered a public key, else clear;
+ * - `required`: sealed, or the fallback text only (no data) for an Expo device or one without a key.
+ * Only pushes with something to show (title/subtitle/body) are sealed; background (`contentAvailable` only) and VoIP
+ * pushes go as they are under `auto`, and lose their `data` under `required`.
+ */
+export declare function sendToDevices(targets: Iterable<PushTarget>, message: PushMessage, t?: PushTransports): Promise<DeviceSendResult>;

package/dist/direct.js

@@ -0,0 +1,150 @@
+/**
+ * Sending to registered devices through whichever transport each one uses: Expo Push for Expo tokens, APNs or FCM
+ * directly for native tokens (`provider` in the device table). Content is sealed per device when the device has a
+ * public key and encryption allows it (see `PushEncryption`); APNs and FCM then see only the envelope and the fallback
+ * text.
+ *
+ *   const devices = await ctx.runQuery(internal.push.devicesOf, { userIds });
+ *   const r = await sendToDevices(devices, { title: "Ana Souza", body: "Re: orçamento", urgency: "high" }, {
+ *     apns: { keyId: env.APNS_KEY_ID, teamId: env.APNS_TEAM_ID, key: env.APNS_KEY, topic: "com.acme.mail" },
+ *     fcm: { serviceAccount: env.FCM_SERVICE_ACCOUNT },
+ *     encryption: "required",
+ *   });
+ *   // r.unregisteredTokens / r.unregisteredVoipTokens → prune; r.environments → record; r.expoTickets → receipts later
+ */
+import { sendApns } from "./apns.js";
+import { DEFAULT_PUSH_FALLBACK } from "./delivery.js";
+import { sealPushContent } from "./envelope.js";
+import { sendExpoMessages } from "./expo.js";
+import { sendFcm } from "./fcm.js";
+import { inferPushProvider, isPushProviderName } from "./devices.js";
+const hasVisibleContent = (m) => !!(m.title || m.subtitle || m.body);
+/** The fallback-only version of a message: no title/subtitle/body/data beyond the fallback text. */
+function fallbackOnly(m, fallback) {
+    const { title, subtitle, body, data, ...rest } = m;
+    void title;
+    void subtitle;
+    void body;
+    void data;
+    const out = { ...rest };
+    if (fallback.title)
+        out.title = fallback.title;
+    if (fallback.body)
+        out.body = fallback.body;
+    return out;
+}
+/**
+ * Sends `message` to every target (duplicate tokens once). Never throws for per-device failures: they come back as
+ * error tickets (a provider other than `expo`/`apns`/`fcm` is `ProviderNotConfigured`, like one with no credentials). Encryption, per device:
+ * - `off`: clear;
+ * - `auto`: sealed when the device is `apns`/`fcm` and registered a public key, else clear;
+ * - `required`: sealed, or the fallback text only (no data) for an Expo device or one without a key.
+ * Only pushes with something to show (title/subtitle/body) are sealed; background (`contentAvailable` only) and VoIP
+ * pushes go as they are under `auto`, and lose their `data` under `required`.
+ */
+export async function sendToDevices(targets, message, t = {}) {
+    const mode = message.encryption ?? t.encryption ?? "auto";
+    const fallback = t.fallback ?? DEFAULT_PUSH_FALLBACK;
+    const now = t.now ?? Date.now;
+    const seen = new Set();
+    // `provider` is whatever the device row holds: anything but expo/apns/fcm gets an error ticket below.
+    const list = [];
+    for (const target of targets) {
+        const provider = target.provider ?? inferPushProvider(target.token, target.platform);
+        let to = target.token;
+        if (message.voip) {
+            if (provider !== "apns" || !target.voipToken)
+                continue;
+            to = target.voipToken;
+        }
+        if (seen.has(to))
+            continue;
+        seen.add(to);
+        list.push({ target, provider, to });
+    }
+    const tickets = new Array(list.length);
+    const groups = { expo: [], apns: [], fcm: [] };
+    await Promise.all(list.map(async ({ target, provider, to }, i) => {
+        if (!isPushProviderName(provider)) {
+            tickets[i] = { token: to, status: "error", error: "ProviderNotConfigured", message: `unknown push provider ${JSON.stringify(provider)} (expected expo, apns or fcm)` };
+            return;
+        }
+        let m = { ...message, to };
+        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 {
+                const content = {};
+                for (const f of ["title", "subtitle", "body", "data"])
+                    if (message[f] !== undefined)
+                        content[f] = message[f];
+                m.sealed = await sealPushContent(target.publicKey, content, { now: now() });
+            }
+            catch (e) {
+                const msg = e.message;
+                tickets[i] = { token: to, status: "error", error: /over \d+/.test(msg) ? "MessageTooBig" : "RequestFailed", message: `cannot seal: ${msg}` };
+                return;
+            }
+        }
+        else if (mode === "required") {
+            const { data, ...withoutData } = message;
+            void data;
+            const base = hasVisibleContent(message) ? fallbackOnly(message, fallback) : withoutData;
+            m = { ...base, to, ...(m.environment ? { environment: m.environment } : {}) };
+        }
+        groups[provider].push({ i, m });
+    }));
+    const run = async (provider, send) => {
+        const g = groups[provider];
+        if (!g.length)
+            return;
+        if (!send) {
+            for (const { i, m } of g)
+                tickets[i] = { token: m.to, status: "error", error: "ProviderNotConfigured", message: `no ${provider} credentials configured` };
+            return;
+        }
+        const out = await send(g.map((x) => x.m));
+        g.forEach(({ i }, k) => (tickets[i] = out[k]));
+    };
+    await Promise.all([
+        run("expo", t.expo === false ? null : (ms) => sendExpoMessages(ms, t.expo || {})),
+        run("apns", t.apns ? (ms) => sendApns(ms, { ...t.apns, fallback: t.apns.fallback ?? fallback }) : null),
+        run("fcm", t.fcm ? (ms) => sendFcm(ms, { ...t.fcm, fallback: t.fcm.fallback ?? fallback }) : null),
+    ]);
+    const result = { tickets, unregisteredTokens: [], unregisteredVoipTokens: [], environments: [], expoTickets: [] };
+    const dead = new Set();
+    tickets.forEach((ticket, i) => {
+        const { target, provider } = list[i];
+        if (ticket.status === "ok") {
+            if (provider === "expo")
+                result.expoTickets.push(ticket);
+            if (ticket.environment && !message.voip)
+                result.environments.push({ token: target.token, environment: ticket.environment });
+            return;
+        }
+        if (ticket.error !== "DeviceNotRegistered" && ticket.error !== "InvalidToken")
+            return;
+        if (message.voip)
+            result.unregisteredVoipTokens.push({ userId: target.userId ?? "", voipToken: ticket.token });
+        else
+            dead.add(target.token);
+    });
+    result.unregisteredTokens = [...dead];
+    return result;
+}

package/dist/envelope.d.ts

@@ -0,0 +1,62 @@
+import { type HpkeRecipient } from "./hpke.ts";
+/**
+ * What is sealed for one device: everything a person would read. APNs and FCM only see the envelope (and the
+ * fallback text the sender chose, which should say nothing).
+ */
+export interface EncryptedPushContent {
+    title?: string;
+    subtitle?: string;
+    body?: string;
+    /** Delivered to the app after decryption (`notification.request.content.data` in expo-notifications). */
+    data?: Record<string, unknown>;
+}
+/** What opening an envelope gives: the content and when the server sealed it (Unix seconds). */
+export interface OpenedPushContent extends EncryptedPushContent {
+    iat: number;
+}
+/**
+ * The encrypted push as it travels, in the APNs payload's `ember` field or the FCM data's `ember` field (as a JSON
+ * string): HPKE's encapsulated key and ciphertext, base64url, and `k`, the id of the device key it was sealed to, so a
+ * device holding a rotated key tries the right one.
+ */
+export interface PushEnvelope {
+    v: typeof EMBER_PUSH_ENVELOPE_VERSION;
+    k: string;
+    enc: string;
+    ct: string;
+}
+export declare const EMBER_PUSH_ENVELOPE_VERSION = 1;
+/**
+ * HPKE `info`: binds every ciphertext to this protocol and version. The iOS Notification Service Extension and the
+ * Android decoder in `@freecorps/ember-expo-push` use the same string. Change it (and `v`) together everywhere.
+ */
+export declare const EMBER_PUSH_HPKE_INFO = "freecorps.ember push v1";
+/**
+ * Plaintext limit in UTF-8 bytes (Brigade's): about 2.8 KB once sealed and base64url-encoded, which leaves room in
+ * APNs' and FCM's 4 KB for the fallback text and the other fields.
+ */
+export declare const PUSH_PLAINTEXT_MAX_BYTES = 2048;
+/** A key id: 8 base64url characters (`pushKeyId`). */
+export declare const PUSH_KEY_ID: RegExp;
+/**
+ * Seals `content` for a device, given its public key as the device registered it (base64url of the uncompressed
+ * P-256 point, 65 bytes). Throws over `PUSH_PLAINTEXT_MAX_BYTES` or for a malformed key.
+ */
+export declare function sealPushContent(devicePublicKey: string, content: EncryptedPushContent, opts?: {
+    now?: number;
+}): Promise<PushEnvelope>;
+/** Opens an envelope (what the device does; for tests and JS clients with WebCrypto). Throws if it does not open. */
+export declare function openPushEnvelope(recipient: HpkeRecipient, envelope: PushEnvelope): Promise<OpenedPushContent>;
+/** The plaintext of an envelope as a device accepts it; throws for anything else. */
+export declare function parseOpenedContent(value: unknown): OpenedPushContent;
+/**
+ * The id of a device key, as an envelope names it (`k`): base64url of the first 6 bytes of SHA-256 over the
+ * uncompressed public key, 8 characters (Brigade's `pushKeyId`). Only a hint for which key to try; the AEAD decides.
+ */
+export declare function pushKeyId(publicKey: string | Uint8Array): Promise<string>;
+/** Accepts an envelope from untrusted JSON (or the JSON string FCM data carries), or returns null. */
+export declare function parsePushEnvelope(value: unknown): PushEnvelope | null;
+/** A device public key from its base64url form; throws unless it is an uncompressed P-256 point. */
+export declare function parseDevicePublicKey(value: string): Uint8Array<ArrayBuffer>;
+/** Cheap shape check for registration (the curve check happens when sealing). */
+export declare function isDevicePublicKey(value: unknown): value is string;