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

package/src/modules/communication_channels/i18n/ko.json

@@ -125,6 +125,39 @@
   "communication_channels.profile.tableTitle": "내 채널",
   "communication_channels.profile.title": "내 통신 채널",
   "communication_channels.push.button.reregister": "푸시 다시 등록",
+  "communication_channels.push.connect.blocked": "유효성 검사로 인해 연결이 차단되었습니다",
+  "communication_channels.push.connect.button.apns": "APNs 연결",
+  "communication_channels.push.connect.button.expo": "Expo 연결",
+  "communication_channels.push.connect.button.fcm": "FCM 연결",
+  "communication_channels.push.connect.cancel": "취소",
+  "communication_channels.push.connect.connected": "푸시 제공자가 연결되었습니다.",
+  "communication_channels.push.connect.connecting": "연결하는 중…",
+  "communication_channels.push.connect.description": "이 채널은 테넌트 전체가 공유합니다 — 이 워크스페이스에 속한 모든 사용자의 기기가 이 채널을 통해 푸시를 받습니다.",
+  "communication_channels.push.connect.displayName": "표시 이름",
+  "communication_channels.push.connect.errors.fields.invalid": "값이 올바르지 않습니다.",
+  "communication_channels.push.connect.errors.fields.invalid_bundle_id": "번들 ID는 com.example.app 형식입니다.",
+  "communication_channels.push.connect.errors.fields.invalid_json": "유효한 JSON이 아닙니다. Firebase에서 생성한 서비스 계정 파일을 그대로 붙여넣으세요.",
+  "communication_channels.push.connect.errors.fields.invalid_key_id": "APNs 키 ID는 영숫자 10자입니다.",
+  "communication_channels.push.connect.errors.fields.invalid_p8": "읽을 수 있는 APNs .p8 서명 키가 아닙니다. BEGIN과 END 줄을 포함해 파일 전체를 붙여넣으세요.",
+  "communication_channels.push.connect.errors.fields.invalid_team_id": "Apple 팀 ID는 영숫자 10자입니다.",
+  "communication_channels.push.connect.errors.fields.missing_fields": "서비스 계정 JSON에 필수 항목(project_id, client_email, private_key)이 없습니다.",
+  "communication_channels.push.connect.errors.fields.required": "필수 입력 항목입니다.",
+  "communication_channels.push.connect.errors.mailbox_already_connected": "이 채널은 이미 다른 제공자를 통해 연결되어 있습니다. 다시 연결하기 전에 해당 제공자에서 연결을 해제하세요.",
+  "communication_channels.push.connect.errors.provider_not_tenant_scoped": "이 제공자는 사용자별 채널을 연결합니다. 개인 채널 연결 절차를 이용하세요.",
+  "communication_channels.push.connect.errors.wrong_scope_for_route": "예상치 못한 채널 범위입니다. 다시 시도하거나 지원팀에 문의하세요.",
+  "communication_channels.push.connect.failed": "푸시 제공자를 연결하지 못했습니다.",
+  "communication_channels.push.connect.fields.apns.bundleId": "번들 ID",
+  "communication_channels.push.connect.fields.apns.keyId": "키 ID",
+  "communication_channels.push.connect.fields.apns.p8Key": "APNs .p8 키",
+  "communication_channels.push.connect.fields.apns.production": "프로덕션 환경",
+  "communication_channels.push.connect.fields.apns.teamId": "팀 ID",
+  "communication_channels.push.connect.fields.expo.accessToken": "액세스 토큰 (선택 사항)",
+  "communication_channels.push.connect.fields.fcm.appName": "앱 이름 (선택 사항)",
+  "communication_channels.push.connect.fields.fcm.serviceAccountJson": "서비스 계정 JSON",
+  "communication_channels.push.connect.save": "연결",
+  "communication_channels.push.connect.title.apns": "Apple 푸시 알림 서비스 연결",
+  "communication_channels.push.connect.title.expo": "Expo 푸시 연결",
+  "communication_channels.push.connect.title.fcm": "Firebase 클라우드 메시징 연결",
   "communication_channels.push.flash.registerFailed": "푸시 등록에 실패했습니다",
   "communication_channels.push.status.active": "푸시 활성",
   "communication_channels.push.status.failed": "푸시 실패 — 폴링 사용 중",
