@freecorps/ember-push 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FreeCorps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,12 @@
-# Temporary Holding Version
+# @freecorps/ember-push
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Push notifications for Ember actions: device table helpers and an Expo Push sender.
+
+Part of [Ember](https://github.com/freecorps/ember), a Convex-style backend on Cloudflare Workers and Durable
+Objects. Source: [`packages/push`](https://github.com/freecorps/ember/tree/main/packages/push).
+
+```sh
+npm install @freecorps/ember-push
+```
+
+License: MIT.

package/dist/devices.d.ts

@@ -0,0 +1,68 @@
+export declare const PUSH_DEVICES_TABLE = "pushDevices";
+/** `{ userId, token, provider, platform?, deviceName?, updatedAt }` with `by_user` and `by_token` indexes. */
+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>;
+    /** "expo" | "apns" | "fcm" */
+    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>;
+    /** ms since epoch of the last registration (stale devices can be pruned). */
+    updatedAt: import("@freecorps/ember-values").Validator<number, "required", never>;
+}>, {
+    by_user: ["userId", "_creationTime"];
+    by_token: ["token", "_creationTime"];
+}, {}>;
+export interface PushDevice {
+    _id: string;
+    _creationTime: number;
+    userId: string;
+    token: string;
+    provider: string;
+    platform?: string;
+    deviceName?: string;
+    updatedAt: number;
+}
+/**
+ * The slice of `ctx.db` the helpers use. Typed loosely so it accepts any schema's `DatabaseReader`/`Writer`
+ * (the table name is a parameter).
+ */
+type Db = {
+    query(table: any): {
+        withIndex(name: any, range?: (q: any) => any): {
+            collect(): any[];
+            unique(): any;
+        };
+    };
+};
+type WriterDb = Db & {
+    insert(table: any, value: any): string;
+    patch(id: any, value: any): void;
+    delete(id: any): void;
+};
+export interface RegisterPushDeviceInput {
+    userId: string;
+    token: string;
+    provider?: string;
+    platform?: string;
+    deviceName?: string;
+}
+/**
+ * Upserts a device by token. A token re-registered by another user (shared device, account switch) moves to that
+ * user. Returns the device id.
+ */
+export declare function registerPushDevice(ctx: {
+    db: WriterDb;
+    now: number;
+}, input: RegisterPushDeviceInput, table?: string): string;
+/** Removes a device by token (sign-out on that device). Returns whether it existed. */
+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;
+export declare function pushDevicesForUser(db: Db, userId: 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;
+    table?: string;
+}): string[];
+export {};

package/dist/devices.js

