@aglyn/tenant-data-admin 1.0.0-beta.230 → 1.0.0-beta.232

package/src/lib/server/plugin-event-outbox.js

@@ -0,0 +1,229 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { deliverPluginDomainEvent } from "@aglyn/aglyn/plugin-manager/plugin-domain-events";
+import { createHash } from "crypto";
+/**
+ * The outbox behind plugin events (AGL-3611): raising an event is a write
+ * here, and a scheduled drain delivers it. See `plugin-domain-events.ts` in
+ * core for the contract a raiser and a subscriber see.
+ *
+ * WHY AN OUTBOX. A fact a plugin reports — an order paid, a return refunded —
+ * must reach accounting, shipping and the merchant's webhooks even when one of
+ * them is down, and even when the process that made the write dies a moment
+ * later. Calling the subscribers in the request loses the event on either.
+ * Writing it here, in the raiser's own transaction where it has one, makes
+ * the event exist exactly when the fact does.
+ *
+ * AT LEAST ONCE, PER SUBSCRIBER. The document records which subscribers
+ * took the event (`delivered`), and a retry calls only the rest. A
+ * subscriber can still see an event twice — its handler succeeded and the
+ * write recording that did not — so the envelope's `id` is the key it
+ * dedupes on.
+ *
+ * ONE DRAIN AT A TIME PER EVENT. A pass leases the document for a minute in
+ * a transaction before it delivers, so two overlapping beats do not both
+ * deliver it. A pass that dies holding the lease is retried once the lease
+ * lapses.
+ *
+ * A delivered event is deleted: the collection holds what is still owed, so
+ * the drain's query reads nothing on an idle platform. One that runs out of
+ * attempts stays, `failed`, with each subscriber's last error.
+ */ export const PLUGIN_EVENT_OUTBOX_COLLECTION = 'pluginEventOutbox';
+/** Attempts per event before it is left as a dead letter. */ export const PLUGIN_EVENT_MAX_ATTEMPTS = 8;
+/** Wait before attempt n+1, by attempts made; the last step repeats. */ export const PLUGIN_EVENT_BACKOFF_MS = [
+    30000,
+    120000,
+    600000,
+    1800000,
+    3600000,
+    21600000,
+    43200000
+];
+/** How long a drain pass holds an event while it delivers. */ export const PLUGIN_EVENT_LEASE_MS = 60000;
+/** Events one pass reads. */ export const PLUGIN_EVENT_SCAN_LIMIT = 100;
+export function pluginEventBackoffMs(attempts) {
+    const last = PLUGIN_EVENT_BACKOFF_MS.length - 1;
+    return PLUGIN_EVENT_BACKOFF_MS[Math.max(0, Math.min(attempts - 1, last))];
+}
+/**
+ * The event's document id: the same raise twice is the same document. `key`
+ * names the occurrence (a fulfillment id, a refund id); without one every
+ * raise is new.
+ */ export function pluginEventId(hostId, event, key) {
+    return createHash('sha256').update(`${hostId}\u0000${event}\u0000${key}`).digest('hex').slice(0, 40);
+}
+/** Firestore refuses `undefined`; the payload is data, so it is plain JSON. */ function plainPayload(payload) {
+    const plain = JSON.parse(JSON.stringify(payload != null ? payload : {}));
+    return plain && typeof plain === 'object' && !Array.isArray(plain) ? plain : {
+        value: plain
+    };
+}
+function recordFor(request, now) {
+    var _request_orgId, _request_occurredAtMs;
+    return {
+        status: 'pending',
+        event: typeof request.event === 'string' ? request.event : request.event.id,
+        pluginId: request.pluginId,
+        hostId: request.hostId,
+        orgId: (_request_orgId = request.orgId) != null ? _request_orgId : null,
+        occurredAtMs: (_request_occurredAtMs = request.occurredAtMs) != null ? _request_occurredAtMs : now,
+        payload: plainPayload(request.payload),
+        attempts: 0,
+        nextAttemptAtMs: now,
+        createdAtMs: now
+    };
+}
+/**
+ * Raises an event INSIDE the caller's transaction or batch, so it is written
+ * exactly when the fact is. The write is a `set` (a transaction cannot read
+ * after it writes), so the caller's own "already done" guard is what keeps a
+ * retry from raising it twice — and the id is keyed, so if it does, the
+ * event is the same document. Returns the id.
+ */ export function stagePluginEvent(writer, firestore, request, now = Date.now()) {
+    const record = recordFor(request, now);
+    const id = pluginEventId(request.hostId, record.event, request.key);
+    writer.set(firestore.collection(PLUGIN_EVENT_OUTBOX_COLLECTION).doc(id), record);
+    return id;
+}
+const GRPC_ALREADY_EXISTS = 6;
+/**
+ * Raises an event after the fact is already written, for a raiser with no
+ * transaction to ride. `create`, so the same key raised twice — a webhook
+ * redelivered — is one event: the second answers `exists`.
+ */ export async function raisePluginEvent(firestore, request, now = Date.now()) {
+    const record = recordFor(request, now);
+    const id = pluginEventId(request.hostId, record.event, request.key);
+    try {
+        await firestore.collection(PLUGIN_EVENT_OUTBOX_COLLECTION).doc(id).create(record);
+        return {
+            id,
+            outcome: 'queued'
+        };
+    } catch (error) {
+        if ((error == null ? void 0 : error.code) === GRPC_ALREADY_EXISTS) return {
+            id,
+            outcome: 'exists'
+        };
+        console.error('[plugin-events] not queued', record.event, request.hostId, error);
+        return {
+            id,
+            outcome: 'failed'
+        };
+    }
+}
+/**
+ * Delivers one event: lease, hand it to the subscribers still owed it, and
+ * record what happened. Exported for a raiser that wants an event out now
+ * rather than on the next beat; the drain is the backstop either way.
+ */ export async function attemptPluginEvent(firestore, id, now = Date.now()) {
+    var _leased_delivered, _leased_subscriberAttempts, _leased_orgId, _leased_attempts, _leased_lastErrors;
+    const ref = firestore.collection(PLUGIN_EVENT_OUTBOX_COLLECTION).doc(id);
+    const leased = await firestore.runTransaction(async (transaction)=>{
+        var _data_leaseUntilMs, _data_nextAttemptAtMs;
+        const snapshot = await transaction.get(ref);
+        if (!snapshot.exists) return null;
+        const data = snapshot.data();
+        if (data.status !== 'pending') return null;
+        if (Number((_data_leaseUntilMs = data.leaseUntilMs) != null ? _data_leaseUntilMs : 0) > now) return null;
+        if (Number((_data_nextAttemptAtMs = data.nextAttemptAtMs) != null ? _data_nextAttemptAtMs : 0) > now) return null;
+        transaction.update(ref, {
+            leaseUntilMs: now + PLUGIN_EVENT_LEASE_MS
+        });
+        return data;
+    });
+    if (!leased) return 'leased';
+    const delivered = _extends({}, (_leased_delivered = leased.delivered) != null ? _leased_delivered : {});
+    const subscriberAttempts = _extends({}, (_leased_subscriberAttempts = leased.subscriberAttempts) != null ? _leased_subscriberAttempts : {});
+    const result = await deliverPluginDomainEvent({
+        id,
+        event: leased.event,
+        hostId: leased.hostId,
+        orgId: (_leased_orgId = leased.orgId) != null ? _leased_orgId : null,
+        occurredAtMs: leased.occurredAtMs,
+        payload: leased.payload
+    }, {
+        skip: new Set(Object.keys(delivered)),
+        attempts: subscriberAttempts
+    });
+    for (const pluginId of result.delivered){
+        var _subscriberAttempts_pluginId;
+        delivered[pluginId] = now;
+        subscriberAttempts[pluginId] = ((_subscriberAttempts_pluginId = subscriberAttempts[pluginId]) != null ? _subscriberAttempts_pluginId : 0) + 1;
+    }
+    for (const { pluginId } of result.failed){
+        var _subscriberAttempts_pluginId1;
+        subscriberAttempts[pluginId] = ((_subscriberAttempts_pluginId1 = subscriberAttempts[pluginId]) != null ? _subscriberAttempts_pluginId1 : 0) + 1;
+    }
+    if (result.failed.length === 0) {
+        await ref.delete();
+        return 'delivered';
+    }
+    const attempts = Number((_leased_attempts = leased.attempts) != null ? _leased_attempts : 0) + 1;
+    const exhausted = attempts >= PLUGIN_EVENT_MAX_ATTEMPTS;
+    const lastErrors = _extends({}, (_leased_lastErrors = leased.lastErrors) != null ? _leased_lastErrors : {});
+    for (const { pluginId, error } of result.failed)lastErrors[pluginId] = error;
+    await ref.update(_extends({
+        status: exhausted ? 'failed' : 'pending',
+        attempts,
+        delivered,
+        subscriberAttempts,
+        lastErrors,
+        leaseUntilMs: 0
+    }, exhausted ? {
+        failedAtMs: now
+    } : {
+        nextAttemptAtMs: now + pluginEventBackoffMs(attempts)
+    }));
+    if (exhausted) {
+        console.error(`[plugin-events] ${leased.event} ${id} on ${leased.hostId} gave up after ${attempts} attempts:`, lastErrors);
+        return 'dead-lettered';
+    }
+    return 'retried';
+}
+/**
+ * One beat of the drain: the events owed now, oldest first. A locked site's
+ * events wait, untouched, for the lock to lift.
+ */ export async function drainPluginEvents(gate, firestore, now = Date.now()) {
+    const due = await firestore.collection(PLUGIN_EVENT_OUTBOX_COLLECTION).where('status', '==', 'pending').where('nextAttemptAtMs', '<=', now).orderBy('nextAttemptAtMs').limit(PLUGIN_EVENT_SCAN_LIMIT).get();
+    const result = {
+        scanned: due.size,
+        delivered: 0,
+        retried: 0,
+        deadLettered: 0,
+        skippedLocked: 0,
+        skippedLeased: 0
+    };
+    for (const snapshot of due.docs){
+        var _snapshot_get;
+        const hostId = String((_snapshot_get = snapshot.get('hostId')) != null ? _snapshot_get : '');
+        if (await gate.isLocked(hostId)) {
+            result.skippedLocked += 1;
+            continue;
+        }
+        const outcome = await attemptPluginEvent(firestore, snapshot.id, now).catch((error)=>{
+            console.error('[plugin-events] attempt failed', snapshot.id, error);
+            return null;
+        });
+        if (outcome === 'delivered') result.delivered += 1;
+        else if (outcome === 'retried') result.retried += 1;
+        else if (outcome === 'dead-lettered') result.deadLettered += 1;
+        else if (outcome === 'leased') result.skippedLeased += 1;
+    }
+    return result;
+}
+
+//# sourceMappingURL=plugin-event-outbox.js.map

