@open-mercato/core 0.6.4-develop.4382.1.6b4f656b77 → 0.6.4

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

@@ -0,0 +1,95 @@
+import { findOneWithDecryption, findWithDecryption } from "@open-mercato/shared/lib/encryption/find";
+import { CommunicationChannel } from "../data/entities.js";
+import { isUniqueViolation } from "./pg-errors.js";
+const POLLING_ONLY_DEFAULT_INTERVAL_SECONDS = 300;
+class MailboxAlreadyConnectedError extends Error {
+  constructor(externalIdentifier, existingProviderKey) {
+    super(`Mailbox ${externalIdentifier} is already connected via ${existingProviderKey}`);
+    this.name = "MailboxAlreadyConnectedError";
+    this.externalIdentifier = externalIdentifier;
+    this.existingProviderKey = existingProviderKey;
+  }
+}
+async function createConnectedChannelRow(args) {
+  const { em, adapter, providerKey, displayName, externalIdentifier, credentialsRefId, userId, scope } = args;
+  const credentialsAvailable = credentialsRefId !== null;
+  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();
+    const userChannels = await findWithDecryption(
+      em,
+      CommunicationChannel,
+      { tenantId: scope.tenantId, userId, deletedAt: null },
+      void 0,
+      dscope
+    );
+    const conflict = userChannels.find(
+      (existing) => existing.providerKey !== providerKey && typeof existing.externalIdentifier === "string" && existing.externalIdentifier.toLowerCase() === normalized
+    );
+    if (conflict) {
+      throw new MailboxAlreadyConnectedError(externalIdentifier, conflict.providerKey);
+    }
+  }
+  const naturalKey = {
+    tenantId: scope.tenantId,
+    userId,
+    providerKey,
+    externalIdentifier,
+    deletedAt: null
+  };
+  const applyConnectionState = (target) => {
+    target.channelType = adapter.channelType;
+    target.displayName = displayName;
+    target.externalIdentifier = externalIdentifier ?? null;
+    target.credentialsRef = credentialsRefId;
+    target.capabilities = adapter.capabilities;
+    target.isActive = credentialsAvailable;
+    target.pollIntervalSeconds = pollIntervalSeconds;
+    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 (existing) {
+      applyConnectionState(existing);
+      await em.flush();
+      return existing;
+    }
+  }
+  const channel = em.create(CommunicationChannel, {
+    providerKey,
+    channelType: adapter.channelType,
+    displayName,
+    externalIdentifier: externalIdentifier ?? null,
+    credentialsRef: credentialsRefId,
+    capabilities: adapter.capabilities,
+    isActive: credentialsAvailable,
+    userId,
+    isPrimary: false,
+    pollIntervalSeconds,
+    status: credentialsAvailable ? "connected" : "requires_reauth",
+    lastError: credentialsAvailable ? null : "credentials_persist_failed",
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId ?? null
+  });
+  em.persist(channel);
+  try {
+    await em.flush();
+    return channel;
+  } catch (err) {
+    if (!isUniqueViolation(err) || !externalIdentifier) throw err;
+    const reEm = em.fork();
+    const winner = await findOneWithDecryption(reEm, CommunicationChannel, naturalKey, void 0, dscope);
+    if (!winner) throw err;
+    applyConnectionState(winner);
+    await reEm.flush();
+    return winner;
+  }
+}
+export {
+  MailboxAlreadyConnectedError,
+  POLLING_ONLY_DEFAULT_INTERVAL_SECONDS,
+  createConnectedChannelRow
+};
+//# sourceMappingURL=connect-channel.js.map

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

@@ -0,0 +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;",
+  "names": []
+}

package/dist/modules/communication_channels/lib/contact-resolver.js

@@ -0,0 +1,79 @@
+import { isTenantDataEncryptionEnabled } from "@open-mercato/shared/lib/encryption/toggles";
+async function resolveContact(input, deps) {
+  const adapterHint = await runAdapterResolve(input);
+  if (!adapterHint && !input.senderIdentifier) return null;
+  const lookupEmail = adapterHint?.email ?? heuristicEmail(input.senderIdentifier);
+  const lookupPhone = adapterHint?.phone ?? heuristicPhone(input.senderIdentifier);
+  let matchedPersonId;
+  if ((lookupEmail || lookupPhone) && deps.container) {
+    matchedPersonId = await lookupCustomerPersonId({
+      container: deps.container,
+      scope: input.scope,
+      email: lookupEmail,
+      phone: lookupPhone
+    });
+  }
+  return {
+    ...adapterHint ?? {},
+    email: lookupEmail,
+    phone: lookupPhone,
+    displayName: adapterHint?.displayName ?? input.senderDisplayName,
+    matchedPersonId: matchedPersonId ?? adapterHint?.matchedPersonId
+  };
+}
+async function runAdapterResolve(input) {
+  if (typeof input.adapter.resolveContact !== "function") return null;
+  try {
+    return await input.adapter.resolveContact({
+      senderIdentifier: input.senderIdentifier,
+      senderDisplayName: input.senderDisplayName,
+      channelMetadata: input.channelMetadata,
+      credentials: input.credentials,
+      scope: input.scope
+    }) ?? null;
+  } catch {
+    return null;
+  }
+}
+async function lookupCustomerPersonId(params) {
+  if (isTenantDataEncryptionEnabled()) return void 0;
+  let queryEngine = null;
+  try {
+    queryEngine = params.container.resolve("queryEngine");
+  } catch {
+    return void 0;
+  }
+  if (!queryEngine || typeof queryEngine.query !== "function") return void 0;
+  const filter = buildPersonLookupFilter(params.email, params.phone);
+  if (!filter) return void 0;
+  try {
+    const rows = await queryEngine.query("customers:customer_entity", {
+      tenantId: params.scope.tenantId,
+      organizationId: params.scope.organizationId,
+      filter,
+      limit: 1
+    });
+    const first = rows?.[0];
+    const id = first && typeof first.id === "string" ? first.id : void 0;
+    return id;
+  } catch {
+    return void 0;
+  }
+}
+function buildPersonLookupFilter(email, phone) {
+  if (email) return { primary_email: email, kind: "person" };
+  if (phone) return { primary_phone: phone, kind: "person" };
+  return null;
+}
+function heuristicEmail(senderIdentifier) {
+  if (!senderIdentifier.includes("@")) return void 0;
+  return senderIdentifier.includes(".") ? senderIdentifier : void 0;
+}
+function heuristicPhone(senderIdentifier) {
+  if (/^\+\d{6,}$/.test(senderIdentifier)) return senderIdentifier;
+  return void 0;
+}
+export {
+  resolveContact
+};
+//# sourceMappingURL=contact-resolver.js.map

