@aglyn/tenant-data-admin 1.0.0-beta.229 → 1.0.0-beta.231

package/src/lib/server/plugin-event-outbox.d.ts

@@ -0,0 +1,138 @@
+/**
+ * @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 { type PluginDomainEvent } from '@aglyn/aglyn/plugin-manager/plugin-domain-events';
+/**
+ * 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 declare const PLUGIN_EVENT_OUTBOX_COLLECTION = "pluginEventOutbox";
+/** Attempts per event before it is left as a dead letter. */
+export declare const PLUGIN_EVENT_MAX_ATTEMPTS = 8;
+/** Wait before attempt n+1, by attempts made; the last step repeats. */
+export declare const PLUGIN_EVENT_BACKOFF_MS: readonly number[];
+/** How long a drain pass holds an event while it delivers. */
+export declare const PLUGIN_EVENT_LEASE_MS = 60000;
+/** Events one pass reads. */
+export declare const PLUGIN_EVENT_SCAN_LIMIT = 100;
+export type PluginEventOutboxStatus = 'pending' | 'failed';
+/** `pluginEventOutbox/{id}`. Written and read only by the Admin SDK. */
+export interface PluginEventOutboxRecord {
+    status: PluginEventOutboxStatus;
+    event: string;
+    /** The plugin that raised it. */
+    pluginId: string;
+    hostId: string;
+    orgId: string | null;
+    occurredAtMs: number;
+    payload: Record<string, unknown>;
+    attempts: number;
+    nextAttemptAtMs: number;
+    createdAtMs: number;
+    /** Subscribers that took it, by plugin id, when. */
+    delivered?: Record<string, number>;
+    /** Attempts per subscriber, for the envelope's `attempt`. */
+    subscriberAttempts?: Record<string, number>;
+    /** Each failing subscriber's last error. */
+    lastErrors?: Record<string, string>;
+    leaseUntilMs?: number;
+    failedAtMs?: number;
+}
+export declare function pluginEventBackoffMs(attempts: number): number;
+/**
+ * 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 declare function pluginEventId(hostId: string, event: string, key: string): string;
+/** A transaction or a batch: anything that can `set` a document. */
+export interface PluginEventWriter {
+    set(ref: FirebaseFirestore.DocumentReference, data: FirebaseFirestore.DocumentData): unknown;
+}
+export interface RaisePluginEventRequest<Payload> {
+    event: PluginDomainEvent<Payload> | string;
+    /** The raising plugin's id. */
+    pluginId: string;
+    hostId: string;
+    orgId?: string | null;
+    payload: Payload;
+    /** The occurrence: the same key raises the same event once. */
+    key: string;
+    occurredAtMs?: number;
+}
+/**
+ * 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 declare function stagePluginEvent<Payload>(writer: PluginEventWriter, firestore: FirebaseFirestore.Firestore, request: RaisePluginEventRequest<Payload>, now?: number): string;
+/**
+ * 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 declare function raisePluginEvent<Payload>(firestore: FirebaseFirestore.Firestore, request: RaisePluginEventRequest<Payload>, now?: number): Promise<{
+    id: string;
+    outcome: 'queued' | 'exists' | 'failed';
+}>;
+export interface PluginEventDrainResult {
+    scanned: number;
+    delivered: number;
+    retried: number;
+    deadLettered: number;
+    skippedLocked: number;
+    skippedLeased: number;
+}
+type AttemptOutcome = 'delivered' | 'retried' | 'dead-lettered' | 'leased';
+/**
+ * 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 declare function attemptPluginEvent(firestore: FirebaseFirestore.Firestore, id: string, now?: number): Promise<AttemptOutcome>;
+/**
+ * One beat of the drain: the events owed now, oldest first. A locked site's
+ * events wait, untouched, for the lock to lift.
+ */
+export declare function drainPluginEvents(gate: {
+    isLocked(hostId: string): Promise<boolean>;
+}, firestore: FirebaseFirestore.Firestore, now?: number): Promise<PluginEventDrainResult>;
+export {};

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;