@@ -0,0 +1,83 @@
+/**
+ * Device registration for user schemas. Add the table to your schema and call the helpers from your own
+ * mutations/queries (they take `ctx.db`, so they run inside the caller's transaction):
+ *
+ *   // ember/schema.ts
+ *   tables: { ..., pushDevices: pushDevicesTable() }
+ *
+ *   // ember/push.ts
+ *   export const register = mutation({
+ *     args: { token: v.string(), platform: v.optional(v.string()) },
+ *     handler: (ctx, args) => registerPushDevice(ctx, { userId: requireUser(ctx).subject, ...args }),
+ *   });
+ */
+import { defineTable } from "@freecorps/ember-server";
+import { v } from "@freecorps/ember-values";
+export const PUSH_DEVICES_TABLE = "pushDevices";
+/** `{ userId, token, provider, platform?, deviceName?, updatedAt }` with `by_user` and `by_token` indexes. */
+export function pushDevicesTable() {
+    return defineTable({
+        userId: v.string(),
+        token: v.string(),
+        /** "expo" | "apns" | "fcm" */
+        provider: v.string(),
+        platform: v.optional(v.string()),
+        deviceName: v.optional(v.string()),
+        /** ms since epoch of the last registration (stale devices can be pruned). */
+        updatedAt: v.number(),
+    })
+        .index("by_user", ["userId"])
+        .index("by_token", ["token"]);
+}
+const byToken = (db, table, token) => db.query(table).withIndex("by_token", (q) => q.eq("token", token)).unique();
+/**
+ * Upserts a device by token. A token re-registered by another user (shared device, account switch) moves to that
+ * user. Returns the device id.
+ */
+export function registerPushDevice(ctx, input, table = PUSH_DEVICES_TABLE) {
+    if (!input.token)
+        throw new Error("registerPushDevice: empty token");
+    const fields = {
+        userId: input.userId,
+        token: input.token,
+        provider: input.provider ?? "expo",
+        updatedAt: ctx.now,
+    };
+    if (input.platform !== undefined)
+        fields.platform = input.platform;
+    if (input.deviceName !== undefined)
+        fields.deviceName = input.deviceName;
+    const existing = byToken(ctx.db, table, input.token);
+    if (existing) {
+        ctx.db.patch(existing._id, fields);
+        return existing._id;
+    }
+    return ctx.db.insert(table, fields);
+}
+/** Removes a device by token (sign-out on that device). Returns whether it existed. */
+export function unregisterPushDevice(db, token, table = PUSH_DEVICES_TABLE) {
+    const existing = byToken(db, table, token);
+    if (existing)
+        db.delete(existing._id);
+    return !!existing;
+}
+/** Removes every device with one of `tokens` (e.g. `unregisteredTokens` from `sendPush`/`checkPushReceipts`). */
+export function removePushTokens(db, tokens, table = PUSH_DEVICES_TABLE) {
+    let n = 0;
+    for (const t of new Set(tokens))
+        if (unregisterPushDevice(db, t, table))
+            n++;
+    return n;
+}
+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();
+    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];
+}