@@ -140,5 +173,6 @@
   "communication_channels.status.disconnected": "연결 끊김",
   "communication_channels.status.error": "오류",
   "communication_channels.status.inactive": "비활성",
-  "communication_channels.status.requiresReauth": "재연결 필요"
+  "communication_channels.status.requiresReauth": "재연결 필요",
+  "notifications.categories.communication_channels": "커뮤니케이션"
 }

package/src/modules/communication_channels/i18n/pl.json

@@ -125,6 +125,39 @@
   "communication_channels.profile.tableTitle": "Twoje kanały",
   "communication_channels.profile.title": "Moje kanały komunikacji",
   "communication_channels.push.button.reregister": "Zarejestruj push ponownie",
+  "communication_channels.push.connect.blocked": "Połączenie zablokowane przez walidację",
+  "communication_channels.push.connect.button.apns": "Połącz APNs",
+  "communication_channels.push.connect.button.expo": "Połącz Expo",
+  "communication_channels.push.connect.button.fcm": "Połącz FCM",
+  "communication_channels.push.connect.cancel": "Anuluj",
+  "communication_channels.push.connect.connected": "Dostawca push połączony.",
+  "communication_channels.push.connect.connecting": "Łączenie…",
+  "communication_channels.push.connect.description": "To współdzielony kanał dla całego tenanta — obsługuje urządzenia wszystkich użytkowników w tej przestrzeni.",
+  "communication_channels.push.connect.displayName": "Nazwa wyświetlana",
+  "communication_channels.push.connect.errors.fields.invalid": "Ta wartość jest nieprawidłowa.",
+  "communication_channels.push.connect.errors.fields.invalid_bundle_id": "Identyfikator pakietu wygląda tak: com.example.app.",
+  "communication_channels.push.connect.errors.fields.invalid_json": "To nie jest prawidłowy JSON. Wklej plik konta serwisowego dokładnie tak, jak wygenerował go Firebase.",
+  "communication_channels.push.connect.errors.fields.invalid_key_id": "Identyfikator klucza APNs składa się z 10 znaków alfanumerycznych.",
+  "communication_channels.push.connect.errors.fields.invalid_p8": "To nie jest czytelny klucz podpisujący APNs .p8. Wklej cały plik razem z liniami BEGIN i END.",
+  "communication_channels.push.connect.errors.fields.invalid_team_id": "Identyfikator zespołu Apple składa się z 10 znaków alfanumerycznych.",
+  "communication_channels.push.connect.errors.fields.missing_fields": "W pliku JSON konta serwisowego brakuje wymaganych pól (project_id, client_email, private_key).",
+  "communication_channels.push.connect.errors.fields.required": "To pole jest wymagane.",
+  "communication_channels.push.connect.errors.mailbox_already_connected": "Ten kanał jest już połączony przez innego dostawcę. Rozłącz go tam przed ponownym połączeniem.",
+  "communication_channels.push.connect.errors.provider_not_tenant_scoped": "Ten dostawca łączy kanały indywidualne; użyj zamiast tego procesu łączenia kanału osobistego.",
+  "communication_channels.push.connect.errors.wrong_scope_for_route": "Nieoczekiwany zakres kanału. Spróbuj ponownie lub skontaktuj się z pomocą techniczną.",
+  "communication_channels.push.connect.failed": "Nie udało się połączyć dostawcy push.",
+  "communication_channels.push.connect.fields.apns.bundleId": "Bundle ID",
+  "communication_channels.push.connect.fields.apns.keyId": "Key ID",
+  "communication_channels.push.connect.fields.apns.p8Key": "Klucz .p8 APNs",
+  "communication_channels.push.connect.fields.apns.production": "Środowisko produkcyjne",
+  "communication_channels.push.connect.fields.apns.teamId": "Team ID",
+  "communication_channels.push.connect.fields.expo.accessToken": "Token dostępu (opcjonalnie)",
+  "communication_channels.push.connect.fields.fcm.appName": "Nazwa aplikacji (opcjonalnie)",
+  "communication_channels.push.connect.fields.fcm.serviceAccountJson": "JSON konta usługi",
+  "communication_channels.push.connect.save": "Połącz",
+  "communication_channels.push.connect.title.apns": "Połącz Apple Push Notification service",
+  "communication_channels.push.connect.title.expo": "Połącz Expo Push",
+  "communication_channels.push.connect.title.fcm": "Połącz Firebase Cloud Messaging",
   "communication_channels.push.flash.registerFailed": "Nie udało się zarejestrować push",
   "communication_channels.push.status.active": "Push aktywny",
   "communication_channels.push.status.failed": "Push nieudany — używam odpytywania",
