Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/apps/worker/src/jobs/push-notification.ts
T

162 lines
5.7 KiB
TypeScript

/**
* Phase 08 #65 — Push-notification fan-out worker.
*
* Consumes events emitted via the existing notifications pipeline and
* dispatches one APNs / FCM / WebPush call per active DeviceToken for
* the recipient user. The worker is intentionally provider-pluggable:
* the two SDK adapters (firebase-admin for FCM, node-apn for APNs) are
* injected through the `providers` seam so unit tests can mock them
* without dragging the actual libraries into Vitest's module graph.
*
* Provider response codes that signal a permanent invalidation
* (`Unregistered`, `InvalidRegistration`, `BadDeviceToken`) flip the
* matching DeviceToken's `revokedAt` so subsequent fan-out passes skip
* the dead row.
*
* Bootstrap-time config (apps/worker/src/index.ts) reads:
* - FCM_SERVICE_ACCOUNT_JSON (base64 or raw JSON for the FCM key)
* - APNS_KEY (PEM contents of the .p8 sign key)
* - APNS_KEY_ID (10-char key id from Apple Developer)
* - APNS_TEAM_ID (10-char team id)
* - APNS_BUNDLE_ID (defaults to de.toolctrl.app)
*
* @see packages/db/src/device-tokens.server.ts
* @see apps/mobile/src/pushRegistration.ts
*/
import { mapWithConcurrency } from "@toolctrl/foundation";
export type PushTargetPlatform = "ios" | "android" | "web";
export type PushProviderResult = {
/** Provider-side message id, when available. */
messageId?: string;
/** Whether the provider accepted the push. */
success: boolean;
/** Provider error code (e.g. `Unregistered`, `InvalidRegistration`). */
errorCode?: string;
};
export type PushPayload = {
/** Bearer/user/tenant context — also forwarded to the provider as APS-data. */
userId: string;
tenantId: string | null;
title: string;
body: string;
data?: Record<string, string>;
};
export type DeviceTokenRow = {
id: string;
token: string;
userId: string;
tenantId: string | null;
platform: string;
pushProvider: string;
revokedAt: Date | null;
};
export type PushProviderSeam = {
sendFcm: (token: string, payload: PushPayload) => Promise<PushProviderResult>;
sendApns: (token: string, payload: PushPayload) => Promise<PushProviderResult>;
sendWebPush: (token: string, payload: PushPayload) => Promise<PushProviderResult>;
};
export type PushFanOutInput = {
payload: PushPayload;
/** Lister: active (revokedAt IS NULL) tokens for the recipient. */
tokenLister: (args: { userId: string; tenantId: string | null }) => Promise<readonly DeviceTokenRow[]>;
/** Provider seam — injected by apps/worker/src/index.ts. */
providers: PushProviderSeam;
/** Revoke seam — called when the provider returns a permanent error. */
tokenRevoker: (token: string) => Promise<void>;
/** Max active device tokens sent at once. Default is intentionally conservative. */
concurrency?: number;
/** Optional logger. */
logger?: {
info: (fields: Record<string, unknown>, msg: string) => void;
warn?: (fields: Record<string, unknown>, msg: string) => void;
error?: (fields: Record<string, unknown>, msg: string) => void;
};
};
export type PushFanOutResult = {
attempted: number;
succeeded: number;
revoked: number;
failed: number;
};
const REVOCATION_ERROR_CODES = new Set([
"Unregistered",
"InvalidRegistration",
"BadDeviceToken",
"DeviceTokenNotForTopic",
"messaging/registration-token-not-registered",
"messaging/invalid-registration-token",
]);
export const PUSH_NOTIFICATION_FAN_OUT_CONCURRENCY = 5;
/**
* Fan out a single notification to every active device for the user.
*
* Pure orchestrator — no DB / SDK imports — so it can be unit-tested with
* Map-backed stubs. The worker entry point wires the seams against the
* real Prisma client and provider SDKs.
*/
export async function dispatchPushNotification(input: PushFanOutInput): Promise<PushFanOutResult> {
const tokens = await input.tokenLister({ userId: input.payload.userId, tenantId: input.payload.tenantId });
const active = tokens.filter((row) => row.revokedAt === null);
let succeeded = 0;
let revoked = 0;
let failed = 0;
await mapWithConcurrency(active, input.concurrency ?? PUSH_NOTIFICATION_FAN_OUT_CONCURRENCY, async (row) => {
const result = await sendForRow(row, input.payload, input.providers);
if (result.success) {
succeeded += 1;
input.logger?.info(
{ token: redactToken(row.token), platform: row.platform, provider: row.pushProvider, messageId: result.messageId },
"push delivered",
);
return;
}
if (result.errorCode && REVOCATION_ERROR_CODES.has(result.errorCode)) {
await input.tokenRevoker(row.token);
revoked += 1;
input.logger?.warn?.(
{ token: redactToken(row.token), platform: row.platform, errorCode: result.errorCode },
"push provider reported token revoked",
);
return;
}
failed += 1;
input.logger?.error?.(
{ token: redactToken(row.token), platform: row.platform, errorCode: result.errorCode },
"push delivery failed",
);
});
return { attempted: active.length, succeeded, revoked, failed };
}
async function sendForRow(row: DeviceTokenRow, payload: PushPayload, providers: PushProviderSeam): Promise<PushProviderResult> {
if (row.platform === "ios" || row.pushProvider === "apns") {
return providers.sendApns(row.token, payload);
}
if (row.platform === "android" || row.pushProvider === "fcm") {
return providers.sendFcm(row.token, payload);
}
return providers.sendWebPush(row.token, payload);
}
/** Redacts everything but the leading 8 chars of a token for log lines. */
export function redactToken(token: string): string {
if (token.length <= 8) return `${token.slice(0, 2)}…`;
return `${token.slice(0, 8)}…`;
}
export { REVOCATION_ERROR_CODES };