package/dist/modules/communication_channels/lib/contact-resolver.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/communication_channels/lib/contact-resolver.ts"],
+  "sourcesContent": ["import type { AwilixContainer } from 'awilix'\nimport { isTenantDataEncryptionEnabled } from '@open-mercato/shared/lib/encryption/toggles'\nimport type { ChannelAdapter, ContactHint, TenantScope } from './adapter'\n\n/**\n * Contact resolver \u2014 used by the inbound bridge to attach an external sender\n * to a CRM person.\n *\n * Flow (SPEC-045d \u00A78.1):\n *   1. If the adapter implements `resolveContact?(...)`, call it to get a\n *      provider-side ContactHint (display name, photo URL, possibly an email\n *      lookup the adapter performed against its own user directory).\n *   2. If the hint includes an email or phone, query the CRM (`customers:customer_entity`)\n *      via the **QueryEngine** (NOT raw SQL \u2014 root AGENTS.md mandate). If a person\n *      matches, populate `matchedPersonId` on the returned hint.\n *   3. Return the merged hint, or `null` if neither the adapter nor the CRM\n *      yields any identity information.\n */\n\nexport interface ContactResolverInput {\n  adapter: ChannelAdapter\n  senderIdentifier: string\n  senderDisplayName?: string\n  channelMetadata?: Record<string, unknown>\n  credentials: Record<string, unknown>\n  scope: TenantScope\n}\n\nexport interface ResolveContactDeps {\n  container: { resolve: <T = unknown>(name: string) => T }\n}\n\ntype QueryEngineLike = {\n  query: (\n    entityType: string,\n    options: {\n      tenantId: string\n      organizationId?: string | null\n      filter?: Record<string, unknown>\n      limit?: number\n      offset?: number\n    },\n  ) => Promise<Record<string, unknown>[]>\n}\n\n/**\n * Resolve a CRM contact from an external sender identifier.\n *\n * Returns `null` when no identity could be derived. Callers MUST treat the\n * return value as advisory (a hint, not an authoritative match) \u2014 see spec\n * \u00A7 8 \"Contact resolution false positive\" risk.\n */\nexport async function resolveContact(\n  input: ContactResolverInput,\n  deps: ResolveContactDeps,\n): Promise<ContactHint | null> {\n  // Step 1 \u2014 adapter resolution (optional)\n  const adapterHint: ContactHint | null = await runAdapterResolve(input)\n  if (!adapterHint && !input.senderIdentifier) return null\n\n  // Step 2 \u2014 CRM lookup by email or phone, via QueryEngine (no raw SQL).\n  const lookupEmail = adapterHint?.email ?? heuristicEmail(input.senderIdentifier)\n  const lookupPhone = adapterHint?.phone ?? heuristicPhone(input.senderIdentifier)\n\n  let matchedPersonId: string | undefined\n  if ((lookupEmail || lookupPhone) && deps.container) {\n    matchedPersonId = await lookupCustomerPersonId({\n      container: deps.container,\n      scope: input.scope,\n      email: lookupEmail,\n      phone: lookupPhone,\n    })\n  }\n\n  return {\n    ...(adapterHint ?? {}),\n    email: lookupEmail,\n    phone: lookupPhone,\n    displayName: adapterHint?.displayName ?? input.senderDisplayName,\n    matchedPersonId: matchedPersonId ?? adapterHint?.matchedPersonId,\n  }\n}\n\nasync function runAdapterResolve(input: ContactResolverInput): Promise<ContactHint | null> {\n  if (typeof input.adapter.resolveContact !== 'function') return null\n  try {\n    return (\n      (await input.adapter.resolveContact({\n        senderIdentifier: input.senderIdentifier,\n        senderDisplayName: input.senderDisplayName,\n        channelMetadata: input.channelMetadata,\n        credentials: input.credentials,\n        scope: input.scope,\n      })) ?? null\n    )\n  } catch {\n    // The adapter is best-effort. A failure does not block ingest; we just lose\n    // the optional CRM match. Errors are not propagated.\n    return null\n  }\n}\n\nasync function lookupCustomerPersonId(params: {\n  container: ResolveContactDeps['container']\n  scope: TenantScope\n  email?: string\n  phone?: string\n}): Promise<string | undefined> {\n  // Under tenant encryption, `primary_email`/`primary_phone` are stored as\n  // ciphertext, so a plaintext equality filter on the base column both hits the\n  // \u00A716 \"no querying an encrypted column by value\" footgun and never matches.\n  // Skip the fast lookup in that case (it would only ever return nothing) \u2014 the\n  // authoritative CRM link is created by the customers `link-channel-message`\n  // subscriber, which does an in-memory decrypted comparison. A blind-index\n  // column is the proper fast-path fix here (same follow-up as\n  // `customers/lib/findPeopleByAddresses`).\n  if (isTenantDataEncryptionEnabled()) return undefined\n\n  let queryEngine: QueryEngineLike | null = null\n  try {\n    queryEngine = params.container.resolve<QueryEngineLike>('queryEngine')\n  } catch {\n    return undefined\n  }\n  if (!queryEngine || typeof queryEngine.query !== 'function') return undefined\n\n  const filter = buildPersonLookupFilter(params.email, params.phone)\n  if (!filter) return undefined\n\n  try {\n    const rows = await queryEngine.query('customers:customer_entity', {\n      tenantId: params.scope.tenantId,\n      organizationId: params.scope.organizationId,\n      filter,\n      limit: 1,\n    })\n    const first = rows?.[0]\n    const id = first && typeof first.id === 'string' ? (first.id as string) : undefined\n    return id\n  } catch {\n    return undefined\n  }\n}\n\nfunction buildPersonLookupFilter(email?: string, phone?: string): Record<string, unknown> | null {\n  if (email) return { primary_email: email, kind: 'person' }\n  if (phone) return { primary_phone: phone, kind: 'person' }\n  return null\n}\n\nfunction heuristicEmail(senderIdentifier: string): string | undefined {\n  if (!senderIdentifier.includes('@')) return undefined\n  // Don't second-guess provider-supplied data; just check it's email-shaped.\n  return senderIdentifier.includes('.') ? senderIdentifier : undefined\n}\n\nfunction heuristicPhone(senderIdentifier: string): string | undefined {\n  // Plain heuristic: +CC followed by 6+ digits. Real phone validation is the\n  // adapter's job (the email integration spec elaborates IMAP paths).\n  if (/^\\+\\d{6,}$/.test(senderIdentifier)) return senderIdentifier\n  return undefined\n}\n"],
+  "mappings": "AACA,SAAS,qCAAqC;AAmD9C,eAAsB,eACpB,OACA,MAC6B;AAE7B,QAAM,cAAkC,MAAM,kBAAkB,KAAK;AACrE,MAAI,CAAC,eAAe,CAAC,MAAM,iBAAkB,QAAO;AAGpD,QAAM,cAAc,aAAa,SAAS,eAAe,MAAM,gBAAgB;AAC/E,QAAM,cAAc,aAAa,SAAS,eAAe,MAAM,gBAAgB;AAE/E,MAAI;AACJ,OAAK,eAAe,gBAAgB,KAAK,WAAW;AAClD,sBAAkB,MAAM,uBAAuB;AAAA,MAC7C,WAAW,KAAK;AAAA,MAChB,OAAO,MAAM;AAAA,MACb,OAAO;AAAA,MACP,OAAO;AAAA,IACT,CAAC;AAAA,EACH;AAEA,SAAO;AAAA,IACL,GAAI,eAAe,CAAC;AAAA,IACpB,OAAO;AAAA,IACP,OAAO;AAAA,IACP,aAAa,aAAa,eAAe,MAAM;AAAA,IAC/C,iBAAiB,mBAAmB,aAAa;AAAA,EACnD;AACF;AAEA,eAAe,kBAAkB,OAA0D;AACzF,MAAI,OAAO,MAAM,QAAQ,mBAAmB,WAAY,QAAO;AAC/D,MAAI;AACF,WACG,MAAM,MAAM,QAAQ,eAAe;AAAA,MAClC,kBAAkB,MAAM;AAAA,MACxB,mBAAmB,MAAM;AAAA,MACzB,iBAAiB,MAAM;AAAA,MACvB,aAAa,MAAM;AAAA,MACnB,OAAO,MAAM;AAAA,IACf,CAAC,KAAM;AAAA,EAEX,QAAQ;AAGN,WAAO;AAAA,EACT;AACF;AAEA,eAAe,uBAAuB,QAKN;AAS9B,MAAI,8BAA8B,EAAG,QAAO;AAE5C,MAAI,cAAsC;AAC1C,MAAI;AACF,kBAAc,OAAO,UAAU,QAAyB,aAAa;AAAA,EACvE,QAAQ;AACN,WAAO;AAAA,EACT;AACA,MAAI,CAAC,eAAe,OAAO,YAAY,UAAU,WAAY,QAAO;AAEpE,QAAM,SAAS,wBAAwB,OAAO,OAAO,OAAO,KAAK;AACjE,MAAI,CAAC,OAAQ,QAAO;AAEpB,MAAI;AACF,UAAM,OAAO,MAAM,YAAY,MAAM,6BAA6B;AAAA,MAChE,UAAU,OAAO,MAAM;AAAA,MACvB,gBAAgB,OAAO,MAAM;AAAA,MAC7B;AAAA,MACA,OAAO;AAAA,IACT,CAAC;AACD,UAAM,QAAQ,OAAO,CAAC;AACtB,UAAM,KAAK,SAAS,OAAO,MAAM,OAAO,WAAY,MAAM,KAAgB;AAC1E,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,SAAS,wBAAwB,OAAgB,OAAgD;AAC/F,MAAI,MAAO,QAAO,EAAE,eAAe,OAAO,MAAM,SAAS;AACzD,MAAI,MAAO,QAAO,EAAE,eAAe,OAAO,MAAM,SAAS;AACzD,SAAO;AACT;AAEA,SAAS,eAAe,kBAA8C;AACpE,MAAI,CAAC,iBAAiB,SAAS,GAAG,EAAG,QAAO;AAE5C,SAAO,iBAAiB,SAAS,GAAG,IAAI,mBAAmB;AAC7D;AAEA,SAAS,eAAe,kBAA8C;AAGpE,MAAI,aAAa,KAAK,gBAAgB,EAAG,QAAO;AAChD,SAAO;AACT;",
+  "names": []
+}