@@ -140,5 +173,6 @@
   "communication_channels.status.disconnected": "Rozłączony",
   "communication_channels.status.error": "Błąd",
   "communication_channels.status.inactive": "Nieaktywny",
-  "communication_channels.status.requiresReauth": "Wymaga ponownego połączenia"
+  "communication_channels.status.requiresReauth": "Wymaga ponownego połączenia",
+  "notifications.categories.communication_channels": "Komunikacja"
 }

package/src/modules/communication_channels/lib/access-control.ts

@@ -17,6 +17,48 @@ import { authorizeFeatures } from '@open-mercato/shared/security/featurePolicy'
 
 export const ADMIN_FEATURE = 'communication_channels.admin'
 
+/**
+ * Org-scoping fragment for reading/managing channels.
+ *
+ * Tenant-wide channels are stored with `organization_id IS NULL` (the
+ * tenant-scoped push providers FCM/APNs/Expo do this deliberately — see
+ * `connect-credential-channel.ts`). They are visible and manageable from ANY
+ * org in the tenant, so a read scoped to the caller's selected org must also
+ * match the NULL rows; otherwise a channel connected while an admin had a
+ * non-null org would be invisible to every listing/detail query (and vice
+ * versa). Org-scoped channels (`organization_id = <org>`) stay scoped to their
+ * org.
+ *
+ * Spread the result into a MikroORM `where` object alongside `tenantId` etc.
+ */
+export function channelOrgScopeWhere(
+  orgId: string | null | undefined,
+): Record<string, unknown> {
+  return orgId
+    ? { $or: [{ organizationId: orgId }, { organizationId: null }] }
+    : { organizationId: null }
+}
+
+/**
+ * Same NULL-inclusive org scoping, expressed over a resolved
+ * `OrganizationScopeFilter` (`resolveOrganizationScopeFilter`) rather than a
+ * single org id.
+ *
+ * Read routes scope on the caller's *selected* organization (the
+ * `om_selected_org` cookie the top-bar switcher writes), not on the org baked
+ * into the session token (#5012) — that resolution yields a list of org ids, or
+ * `undefined` when the caller is unrestricted (super-admin viewing all orgs).
+ * An unrestricted caller sees every channel in the tenant, so the fragment is
+ * empty; a restricted one gets their orgs plus the tenant-wide (`NULL`) rows.
+ */
+export function channelOrgScopeWhereFromFilter(
+  filter: { organizationIds: string[] | undefined } | null | undefined,
+): Record<string, unknown> {
+  const organizationIds = filter?.organizationIds
+  if (!organizationIds || organizationIds.length === 0) return {}
+  return { $or: [{ organizationId: { $in: organizationIds } }, { organizationId: null }] }
+}
+
 /**
  * Throws when the caller may not access a specific channel. Returns silently
  * when access is allowed.

package/src/modules/communication_channels/lib/adapter.ts

@@ -486,6 +486,14 @@ export interface ValidateCredentialsResult {
   ok: boolean
   /** Field-level error messages keyed by credential field name; for `createCrudFormError`. */
   errors?: Record<string, string>
+  /**
+   * Stable machine-readable code per failing field, keyed the same way as
+   * `errors`. Lets a UI render a localized message instead of the English
+   * prose in `errors` (which stays reserved for logs and API consumers), the
+   * same split the route-level `code` field already uses. Optional: adapters
+   * that don't emit codes keep working and callers fall back to `errors`.
+   */
+  errorCodes?: Record<string, string>
 }
 
 // ── The adapter contract ─────────────────────────────────────
