@open-mercato/core 0.6.8-develop.6983.1.e4f794099e → 0.6.8-develop.6985.1.fb93574faa

package/dist/modules/communication_channels/lib/access-control.js

@@ -1,5 +1,13 @@
 import { authorizeFeatures } from "@open-mercato/shared/security/featurePolicy";
 const ADMIN_FEATURE = "communication_channels.admin";
+function channelOrgScopeWhere(orgId) {
+  return orgId ? { $or: [{ organizationId: orgId }, { organizationId: null }] } : { organizationId: null };
+}
+function channelOrgScopeWhereFromFilter(filter) {
+  const organizationIds = filter?.organizationIds;
+  if (!organizationIds || organizationIds.length === 0) return {};
+  return { $or: [{ organizationId: { $in: organizationIds } }, { organizationId: null }] };
+}
 function assertCanAccessChannel(channel, currentUserId, userFeatures) {
   if (!channel) {
     throw new ChannelAccessDeniedError("Channel not found");
@@ -38,6 +46,8 @@ export {
   ADMIN_FEATURE,
   ChannelAccessDeniedError,
   assertCanAccessChannel,
-  assertCanManageChannel
+  assertCanManageChannel,
+  channelOrgScopeWhere,
+  channelOrgScopeWhereFromFilter
 };
 //# sourceMappingURL=access-control.js.map

package/dist/modules/communication_channels/lib/access-control.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/modules/communication_channels/lib/access-control.ts"],
-  "sourcesContent": ["import { authorizeFeatures } from '@open-mercato/shared/security/featurePolicy'\n\n/**\n * Per-user channel access control \u2014 service-layer authorization helpers.\n *\n * Personal mailbox privacy (v1: strict owner-only). A per-user channel\n * (`userId` set) may be read or managed ONLY by its owner \u2014 not even an admin\n * or superadmin can act on another user's personal mailbox. Tenant-wide /\n * shared channels (`userId == null`, e.g. WhatsApp Business / Slack workspaces)\n * remain accessible to any caller the route already feature-gated.\n *\n * Routes also narrow at the SQL layer (the admin channel list returns\n * `user_id IS NULL` rows only; the profile list filters `user_id =\n * currentUser.id`); these helpers are the per-channel authorization backstop a\n * route calls once it has loaded the row.\n */\n\nexport const ADMIN_FEATURE = 'communication_channels.admin'\n\n/**\n * Throws when the caller may not access a specific channel. Returns silently\n * when access is allowed.\n *\n * Personal mailbox privacy (v1: strict owner-only). A per-user channel\n * (`userId` set) may be acted on ONLY by its owner \u2014 not even an admin /\n * superadmin can poll, test-send, import history from, register push on, or\n * delete another user's personal mailbox. Tenant-wide channels\n * (`userId == null`, e.g. WhatsApp Business / Slack workspaces) remain\n * accessible to any caller the route already feature-gated.\n *\n * `userFeatures` is retained on the signature (callers pass it) but no longer\n * grants a bypass; it is reserved for the v2 admin-oversight feature.\n *\n * Callers MUST pass the fully decrypted channel row \u2014 we read `userId` directly.\n */\nexport function assertCanAccessChannel(\n  channel: { userId?: string | null } | null | undefined,\n  currentUserId: string | null | undefined,\n  userFeatures: string[] | null | undefined,\n): void {\n  if (!channel) {\n    // Defensive: callers pre-check existence and return 404, so this is\n    // unreachable in practice. Throw the typed access error (route-mapped to a\n    // masked 404) rather than a bare Error that would surface as a 500.\n    throw new ChannelAccessDeniedError('Channel not found')\n  }\n  void userFeatures\n  // Tenant-wide / shared channel \u2014 accessible to all callers.\n  if (channel.userId == null) return\n  // Personal mailbox \u2014 owner only, regardless of admin grants (v1).\n  if (channel.userId !== currentUserId) {\n    throw new ChannelAccessDeniedError(\n      'Channel is a personal mailbox owned by another user',\n    )\n  }\n}\n\n/**\n * Authorization for MANAGING (mutating) a channel \u2014 disconnect, poll, set\n * primary, import history, register push. Encodes the per-user ownership rule:\n *\n *   - **Personal mailbox** (`userId` set): the **owner has full control** of\n *     their own account; any other caller \u2014 admin included \u2014 is denied (v1\n *     strict owner-only, no bypass). Routes gate these on\n *     `communication_channels.connect_user_channel` so every email user reaches\n *     this check for their own channels.\n *   - **Tenant-wide / shared channel** (`userId == null`, e.g. WhatsApp\n *     Business / Slack workspaces): requires the route's `elevatedFeature`\n *     (`communication_channels.manage`, `\u2026channel.push.manage`, or\n *     `\u2026channel.import_history`). Evaluated by the shared feature policy.\n *\n * Throws `ChannelAccessDeniedError` (route handlers map it to 404, masking\n * existence) when the caller may not manage the channel.\n */\nexport function assertCanManageChannel(\n  channel: { userId?: string | null } | null | undefined,\n  currentUserId: string | null | undefined,\n  userFeatures: string[] | null | undefined,\n  elevatedFeature: string,\n): void {\n  if (!channel) {\n    // Defensive: callers pre-check existence and return 404, so this is\n    // unreachable in practice. Throw the typed access error (route-mapped to a\n    // masked 404) rather than a bare Error that would surface as a 500.\n    throw new ChannelAccessDeniedError('Channel not found')\n  }\n  // Personal mailbox \u2014 owner only. The owner manages their own account fully\n  // (gated by connect_user_channel at the route); no admin bypass in v1.\n  if (channel.userId != null) {\n    if (channel.userId !== currentUserId) {\n      throw new ChannelAccessDeniedError('Channel is a personal mailbox owned by another user')\n    }\n    return\n  }\n  // Tenant-wide / shared channel \u2014 requires the elevated management feature.\n  const grantedFeatures = Array.isArray(userFeatures) ? userFeatures : []\n  if (!authorizeFeatures([elevatedFeature], { grantedFeatures })) {\n    throw new ChannelAccessDeniedError(`Managing a shared channel requires '${elevatedFeature}'`)\n  }\n}\n\n/**\n * Stable error class so route handlers can map to a 403 instead of leaking the\n * underlying message verbatim. Subclasses `Error` for compatibility with the\n * platform's error logging helpers.\n */\nexport class ChannelAccessDeniedError extends Error {\n  override name = 'ChannelAccessDeniedError'\n  readonly statusCode = 403\n}\n"],
-  "mappings": "AAAA,SAAS,yBAAyB;AAiB3B,MAAM,gBAAgB;AAkBtB,SAAS,uBACd,SACA,eACA,cACM;AACN,MAAI,CAAC,SAAS;AAIZ,UAAM,IAAI,yBAAyB,mBAAmB;AAAA,EACxD;AACA,OAAK;AAEL,MAAI,QAAQ,UAAU,KAAM;AAE5B,MAAI,QAAQ,WAAW,eAAe;AACpC,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACF;AAmBO,SAAS,uBACd,SACA,eACA,cACA,iBACM;AACN,MAAI,CAAC,SAAS;AAIZ,UAAM,IAAI,yBAAyB,mBAAmB;AAAA,EACxD;AAGA,MAAI,QAAQ,UAAU,MAAM;AAC1B,QAAI,QAAQ,WAAW,eAAe;AACpC,YAAM,IAAI,yBAAyB,qDAAqD;AAAA,IAC1F;AACA;AAAA,EACF;AAEA,QAAM,kBAAkB,MAAM,QAAQ,YAAY,IAAI,eAAe,CAAC;AACtE,MAAI,CAAC,kBAAkB,CAAC,eAAe,GAAG,EAAE,gBAAgB,CAAC,GAAG;AAC9D,UAAM,IAAI,yBAAyB,uCAAuC,eAAe,GAAG;AAAA,EAC9F;AACF;AAOO,MAAM,iCAAiC,MAAM;AAAA,EAA7C;AAAA;AACL,SAAS,OAAO;AAChB,SAAS,aAAa;AAAA;AACxB;",
+  "sourcesContent": ["import { authorizeFeatures } from '@open-mercato/shared/security/featurePolicy'\n\n/**\n * Per-user channel access control \u2014 service-layer authorization helpers.\n *\n * Personal mailbox privacy (v1: strict owner-only). A per-user channel\n * (`userId` set) may be read or managed ONLY by its owner \u2014 not even an admin\n * or superadmin can act on another user's personal mailbox. Tenant-wide /\n * shared channels (`userId == null`, e.g. WhatsApp Business / Slack workspaces)\n * remain accessible to any caller the route already feature-gated.\n *\n * Routes also narrow at the SQL layer (the admin channel list returns\n * `user_id IS NULL` rows only; the profile list filters `user_id =\n * currentUser.id`); these helpers are the per-channel authorization backstop a\n * route calls once it has loaded the row.\n */\n\nexport const ADMIN_FEATURE = 'communication_channels.admin'\n\n/**\n * Org-scoping fragment for reading/managing channels.\n *\n * Tenant-wide channels are stored with `organization_id IS NULL` (the\n * tenant-scoped push providers FCM/APNs/Expo do this deliberately \u2014 see\n * `connect-credential-channel.ts`). They are visible and manageable from ANY\n * org in the tenant, so a read scoped to the caller's selected org must also\n * match the NULL rows; otherwise a channel connected while an admin had a\n * non-null org would be invisible to every listing/detail query (and vice\n * versa). Org-scoped channels (`organization_id = <org>`) stay scoped to their\n * org.\n *\n * Spread the result into a MikroORM `where` object alongside `tenantId` etc.\n */\nexport function channelOrgScopeWhere(\n  orgId: string | null | undefined,\n): Record<string, unknown> {\n  return orgId\n    ? { $or: [{ organizationId: orgId }, { organizationId: null }] }\n    : { organizationId: null }\n}\n\n/**\n * Same NULL-inclusive org scoping, expressed over a resolved\n * `OrganizationScopeFilter` (`resolveOrganizationScopeFilter`) rather than a\n * single org id.\n *\n * Read routes scope on the caller's *selected* organization (the\n * `om_selected_org` cookie the top-bar switcher writes), not on the org baked\n * into the session token (#5012) \u2014 that resolution yields a list of org ids, or\n * `undefined` when the caller is unrestricted (super-admin viewing all orgs).\n * An unrestricted caller sees every channel in the tenant, so the fragment is\n * empty; a restricted one gets their orgs plus the tenant-wide (`NULL`) rows.\n */\nexport function channelOrgScopeWhereFromFilter(\n  filter: { organizationIds: string[] | undefined } | null | undefined,\n): Record<string, unknown> {\n  const organizationIds = filter?.organizationIds\n  if (!organizationIds || organizationIds.length === 0) return {}\n  return { $or: [{ organizationId: { $in: organizationIds } }, { organizationId: null }] }\n}\n\n/**\n * Throws when the caller may not access a specific channel. Returns silently\n * when access is allowed.\n *\n * Personal mailbox privacy (v1: strict owner-only). A per-user channel\n * (`userId` set) may be acted on ONLY by its owner \u2014 not even an admin /\n * superadmin can poll, test-send, import history from, register push on, or\n * delete another user's personal mailbox. Tenant-wide channels\n * (`userId == null`, e.g. WhatsApp Business / Slack workspaces) remain\n * accessible to any caller the route already feature-gated.\n *\n * `userFeatures` is retained on the signature (callers pass it) but no longer\n * grants a bypass; it is reserved for the v2 admin-oversight feature.\n *\n * Callers MUST pass the fully decrypted channel row \u2014 we read `userId` directly.\n */\nexport function assertCanAccessChannel(\n  channel: { userId?: string | null } | null | undefined,\n  currentUserId: string | null | undefined,\n  userFeatures: string[] | null | undefined,\n): void {\n  if (!channel) {\n    // Defensive: callers pre-check existence and return 404, so this is\n    // unreachable in practice. Throw the typed access error (route-mapped to a\n    // masked 404) rather than a bare Error that would surface as a 500.\n    throw new ChannelAccessDeniedError('Channel not found')\n  }\n  void userFeatures\n  // Tenant-wide / shared channel \u2014 accessible to all callers.\n  if (channel.userId == null) return\n  // Personal mailbox \u2014 owner only, regardless of admin grants (v1).\n  if (channel.userId !== currentUserId) {\n    throw new ChannelAccessDeniedError(\n      'Channel is a personal mailbox owned by another user',\n    )\n  }\n}\n\n/**\n * Authorization for MANAGING (mutating) a channel \u2014 disconnect, poll, set\n * primary, import history, register push. Encodes the per-user ownership rule:\n *\n *   - **Personal mailbox** (`userId` set): the **owner has full control** of\n *     their own account; any other caller \u2014 admin included \u2014 is denied (v1\n *     strict owner-only, no bypass). Routes gate these on\n *     `communication_channels.connect_user_channel` so every email user reaches\n *     this check for their own channels.\n *   - **Tenant-wide / shared channel** (`userId == null`, e.g. WhatsApp\n *     Business / Slack workspaces): requires the route's `elevatedFeature`\n *     (`communication_channels.manage`, `\u2026channel.push.manage`, or\n *     `\u2026channel.import_history`). Evaluated by the shared feature policy.\n *\n * Throws `ChannelAccessDeniedError` (route handlers map it to 404, masking\n * existence) when the caller may not manage the channel.\n */\nexport function assertCanManageChannel(\n  channel: { userId?: string | null } | null | undefined,\n  currentUserId: string | null | undefined,\n  userFeatures: string[] | null | undefined,\n  elevatedFeature: string,\n): void {\n  if (!channel) {\n    // Defensive: callers pre-check existence and return 404, so this is\n    // unreachable in practice. Throw the typed access error (route-mapped to a\n    // masked 404) rather than a bare Error that would surface as a 500.\n    throw new ChannelAccessDeniedError('Channel not found')\n  }\n  // Personal mailbox \u2014 owner only. The owner manages their own account fully\n  // (gated by connect_user_channel at the route); no admin bypass in v1.\n  if (channel.userId != null) {\n    if (channel.userId !== currentUserId) {\n      throw new ChannelAccessDeniedError('Channel is a personal mailbox owned by another user')\n    }\n    return\n  }\n  // Tenant-wide / shared channel \u2014 requires the elevated management feature.\n  const grantedFeatures = Array.isArray(userFeatures) ? userFeatures : []\n  if (!authorizeFeatures([elevatedFeature], { grantedFeatures })) {\n    throw new ChannelAccessDeniedError(`Managing a shared channel requires '${elevatedFeature}'`)\n  }\n}\n\n/**\n * Stable error class so route handlers can map to a 403 instead of leaking the\n * underlying message verbatim. Subclasses `Error` for compatibility with the\n * platform's error logging helpers.\n */\nexport class ChannelAccessDeniedError extends Error {\n  override name = 'ChannelAccessDeniedError'\n  readonly statusCode = 403\n}\n"],
+  "mappings": "AAAA,SAAS,yBAAyB;AAiB3B,MAAM,gBAAgB;AAgBtB,SAAS,qBACd,OACyB;AACzB,SAAO,QACH,EAAE,KAAK,CAAC,EAAE,gBAAgB,MAAM,GAAG,EAAE,gBAAgB,KAAK,CAAC,EAAE,IAC7D,EAAE,gBAAgB,KAAK;AAC7B;AAcO,SAAS,+BACd,QACyB;AACzB,QAAM,kBAAkB,QAAQ;AAChC,MAAI,CAAC,mBAAmB,gBAAgB,WAAW,EAAG,QAAO,CAAC;AAC9D,SAAO,EAAE,KAAK,CAAC,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,GAAG,EAAE,gBAAgB,KAAK,CAAC,EAAE;AACzF;AAkBO,SAAS,uBACd,SACA,eACA,cACM;AACN,MAAI,CAAC,SAAS;AAIZ,UAAM,IAAI,yBAAyB,mBAAmB;AAAA,EACxD;AACA,OAAK;AAEL,MAAI,QAAQ,UAAU,KAAM;AAE5B,MAAI,QAAQ,WAAW,eAAe;AACpC,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACF;AAmBO,SAAS,uBACd,SACA,eACA,cACA,iBACM;AACN,MAAI,CAAC,SAAS;AAIZ,UAAM,IAAI,yBAAyB,mBAAmB;AAAA,EACxD;AAGA,MAAI,QAAQ,UAAU,MAAM;AAC1B,QAAI,QAAQ,WAAW,eAAe;AACpC,YAAM,IAAI,yBAAyB,qDAAqD;AAAA,IAC1F;AACA;AAAA,EACF;AAEA,QAAM,kBAAkB,MAAM,QAAQ,YAAY,IAAI,eAAe,CAAC;AACtE,MAAI,CAAC,kBAAkB,CAAC,eAAe,GAAG,EAAE,gBAAgB,CAAC,GAAG;AAC9D,UAAM,IAAI,yBAAyB,uCAAuC,eAAe,GAAG;AAAA,EAC9F;AACF;AAOO,MAAM,iCAAiC,MAAM;AAAA,EAA7C;AAAA;AACL,SAAS,OAAO;AAChB,SAAS,aAAa;AAAA;AACxB;",
   "names": []
 }

package/dist/modules/communication_channels/lib/connect-channel.js

@@ -13,10 +13,12 @@ class MailboxAlreadyConnectedError extends Error {
 async function createConnectedChannelRow(args) {
   const { em, adapter, providerKey, displayName, externalIdentifier, credentialsRefId, userId, scope } = args;
   const credentialsAvailable = credentialsRefId !== null;
+  const isTenantWidePush = adapter.channelType === "push" && userId === null;
+  const effectiveExternalIdentifier = isTenantWidePush ? null : externalIdentifier;
   const pollIntervalSeconds = args.pollIntervalSeconds !== void 0 ? args.pollIntervalSeconds : adapter.capabilities?.realtimePush === false ? POLLING_ONLY_DEFAULT_INTERVAL_SECONDS : null;
   const dscope = { tenantId: scope.tenantId, organizationId: scope.organizationId ?? null };
-  if (externalIdentifier) {
-    const normalized = externalIdentifier.toLowerCase();
+  if (effectiveExternalIdentifier) {
+    const normalized = effectiveExternalIdentifier.toLowerCase();
     const userChannels = await findWithDecryption(
       em,
       CommunicationChannel,
@@ -28,20 +30,26 @@ async function createConnectedChannelRow(args) {
       (existing) => existing.providerKey !== providerKey && typeof existing.externalIdentifier === "string" && existing.externalIdentifier.toLowerCase() === normalized
     );
     if (conflict) {
-      throw new MailboxAlreadyConnectedError(externalIdentifier, conflict.providerKey);
+      throw new MailboxAlreadyConnectedError(effectiveExternalIdentifier, conflict.providerKey);
     }
   }
-  const naturalKey = {
+  const dedupeFilter = isTenantWidePush ? {
+    tenantId: scope.tenantId,
+    userId: null,
+    providerKey,
+    channelType: "push",
+    deletedAt: null
+  } : effectiveExternalIdentifier ? {
     tenantId: scope.tenantId,
     userId,
     providerKey,
-    externalIdentifier,
+    externalIdentifier: effectiveExternalIdentifier,
     deletedAt: null
-  };
+  } : null;
   const applyConnectionState = (target) => {
     target.channelType = adapter.channelType;
     target.displayName = displayName;
-    target.externalIdentifier = externalIdentifier ?? null;
+    target.externalIdentifier = effectiveExternalIdentifier ?? null;
     target.credentialsRef = credentialsRefId;
     target.capabilities = adapter.capabilities;
     target.isActive = credentialsAvailable;
@@ -49,8 +57,8 @@ async function createConnectedChannelRow(args) {
     target.status = credentialsAvailable ? "connected" : "requires_reauth";
     target.lastError = credentialsAvailable ? null : "credentials_persist_failed";
   };
-  if (externalIdentifier) {
-    const existing = await findOneWithDecryption(em, CommunicationChannel, naturalKey, void 0, dscope);
+  if (dedupeFilter) {
+    const existing = await findOneWithDecryption(em, CommunicationChannel, dedupeFilter, void 0, dscope);
     if (existing) {
       applyConnectionState(existing);
       await em.flush();
@@ -61,7 +69,7 @@ async function createConnectedChannelRow(args) {
     providerKey,
     channelType: adapter.channelType,
     displayName,
-    externalIdentifier: externalIdentifier ?? null,
+    externalIdentifier: effectiveExternalIdentifier ?? null,
     credentialsRef: credentialsRefId,
     capabilities: adapter.capabilities,
     isActive: credentialsAvailable,
@@ -78,9 +86,9 @@ async function createConnectedChannelRow(args) {
     await em.flush();
     return channel;
   } catch (err) {
-    if (!isUniqueViolation(err) || !externalIdentifier) throw err;
+    if (!isUniqueViolation(err) || !dedupeFilter) throw err;
     const reEm = em.fork();
-    const winner = await findOneWithDecryption(reEm, CommunicationChannel, naturalKey, void 0, dscope);
+    const winner = await findOneWithDecryption(reEm, CommunicationChannel, dedupeFilter, void 0, dscope);
     if (!winner) throw err;
     applyConnectionState(winner);
     await reEm.flush();

package/dist/modules/communication_channels/lib/connect-channel.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/modules/communication_channels/lib/connect-channel.ts"],
-  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'\nimport { CommunicationChannel } from '../data/entities'\nimport type { ChannelAdapter } from './adapter'\nimport { isUniqueViolation } from './pg-errors'\n\n/**\n * Default poll cadence (seconds) for a polling-only channel \u2014 one whose adapter\n * declares `realtimePush: false`. Push-capable channels use `null` (push-driven,\n * no fixed poll). Shared so push teardown restores the same cadence connect uses.\n */\nexport const POLLING_ONLY_DEFAULT_INTERVAL_SECONDS = 300\n\n/**\n * Thrown by {@link createConnectedChannelRow} when the same mailbox\n * (`externalIdentifier`) is already connected for this user via a DIFFERENT\n * provider. Both channels would poll the same inbox, and the per-channel\n * `(channel_id, external_message_id)` dedup cannot dedupe the same email across\n * channels \u2014 so every message would be ingested (and threaded) twice.\n */\nexport class MailboxAlreadyConnectedError extends Error {\n  readonly externalIdentifier: string\n  readonly existingProviderKey: string\n  constructor(externalIdentifier: string, existingProviderKey: string) {\n    super(`Mailbox ${externalIdentifier} is already connected via ${existingProviderKey}`)\n    this.name = 'MailboxAlreadyConnectedError'\n    this.externalIdentifier = externalIdentifier\n    this.existingProviderKey = existingProviderKey\n  }\n}\n\nexport interface CreateConnectedChannelRowArgs {\n  em: EntityManager\n  adapter: Pick<ChannelAdapter, 'channelType' | 'capabilities'>\n  providerKey: string\n  displayName: string\n  externalIdentifier: string | null\n  credentialsRefId: string | null\n  userId: string\n  scope: { tenantId: string; organizationId: string | null }\n  /**\n   * Explicit poll-interval override (seconds). When omitted, it is derived from\n   * the adapter's push capability (push-capable \u2192 null, polling-only \u2192 300).\n   */\n  pollIntervalSeconds?: number | null\n}\n\n/**\n * Create + persist the per-user `CommunicationChannel` row for a connect flow.\n * Shared by the credential-connect command and the OAuth callback so both entry\n * points use one channel-shape implementation instead of duplicating `em.create`.\n *\n * When credentials could not be persisted (`credentialsRefId === null`) the row\n * is created in `requires_reauth` + `isActive=false` so workers don't poll a\n * credential-less channel; the user reconnects to recover.\n */\nexport async function createConnectedChannelRow(\n  args: CreateConnectedChannelRowArgs,\n): Promise<CommunicationChannel> {\n  const { em, adapter, providerKey, displayName, externalIdentifier, credentialsRefId, userId, scope } = args\n  const credentialsAvailable = credentialsRefId !== null\n  const pollIntervalSeconds =\n    args.pollIntervalSeconds !== undefined\n      ? args.pollIntervalSeconds\n      : adapter.capabilities?.realtimePush === false\n        ? POLLING_ONLY_DEFAULT_INTERVAL_SECONDS\n        : null\n  const dscope = { tenantId: scope.tenantId, organizationId: scope.organizationId ?? null }\n\n  // Cross-provider duplicate guard: the same mailbox must not be connected via\n  // two providers for one user. Both channels would poll the same inbox, and the\n  // per-channel `(channel_id, external_message_id)` dedup cannot dedupe the same\n  // email across channels \u2014 so every message would be ingested (and threaded)\n  // twice. Reconnecting the SAME provider/mailbox is fine (healed below); this\n  // only blocks a DIFFERENT provider for an already-connected address.\n  if (externalIdentifier) {\n    const normalized = externalIdentifier.toLowerCase()\n    const userChannels = (await findWithDecryption(\n      em,\n      CommunicationChannel,\n      { tenantId: scope.tenantId, userId, deletedAt: null },\n      undefined,\n      dscope,\n    )) as CommunicationChannel[]\n    const conflict = userChannels.find(\n      (existing) =>\n        existing.providerKey !== providerKey &&\n        typeof existing.externalIdentifier === 'string' &&\n        existing.externalIdentifier.toLowerCase() === normalized,\n    )\n    if (conflict) {\n      throw new MailboxAlreadyConnectedError(externalIdentifier, conflict.providerKey)\n    }\n  }\n\n  const naturalKey = {\n    tenantId: scope.tenantId,\n    userId,\n    providerKey,\n    externalIdentifier,\n    deletedAt: null,\n  }\n\n  // Heal-on-reconnect: a channel for the same (tenant, user, provider, mailbox)\n  // already exists when the user re-runs OAuth / reconnects after a\n  // `requires_reauth`. Update it in place rather than inserting a duplicate row \u2014\n  // a duplicate would stay `isActive` and keep polling + re-emitting reauth\n  // banners, and register a second competing push subscription. Only mailboxes\n  // with a known `externalIdentifier` participate (the unique index is partial).\n  const applyConnectionState = (target: CommunicationChannel): void => {\n    target.channelType = adapter.channelType\n    target.displayName = displayName\n    target.externalIdentifier = externalIdentifier ?? null\n    target.credentialsRef = credentialsRefId\n    target.capabilities = adapter.capabilities as unknown as Record<string, unknown>\n    target.isActive = credentialsAvailable\n    target.pollIntervalSeconds = pollIntervalSeconds\n    target.status = credentialsAvailable ? 'connected' : 'requires_reauth'\n    target.lastError = credentialsAvailable ? null : 'credentials_persist_failed'\n  }\n\n  if (externalIdentifier) {\n    const existing = await findOneWithDecryption(em, CommunicationChannel, naturalKey, undefined, dscope)\n    if (existing) {\n      applyConnectionState(existing)\n      await em.flush()\n      return existing\n    }\n  }\n\n  const channel = em.create(CommunicationChannel, {\n    providerKey,\n    channelType: adapter.channelType,\n    displayName,\n    externalIdentifier: externalIdentifier ?? null,\n    credentialsRef: credentialsRefId,\n    capabilities: adapter.capabilities as unknown as Record<string, unknown>,\n    isActive: credentialsAvailable,\n    userId,\n    isPrimary: false,\n    pollIntervalSeconds,\n    status: credentialsAvailable ? 'connected' : 'requires_reauth',\n    lastError: credentialsAvailable ? null : 'credentials_persist_failed',\n    tenantId: scope.tenantId,\n    organizationId: scope.organizationId ?? null,\n  })\n  em.persist(channel)\n  try {\n    await em.flush()\n    return channel\n  } catch (err) {\n    // Concurrent connect for the same mailbox won the race (partial unique index\n    // rejected ours). Re-select the winner on a clean fork and heal it so the\n    // caller still gets a single, connected channel.\n    if (!isUniqueViolation(err) || !externalIdentifier) throw err\n    const reEm = em.fork()\n    const winner = await findOneWithDecryption(reEm, CommunicationChannel, naturalKey, undefined, dscope)\n    if (!winner) throw err\n    applyConnectionState(winner)\n    await reEm.flush()\n    return winner\n  }\n}\n"],
-  "mappings": "AACA,SAAS,uBAAuB,0BAA0B;AAC1D,SAAS,4BAA4B;AAErC,SAAS,yBAAyB;AAO3B,MAAM,wCAAwC;AAS9C,MAAM,qCAAqC,MAAM;AAAA,EAGtD,YAAY,oBAA4B,qBAA6B;AACnE,UAAM,WAAW,kBAAkB,6BAA6B,mBAAmB,EAAE;AACrF,SAAK,OAAO;AACZ,SAAK,qBAAqB;AAC1B,SAAK,sBAAsB;AAAA,EAC7B;AACF;AA2BA,eAAsB,0BACpB,MAC+B;AAC/B,QAAM,EAAE,IAAI,SAAS,aAAa,aAAa,oBAAoB,kBAAkB,QAAQ,MAAM,IAAI;AACvG,QAAM,uBAAuB,qBAAqB;AAClD,QAAM,sBACJ,KAAK,wBAAwB,SACzB,KAAK,sBACL,QAAQ,cAAc,iBAAiB,QACrC,wCACA;AACR,QAAM,SAAS,EAAE,UAAU,MAAM,UAAU,gBAAgB,MAAM,kBAAkB,KAAK;AAQxF,MAAI,oBAAoB;AACtB,UAAM,aAAa,mBAAmB,YAAY;AAClD,UAAM,eAAgB,MAAM;AAAA,MAC1B;AAAA,MACA;AAAA,MACA,EAAE,UAAU,MAAM,UAAU,QAAQ,WAAW,KAAK;AAAA,MACpD;AAAA,MACA;AAAA,IACF;AACA,UAAM,WAAW,aAAa;AAAA,MAC5B,CAAC,aACC,SAAS,gBAAgB,eACzB,OAAO,SAAS,uBAAuB,YACvC,SAAS,mBAAmB,YAAY,MAAM;AAAA,IAClD;AACA,QAAI,UAAU;AACZ,YAAM,IAAI,6BAA6B,oBAAoB,SAAS,WAAW;AAAA,IACjF;AAAA,EACF;AAEA,QAAM,aAAa;AAAA,IACjB,UAAU,MAAM;AAAA,IAChB;AAAA,IACA;AAAA,IACA;AAAA,IACA,WAAW;AAAA,EACb;AAQA,QAAM,uBAAuB,CAAC,WAAuC;AACnE,WAAO,cAAc,QAAQ;AAC7B,WAAO,cAAc;AACrB,WAAO,qBAAqB,sBAAsB;AAClD,WAAO,iBAAiB;AACxB,WAAO,eAAe,QAAQ;AAC9B,WAAO,WAAW;AAClB,WAAO,sBAAsB;AAC7B,WAAO,SAAS,uBAAuB,cAAc;AACrD,WAAO,YAAY,uBAAuB,OAAO;AAAA,EACnD;AAEA,MAAI,oBAAoB;AACtB,UAAM,WAAW,MAAM,sBAAsB,IAAI,sBAAsB,YAAY,QAAW,MAAM;AACpG,QAAI,UAAU;AACZ,2BAAqB,QAAQ;AAC7B,YAAM,GAAG,MAAM;AACf,aAAO;AAAA,IACT;AAAA,EACF;AAEA,QAAM,UAAU,GAAG,OAAO,sBAAsB;AAAA,IAC9C;AAAA,IACA,aAAa,QAAQ;AAAA,IACrB;AAAA,IACA,oBAAoB,sBAAsB;AAAA,IAC1C,gBAAgB;AAAA,IAChB,cAAc,QAAQ;AAAA,IACtB,UAAU;AAAA,IACV;AAAA,IACA,WAAW;AAAA,IACX;AAAA,IACA,QAAQ,uBAAuB,cAAc;AAAA,IAC7C,WAAW,uBAAuB,OAAO;AAAA,IACzC,UAAU,MAAM;AAAA,IAChB,gBAAgB,MAAM,kBAAkB;AAAA,EAC1C,CAAC;AACD,KAAG,QAAQ,OAAO;AAClB,MAAI;AACF,UAAM,GAAG,MAAM;AACf,WAAO;AAAA,EACT,SAAS,KAAK;AAIZ,QAAI,CAAC,kBAAkB,GAAG,KAAK,CAAC,mBAAoB,OAAM;AAC1D,UAAM,OAAO,GAAG,KAAK;AACrB,UAAM,SAAS,MAAM,sBAAsB,MAAM,sBAAsB,YAAY,QAAW,MAAM;AACpG,QAAI,CAAC,OAAQ,OAAM;AACnB,yBAAqB,MAAM;AAC3B,UAAM,KAAK,MAAM;AACjB,WAAO;AAAA,EACT;AACF;",
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'\nimport { CommunicationChannel } from '../data/entities'\nimport type { ChannelAdapter } from './adapter'\nimport { isUniqueViolation } from './pg-errors'\n\n/**\n * Default poll cadence (seconds) for a polling-only channel \u2014 one whose adapter\n * declares `realtimePush: false`. Push-capable channels use `null` (push-driven,\n * no fixed poll). Shared so push teardown restores the same cadence connect uses.\n */\nexport const POLLING_ONLY_DEFAULT_INTERVAL_SECONDS = 300\n\n/**\n * Thrown by {@link createConnectedChannelRow} when the same mailbox\n * (`externalIdentifier`) is already connected for this user via a DIFFERENT\n * provider. Both channels would poll the same inbox, and the per-channel\n * `(channel_id, external_message_id)` dedup cannot dedupe the same email across\n * channels \u2014 so every message would be ingested (and threaded) twice.\n */\nexport class MailboxAlreadyConnectedError extends Error {\n  readonly externalIdentifier: string\n  readonly existingProviderKey: string\n  constructor(externalIdentifier: string, existingProviderKey: string) {\n    super(`Mailbox ${externalIdentifier} is already connected via ${existingProviderKey}`)\n    this.name = 'MailboxAlreadyConnectedError'\n    this.externalIdentifier = externalIdentifier\n    this.existingProviderKey = existingProviderKey\n  }\n}\n\nexport interface CreateConnectedChannelRowArgs {\n  em: EntityManager\n  adapter: Pick<ChannelAdapter, 'channelType' | 'capabilities'>\n  providerKey: string\n  displayName: string\n  externalIdentifier: string | null\n  credentialsRefId: string | null\n  /** Connecting user, or `null` for a tenant-wide channel (push: FCM/APNs/Expo). */\n  userId: string | null\n  scope: { tenantId: string; organizationId: string | null }\n  /**\n   * Explicit poll-interval override (seconds). When omitted, it is derived from\n   * the adapter's push capability (push-capable \u2192 null, polling-only \u2192 300).\n   */\n  pollIntervalSeconds?: number | null\n}\n\n/**\n * Create + persist a `CommunicationChannel` row for a connect flow. `userId` is\n * the connecting user for per-user channels (Gmail/IMAP) or `null` for tenant-wide\n * channels (push: FCM/APNs/Expo). Shared by the credential-connect command and the\n * OAuth callback so both entry points use one channel-shape implementation instead\n * of duplicating `em.create`.\n *\n * When credentials could not be persisted (`credentialsRefId === null`) the row\n * is created in `requires_reauth` + `isActive=false` so workers don't poll a\n * credential-less channel; the user reconnects to recover.\n */\nexport async function createConnectedChannelRow(\n  args: CreateConnectedChannelRowArgs,\n): Promise<CommunicationChannel> {\n  const { em, adapter, providerKey, displayName, externalIdentifier, credentialsRefId, userId, scope } = args\n  const credentialsAvailable = credentialsRefId !== null\n\n  // A tenant-wide push channel (FCM/APNs/Expo, `user_id = NULL`) is a mailbox-less channel keyed on\n  // (tenant, provider, channel_type='push', user_id NULL), enforced by\n  // `communication_channels_tenant_push_provider_uq`. Push credential schemas are `.passthrough()`, so a\n  // stray `email`/`username`/`fromAddress` key can leak through the connect command as an\n  // `externalIdentifier`. Left in place it would send a push reconnect down the mailbox dedup branch\n  // below \u2014 which never matches the existing push row \u2014 so the INSERT hits the tenant-push unique index,\n  // and the mailbox recovery filter can't find the winner \u21D2 an unrecoverable 500. Drop the stray\n  // identifier for tenant-wide push so the guard, the dedup key, and the stored row all stay consistent\n  // with that index.\n  const isTenantWidePush = adapter.channelType === 'push' && userId === null\n  const effectiveExternalIdentifier = isTenantWidePush ? null : externalIdentifier\n  const pollIntervalSeconds =\n    args.pollIntervalSeconds !== undefined\n      ? args.pollIntervalSeconds\n      : adapter.capabilities?.realtimePush === false\n        ? POLLING_ONLY_DEFAULT_INTERVAL_SECONDS\n        : null\n  const dscope = { tenantId: scope.tenantId, organizationId: scope.organizationId ?? null }\n\n  // Cross-provider duplicate guard: the same mailbox must not be connected via\n  // two providers for one user. Both channels would poll the same inbox, and the\n  // per-channel `(channel_id, external_message_id)` dedup cannot dedupe the same\n  // email across channels \u2014 so every message would be ingested (and threaded)\n  // twice. Reconnecting the SAME provider/mailbox is fine (healed below); this\n  // only blocks a DIFFERENT provider for an already-connected address.\n  if (effectiveExternalIdentifier) {\n    const normalized = effectiveExternalIdentifier.toLowerCase()\n    const userChannels = (await findWithDecryption(\n      em,\n      CommunicationChannel,\n      { tenantId: scope.tenantId, userId, deletedAt: null },\n      undefined,\n      dscope,\n    )) as CommunicationChannel[]\n    const conflict = userChannels.find(\n      (existing) =>\n        existing.providerKey !== providerKey &&\n        typeof existing.externalIdentifier === 'string' &&\n        existing.externalIdentifier.toLowerCase() === normalized,\n    )\n    if (conflict) {\n      throw new MailboxAlreadyConnectedError(effectiveExternalIdentifier, conflict.providerKey)\n    }\n  }\n\n  // Heal-on-reconnect dedup key. Two shapes:\n  //  - mailbox channels (Gmail/IMAP): keyed on (tenant, user, provider, mailbox);\n  //    only rows with a known `externalIdentifier` participate.\n  //  - tenant-wide push channels (FCM/APNs/Expo): no mailbox, `user_id = NULL`, so\n  //    keyed on (tenant, provider, channel_type='push', user_id NULL). Without this\n  //    every admin reconnect would insert a duplicate (fan-out takes the oldest per\n  //    provider, so duplicates are silent noise + a concurrent-connect race).\n  // `null` \u21D2 no dedup key (identifier-less non-push channel): always insert.\n  const dedupeFilter = isTenantWidePush\n    ? {\n        tenantId: scope.tenantId,\n        userId: null,\n        providerKey,\n        channelType: 'push',\n        deletedAt: null,\n      }\n    : effectiveExternalIdentifier\n      ? {\n          tenantId: scope.tenantId,\n          userId,\n          providerKey,\n          externalIdentifier: effectiveExternalIdentifier,\n          deletedAt: null,\n        }\n      : null\n\n  // Heal-on-reconnect: a channel for the same dedup key already exists when the\n  // user re-runs OAuth / reconnects after a `requires_reauth`, or an admin\n  // re-submits a tenant push provider's credentials. Update it in place rather\n  // than inserting a duplicate row \u2014 a duplicate would stay `isActive` and keep\n  // polling + re-emitting reauth banners, and register a second competing push\n  // subscription. Backed by the partial unique indexes\n  // `communication_channels_user_provider_external_uq` (mailbox) and\n  // `communication_channels_tenant_push_provider_uq` (tenant push).\n  const applyConnectionState = (target: CommunicationChannel): void => {\n    target.channelType = adapter.channelType\n    target.displayName = displayName\n    target.externalIdentifier = effectiveExternalIdentifier ?? null\n    target.credentialsRef = credentialsRefId\n    target.capabilities = adapter.capabilities as unknown as Record<string, unknown>\n    target.isActive = credentialsAvailable\n    target.pollIntervalSeconds = pollIntervalSeconds\n    target.status = credentialsAvailable ? 'connected' : 'requires_reauth'\n    target.lastError = credentialsAvailable ? null : 'credentials_persist_failed'\n  }\n\n  if (dedupeFilter) {\n    const existing = await findOneWithDecryption(em, CommunicationChannel, dedupeFilter, undefined, dscope)\n    if (existing) {\n      applyConnectionState(existing)\n      await em.flush()\n      return existing\n    }\n  }\n\n  const channel = em.create(CommunicationChannel, {\n    providerKey,\n    channelType: adapter.channelType,\n    displayName,\n    externalIdentifier: effectiveExternalIdentifier ?? null,\n    credentialsRef: credentialsRefId,\n    capabilities: adapter.capabilities as unknown as Record<string, unknown>,\n    isActive: credentialsAvailable,\n    userId,\n    isPrimary: false,\n    pollIntervalSeconds,\n    status: credentialsAvailable ? 'connected' : 'requires_reauth',\n    lastError: credentialsAvailable ? null : 'credentials_persist_failed',\n    tenantId: scope.tenantId,\n    organizationId: scope.organizationId ?? null,\n  })\n  em.persist(channel)\n  try {\n    await em.flush()\n    return channel\n  } catch (err) {\n    // Concurrent connect for the same mailbox won the race (partial unique index\n    // rejected ours). Re-select the winner on a clean fork and heal it so the\n    // caller still gets a single, connected channel.\n    if (!isUniqueViolation(err) || !dedupeFilter) throw err\n    const reEm = em.fork()\n    const winner = await findOneWithDecryption(reEm, CommunicationChannel, dedupeFilter, undefined, dscope)\n    if (!winner) throw err\n    applyConnectionState(winner)\n    await reEm.flush()\n    return winner\n  }\n}\n"],
+  "mappings": "AACA,SAAS,uBAAuB,0BAA0B;AAC1D,SAAS,4BAA4B;AAErC,SAAS,yBAAyB;AAO3B,MAAM,wCAAwC;AAS9C,MAAM,qCAAqC,MAAM;AAAA,EAGtD,YAAY,oBAA4B,qBAA6B;AACnE,UAAM,WAAW,kBAAkB,6BAA6B,mBAAmB,EAAE;AACrF,SAAK,OAAO;AACZ,SAAK,qBAAqB;AAC1B,SAAK,sBAAsB;AAAA,EAC7B;AACF;AA8BA,eAAsB,0BACpB,MAC+B;AAC/B,QAAM,EAAE,IAAI,SAAS,aAAa,aAAa,oBAAoB,kBAAkB,QAAQ,MAAM,IAAI;AACvG,QAAM,uBAAuB,qBAAqB;AAWlD,QAAM,mBAAmB,QAAQ,gBAAgB,UAAU,WAAW;AACtE,QAAM,8BAA8B,mBAAmB,OAAO;AAC9D,QAAM,sBACJ,KAAK,wBAAwB,SACzB,KAAK,sBACL,QAAQ,cAAc,iBAAiB,QACrC,wCACA;AACR,QAAM,SAAS,EAAE,UAAU,MAAM,UAAU,gBAAgB,MAAM,kBAAkB,KAAK;AAQxF,MAAI,6BAA6B;AAC/B,UAAM,aAAa,4BAA4B,YAAY;AAC3D,UAAM,eAAgB,MAAM;AAAA,MAC1B;AAAA,MACA;AAAA,MACA,EAAE,UAAU,MAAM,UAAU,QAAQ,WAAW,KAAK;AAAA,MACpD;AAAA,MACA;AAAA,IACF;AACA,UAAM,WAAW,aAAa;AAAA,MAC5B,CAAC,aACC,SAAS,gBAAgB,eACzB,OAAO,SAAS,uBAAuB,YACvC,SAAS,mBAAmB,YAAY,MAAM;AAAA,IAClD;AACA,QAAI,UAAU;AACZ,YAAM,IAAI,6BAA6B,6BAA6B,SAAS,WAAW;AAAA,IAC1F;AAAA,EACF;AAUA,QAAM,eAAe,mBACjB;AAAA,IACE,UAAU,MAAM;AAAA,IAChB,QAAQ;AAAA,IACR;AAAA,IACA,aAAa;AAAA,IACb,WAAW;AAAA,EACb,IACA,8BACE;AAAA,IACE,UAAU,MAAM;AAAA,IAChB;AAAA,IACA;AAAA,IACA,oBAAoB;AAAA,IACpB,WAAW;AAAA,EACb,IACA;AAUN,QAAM,uBAAuB,CAAC,WAAuC;AACnE,WAAO,cAAc,QAAQ;AAC7B,WAAO,cAAc;AACrB,WAAO,qBAAqB,+BAA+B;AAC3D,WAAO,iBAAiB;AACxB,WAAO,eAAe,QAAQ;AAC9B,WAAO,WAAW;AAClB,WAAO,sBAAsB;AAC7B,WAAO,SAAS,uBAAuB,cAAc;AACrD,WAAO,YAAY,uBAAuB,OAAO;AAAA,EACnD;AAEA,MAAI,cAAc;AAChB,UAAM,WAAW,MAAM,sBAAsB,IAAI,sBAAsB,cAAc,QAAW,MAAM;AACtG,QAAI,UAAU;AACZ,2BAAqB,QAAQ;AAC7B,YAAM,GAAG,MAAM;AACf,aAAO;AAAA,IACT;AAAA,EACF;AAEA,QAAM,UAAU,GAAG,OAAO,sBAAsB;AAAA,IAC9C;AAAA,IACA,aAAa,QAAQ;AAAA,IACrB;AAAA,IACA,oBAAoB,+BAA+B;AAAA,IACnD,gBAAgB;AAAA,IAChB,cAAc,QAAQ;AAAA,IACtB,UAAU;AAAA,IACV;AAAA,IACA,WAAW;AAAA,IACX;AAAA,IACA,QAAQ,uBAAuB,cAAc;AAAA,IAC7C,WAAW,uBAAuB,OAAO;AAAA,IACzC,UAAU,MAAM;AAAA,IAChB,gBAAgB,MAAM,kBAAkB;AAAA,EAC1C,CAAC;AACD,KAAG,QAAQ,OAAO;AAClB,MAAI;AACF,UAAM,GAAG,MAAM;AACf,WAAO;AAAA,EACT,SAAS,KAAK;AAIZ,QAAI,CAAC,kBAAkB,GAAG,KAAK,CAAC,aAAc,OAAM;AACpD,UAAM,OAAO,GAAG,KAAK;AACrB,UAAM,SAAS,MAAM,sBAAsB,MAAM,sBAAsB,cAAc,QAAW,MAAM;AACtG,QAAI,CAAC,OAAQ,OAAM;AACnB,yBAAqB,MAAM;AAC3B,UAAM,KAAK,MAAM;AACjB,WAAO;AAAA,EACT;AACF;",
   "names": []
 }

package/dist/modules/communication_channels/lib/push-adapter.js

@@ -0,0 +1,68 @@
+import { pushChannelCapabilities } from "./push-capabilities.js";
+import { resolvePushCredentialIssue } from "./push-credential-errors.js";
+const DEVICE_UNREGISTERED = "device_unregistered";
+function deviceUnregisteredResult(metadata) {
+  return {
+    externalMessageId: "",
+    status: "failed",
+    error: DEVICE_UNREGISTERED,
+    metadata: { unregistered: true, ...metadata ?? {} }
+  };
+}
+const MISSING_PUSH_TOKEN_RESULT = {
+  externalMessageId: "",
+  status: "failed",
+  error: "missing_push_token"
+};
+function supportsReceiptChecking(adapter) {
+  return typeof adapter?.checkReceipts === "function";
+}
+function readPushToken(input) {
+  const token = typeof input.metadata?.pushToken === "string" ? input.metadata.pushToken : "";
+  return token.length > 0 ? token : null;
+}
+class BasePushChannelAdapter {
+  constructor() {
+    this.channelType = "push";
+    // Push credentials (service account / signing key) serve every device in the
+    // tenant, so a push channel is tenant-wide (user_id = NULL), connected by an
+    // admin — never a per-user channel. Covers fcm/apns/expo + the test stub.
+    this.channelScope = "tenant";
+    this.capabilities = pushChannelCapabilities;
+  }
+  async convertOutbound(input) {
+    return { content: { text: input.body, bodyFormat: input.bodyFormat }, metadata: input.channelMetadata ?? {} };
+  }
+  async verifyWebhook(_input) {
+    return { raw: {}, eventType: "other", metadata: { reason: `${this.providerKey}-no-webhook` } };
+  }
+  async getStatus(_input) {
+    return { status: "sent" };
+  }
+  async normalizeInbound(_raw) {
+    throw new Error(`[internal] ${this.providerKey} push adapter normalizeInbound is not used (push is outbound-only)`);
+  }
+  async validateCredentials(input) {
+    const parsed = this.credentialsSchema.safeParse(input.credentials);
+    if (parsed.success) return { ok: true };
+    const errors = {};
+    const errorCodes = {};
+    for (const issue of parsed.error.issues) {
+      const key = issue.path[0];
+      if (typeof key !== "string" || errors[key]) continue;
+      const resolved = resolvePushCredentialIssue(issue.message);
+      errors[key] = resolved.message;
+      errorCodes[key] = resolved.code;
+    }
+    return { ok: false, errors, errorCodes };
+  }
+}
+export {
+  BasePushChannelAdapter,
+  DEVICE_UNREGISTERED,
+  MISSING_PUSH_TOKEN_RESULT,
+  deviceUnregisteredResult,
+  readPushToken,
+  supportsReceiptChecking
+};
+//# sourceMappingURL=push-adapter.js.map

package/dist/modules/communication_channels/lib/push-adapter.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/communication_channels/lib/push-adapter.ts"],
+  "sourcesContent": ["import type { ZodType } from 'zod'\nimport type {\n  ChannelAdapter,\n  ChannelCapabilities,\n  ChannelNativeContent,\n  ConvertOutboundInput,\n  GetMessageStatusInput,\n  InboundMessage,\n  MessageStatus,\n  NormalizedInboundMessage,\n  SendMessageInput,\n  SendMessageResult,\n  ValidateCredentialsInput,\n  ValidateCredentialsResult,\n  VerifyWebhookInput,\n} from './adapter'\nimport { pushChannelCapabilities } from './push-capabilities'\nimport { resolvePushCredentialIssue } from './push-credential-errors'\n\n/**\n * Uniform sentinel a push adapter returns for a permanently-invalid device token.\n * The `push_notifications` worker checks `error === DEVICE_UNREGISTERED ||\n * metadata.unregistered === true` and soft-deletes the device \u2014 so every push\n * provider (fcm/apns/expo + the test stub) MUST use this exact shape.\n */\nexport const DEVICE_UNREGISTERED = 'device_unregistered'\n\n/** Build the uniform `device_unregistered` result. Extra metadata is merged in. */\nexport function deviceUnregisteredResult(metadata?: Record<string, unknown>): SendMessageResult {\n  return {\n    externalMessageId: '',\n    status: 'failed',\n    error: DEVICE_UNREGISTERED,\n    metadata: { unregistered: true, ...(metadata ?? {}) },\n  }\n}\n\n/** Standard result when a send is attempted without a device token. */\nexport const MISSING_PUSH_TOKEN_RESULT: SendMessageResult = {\n  externalMessageId: '',\n  status: 'failed',\n  error: 'missing_push_token',\n}\n\n/**\n * Outcome of checking one provider delivery receipt for a previously-accepted push.\n * Emitted only for tickets whose receipt is already available (`resolved`); a ticket whose\n * receipt is not yet ready is omitted so the caller retries it on a later sweep.\n */\nexport interface PushReceiptOutcome {\n  /** The provider ticket id returned by the synchronous send (persisted as `externalMessageId`). */\n  ticketId: string\n  /** The receipt reports the device token is permanently invalid \u21D2 soft-delete the device. */\n  unregistered: boolean\n}\n\n/**\n * Optional capability for providers whose \"device unregistered\" signal arrives in an ASYNCHRONOUS\n * receipt phase rather than the synchronous send ticket (Expo). Implemented by the Expo adapter and\n * polled by the push_notifications receipt reaper; FCM/APNs prune synchronously in `sendMessage` and\n * do not implement it. Additive to `ChannelAdapter` \u2014 feature-detected via `supportsReceiptChecking`.\n */\nexport interface PushReceiptChecker {\n  /**\n   * Fetch delivery receipts for previously-accepted push tickets and report which map to a\n   * permanently-unregistered device token. Return an entry ONLY for tickets whose receipt is ready;\n   * omit tickets with no receipt yet so the caller re-checks them later. Reuses the same tenant\n   * credentials as the send path.\n   */\n  checkReceipts(ticketIds: string[], credentials: unknown): Promise<PushReceiptOutcome[]>\n}\n\n/** Feature-detect the optional `PushReceiptChecker` capability on a resolved channel adapter. */\nexport function supportsReceiptChecking(adapter: unknown): adapter is PushReceiptChecker {\n  return typeof (adapter as { checkReceipts?: unknown } | null | undefined)?.checkReceipts === 'function'\n}\n\n/** Extract the per-call push token from `SendMessageInput.metadata`, or null if absent. */\nexport function readPushToken(input: SendMessageInput): string | null {\n  const token = typeof input.metadata?.pushToken === 'string' ? input.metadata.pushToken : ''\n  return token.length > 0 ? token : null\n}\n\n/**\n * Shared base for outbound-only mobile-push `ChannelAdapter`s (fcm/apns/expo and\n * the test `push_stub`). Concrete adapters provide just `providerKey`,\n * `credentialsSchema`, and `sendMessage`; the push capabilities baseline, the\n * no-op inbound surface (push is outbound-only), the passthrough `convertOutbound`,\n * and schema-driven `validateCredentials` are shared so the push family stays\n * consistent. This is push-specific and does NOT change the per-package\n * standalone convention used by the email channel adapters (gmail/imap).\n */\nexport abstract class BasePushChannelAdapter implements ChannelAdapter {\n  abstract readonly providerKey: string\n  readonly channelType = 'push'\n  // Push credentials (service account / signing key) serve every device in the\n  // tenant, so a push channel is tenant-wide (user_id = NULL), connected by an\n  // admin \u2014 never a per-user channel. Covers fcm/apns/expo + the test stub.\n  readonly channelScope = 'tenant' as const\n  readonly capabilities: ChannelCapabilities = pushChannelCapabilities\n\n  /** Zod schema for this provider's tenant-level credentials; drives `validateCredentials`. */\n  protected abstract readonly credentialsSchema: ZodType<unknown>\n\n  abstract sendMessage(input: SendMessageInput): Promise<SendMessageResult>\n\n  async convertOutbound(input: ConvertOutboundInput): Promise<ChannelNativeContent> {\n    return { content: { text: input.body, bodyFormat: input.bodyFormat }, metadata: input.channelMetadata ?? {} }\n  }\n\n  async verifyWebhook(_input: VerifyWebhookInput): Promise<InboundMessage> {\n    return { raw: {}, eventType: 'other', metadata: { reason: `${this.providerKey}-no-webhook` } }\n  }\n\n  async getStatus(_input: GetMessageStatusInput): Promise<MessageStatus> {\n    return { status: 'sent' }\n  }\n\n  async normalizeInbound(_raw: InboundMessage): Promise<NormalizedInboundMessage> {\n    throw new Error(`[internal] ${this.providerKey} push adapter normalizeInbound is not used (push is outbound-only)`)\n  }\n\n  async validateCredentials(input: ValidateCredentialsInput): Promise<ValidateCredentialsResult> {\n    const parsed = this.credentialsSchema.safeParse(input.credentials)\n    if (parsed.success) return { ok: true }\n    const errors: Record<string, string> = {}\n    const errorCodes: Record<string, string> = {}\n    for (const issue of parsed.error.issues) {\n      const key = issue.path[0]\n      if (typeof key !== 'string' || errors[key]) continue\n      // Schemas emit a stable code as the issue message; keep the English prose\n      // for API consumers and hand the code to the UI so it can localize.\n      const resolved = resolvePushCredentialIssue(issue.message)\n      errors[key] = resolved.message\n      errorCodes[key] = resolved.code\n    }\n    return { ok: false, errors, errorCodes }\n  }\n}\n"],
+  "mappings": "AAgBA,SAAS,+BAA+B;AACxC,SAAS,kCAAkC;AAQpC,MAAM,sBAAsB;AAG5B,SAAS,yBAAyB,UAAuD;AAC9F,SAAO;AAAA,IACL,mBAAmB;AAAA,IACnB,QAAQ;AAAA,IACR,OAAO;AAAA,IACP,UAAU,EAAE,cAAc,MAAM,GAAI,YAAY,CAAC,EAAG;AAAA,EACtD;AACF;AAGO,MAAM,4BAA+C;AAAA,EAC1D,mBAAmB;AAAA,EACnB,QAAQ;AAAA,EACR,OAAO;AACT;AA+BO,SAAS,wBAAwB,SAAiD;AACvF,SAAO,OAAQ,SAA4D,kBAAkB;AAC/F;AAGO,SAAS,cAAc,OAAwC;AACpE,QAAM,QAAQ,OAAO,MAAM,UAAU,cAAc,WAAW,MAAM,SAAS,YAAY;AACzF,SAAO,MAAM,SAAS,IAAI,QAAQ;AACpC;AAWO,MAAe,uBAAiD;AAAA,EAAhE;AAEL,SAAS,cAAc;AAIvB;AAAA;AAAA;AAAA,SAAS,eAAe;AACxB,SAAS,eAAoC;AAAA;AAAA,EAO7C,MAAM,gBAAgB,OAA4D;AAChF,WAAO,EAAE,SAAS,EAAE,MAAM,MAAM,MAAM,YAAY,MAAM,WAAW,GAAG,UAAU,MAAM,mBAAmB,CAAC,EAAE;AAAA,EAC9G;AAAA,EAEA,MAAM,cAAc,QAAqD;AACvE,WAAO,EAAE,KAAK,CAAC,GAAG,WAAW,SAAS,UAAU,EAAE,QAAQ,GAAG,KAAK,WAAW,cAAc,EAAE;AAAA,EAC/F;AAAA,EAEA,MAAM,UAAU,QAAuD;AACrE,WAAO,EAAE,QAAQ,OAAO;AAAA,EAC1B;AAAA,EAEA,MAAM,iBAAiB,MAAyD;AAC9E,UAAM,IAAI,MAAM,cAAc,KAAK,WAAW,oEAAoE;AAAA,EACpH;AAAA,EAEA,MAAM,oBAAoB,OAAqE;AAC7F,UAAM,SAAS,KAAK,kBAAkB,UAAU,MAAM,WAAW;AACjE,QAAI,OAAO,QAAS,QAAO,EAAE,IAAI,KAAK;AACtC,UAAM,SAAiC,CAAC;AACxC,UAAM,aAAqC,CAAC;AAC5C,eAAW,SAAS,OAAO,MAAM,QAAQ;AACvC,YAAM,MAAM,MAAM,KAAK,CAAC;AACxB,UAAI,OAAO,QAAQ,YAAY,OAAO,GAAG,EAAG;AAG5C,YAAM,WAAW,2BAA2B,MAAM,OAAO;AACzD,aAAO,GAAG,IAAI,SAAS;AACvB,iBAAW,GAAG,IAAI,SAAS;AAAA,IAC7B;AACA,WAAO,EAAE,IAAI,OAAO,QAAQ,WAAW;AAAA,EACzC;AACF;",
+  "names": []
+}

package/dist/modules/communication_channels/lib/push-capabilities.js

@@ -0,0 +1,31 @@
+const pushChannelCapabilities = {
+  // Core
+  threading: false,
+  richText: false,
+  fileSharing: false,
+  readReceipts: false,
+  deliveryReceipts: false,
+  typingIndicators: false,
+  // Extended
+  reactions: false,
+  multiReactionPerUser: false,
+  editMessage: false,
+  deleteMessage: false,
+  presence: false,
+  richBlocks: false,
+  interactiveComponents: false,
+  inlineImages: false,
+  conversationHistory: false,
+  contactCards: false,
+  locationSharing: false,
+  voiceNotes: false,
+  stickers: false,
+  // Body formats
+  supportedBodyFormats: ["text"],
+  // Push is real-time; no polling.
+  realtimePush: true
+};
+export {
+  pushChannelCapabilities
+};
+//# sourceMappingURL=push-capabilities.js.map

package/dist/modules/communication_channels/lib/push-capabilities.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/communication_channels/lib/push-capabilities.ts"],
+  "sourcesContent": ["import type { ChannelCapabilities } from './adapter'\n\n/**\n * Baseline capability profile shared by every mobile-push channel provider\n * (FCM / APNs / Expo) and the test-only `push_stub` adapter. Mirrors the\n * `baseEmailCapabilities` pattern so the push contract has a single source of\n * truth: push is a fire-and-forget outbound channel with no threading, history,\n * reactions, or rich content, and it is real-time (`realtimePush: true`) so the\n * hub never schedules polling for it.\n *\n * Providers spread this and override only what genuinely differs.\n */\nexport const pushChannelCapabilities: ChannelCapabilities = {\n  // Core\n  threading: false,\n  richText: false,\n  fileSharing: false,\n  readReceipts: false,\n  deliveryReceipts: false,\n  typingIndicators: false,\n\n  // Extended\n  reactions: false,\n  multiReactionPerUser: false,\n  editMessage: false,\n  deleteMessage: false,\n  presence: false,\n  richBlocks: false,\n  interactiveComponents: false,\n  inlineImages: false,\n  conversationHistory: false,\n  contactCards: false,\n  locationSharing: false,\n  voiceNotes: false,\n  stickers: false,\n\n  // Body formats\n  supportedBodyFormats: ['text'],\n\n  // Push is real-time; no polling.\n  realtimePush: true,\n}\n"],
+  "mappings": "AAYO,MAAM,0BAA+C;AAAA;AAAA,EAE1D,WAAW;AAAA,EACX,UAAU;AAAA,EACV,aAAa;AAAA,EACb,cAAc;AAAA,EACd,kBAAkB;AAAA,EAClB,kBAAkB;AAAA;AAAA,EAGlB,WAAW;AAAA,EACX,sBAAsB;AAAA,EACtB,aAAa;AAAA,EACb,eAAe;AAAA,EACf,UAAU;AAAA,EACV,YAAY;AAAA,EACZ,uBAAuB;AAAA,EACvB,cAAc;AAAA,EACd,qBAAqB;AAAA,EACrB,cAAc;AAAA,EACd,iBAAiB;AAAA,EACjB,YAAY;AAAA,EACZ,UAAU;AAAA;AAAA,EAGV,sBAAsB,CAAC,MAAM;AAAA;AAAA,EAG7B,cAAc;AAChB;",
+  "names": []
+}

package/dist/modules/communication_channels/lib/push-connect-error.js

@@ -0,0 +1,20 @@
+function resolvePushConnectErrorMessage(translate, body) {
+  const fallback = translate("communication_channels.push.connect.failed", "Could not connect push provider.");
+  if (!body?.code) return fallback;
+  return translate(`communication_channels.push.connect.errors.${body.code}`, fallback);
+}
+function resolvePushConnectFieldErrors(translate, body) {
+  const fieldErrors = body?.fieldErrors ?? {};
+  const fieldErrorCodes = body?.fieldErrorCodes ?? {};
+  const resolved = {};
+  for (const [field, message] of Object.entries(fieldErrors)) {
+    const code = fieldErrorCodes[field];
+    resolved[field] = code ? translate(`communication_channels.push.connect.errors.fields.${code}`, message) : message;
+  }
+  return resolved;
+}
+export {
+  resolvePushConnectErrorMessage,
+  resolvePushConnectFieldErrors
+};
+//# sourceMappingURL=push-connect-error.js.map

package/dist/modules/communication_channels/lib/push-connect-error.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/communication_channels/lib/push-connect-error.ts"],
+  "sourcesContent": ["export type PushConnectErrorBody = {\n  code?: string | null\n  fieldErrors?: Record<string, string> | null\n  fieldErrorCodes?: Record<string, string> | null\n}\n\nexport type PushConnectTranslate = (key: string, fallback: string) => string\n\n/**\n * Map a push connect route's structured error `code`\n * (`provider_not_tenant_scoped`, `mailbox_already_connected`,\n * `wrong_scope_for_route`, \u2026) to a localized\n * `communication_channels.push.connect.errors.<code>` message, falling back to\n * the generic `push.connect.failed` when the response carries no code or no\n * matching translation exists. The raw English `error` string the route also\n * returns stays reserved for logs/API consumers so the shipped locale files\n * apply on the failure path.\n */\nexport function resolvePushConnectErrorMessage(\n  translate: PushConnectTranslate,\n  body: PushConnectErrorBody | undefined,\n): string {\n  const fallback = translate('communication_channels.push.connect.failed', 'Could not connect push provider.')\n  if (!body?.code) return fallback\n  return translate(`communication_channels.push.connect.errors.${body.code}`, fallback)\n}\n\n/**\n * Localize the per-field credential-validation errors a 422 connect response\n * carries. Each field's `fieldErrorCodes` entry maps to\n * `communication_channels.push.connect.errors.fields.<code>`; when a field has\n * no code (an adapter that predates the code contract) or the locale ships no\n * matching key, the raw English `fieldErrors` string is used so the operator\n * still sees something actionable rather than a blank field.\n *\n * Returns a map ready for a widget's `setFieldErrors`.\n */\nexport function resolvePushConnectFieldErrors(\n  translate: PushConnectTranslate,\n  body: PushConnectErrorBody | undefined,\n): Record<string, string> {\n  const fieldErrors = body?.fieldErrors ?? {}\n  const fieldErrorCodes = body?.fieldErrorCodes ?? {}\n  const resolved: Record<string, string> = {}\n  for (const [field, message] of Object.entries(fieldErrors)) {\n    const code = fieldErrorCodes[field]\n    resolved[field] = code\n      ? translate(`communication_channels.push.connect.errors.fields.${code}`, message)\n      : message\n  }\n  return resolved\n}\n"],
+  "mappings": "AAkBO,SAAS,+BACd,WACA,MACQ;AACR,QAAM,WAAW,UAAU,8CAA8C,kCAAkC;AAC3G,MAAI,CAAC,MAAM,KAAM,QAAO;AACxB,SAAO,UAAU,8CAA8C,KAAK,IAAI,IAAI,QAAQ;AACtF;AAYO,SAAS,8BACd,WACA,MACwB;AACxB,QAAM,cAAc,MAAM,eAAe,CAAC;AAC1C,QAAM,kBAAkB,MAAM,mBAAmB,CAAC;AAClD,QAAM,WAAmC,CAAC;AAC1C,aAAW,CAAC,OAAO,OAAO,KAAK,OAAO,QAAQ,WAAW,GAAG;AAC1D,UAAM,OAAO,gBAAgB,KAAK;AAClC,aAAS,KAAK,IAAI,OACd,UAAU,qDAAqD,IAAI,IAAI,OAAO,IAC9E;AAAA,EACN;AACA,SAAO;AACT;",
+  "names": []
+}

package/dist/modules/communication_channels/lib/push-credential-errors.js

@@ -0,0 +1,41 @@
+const PUSH_CREDENTIAL_ERROR_REQUIRED = "required";
+const PUSH_CREDENTIAL_ERROR_INVALID = "invalid";
+const PUSH_CREDENTIAL_ERROR_INVALID_JSON = "invalid_json";
+const PUSH_CREDENTIAL_ERROR_MISSING_FIELDS = "missing_fields";
+const PUSH_CREDENTIAL_ERROR_INVALID_P8 = "invalid_p8";
+const PUSH_CREDENTIAL_ERROR_INVALID_KEY_ID = "invalid_key_id";
+const PUSH_CREDENTIAL_ERROR_INVALID_TEAM_ID = "invalid_team_id";
+const PUSH_CREDENTIAL_ERROR_INVALID_BUNDLE_ID = "invalid_bundle_id";
+const PUSH_CREDENTIAL_ERROR_MESSAGES = {
+  [PUSH_CREDENTIAL_ERROR_REQUIRED]: "This field is required.",
+  [PUSH_CREDENTIAL_ERROR_INVALID]: "This value is invalid.",
+  [PUSH_CREDENTIAL_ERROR_INVALID_JSON]: "This is not valid JSON. Paste the service account file exactly as Firebase generated it.",
+  [PUSH_CREDENTIAL_ERROR_MISSING_FIELDS]: "The service account JSON is missing required fields (project_id, client_email, private_key).",
+  [PUSH_CREDENTIAL_ERROR_INVALID_P8]: "This is not a readable APNs .p8 signing key. Paste the whole file including the BEGIN and END lines.",
+  [PUSH_CREDENTIAL_ERROR_INVALID_KEY_ID]: "An APNs Key ID is 10 alphanumeric characters.",
+  [PUSH_CREDENTIAL_ERROR_INVALID_TEAM_ID]: "An Apple Team ID is 10 alphanumeric characters.",
+  [PUSH_CREDENTIAL_ERROR_INVALID_BUNDLE_ID]: "A Bundle ID looks like com.example.app."
+};
+function isPushCredentialErrorCode(value) {
+  return Object.prototype.hasOwnProperty.call(PUSH_CREDENTIAL_ERROR_MESSAGES, value);
+}
+function resolvePushCredentialIssue(issueMessage) {
+  if (isPushCredentialErrorCode(issueMessage)) {
+    return { code: issueMessage, message: PUSH_CREDENTIAL_ERROR_MESSAGES[issueMessage] };
+  }
+  return { code: PUSH_CREDENTIAL_ERROR_INVALID, message: issueMessage };
+}
+export {
+  PUSH_CREDENTIAL_ERROR_INVALID,
+  PUSH_CREDENTIAL_ERROR_INVALID_BUNDLE_ID,
+  PUSH_CREDENTIAL_ERROR_INVALID_JSON,
+  PUSH_CREDENTIAL_ERROR_INVALID_KEY_ID,
+  PUSH_CREDENTIAL_ERROR_INVALID_P8,
+  PUSH_CREDENTIAL_ERROR_INVALID_TEAM_ID,
+  PUSH_CREDENTIAL_ERROR_MESSAGES,
+  PUSH_CREDENTIAL_ERROR_MISSING_FIELDS,
+  PUSH_CREDENTIAL_ERROR_REQUIRED,
+  isPushCredentialErrorCode,
+  resolvePushCredentialIssue
+};
+//# sourceMappingURL=push-credential-errors.js.map

package/dist/modules/communication_channels/lib/push-credential-errors.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/communication_channels/lib/push-credential-errors.ts"],
+  "sourcesContent": ["/**\n * Stable field-error codes for push credential validation (fcm/apns/expo).\n *\n * Push credential schemas emit one of these codes as the zod issue `message`\n * instead of prose. {@link BasePushChannelAdapter.validateCredentials} then\n * splits each issue into two channels:\n *\n *   - `errors[field]`     \u2014 English prose from {@link PUSH_CREDENTIAL_ERROR_MESSAGES},\n *                           reserved for logs and API consumers.\n *   - `errorCodes[field]` \u2014 the code, which the connect widgets map to\n *                           `communication_channels.push.connect.errors.fields.<code>`\n *                           so operators see a localized message.\n *\n * This mirrors the route-level split already used by `push-connect-error.ts`.\n * An issue whose message is not a known code degrades to {@link PUSH_CREDENTIAL_ERROR_INVALID}\n * with the raw zod message kept in `errors`, so a schema change can never leak\n * an untranslated internal string into the UI.\n */\n\nexport const PUSH_CREDENTIAL_ERROR_REQUIRED = 'required'\nexport const PUSH_CREDENTIAL_ERROR_INVALID = 'invalid'\nexport const PUSH_CREDENTIAL_ERROR_INVALID_JSON = 'invalid_json'\nexport const PUSH_CREDENTIAL_ERROR_MISSING_FIELDS = 'missing_fields'\nexport const PUSH_CREDENTIAL_ERROR_INVALID_P8 = 'invalid_p8'\nexport const PUSH_CREDENTIAL_ERROR_INVALID_KEY_ID = 'invalid_key_id'\nexport const PUSH_CREDENTIAL_ERROR_INVALID_TEAM_ID = 'invalid_team_id'\nexport const PUSH_CREDENTIAL_ERROR_INVALID_BUNDLE_ID = 'invalid_bundle_id'\n\n/**\n * English prose per code. Kept as the `errors` payload so existing API\n * consumers and log readers still get a human-readable string.\n */\nexport const PUSH_CREDENTIAL_ERROR_MESSAGES: Record<string, string> = {\n  [PUSH_CREDENTIAL_ERROR_REQUIRED]: 'This field is required.',\n  [PUSH_CREDENTIAL_ERROR_INVALID]: 'This value is invalid.',\n  [PUSH_CREDENTIAL_ERROR_INVALID_JSON]: 'This is not valid JSON. Paste the service account file exactly as Firebase generated it.',\n  [PUSH_CREDENTIAL_ERROR_MISSING_FIELDS]: 'The service account JSON is missing required fields (project_id, client_email, private_key).',\n  [PUSH_CREDENTIAL_ERROR_INVALID_P8]: 'This is not a readable APNs .p8 signing key. Paste the whole file including the BEGIN and END lines.',\n  [PUSH_CREDENTIAL_ERROR_INVALID_KEY_ID]: 'An APNs Key ID is 10 alphanumeric characters.',\n  [PUSH_CREDENTIAL_ERROR_INVALID_TEAM_ID]: 'An Apple Team ID is 10 alphanumeric characters.',\n  [PUSH_CREDENTIAL_ERROR_INVALID_BUNDLE_ID]: 'A Bundle ID looks like com.example.app.',\n}\n\nexport function isPushCredentialErrorCode(value: string): boolean {\n  return Object.prototype.hasOwnProperty.call(PUSH_CREDENTIAL_ERROR_MESSAGES, value)\n}\n\n/**\n * Split a zod issue message into `{ code, message }`. Known codes resolve to\n * their English prose; anything else is reported as {@link PUSH_CREDENTIAL_ERROR_INVALID}\n * while preserving the original text for logs.\n */\nexport function resolvePushCredentialIssue(issueMessage: string): { code: string; message: string } {\n  if (isPushCredentialErrorCode(issueMessage)) {\n    return { code: issueMessage, message: PUSH_CREDENTIAL_ERROR_MESSAGES[issueMessage] }\n  }\n  return { code: PUSH_CREDENTIAL_ERROR_INVALID, message: issueMessage }\n}\n"],
+  "mappings": "AAmBO,MAAM,iCAAiC;AACvC,MAAM,gCAAgC;AACtC,MAAM,qCAAqC;AAC3C,MAAM,uCAAuC;AAC7C,MAAM,mCAAmC;AACzC,MAAM,uCAAuC;AAC7C,MAAM,wCAAwC;AAC9C,MAAM,0CAA0C;AAMhD,MAAM,iCAAyD;AAAA,EACpE,CAAC,8BAA8B,GAAG;AAAA,EAClC,CAAC,6BAA6B,GAAG;AAAA,EACjC,CAAC,kCAAkC,GAAG;AAAA,EACtC,CAAC,oCAAoC,GAAG;AAAA,EACxC,CAAC,gCAAgC,GAAG;AAAA,EACpC,CAAC,oCAAoC,GAAG;AAAA,EACxC,CAAC,qCAAqC,GAAG;AAAA,EACzC,CAAC,uCAAuC,GAAG;AAC7C;AAEO,SAAS,0BAA0B,OAAwB;AAChE,SAAO,OAAO,UAAU,eAAe,KAAK,gCAAgC,KAAK;AACnF;AAOO,SAAS,2BAA2B,cAAyD;AAClG,MAAI,0BAA0B,YAAY,GAAG;AAC3C,WAAO,EAAE,MAAM,cAAc,SAAS,+BAA+B,YAAY,EAAE;AAAA,EACrF;AACA,SAAO,EAAE,MAAM,+BAA+B,SAAS,aAAa;AACtE;",
+  "names": []
+}

package/dist/modules/communication_channels/lib/push-envelope.js

@@ -0,0 +1,46 @@
+function toStringRecord(value) {
+  if (!value || typeof value !== "object") return {};
+  const out = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (raw == null) continue;
+    out[key] = typeof raw === "string" ? raw : String(raw);
+  }
+  return out;
+}
+const KNOWN_PUSH_OPTION_KEYS = /* @__PURE__ */ new Set(["sound", "badge", "image", "priority", "channelId", "body"]);
+function toPushOptions(value) {
+  if (!value || typeof value !== "object") return {};
+  const raw = value;
+  const options = {};
+  for (const [key, entry] of Object.entries(raw)) {
+    if (!KNOWN_PUSH_OPTION_KEYS.has(key)) options[key] = entry;
+  }
+  if (typeof raw.sound === "string") options.sound = raw.sound;
+  if (typeof raw.image === "string") options.image = raw.image;
+  if (typeof raw.channelId === "string") options.channelId = raw.channelId;
+  if (typeof raw.body === "string") options.body = raw.body;
+  if (typeof raw.badge === "number" && Number.isFinite(raw.badge)) options.badge = raw.badge;
+  if (raw.priority === "high" || raw.priority === "normal") options.priority = raw.priority;
+  return options;
+}
+function readPushEnvelope(content) {
+  const raw = content?.raw ?? {};
+  const title = typeof raw.title === "string" ? raw.title : "";
+  const body = typeof raw.body === "string" ? raw.body : content?.text ?? "";
+  return {
+    title,
+    body,
+    data: toStringRecord(raw.data),
+    options: toPushOptions(raw.options),
+    silent: raw.silent === true
+  };
+}
+function resolvePushBody(envelope) {
+  const override = envelope.options.body;
+  return typeof override === "string" && override.length > 0 ? override : envelope.body;
+}
+export {
+  readPushEnvelope,
+  resolvePushBody
+};
+//# sourceMappingURL=push-envelope.js.map

package/dist/modules/communication_channels/lib/push-envelope.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/communication_channels/lib/push-envelope.ts"],
+  "sourcesContent": ["import type { MessageContent } from './adapter'\n\n/**\n * Flat, provider-agnostic push customization a caller can attach to a\n * notification (via `Notification.pushOptions`) or a silent push. Each push\n * adapter maps the recognized keys onto its own provider message shape (see\n * {@link readPushOptions}); unknown keys are ignored by the adapters but kept on\n * the envelope so a provider that understands them can still read them.\n */\nexport interface PushOptions {\n  /** Notification sound (provider default when omitted). */\n  sound?: string\n  /** App icon badge count (iOS / supported Android launchers). */\n  badge?: number\n  /** Rich image URL shown in the expanded notification. */\n  image?: string\n  /** Delivery priority. Maps to FCM `android.priority` / `apns-priority` / Expo `priority`. */\n  priority?: 'high' | 'normal'\n  /** Android notification channel id (FCM `android.notification.channel_id` / Expo `channelId`). */\n  channelId?: string\n  /** Overrides the push body text without changing the in-app notification body. */\n  body?: string\n  [key: string]: unknown\n}\n\n/**\n * The push payload the `push_notifications` worker packs into\n * `SendMessageInput.content.raw` before calling a push adapter's `sendMessage`\n * (see `push_notifications/lib/push-delivery.ts`). Each provider adapter\n * (fcm/apns/expo) reads it the same way via {@link readPushEnvelope} so the\n * title/body/data contract stays uniform.\n */\nexport interface PushEnvelope {\n  title: string\n  body: string\n  data: Record<string, string>\n  /** Flat per-provider customization; see {@link PushOptions}. */\n  options: PushOptions\n  /**\n   * When `true`, deliver as a silent / content-available wake-up: no visible\n   * alert (title/body omitted), data-only payload. Adapters branch on this.\n   */\n  silent: boolean\n}\n\nfunction toStringRecord(value: unknown): Record<string, string> {\n  if (!value || typeof value !== 'object') return {}\n  const out: Record<string, string> = {}\n  for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {\n    if (raw == null) continue\n    out[key] = typeof raw === 'string' ? raw : String(raw)\n  }\n  return out\n}\n\nconst KNOWN_PUSH_OPTION_KEYS = new Set(['sound', 'badge', 'image', 'priority', 'channelId', 'body'])\n\n/**\n * Normalize caller-supplied push options. The recognized keys are coerced to their declared types and a\n * malformed value is DROPPED rather than passed through: a bad `priority` (e.g. `'urgent'`) would reach\n * the provider SDK as an invalid enum and fail every delivery retry with a misleading error. Unknown\n * keys are preserved verbatim so a provider that understands them can still read them (see PushOptions).\n */\nfunction toPushOptions(value: unknown): PushOptions {\n  if (!value || typeof value !== 'object') return {}\n  const raw = value as Record<string, unknown>\n  const options: PushOptions = {}\n  for (const [key, entry] of Object.entries(raw)) {\n    if (!KNOWN_PUSH_OPTION_KEYS.has(key)) options[key] = entry\n  }\n  if (typeof raw.sound === 'string') options.sound = raw.sound\n  if (typeof raw.image === 'string') options.image = raw.image\n  if (typeof raw.channelId === 'string') options.channelId = raw.channelId\n  if (typeof raw.body === 'string') options.body = raw.body\n  if (typeof raw.badge === 'number' && Number.isFinite(raw.badge)) options.badge = raw.badge\n  if (raw.priority === 'high' || raw.priority === 'normal') options.priority = raw.priority\n  return options\n}\n\n/** Read the normalized push envelope from a hub `MessageContent`. Defensive against missing fields. */\nexport function readPushEnvelope(content: MessageContent | undefined): PushEnvelope {\n  const raw = (content?.raw ?? {}) as {\n    title?: unknown\n    body?: unknown\n    data?: unknown\n    options?: unknown\n    silent?: unknown\n  }\n  const title = typeof raw.title === 'string' ? raw.title : ''\n  const body = typeof raw.body === 'string' ? raw.body : content?.text ?? ''\n  return {\n    title,\n    body,\n    data: toStringRecord(raw.data),\n    options: toPushOptions(raw.options),\n    silent: raw.silent === true,\n  }\n}\n\n/** The push body text after applying a non-empty `pushOptions.body` override, if present. */\nexport function resolvePushBody(envelope: PushEnvelope): string {\n  const override = envelope.options.body\n  return typeof override === 'string' && override.length > 0 ? override : envelope.body\n}\n"],
+  "mappings": "AA6CA,SAAS,eAAe,OAAwC;AAC9D,MAAI,CAAC,SAAS,OAAO,UAAU,SAAU,QAAO,CAAC;AACjD,QAAM,MAA8B,CAAC;AACrC,aAAW,CAAC,KAAK,GAAG,KAAK,OAAO,QAAQ,KAAgC,GAAG;AACzE,QAAI,OAAO,KAAM;AACjB,QAAI,GAAG,IAAI,OAAO,QAAQ,WAAW,MAAM,OAAO,GAAG;AAAA,EACvD;AACA,SAAO;AACT;AAEA,MAAM,yBAAyB,oBAAI,IAAI,CAAC,SAAS,SAAS,SAAS,YAAY,aAAa,MAAM,CAAC;AAQnG,SAAS,cAAc,OAA6B;AAClD,MAAI,CAAC,SAAS,OAAO,UAAU,SAAU,QAAO,CAAC;AACjD,QAAM,MAAM;AACZ,QAAM,UAAuB,CAAC;AAC9B,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,GAAG,GAAG;AAC9C,QAAI,CAAC,uBAAuB,IAAI,GAAG,EAAG,SAAQ,GAAG,IAAI;AAAA,EACvD;AACA,MAAI,OAAO,IAAI,UAAU,SAAU,SAAQ,QAAQ,IAAI;AACvD,MAAI,OAAO,IAAI,UAAU,SAAU,SAAQ,QAAQ,IAAI;AACvD,MAAI,OAAO,IAAI,cAAc,SAAU,SAAQ,YAAY,IAAI;AAC/D,MAAI,OAAO,IAAI,SAAS,SAAU,SAAQ,OAAO,IAAI;AACrD,MAAI,OAAO,IAAI,UAAU,YAAY,OAAO,SAAS,IAAI,KAAK,EAAG,SAAQ,QAAQ,IAAI;AACrF,MAAI,IAAI,aAAa,UAAU,IAAI,aAAa,SAAU,SAAQ,WAAW,IAAI;AACjF,SAAO;AACT;AAGO,SAAS,iBAAiB,SAAmD;AAClF,QAAM,MAAO,SAAS,OAAO,CAAC;AAO9B,QAAM,QAAQ,OAAO,IAAI,UAAU,WAAW,IAAI,QAAQ;AAC1D,QAAM,OAAO,OAAO,IAAI,SAAS,WAAW,IAAI,OAAO,SAAS,QAAQ;AACxE,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,MAAM,eAAe,IAAI,IAAI;AAAA,IAC7B,SAAS,cAAc,IAAI,OAAO;AAAA,IAClC,QAAQ,IAAI,WAAW;AAAA,EACzB;AACF;AAGO,SAAS,gBAAgB,UAAgC;AAC9D,QAAM,WAAW,SAAS,QAAQ;AAClC,SAAO,OAAO,aAAa,YAAY,SAAS,SAAS,IAAI,WAAW,SAAS;AACnF;",
+  "names": []
+}

package/dist/modules/communication_channels/lib/refcounted-client-cache.js

@@ -0,0 +1,64 @@
+function createRefCountedClientCache(options) {
+  const entries = /* @__PURE__ */ new Map();
+  const scheduleDispose = (entry) => {
+    if (entry.disposed) return;
+    entry.disposed = true;
+    void entry.client.then((client) => options.dispose(client)).catch(() => {
+    });
+  };
+  const releaseEntry = (entry) => {
+    if (entry.refs <= 0) return;
+    entry.refs -= 1;
+    if (entry.refs === 0 && entry.evicted) scheduleDispose(entry);
+  };
+  const enforceMax = () => {
+    while (entries.size > options.max) {
+      const oldest = entries.values().next().value;
+      if (!oldest) break;
+      entries.delete(oldest.key);
+      oldest.evicted = true;
+      if (oldest.refs === 0) scheduleDispose(oldest);
+    }
+  };
+  const obtain = (key, factory) => {
+    const existing = entries.get(key);
+    if (existing) {
+      entries.delete(key);
+      entries.set(key, existing);
+      existing.refs += 1;
+      return existing;
+    }
+    const entry = { key, client: factory(), refs: 1, evicted: false, disposed: false };
+    entries.set(key, entry);
+    entry.client.catch(() => {
+      if (entries.get(key) === entry) entries.delete(key);
+    });
+    enforceMax();
+    return entry;
+  };
+  return {
+    async acquire(key, factory) {
+      const entry = obtain(key, factory);
+      try {
+        const client = await entry.client;
+        let released = false;
+        return {
+          client,
+          release: () => {
+            if (released) return;
+            released = true;
+            releaseEntry(entry);
+          }
+        };
+      } catch (err) {
+        releaseEntry(entry);
+        throw err;
+      }
+    },
+    size: () => entries.size
+  };
+}
+export {
+  createRefCountedClientCache
+};
+//# sourceMappingURL=refcounted-client-cache.js.map

package/dist/modules/communication_channels/lib/refcounted-client-cache.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/communication_channels/lib/refcounted-client-cache.ts"],
+  "sourcesContent": ["/**\n * A bounded, LRU client cache whose disposal is fenced on in-flight use.\n *\n * Push adapters cache one live provider client (a firebase-admin App carrying a\n * background OAuth-refresh timer, or a node-apn Provider holding an HTTP/2 socket)\n * per credential identity, and LRU-evict the least-recently-used one when the cache\n * grows past `max`. The hazard the previous inline caches had: eviction disposed the\n * client (`app.delete()` / `provider.shutdown()`) immediately, even while a concurrent\n * `sendMessage` still held it \u2014 closing the socket mid-stream. Above the cap that is a\n * steady-state error rate, not a rare race.\n *\n * This cache reference-counts every borrow and DEFERS disposal of an evicted client\n * until its last in-flight borrow releases, so a send never loses its client\n * underneath it. A client that is never evicted is never disposed.\n */\nexport type RefCountedClientCacheOptions<TClient> = {\n  /** Maximum number of live clients kept at once; the least-recently-used is evicted past this. */\n  max: number\n  /**\n   * Release the underlying resource. Called at most once per created client, and only after the client\n   * has been evicted AND every borrow of it has been released. Must not throw synchronously.\n   */\n  dispose: (client: TClient) => void | Promise<void>\n}\n\nexport type ClientLease<TClient> = {\n  client: TClient\n  /**\n   * Release this borrow. Idempotent. Once the last borrow of an already-evicted client releases, the\n   * client is disposed. Callers MUST call this exactly once per successful `acquire`, in a `finally`.\n   */\n  release: () => void\n}\n\ntype CacheEntry<TClient> = {\n  key: string\n  client: Promise<TClient>\n  refs: number\n  evicted: boolean\n  disposed: boolean\n}\n\nexport type RefCountedClientCache<TClient> = {\n  /**\n   * Borrow the client for `key`, creating it via `factory` on a miss. On a hit the entry is promoted to\n   * most-recently-used. A rejected factory result is dropped from the cache (never disposed \u2014 nothing was\n   * constructed) so the next borrow re-creates. The returned lease MUST be released by the caller.\n   */\n  acquire: (key: string, factory: () => Promise<TClient>) => Promise<ClientLease<TClient>>\n  /** Number of live (non-evicted) cached entries. Test/introspection only. */\n  size: () => number\n}\n\nexport function createRefCountedClientCache<TClient>(\n  options: RefCountedClientCacheOptions<TClient>,\n): RefCountedClientCache<TClient> {\n  const entries = new Map<string, CacheEntry<TClient>>()\n\n  const scheduleDispose = (entry: CacheEntry<TClient>): void => {\n    if (entry.disposed) return\n    entry.disposed = true\n    void entry.client.then((client) => options.dispose(client)).catch(() => {})\n  }\n\n  const releaseEntry = (entry: CacheEntry<TClient>): void => {\n    if (entry.refs <= 0) return\n    entry.refs -= 1\n    if (entry.refs === 0 && entry.evicted) scheduleDispose(entry)\n  }\n\n  const enforceMax = (): void => {\n    while (entries.size > options.max) {\n      const oldest = entries.values().next().value as CacheEntry<TClient> | undefined\n      if (!oldest) break\n      entries.delete(oldest.key)\n      oldest.evicted = true\n      // Defer disposal while borrows remain; releaseEntry disposes when the last one returns.\n      if (oldest.refs === 0) scheduleDispose(oldest)\n    }\n  }\n\n  const obtain = (key: string, factory: () => Promise<TClient>): CacheEntry<TClient> => {\n    const existing = entries.get(key)\n    if (existing) {\n      // Refresh recency: delete + re-insert moves the key to the newest position.\n      entries.delete(key)\n      entries.set(key, existing)\n      existing.refs += 1\n      return existing\n    }\n    const entry: CacheEntry<TClient> = { key, client: factory(), refs: 1, evicted: false, disposed: false }\n    entries.set(key, entry)\n    // Drop a rejected init (e.g. invalid credentials) so the next borrow re-creates instead of forever\n    // returning the cached rejection. Nothing was constructed, so there is nothing to dispose.\n    entry.client.catch(() => {\n      if (entries.get(key) === entry) entries.delete(key)\n    })\n    enforceMax()\n    return entry\n  }\n\n  return {\n    async acquire(key, factory) {\n      const entry = obtain(key, factory)\n      try {\n        const client = await entry.client\n        let released = false\n        return {\n          client,\n          release: () => {\n            if (released) return\n            released = true\n            releaseEntry(entry)\n          },\n        }\n      } catch (err) {\n        releaseEntry(entry)\n        throw err\n      }\n    },\n    size: () => entries.size,\n  }\n}\n"],
+  "mappings": "AAqDO,SAAS,4BACd,SACgC;AAChC,QAAM,UAAU,oBAAI,IAAiC;AAErD,QAAM,kBAAkB,CAAC,UAAqC;AAC5D,QAAI,MAAM,SAAU;AACpB,UAAM,WAAW;AACjB,SAAK,MAAM,OAAO,KAAK,CAAC,WAAW,QAAQ,QAAQ,MAAM,CAAC,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EAC5E;AAEA,QAAM,eAAe,CAAC,UAAqC;AACzD,QAAI,MAAM,QAAQ,EAAG;AACrB,UAAM,QAAQ;AACd,QAAI,MAAM,SAAS,KAAK,MAAM,QAAS,iBAAgB,KAAK;AAAA,EAC9D;AAEA,QAAM,aAAa,MAAY;AAC7B,WAAO,QAAQ,OAAO,QAAQ,KAAK;AACjC,YAAM,SAAS,QAAQ,OAAO,EAAE,KAAK,EAAE;AACvC,UAAI,CAAC,OAAQ;AACb,cAAQ,OAAO,OAAO,GAAG;AACzB,aAAO,UAAU;AAEjB,UAAI,OAAO,SAAS,EAAG,iBAAgB,MAAM;AAAA,IAC/C;AAAA,EACF;AAEA,QAAM,SAAS,CAAC,KAAa,YAAyD;AACpF,UAAM,WAAW,QAAQ,IAAI,GAAG;AAChC,QAAI,UAAU;AAEZ,cAAQ,OAAO,GAAG;AAClB,cAAQ,IAAI,KAAK,QAAQ;AACzB,eAAS,QAAQ;AACjB,aAAO;AAAA,IACT;AACA,UAAM,QAA6B,EAAE,KAAK,QAAQ,QAAQ,GAAG,MAAM,GAAG,SAAS,OAAO,UAAU,MAAM;AACtG,YAAQ,IAAI,KAAK,KAAK;AAGtB,UAAM,OAAO,MAAM,MAAM;AACvB,UAAI,QAAQ,IAAI,GAAG,MAAM,MAAO,SAAQ,OAAO,GAAG;AAAA,IACpD,CAAC;AACD,eAAW;AACX,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL,MAAM,QAAQ,KAAK,SAAS;AAC1B,YAAM,QAAQ,OAAO,KAAK,OAAO;AACjC,UAAI;AACF,cAAM,SAAS,MAAM,MAAM;AAC3B,YAAI,WAAW;AACf,eAAO;AAAA,UACL;AAAA,UACA,SAAS,MAAM;AACb,gBAAI,SAAU;AACd,uBAAW;AACX,yBAAa,KAAK;AAAA,UACpB;AAAA,QACF;AAAA,MACF,SAAS,KAAK;AACZ,qBAAa,KAAK;AAClB,cAAM;AAAA,MACR;AAAA,IACF;AAAA,IACA,MAAM,MAAM,QAAQ;AAAA,EACtB;AACF;",
+  "names": []
+}

package/dist/modules/communication_channels/migrations/Migration20260703123630_communication_channels.js

@@ -0,0 +1,13 @@
+import { Migration } from "@mikro-orm/migrations";
+class Migration20260703123630_communication_channels extends Migration {
+  up() {
+    this.addSql(`create unique index "communication_channels_tenant_push_provider_uq" on "communication_channels" ("tenant_id", "provider_key") where "channel_type" = 'push' and "user_id" is null and "deleted_at" is null;`);
+  }
+  down() {
+    this.addSql(`drop index if exists "communication_channels_tenant_push_provider_uq";`);
+  }
+}
+export {
+  Migration20260703123630_communication_channels
+};
+//# sourceMappingURL=Migration20260703123630_communication_channels.js.map

package/dist/modules/communication_channels/migrations/Migration20260703123630_communication_channels.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/communication_channels/migrations/Migration20260703123630_communication_channels.ts"],
+  "sourcesContent": ["import { Migration } from '@mikro-orm/migrations';\n\nexport class Migration20260703123630_communication_channels extends Migration {\n\n  override up(): void | Promise<void> {\n    // Enforce one tenant-wide push channel per (tenant, provider). Push providers\n    // (FCM/APNs/Expo) have no external_identifier and user_id IS NULL, so the\n    // mailbox unique index (communication_channels_user_provider_external_uq) does\n    // not cover them. This keeps an admin reconnect healing the single shared row\n    // (createConnectedChannelRow) instead of inserting duplicates the push fan-out\n    // would silently ignore. Only covers user_id IS NULL rows, so existing per-user\n    // channels are unaffected.\n    this.addSql(`create unique index \"communication_channels_tenant_push_provider_uq\" on \"communication_channels\" (\"tenant_id\", \"provider_key\") where \"channel_type\" = 'push' and \"user_id\" is null and \"deleted_at\" is null;`);\n  }\n\n  override down(): void | Promise<void> {\n    this.addSql(`drop index if exists \"communication_channels_tenant_push_provider_uq\";`);\n  }\n\n}\n"],
+  "mappings": "AAAA,SAAS,iBAAiB;AAEnB,MAAM,uDAAuD,UAAU;AAAA,EAEnE,KAA2B;AAQlC,SAAK,OAAO,8MAA8M;AAAA,EAC5N;AAAA,EAES,OAA6B;AACpC,SAAK,OAAO,wEAAwE;AAAA,EACtF;AAEF;",
+  "names": []
+}