feat(sdk): Hybrid Link tier transitions (resolution, merge, candidates)

CHANGELOG.md

@@ -2,10 +2,16 @@
 
 ## Unreleased
 
+- Hybrid Link tier transitions. `Client.sessions.quoteTierChange` accepts
+  `hybridResolution` (`keep` one connection or `split` into two Numbers) for a
+  Hybrid Link Number leaving Pro, or `hybridMerge` to merge a same-number pair
+  on an upgrade to Pro. `NumberTierChange.quote.hybridTransition` reports the
+  plan and its `status`. `Client.projects.listHybridMergeCandidates` lists
+  mergeable pairs. `PolymorfaErrorCode` adds `hybrid_choice_required` and
+  `hybrid_transition_ineligible`.
 - `Session` gains optional `newChatCapping` (`NewChatCapping`): WhatsApp's
   per-number new-chat cap, returned by `sessions.retrieve` for linked-device
   numbers. API contract: polymorfa/polymorfa#403.
-
 - Brazil payment orders (beta, requires team enrollment, an Official API
   Number and Meta payments eligibility in Brazil). `messages.send` accepts
   `orderDetails` (Pix dynamic code, payment link or boleto, itemized or

README.md

@@ -305,10 +305,11 @@ The organization view also exposes these management resources:
   customer incidents
 - `projects`: list, create, request production enrollment, approve, and cancel;
   retrieve and update Safe Mode, warm-up, Ban Insurance evidence, and Health
-  policy settings
+  policy settings; list same-number pairs that can merge into Hybrid Link
 - `sessions`: list, start, stop, or delete one session; stop or delete a bounded
-  batch; review and confirm a tier change; create a testing session; and
-  retrieve or update the session Safe Mode override
+  batch; review and confirm a tier change, including the Hybrid Link
+  resolution or merge; create a testing session; and retrieve or update the
+  session Safe Mode override
 - `campaigns`: list, create, retrieve, update, delete, lifecycle actions,
   analytics, events, and paged or appended recipients. The single-campaign
   operations require the owning `projectId`. This resource is available only

contracts/README.md

@@ -41,6 +41,35 @@ published SDK package before updating their pinned dependency.
 
 ## Full snapshots
 
+The current snapshots are byte-identical copies of the Messaging and Platform
+OpenAPI files at `polymorfa/polymorfa` commit
+`fcf7b21015dd185e987b5aa3580e8af5f4c7f1a4` on the coordinated API branch
+`t3code/hybrid-pro-downgrade` (API PR #404, not yet merged to API `dev`). The
+Messaging file is byte-identical to the SDK `dev` pin `e818ba6`. The Platform
+file adds Hybrid Link tier transitions: `hybridResolution` and `hybridMerge` on
+`NumberTierQuoteRequest`, `quote.hybridTransition` on `NumberTierChange`, and
+`GET /platform/projects/{projectId}/hybrid-merge-candidates`, covered by
+`Client.projects.listHybridMergeCandidates`. Each candidate Number reports
+`canBeAbsorbed` (false with hosted message storage), and the list returns
+`403 feature_unavailable` without live Hybrid Link access. A missing choice
+returns `409 hybrid_choice_required`, and a queued change rejected for that
+reason reports `failureReason: "hybrid_choice_required"`.
+`hybrid_choice_required` and `hybrid_transition_ineligible` are documented in
+operation prose rather than the public error enum; `POLYMORFA_ERROR_CODES`
+lists both. Four fingerprints changed: the three tier-quote operations and the
+excluded Console `updateProject`.
+
+The branch also contains API `dev` through `5ce6290bc`, whose PR #428 adds six
+Platform operations for hosted Flow endpoints and Flow encryption keys
+(`GET`/`PUT`/`DELETE /platform/flows/{flowId}/endpoint`,
+`GET /platform/flows/{flowId}/endpoint/receipts`,
+`GET /platform/flow-encryption-keys` and
+`POST /platform/flow-encryption-keys/rotate`). No SDK change covers them yet;
+the ledger excludes them with that reason. Repin to the merged API `dev` commit
+before merging this SDK change.
+
+The preceding snapshots were described as follows.
+
 The two public Flow draft reads in the pinned Platform snapshot are covered by
 `Client.project(projectId).flows.list` and `.retrieve`. The API declares both
 public, project-bound, and `sessions:read`.
@@ -232,12 +261,12 @@ signed events with these names still decode as unknown events.
 
 | Status              | Operations |
 | ------------------- | ---------: |
-| Covered             |        406 |
+| Covered             |        421 |
 | Missing             |          0 |
-| Excluded            |        130 |
+| Excluded            |        136 |
 | Partial             |          0 |
 | Changed fingerprint |          0 |
-| Total               |        536 |
+| Total               |        557 |
 
 This revision adds test event triggering
 (`POST /messaging/testing/{projectId}/events`) and fixture listing

contracts/coverage.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sourceCommit": "e818ba62830d3727a7822379bb46c1fece90ef1b",
+  "sourceCommit": "fcf7b21015dd185e987b5aa3580e8af5f4c7f1a4",
   "excludedContracts": [
     {
       "family": "graph",
@@ -3990,7 +3990,7 @@
       "method": "GET",
       "path": "/platform/sessions/{sessionId}/tier-quotes/{quoteId}",
       "operationId": "getSessionTierChange",
-      "fingerprint": "26a366bd27b1e77700ca427f137f3f01c99c398f41f95edb8008af2bcb19aefe",
+      "fingerprint": "602247de1ae72206a3207b1cd8d7ce65fec0a7b386716f6b5e24fd85f79b5454",
       "typescript": {
         "status": "covered",
         "method": "Client.sessions.retrieveTierChange"
@@ -4278,7 +4278,7 @@
       "method": "PATCH",
       "path": "/console/projects/{projectId}",
       "operationId": "updateProject",
-      "fingerprint": "1d124460d20e14953ecf03af3372e69a31b59c512a4b27568c8537d936a9ed17",
+      "fingerprint": "17294266cd2773fd99470bd94aab7b9a01adba28b3718c31a312a8ac00e36985",
       "typescript": {
         "status": "excluded",
         "reason": "Console-only operation requires dashboard identity; not available to SDK credentials."
@@ -4377,7 +4377,7 @@
       "method": "PATCH",
       "path": "/platform/sessions/{sessionId}",
       "operationId": "setSessionTierOverride",
-      "fingerprint": "a28a3700b2e1ca7362a57de40598959640bbf31d709d929623206bc3ecd45f1d",
+      "fingerprint": "42e924cd6ea94896fa447071dfa78b152f06475f06d5be200ed9d5cffdab1f96",
       "typescript": {
         "status": "covered",
         "method": "Client.sessions.setTierOverride"
@@ -5165,6 +5165,72 @@
         "method": "Client.project(projectId).flows.upload"
       }
     },
+    {
+      "family": "platform",
+      "method": "DELETE",
+      "path": "/platform/flows/{flowId}/endpoint",
+      "operationId": "deleteFlowEndpoint",
+      "fingerprint": "c282b7d48c759117c33fbc797616541664c01da36679335444e53d48d37e4e6a",
+      "typescript": {
+        "status": "excluded",
+        "reason": "Hosted Flow endpoint and Flow encryption key operations from API PR #428 have no SDK owner yet; they are outside the Hybrid Link tier-transition change and need a separate SDK PR."
+      }
+    },
+    {
+      "family": "platform",
+      "method": "GET",
+      "path": "/platform/flow-encryption-keys",
+      "operationId": "getFlowEncryptionKey",
+      "fingerprint": "2cef096982f4a550dff1c3cded7248685c28d433c36bd2304d99a193f8cda000",
+      "typescript": {
+        "status": "excluded",
+        "reason": "Hosted Flow endpoint and Flow encryption key operations from API PR #428 have no SDK owner yet; they are outside the Hybrid Link tier-transition change and need a separate SDK PR."
+      }
+    },
+    {
+      "family": "platform",
+      "method": "GET",
+      "path": "/platform/flows/{flowId}/endpoint",
+      "operationId": "getFlowEndpoint",
+      "fingerprint": "12354b56aedcccd9a81fae27d6deb93da3e6490e07192cb8137770312bafe5ff",
+      "typescript": {
+        "status": "excluded",
+        "reason": "Hosted Flow endpoint and Flow encryption key operations from API PR #428 have no SDK owner yet; they are outside the Hybrid Link tier-transition change and need a separate SDK PR."
+      }
+    },
+    {
+      "family": "platform",
+      "method": "GET",
+      "path": "/platform/flows/{flowId}/endpoint/receipts",
+      "operationId": "listFlowEndpointReceipts",
+      "fingerprint": "861ecbba5343f1b72688b9c8da9fb2a678de49cf10abf16794464e8870c68427",
+      "typescript": {
+        "status": "excluded",
+        "reason": "Hosted Flow endpoint and Flow encryption key operations from API PR #428 have no SDK owner yet; they are outside the Hybrid Link tier-transition change and need a separate SDK PR."
+      }
+    },
+    {
+      "family": "platform",
+      "method": "POST",
+      "path": "/platform/flow-encryption-keys/rotate",
+      "operationId": "rotateFlowEncryptionKey",
+      "fingerprint": "44534cbc6d6ee4f783e3f1782dfa4f638f5c94fe9cb176f93fb74c18dc8f2457",
+      "typescript": {
+        "status": "excluded",
+        "reason": "Hosted Flow endpoint and Flow encryption key operations from API PR #428 have no SDK owner yet; they are outside the Hybrid Link tier-transition change and need a separate SDK PR."
+      }
+    },
+    {
+      "family": "platform",
+      "method": "PUT",
+      "path": "/platform/flows/{flowId}/endpoint",
+      "operationId": "setFlowEndpoint",
+      "fingerprint": "cefa55fe9a7793bc12f590909c8620dd9b82a7f793750167505bce84143ae5a4",
+      "typescript": {
+        "status": "excluded",
+        "reason": "Hosted Flow endpoint and Flow encryption key operations from API PR #428 have no SDK owner yet; they are outside the Hybrid Link tier-transition change and need a separate SDK PR."
+      }
+    },
     {
       "family": "platform",
       "method": "POST",
@@ -5503,7 +5569,7 @@
       "method": "POST",
       "path": "/platform/sessions/{sessionId}/tier-quotes",
       "operationId": "quoteSessionTierChange",
-      "fingerprint": "7bd49359f1b8a15cd21477573209924c7ea1532d0f4b258eb0022a30a8c4593a",
+      "fingerprint": "a9e13a9e870e108da6669c7a1bd79655df499ab2c03f22f5e4bcea89f621d185",
       "typescript": {
         "status": "covered",
         "method": "Client.sessions.quoteTierChange"
@@ -5852,6 +5918,17 @@
         "method": "Client.projects.updateWarmupPlan"
       }
     },
+    {
+      "family": "platform",
+      "method": "GET",
+      "path": "/platform/projects/{projectId}/hybrid-merge-candidates",
+      "operationId": "listHybridMergeCandidates",
+      "fingerprint": "e4fdcbb9deffd164c07bd7f10b50455f339fed3cb0d8817a4344eac0f8af49ee",
+      "typescript": {
+        "status": "covered",
+        "method": "Client.projects.listHybridMergeCandidates"
+      }
+    },
     {
       "family": "platform",
       "method": "PUT",