package/dist/modules/communication_channels/lib/credential-refresh.js

@@ -0,0 +1,97 @@
+import { resolveOAuthClientCredentials } from "./oauth-client-config.js";
+const DEFAULT_REFRESH_WINDOW_MS = 6e4;
+const inFlightRefreshes = /* @__PURE__ */ new Map();
+async function refreshCredentialsIfNeeded(input, deps) {
+  const log = deps?.logger ?? (() => {
+  });
+  if (typeof input.adapter.refreshCredentials !== "function") {
+    return { refreshed: false, credentials: input.credentials };
+  }
+  const refreshWindow = input.refreshWindowMs ?? DEFAULT_REFRESH_WINDOW_MS;
+  if (!input.force && !shouldRefresh(input.credentials, refreshWindow)) {
+    return { refreshed: false, credentials: input.credentials };
+  }
+  const existing = inFlightRefreshes.get(input.channelId);
+  if (existing) return existing;
+  const refreshCredentials = input.adapter.refreshCredentials.bind(input.adapter);
+  const refreshPromise = runRefresh(input, refreshCredentials, deps, log).finally(() => {
+    inFlightRefreshes.delete(input.channelId);
+  });
+  inFlightRefreshes.set(input.channelId, refreshPromise);
+  return refreshPromise;
+}
+async function runRefresh(input, refreshCredentials, deps, log) {
+  let oauthClient;
+  if (deps?.credentialsService) {
+    try {
+      const raw = await resolveOAuthClientCredentials(
+        deps.credentialsService,
+        input.adapter.providerKey,
+        { tenantId: input.scope.tenantId, organizationId: input.scope.organizationId }
+      );
+      oauthClient = safeParseOAuthClient(raw);
+    } catch (resolveErr) {
+      log(
+        "[communication_channels] resolving OAuth client config failed:",
+        resolveErr instanceof Error ? resolveErr.message : resolveErr
+      );
+    }
+  }
+  let result;
+  try {
+    result = await refreshCredentials({
+      channelId: input.channelId,
+      credentials: input.credentials,
+      scope: input.scope,
+      oauthClient
+    });
+  } catch (err) {
+    log("[communication_channels] refreshCredentials failed:", err instanceof Error ? err.message : err);
+    return { refreshed: false, credentials: input.credentials };
+  }
+  const next = result?.credentials ?? input.credentials;
+  if (deps?.credentialsService?.save) {
+    try {
+      await deps.credentialsService.save(
+        `channel_${input.adapter.providerKey}`,
+        result.expiresAt ? { ...next, expiresAt: result.expiresAt.toISOString() } : next,
+        input.scope
+      );
+    } catch (saveErr) {
+      log("[communication_channels] persisting refreshed credentials failed:", saveErr instanceof Error ? saveErr.message : saveErr);
+    }
+  }
+  return { refreshed: true, credentials: next };
+}
+function shouldRefresh(credentials, windowMs) {
+  const expiresAtRaw = credentials?.expiresAt;
+  if (!expiresAtRaw) return false;
+  const expiresAt = parseExpiresAt(expiresAtRaw);
+  if (!expiresAt) return false;
+  return expiresAt.getTime() - Date.now() <= windowMs;
+}
+function parseExpiresAt(raw) {
+  if (raw instanceof Date) return Number.isFinite(raw.getTime()) ? raw : null;
+  if (typeof raw === "string" || typeof raw === "number") {
+    const date = new Date(raw);
+    return Number.isFinite(date.getTime()) ? date : null;
+  }
+  return null;
+}
+function safeParseOAuthClient(raw) {
+  if (!raw || typeof raw !== "object") return void 0;
+  const record = raw;
+  const clientId = typeof record.clientId === "string" ? record.clientId : void 0;
+  if (!clientId) return void 0;
+  const clientSecret = typeof record.clientSecret === "string" ? record.clientSecret : void 0;
+  const scopes = Array.isArray(record.scopes) ? record.scopes.filter((value) => typeof value === "string") : void 0;
+  return {
+    clientId,
+    ...clientSecret !== void 0 ? { clientSecret } : {},
+    ...scopes !== void 0 ? { scopes } : {}
+  };
+}
+export {
+  refreshCredentialsIfNeeded
+};
+//# sourceMappingURL=credential-refresh.js.map

