@mulmobridge/web-push 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# @mulmobridge/web-push
+
+Auth-agnostic sender for the **mulmoserver `sendPush` Cloud Function**. The app only
+POSTs `{ title, body }` + a Firebase Auth ID token; the target devices resolve
+server-side from the signed-in user's uid, and device registration / delivery /
+dead-token pruning are the server's job (see mulmoserver `docs/web-push-sending.md`).
+
+No firebase or app dependency — the caller injects the ID-token provider, so both
+mulmoclaude and mulmoterminal share one source of truth for the wire contract.
+
+## Usage
+
+```ts
+import { sendWebPush } from "@mulmobridge/web-push";
+
+const result = await sendWebPush("✅ my-project", "Task finished", {
+  // Return the current Firebase Auth ID token, or null when not signed in.
+  getIdToken: async () => auth.currentUser?.getIdToken() ?? null,
+});
+// → { sent, failed, targets } on success, or null when nothing was sent
+//   (not signed in / network / timeout / non-2xx). Never throws.
+// targets === 0 means the user hasn't enabled notifications on any device.
+```
+
+## API
+
+- `sendWebPush(title, body, options)` — POST to `sendPush`. No-ops (returns `null`,
+  never fetches) when `getIdToken()` yields `null` or rejects. `AbortController`
+  timeout (default 8000 ms). Never throws.
+- `buildSendPushBody(title, body)` — the onCall `{ data: { title, body } }` envelope.
+- `parseSendPushResult(json)` — read `{ sent, failed, targets }` from the onCall
+  `{ result }` envelope, or `null` when the shape doesn't match.
+- `DEFAULT_SEND_PUSH_URL` — the mulmoserver production endpoint.
+
+### `SendWebPushOptions`
+
+| Field | Default | Purpose |
+|---|---|---|
+| `getIdToken` | — (required) | `() => Promise<string \| null>`; `null` ⇒ skip |
+| `url` | `DEFAULT_SEND_PUSH_URL` | sendPush endpoint |
+| `timeoutMs` | `8000` | request timeout |
+| `fetchImpl` | `globalThis.fetch` | test seam |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export declare const DEFAULT_SEND_PUSH_URL = "https://asia-northeast1-mulmoserver.cloudfunctions.net/sendPush";
+export interface SendPushResult {
+    sent: number;
+    failed: number;
+    targets: number;
+}
+export interface SendWebPushOptions {
+    getIdToken: () => Promise<string | null>;
+    url?: string;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+export declare function buildSendPushBody(title: string, body: string): string;
+export declare function parseSendPushResult(json: unknown): SendPushResult | null;
+export declare function sendWebPush(title: string, body: string, options: SendWebPushOptions): Promise<SendPushResult | null>;

package/dist/index.js

@@ -0,0 +1,65 @@
+// @mulmobridge/web-push — send a Web Push via the mulmoserver `sendPush`
+// Cloud Function (see mulmoserver docs/web-push-sending.md).
+//
+// Auth-agnostic: the caller injects an ID-token provider, so this has no
+// firebase / app dependency and both mulmoclaude and mulmoterminal share it.
+// We only POST { title, body }; the target devices resolve server-side from the
+// signed-in user's uid, and registration / delivery / dead-token pruning are
+// the server's job.
+// asia-northeast1 onCall endpoint for the `mulmoserver` project.
+export const DEFAULT_SEND_PUSH_URL = "https://asia-northeast1-mulmoserver.cloudfunctions.net/sendPush";
+const DEFAULT_TIMEOUT_MS = 8000;
+// The onCall wire shape wraps the payload in `data`.
+export function buildSendPushBody(title, body) {
+    return JSON.stringify({ data: { title, body } });
+}
+// The onCall response wraps the payload in `result`. Missing / non-number counts read as 0.
+export function parseSendPushResult(json) {
+    if (typeof json !== "object" || json === null)
+        return null;
+    const result = json.result;
+    if (typeof result !== "object" || result === null)
+        return null;
+    const record = result;
+    const num = (value) => (typeof value === "number" ? value : 0);
+    return { sent: num(record.sent), failed: num(record.failed), targets: num(record.targets) };
+}
+// getIdToken can itself throw (auth SDK). Treat any failure as "not signed in".
+async function resolveIdToken(getIdToken) {
+    try {
+        return await getIdToken();
+    }
+    catch {
+        return null;
+    }
+}
+// POST { title, body } to sendPush as the signed-in user. Returns the delivery
+// result, or null when nothing was sent (not signed in / network / timeout /
+// non-2xx / bad JSON). Never throws — a failed push must not disturb its trigger.
+export async function sendWebPush(title, body, options) {
+    const idToken = await resolveIdToken(options.getIdToken);
+    if (!idToken)
+        return null; // not signed in → nothing to send with
+    const url = options.url ?? DEFAULT_SEND_PUSH_URL;
+    const timeout_ms = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const doFetch = options.fetchImpl ?? globalThis.fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout_ms);
+    try {
+        const res = await doFetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${idToken}` },
+            body: buildSendPushBody(title, body),
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return null;
+        return parseSendPushResult(await res.json());
+    }
+    catch {
+        return null; // offline / aborted / bad JSON — silently skip
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@mulmobridge/web-push",
+  "version": "0.1.0",
+  "description": "Auth-agnostic sender for the mulmoserver Web Push (sendPush) Cloud Function",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepack": "yarn build",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/test_*.ts",
+    "lint": "eslint src test"
+  },
+  "license": "MIT",
+  "author": "Receptron Team",
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
+}