@@ -494,6 +502,23 @@ export interface ChannelAdapter {
   readonly providerKey: string
   readonly channelType: 'whatsapp' | 'slack' | 'email' | 'sms' | string
 
+  /**
+   * Scope of a connected channel for this provider. Governs whether the connect
+   * flow stamps `CommunicationChannel.user_id` with the connecting user or leaves
+   * it NULL (tenant-wide):
+   *
+   * - `'user'` (default when absent) — one channel per user (Gmail, IMAP). The
+   *   credential belongs to the connecting user.
+   * - `'tenant'` — one shared channel per tenant (`user_id = NULL`), connected by
+   *   an admin. Used by push providers (FCM/APNs/Expo) whose service account /
+   *   signing key serves every device in the tenant. Reading (fan-out/delivery)
+   *   is already scope-agnostic; this only affects the connect/write path.
+   *
+   * ADDITIVE-ONLY (BACKWARD_COMPATIBILITY.md): existing adapters that omit it keep
+   * their per-user behaviour unchanged.
+   */
+  readonly channelScope?: 'tenant' | 'user'
+
   /** Declare supported features */
   readonly capabilities: ChannelCapabilities
 

package/src/modules/communication_channels/lib/connect-channel.ts

@@ -36,7 +36,8 @@ export interface CreateConnectedChannelRowArgs {
   displayName: string
   externalIdentifier: string | null
   credentialsRefId: string | null
-  userId: string
+  /** Connecting user, or `null` for a tenant-wide channel (push: FCM/APNs/Expo). */
+  userId: string | null
   scope: { tenantId: string; organizationId: string | null }
   /**
    * Explicit poll-interval override (seconds). When omitted, it is derived from
@@ -46,9 +47,11 @@ export interface CreateConnectedChannelRowArgs {
 }
 
 /**
- * Create + persist the per-user `CommunicationChannel` row for a connect flow.
- * Shared by the credential-connect command and the OAuth callback so both entry
- * points use one channel-shape implementation instead of duplicating `em.create`.
+ * Create + persist a `CommunicationChannel` row for a connect flow. `userId` is
+ * the connecting user for per-user channels (Gmail/IMAP) or `null` for tenant-wide
+ * channels (push: FCM/APNs/Expo). Shared by the credential-connect command and the
+ * OAuth callback so both entry points use one channel-shape implementation instead
+ * of duplicating `em.create`.
  *
  * When credentials could not be persisted (`credentialsRefId === null`) the row
  * is created in `requires_reauth` + `isActive=false` so workers don't poll a
@@ -59,6 +62,18 @@ export async function createConnectedChannelRow(
 ): Promise<CommunicationChannel> {
   const { em, adapter, providerKey, displayName, externalIdentifier, credentialsRefId, userId, scope } = args
   const credentialsAvailable = credentialsRefId !== null
+
+  // A tenant-wide push channel (FCM/APNs/Expo, `user_id = NULL`) is a mailbox-less channel keyed on
+  // (tenant, provider, channel_type='push', user_id NULL), enforced by
+  // `communication_channels_tenant_push_provider_uq`. Push credential schemas are `.passthrough()`, so a
+  // stray `email`/`username`/`fromAddress` key can leak through the connect command as an
+  // `externalIdentifier`. Left in place it would send a push reconnect down the mailbox dedup branch
+  // below — which never matches the existing push row — so the INSERT hits the tenant-push unique index,
+  // and the mailbox recovery filter can't find the winner ⇒ an unrecoverable 500. Drop the stray
+  // identifier for tenant-wide push so the guard, the dedup key, and the stored row all stay consistent
+  // with that index.
+  const isTenantWidePush = adapter.channelType === 'push' && userId === null
+  const effectiveExternalIdentifier = isTenantWidePush ? null : externalIdentifier
   const pollIntervalSeconds =
     args.pollIntervalSeconds !== undefined
       ? args.pollIntervalSeconds
@@ -73,8 +88,8 @@ export async function createConnectedChannelRow(
   // email across channels — so every message would be ingested (and threaded)
   // twice. Reconnecting the SAME provider/mailbox is fine (healed below); this
   // only blocks a DIFFERENT provider for an already-connected address.
-  if (externalIdentifier) {
-    const normalized = externalIdentifier.toLowerCase()
+  if (effectiveExternalIdentifier) {
+    const normalized = effectiveExternalIdentifier.toLowerCase()
     const userChannels = (await findWithDecryption(
       em,
       CommunicationChannel,
@@ -89,28 +104,48 @@ export async function createConnectedChannelRow(
         existing.externalIdentifier.toLowerCase() === normalized,
     )
     if (conflict) {
-      throw new MailboxAlreadyConnectedError(externalIdentifier, conflict.providerKey)
+      throw new MailboxAlreadyConnectedError(effectiveExternalIdentifier, conflict.providerKey)
     }
   }
 
-  const naturalKey = {
-    tenantId: scope.tenantId,
-    userId,
-    providerKey,
-    externalIdentifier,
-    deletedAt: null,
-  }
+  // Heal-on-reconnect dedup key. Two shapes:
+  //  - mailbox channels (Gmail/IMAP): keyed on (tenant, user, provider, mailbox);
+  //    only rows with a known `externalIdentifier` participate.
+  //  - tenant-wide push channels (FCM/APNs/Expo): no mailbox, `user_id = NULL`, so
+  //    keyed on (tenant, provider, channel_type='push', user_id NULL). Without this
+  //    every admin reconnect would insert a duplicate (fan-out takes the oldest per
+  //    provider, so duplicates are silent noise + a concurrent-connect race).
+  // `null` ⇒ no dedup key (identifier-less non-push channel): always insert.
+  const dedupeFilter = isTenantWidePush
+    ? {
+        tenantId: scope.tenantId,
+        userId: null,
+        providerKey,
+        channelType: 'push',
+        deletedAt: null,
+      }
+    : effectiveExternalIdentifier
+      ? {
+          tenantId: scope.tenantId,
+          userId,
+          providerKey,
+          externalIdentifier: effectiveExternalIdentifier,
+          deletedAt: null,
+        }
+      : null
 
-  // Heal-on-reconnect: a channel for the same (tenant, user, provider, mailbox)
-  // already exists when the user re-runs OAuth / reconnects after a
-  // `requires_reauth`. Update it in place rather than inserting a duplicate row —
-  // a duplicate would stay `isActive` and keep polling + re-emitting reauth
-  // banners, and register a second competing push subscription. Only mailboxes
-  // with a known `externalIdentifier` participate (the unique index is partial).
+  // Heal-on-reconnect: a channel for the same dedup key already exists when the
+  // user re-runs OAuth / reconnects after a `requires_reauth`, or an admin
+  // re-submits a tenant push provider's credentials. Update it in place rather
+  // than inserting a duplicate row — a duplicate would stay `isActive` and keep
+  // polling + re-emitting reauth banners, and register a second competing push
+  // subscription. Backed by the partial unique indexes
+  // `communication_channels_user_provider_external_uq` (mailbox) and
+  // `communication_channels_tenant_push_provider_uq` (tenant push).
   const applyConnectionState = (target: CommunicationChannel): void => {
     target.channelType = adapter.channelType
     target.displayName = displayName
-    target.externalIdentifier = externalIdentifier ?? null
+    target.externalIdentifier = effectiveExternalIdentifier ?? null
     target.credentialsRef = credentialsRefId
     target.capabilities = adapter.capabilities as unknown as Record<string, unknown>
     target.isActive = credentialsAvailable
@@ -119,8 +154,8 @@ export async function createConnectedChannelRow(
     target.lastError = credentialsAvailable ? null : 'credentials_persist_failed'
   }
 
-  if (externalIdentifier) {
-    const existing = await findOneWithDecryption(em, CommunicationChannel, naturalKey, undefined, dscope)
+  if (dedupeFilter) {
+    const existing = await findOneWithDecryption(em, CommunicationChannel, dedupeFilter, undefined, dscope)
     if (existing) {
       applyConnectionState(existing)
       await em.flush()
@@ -132,7 +167,7 @@ export async function createConnectedChannelRow(
     providerKey,
     channelType: adapter.channelType,
     displayName,
-    externalIdentifier: externalIdentifier ?? null,
+    externalIdentifier: effectiveExternalIdentifier ?? null,
     credentialsRef: credentialsRefId,
     capabilities: adapter.capabilities as unknown as Record<string, unknown>,
     isActive: credentialsAvailable,
@@ -152,9 +187,9 @@ export async function createConnectedChannelRow(
     // Concurrent connect for the same mailbox won the race (partial unique index
     // rejected ours). Re-select the winner on a clean fork and heal it so the
     // caller still gets a single, connected channel.
-    if (!isUniqueViolation(err) || !externalIdentifier) throw err
+    if (!isUniqueViolation(err) || !dedupeFilter) throw err
     const reEm = em.fork()
-    const winner = await findOneWithDecryption(reEm, CommunicationChannel, naturalKey, undefined, dscope)
+    const winner = await findOneWithDecryption(reEm, CommunicationChannel, dedupeFilter, undefined, dscope)
     if (!winner) throw err
     applyConnectionState(winner)
     await reEm.flush()

package/src/modules/communication_channels/lib/push-adapter.ts

@@ -0,0 +1,139 @@
+import type { ZodType } from 'zod'
+import type {
+  ChannelAdapter,
+  ChannelCapabilities,
+  ChannelNativeContent,
+  ConvertOutboundInput,
+  GetMessageStatusInput,
+  InboundMessage,
+  MessageStatus,
+  NormalizedInboundMessage,
+  SendMessageInput,
+  SendMessageResult,
+  ValidateCredentialsInput,
+  ValidateCredentialsResult,
+  VerifyWebhookInput,
+} from './adapter'
+import { pushChannelCapabilities } from './push-capabilities'
+import { resolvePushCredentialIssue } from './push-credential-errors'
+
+/**
+ * Uniform sentinel a push adapter returns for a permanently-invalid device token.
+ * The `push_notifications` worker checks `error === DEVICE_UNREGISTERED ||
+ * metadata.unregistered === true` and soft-deletes the device — so every push
+ * provider (fcm/apns/expo + the test stub) MUST use this exact shape.
+ */
+export const DEVICE_UNREGISTERED = 'device_unregistered'
+
+/** Build the uniform `device_unregistered` result. Extra metadata is merged in. */
+export function deviceUnregisteredResult(metadata?: Record<string, unknown>): SendMessageResult {
+  return {
+    externalMessageId: '',
+    status: 'failed',
+    error: DEVICE_UNREGISTERED,
+    metadata: { unregistered: true, ...(metadata ?? {}) },
+  }
+}
+
+/** Standard result when a send is attempted without a device token. */
+export const MISSING_PUSH_TOKEN_RESULT: SendMessageResult = {
+  externalMessageId: '',
+  status: 'failed',
+  error: 'missing_push_token',
+}
+
+/**
+ * Outcome of checking one provider delivery receipt for a previously-accepted push.
+ * Emitted only for tickets whose receipt is already available (`resolved`); a ticket whose
+ * receipt is not yet ready is omitted so the caller retries it on a later sweep.
+ */
+export interface PushReceiptOutcome {
+  /** The provider ticket id returned by the synchronous send (persisted as `externalMessageId`). */
+  ticketId: string
+  /** The receipt reports the device token is permanently invalid ⇒ soft-delete the device. */
+  unregistered: boolean
+}
+
+/**
+ * Optional capability for providers whose "device unregistered" signal arrives in an ASYNCHRONOUS
+ * receipt phase rather than the synchronous send ticket (Expo). Implemented by the Expo adapter and
+ * polled by the push_notifications receipt reaper; FCM/APNs prune synchronously in `sendMessage` and
+ * do not implement it. Additive to `ChannelAdapter` — feature-detected via `supportsReceiptChecking`.
+ */
+export interface PushReceiptChecker {
+  /**
+   * Fetch delivery receipts for previously-accepted push tickets and report which map to a
+   * permanently-unregistered device token. Return an entry ONLY for tickets whose receipt is ready;
+   * omit tickets with no receipt yet so the caller re-checks them later. Reuses the same tenant
+   * credentials as the send path.
+   */
+  checkReceipts(ticketIds: string[], credentials: unknown): Promise<PushReceiptOutcome[]>
+}
+
+/** Feature-detect the optional `PushReceiptChecker` capability on a resolved channel adapter. */
+export function supportsReceiptChecking(adapter: unknown): adapter is PushReceiptChecker {
+  return typeof (adapter as { checkReceipts?: unknown } | null | undefined)?.checkReceipts === 'function'
+}
+
+/** Extract the per-call push token from `SendMessageInput.metadata`, or null if absent. */
+export function readPushToken(input: SendMessageInput): string | null {
+  const token = typeof input.metadata?.pushToken === 'string' ? input.metadata.pushToken : ''
+  return token.length > 0 ? token : null
+}
+
+/**
+ * Shared base for outbound-only mobile-push `ChannelAdapter`s (fcm/apns/expo and
+ * the test `push_stub`). Concrete adapters provide just `providerKey`,
+ * `credentialsSchema`, and `sendMessage`; the push capabilities baseline, the
+ * no-op inbound surface (push is outbound-only), the passthrough `convertOutbound`,
+ * and schema-driven `validateCredentials` are shared so the push family stays
+ * consistent. This is push-specific and does NOT change the per-package
+ * standalone convention used by the email channel adapters (gmail/imap).
+ */
+export abstract class BasePushChannelAdapter implements ChannelAdapter {
+  abstract readonly providerKey: string
+  readonly 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.
+  readonly channelScope = 'tenant' as const
+  readonly capabilities: ChannelCapabilities = pushChannelCapabilities
+
+  /** Zod schema for this provider's tenant-level credentials; drives `validateCredentials`. */
+  protected abstract readonly credentialsSchema: ZodType<unknown>
+
+  abstract sendMessage(input: SendMessageInput): Promise<SendMessageResult>
+
+  async convertOutbound(input: ConvertOutboundInput): Promise<ChannelNativeContent> {
+    return { content: { text: input.body, bodyFormat: input.bodyFormat }, metadata: input.channelMetadata ?? {} }
+  }
+
+  async verifyWebhook(_input: VerifyWebhookInput): Promise<InboundMessage> {
+    return { raw: {}, eventType: 'other', metadata: { reason: `${this.providerKey}-no-webhook` } }
+  }
+
+  async getStatus(_input: GetMessageStatusInput): Promise<MessageStatus> {
+    return { status: 'sent' }
+  }
+
+  async normalizeInbound(_raw: InboundMessage): Promise<NormalizedInboundMessage> {
+    throw new Error(`[internal] ${this.providerKey} push adapter normalizeInbound is not used (push is outbound-only)`)
+  }
+
+  async validateCredentials(input: ValidateCredentialsInput): Promise<ValidateCredentialsResult> {
+    const parsed = this.credentialsSchema.safeParse(input.credentials)
+    if (parsed.success) return { ok: true }
+    const errors: Record<string, string> = {}
+    const errorCodes: Record<string, string> = {}
+    for (const issue of parsed.error.issues) {
+      const key = issue.path[0]
+      if (typeof key !== 'string' || errors[key]) continue
+      // Schemas emit a stable code as the issue message; keep the English prose
+      // for API consumers and hand the code to the UI so it can localize.
+      const resolved = resolvePushCredentialIssue(issue.message)
+      errors[key] = resolved.message
+      errorCodes[key] = resolved.code
+    }
+    return { ok: false, errors, errorCodes }
+  }
+}

package/src/modules/communication_channels/lib/push-capabilities.ts

@@ -0,0 +1,42 @@
+import type { ChannelCapabilities } from './adapter'
+
+/**
+ * Baseline capability profile shared by every mobile-push channel provider
+ * (FCM / APNs / Expo) and the test-only `push_stub` adapter. Mirrors the
+ * `baseEmailCapabilities` pattern so the push contract has a single source of
+ * truth: push is a fire-and-forget outbound channel with no threading, history,
+ * reactions, or rich content, and it is real-time (`realtimePush: true`) so the
+ * hub never schedules polling for it.
+ *
+ * Providers spread this and override only what genuinely differs.
+ */
+export const pushChannelCapabilities: ChannelCapabilities = {
+  // 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,
+}

package/src/modules/communication_channels/lib/push-connect-error.ts

@@ -0,0 +1,52 @@
+export type PushConnectErrorBody = {
+  code?: string | null
+  fieldErrors?: Record<string, string> | null
+  fieldErrorCodes?: Record<string, string> | null
+}
+
+export type PushConnectTranslate = (key: string, fallback: string) => string
+
+/**
+ * Map a push connect route's structured error `code`
+ * (`provider_not_tenant_scoped`, `mailbox_already_connected`,
+ * `wrong_scope_for_route`, …) to a localized
+ * `communication_channels.push.connect.errors.<code>` message, falling back to
+ * the generic `push.connect.failed` when the response carries no code or no
+ * matching translation exists. The raw English `error` string the route also
+ * returns stays reserved for logs/API consumers so the shipped locale files
+ * apply on the failure path.
+ */
+export function resolvePushConnectErrorMessage(
+  translate: PushConnectTranslate,
+  body: PushConnectErrorBody | undefined,
+): string {
+  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)
+}
+
+/**
+ * Localize the per-field credential-validation errors a 422 connect response
+ * carries. Each field's `fieldErrorCodes` entry maps to
+ * `communication_channels.push.connect.errors.fields.<code>`; when a field has
+ * no code (an adapter that predates the code contract) or the locale ships no
+ * matching key, the raw English `fieldErrors` string is used so the operator
+ * still sees something actionable rather than a blank field.
+ *
+ * Returns a map ready for a widget's `setFieldErrors`.
+ */
+export function resolvePushConnectFieldErrors(
+  translate: PushConnectTranslate,
+  body: PushConnectErrorBody | undefined,
+): Record<string, string> {
+  const fieldErrors = body?.fieldErrors ?? {}
+  const fieldErrorCodes = body?.fieldErrorCodes ?? {}
+  const resolved: Record<string, string> = {}
+  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
+}

package/src/modules/communication_channels/lib/push-credential-errors.ts

@@ -0,0 +1,58 @@
+/**
+ * Stable field-error codes for push credential validation (fcm/apns/expo).
+ *
+ * Push credential schemas emit one of these codes as the zod issue `message`
+ * instead of prose. {@link BasePushChannelAdapter.validateCredentials} then
+ * splits each issue into two channels:
+ *
+ *   - `errors[field]`     — English prose from {@link PUSH_CREDENTIAL_ERROR_MESSAGES},
+ *                           reserved for logs and API consumers.
+ *   - `errorCodes[field]` — the code, which the connect widgets map to
+ *                           `communication_channels.push.connect.errors.fields.<code>`
+ *                           so operators see a localized message.
+ *
+ * This mirrors the route-level split already used by `push-connect-error.ts`.
+ * An issue whose message is not a known code degrades to {@link PUSH_CREDENTIAL_ERROR_INVALID}
+ * with the raw zod message kept in `errors`, so a schema change can never leak
+ * an untranslated internal string into the UI.
+ */
+
+export const PUSH_CREDENTIAL_ERROR_REQUIRED = 'required'
+export const PUSH_CREDENTIAL_ERROR_INVALID = 'invalid'
+export const PUSH_CREDENTIAL_ERROR_INVALID_JSON = 'invalid_json'
+export const PUSH_CREDENTIAL_ERROR_MISSING_FIELDS = 'missing_fields'
+export const PUSH_CREDENTIAL_ERROR_INVALID_P8 = 'invalid_p8'
+export const PUSH_CREDENTIAL_ERROR_INVALID_KEY_ID = 'invalid_key_id'
+export const PUSH_CREDENTIAL_ERROR_INVALID_TEAM_ID = 'invalid_team_id'
+export const PUSH_CREDENTIAL_ERROR_INVALID_BUNDLE_ID = 'invalid_bundle_id'
+
+/**
+ * English prose per code. Kept as the `errors` payload so existing API
+ * consumers and log readers still get a human-readable string.
+ */
+export const PUSH_CREDENTIAL_ERROR_MESSAGES: Record<string, string> = {
+  [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.',
+}
+
+export function isPushCredentialErrorCode(value: string): boolean {
+  return Object.prototype.hasOwnProperty.call(PUSH_CREDENTIAL_ERROR_MESSAGES, value)
+}
+
+/**
+ * Split a zod issue message into `{ code, message }`. Known codes resolve to
+ * their English prose; anything else is reported as {@link PUSH_CREDENTIAL_ERROR_INVALID}
+ * while preserving the original text for logs.
+ */
+export function resolvePushCredentialIssue(issueMessage: string): { code: string; message: string } {
+  if (isPushCredentialErrorCode(issueMessage)) {
+    return { code: issueMessage, message: PUSH_CREDENTIAL_ERROR_MESSAGES[issueMessage] }
+  }
+  return { code: PUSH_CREDENTIAL_ERROR_INVALID, message: issueMessage }
+}