package/src/lib/server/plugin-event-outbox.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/plugin-event-outbox.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  deliverPluginDomainEvent,\n  type PluginDomainEvent,\n} from '@aglyn/aglyn/plugin-manager/plugin-domain-events'\nimport { createHash } from 'crypto'\n\n/**\n * The outbox behind plugin events (AGL-3611): raising an event is a write\n * here, and a scheduled drain delivers it. See `plugin-domain-events.ts` in\n * core for the contract a raiser and a subscriber see.\n *\n * WHY AN OUTBOX. A fact a plugin reports — an order paid, a return refunded —\n * must reach accounting, shipping and the merchant's webhooks even when one of\n * them is down, and even when the process that made the write dies a moment\n * later. Calling the subscribers in the request loses the event on either.\n * Writing it here, in the raiser's own transaction where it has one, makes\n * the event exist exactly when the fact does.\n *\n * AT LEAST ONCE, PER SUBSCRIBER. The document records which subscribers\n * took the event (`delivered`), and a retry calls only the rest. A\n * subscriber can still see an event twice — its handler succeeded and the\n * write recording that did not — so the envelope's `id` is the key it\n * dedupes on.\n *\n * ONE DRAIN AT A TIME PER EVENT. A pass leases the document for a minute in\n * a transaction before it delivers, so two overlapping beats do not both\n * deliver it. A pass that dies holding the lease is retried once the lease\n * lapses.\n *\n * A delivered event is deleted: the collection holds what is still owed, so\n * the drain's query reads nothing on an idle platform. One that runs out of\n * attempts stays, `failed`, with each subscriber's last error.\n */\n\nexport const PLUGIN_EVENT_OUTBOX_COLLECTION = 'pluginEventOutbox'\n\n/** Attempts per event before it is left as a dead letter. */\nexport const PLUGIN_EVENT_MAX_ATTEMPTS = 8\n\n/** Wait before attempt n+1, by attempts made; the last step repeats. */\nexport const PLUGIN_EVENT_BACKOFF_MS: readonly number[] = [\n  30_000,\n  120_000,\n  600_000,\n  1_800_000,\n  3_600_000,\n  21_600_000,\n  43_200_000,\n]\n\n/** How long a drain pass holds an event while it delivers. */\nexport const PLUGIN_EVENT_LEASE_MS = 60_000\n\n/** Events one pass reads. */\nexport const PLUGIN_EVENT_SCAN_LIMIT = 100\n\nexport type PluginEventOutboxStatus = 'pending' | 'failed'\n\n/** `pluginEventOutbox/{id}`. Written and read only by the Admin SDK. */\nexport interface PluginEventOutboxRecord {\n  status: PluginEventOutboxStatus\n  event: string\n  /** The plugin that raised it. */\n  pluginId: string\n  hostId: string\n  orgId: string | null\n  occurredAtMs: number\n  payload: Record<string, unknown>\n  attempts: number\n  nextAttemptAtMs: number\n  createdAtMs: number\n  /** Subscribers that took it, by plugin id, when. */\n  delivered?: Record<string, number>\n  /** Attempts per subscriber, for the envelope's `attempt`. */\n  subscriberAttempts?: Record<string, number>\n  /** Each failing subscriber's last error. */\n  lastErrors?: Record<string, string>\n  leaseUntilMs?: number\n  failedAtMs?: number\n}\n\nexport function pluginEventBackoffMs(attempts: number): number {\n  const last = PLUGIN_EVENT_BACKOFF_MS.length - 1\n  return PLUGIN_EVENT_BACKOFF_MS[Math.max(0, Math.min(attempts - 1, last))]\n}\n\n/**\n * The event's document id: the same raise twice is the same document. `key`\n * names the occurrence (a fulfillment id, a refund id); without one every\n * raise is new.\n */\nexport function pluginEventId(hostId: string, event: string, key: string): string {\n  return createHash('sha256').update(`${hostId}\\u0000${event}\\u0000${key}`).digest('hex').slice(0, 40)\n}\n\n/** A transaction or a batch: anything that can `set` a document. */\nexport interface PluginEventWriter {\n  set(ref: FirebaseFirestore.DocumentReference, data: FirebaseFirestore.DocumentData): unknown\n}\n\nexport interface RaisePluginEventRequest<Payload> {\n  event: PluginDomainEvent<Payload> | string\n  /** The raising plugin's id. */\n  pluginId: string\n  hostId: string\n  orgId?: string | null\n  payload: Payload\n  /** The occurrence: the same key raises the same event once. */\n  key: string\n  occurredAtMs?: number\n}\n\n/** Firestore refuses `undefined`; the payload is data, so it is plain JSON. */\nfunction plainPayload(payload: unknown): Record<string, unknown> {\n  const plain = JSON.parse(JSON.stringify(payload ?? {}))\n  return plain && typeof plain === 'object' && !Array.isArray(plain) ? plain : { value: plain }\n}\n\nfunction recordFor<Payload>(request: RaisePluginEventRequest<Payload>, now: number): PluginEventOutboxRecord {\n  return {\n    status: 'pending',\n    event: typeof request.event === 'string' ? request.event : request.event.id,\n    pluginId: request.pluginId,\n    hostId: request.hostId,\n    orgId: request.orgId ?? null,\n    occurredAtMs: request.occurredAtMs ?? now,\n    payload: plainPayload(request.payload),\n    attempts: 0,\n    nextAttemptAtMs: now,\n    createdAtMs: now,\n  }\n}\n\n/**\n * Raises an event INSIDE the caller's transaction or batch, so it is written\n * exactly when the fact is. The write is a `set` (a transaction cannot read\n * after it writes), so the caller's own \"already done\" guard is what keeps a\n * retry from raising it twice — and the id is keyed, so if it does, the\n * event is the same document. Returns the id.\n */\nexport function stagePluginEvent<Payload>(\n  writer: PluginEventWriter,\n  firestore: FirebaseFirestore.Firestore,\n  request: RaisePluginEventRequest<Payload>,\n  now = Date.now(),\n): string {\n  const record = recordFor(request, now)\n  const id = pluginEventId(request.hostId, record.event, request.key)\n  writer.set(\n    firestore.collection(PLUGIN_EVENT_OUTBOX_COLLECTION).doc(id),\n    record as unknown as FirebaseFirestore.DocumentData,\n  )\n  return id\n}\n\nconst GRPC_ALREADY_EXISTS = 6\n\n/**\n * Raises an event after the fact is already written, for a raiser with no\n * transaction to ride. `create`, so the same key raised twice — a webhook\n * redelivered — is one event: the second answers `exists`.\n */\nexport async function raisePluginEvent<Payload>(\n  firestore: FirebaseFirestore.Firestore,\n  request: RaisePluginEventRequest<Payload>,\n  now = Date.now(),\n): Promise<{ id: string; outcome: 'queued' | 'exists' | 'failed' }> {\n  const record = recordFor(request, now)\n  const id = pluginEventId(request.hostId, record.event, request.key)\n  try {\n    await firestore\n      .collection(PLUGIN_EVENT_OUTBOX_COLLECTION)\n      .doc(id)\n      .create(record as unknown as FirebaseFirestore.DocumentData)\n    return { id, outcome: 'queued' }\n  } catch (error) {\n    if ((error as { code?: number })?.code === GRPC_ALREADY_EXISTS) return { id, outcome: 'exists' }\n    console.error('[plugin-events] not queued', record.event, request.hostId, error)\n    return { id, outcome: 'failed' }\n  }\n}\n\nexport interface PluginEventDrainResult {\n  scanned: number\n  delivered: number\n  retried: number\n  deadLettered: number\n  skippedLocked: number\n  skippedLeased: number\n}\n\ntype AttemptOutcome = 'delivered' | 'retried' | 'dead-lettered' | 'leased'\n\n/**\n * Delivers one event: lease, hand it to the subscribers still owed it, and\n * record what happened. Exported for a raiser that wants an event out now\n * rather than on the next beat; the drain is the backstop either way.\n */\nexport async function attemptPluginEvent(\n  firestore: FirebaseFirestore.Firestore,\n  id: string,\n  now = Date.now(),\n): Promise<AttemptOutcome> {\n  const ref = firestore.collection(PLUGIN_EVENT_OUTBOX_COLLECTION).doc(id)\n  const leased = await firestore.runTransaction(async (transaction) => {\n    const snapshot = await transaction.get(ref)\n    if (!snapshot.exists) return null\n    const data = snapshot.data() as PluginEventOutboxRecord\n    if (data.status !== 'pending') return null\n    if (Number(data.leaseUntilMs ?? 0) > now) return null\n    if (Number(data.nextAttemptAtMs ?? 0) > now) return null\n    transaction.update(ref, { leaseUntilMs: now + PLUGIN_EVENT_LEASE_MS })\n    return data\n  })\n  if (!leased) return 'leased'\n\n  const delivered = { ...(leased.delivered ?? {}) }\n  const subscriberAttempts = { ...(leased.subscriberAttempts ?? {}) }\n  const result = await deliverPluginDomainEvent(\n    {\n      id,\n      event: leased.event,\n      hostId: leased.hostId,\n      orgId: leased.orgId ?? null,\n      occurredAtMs: leased.occurredAtMs,\n      payload: leased.payload,\n    },\n    { skip: new Set(Object.keys(delivered)), attempts: subscriberAttempts },\n  )\n  for (const pluginId of result.delivered) {\n    delivered[pluginId] = now\n    subscriberAttempts[pluginId] = (subscriberAttempts[pluginId] ?? 0) + 1\n  }\n  for (const { pluginId } of result.failed) {\n    subscriberAttempts[pluginId] = (subscriberAttempts[pluginId] ?? 0) + 1\n  }\n\n  if (result.failed.length === 0) {\n    await ref.delete()\n    return 'delivered'\n  }\n  const attempts = Number(leased.attempts ?? 0) + 1\n  const exhausted = attempts >= PLUGIN_EVENT_MAX_ATTEMPTS\n  const lastErrors = { ...(leased.lastErrors ?? {}) }\n  for (const { pluginId, error } of result.failed) lastErrors[pluginId] = error\n  await ref.update({\n    status: exhausted ? 'failed' : 'pending',\n    attempts,\n    delivered,\n    subscriberAttempts,\n    lastErrors,\n    leaseUntilMs: 0,\n    ...(exhausted ? { failedAtMs: now } : { nextAttemptAtMs: now + pluginEventBackoffMs(attempts) }),\n  })\n  if (exhausted) {\n    console.error(\n      `[plugin-events] ${leased.event} ${id} on ${leased.hostId} gave up after ${attempts} attempts:`,\n      lastErrors,\n    )\n    return 'dead-lettered'\n  }\n  return 'retried'\n}\n\n/**\n * One beat of the drain: the events owed now, oldest first. A locked site's\n * events wait, untouched, for the lock to lift.\n */\nexport async function drainPluginEvents(\n  gate: { isLocked(hostId: string): Promise<boolean> },\n  firestore: FirebaseFirestore.Firestore,\n  now = Date.now(),\n): Promise<PluginEventDrainResult> {\n  const due = await firestore\n    .collection(PLUGIN_EVENT_OUTBOX_COLLECTION)\n    .where('status', '==', 'pending')\n    .where('nextAttemptAtMs', '<=', now)\n    .orderBy('nextAttemptAtMs')\n    .limit(PLUGIN_EVENT_SCAN_LIMIT)\n    .get()\n  const result: PluginEventDrainResult = {\n    scanned: due.size,\n    delivered: 0,\n    retried: 0,\n    deadLettered: 0,\n    skippedLocked: 0,\n    skippedLeased: 0,\n  }\n  for (const snapshot of due.docs) {\n    const hostId = String(snapshot.get('hostId') ?? '')\n    if (await gate.isLocked(hostId)) {\n      result.skippedLocked += 1\n      continue\n    }\n    const outcome = await attemptPluginEvent(firestore, snapshot.id, now).catch((error) => {\n      console.error('[plugin-events] attempt failed', snapshot.id, error)\n      return null\n    })\n    if (outcome === 'delivered') result.delivered += 1\n    else if (outcome === 'retried') result.retried += 1\n    else if (outcome === 'dead-lettered') result.deadLettered += 1\n    else if (outcome === 'leased') result.skippedLeased += 1\n  }\n  return result\n}\n"],"names":["deliverPluginDomainEvent","createHash","PLUGIN_EVENT_OUTBOX_COLLECTION","PLUGIN_EVENT_MAX_ATTEMPTS","PLUGIN_EVENT_BACKOFF_MS","PLUGIN_EVENT_LEASE_MS","PLUGIN_EVENT_SCAN_LIMIT","pluginEventBackoffMs","attempts","last","length","Math","max","min","pluginEventId","hostId","event","key","update","digest","slice","plainPayload","payload","plain","JSON","parse","stringify","Array","isArray","value","recordFor","request","now","status","id","pluginId","orgId","occurredAtMs","nextAttemptAtMs","createdAtMs","stagePluginEvent","writer","firestore","Date","record","set","collection","doc","GRPC_ALREADY_EXISTS","raisePluginEvent","create","outcome","error","code","console","attemptPluginEvent","leased","ref","runTransaction","transaction","data","snapshot","get","exists","Number","leaseUntilMs","delivered","subscriberAttempts","result","skip","Set","Object","keys","failed","delete","exhausted","lastErrors","failedAtMs","drainPluginEvents","gate","due","where","orderBy","limit","scanned","size","retried","deadLettered","skippedLocked","skippedLeased","docs","String","isLocked","catch"],"mappings":"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"}