package/dist/modules/communication_channels/lib/credential-refresh.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/communication_channels/lib/credential-refresh.ts"],
+  "sourcesContent": ["import type {\n  ChannelAdapter,\n  OAuthClientConfig,\n  RefreshedCredentials,\n  TenantScope,\n} from './adapter'\nimport { resolveOAuthClientCredentials } from './oauth-client-config'\n\n/**\n * Optional credentials-service shape \u2014 matches the integrations module's\n * `CredentialsService`. We keep this loose so the helper compiles even when\n * the integrations module is disabled in a downstream app (the helper just\n * skips persistence in that case).\n */\n/**\n * Matches the real `CredentialsService.save(integrationId, credentials, scope)`\n * signature from `packages/core/src/modules/integrations/lib/credentials-service.ts`.\n * The legacy call sites had this argument order inverted; that bug was the root\n * cause of C1 in the 2026-05-26 review.\n *\n * `scope.userId` (added 2026-05-26 for per-user channels) lets the credentials\n * service write to a user-scoped row instead of overwriting the tenant-wide row.\n */\ntype CredentialsScope = TenantScope & { userId?: string | null }\ntype CredentialsServiceLike = {\n  resolve: (integrationId: string, scope: CredentialsScope) => Promise<Record<string, unknown> | null>\n  save?: (integrationId: string, credentials: Record<string, unknown>, scope: CredentialsScope) => Promise<void>\n}\n\nexport type RefreshCredentialsIfNeededInput = {\n  adapter: ChannelAdapter\n  channelId: string\n  /** Current decrypted credential blob. May contain `expiresAt` (Date or ISO string). */\n  credentials: Record<string, unknown>\n  scope: CredentialsScope\n  /** Refresh window \u2014 refresh when token expires within this many ms. Defaults to 60s. */\n  refreshWindowMs?: number\n  /** Force a refresh regardless of expiry \u2014 used after a 401 response from the provider. */\n  force?: boolean\n}\n\nexport type RefreshCredentialsIfNeededResult = {\n  refreshed: boolean\n  /** The latest credential blob to use for the outbound call. */\n  credentials: Record<string, unknown>\n}\n\nconst DEFAULT_REFRESH_WINDOW_MS = 60_000\n\n/**\n * In-process single-flight for credential refresh, keyed by `channelId`. The\n * outbound-delivery worker runs at concurrency 10 in ONE process, so two\n * concurrent sends on the same channel can both pass `shouldRefresh` and both\n * call `adapter.refreshCredentials`. With rotating refresh-token providers\n * (Gmail) the second exchange invalidates the first's token and\n * flaps the channel to `requires_reauth`. Coalescing concurrent refreshes for\n * the same channel onto one in-flight promise prevents that race for the common\n * single-process case. Entries are deleted in `finally` once settled.\n */\nconst inFlightRefreshes = new Map<string, Promise<RefreshCredentialsIfNeededResult>>()\n\n/**\n * Refresh OAuth credentials when an access token is near expiry, or when the\n * caller forces it (e.g. after a 401 response).\n *\n * Behaviour:\n *   - No-op when the adapter does not implement `refreshCredentials?`.\n *   - No-op when the credential blob has no `expiresAt` AND `force !== true`.\n *   - Returns the refreshed credentials in-memory; persistence to\n *     `integration_credentials` happens via the `CredentialsService` if it\n *     is registered AND exposes `save()` (best-effort \u2014 failures are logged\n *     but don't block the outbound call).\n */\nexport async function refreshCredentialsIfNeeded(\n  input: RefreshCredentialsIfNeededInput,\n  deps?: { credentialsService?: CredentialsServiceLike | null; logger?: (...args: unknown[]) => void },\n): Promise<RefreshCredentialsIfNeededResult> {\n  const log = deps?.logger ?? (() => {})\n  if (typeof input.adapter.refreshCredentials !== 'function') {\n    return { refreshed: false, credentials: input.credentials }\n  }\n\n  const refreshWindow = input.refreshWindowMs ?? DEFAULT_REFRESH_WINDOW_MS\n  if (!input.force && !shouldRefresh(input.credentials, refreshWindow)) {\n    return { refreshed: false, credentials: input.credentials }\n  }\n\n  // Coalesce concurrent refreshes for the same channel onto one in-flight\n  // promise so rotating refresh tokens are not exchanged twice in parallel.\n  const existing = inFlightRefreshes.get(input.channelId)\n  if (existing) return existing\n\n  const refreshCredentials = input.adapter.refreshCredentials.bind(input.adapter)\n  const refreshPromise = runRefresh(input, refreshCredentials, deps, log).finally(() => {\n    inFlightRefreshes.delete(input.channelId)\n  })\n  inFlightRefreshes.set(input.channelId, refreshPromise)\n  return refreshPromise\n}\n\nasync function runRefresh(\n  input: RefreshCredentialsIfNeededInput,\n  refreshCredentials: NonNullable<ChannelAdapter['refreshCredentials']>,\n  deps: { credentialsService?: CredentialsServiceLike | null; logger?: (...args: unknown[]) => void } | undefined,\n  log: (...args: unknown[]) => void,\n): Promise<RefreshCredentialsIfNeededResult> {\n  // Resolve the tenant's OAuth client config (clientId/clientSecret) the admin\n  // stored under the `channel_<providerKey>` integration at TENANT scope\n  // (userId = null). The adapter uses it for the token-endpoint call. We always\n  // resolve at tenant scope here \u2014 never the channel's per-user scope \u2014 because\n  // the per-user row holds the user's tokens, not the client app credentials.\n  let oauthClient: OAuthClientConfig | undefined\n  if (deps?.credentialsService) {\n    try {\n      const raw = await resolveOAuthClientCredentials(\n        deps.credentialsService,\n        input.adapter.providerKey,\n        { tenantId: input.scope.tenantId, organizationId: input.scope.organizationId },\n      )\n      oauthClient = safeParseOAuthClient(raw)\n    } catch (resolveErr) {\n      log(\n        '[communication_channels] resolving OAuth client config failed:',\n        resolveErr instanceof Error ? resolveErr.message : resolveErr,\n      )\n    }\n  }\n\n  let result: RefreshedCredentials\n  try {\n    result = await refreshCredentials({\n      channelId: input.channelId,\n      credentials: input.credentials,\n      scope: input.scope,\n      oauthClient,\n    })\n  } catch (err) {\n    log('[communication_channels] refreshCredentials failed:', err instanceof Error ? err.message : err)\n    // Return current credentials \u2014 caller may still attempt the send with the old token.\n    return { refreshed: false, credentials: input.credentials }\n  }\n\n  const next = result?.credentials ?? input.credentials\n  if (deps?.credentialsService?.save) {\n    try {\n      await deps.credentialsService.save(\n        `channel_${input.adapter.providerKey}`,\n        result.expiresAt ? { ...next, expiresAt: result.expiresAt.toISOString() } : next,\n        input.scope,\n      )\n    } catch (saveErr) {\n      log('[communication_channels] persisting refreshed credentials failed:', saveErr instanceof Error ? saveErr.message : saveErr)\n    }\n  }\n\n  return { refreshed: true, credentials: next }\n}\n\nfunction shouldRefresh(credentials: Record<string, unknown>, windowMs: number): boolean {\n  const expiresAtRaw = credentials?.expiresAt\n  if (!expiresAtRaw) return false\n  const expiresAt = parseExpiresAt(expiresAtRaw)\n  if (!expiresAt) return false\n  return expiresAt.getTime() - Date.now() <= windowMs\n}\n\nfunction parseExpiresAt(raw: unknown): Date | null {\n  if (raw instanceof Date) return Number.isFinite(raw.getTime()) ? raw : null\n  if (typeof raw === 'string' || typeof raw === 'number') {\n    const date = new Date(raw)\n    return Number.isFinite(date.getTime()) ? date : null\n  }\n  return null\n}\n\n/**\n * Parse a raw `channel_<provider>` client-credential row into the\n * `OAuthClientConfig` shape adapters expect. Returns `undefined` when the row is\n * missing or malformed \u2014 adapters then fall back to the deprecated\n * `credentials._client` read path (one minor-release deprecation per Spec A).\n */\nfunction safeParseOAuthClient(raw: unknown): OAuthClientConfig | undefined {\n  if (!raw || typeof raw !== 'object') return undefined\n  const record = raw as Record<string, unknown>\n  const clientId = typeof record.clientId === 'string' ? record.clientId : undefined\n  if (!clientId) return undefined\n  const clientSecret =\n    typeof record.clientSecret === 'string' ? record.clientSecret : undefined\n  const scopes = Array.isArray(record.scopes)\n    ? record.scopes.filter((value): value is string => typeof value === 'string')\n    : undefined\n  return {\n    clientId,\n    ...(clientSecret !== undefined ? { clientSecret } : {}),\n    ...(scopes !== undefined ? { scopes } : {}),\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/modules/communication_channels/lib/dead-letter.js

@@ -0,0 +1,62 @@
+import { findOneWithDecryption } from "@open-mercato/shared/lib/encryption/find";
+import { ChannelIngestDeadLetter } from "../data/entities.js";
+const DEAD_LETTER_RAW_BODY_MAX_BYTES_DEFAULT = 32768;
+function extractExternalUid(message) {
+  const meta = message.channelMetadata;
+  if (meta && typeof meta.uid === "string") return meta.uid;
+  if (meta && typeof meta.uid === "number") return String(meta.uid);
+  return null;
+}
+function truncateRawBody(message) {
+  const envCap = Number.parseInt(process.env.OM_CHANNEL_DEAD_LETTER_RAW_BODY_MAX_BYTES ?? "", 10);
+  const cap = Number.isFinite(envCap) && envCap > 0 ? envCap : DEAD_LETTER_RAW_BODY_MAX_BYTES_DEFAULT;
+  const body = message.body ?? "";
+  if (body.length === 0) return null;
+  const buf = Buffer.from(body, "utf-8");
+  if (buf.byteLength <= cap) return body;
+  return `${buf.subarray(0, cap).toString("utf-8")}\u2026[truncated]`;
+}
+async function writeIngestDeadLetter(args) {
+  const { em, scope, channel, message, err, errorMessage } = args;
+  const externalMessageId = message.externalMessageId ?? null;
+  try {
+    if (externalMessageId) {
+      const existing = await findOneWithDecryption(
+        em,
+        ChannelIngestDeadLetter,
+        {
+          tenantId: scope.tenantId,
+          organizationId: scope.organizationId ?? null,
+          channelId: channel.id,
+          externalMessageId
+        },
+        void 0,
+        { tenantId: scope.tenantId, organizationId: scope.organizationId ?? null }
+      );
+      if (existing) return;
+    }
+    const deadLetter = em.create(ChannelIngestDeadLetter, {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId ?? null,
+      channelId: channel.id,
+      providerKey: channel.providerKey,
+      externalUid: extractExternalUid(message),
+      externalMessageId,
+      errorClass: err instanceof Error ? err.name : "Error",
+      errorMessage,
+      rawBody: truncateRawBody(message)
+    });
+    em.persist(deadLetter);
+    await em.flush();
+  } catch (ddlErr) {
+    console.error(
+      `[communication_channels:dead-letter] failed to record dead-letter for channel ${channel.id}: ${ddlErr instanceof Error ? ddlErr.message : String(ddlErr)}`
+    );
+  }
+}
+export {
+  extractExternalUid,
+  truncateRawBody,
+  writeIngestDeadLetter
+};
+//# sourceMappingURL=dead-letter.js.map

package/dist/modules/communication_channels/lib/dead-letter.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/communication_channels/lib/dead-letter.ts"],
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'\nimport { ChannelIngestDeadLetter } from '../data/entities'\nimport type { NormalizedInboundMessage } from './adapter'\n\nconst DEAD_LETTER_RAW_BODY_MAX_BYTES_DEFAULT = 32_768\n\nexport function extractExternalUid(message: NormalizedInboundMessage): string | null {\n  const meta = message.channelMetadata as Record<string, unknown> | undefined\n  if (meta && typeof meta.uid === 'string') return meta.uid\n  if (meta && typeof meta.uid === 'number') return String(meta.uid)\n  return null\n}\n\n/**\n * First N *bytes* of the raw body, for dead-letter forensics. Counts bytes (not\n * UTF-16 code units) so a multi-byte body cannot blow past the intended cap.\n */\nexport function truncateRawBody(message: NormalizedInboundMessage): string | null {\n  const envCap = Number.parseInt(process.env.OM_CHANNEL_DEAD_LETTER_RAW_BODY_MAX_BYTES ?? '', 10)\n  const cap = Number.isFinite(envCap) && envCap > 0 ? envCap : DEAD_LETTER_RAW_BODY_MAX_BYTES_DEFAULT\n  const body = message.body ?? ''\n  if (body.length === 0) return null\n  const buf = Buffer.from(body, 'utf-8')\n  if (buf.byteLength <= cap) return body\n  return `${buf.subarray(0, cap).toString('utf-8')}\u2026[truncated]`\n}\n\nexport interface WriteIngestDeadLetterArgs {\n  em: EntityManager\n  scope: { tenantId: string; organizationId?: string | null }\n  channel: { id: string; providerKey: string }\n  message: NormalizedInboundMessage\n  err: unknown\n  errorMessage: string\n}\n\n/**\n * Persist a `ChannelIngestDeadLetter` row for a permanently-failed inbound\n * message so an operator can replay it later. Best-effort: a failure to write\n * the dead-letter is logged but never thrown, so a bad message cannot block the\n * caller from advancing its cursor.\n *\n * Idempotent on `(channelId, externalMessageId)`: a replayed page that fails the\n * same message again is a no-op, so the dead-letter table never accumulates\n * duplicate rows for the same poison message.\n */\nexport async function writeIngestDeadLetter(args: WriteIngestDeadLetterArgs): Promise<void> {\n  const { em, scope, channel, message, err, errorMessage } = args\n  const externalMessageId = message.externalMessageId ?? null\n  try {\n    if (externalMessageId) {\n      const existing = await findOneWithDecryption(\n        em,\n        ChannelIngestDeadLetter,\n        {\n          tenantId: scope.tenantId,\n          organizationId: scope.organizationId ?? null,\n          channelId: channel.id,\n          externalMessageId,\n        },\n        undefined,\n        { tenantId: scope.tenantId, organizationId: scope.organizationId ?? null },\n      )\n      if (existing) return\n    }\n    const deadLetter = em.create(ChannelIngestDeadLetter, {\n      tenantId: scope.tenantId,\n      organizationId: scope.organizationId ?? null,\n      channelId: channel.id,\n      providerKey: channel.providerKey,\n      externalUid: extractExternalUid(message),\n      externalMessageId,\n      errorClass: err instanceof Error ? err.name : 'Error',\n      errorMessage,\n      rawBody: truncateRawBody(message),\n    })\n    em.persist(deadLetter)\n    await em.flush()\n  } catch (ddlErr) {\n    console.error(\n      `[communication_channels:dead-letter] failed to record dead-letter for channel ${channel.id}: ${\n        ddlErr instanceof Error ? ddlErr.message : String(ddlErr)\n      }`,\n    )\n  }\n}\n"],
+  "mappings": "AACA,SAAS,6BAA6B;AACtC,SAAS,+BAA+B;AAGxC,MAAM,yCAAyC;AAExC,SAAS,mBAAmB,SAAkD;AACnF,QAAM,OAAO,QAAQ;AACrB,MAAI,QAAQ,OAAO,KAAK,QAAQ,SAAU,QAAO,KAAK;AACtD,MAAI,QAAQ,OAAO,KAAK,QAAQ,SAAU,QAAO,OAAO,KAAK,GAAG;AAChE,SAAO;AACT;AAMO,SAAS,gBAAgB,SAAkD;AAChF,QAAM,SAAS,OAAO,SAAS,QAAQ,IAAI,6CAA6C,IAAI,EAAE;AAC9F,QAAM,MAAM,OAAO,SAAS,MAAM,KAAK,SAAS,IAAI,SAAS;AAC7D,QAAM,OAAO,QAAQ,QAAQ;AAC7B,MAAI,KAAK,WAAW,EAAG,QAAO;AAC9B,QAAM,MAAM,OAAO,KAAK,MAAM,OAAO;AACrC,MAAI,IAAI,cAAc,IAAK,QAAO;AAClC,SAAO,GAAG,IAAI,SAAS,GAAG,GAAG,EAAE,SAAS,OAAO,CAAC;AAClD;AAqBA,eAAsB,sBAAsB,MAAgD;AAC1F,QAAM,EAAE,IAAI,OAAO,SAAS,SAAS,KAAK,aAAa,IAAI;AAC3D,QAAM,oBAAoB,QAAQ,qBAAqB;AACvD,MAAI;AACF,QAAI,mBAAmB;AACrB,YAAM,WAAW,MAAM;AAAA,QACrB;AAAA,QACA;AAAA,QACA;AAAA,UACE,UAAU,MAAM;AAAA,UAChB,gBAAgB,MAAM,kBAAkB;AAAA,UACxC,WAAW,QAAQ;AAAA,UACnB;AAAA,QACF;AAAA,QACA;AAAA,QACA,EAAE,UAAU,MAAM,UAAU,gBAAgB,MAAM,kBAAkB,KAAK;AAAA,MAC3E;AACA,UAAI,SAAU;AAAA,IAChB;AACA,UAAM,aAAa,GAAG,OAAO,yBAAyB;AAAA,MACpD,UAAU,MAAM;AAAA,MAChB,gBAAgB,MAAM,kBAAkB;AAAA,MACxC,WAAW,QAAQ;AAAA,MACnB,aAAa,QAAQ;AAAA,MACrB,aAAa,mBAAmB,OAAO;AAAA,MACvC;AAAA,MACA,YAAY,eAAe,QAAQ,IAAI,OAAO;AAAA,MAC9C;AAAA,MACA,SAAS,gBAAgB,OAAO;AAAA,IAClC,CAAC;AACD,OAAG,QAAQ,UAAU;AACrB,UAAM,GAAG,MAAM;AAAA,EACjB,SAAS,QAAQ;AACf,YAAQ;AAAA,MACN,iFAAiF,QAAQ,EAAE,KACzF,kBAAkB,QAAQ,OAAO,UAAU,OAAO,MAAM,CAC1D;AAAA,IACF;AAAA,EACF;AACF;",
+  "names": []
+}

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

