integration.provider-customer-support

@lssm-tech/integration.provider-customer-support

Provider-specific SupportOS adapters above the neutral customer-support contracts. The initial Intercom lane pins REST API 2.15, models US/EU/Australia hosts, retrieves OAuth credentials only through secret references, verifies webhook HMAC before durable receipt, and supports cursor overlap/reconciliation plus explicit authority cutover.

Intercom remains authoritative until a signed cutover. The adapter never places SDK types, access tokens, raw webhook bodies, or customer content in semantic contracts or telemetry.

Support actions and ambiguous outcomes

IntercomTransport is method-aware: reads retry under a bounded policy, while effects retry only a definitive 429. A timeout, network failure, 5xx or unreadable success after an effect was sent raises IntercomIndeterminateOutcomeError; Idempotency-Key is not forwarded because Intercom 2.15 documents no idempotency guarantee for these endpoints. IntercomSupportAdapter.dispatch never returns a synthetic receipt.

IntercomConversationActionExecutor implements the SupportOS SupportConversationActionPort for reply, note, assign, snooze, reopen and close. Each action is claimed in durable custody under its idempotency key before the provider call; duplicates are suppressed and a reused key with a different payload is an idempotency conflict. Customer-visible actions need an approval bound to digestSupportConversationAction and a basis part; internal actions need that approval or a Connect admission (SupportConversationActionAdmissionPort). An approved verdict alone never authorizes an effect: the approval must prove an independent human signer, read from approverIdentity (SupportApprovalIdentityPort) when bound or else named by the verdict, who is neither the responding Intercom admin (actorRef) nor the principal that admin maps to through responderPrincipals (SupportResponderPrincipalPort). Without a responder mapping, or for an unmapped admin, approvals authorize nothing; a failed identity or mapping lookup is DEPENDENCY_DEGRADED and sends nothing. The action request names no proposer, so the executor does not exclude the proposer: support-resolution-v1 (SupportResolutionWorkflow) enforces that before dispatch, and a host calling the executor directly must do the same. A newer human/Fin reply, customer follow-up, foreign assignee or closed conversation supersedes or rejects the action before sending. The parts present before dispatch are recorded; reconcile reads the conversation back with IntercomConversationReader and only a new matching part (no negative clock skew) proves acceptance. Absence after the grace window stays uncertain until confirmNotExecuted records a human confirmation. Bind a durable custody store in production; InMemorySupportConversationActionCustody is for tests. IntercomSupportAdapter.dispatch routes support.reply, support.note, support.assign, support.snooze, support.reopen and support.close through the typed executor passed as its last constructor argument (and fails closed without one); only an accepted provider part is returned as a receipt. resolveIntercomCommand now serves only tag, contact and company updates.