@shware/workflow 3.3.0 → 4.1.0

package/dist/fcm.cjs

@@ -1,16 +1,90 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_engine_retry = require("./engine/retry.cjs");
 const require_jwt = require("./jwt.cjs");
 //#region src/fcm.ts
-/** Errors FCM reports for a token that will never deliver again — not worth a retry. */
-const DEAD_TOKEN_CODES = /* @__PURE__ */ new Set([
-	"UNREGISTERED",
-	"INVALID_ARGUMENT",
-	"SENDER_ID_MISMATCH"
+/**
+* How an FCM v1 answer is classified, after the API's error codes
+* (https://firebase.google.com/docs/reference/fcm/rest/v1/ErrorCode):
+*
+* - dead token: 404 `UNREGISTERED` (the app was uninstalled, or the token expired) — also a 404
+*   whose only code is the gRPC status `NOT_FOUND`. The copy settles undelivered and the host
+*   forgets the token.
+* - undelivered, device kept: 400 `INVALID_ARGUMENT`. FCM gives it for a malformed token but
+*   just as well for a payload problem (a message too big, a bad data key, a bad TTL), which
+*   would hit every device of the template at once; the copy settles with the reason, so the
+*   report shows it, and nothing is deleted on a guess.
+* - configuration: 403 `SENDER_ID_MISMATCH` (the token belongs to another Firebase project) and
+*   401 `THIRD_PARTY_AUTH_ERROR` (the APNs or web push credentials in the Firebase project):
+*   `PermanentError`, devices kept.
+* - transient: 401 `UNAUTHENTICATED` (the cached access token is dropped first), 429
+*   `QUOTA_EXCEEDED`, 503 `UNAVAILABLE`, 500 `INTERNAL` and any other 429 / 5xx.
+* - everything else (another 4xx) is this request itself: a `PermanentError`.
+*/
+const DEAD_TOKEN_REASONS = /* @__PURE__ */ new Set(["UNREGISTERED", "NOT_FOUND"]);
+const CONFIGURATION_CODES = /* @__PURE__ */ new Set(["SENDER_ID_MISMATCH", "THIRD_PARTY_AUTH_ERROR"]);
+const TRANSIENT_CODES = /* @__PURE__ */ new Set([
+	"QUOTA_EXCEEDED",
+	"UNAVAILABLE",
+	"INTERNAL"
 ]);
 const SCOPE = "https://www.googleapis.com/auth/firebase.messaging";
+/**
+* The OAuth2 access token for one service account, exchanged once and reused until a minute
+* before it expires. Concurrent callers without a usable token share the one exchange in flight,
+* and an exchange that failed is not kept, so the next call tries again. One instance serves every
+* sender built on the account — a host keeps it across runs, and builds the senders per run.
+*/
+var FcmAccessToken = class {
+	options;
+	/** The Firebase project the account belongs to — the `messages:send` URL names it. */
+	projectId;
+	minted;
+	minting;
+	constructor(options) {
+		this.options = options;
+		this.projectId = options.serviceAccount.project_id;
+	}
+	/** The current token, exchanged now if there is none or it is about to expire. */
+	async token(now = Date.now()) {
+		if (this.minted !== void 0 && this.minted.expiresAt - 6e4 > now) return this.minted.value;
+		this.minting ??= this.exchange(now).then((minted) => {
+			this.minted = minted;
+			return minted.value;
+		}).finally(() => {
+			this.minting = void 0;
+		});
+		return this.minting;
+	}
+	/** Forget the token: FCM refused it (401), so the next call exchanges a new one. */
+	invalidate() {
+		this.minted = void 0;
+	}
+	async exchange(now) {
+		const { serviceAccount } = this.options;
+		const tokenUri = serviceAccount.token_uri ?? "https://oauth2.googleapis.com/token";
+		const assertion = await signJwt(serviceAccount, tokenUri, SCOPE, now);
+		const response = await (this.options.fetch ?? fetch)(tokenUri, {
+			method: "POST",
+			headers: { "content-type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams({
+				grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+				assertion
+			})
+		});
+		if (!response.ok) {
+			const detail = `${response.status} ${await response.text()}`;
+			if (require_engine_retry.isRetryableStatus(response.status)) throw new Error(`FCM token exchange failed: ${detail}`);
+			throw new require_engine_retry.PermanentError(`FCM token exchange refused for '${serviceAccount.client_email}': ${detail}`);
+		}
+		const json = await response.json();
+		return {
+			value: json.access_token,
+			expiresAt: now + json.expires_in * 1e3
+		};
+	}
+};
 var FcmPushSender = class {
 	options;
-	token;
 	constructor(options) {
 		this.options = options;
 	}
@@ -18,11 +92,11 @@ var FcmPushSender = class {
 		if (message.channel !== "push") throw new Error(`FcmPushSender: unsupported channel '${message.channel}'`);
 		if (message.recipient === void 0) throw new Error(`FcmPushSender: no push token for user '${message.userId}'`);
 		const { title, body, image, url } = await this.options.render(message.template, message.props);
-		const { serviceAccount, android, apns } = this.options;
-		const response = await (this.options.fetch ?? fetch)(`https://fcm.googleapis.com/v1/projects/${serviceAccount.project_id}/messages:send`, {
+		const { credentials, android, apns } = this.options;
+		const response = await (this.options.fetch ?? fetch)(`https://fcm.googleapis.com/v1/projects/${credentials.projectId}/messages:send`, {
 			method: "POST",
 			headers: {
-				authorization: `Bearer ${await this.accessToken()}`,
+				authorization: `Bearer ${await credentials.token()}`,
 				"content-type": "application/json"
 			},
 			body: JSON.stringify({ message: {
@@ -47,37 +121,29 @@ var FcmPushSender = class {
 		});
 		if (response.ok) return;
 		const text = await response.text();
-		if (DEAD_TOKEN_CODES.has(fcmErrorCode(text))) {
-			console.warn(`[fcm] token gone for user ${message.userId}: ${fcmErrorCode(text)}`);
-			await this.options.onUnregistered?.(message);
+		const { status } = response;
+		const code = fcmErrorCode(text);
+		if (code === "UNREGISTERED" || status === 404 && DEAD_TOKEN_REASONS.has(code)) {
+			console.warn(`[fcm] token gone for user ${message.userId}: ${code}`);
 			return {
 				delivered: false,
-				reason: fcmErrorCode(text)
+				reason: code
 			};
 		}
-		throw new Error(`FCM send failed: ${response.status} ${text}`);
-	}
-	async accessToken() {
-		const now = Date.now();
-		if (this.token !== void 0 && this.token.expiresAt - 6e4 > now) return this.token.value;
-		const { serviceAccount } = this.options;
-		const tokenUri = serviceAccount.token_uri ?? "https://oauth2.googleapis.com/token";
-		const assertion = await signJwt(serviceAccount, tokenUri, SCOPE, now);
-		const response = await (this.options.fetch ?? fetch)(tokenUri, {
-			method: "POST",
-			headers: { "content-type": "application/x-www-form-urlencoded" },
-			body: new URLSearchParams({
-				grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
-				assertion
-			})
-		});
-		if (!response.ok) throw new Error(`FCM token exchange failed: ${response.status} ${await response.text()}`);
-		const json = await response.json();
-		this.token = {
-			value: json.access_token,
-			expiresAt: now + json.expires_in * 1e3
-		};
-		return json.access_token;
+		if (code === "INVALID_ARGUMENT") {
+			console.warn(`[fcm] refused for user ${message.userId}: ${status} ${text}`);
+			return {
+				delivered: false,
+				reason: code
+			};
+		}
+		if (CONFIGURATION_CODES.has(code)) throw new require_engine_retry.PermanentError(`FCM refused the request for project '${credentials.projectId}': ${status} ${code}`);
+		if (status === 401 || code === "UNAUTHENTICATED") {
+			credentials.invalidate();
+			throw new Error(`FCM send failed: ${status} ${code || text} (access token renewed for the retry)`);
+		}
+		if (TRANSIENT_CODES.has(code) || require_engine_retry.isRetryableStatus(status)) throw new Error(`FCM send failed: ${status} ${code || text}`);
+		throw new require_engine_retry.PermanentError(`FCM refused the request: ${status} ${code || text}`);
 	}
 };
 /** FCM v1 error bodies carry the code at `error.status` and, for messaging, in `error.details[].errorCode`. */
@@ -112,11 +178,18 @@ async function signJwt(account, audience, scope, nowMs = Date.now()) {
 }
 /** Parse the service-account JSON as it is usually shipped: base64 of the file, in one secret. */
 function serviceAccountFromBase64(value) {
-	const json = JSON.parse(atob(value));
-	if (!json.project_id || !json.client_email || !json.private_key) throw new Error("service account JSON is missing project_id, client_email or private_key");
+	let json;
+	try {
+		json = JSON.parse(atob(value));
+	} catch (error) {
+		throw new require_engine_retry.PermanentError("service account is not base64-encoded JSON", { cause: error });
+	}
+	if (!json.project_id || !json.client_email || !json.private_key) throw new require_engine_retry.PermanentError("service account JSON is missing project_id, client_email or private_key");
 	return json;
 }
 //#endregion
+exports.DEAD_TOKEN_REASONS = DEAD_TOKEN_REASONS;
+exports.FcmAccessToken = FcmAccessToken;
 exports.FcmPushSender = FcmPushSender;
 exports.fcmErrorCode = fcmErrorCode;
 exports.serviceAccountFromBase64 = serviceAccountFromBase64;

package/dist/fcm.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"fcm.cjs","names":["base64url","pemToDer"],"sources":["../src/fcm.ts"],"sourcesContent":["import type { MessageSender, OutboundMessage, SendResult } from './engine';\nimport { base64url, pemToDer } from './jwt';\nimport type { PushRenderer } from './push';\n\n/**\n * `@shware/workflow/fcm` — push delivery through Firebase Cloud Messaging's\n * HTTP v1 API, from a service account. No dependencies: the OAuth2 access\n * token is minted by signing a JWT with WebCrypto (Workers, Node 20+, Deno,\n * Bun), so this runs wherever the engine runs.\n *\n * The recipient is an FCM registration token the app registered for the user\n * (`registerDevice`); the engine sends one message per device.\n */\n\n/** The fields of a Google service-account JSON this sender needs. */\nexport interface FcmServiceAccount {\n  project_id: string;\n  client_email: string;\n  /** PEM, `-----BEGIN PRIVATE KEY-----` (PKCS #8). */\n  private_key: string;\n  token_uri?: string;\n}\n\nexport interface FcmPushOptions {\n  serviceAccount: FcmServiceAccount;\n  render: PushRenderer;\n  /** Android-specific delivery options, e.g. `{ channel_id: 'default' }` (FCM v1 `android.notification`). */\n  android?: Record<string, unknown>;\n  /** APNs-specific payload options merged into `aps`, e.g. `{ sound: 'default' }`. */\n  apns?: Record<string, unknown>;\n  /** Fetch implementation (defaults to the global one). */\n  fetch?: typeof fetch;\n  /** Called for a token FCM reports as gone (`UNREGISTERED`); `channelsFromConfig` removes the device. */\n  onUnregistered?: (message: OutboundMessage) => Promise<void> | void;\n}\n\n/** Errors FCM reports for a token that will never deliver again — not worth a retry. */\nconst DEAD_TOKEN_CODES = new Set(['UNREGISTERED', 'INVALID_ARGUMENT', 'SENDER_ID_MISMATCH']);\n\nconst SCOPE = 'https://www.googleapis.com/auth/firebase.messaging';\n\nexport class FcmPushSender implements MessageSender {\n  private token: { value: string; expiresAt: number } | undefined;\n\n  constructor(private readonly options: FcmPushOptions) {}\n\n  async send(message: OutboundMessage): Promise<void | SendResult> {\n    if (message.channel !== 'push') {\n      throw new Error(`FcmPushSender: unsupported channel '${message.channel}'`);\n    }\n    if (message.recipient === undefined) {\n      throw new Error(`FcmPushSender: no push token for user '${message.userId}'`);\n    }\n    const { title, body, image, url } = await this.options.render(message.template, message.props);\n    const { serviceAccount, android, apns } = this.options;\n    const doFetch = this.options.fetch ?? fetch;\n\n    const response = await doFetch(\n      `https://fcm.googleapis.com/v1/projects/${serviceAccount.project_id}/messages:send`,\n      {\n        method: 'POST',\n        headers: {\n          authorization: `Bearer ${await this.accessToken()}`,\n          'content-type': 'application/json',\n        },\n        body: JSON.stringify({\n          message: {\n            token: message.recipient,\n            notification: { title, body, ...(image === undefined ? {} : { image }) },\n            // The template key travels as data so the app can route a tap; the\n            // idempotency key lets the app de-duplicate a redelivered push.\n            data: {\n              template: message.template,\n              idempotencyKey: message.idempotencyKey,\n              ...(url === undefined ? {} : { url }),\n              ...message.tracking?.data,\n            },\n            ...(android === undefined ? {} : { android: { notification: android } }),\n            apns: { payload: { aps: { sound: 'default', ...apns } } },\n          },\n        }),\n      }\n    );\n    if (response.ok) return;\n\n    const text = await response.text();\n    if (DEAD_TOKEN_CODES.has(fcmErrorCode(text))) {\n      // A dead token is a fact about the recipient, not a transient failure:\n      // report it and move on, so the step does not retry into the same wall.\n      console.warn(`[fcm] token gone for user ${message.userId}: ${fcmErrorCode(text)}`);\n      await this.options.onUnregistered?.(message);\n      return { delivered: false, reason: fcmErrorCode(text) };\n    }\n    throw new Error(`FCM send failed: ${response.status} ${text}`);\n  }\n\n  private async accessToken(): Promise<string> {\n    const now = Date.now();\n    if (this.token !== undefined && this.token.expiresAt - 60_000 > now) return this.token.value;\n\n    const { serviceAccount } = this.options;\n    const tokenUri = serviceAccount.token_uri ?? 'https://oauth2.googleapis.com/token';\n    const assertion = await signJwt(serviceAccount, tokenUri, SCOPE, now);\n    const doFetch = this.options.fetch ?? fetch;\n    const response = await doFetch(tokenUri, {\n      method: 'POST',\n      headers: { 'content-type': 'application/x-www-form-urlencoded' },\n      body: new URLSearchParams({\n        grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',\n        assertion,\n      }),\n    });\n    if (!response.ok) {\n      throw new Error(`FCM token exchange failed: ${response.status} ${await response.text()}`);\n    }\n    const json = (await response.json()) as { access_token: string; expires_in: number };\n    this.token = { value: json.access_token, expiresAt: now + json.expires_in * 1000 };\n    return json.access_token;\n  }\n}\n\n/** FCM v1 error bodies carry the code at `error.status` and, for messaging, in `error.details[].errorCode`. */\nexport function fcmErrorCode(body: string): string {\n  try {\n    const parsed = JSON.parse(body) as {\n      error?: { status?: string; details?: { errorCode?: string }[] };\n    };\n    const detail = parsed.error?.details?.find((d) => d.errorCode !== undefined)?.errorCode;\n    return detail ?? parsed.error?.status ?? '';\n  } catch {\n    return '';\n  }\n}\n\n/** RS256-sign the OAuth2 JWT assertion for a service account. */\nexport async function signJwt(\n  account: FcmServiceAccount,\n  audience: string,\n  scope: string,\n  nowMs = Date.now()\n): Promise<string> {\n  const iat = Math.floor(nowMs / 1000);\n  const header = base64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }));\n  const claims = base64url(\n    JSON.stringify({ iss: account.client_email, scope, aud: audience, iat, exp: iat + 3600 })\n  );\n  const key = await crypto.subtle.importKey(\n    'pkcs8',\n    pemToDer(account.private_key),\n    { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },\n    false,\n    ['sign']\n  );\n  const signature = await crypto.subtle.sign(\n    'RSASSA-PKCS1-v1_5',\n    key,\n    new TextEncoder().encode(`${header}.${claims}`)\n  );\n  return `${header}.${claims}.${base64url(new Uint8Array(signature))}`;\n}\n\n/** Parse the service-account JSON as it is usually shipped: base64 of the file, in one secret. */\nexport function serviceAccountFromBase64(value: string): FcmServiceAccount {\n  const json = JSON.parse(atob(value)) as Partial<FcmServiceAccount>;\n  if (!json.project_id || !json.client_email || !json.private_key) {\n    throw new Error('service account JSON is missing project_id, client_email or private_key');\n  }\n  return json as FcmServiceAccount;\n}\n"],"mappings":"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"}
+{"version":3,"file":"fcm.cjs","names":["isRetryableStatus","PermanentError","base64url","pemToDer"],"sources":["../src/fcm.ts"],"sourcesContent":["import type { MessageSender, OutboundMessage, SendResult } from './engine';\nimport { PermanentError, isRetryableStatus } from './engine/retry';\nimport { base64url, pemToDer } from './jwt';\nimport type { PushRenderer } from './push';\n\n/**\n * `@shware/workflow/fcm` — push delivery through Firebase Cloud Messaging's\n * HTTP v1 API, from a service account. No dependencies: the OAuth2 access\n * token is minted by signing a JWT with WebCrypto (Workers, Node 20+, Deno,\n * Bun), so this runs wherever the engine runs.\n *\n * The recipient is an FCM registration token the app registered for the user\n * (`registerDevice`); the engine sends one message per device.\n */\n\n/** The fields of a Google service-account JSON this sender needs. */\nexport interface FcmServiceAccount {\n  project_id: string;\n  client_email: string;\n  /** PEM, `-----BEGIN PRIVATE KEY-----` (PKCS #8). */\n  private_key: string;\n  token_uri?: string;\n}\n\nexport interface FcmAccessTokenOptions {\n  serviceAccount: FcmServiceAccount;\n  /** Fetch implementation for the token exchange (defaults to the global one). */\n  fetch?: typeof fetch;\n}\n\nexport interface FcmPushOptions {\n  /** The access token the requests carry — shared by every sender on the same service account. */\n  credentials: FcmAccessToken;\n  render: PushRenderer;\n  /** Android-specific delivery options, e.g. `{ channel_id: 'default' }` (FCM v1 `android.notification`). */\n  android?: Record<string, unknown>;\n  /** APNs-specific payload options merged into `aps`, e.g. `{ sound: 'default' }`. */\n  apns?: Record<string, unknown>;\n  /** Fetch implementation (defaults to the global one). */\n  fetch?: typeof fetch;\n}\n\n/**\n * How an FCM v1 answer is classified, after the API's error codes\n * (https://firebase.google.com/docs/reference/fcm/rest/v1/ErrorCode):\n *\n * - dead token: 404 `UNREGISTERED` (the app was uninstalled, or the token expired) — also a 404\n *   whose only code is the gRPC status `NOT_FOUND`. The copy settles undelivered and the host\n *   forgets the token.\n * - undelivered, device kept: 400 `INVALID_ARGUMENT`. FCM gives it for a malformed token but\n *   just as well for a payload problem (a message too big, a bad data key, a bad TTL), which\n *   would hit every device of the template at once; the copy settles with the reason, so the\n *   report shows it, and nothing is deleted on a guess.\n * - configuration: 403 `SENDER_ID_MISMATCH` (the token belongs to another Firebase project) and\n *   401 `THIRD_PARTY_AUTH_ERROR` (the APNs or web push credentials in the Firebase project):\n *   `PermanentError`, devices kept.\n * - transient: 401 `UNAUTHENTICATED` (the cached access token is dropped first), 429\n *   `QUOTA_EXCEEDED`, 503 `UNAVAILABLE`, 500 `INTERNAL` and any other 429 / 5xx.\n * - everything else (another 4xx) is this request itself: a `PermanentError`.\n */\nexport const DEAD_TOKEN_REASONS: ReadonlySet<string> = new Set(['UNREGISTERED', 'NOT_FOUND']);\n\nconst CONFIGURATION_CODES: ReadonlySet<string> = new Set([\n  'SENDER_ID_MISMATCH',\n  'THIRD_PARTY_AUTH_ERROR',\n]);\nconst TRANSIENT_CODES: ReadonlySet<string> = new Set(['QUOTA_EXCEEDED', 'UNAVAILABLE', 'INTERNAL']);\n\nconst SCOPE = 'https://www.googleapis.com/auth/firebase.messaging';\n\n/**\n * The OAuth2 access token for one service account, exchanged once and reused until a minute\n * before it expires. Concurrent callers without a usable token share the one exchange in flight,\n * and an exchange that failed is not kept, so the next call tries again. One instance serves every\n * sender built on the account — a host keeps it across runs, and builds the senders per run.\n */\nexport class FcmAccessToken {\n  /** The Firebase project the account belongs to — the `messages:send` URL names it. */\n  readonly projectId: string;\n  private minted: { value: string; expiresAt: number } | undefined;\n  private minting: Promise<string> | undefined;\n\n  constructor(private readonly options: FcmAccessTokenOptions) {\n    this.projectId = options.serviceAccount.project_id;\n  }\n\n  /** The current token, exchanged now if there is none or it is about to expire. */\n  async token(now = Date.now()): Promise<string> {\n    if (this.minted !== undefined && this.minted.expiresAt - 60_000 > now) {\n      return this.minted.value;\n    }\n    this.minting ??= this.exchange(now)\n      .then((minted) => {\n        this.minted = minted;\n        return minted.value;\n      })\n      .finally(() => {\n        this.minting = undefined;\n      });\n    return this.minting;\n  }\n\n  /** Forget the token: FCM refused it (401), so the next call exchanges a new one. */\n  invalidate(): void {\n    this.minted = undefined;\n  }\n\n  private async exchange(now: number): Promise<{ value: string; expiresAt: number }> {\n    const { serviceAccount } = this.options;\n    const tokenUri = serviceAccount.token_uri ?? 'https://oauth2.googleapis.com/token';\n    const assertion = await signJwt(serviceAccount, tokenUri, SCOPE, now);\n    const doFetch = this.options.fetch ?? fetch;\n    const response = await doFetch(tokenUri, {\n      method: 'POST',\n      headers: { 'content-type': 'application/x-www-form-urlencoded' },\n      body: new URLSearchParams({\n        grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',\n        assertion,\n      }),\n    });\n    if (!response.ok) {\n      const detail = `${response.status} ${await response.text()}`;\n      // A 4xx from the token endpoint (`invalid_grant`: the key was revoked, `invalid_client`)\n      // is the service account itself; only a throttled or failing endpoint is worth a retry\n      if (isRetryableStatus(response.status)) {\n        throw new Error(`FCM token exchange failed: ${detail}`);\n      }\n      throw new PermanentError(\n        `FCM token exchange refused for '${serviceAccount.client_email}': ${detail}`\n      );\n    }\n    const json = (await response.json()) as { access_token: string; expires_in: number };\n    return { value: json.access_token, expiresAt: now + json.expires_in * 1000 };\n  }\n}\n\nexport class FcmPushSender implements MessageSender {\n  constructor(private readonly options: FcmPushOptions) {}\n\n  async send(message: OutboundMessage): Promise<void | SendResult> {\n    if (message.channel !== 'push') {\n      throw new Error(`FcmPushSender: unsupported channel '${message.channel}'`);\n    }\n    if (message.recipient === undefined) {\n      throw new Error(`FcmPushSender: no push token for user '${message.userId}'`);\n    }\n    const { title, body, image, url } = await this.options.render(message.template, message.props);\n    const { credentials, android, apns } = this.options;\n    const doFetch = this.options.fetch ?? fetch;\n\n    const response = await doFetch(\n      `https://fcm.googleapis.com/v1/projects/${credentials.projectId}/messages:send`,\n      {\n        method: 'POST',\n        headers: {\n          authorization: `Bearer ${await credentials.token()}`,\n          'content-type': 'application/json',\n        },\n        body: JSON.stringify({\n          message: {\n            token: message.recipient,\n            notification: { title, body, ...(image === undefined ? {} : { image }) },\n            // The template key travels as data so the app can route a tap; the\n            // idempotency key lets the app de-duplicate a redelivered push.\n            data: {\n              template: message.template,\n              idempotencyKey: message.idempotencyKey,\n              ...(url === undefined ? {} : { url }),\n              ...message.tracking?.data,\n            },\n            ...(android === undefined ? {} : { android: { notification: android } }),\n            apns: { payload: { aps: { sound: 'default', ...apns } } },\n          },\n        }),\n      }\n    );\n    if (response.ok) return;\n\n    const text = await response.text();\n    const { status } = response;\n    const code = fcmErrorCode(text);\n    if (code === 'UNREGISTERED' || (status === 404 && DEAD_TOKEN_REASONS.has(code))) {\n      // A dead token is a fact about the recipient, not a transient failure:\n      // report it and move on, so the step does not retry into the same wall.\n      console.warn(`[fcm] token gone for user ${message.userId}: ${code}`);\n      return { delivered: false, reason: code };\n    }\n    if (code === 'INVALID_ARGUMENT') {\n      // The token or our payload: settled so the report says which device, nothing deleted\n      console.warn(`[fcm] refused for user ${message.userId}: ${status} ${text}`);\n      return { delivered: false, reason: code };\n    }\n    if (CONFIGURATION_CODES.has(code)) {\n      throw new PermanentError(\n        `FCM refused the request for project '${credentials.projectId}': ${status} ${code}`\n      );\n    }\n    if (status === 401 || code === 'UNAUTHENTICATED') {\n      // The access token was revoked before it expired: mint a new one on the retry\n      credentials.invalidate();\n      throw new Error(\n        `FCM send failed: ${status} ${code || text} (access token renewed for the retry)`\n      );\n    }\n    if (TRANSIENT_CODES.has(code) || isRetryableStatus(status)) {\n      throw new Error(`FCM send failed: ${status} ${code || text}`);\n    }\n    throw new PermanentError(`FCM refused the request: ${status} ${code || text}`);\n  }\n}\n\n/** FCM v1 error bodies carry the code at `error.status` and, for messaging, in `error.details[].errorCode`. */\nexport function fcmErrorCode(body: string): string {\n  try {\n    const parsed = JSON.parse(body) as {\n      error?: { status?: string; details?: { errorCode?: string }[] };\n    };\n    const detail = parsed.error?.details?.find((d) => d.errorCode !== undefined)?.errorCode;\n    return detail ?? parsed.error?.status ?? '';\n  } catch {\n    return '';\n  }\n}\n\n/** RS256-sign the OAuth2 JWT assertion for a service account. */\nexport async function signJwt(\n  account: FcmServiceAccount,\n  audience: string,\n  scope: string,\n  nowMs = Date.now()\n): Promise<string> {\n  const iat = Math.floor(nowMs / 1000);\n  const header = base64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }));\n  const claims = base64url(\n    JSON.stringify({ iss: account.client_email, scope, aud: audience, iat, exp: iat + 3600 })\n  );\n  const key = await crypto.subtle.importKey(\n    'pkcs8',\n    pemToDer(account.private_key),\n    { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },\n    false,\n    ['sign']\n  );\n  const signature = await crypto.subtle.sign(\n    'RSASSA-PKCS1-v1_5',\n    key,\n    new TextEncoder().encode(`${header}.${claims}`)\n  );\n  return `${header}.${claims}.${base64url(new Uint8Array(signature))}`;\n}\n\n/** Parse the service-account JSON as it is usually shipped: base64 of the file, in one secret. */\nexport function serviceAccountFromBase64(value: string): FcmServiceAccount {\n  let json: Partial<FcmServiceAccount>;\n  try {\n    json = JSON.parse(atob(value)) as Partial<FcmServiceAccount>;\n  } catch (error) {\n    // A secret that is not base64 JSON is the same on every attempt: not worth a retry\n    throw new PermanentError('service account is not base64-encoded JSON', { cause: error });\n  }\n  if (!json.project_id || !json.client_email || !json.private_key) {\n    throw new PermanentError(\n      'service account JSON is missing project_id, client_email or private_key'\n    );\n  }\n  return json as FcmServiceAccount;\n}\n"],"mappings":"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"}

package/dist/fcm.d.cts

@@ -19,8 +19,14 @@ export interface FcmServiceAccount {
   private_key: string;
   token_uri?: string;
 }
-export interface FcmPushOptions {
+export interface FcmAccessTokenOptions {
   serviceAccount: FcmServiceAccount;
+  /** Fetch implementation for the token exchange (defaults to the global one). */
+  fetch?: typeof fetch;
+}
+export interface FcmPushOptions {
+  /** The access token the requests carry — shared by every sender on the same service account. */
+  credentials: FcmAccessToken;
   render: PushRenderer;
   /** Android-specific delivery options, e.g. `{ channel_id: 'default' }` (FCM v1 `android.notification`). */
   android?: Record<string, unknown>;
@@ -28,15 +34,49 @@ export interface FcmPushOptions {
   apns?: Record<string, unknown>;
   /** Fetch implementation (defaults to the global one). */
   fetch?: typeof fetch;
-  /** Called for a token FCM reports as gone (`UNREGISTERED`); `channelsFromConfig` removes the device. */
-  onUnregistered?: (message: OutboundMessage) => Promise<void> | void;
+}
+/**
+ * How an FCM v1 answer is classified, after the API's error codes
+ * (https://firebase.google.com/docs/reference/fcm/rest/v1/ErrorCode):
+ *
+ * - dead token: 404 `UNREGISTERED` (the app was uninstalled, or the token expired) — also a 404
+ *   whose only code is the gRPC status `NOT_FOUND`. The copy settles undelivered and the host
+ *   forgets the token.
+ * - undelivered, device kept: 400 `INVALID_ARGUMENT`. FCM gives it for a malformed token but
+ *   just as well for a payload problem (a message too big, a bad data key, a bad TTL), which
+ *   would hit every device of the template at once; the copy settles with the reason, so the
+ *   report shows it, and nothing is deleted on a guess.
+ * - configuration: 403 `SENDER_ID_MISMATCH` (the token belongs to another Firebase project) and
+ *   401 `THIRD_PARTY_AUTH_ERROR` (the APNs or web push credentials in the Firebase project):
+ *   `PermanentError`, devices kept.
+ * - transient: 401 `UNAUTHENTICATED` (the cached access token is dropped first), 429
+ *   `QUOTA_EXCEEDED`, 503 `UNAVAILABLE`, 500 `INTERNAL` and any other 429 / 5xx.
+ * - everything else (another 4xx) is this request itself: a `PermanentError`.
+ */
+export declare const DEAD_TOKEN_REASONS: ReadonlySet<string>;
+/**
+ * The OAuth2 access token for one service account, exchanged once and reused until a minute
+ * before it expires. Concurrent callers without a usable token share the one exchange in flight,
+ * and an exchange that failed is not kept, so the next call tries again. One instance serves every
+ * sender built on the account — a host keeps it across runs, and builds the senders per run.
+ */
+export declare class FcmAccessToken {
+  private readonly options;
+  /** The Firebase project the account belongs to — the `messages:send` URL names it. */
+  readonly projectId: string;
+  private minted;
+  private minting;
+  constructor(options: FcmAccessTokenOptions);
+  /** The current token, exchanged now if there is none or it is about to expire. */
+  token(now?: number): Promise<string>;
+  /** Forget the token: FCM refused it (401), so the next call exchanges a new one. */
+  invalidate(): void;
+  private exchange;
 }
 export declare class FcmPushSender implements MessageSender {
   private readonly options;
-  private token;
   constructor(options: FcmPushOptions);
   send(message: OutboundMessage): Promise<void | SendResult>;
-  private accessToken;
 }
 /** FCM v1 error bodies carry the code at `error.status` and, for messaging, in `error.details[].errorCode`. */
 export declare function fcmErrorCode(body: string): string;

package/dist/fcm.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"fcm.d.cts","names":[],"sources":["../src/fcm.ts"],"mappings":";;;;;;;;;;;;;;iBAeiB;EACf;EACA;;EAEA;EACA;;iBAGe;EACf,gBAAgB;EAChB,QAAQ;;EAER,UAAU;;EAEV,OAAO;;EAEP,eAAe;;EAEf,kBAAkB,SAAS,oBAAoB;;qBAQpC,yBAAyB;mBAGP;UAFrB;EAER,YAA6B,SAAS;EAEhC,KAAK,SAAS,kBAAkB,eAAe;UAkDvC;;;wBA0BA,aAAa;;wBAaP,QACpB,SAAS,mBACT,kBACA,eACA,iBACC;;wBAsBa,yBAAyB,gBAAgB"}
+{"version":3,"file":"fcm.d.cts","names":[],"sources":["../src/fcm.ts"],"mappings":";;;;;;;;;;;;;;iBAgBiB;EACf;EACA;;EAEA;EACA;;iBAGe;EACf,gBAAgB;;EAEhB,eAAe;;iBAGA;;EAEf,aAAa;EACb,QAAQ;;EAER,UAAU;;EAEV,OAAO;;EAEP,eAAe;;;;;;;;;;;;;;;;;;;;qBAqBJ,oBAAoB;;;;;;;qBAgBpB;mBAMkB;;WAJpB;UACD;UACA;EAER,YAA6B,SAAS;;EAKhC,MAAM,eAAmB;;EAgB/B;UAIc;;qBA6BH,yBAAyB;mBACP;EAA7B,YAA6B,SAAS;EAEhC,KAAK,SAAS,kBAAkB,eAAe;;;wBAyEvC,aAAa;;wBAaP,QACpB,SAAS,mBACT,kBACA,eACA,iBACC;;wBAsBa,yBAAyB,gBAAgB"}

package/dist/fcm.d.mts

@@ -19,8 +19,14 @@ export interface FcmServiceAccount {
   private_key: string;
   token_uri?: string;
 }
-export interface FcmPushOptions {
+export interface FcmAccessTokenOptions {
   serviceAccount: FcmServiceAccount;
+  /** Fetch implementation for the token exchange (defaults to the global one). */
+  fetch?: typeof fetch;
+}
+export interface FcmPushOptions {
+  /** The access token the requests carry — shared by every sender on the same service account. */
+  credentials: FcmAccessToken;
   render: PushRenderer;
   /** Android-specific delivery options, e.g. `{ channel_id: 'default' }` (FCM v1 `android.notification`). */
   android?: Record<string, unknown>;
@@ -28,15 +34,49 @@ export interface FcmPushOptions {
   apns?: Record<string, unknown>;
   /** Fetch implementation (defaults to the global one). */
   fetch?: typeof fetch;
-  /** Called for a token FCM reports as gone (`UNREGISTERED`); `channelsFromConfig` removes the device. */
-  onUnregistered?: (message: OutboundMessage) => Promise<void> | void;
+}
+/**
+ * How an FCM v1 answer is classified, after the API's error codes
+ * (https://firebase.google.com/docs/reference/fcm/rest/v1/ErrorCode):
+ *
+ * - dead token: 404 `UNREGISTERED` (the app was uninstalled, or the token expired) — also a 404
+ *   whose only code is the gRPC status `NOT_FOUND`. The copy settles undelivered and the host
+ *   forgets the token.
+ * - undelivered, device kept: 400 `INVALID_ARGUMENT`. FCM gives it for a malformed token but
+ *   just as well for a payload problem (a message too big, a bad data key, a bad TTL), which
+ *   would hit every device of the template at once; the copy settles with the reason, so the
+ *   report shows it, and nothing is deleted on a guess.
+ * - configuration: 403 `SENDER_ID_MISMATCH` (the token belongs to another Firebase project) and
+ *   401 `THIRD_PARTY_AUTH_ERROR` (the APNs or web push credentials in the Firebase project):
+ *   `PermanentError`, devices kept.
+ * - transient: 401 `UNAUTHENTICATED` (the cached access token is dropped first), 429
+ *   `QUOTA_EXCEEDED`, 503 `UNAVAILABLE`, 500 `INTERNAL` and any other 429 / 5xx.
+ * - everything else (another 4xx) is this request itself: a `PermanentError`.
+ */
+export declare const DEAD_TOKEN_REASONS: ReadonlySet<string>;
+/**
+ * The OAuth2 access token for one service account, exchanged once and reused until a minute
+ * before it expires. Concurrent callers without a usable token share the one exchange in flight,
+ * and an exchange that failed is not kept, so the next call tries again. One instance serves every
+ * sender built on the account — a host keeps it across runs, and builds the senders per run.
+ */
+export declare class FcmAccessToken {
+  private readonly options;
+  /** The Firebase project the account belongs to — the `messages:send` URL names it. */
+  readonly projectId: string;
+  private minted;
+  private minting;
+  constructor(options: FcmAccessTokenOptions);
+  /** The current token, exchanged now if there is none or it is about to expire. */
+  token(now?: number): Promise<string>;
+  /** Forget the token: FCM refused it (401), so the next call exchanges a new one. */
+  invalidate(): void;
+  private exchange;
 }
 export declare class FcmPushSender implements MessageSender {
   private readonly options;
-  private token;
   constructor(options: FcmPushOptions);
   send(message: OutboundMessage): Promise<void | SendResult>;
-  private accessToken;
 }
 /** FCM v1 error bodies carry the code at `error.status` and, for messaging, in `error.details[].errorCode`. */
 export declare function fcmErrorCode(body: string): string;

package/dist/fcm.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"fcm.d.mts","names":[],"sources":["../src/fcm.ts"],"mappings":";;;;;;;;;;;;;;iBAeiB;EACf;EACA;;EAEA;EACA;;iBAGe;EACf,gBAAgB;EAChB,QAAQ;;EAER,UAAU;;EAEV,OAAO;;EAEP,eAAe;;EAEf,kBAAkB,SAAS,oBAAoB;;qBAQpC,yBAAyB;mBAGP;UAFrB;EAER,YAA6B,SAAS;EAEhC,KAAK,SAAS,kBAAkB,eAAe;UAkDvC;;;wBA0BA,aAAa;;wBAaP,QACpB,SAAS,mBACT,kBACA,eACA,iBACC;;wBAsBa,yBAAyB,gBAAgB"}
+{"version":3,"file":"fcm.d.mts","names":[],"sources":["../src/fcm.ts"],"mappings":";;;;;;;;;;;;;;iBAgBiB;EACf;EACA;;EAEA;EACA;;iBAGe;EACf,gBAAgB;;EAEhB,eAAe;;iBAGA;;EAEf,aAAa;EACb,QAAQ;;EAER,UAAU;;EAEV,OAAO;;EAEP,eAAe;;;;;;;;;;;;;;;;;;;;qBAqBJ,oBAAoB;;;;;;;qBAgBpB;mBAMkB;;WAJpB;UACD;UACA;EAER,YAA6B,SAAS;;EAKhC,MAAM,eAAmB;;EAgB/B;UAIc;;qBA6BH,yBAAyB;mBACP;EAA7B,YAA6B,SAAS;EAEhC,KAAK,SAAS,kBAAkB,eAAe;;;wBAyEvC,aAAa;;wBAaP,QACpB,SAAS,mBACT,kBACA,eACA,iBACC;;wBAsBa,yBAAyB,gBAAgB"}

package/dist/fcm.mjs

@@ -1,15 +1,89 @@
+import { PermanentError, isRetryableStatus } from "./engine/retry.mjs";
 import { base64url, pemToDer } from "./jwt.mjs";
 //#region src/fcm.ts
-/** Errors FCM reports for a token that will never deliver again — not worth a retry. */
-const DEAD_TOKEN_CODES = /* @__PURE__ */ new Set([
-	"UNREGISTERED",
-	"INVALID_ARGUMENT",
-	"SENDER_ID_MISMATCH"
+/**
+* How an FCM v1 answer is classified, after the API's error codes
+* (https://firebase.google.com/docs/reference/fcm/rest/v1/ErrorCode):
+*
+* - dead token: 404 `UNREGISTERED` (the app was uninstalled, or the token expired) — also a 404
+*   whose only code is the gRPC status `NOT_FOUND`. The copy settles undelivered and the host
+*   forgets the token.
+* - undelivered, device kept: 400 `INVALID_ARGUMENT`. FCM gives it for a malformed token but
+*   just as well for a payload problem (a message too big, a bad data key, a bad TTL), which
+*   would hit every device of the template at once; the copy settles with the reason, so the
+*   report shows it, and nothing is deleted on a guess.
+* - configuration: 403 `SENDER_ID_MISMATCH` (the token belongs to another Firebase project) and
+*   401 `THIRD_PARTY_AUTH_ERROR` (the APNs or web push credentials in the Firebase project):
+*   `PermanentError`, devices kept.
+* - transient: 401 `UNAUTHENTICATED` (the cached access token is dropped first), 429
+*   `QUOTA_EXCEEDED`, 503 `UNAVAILABLE`, 500 `INTERNAL` and any other 429 / 5xx.
+* - everything else (another 4xx) is this request itself: a `PermanentError`.
+*/
+const DEAD_TOKEN_REASONS = /* @__PURE__ */ new Set(["UNREGISTERED", "NOT_FOUND"]);
+const CONFIGURATION_CODES = /* @__PURE__ */ new Set(["SENDER_ID_MISMATCH", "THIRD_PARTY_AUTH_ERROR"]);
+const TRANSIENT_CODES = /* @__PURE__ */ new Set([
+	"QUOTA_EXCEEDED",
+	"UNAVAILABLE",
+	"INTERNAL"
 ]);
 const SCOPE = "https://www.googleapis.com/auth/firebase.messaging";
+/**
+* The OAuth2 access token for one service account, exchanged once and reused until a minute
+* before it expires. Concurrent callers without a usable token share the one exchange in flight,
+* and an exchange that failed is not kept, so the next call tries again. One instance serves every
+* sender built on the account — a host keeps it across runs, and builds the senders per run.
+*/
+var FcmAccessToken = class {
+	options;
+	/** The Firebase project the account belongs to — the `messages:send` URL names it. */
+	projectId;
+	minted;
+	minting;
+	constructor(options) {
+		this.options = options;
+		this.projectId = options.serviceAccount.project_id;
+	}
+	/** The current token, exchanged now if there is none or it is about to expire. */
+	async token(now = Date.now()) {
+		if (this.minted !== void 0 && this.minted.expiresAt - 6e4 > now) return this.minted.value;
+		this.minting ??= this.exchange(now).then((minted) => {
+			this.minted = minted;
+			return minted.value;
+		}).finally(() => {
+			this.minting = void 0;
+		});
+		return this.minting;
+	}
+	/** Forget the token: FCM refused it (401), so the next call exchanges a new one. */
+	invalidate() {
+		this.minted = void 0;
+	}
+	async exchange(now) {
+		const { serviceAccount } = this.options;
+		const tokenUri = serviceAccount.token_uri ?? "https://oauth2.googleapis.com/token";
+		const assertion = await signJwt(serviceAccount, tokenUri, SCOPE, now);
+		const response = await (this.options.fetch ?? fetch)(tokenUri, {
+			method: "POST",
+			headers: { "content-type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams({
+				grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+				assertion
+			})
+		});
+		if (!response.ok) {
+			const detail = `${response.status} ${await response.text()}`;
+			if (isRetryableStatus(response.status)) throw new Error(`FCM token exchange failed: ${detail}`);
+			throw new PermanentError(`FCM token exchange refused for '${serviceAccount.client_email}': ${detail}`);
+		}
+		const json = await response.json();
+		return {
+			value: json.access_token,
+			expiresAt: now + json.expires_in * 1e3
+		};
+	}
+};
 var FcmPushSender = class {
 	options;
-	token;
 	constructor(options) {
 		this.options = options;
 	}
@@ -17,11 +91,11 @@ var FcmPushSender = class {
 		if (message.channel !== "push") throw new Error(`FcmPushSender: unsupported channel '${message.channel}'`);
 		if (message.recipient === void 0) throw new Error(`FcmPushSender: no push token for user '${message.userId}'`);
 		const { title, body, image, url } = await this.options.render(message.template, message.props);
-		const { serviceAccount, android, apns } = this.options;
-		const response = await (this.options.fetch ?? fetch)(`https://fcm.googleapis.com/v1/projects/${serviceAccount.project_id}/messages:send`, {
+		const { credentials, android, apns } = this.options;
+		const response = await (this.options.fetch ?? fetch)(`https://fcm.googleapis.com/v1/projects/${credentials.projectId}/messages:send`, {
 			method: "POST",
 			headers: {
-				authorization: `Bearer ${await this.accessToken()}`,
+				authorization: `Bearer ${await credentials.token()}`,
 				"content-type": "application/json"
 			},
 			body: JSON.stringify({ message: {
@@ -46,37 +120,29 @@ var FcmPushSender = class {
 		});
 		if (response.ok) return;
 		const text = await response.text();
-		if (DEAD_TOKEN_CODES.has(fcmErrorCode(text))) {
-			console.warn(`[fcm] token gone for user ${message.userId}: ${fcmErrorCode(text)}`);
-			await this.options.onUnregistered?.(message);
+		const { status } = response;
+		const code = fcmErrorCode(text);
+		if (code === "UNREGISTERED" || status === 404 && DEAD_TOKEN_REASONS.has(code)) {
+			console.warn(`[fcm] token gone for user ${message.userId}: ${code}`);
 			return {
 				delivered: false,
-				reason: fcmErrorCode(text)
+				reason: code
 			};
 		}
-		throw new Error(`FCM send failed: ${response.status} ${text}`);
-	}
-	async accessToken() {
-		const now = Date.now();
-		if (this.token !== void 0 && this.token.expiresAt - 6e4 > now) return this.token.value;
-		const { serviceAccount } = this.options;
-		const tokenUri = serviceAccount.token_uri ?? "https://oauth2.googleapis.com/token";
-		const assertion = await signJwt(serviceAccount, tokenUri, SCOPE, now);
-		const response = await (this.options.fetch ?? fetch)(tokenUri, {
-			method: "POST",
-			headers: { "content-type": "application/x-www-form-urlencoded" },
-			body: new URLSearchParams({
-				grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
-				assertion
-			})
-		});
-		if (!response.ok) throw new Error(`FCM token exchange failed: ${response.status} ${await response.text()}`);
-		const json = await response.json();
-		this.token = {
-			value: json.access_token,
-			expiresAt: now + json.expires_in * 1e3
-		};
-		return json.access_token;
+		if (code === "INVALID_ARGUMENT") {
+			console.warn(`[fcm] refused for user ${message.userId}: ${status} ${text}`);
+			return {
+				delivered: false,
+				reason: code
+			};
+		}
+		if (CONFIGURATION_CODES.has(code)) throw new PermanentError(`FCM refused the request for project '${credentials.projectId}': ${status} ${code}`);
+		if (status === 401 || code === "UNAUTHENTICATED") {
+			credentials.invalidate();
+			throw new Error(`FCM send failed: ${status} ${code || text} (access token renewed for the retry)`);
+		}
+		if (TRANSIENT_CODES.has(code) || isRetryableStatus(status)) throw new Error(`FCM send failed: ${status} ${code || text}`);
+		throw new PermanentError(`FCM refused the request: ${status} ${code || text}`);
 	}
 };
 /** FCM v1 error bodies carry the code at `error.status` and, for messaging, in `error.details[].errorCode`. */
@@ -111,11 +177,16 @@ async function signJwt(account, audience, scope, nowMs = Date.now()) {
 }
 /** Parse the service-account JSON as it is usually shipped: base64 of the file, in one secret. */
 function serviceAccountFromBase64(value) {
-	const json = JSON.parse(atob(value));
-	if (!json.project_id || !json.client_email || !json.private_key) throw new Error("service account JSON is missing project_id, client_email or private_key");
+	let json;
+	try {
+		json = JSON.parse(atob(value));
+	} catch (error) {
+		throw new PermanentError("service account is not base64-encoded JSON", { cause: error });
+	}
+	if (!json.project_id || !json.client_email || !json.private_key) throw new PermanentError("service account JSON is missing project_id, client_email or private_key");
 	return json;
 }
 //#endregion
-export { FcmPushSender, fcmErrorCode, serviceAccountFromBase64, signJwt };
+export { DEAD_TOKEN_REASONS, FcmAccessToken, FcmPushSender, fcmErrorCode, serviceAccountFromBase64, signJwt };
 
 //# sourceMappingURL=fcm.mjs.map