@@ -0,0 +1,47 @@
+const EMAIL_MAX_ATTACHMENT_BYTES = 25e6;
+const baseEmailCapabilities = {
+  // Core
+  threading: true,
+  richText: true,
+  fileSharing: false,
+  maxFileSize: EMAIL_MAX_ATTACHMENT_BYTES,
+  supportedMimeTypes: [
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+    "application/pdf",
+    "application/zip",
+    "application/octet-stream",
+    "text/plain",
+    "text/html",
+    "text/csv"
+  ],
+  readReceipts: false,
+  deliveryReceipts: false,
+  typingIndicators: false,
+  // Extended
+  reactions: false,
+  multiReactionPerUser: false,
+  editMessage: false,
+  deleteMessage: false,
+  presence: false,
+  richBlocks: false,
+  interactiveComponents: false,
+  inlineImages: true,
+  conversationHistory: true,
+  contactCards: false,
+  locationSharing: false,
+  voiceNotes: false,
+  stickers: false,
+  // Body formats
+  supportedBodyFormats: ["text", "html"],
+  maxBodyLength: 5e6,
+  // Polling (real-time push deferred to v2 for all email providers)
+  realtimePush: false
+};
+export {
+  EMAIL_MAX_ATTACHMENT_BYTES,
+  baseEmailCapabilities
+};
+//# sourceMappingURL=email-capabilities.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/communication_channels/lib/email-capabilities.ts"],
+  "sourcesContent": ["import type { ChannelCapabilities } from './adapter'\n\n/**\n * Shared default attachment ceiling for email providers (Gmail allows\n * more, but larger uploads need resumable/upload-session APIs we don't use, so\n * all providers cap at the same conservative value).\n */\nexport const EMAIL_MAX_ATTACHMENT_BYTES = 25_000_000\n\n/**\n * Baseline capability profile shared by every email channel provider. Providers\n * spread this and override only what genuinely differs (e.g. `deleteMessage`).\n *\n * `fileSharing: false` until a provider's `convertOutbound` stitches attachment\n * bytes into the sent message \u2014 advertising `true` would silently drop bytes.\n */\nexport const baseEmailCapabilities: ChannelCapabilities = {\n  // Core\n  threading: true,\n  richText: true,\n  fileSharing: false,\n  maxFileSize: EMAIL_MAX_ATTACHMENT_BYTES,\n  supportedMimeTypes: [\n    'image/png',\n    'image/jpeg',\n    'image/gif',\n    'image/webp',\n    'application/pdf',\n    'application/zip',\n    'application/octet-stream',\n    'text/plain',\n    'text/html',\n    'text/csv',\n  ],\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: true,\n  conversationHistory: true,\n  contactCards: false,\n  locationSharing: false,\n  voiceNotes: false,\n  stickers: false,\n\n  // Body formats\n  supportedBodyFormats: ['text', 'html'],\n  maxBodyLength: 5_000_000,\n\n  // Polling (real-time push deferred to v2 for all email providers)\n  realtimePush: false,\n}\n"],
+  "mappings": "AAOO,MAAM,6BAA6B;AASnC,MAAM,wBAA6C;AAAA;AAAA,EAExD,WAAW;AAAA,EACX,UAAU;AAAA,EACV,aAAa;AAAA,EACb,aAAa;AAAA,EACb,oBAAoB;AAAA,IAClB;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA,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,QAAQ,MAAM;AAAA,EACrC,eAAe;AAAA;AAAA,EAGf,cAAc;AAChB;",
+  "names": []
+}