package/dist/expo.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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";
+/** Messages per `send` request. */
+export declare const EXPO_SEND_CHUNK = 100;
+/** Ids per `getReceipts` request. */
+export declare const EXPO_RECEIPTS_CHUNK = 1000;
+/** Max payload of one notification, in bytes. */
+export declare const EXPO_MAX_PAYLOAD = 4096;
+export interface ExpoPushOptions {
+    /** Expo access token, required when the project enforces push security. Keep it in a Worker secret. */
+    accessToken?: string;
+    fetch?: typeof fetch;
+    /** Notifications per second across this call (default 600, the per-project limit). */
+    ratePerSecond?: number;
+    /** Retries of a whole request on 429 / 5xx / network errors (default 2), with exponential backoff. */
+    retries?: number;
+    /** First retry delay in ms (default 1000); doubles each time. A `Retry-After` header wins. */
+    retryDelayMs?: number;
+    /** Override endpoints (tests, proxies). */
+    sendUrl?: string;
+    receiptsUrl?: string;
+    /** Injected for tests. */
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+/** `ExponentPushToken[...]` / `ExpoPushToken[...]` (or the older bare UUID form). */
+export declare function isExpoPushToken(token: unknown): token is string;
+/** The JSON Expo expects for one message. */
+export declare function toExpoMessage(m: AddressedPushMessage): Record<string, unknown>;
+/** Payload size Expo checks against 4096 B: the notification fields plus `data`. */
+export declare function payloadSize(m: PushMessage): number;
+/**
+ * Sends `messages` through Expo in chunks of 100, paced to `ratePerSecond`. Never throws for message failures: a
+ * malformed token, an oversized payload or a failed request becomes an error ticket for the affected messages.
+ */
+export declare function sendExpoMessages(messages: AddressedPushMessage[], opts?: ExpoPushOptions): Promise<PushTicket[]>;
+/**
+ * Sends the same `message` to every token (duplicates removed). `unregisteredTokens` lists tokens to delete now;
+ * keep the `ok` tickets and call `checkPushReceipts` ~15 min later for the final outcome.
+ */
+export declare function sendPush(tokens: string | Iterable<string>, message: PushMessage, opts?: ExpoPushOptions): Promise<SendPushResult>;
+/**
+ * Reads receipts for the `ok` tickets (1000 ids per request). Error tickets count toward `unregisteredTokens`
+ * when they say DeviceNotRegistered. A failed receipts request leaves its ids in `pending`.
+ */
+export declare function checkPushReceipts(tickets: PushTicket[], opts?: ExpoPushOptions): Promise<ReceiptCheck>;
+/** Expo Push as a `PushProvider`. */
+export declare function expoPushProvider(opts?: ExpoPushOptions): PushProvider;

package/dist/expo.js

@@ -0,0 +1,211 @@
+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. */
+export const EXPO_SEND_CHUNK = 100;
+/** Ids per `getReceipts` request. */
+export const EXPO_RECEIPTS_CHUNK = 1000;
+/** Max payload of one notification, in bytes. */
+export const EXPO_MAX_PAYLOAD = 4096;
+/** `ExponentPushToken[...]` / `ExpoPushToken[...]` (or the older bare UUID form). */
+export function isExpoPushToken(token) {
+    if (typeof token !== "string")
+        return false;
+    return (/^Expo(?:nent)?PushToken\[[^\]]+\]$/.test(token) ||
+        /^[a-z\d]{8}-[a-z\d]{4}-[a-z\d]{4}-[a-z\d]{4}-[a-z\d]{12}$/i.test(token));
+}
+/** The JSON Expo expects for one message. */
+export function toExpoMessage(m) {
+    const { contentAvailable, ...rest } = m;
+    const out = {};
+    for (const [k, val] of Object.entries(rest))
+        if (val !== undefined)
+            out[k] = val;
+    if (contentAvailable)
+        out._contentAvailable = true;
+    return out;
+}
+const utf8Length = (s) => new TextEncoder().encode(s).length;
+/** Payload size Expo checks against 4096 B: the notification fields plus `data`. */
+export function payloadSize(m) {
+    const { title, subtitle, body, data } = m;
+    return utf8Length(JSON.stringify({ title, subtitle, body, data }));
+}
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function chunks(xs, n) {
+    const out = [];
+    for (let i = 0; i < xs.length; i += n)
+        out.push(xs.slice(i, i + n));
+    return out;
+}
+class Transport {
+    o;
+    fetch;
+    sleep;
+    now;
+    /** Earliest time the next batch may start, so the overall rate stays under `ratePerSecond`. */
+    nextAt = 0;
+    constructor(o) {
+        this.o = o;
+        const f = o.fetch ?? globalThis.fetch;
+        if (!f)
+            throw new Error("@freecorps/ember-push: no fetch available; pass options.fetch");
+        this.fetch = f.bind(globalThis);
+        this.sleep = o.sleep ?? defaultSleep;
+        this.now = o.now ?? Date.now;
+    }
+    /** Waits until `count` more notifications fit in the rate budget. */
+    async pace(count) {
+        const rate = this.o.ratePerSecond ?? 600;
+        const t = this.now();
+        if (this.nextAt > t)
+            await this.sleep(this.nextAt - t);
+        this.nextAt = Math.max(this.nextAt, t) + (count / rate) * 1000;
+    }
+    /** POSTs JSON; retries 429/5xx/network errors. Returns the parsed body or throws with a message. */
+    async post(url, body) {
+        const retries = this.o.retries ?? 2;
+        let delay = this.o.retryDelayMs ?? 1000;
+        const headers = {
+            accept: "application/json",
+            "accept-encoding": "gzip, deflate",
+            "content-type": "application/json",
+        };
+        if (this.o.accessToken)
+            headers.authorization = `Bearer ${this.o.accessToken}`;
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await this.fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
+            }
+            catch (e) {
+                if (attempt >= retries)
+                    throw new Error(`request failed: ${e.message}`);
+                await this.sleep(delay);
+                delay *= 2;
+                continue;
+            }
+            if ((res.status === 429 || res.status >= 500) && attempt < retries) {
+                const ra = Number(res.headers.get("retry-after"));
+                await this.sleep(Number.isFinite(ra) && ra > 0 ? ra * 1000 : delay);
+                delay *= 2;
+                continue;
+            }
+            const text = await res.text();
+            let json;
+            try {
+                json = text ? JSON.parse(text) : {};
+            }
+            catch {
+                json = undefined;
+            }
+            if (!res.ok || !json || json.errors) {
+                const err = json?.errors?.[0];
+                const msg = err ? `${err.code ?? "error"}: ${err.message ?? ""}`.trim() : `HTTP ${res.status}`;
+                throw Object.assign(new Error(msg), { code: err?.code, status: res.status });
+            }
+            return json;
+        }
+    }
+}
+/**
+ * Sends `messages` through Expo in chunks of 100, paced to `ratePerSecond`. Never throws for message failures: a
+ * malformed token, an oversized payload or a failed request becomes an error ticket for the affected messages.
+ */
+export async function sendExpoMessages(messages, opts = {}) {
+    const transport = new Transport(opts);
+    const tickets = new Array(messages.length);
+    const sendable = [];
+    messages.forEach((m, i) => {
+        if (!isExpoPushToken(m.to))
+            tickets[i] = { token: String(m.to), status: "error", error: "InvalidToken", message: "not an Expo push token" };
+        else if (payloadSize(m) > EXPO_MAX_PAYLOAD)
+            tickets[i] = { token: m.to, status: "error", error: "MessageTooBig", message: `payload over ${EXPO_MAX_PAYLOAD} bytes` };
+        else
+            sendable.push({ i, m });
+    });
+    for (const batch of chunks(sendable, EXPO_SEND_CHUNK)) {
+        await transport.pace(batch.length);
+        try {
+            const json = await transport.post(opts.sendUrl ?? EXPO_PUSH_URL, batch.map((b) => toExpoMessage(b.m)));
+            const data = Array.isArray(json.data) ? json.data : [];
+            batch.forEach(({ i, m }, k) => {
+                const t = data[k];
+                if (t?.status === "ok" && typeof t.id === "string")
+                    tickets[i] = { token: m.to, status: "ok", id: t.id };
+                else if (t?.status === "error") {
+                    const ticket = { token: m.to, status: "error", message: String(t.message ?? "error") };
+                    if (t.details?.error)
+                        ticket.error = t.details.error;
+                    tickets[i] = ticket;
+                }
+                else
+                    tickets[i] = { token: m.to, status: "error", error: "RequestFailed", message: "no ticket in response" };
+            });
+        }
+        catch (e) {
+            const err = e;
+            for (const { i, m } of batch) {
+                const ticket = { token: m.to, status: "error", error: "RequestFailed", message: err.message };
+                if (err.code === "PUSH_TOO_MANY_EXPERIENCE_IDS")
+                    ticket.error = "MismatchSenderId";
+                tickets[i] = ticket;
+            }
+        }
+    }
+    return tickets;
+}
+const unregistered = (xs) => [
+    ...new Set(xs.filter((t) => t.status === "error" && (t.error === "DeviceNotRegistered" || t.error === "InvalidToken")).map((t) => t.token)),
+];
+/**
+ * Sends the same `message` to every token (duplicates removed). `unregisteredTokens` lists tokens to delete now;
+ * keep the `ok` tickets and call `checkPushReceipts` ~15 min later for the final outcome.
+ */
+export async function sendPush(tokens, message, opts = {}) {
+    const list = typeof tokens === "string" ? [tokens] : [...new Set(tokens)];
+    const tickets = await sendExpoMessages(list.map((to) => ({ ...message, to })), opts);
+    return { tickets, unregisteredTokens: unregistered(tickets) };
+}
+/**
+ * Reads receipts for the `ok` tickets (1000 ids per request). Error tickets count toward `unregisteredTokens`
+ * when they say DeviceNotRegistered. A failed receipts request leaves its ids in `pending`.
+ */
+export async function checkPushReceipts(tickets, opts = {}) {
+    const transport = new Transport(opts);
+    const ok = tickets.filter((t) => t.status === "ok");
+    const receipts = [];
+    const pending = [];
+    for (const batch of chunks(ok, EXPO_RECEIPTS_CHUNK)) {
+        let data = {};
+        try {
+            const json = await transport.post(opts.receiptsUrl ?? EXPO_RECEIPTS_URL, { ids: batch.map((t) => t.id) });
+            data = json.data && typeof json.data === "object" ? json.data : {};
+        }
+        catch {
+            data = {};
+        }
+        for (const t of batch) {
+            const r = data[t.id];
+            if (!r)
+                pending.push({ token: t.token, id: t.id });
+            else if (r.status === "ok")
+                receipts.push({ token: t.token, id: t.id, status: "ok" });
+            else {
+                const receipt = { token: t.token, id: t.id, status: "error", message: String(r.message ?? "error") };
+                if (r.details?.error)
+                    receipt.error = r.details.error;
+                receipts.push(receipt);
+            }
+        }
+    }
+    return { receipts, pending, unregisteredTokens: unregistered([...tickets, ...receipts]) };
+}
+/** Expo Push as a `PushProvider`. */
+export function expoPushProvider(opts = {}) {
+    return {
+        name: "expo",
+        isToken: isExpoPushToken,
+        send: (messages) => sendExpoMessages(messages, opts),
+        checkReceipts: (tickets) => checkPushReceipts(tickets, opts),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@freecorps/ember-push`: push notifications for Ember apps (PLAN §10: iOS background sync is rare, so news arrives by push).
+ *
+ * - Device table + helpers for your schema (`pushDevicesTable`, `registerPushDevice`, ...): run in mutations.
+ * - Sending (`sendPush`, `checkPushReceipts`): plain `fetch`, so call them from an **action** (PLAN D6: I/O only in
+ *   actions). Typical flow: a mutation schedules an action → the action reads tokens with `ctx.runQuery`, calls
+ *   `sendPush`, deletes `unregisteredTokens` with `ctx.runMutation`, and schedules a receipts check ~15 min later.
+ * - `PushProvider` keeps the backend pluggable: Expo Push today; direct APNs/FCM later.
+ */
+export * from "./types.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, pushDevicesForUser, pushDevicesTable, pushTokensForUsers, registerPushDevice, removePushTokens, unregisterPushDevice, type PushDevice, type RegisterPushDeviceInput, } from "./devices.ts";

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * `@freecorps/ember-push`: push notifications for Ember apps (PLAN §10: iOS background sync is rare, so news arrives by push).
+ *
+ * - Device table + helpers for your schema (`pushDevicesTable`, `registerPushDevice`, ...): run in mutations.
+ * - Sending (`sendPush`, `checkPushReceipts`): plain `fetch`, so call them from an **action** (PLAN D6: I/O only in
+ *   actions). Typical flow: a mutation schedules an action → the action reads tokens with `ctx.runQuery`, calls
+ *   `sendPush`, deletes `unregisteredTokens` with `ctx.runMutation`, and schedules a receipts check ~15 min later.
+ * - `PushProvider` keeps the backend pluggable: Expo Push today; direct APNs/FCM later.
+ */
+export * from "./types.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, pushDevicesForUser, pushDevicesTable, pushTokensForUsers, registerPushDevice, removePushTokens, unregisterPushDevice, } from "./devices.js";

package/dist/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Provider-neutral push types. Expo Push is the first provider (PLAN §10, CLOUDFLARE.md §8); direct APNs (ES256 JWT
+ * over HTTP/2) and FCM v1 (service-account OAuth) can implement `PushProvider` later without changing callers.
+ */
+/** What a notification says. Fields a provider does not support are ignored by it. */
+export interface PushMessage {
+    title?: string;
+    subtitle?: string;
+    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;
+    /** iOS app icon badge; 0 clears it. */
+    badge?: number;
+    /** Android notification channel (created by the app, e.g. `registerForPush` creates `"default"`). */
+    channelId?: string;
+    priority?: "default" | "normal" | "high";
+    /** Seconds the push service keeps trying to deliver. */
+    ttl?: number;
+    /** iOS background ("silent") push: data-only + `content-available`. Apple advises at most 2–3 per hour. */
+    contentAvailable?: boolean;
+    /** iOS notification category (actions). */
+    categoryId?: string;
+    /** iOS Notification Service Extension may modify the content. */
+    mutableContent?: boolean;
+}
+/** A message for one device token. */
+export interface AddressedPushMessage extends PushMessage {
+    to: string;
+}
+/** Well-known per-message errors (Expo names; APNs/FCM providers map theirs onto these). */
+export type PushErrorCode = "DeviceNotRegistered" | "MessageTooBig" | "MessageRateExceeded" | "MismatchSenderId" | "InvalidCredentials" | "InvalidToken" | "RequestFailed" | (string & {});
+/** The push service's answer at send time. `ok` means accepted, not delivered: check receipts later. */
+export type PushTicket = {
+    token: string;
+    status: "ok";
+    id: string;
+} | {
+    token: string;
+    status: "error";
+    message: string;
+    error?: PushErrorCode;
+};
+/** Final delivery outcome reported by the provider (Expo keeps receipts for 24 h). */
+export type PushReceipt = {
+    token: string;
+    id: string;
+    status: "ok";
+} | {
+    token: string;
+    id: string;
+    status: "error";
+    message: string;
+    error?: PushErrorCode;
+};
+export interface ReceiptCheck {
+    receipts: PushReceipt[];
+    /** Ticket ids with no receipt yet (try again later; Expo usually has them within 15 min). */
+    pending: Array<{
+        token: string;
+        id: string;
+    }>;
+    /** Tokens to delete from the device table (DeviceNotRegistered in a ticket or a receipt). */
+    unregisteredTokens: string[];
+}
+export interface SendPushResult {
+    tickets: PushTicket[];
+    /** Tokens to delete right away: malformed, or DeviceNotRegistered in the ticket. */
+    unregisteredTokens: string[];
+}
+/** A push backend. `send` never throws for per-message failures: they come back as error tickets. */
+export interface PushProvider {
+    readonly name: string;
+    /** Whether `token` looks like a token of this provider (cheap format check). */
+    isToken(token: string): boolean;
+    send(messages: AddressedPushMessage[]): Promise<PushTicket[]>;
+    /** Providers without receipts (APNs/FCM answer synchronously) may omit this. */
+    checkReceipts?(tickets: PushTicket[]): Promise<ReceiptCheck>;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Provider-neutral push types. Expo Push is the first provider (PLAN §10, CLOUDFLARE.md §8); direct APNs (ES256 JWT
+ * over HTTP/2) and FCM v1 (service-account OAuth) can implement `PushProvider` later without changing callers.
+ */
+export {};

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@freecorps/ember-push",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Push notifications for Ember actions: device table helpers and an Expo Push sender.",
+  "keywords": [
+    "ember",
+    "convex",
+    "cloudflare",
+    "workers",
+    "push",
+    "expo",
+    "notifications"
+  ],
+  "homepage": "https://github.com/freecorps/ember/tree/main/packages/push#readme",
+  "bugs": {
+    "url": "https://github.com/freecorps/ember/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/freecorps/ember.git",
+    "directory": "packages/push"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@freecorps/ember-server": "0.1.0",
+    "@freecorps/ember-values": "0.1.0"
+  }
+}