package/src/lib/server/push-apns.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Apple Push Notification service, sent directly (AGL-3651): HTTP/2 to
+ * `api.push.apple.com` (or `api.sandbox.push.apple.com` for a development
+ * build's token), authenticated with a provider token, an ES256 JWT signed
+ * with the team's APNs key.
+ *
+ *   APNS_KEY_P8   the `.p8` key: PEM text, or that PEM (or its DER) base64-encoded
+ *   APNS_KEY_ID   the key's 10-character id
+ *   APNS_TEAM_ID  the Apple Developer team id
+ *
+ * Without all three the transport is off: a device on APNs is skipped and
+ * that is logged once per process. A provider token is reused for up to 50
+ * minutes (Apple refuses one older than an hour, and one refreshed more often
+ * than every 20). A `410`, `BadDeviceToken` or `Unregistered` answer means the
+ * token is gone, and the row is pruned.
+ *
+ * Server-only, imported by `push-delivery.ts` only when a device is on APNs.
+ */
+import { type KeyObject } from 'node:crypto';
+import type { PushMessage, PushOutcome, PushTransport } from './push-delivery';
+export declare const APNS_HOSTS: {
+    readonly production: "https://api.push.apple.com";
+    readonly sandbox: "https://api.sandbox.push.apple.com";
+};
+/** A provider token is reused for at most this long. */
+export declare const APNS_TOKEN_TTL_MS: number;
+export interface ApnsCredentials {
+    key: KeyObject;
+    keyId: string;
+    teamId: string;
+}
+export interface ApnsResponse {
+    status: number;
+    body: string;
+}
+/** One HTTP/2 POST to an APNs origin; injectable for tests. */
+export type ApnsRequest = (origin: string, headers: Record<string, string>, body: string) => Promise<ApnsResponse>;
+/** The `.p8` key from `APNS_KEY_P8`: PEM, base64 of the PEM, or base64 of the DER. */
+export declare function parseApnsKey(raw: string): KeyObject;
+export declare function apnsCredentials(env: Record<string, string | undefined>): ApnsCredentials | null;
+/** An ES256 provider token: `{alg, kid}.{iss, iat}`, signed raw (r‖s), as APNs requires. */
+export declare function apnsProviderToken(credentials: ApnsCredentials, nowMs: number): string;
+/** The APNs payload: the alert, the default sound, and the tap data beside `aps`. */
+export declare function apnsPayload(message: PushMessage): string;
+export declare function apnsOutcome(response: ApnsResponse): PushOutcome;
+export interface ApnsTransportOptions {
+    credentials: ApnsCredentials;
+    /** Injected in tests; the default opens HTTP/2 sessions per send. */
+    request?: ApnsRequest;
+    now?: () => number;
+}
+export declare function createApnsTransport(options: ApnsTransportOptions): PushTransport;
+/**
+ * The deployment's APNs transport from `APNS_*`, or null — logged once —
+ * when they are not set.
+ */
+export declare function apnsTransport(env?: Record<string, string | undefined>): PushTransport | null;

package/src/lib/server/push-apns.js

@@ -0,0 +1,225 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Apple Push Notification service, sent directly (AGL-3651): HTTP/2 to
+ * `api.push.apple.com` (or `api.sandbox.push.apple.com` for a development
+ * build's token), authenticated with a provider token, an ES256 JWT signed
+ * with the team's APNs key.
+ *
+ *   APNS_KEY_P8   the `.p8` key: PEM text, or that PEM (or its DER) base64-encoded
+ *   APNS_KEY_ID   the key's 10-character id
+ *   APNS_TEAM_ID  the Apple Developer team id
+ *
+ * Without all three the transport is off: a device on APNs is skipped and
+ * that is logged once per process. A provider token is reused for up to 50
+ * minutes (Apple refuses one older than an hour, and one refreshed more often
+ * than every 20). A `410`, `BadDeviceToken` or `Unregistered` answer means the
+ * token is gone, and the row is pruned.
+ *
+ * Server-only, imported by `push-delivery.ts` only when a device is on APNs.
+ */ import { createPrivateKey, sign } from "node:crypto";
+import { connect } from "node:http2";
+export const APNS_HOSTS = {
+    production: 'https://api.push.apple.com',
+    sandbox: 'https://api.sandbox.push.apple.com'
+};
+/** A provider token is reused for at most this long. */ export const APNS_TOKEN_TTL_MS = 50 * 60 * 1000;
+/** Requests in flight at once on one connection. */ const CONCURRENCY = 20;
+const base64url = (input)=>Buffer.from(input).toString('base64url');
+/** The `.p8` key from `APNS_KEY_P8`: PEM, base64 of the PEM, or base64 of the DER. */ export function parseApnsKey(raw) {
+    const text = raw.trim().replace(/\\n/g, '\n');
+    if (text.includes('-----BEGIN')) return createPrivateKey(text);
+    const decoded = Buffer.from(text, 'base64');
+    const asText = decoded.toString('utf8');
+    if (asText.includes('-----BEGIN')) return createPrivateKey(asText);
+    return createPrivateKey({
+        key: decoded,
+        format: 'der',
+        type: 'pkcs8'
+    });
+}
+export function apnsCredentials(env) {
+    var _env_APNS_KEY_P8, _env_APNS_KEY_ID, _env_APNS_TEAM_ID;
+    const raw = (_env_APNS_KEY_P8 = env['APNS_KEY_P8']) == null ? void 0 : _env_APNS_KEY_P8.trim();
+    const keyId = (_env_APNS_KEY_ID = env['APNS_KEY_ID']) == null ? void 0 : _env_APNS_KEY_ID.trim();
+    const teamId = (_env_APNS_TEAM_ID = env['APNS_TEAM_ID']) == null ? void 0 : _env_APNS_TEAM_ID.trim();
+    if (!raw || !keyId || !teamId) return null;
+    return {
+        key: parseApnsKey(raw),
+        keyId,
+        teamId
+    };
+}
+/** An ES256 provider token: `{alg, kid}.{iss, iat}`, signed raw (r‖s), as APNs requires. */ export function apnsProviderToken(credentials, nowMs) {
+    const header = base64url(JSON.stringify({
+        alg: 'ES256',
+        kid: credentials.keyId
+    }));
+    const claims = base64url(JSON.stringify({
+        iss: credentials.teamId,
+        iat: Math.floor(nowMs / 1000)
+    }));
+    const signature = sign('sha256', Buffer.from(`${header}.${claims}`), {
+        key: credentials.key,
+        dsaEncoding: 'ieee-p1363'
+    });
+    return `${header}.${claims}.${base64url(signature)}`;
+}
+/** The APNs payload: the alert, the default sound, and the tap data beside `aps`. */ export function apnsPayload(message) {
+    return JSON.stringify(_extends({
+        aps: {
+            alert: _extends({
+                title: message.title
+            }, message.body ? {
+                body: message.body
+            } : {}),
+            sound: 'default'
+        }
+    }, message.data));
+}
+const GONE = new Set([
+    'BadDeviceToken',
+    'Unregistered',
+    'DeviceTokenNotForTopic'
+]);
+export function apnsOutcome(response) {
+    if (response.status === 200) return 'sent';
+    if (response.status === 410) return 'prune';
+    let reason = '';
+    try {
+        var _ref;
+        var _JSON_parse;
+        reason = String((_ref = (_JSON_parse = JSON.parse(response.body)) == null ? void 0 : _JSON_parse.reason) != null ? _ref : '');
+    } catch (unused) {
+    // An unreadable body is a failure, not a verdict on the token.
+    }
+    return GONE.has(reason) ? 'prune' : 'failed';
+}
+/** The default request: one HTTP/2 session per origin for the life of a send. */ function http2Requester() {
+    const sessions = new Map();
+    const session = (origin)=>{
+        let open = sessions.get(origin);
+        if (!open || open.closed || open.destroyed) {
+            open = connect(origin);
+            open.on('error', ()=>undefined);
+            sessions.set(origin, open);
+        }
+        return open;
+    };
+    const request = (origin, headers, body)=>new Promise((resolve, reject)=>{
+            const stream = session(origin).request(_extends({
+                ':method': 'POST'
+            }, headers));
+            let status = 0;
+            let text = '';
+            stream.setEncoding('utf8');
+            stream.setTimeout(15000, ()=>stream.close());
+            stream.on('response', (head)=>{
+                var _head_status;
+                status = Number((_head_status = head[':status']) != null ? _head_status : 0);
+            });
+            stream.on('data', (chunk)=>{
+                text += chunk;
+            });
+            stream.on('end', ()=>resolve({
+                    status,
+                    body: text
+                }));
+            stream.on('error', reject);
+            stream.end(body);
+        });
+    return {
+        request,
+        close: ()=>{
+            for (const open of sessions.values())open.close();
+            sessions.clear();
+        }
+    };
+}
+export function createApnsTransport(options) {
+    var _options_now;
+    const now = (_options_now = options.now) != null ? _options_now : Date.now;
+    let cached = null;
+    const providerToken = ()=>{
+        const at = now();
+        if (!cached || at - cached.at >= APNS_TOKEN_TTL_MS) cached = {
+            token: apnsProviderToken(options.credentials, at),
+            at
+        };
+        return cached.token;
+    };
+    return {
+        async send (targets, message) {
+            const { request, close } = options.request ? {
+                request: options.request,
+                close: ()=>undefined
+            } : http2Requester();
+            const body = apnsPayload(message);
+            const outcomes = new Array(targets.length).fill('failed');
+            try {
+                for(let start = 0; start < targets.length; start += CONCURRENCY){
+                    const batch = targets.slice(start, start + CONCURRENCY);
+                    await Promise.all(batch.map(async (target, offset)=>{
+                        try {
+                            var _target_apnsEnvironment;
+                            const response = await request(APNS_HOSTS[(_target_apnsEnvironment = target.apnsEnvironment) != null ? _target_apnsEnvironment : 'production'], {
+                                ':path': `/3/device/${target.token}`,
+                                authorization: `bearer ${providerToken()}`,
+                                'apns-topic': target.topic,
+                                'apns-push-type': 'alert',
+                                'apns-priority': message.urgent ? '10' : '5',
+                                'content-type': 'application/json'
+                            }, body);
+                            // An expired or refused provider token is ours to mint again, not the device's fault.
+                            if (response.status === 403) cached = null;
+                            outcomes[start + offset] = apnsOutcome(response);
+                        } catch (unused) {
+                            outcomes[start + offset] = 'failed';
+                        }
+                    }));
+                }
+            } finally{
+                close();
+            }
+            return outcomes;
+        }
+    };
+}
+let warnedMissingKey = false;
+let configured = null;
+/**
+ * The deployment's APNs transport from `APNS_*`, or null — logged once —
+ * when they are not set.
+ */ export function apnsTransport(env = process.env) {
+    if (configured) return configured.transport;
+    const credentials = apnsCredentials(env);
+    if (!credentials) {
+        if (!warnedMissingKey) {
+            warnedMissingKey = true;
+            console.warn('push: APNS_KEY_P8, APNS_KEY_ID and APNS_TEAM_ID are not all set; iOS and macOS devices are skipped');
+        }
+        return null;
+    }
+    configured = {
+        transport: createApnsTransport({
+            credentials
+        })
+    };
+    return configured.transport;
+}
+
+//# sourceMappingURL=push-apns.js.map

package/src/lib/server/push-apns.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/push-apns.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Apple Push Notification service, sent directly (AGL-3651): HTTP/2 to\n * `api.push.apple.com` (or `api.sandbox.push.apple.com` for a development\n * build's token), authenticated with a provider token, an ES256 JWT signed\n * with the team's APNs key.\n *\n *   APNS_KEY_P8   the `.p8` key: PEM text, or that PEM (or its DER) base64-encoded\n *   APNS_KEY_ID   the key's 10-character id\n *   APNS_TEAM_ID  the Apple Developer team id\n *\n * Without all three the transport is off: a device on APNs is skipped and\n * that is logged once per process. A provider token is reused for up to 50\n * minutes (Apple refuses one older than an hour, and one refreshed more often\n * than every 20). A `410`, `BadDeviceToken` or `Unregistered` answer means the\n * token is gone, and the row is pruned.\n *\n * Server-only, imported by `push-delivery.ts` only when a device is on APNs.\n */\n\nimport { createPrivateKey, sign, type KeyObject } from 'node:crypto'\nimport { connect, type ClientHttp2Session } from 'node:http2'\nimport type { PushMessage, PushOutcome, PushTarget, PushTransport } from './push-delivery'\n\nexport const APNS_HOSTS = {\n  production: 'https://api.push.apple.com',\n  sandbox: 'https://api.sandbox.push.apple.com',\n} as const\n\n/** A provider token is reused for at most this long. */\nexport const APNS_TOKEN_TTL_MS = 50 * 60 * 1000\n\n/** Requests in flight at once on one connection. */\nconst CONCURRENCY = 20\n\nexport interface ApnsCredentials {\n  key: KeyObject\n  keyId: string\n  teamId: string\n}\n\nexport interface ApnsResponse {\n  status: number\n  body: string\n}\n\n/** One HTTP/2 POST to an APNs origin; injectable for tests. */\nexport type ApnsRequest = (origin: string, headers: Record<string, string>, body: string) => Promise<ApnsResponse>\n\nconst base64url = (input: Buffer | string) => Buffer.from(input).toString('base64url')\n\n/** The `.p8` key from `APNS_KEY_P8`: PEM, base64 of the PEM, or base64 of the DER. */\nexport function parseApnsKey(raw: string): KeyObject {\n  const text = raw.trim().replace(/\\\\n/g, '\\n')\n  if (text.includes('-----BEGIN')) return createPrivateKey(text)\n  const decoded = Buffer.from(text, 'base64')\n  const asText = decoded.toString('utf8')\n  if (asText.includes('-----BEGIN')) return createPrivateKey(asText)\n  return createPrivateKey({ key: decoded, format: 'der', type: 'pkcs8' })\n}\n\nexport function apnsCredentials(env: Record<string, string | undefined>): ApnsCredentials | null {\n  const raw = env['APNS_KEY_P8']?.trim()\n  const keyId = env['APNS_KEY_ID']?.trim()\n  const teamId = env['APNS_TEAM_ID']?.trim()\n  if (!raw || !keyId || !teamId) return null\n  return { key: parseApnsKey(raw), keyId, teamId }\n}\n\n/** An ES256 provider token: `{alg, kid}.{iss, iat}`, signed raw (r‖s), as APNs requires. */\nexport function apnsProviderToken(credentials: ApnsCredentials, nowMs: number): string {\n  const header = base64url(JSON.stringify({ alg: 'ES256', kid: credentials.keyId }))\n  const claims = base64url(JSON.stringify({ iss: credentials.teamId, iat: Math.floor(nowMs / 1000) }))\n  const signature = sign('sha256', Buffer.from(`${header}.${claims}`), {\n    key: credentials.key,\n    dsaEncoding: 'ieee-p1363',\n  })\n  return `${header}.${claims}.${base64url(signature)}`\n}\n\n/** The APNs payload: the alert, the default sound, and the tap data beside `aps`. */\nexport function apnsPayload(message: PushMessage): string {\n  return JSON.stringify({\n    aps: {\n      alert: { title: message.title, ...(message.body ? { body: message.body } : {}) },\n      sound: 'default',\n    },\n    ...message.data,\n  })\n}\n\nconst GONE = new Set(['BadDeviceToken', 'Unregistered', 'DeviceTokenNotForTopic'])\n\nexport function apnsOutcome(response: ApnsResponse): PushOutcome {\n  if (response.status === 200) return 'sent'\n  if (response.status === 410) return 'prune'\n  let reason = ''\n  try {\n    reason = String(JSON.parse(response.body)?.reason ?? '')\n  } catch {\n    // An unreadable body is a failure, not a verdict on the token.\n  }\n  return GONE.has(reason) ? 'prune' : 'failed'\n}\n\n/** The default request: one HTTP/2 session per origin for the life of a send. */\nfunction http2Requester(): { request: ApnsRequest; close: () => void } {\n  const sessions = new Map<string, ClientHttp2Session>()\n  const session = (origin: string) => {\n    let open = sessions.get(origin)\n    if (!open || open.closed || open.destroyed) {\n      open = connect(origin)\n      open.on('error', () => undefined)\n      sessions.set(origin, open)\n    }\n    return open\n  }\n  const request: ApnsRequest = (origin, headers, body) =>\n    new Promise((resolve, reject) => {\n      const stream = session(origin).request({ ':method': 'POST', ...headers })\n      let status = 0\n      let text = ''\n      stream.setEncoding('utf8')\n      stream.setTimeout(15_000, () => stream.close())\n      stream.on('response', (head) => {\n        status = Number(head[':status'] ?? 0)\n      })\n      stream.on('data', (chunk: string) => {\n        text += chunk\n      })\n      stream.on('end', () => resolve({ status, body: text }))\n      stream.on('error', reject)\n      stream.end(body)\n    })\n  return {\n    request,\n    close: () => {\n      for (const open of sessions.values()) open.close()\n      sessions.clear()\n    },\n  }\n}\n\nexport interface ApnsTransportOptions {\n  credentials: ApnsCredentials\n  /** Injected in tests; the default opens HTTP/2 sessions per send. */\n  request?: ApnsRequest\n  now?: () => number\n}\n\nexport function createApnsTransport(options: ApnsTransportOptions): PushTransport {\n  const now = options.now ?? Date.now\n  let cached: { token: string; at: number } | null = null\n  const providerToken = () => {\n    const at = now()\n    if (!cached || at - cached.at >= APNS_TOKEN_TTL_MS) cached = { token: apnsProviderToken(options.credentials, at), at }\n    return cached.token\n  }\n  return {\n    async send(targets: readonly PushTarget[], message: PushMessage): Promise<PushOutcome[]> {\n      const { request, close } = options.request\n        ? { request: options.request, close: () => undefined }\n        : http2Requester()\n      const body = apnsPayload(message)\n      const outcomes: PushOutcome[] = new Array(targets.length).fill('failed')\n      try {\n        for (let start = 0; start < targets.length; start += CONCURRENCY) {\n          const batch = targets.slice(start, start + CONCURRENCY)\n          await Promise.all(\n            batch.map(async (target, offset) => {\n              try {\n                const response = await request(\n                  APNS_HOSTS[target.apnsEnvironment ?? 'production'],\n                  {\n                    ':path': `/3/device/${target.token}`,\n                    authorization: `bearer ${providerToken()}`,\n                    'apns-topic': target.topic,\n                    'apns-push-type': 'alert',\n                    'apns-priority': message.urgent ? '10' : '5',\n                    'content-type': 'application/json',\n                  },\n                  body,\n                )\n                // An expired or refused provider token is ours to mint again, not the device's fault.\n                if (response.status === 403) cached = null\n                outcomes[start + offset] = apnsOutcome(response)\n              } catch {\n                outcomes[start + offset] = 'failed'\n              }\n            }),\n          )\n        }\n      } finally {\n        close()\n      }\n      return outcomes\n    },\n  }\n}\n\nlet warnedMissingKey = false\nlet configured: { transport: PushTransport } | null = null\n\n/**\n * The deployment's APNs transport from `APNS_*`, or null — logged once —\n * when they are not set.\n */\nexport function apnsTransport(env: Record<string, string | undefined> = process.env): PushTransport | null {\n  if (configured) return configured.transport\n  const credentials = apnsCredentials(env)\n  if (!credentials) {\n    if (!warnedMissingKey) {\n      warnedMissingKey = true\n      console.warn('push: APNS_KEY_P8, APNS_KEY_ID and APNS_TEAM_ID are not all set; iOS and macOS devices are skipped')\n    }\n    return null\n  }\n  configured = { transport: createApnsTransport({ credentials }) }\n  return configured.transport\n}\n"],"names":["createPrivateKey","sign","connect","APNS_HOSTS","production","sandbox","APNS_TOKEN_TTL_MS","CONCURRENCY","base64url","input","Buffer","from","toString","parseApnsKey","raw","text","trim","replace","includes","decoded","asText","key","format","type","apnsCredentials","env","keyId","teamId","apnsProviderToken","credentials","nowMs","header","JSON","stringify","alg","kid","claims","iss","iat","Math","floor","signature","dsaEncoding","apnsPayload","message","aps","alert","title","body","sound","data","GONE","Set","apnsOutcome","response","status","reason","String","parse","has","http2Requester","sessions","Map","session","origin","open","get","closed","destroyed","on","undefined","set","request","headers","Promise","resolve","reject","stream","setEncoding","setTimeout","close","head","Number","chunk","end","values","clear","createApnsTransport","options","now","Date","cached","providerToken","at","token","send","targets","outcomes","Array","length","fill","start","batch","slice","all","map","target","offset","apnsEnvironment","authorization","topic","urgent","warnedMissingKey","configured","apnsTransport","process","transport","console","warn"],"mappings":"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"}