package/dist/modules/communication_channels/lib/email-contact.js

@@ -0,0 +1,14 @@
+async function emailResolveContact(input) {
+  if (!input.senderIdentifier) return null;
+  if (input.senderIdentifier.includes("@")) {
+    return {
+      email: input.senderIdentifier,
+      displayName: input.senderDisplayName
+    };
+  }
+  return null;
+}
+export {
+  emailResolveContact
+};
+//# sourceMappingURL=email-contact.js.map

package/dist/modules/communication_channels/lib/email-contact.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/communication_channels/lib/email-contact.ts"],
+  "sourcesContent": ["import type { ContactHint, ResolveContactInput } from './adapter'\n\n/**\n * Shared `resolveContact` for email providers. An email sender identifier *is*\n * the contact email, so the hint is a direct passthrough; non-email identifiers\n * (or empty senders) yield `null` and the hub falls back to its own resolution.\n */\nexport async function emailResolveContact(input: ResolveContactInput): Promise<ContactHint | null> {\n  if (!input.senderIdentifier) return null\n  if (input.senderIdentifier.includes('@')) {\n    return {\n      email: input.senderIdentifier,\n      displayName: input.senderDisplayName,\n    }\n  }\n  return null\n}\n"],
+  "mappings": "AAOA,eAAsB,oBAAoB,OAAyD;AACjG,MAAI,CAAC,MAAM,iBAAkB,QAAO;AACpC,MAAI,MAAM,iBAAiB,SAAS,GAAG,GAAG;AACxC,WAAO;AAAA,MACL,OAAO,MAAM;AAAA,MACb,aAAa,MAAM;AAAA,IACrB;AAAA,EACF;AACA,SAAO;AACT;",
+  "names": []
+}