diff --git a/CHANGELOG.md b/CHANGELOG.md index 60ae9b997..800e177d9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -83,6 +83,16 @@ defaults where available. Go callers should use keyed struct literals. Appended .NET record fields also change the positional deconstruction shape. +- All six server SDKs recognize the Ban Credit claim verdict + `linked_device_interactive` on claim reads and `bansafe.claim` webhooks, and + type claim evidence `linkedDeviceInteractive`. Rust's closed verdict enums + previously rejected this value. Source compatibility: Rust exhaustive + `match` on the verdict enums and `ClaimEvidence` struct literals, Go unkeyed `BanSafeClaimEvidence` + literals and the C# `BanSafeClaimEvidence` constructor/Deconstruct need the + added members. Pinned to API contract revision `f180dc1ee2` (merged to API `dev` as + `a3db53e74c`), which contains merged API #845. Package publication follows the existing release + process. + - UI Kit: keep a 320px thread beside the Inbox list in narrow two-pane layouts, and include the linked guides in the package. - Breaking: the browser UI packages are now one package, the UI Kit @@ -113,7 +123,6 @@ - Add the read-only nullable call-settings exclusion-end response field across all six SDKs. Rust response struct literals require the new optional field; C# positional construction remains compatible. Bound to accepted API source `77e9ce31`, which also clarifies when a ban is excluded; unreleased. - TypeScript, Python and PHP call-settings updates now refuse keys the API does not accept, including the response-only `simultaneousCallsCoverageExcludedUntil`, before sending. Go, Rust and .NET requests already serialize only writable fields. - - All six server SDKs expose optional automatic-pause `reason`/`code` and optional recipient-skip `messageIndex`/`followUpId` from accepted API source `9bb1e2ed`. Future reason/code strings and raw envelope fields are retained; diff --git a/contracts/README.md b/contracts/README.md index 9ac0a9704..076447722 100644 --- a/contracts/README.md +++ b/contracts/README.md @@ -1,5 +1,16 @@ # Contract coverage +## Ban Credit claim waivers + +`ban-credit-waivers.json` pins the `BanSafeClaim` and `BanSafeClaimPayload` +verdict enums and the `linkedDeviceInteractive` claim evidence field to API contract revision `f180dc1ee2bd45dbecf01702f73bdd75c664634b` +(polymorfa/polymorfa#845, merged; that revision merged to API `dev` as +`a3db53e74c` with byte-identical specifications). It is held with `published: false`. +`ban-credit-waivers-contract.test.ts` checks the TypeScript types against it; +each native package has a decoding test. No operation is added. The full +snapshots here already contain the verdict, so this supplement stays as the +explicit pin that the decoding tests read. + ## Number-scoped Test phone and events The full Messaging snapshot at API `f180dc1ee2bd45dbecf01702f73bdd75c664634b` diff --git a/contracts/ban-credit-waivers.json b/contracts/ban-credit-waivers.json new file mode 100644 index 000000000..53450df44 --- /dev/null +++ b/contracts/ban-credit-waivers.json @@ -0,0 +1,65 @@ +{ + "repository": "polymorfa/polymorfa", + "sourceCommit": "f180dc1ee2bd45dbecf01702f73bdd75c664634b", + "published": false, + "scope": "Ban Credit claim waivers: verdict linked_device_interactive and claim evidence linkedDeviceInteractive (polymorfa/polymorfa#845, merged; contained in contract revision f180dc1ee2, merged to API dev as a3db53e74c). Other SDK contracts retain their recorded source revisions.", + "sources": { + "platform": { + "sourcePath": "apps/api/docs/openapi.management.json", + "sha256": "bee9be6cc08d2ec78f5eb5e05135bea3751f93af917b8dd6983b26029feac485" + }, + "messaging": { + "sourcePath": "apps/api/docs/openapi.json", + "sha256": "0c66f1ee93923cf57425ac29c01a84c5c140b703ace2160e1b899ee6dad0b071" + } + }, + "verdicts": { + "BanSafeClaim": { + "family": "platform", + "enum": [ + "other_device", + "customer_conduct", + "shared_network", + "ours", + "inconclusive", + "simultaneous_calls", + "linked_device_interactive" + ] + }, + "BanSafeClaimPayload": { + "family": "messaging", + "enum": [ + "other_device", + "customer_conduct", + "shared_network", + "ours", + "inconclusive", + "simultaneous_calls", + "linked_device_interactive" + ] + } + }, + "evidence": { + "BanSafeClaimEvidence": { + "family": "platform", + "required": [ + "attributionRuleVersion", + "windowDays", + "deviceEvidence", + "otherDevices", + "restrictedInWindow", + "criticalFindingDays", + "sharedConnection", + "measuredHours", + "simultaneousCalls", + "linkedDeviceInteractive" + ], + "properties": { + "linkedDeviceInteractive": { + "type": "boolean", + "description": "Whether this number sent an interactive message (buttons, lists, product messages, Flows and similar) from a linked device inside the window. When true, Ban Credit does not cover the ban and the claim is denied when filed. False can also mean not recorded: earlier claims report false, and sends before recording began are not backfilled." + } + } + } + } +} diff --git a/contracts/doc-snippets.json b/contracts/doc-snippets.json index bc6b23f11..910a36513 100644 --- a/contracts/doc-snippets.json +++ b/contracts/doc-snippets.json @@ -1,7 +1,7 @@ { "schemaVersion": 1, - "sourceCommit": "1e6fd9952e8183497a28f43c3987d960d9bf52eb", - "sourceFilesSha256": "536a8c44342cf6a09e6a47d37f6f3239b8a083471a33743a2b8b0cfa32a73792", + "sourceCommit": "f8a64f81955e87f7a3ff64c3f15061a1e967bd0c", + "sourceFilesSha256": "a470c775eb94e39111bd251c255076caad4236ed1b5ecb4284d7b620aa2e54fa", "apiVersion": "2026-09-22", "apiSourceCommit": "f180dc1ee2bd45dbecf01702f73bdd75c664634b", "specs": { diff --git a/packages/dotnet/README.md b/packages/dotnet/README.md index 5f9d48931..bbf9143b6 100644 --- a/packages/dotnet/README.md +++ b/packages/dotnet/README.md @@ -1010,6 +1010,12 @@ when the 30-day claim window overlaps an enabled period. Claim verdicts and `bansafe.claim` webhook verdicts recognize `simultaneous_calls`. Claim evidence includes `simultaneousCalls`; the webhook does not acquire an evidence object. +Ban Credit claims also recognize `linked_device_interactive` (the Number sent +an interactive message from a linked device in the 30 days before the ban), on +claim reads and `bansafe.claim` webhooks. It opens `denied` with amount 0. +Claim evidence includes `linkedDeviceInteractive`; claims filed before it was +recorded report `false`. + No browser/client-token authority, call media behavior, automatic state read, retry policy or feature availability is added by these SDK fields. diff --git a/packages/dotnet/src/Polymorfa.Sdk/BanSafe.cs b/packages/dotnet/src/Polymorfa.Sdk/BanSafe.cs index f9f38d553..47cf84854 100644 --- a/packages/dotnet/src/Polymorfa.Sdk/BanSafe.cs +++ b/packages/dotnet/src/Polymorfa.Sdk/BanSafe.cs @@ -64,7 +64,7 @@ public sealed record BanSafeEnforcementSummary : BanSafeNumber public sealed record BanSafeIncident(string Id, string SessionId, string Session, string PhoneNumber, string ProjectId, string Kind, string Source, string Resolution, bool Ambiguous, string StartedAt, string? EndsAt, string? ClosedAt, string? ClosedBy, string? ClaimId, string? Note, string? ReportedBy, string CreatedAt); public sealed record ReportBanSafeIncidentRequest(string Session, string? OccurredAt = null, string? Note = null); public sealed record BanSafeIncidentReceipt(string IncidentId, bool Created, string SessionId, string Session, string OccurredAt); -public sealed record BanSafeClaimEvidence(long? AttributionRuleVersion, int WindowDays, bool DeviceEvidence, long OtherDevices, bool RestrictedInWindow, long CriticalFindingDays, bool SharedConnection, decimal MeasuredHours, bool SimultaneousCalls); +public sealed record BanSafeClaimEvidence(long? AttributionRuleVersion, int WindowDays, bool DeviceEvidence, long OtherDevices, bool RestrictedInWindow, long CriticalFindingDays, bool SharedConnection, decimal MeasuredHours, bool SimultaneousCalls, bool LinkedDeviceInteractive); public sealed record BanSafeClaim(string Id, string IncidentId, string SessionId, string Session, string PhoneNumber, string ProjectId, string Status, string Verdict, string WindowStart, string WindowEnd, decimal MeasuredCents, decimal CapCents, decimal AmountCents, BanSafeClaimEvidence Evidence, string Summary, string Reason, string? DecidedAt, string? PaidAt, string CreatedAt); public sealed record BanSafeSignalDefinition(string Key, string Label, string Group, string Kind, string Unit, string Description); public sealed record BanSafeCodeCount(long Code, long Count); diff --git a/packages/dotnet/tests/Polymorfa.Sdk.Tests/BanSafeTests.cs b/packages/dotnet/tests/Polymorfa.Sdk.Tests/BanSafeTests.cs index e8f0a8652..d0642d5e4 100644 --- a/packages/dotnet/tests/Polymorfa.Sdk.Tests/BanSafeTests.cs +++ b/packages/dotnet/tests/Polymorfa.Sdk.Tests/BanSafeTests.cs @@ -5,7 +5,7 @@ internal static class BanSafeTests { private const string Health = """{"sessionId":"s1","session":"support","phoneNumber":"+15550001111","projectId":"p1","health":null,"band":"unknown","healthSource":"unavailable","healthEstimatorVersion":null,"healthModelVersion":null,"healthEvaluatedAt":null,"healthFeatureCoverage":null,"healthReliability":"unavailable","healthUnavailableReason":"no_active_model","healthProbabilities":null,"mostLikelyHealthState":null,"healthExplanation":null,"observedAccountState":{"state":"limited","observedAt":"2026-09-22","source":"restriction_event"},"enforcement":null}"""; private const string Incident = """{"id":"i1","sessionId":"s1","session":"support","phoneNumber":"+15550001111","projectId":"p1","kind":"customer_report","source":"customer","resolution":"retracted","ambiguous":true,"startedAt":"2026-09-22","endsAt":null,"closedAt":null,"closedBy":"owner","claimId":null,"note":null,"reportedBy":null,"createdAt":"2026-09-22"}"""; - private const string Claim = """{"id":"c1","incidentId":"i1","sessionId":"s1","session":"support","phoneNumber":"+15550001111","projectId":"p1","status":"paid","verdict":"ours","windowStart":"2026-09-01","windowEnd":"2026-09-22","measuredCents":1.123456,"capCents":2.123456,"amountCents":0.123456,"evidence":{"attributionRuleVersion":1,"windowDays":21,"deviceEvidence":false,"otherDevices":0,"restrictedInWindow":false,"criticalFindingDays":0,"sharedConnection":false,"simultaneousCalls":false,"measuredHours":1.5},"summary":"Reviewed","reason":"ours","decidedAt":null,"paidAt":null,"createdAt":"2026-09-22"}"""; + private const string Claim = """{"id":"c1","incidentId":"i1","sessionId":"s1","session":"support","phoneNumber":"+15550001111","projectId":"p1","status":"paid","verdict":"ours","windowStart":"2026-09-01","windowEnd":"2026-09-22","measuredCents":1.123456,"capCents":2.123456,"amountCents":0.123456,"evidence":{"attributionRuleVersion":1,"windowDays":21,"deviceEvidence":false,"otherDevices":0,"restrictedInWindow":false,"criticalFindingDays":0,"sharedConnection":false,"simultaneousCalls":false,"linkedDeviceInteractive":false,"measuredHours":1.5},"summary":"Reviewed","reason":"ours","decidedAt":null,"paidAt":null,"createdAt":"2026-09-22"}"""; private const string Collection = """{"state":"fresh","latestFlushedAt":"2026-09-22","latestReceivedAt":"2026-09-22","freshUntil":null,"recordVersion":1,"collectorVersion":1,"partial":false,"droppedRecords":0}"""; private const string Snapshot = """{"bucketStart":"2026-09-22","flushedAt":"2026-09-22","receivedAt":"2026-09-22","partial":false,"recordVersion":1,"signals":[{"key":"latency","label":"Latency","group":"delivery","kind":"histogram","unit":"milliseconds","description":"Latency","measured":true,"value":[1.25,2.5],"sampleSize":2,"codes":null},{"key":"ready","label":"Ready","group":"connection","kind":"boolean","unit":"none","description":"Ready","measured":true,"value":false,"sampleSize":0,"codes":[{"code":403,"count":1}]}]}"""; public static async Task RunAsync() @@ -26,6 +26,20 @@ public static async Task RunAsync() await Team("POST", "/platform/bansafe/incidents/i1/retract", null, Envelope(Incident), async c => ResourceTests.Equal((await c.BanSafe.RetractIncidentAsync("i1")).Data.Data.ClosedBy, "owner")); await Team("GET", "/platform/bansafe/claims?session=support&status=paid", null, Page(Claim), async c => ResourceTests.Equal((await c.BanSafe.ListClaimsAsync(new(Session: "support", Status: "paid"))).Items[0].AmountCents, 0.123456m)); await Team("GET", "/platform/bansafe/claims/c1", null, Envelope(Claim), async c => ResourceTests.Equal((await c.BanSafe.GetClaimAsync("c1")).Data.Data.Evidence.MeasuredHours, 1.5m)); + // Ban Credit waiver: the verdict and evidence flag decode from the claim read. + foreach (var (verdict, linked) in new[] { ("linked_device_interactive", true) }) + { + var waived = Claim.Replace("\"status\":\"paid\",\"verdict\":\"ours\"", $"\"status\":\"denied\",\"verdict\":\"{verdict}\"").Replace("\"attributionRuleVersion\":1", "\"attributionRuleVersion\":3").Replace("\"linkedDeviceInteractive\":false", $"\"linkedDeviceInteractive\":{(linked ? "true" : "false")}"); + await Team("GET", "/platform/bansafe/claims/c1", null, Envelope(waived), async c => + { + var claim = (await c.BanSafe.GetClaimAsync("c1")).Data.Data; + ResourceTests.Equal(claim.Verdict, verdict); + ResourceTests.Equal(claim.Evidence.AttributionRuleVersion, 3L); + ResourceTests.True(claim.Evidence.LinkedDeviceInteractive == linked); + }); + var payload = JsonSerializer.Deserialize($$"""{"id":"c1","incidentId":"i1","phoneNumber":"+15550001111","status":"denied","verdict":"{{verdict}}","windowStart":"a","windowEnd":"b","measuredCents":0,"capCents":0,"amountCents":0,"summary":"s","reason":"r","decidedAt":null,"paidAt":null}""", new JsonSerializerOptions(JsonSerializerDefaults.Web))!; + ResourceTests.Equal(payload.Verdict, verdict); + } var options = new JsonSerializerOptions(); foreach (var json in new[] { "null", "0", "false", "\"unknown\"", "[]", "[1.5,2.25]" }) { var v = JsonSerializer.Deserialize(json, options); ResourceTests.Equal(JsonSerializer.Serialize(v, options), json); } foreach (var json in new[] { "{}", "[true]" }) { try { JsonSerializer.Deserialize(json, options); throw new Exception("Invalid signal value accepted"); } catch (JsonException) { } catch (InvalidOperationException) { } } Console.WriteLine("PASS 15 BanSafe routes, health authority/nulls, closed signal variants and six-decimal claims"); diff --git a/packages/dotnet/tests/Polymorfa.Sdk.Tests/CallsTests.cs b/packages/dotnet/tests/Polymorfa.Sdk.Tests/CallsTests.cs index a4b24ee7d..fa404c994 100644 --- a/packages/dotnet/tests/Polymorfa.Sdk.Tests/CallsTests.cs +++ b/packages/dotnet/tests/Polymorfa.Sdk.Tests/CallsTests.cs @@ -39,7 +39,7 @@ public static async Task RunAsync() await Invalid(() => client.Calls.UpdateCallSettingsAsync("s", new(AcknowledgeRisk: true))); await Invalid(() => client.Calls.ReportAsync("call", new("quality", "connection1", new("polymorfa-dotnet", "0.1.0", "other"), Quality: new(RttMs: -1)))); var json = new System.Text.Json.JsonSerializerOptions { PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase }; - var claim = System.Text.Json.JsonSerializer.Deserialize("""{"attributionRuleVersion":null,"windowDays":30,"deviceEvidence":false,"otherDevices":0,"restrictedInWindow":false,"criticalFindingDays":0,"sharedConnection":false,"simultaneousCalls":true,"measuredHours":0}""", json)!; + var claim = System.Text.Json.JsonSerializer.Deserialize("""{"attributionRuleVersion":null,"windowDays":30,"deviceEvidence":false,"otherDevices":0,"restrictedInWindow":false,"criticalFindingDays":0,"sharedConnection":false,"simultaneousCalls":true,"linkedDeviceInteractive":false,"measuredHours":0}""", json)!; True(claim.SimultaneousCalls); Console.WriteLine("PASS Calls routes, simultaneous-call presence, evidence and validation"); } diff --git a/packages/dotnet/tests/Polymorfa.Sdk.Tests/Program.cs b/packages/dotnet/tests/Polymorfa.Sdk.Tests/Program.cs index 6b175d2aa..4cc707327 100644 --- a/packages/dotnet/tests/Polymorfa.Sdk.Tests/Program.cs +++ b/packages/dotnet/tests/Polymorfa.Sdk.Tests/Program.cs @@ -7,6 +7,8 @@ if (args.Contains("--simultaneous-calls-only")) { await CallsTests.RunAsync(); return; } +if (args.Contains("--bansafe-only")) { await BanSafeTests.RunAsync(); Console.WriteLine("PASS BanSafe routes and Ban Credit waiver claims"); return; } + if (args.Contains("--official-round2-only")) { await OfficialRound2Tests.RunAsync(); return; } OpaqueCredentialTests.Run(); diff --git a/packages/go/README.md b/packages/go/README.md index 7b672bd26..44251ecf8 100644 --- a/packages/go/README.md +++ b/packages/go/README.md @@ -805,6 +805,12 @@ when the 30-day claim window overlaps an enabled period. Claim verdicts and `bansafe.claim` webhook verdicts recognize `simultaneous_calls`. Claim evidence includes `simultaneousCalls`; the webhook does not acquire an evidence object. +Ban Credit claims also recognize `linked_device_interactive` (the Number sent +an interactive message from a linked device in the 30 days before the ban), on +claim reads and `bansafe.claim` webhooks. It opens `denied` with amount 0. +Claim evidence includes `linkedDeviceInteractive`; claims filed before it was +recorded report `false`. + No browser/client-token authority, call media behavior, automatic state read, retry policy or feature availability is added by these SDK fields. diff --git a/packages/go/ban_credit_waivers_test.go b/packages/go/ban_credit_waivers_test.go new file mode 100644 index 000000000..fb59fe1fb --- /dev/null +++ b/packages/go/ban_credit_waivers_test.go @@ -0,0 +1,39 @@ +package polymorfa + +import ( + "encoding/json" + "testing" +) + +func TestBanCreditWaiverVerdictsAndEvidence(t *testing.T) { + for _, tc := range []struct { + verdict string + evidence string + linked bool + }{ + {"linked_device_interactive", `{"attributionRuleVersion":3,"linkedDeviceInteractive":true}`, true}, + } { + var claim BanSafeClaim + if err := json.Unmarshal([]byte(`{"status":"denied","amountCents":0,"verdict":"`+tc.verdict+`","evidence":`+tc.evidence+`}`), &claim); err != nil { + t.Fatal(err) + } + if claim.Verdict != tc.verdict || claim.Evidence.AttributionRuleVersion == nil || *claim.Evidence.AttributionRuleVersion != 3 { + t.Fatalf("decoded %+v", claim) + } + if claim.Evidence.LinkedDeviceInteractive != tc.linked { + t.Fatalf("evidence %+v", claim.Evidence) + } + encoded, err := json.Marshal(claim.Evidence) + if err != nil { + t.Fatal(err) + } + var round map[string]any + if err := json.Unmarshal(encoded, &round); err != nil || round["linkedDeviceInteractive"] != tc.linked { + t.Fatalf("round trip %s", encoded) + } + var payload BanSafeClaimPayload + if err := json.Unmarshal([]byte(`{"verdict":"`+tc.verdict+`"}`), &payload); err != nil || payload.Verdict != tc.verdict { + t.Fatalf("webhook payload %+v %v", payload, err) + } + } +} diff --git a/packages/go/bansafe.go b/packages/go/bansafe.go index ce1e26556..d6ce56a9f 100644 --- a/packages/go/bansafe.go +++ b/packages/go/bansafe.go @@ -182,15 +182,16 @@ type BanSafeIncidentReceipt struct { OccurredAt string `json:"occurredAt"` } type BanSafeClaimEvidence struct { - SimultaneousCalls bool `json:"simultaneousCalls"` - AttributionRuleVersion *int `json:"attributionRuleVersion"` - WindowDays int `json:"windowDays"` - DeviceEvidence bool `json:"deviceEvidence"` - OtherDevices int `json:"otherDevices"` - RestrictedInWindow bool `json:"restrictedInWindow"` - CriticalFindingDays int `json:"criticalFindingDays"` - SharedConnection bool `json:"sharedConnection"` - MeasuredHours int `json:"measuredHours"` + SimultaneousCalls bool `json:"simultaneousCalls"` + LinkedDeviceInteractive bool `json:"linkedDeviceInteractive"` + AttributionRuleVersion *int `json:"attributionRuleVersion"` + WindowDays int `json:"windowDays"` + DeviceEvidence bool `json:"deviceEvidence"` + OtherDevices int `json:"otherDevices"` + RestrictedInWindow bool `json:"restrictedInWindow"` + CriticalFindingDays int `json:"criticalFindingDays"` + SharedConnection bool `json:"sharedConnection"` + MeasuredHours int `json:"measuredHours"` } type BanSafeClaim struct { ID string `json:"id"` diff --git a/packages/php/README.md b/packages/php/README.md index 126511d0f..11bb82149 100644 --- a/packages/php/README.md +++ b/packages/php/README.md @@ -960,6 +960,12 @@ when the 30-day claim window overlaps an enabled period. Claim verdicts and `bansafe.claim` webhook verdicts recognize `simultaneous_calls`. Claim evidence includes `simultaneousCalls`; the webhook does not acquire an evidence object. +Ban Credit claims also recognize `linked_device_interactive` (the Number sent +an interactive message from a linked device in the 30 days before the ban), on +claim reads and `bansafe.claim` webhooks. It opens `denied` with amount 0. +Claim evidence includes `linkedDeviceInteractive`; claims filed before it was +recorded report `false`. + No browser/client-token authority, call media behavior, automatic state read, retry policy or feature availability is added by these SDK fields. diff --git a/packages/php/src/BanSafeTelemetryModels.php b/packages/php/src/BanSafeTelemetryModels.php index e20320e48..b9e99e918 100644 --- a/packages/php/src/BanSafeTelemetryModels.php +++ b/packages/php/src/BanSafeTelemetryModels.php @@ -25,7 +25,7 @@ * @phpstan-type EnforcementSummary array{health:int|float|null,band:Band,healthSource:Source,healthEstimatorVersion:?string,healthModelVersion:?string,healthEvaluatedAt:?string,healthFeatureCoverage:int|float|null,healthReliability:Reliability,healthUnavailableReason:Unavailable|null,healthProbabilities:Probabilities|null,mostLikelyHealthState:HealthState|null,healthExplanation:Explanation|null,observedAccountState:Observed|null,sessionId:string,session:string,phoneNumber:string,projectId:string,rung:Rung,previousRung:Rung,teamFloor:Rung,reason:string,source:'automatic'|'operator',throughputPerMinute:int|float|null,blocksUnsolicited:bool,suspended:bool,enforcement?:Enforcement|null,blockingFindings:list,startedAt:string,eligibleLiftAt:?string,liftRequires:string,operatorHold:bool,appealState:Appeal,state:'applied'|'applying'} * @phpstan-type Incident array{id:string,sessionId:string,session:string,phoneNumber:string,projectId:string,kind:'cap_warning'|'cap_reached'|'timelock'|'temporary_ban'|'permanent_ban'|'connect_blocked'|'customer_report',source:'runtime'|'customer',resolution:string,ambiguous:bool,startedAt:string,endsAt:?string,closedAt:?string,closedBy:?string,claimId:?string,note:?string,reportedBy:?string,createdAt:string} * @phpstan-type ClaimStatus 'filed'|'under_review'|'approved'|'denied'|'paid'|'reversed' - * @phpstan-type Claim array{id:string,incidentId:string,sessionId:string,session:string,phoneNumber:string,projectId:string,status:ClaimStatus,verdict:'other_device'|'customer_conduct'|'shared_network'|'simultaneous_calls'|'ours'|'inconclusive',windowStart:string,windowEnd:string,measuredCents:int|float,capCents:int|float,amountCents:int|float,evidence:array{attributionRuleVersion:?int,windowDays:int,deviceEvidence:bool,otherDevices:int,restrictedInWindow:bool,criticalFindingDays:int,sharedConnection:bool,simultaneousCalls:bool,measuredHours:int|float},summary:string,reason:string,decidedAt:?string,paidAt:?string,createdAt:string} + * @phpstan-type Claim array{id:string,incidentId:string,sessionId:string,session:string,phoneNumber:string,projectId:string,status:ClaimStatus,verdict:'other_device'|'customer_conduct'|'shared_network'|'simultaneous_calls'|'linked_device_interactive'|'ours'|'inconclusive',windowStart:string,windowEnd:string,measuredCents:int|float,capCents:int|float,amountCents:int|float,evidence:array{attributionRuleVersion:?int,windowDays:int,deviceEvidence:bool,otherDevices:int,restrictedInWindow:bool,criticalFindingDays:int,sharedConnection:bool,simultaneousCalls:bool,linkedDeviceInteractive:bool,measuredHours:int|float},summary:string,reason:string,decidedAt:?string,paidAt:?string,createdAt:string} * @phpstan-type SignalDefinition array{key:string,label:string,group:string,kind:'number'|'boolean'|'enum'|'histogram'|'code_counts',unit:'count'|'milliseconds'|'unix_milliseconds'|'ratio'|'none',description:string} * @phpstan-type Signal array{key:string,label:string,group:string,kind:'number'|'boolean'|'enum'|'histogram'|'code_counts',unit:'count'|'milliseconds'|'unix_milliseconds'|'ratio'|'none',description:string,measured:bool,value:int|float|bool|string|list|null,sampleSize:?int,codes:list|null} * @phpstan-type CollectionStatus array{state:'fresh'|'stale'|'not_collected'|'unsupported',latestFlushedAt:?string,latestReceivedAt:?string,freshUntil:?string,recordVersion:?int,collectorVersion:?int,partial:?bool,droppedRecords:?int} diff --git a/packages/php/src/WebhookModels.php b/packages/php/src/WebhookModels.php index 26f0af295..b55c6281d 100644 --- a/packages/php/src/WebhookModels.php +++ b/packages/php/src/WebhookModels.php @@ -76,7 +76,7 @@ * @phpstan-type HealthThreshold array{sessionId:string,projectId:string,health:int|float,threshold:int|float,healthSource:'rules_v1'|'ml_model',estimatorVersion:string,modelVersion:?string,evaluatedAt:string,policyVersion:int|float,episodeId:string,actionId:string} * @phpstan-type BanSafeAction array{phoneNumber:string,action:'applied'|'changed'|'lifted'|'daily_allowance_reached',scope:'number'|'team',rung:Rung,previousRung:Rung|null,reason:'health'|'finding'|'team_pattern'|'repeat'|'restriction'|'operator'|'health_model_cutover'|'warmup',health:int|float|null,healthBand:'good'|'fair'|'poor'|'failing'|'unknown',requires:list,throughputPerMinute:int|float|null,eligibleLiftAt:?string,liftRequires:string,appealUrl:string,startedAt:string,docs:string} * @phpstan-type BanSafeIncident array{id:string,phoneNumber:string,kind:'cap_warning'|'cap_reached'|'timelock'|'temporary_ban'|'permanent_ban'|'connect_blocked'|'customer_report',source:'runtime'|'customer',startedAt:string,endsAt:?string,belief:int|float,resolution:'open'|'corroborated'|'contradicted'|'phone_switch'|'final',claimId:?string,closedAt:?string} - * @phpstan-type BanSafeClaim array{id:string,incidentId:string,phoneNumber:string,status:'filed'|'under_review'|'approved'|'denied'|'paid'|'reversed',verdict:'other_device'|'customer_conduct'|'shared_network'|'simultaneous_calls'|'ours'|'inconclusive',windowStart:string,windowEnd:string,measuredCents:int|float,capCents:int|float,amountCents:int|float,summary:string,reason:string,decidedAt:?string,paidAt:?string} + * @phpstan-type BanSafeClaim array{id:string,incidentId:string,phoneNumber:string,status:'filed'|'under_review'|'approved'|'denied'|'paid'|'reversed',verdict:'other_device'|'customer_conduct'|'shared_network'|'simultaneous_calls'|'linked_device_interactive'|'ours'|'inconclusive',windowStart:string,windowEnd:string,measuredCents:int|float,capCents:int|float,amountCents:int|float,summary:string,reason:string,decidedAt:?string,paidAt:?string} * @phpstan-type PaymentStatus array{reportedBy:'whatsapp',providerEventId:string,referenceId:string,conversation:array{id?:string,phoneNumber?:string,bsuid?:string,parentBsuid?:string},kind:'payment_status',status:string,amount?:array{value:int|float,offset:int|float},currency?:string,transaction?:array{id?:string,providerTransactionId?:string,provider?:string,status?:string,method?:string,errorCode?:string}} * @phpstan-type PaymentMethod array{reportedBy:'whatsapp',providerEventId:string,referenceId:string,conversation:array{id?:string,phoneNumber?:string,bsuid?:string,parentBsuid?:string},kind:'payment_method_selected',messageId:string,paymentMethod:string,lastFourDigits?:string,credentialId?:string,paymentTimestamp?:int|float} * @phpstan-type RuntimeTemplate array{templateName:string,templateId:string,status:string,category:string,reason:string,qualityRating:string} diff --git a/packages/php/tests/platform_bansafe.php b/packages/php/tests/platform_bansafe.php index 8b71c696b..83aa7b5c3 100644 --- a/packages/php/tests/platform_bansafe.php +++ b/packages/php/tests/platform_bansafe.php @@ -13,6 +13,7 @@ $enforcement = $health + ['sessionId' => 'sid','session' => 'session','phoneNumber' => '+15555555555','projectId' => 'project','rung' => 'notify','previousRung' => 'none','teamFloor' => 'none','reason' => 'Fixture','source' => 'operator','throughputPerMinute' => null,'blocksUnsolicited' => false,'suspended' => false,'blockingFindings' => [],'startedAt' => 'now','eligibleLiftAt' => null,'liftRequires' => 'Review','operatorHold' => true,'appealState' => 'requested','state' => 'applying']; $incident = ['id' => 'incident','sessionId' => 'sid','session' => 'session','phoneNumber' => '+15555555555','projectId' => 'project','kind' => 'customer_report','source' => 'customer','resolution' => 'unresolved','ambiguous' => true,'startedAt' => 'now','endsAt' => null,'closedAt' => null,'closedBy' => null,'claimId' => null,'note' => 'Fixture','reportedBy' => 'customer','createdAt' => 'now']; $claim = ['id' => 'claim','incidentId' => 'incident','sessionId' => 'sid','session' => 'session','phoneNumber' => '+15555555555','projectId' => 'project','status' => 'under_review','verdict' => 'inconclusive','windowStart' => 'now','windowEnd' => 'now','measuredCents' => 0.000001,'capCents' => 12.345678,'amountCents' => 0.125,'evidence' => ['attributionRuleVersion' => 1,'windowDays' => 7,'deviceEvidence' => false,'otherDevices' => 0,'restrictedInWindow' => true,'criticalFindingDays' => 2,'sharedConnection' => false,'measuredHours' => 1.5],'summary' => 'Fixture','reason' => 'Evidence pending','decidedAt' => null,'paidAt' => null,'createdAt' => 'now']; +$waived = array_replace($claim, ['status' => 'denied','verdict' => 'linked_device_interactive','amountCents' => 0,'evidence' => ['attributionRuleVersion' => 3,'windowDays' => 30,'deviceEvidence' => false,'otherDevices' => 0,'restrictedInWindow' => false,'criticalFindingDays' => 0,'sharedConnection' => false,'simultaneousCalls' => false,'linkedDeviceInteractive' => true,'measuredHours' => 0]]); $page = fn ($data) => ['data' => [$data],'page' => ['nextCursor' => null,'hasMore' => false]]; $envelope = fn ($data) => ['data' => $data]; $created = ['incidentId' => 'incident','created' => true,'sessionId' => 'sid','session' => 'session','occurredAt' => 'now']; @@ -32,6 +33,7 @@ ['POST','/platform/bansafe/incidents/incident/retract',null,$envelope($incident),fn ($c) => $c->banSafe->retractIncident('incident')], ['GET','/platform/bansafe/claims?status=under_review',null,$page($claim),fn ($c) => $c->banSafe->listClaims(['status' => 'under_review'])], ['GET','/platform/bansafe/claims/claim',null,$envelope($claim),fn ($c) => $c->banSafe->getClaim('claim')], + ['GET','/platform/bansafe/claims/waived',null,$envelope($waived),fn ($c) => $c->banSafe->getClaim('waived')], ], fn ($credential, $url) => new Polymorfa\Client($credential, baseUrl:$url)); check($number['health'] === null && $number['band'] === 'unknown', 'Unavailable health remains distinct from a healthy score'); check($claim['measuredCents'] === 0.000001 && $claim['amountCents'] === 0.125, 'BanSafe fractional credits retained'); diff --git a/packages/python/README.md b/packages/python/README.md index 340122497..28d9e03ab 100644 --- a/packages/python/README.md +++ b/packages/python/README.md @@ -827,6 +827,12 @@ when the 30-day claim window overlaps an enabled period. Claim verdicts and `bansafe.claim` webhook verdicts recognize `simultaneous_calls`. Claim evidence includes `simultaneousCalls`; the webhook does not acquire an evidence object. +Ban Credit claims also recognize `linked_device_interactive` (the Number sent +an interactive message from a linked device in the 30 days before the ban), on +claim reads and `bansafe.claim` webhooks. It opens `denied` with amount 0. +Claim evidence includes `linkedDeviceInteractive`; claims filed before it was +recorded report `false`. + No browser/client-token authority, call media behavior, automatic state read, retry policy or feature availability is added by these SDK fields. diff --git a/packages/python/src/polymorfa/bansafe_observations.py b/packages/python/src/polymorfa/bansafe_observations.py index c77b1b060..106093685 100644 --- a/packages/python/src/polymorfa/bansafe_observations.py +++ b/packages/python/src/polymorfa/bansafe_observations.py @@ -37,6 +37,7 @@ "customer_conduct", "shared_network", "simultaneous_calls", + "linked_device_interactive", "ours", "inconclusive", ] @@ -252,6 +253,7 @@ class IncidentReceipt(TypedDict): class ClaimEvidence(TypedDict): simultaneousCalls: bool + linkedDeviceInteractive: bool attributionRuleVersion: int | None windowDays: int deviceEvidence: bool diff --git a/packages/python/src/polymorfa/webhook_models.py b/packages/python/src/polymorfa/webhook_models.py index 2b19ece01..8723722ad 100644 --- a/packages/python/src/polymorfa/webhook_models.py +++ b/packages/python/src/polymorfa/webhook_models.py @@ -750,6 +750,7 @@ class BanSafeClaimPayload(TypedDict): "customer_conduct", "shared_network", "simultaneous_calls", + "linked_device_interactive", "ours", "inconclusive", ] diff --git a/packages/python/tests/test_ban_credit_waivers.py b/packages/python/tests/test_ban_credit_waivers.py new file mode 100644 index 000000000..a1ec5217e --- /dev/null +++ b/packages/python/tests/test_ban_credit_waivers.py @@ -0,0 +1,19 @@ +from typing import get_args, get_type_hints + +from polymorfa.bansafe_observations import Claim, ClaimEvidence, ClaimVerdict +from polymorfa.webhook_models import BanSafeClaimPayload + +WAIVERS = ("linked_device_interactive",) + + +def test_claim_verdicts_include_the_ban_credit_waivers() -> None: + for verdict in WAIVERS: + assert verdict in get_args(ClaimVerdict) + assert verdict in get_args(get_type_hints(BanSafeClaimPayload)["verdict"]) + assert get_type_hints(Claim)["verdict"] == ClaimVerdict + + +def test_claim_evidence_types_the_waiver_flags() -> None: + hints = get_type_hints(ClaimEvidence) + assert hints["linkedDeviceInteractive"] is bool + assert {"linkedDeviceInteractive"} <= ClaimEvidence.__required_keys__ diff --git a/packages/python/tests/test_bansafe_observations.py b/packages/python/tests/test_bansafe_observations.py index 84b3744e1..0f967f038 100644 --- a/packages/python/tests/test_bansafe_observations.py +++ b/packages/python/tests/test_bansafe_observations.py @@ -157,6 +157,7 @@ "criticalFindingDays": 1, "sharedConnection": False, "simultaneousCalls": False, + "linkedDeviceInteractive": False, "measuredHours": 100, }, "summary": "Review", diff --git a/packages/rust/README.md b/packages/rust/README.md index dd840cfee..6a1a0bbf0 100644 --- a/packages/rust/README.md +++ b/packages/rust/README.md @@ -894,6 +894,12 @@ when the 30-day claim window overlaps an enabled period. Claim verdicts and `bansafe.claim` webhook verdicts recognize `simultaneous_calls`. Claim evidence includes `simultaneousCalls`; the webhook does not acquire an evidence object. +Ban Credit claims also recognize `linked_device_interactive` (the Number sent +an interactive message from a linked device in the 30 days before the ban), on +claim reads and `bansafe.claim` webhooks. It opens `denied` with amount 0. +Claim evidence includes `linkedDeviceInteractive`; claims filed before it was +recorded report `false`. + No browser/client-token authority, call media behavior, automatic state read, retry policy or feature availability is added by these SDK fields. diff --git a/packages/rust/src/bansafe.rs b/packages/rust/src/bansafe.rs index 9ef2b679d..29d56c5b4 100644 --- a/packages/rust/src/bansafe.rs +++ b/packages/rust/src/bansafe.rs @@ -28,7 +28,7 @@ enumeration!(ResolveReason {Clean=>"clean",KeyRetired=>"key_retired",NumberRemov enumeration!(IncidentKind {CapWarning=>"cap_warning",CapReached=>"cap_reached",Timelock=>"timelock",TemporaryBan=>"temporary_ban",PermanentBan=>"permanent_ban",ConnectBlocked=>"connect_blocked",CustomerReport=>"customer_report"}); enumeration!(IncidentSource {Runtime=>"runtime",Customer=>"customer"}); enumeration!(ClaimStatus {Filed=>"filed",UnderReview=>"under_review",Approved=>"approved",Denied=>"denied",Paid=>"paid",Reversed=>"reversed"}); -enumeration!(ClaimVerdict {OtherDevice=>"other_device",CustomerConduct=>"customer_conduct",SharedNetwork=>"shared_network",SimultaneousCalls=>"simultaneous_calls",Ours=>"ours",Inconclusive=>"inconclusive"}); +enumeration!(ClaimVerdict {OtherDevice=>"other_device",CustomerConduct=>"customer_conduct",SharedNetwork=>"shared_network",SimultaneousCalls=>"simultaneous_calls",LinkedDeviceInteractive=>"linked_device_interactive",Ours=>"ours",Inconclusive=>"inconclusive"}); enumeration!(SignalKind {Number=>"number",Boolean=>"boolean",Enum=>"enum",Histogram=>"histogram",CodeCounts=>"code_counts"}); enumeration!(SignalUnit {Count=>"count",Milliseconds=>"milliseconds",UnixMilliseconds=>"unix_milliseconds",Ratio=>"ratio",None=>"none"}); enumeration!(CollectionState {Fresh=>"fresh",Stale=>"stale",NotCollected=>"not_collected",Unsupported=>"unsupported"}); @@ -134,7 +134,7 @@ model!(IncidentReceipt { session: String, occurred_at: String }); -model!(ClaimEvidence {attribution_rule_version:Option,window_days:u32,device_evidence:bool,other_devices:u32,restricted_in_window:bool,critical_finding_days:u32,shared_connection:bool,simultaneous_calls:bool,measured_hours:u32}); +model!(ClaimEvidence {attribution_rule_version:Option,window_days:u32,device_evidence:bool,other_devices:u32,restricted_in_window:bool,critical_finding_days:u32,shared_connection:bool,simultaneous_calls:bool,linked_device_interactive:bool,measured_hours:u32}); model!(Claim {id:String,incident_id:String,session_id:String,session:String,phone_number:String,project_id:String,status:ClaimStatus,verdict:ClaimVerdict,window_start:String,window_end:String,measured_cents:f64,cap_cents:f64,amount_cents:f64,evidence:ClaimEvidence,summary:String,reason:String,decided_at:Option,paid_at:Option,created_at:String}); model!(SignalDefinition { key: String, diff --git a/packages/rust/src/webhook_payloads.rs b/packages/rust/src/webhook_payloads.rs index 531e07b23..1a46553d0 100644 --- a/packages/rust/src/webhook_payloads.rs +++ b/packages/rust/src/webhook_payloads.rs @@ -1136,6 +1136,7 @@ pub enum BanSafeClaimStatus { #[serde(rename_all = "snake_case")] pub enum BanSafeClaimVerdict { SimultaneousCalls, + LinkedDeviceInteractive, OtherDevice, CustomerConduct, SharedNetwork, diff --git a/packages/rust/tests/ban_credit_waivers.rs b/packages/rust/tests/ban_credit_waivers.rs new file mode 100644 index 000000000..d1bd83ae4 --- /dev/null +++ b/packages/rust/tests/ban_credit_waivers.rs @@ -0,0 +1,23 @@ +use serde_json::json; + +#[test] +fn ban_credit_waiver_verdicts_and_evidence_round_trip() { + { + let (value, verdict) = ( + "linked_device_interactive", + polymorfa_sdk::bansafe::ClaimVerdict::LinkedDeviceInteractive, + ); + let decoded: polymorfa_sdk::bansafe::ClaimVerdict = + serde_json::from_value(json!(value)).unwrap(); + assert_eq!(decoded, verdict); + assert_eq!(serde_json::to_value(decoded).unwrap(), json!(value)); + let webhook: polymorfa_sdk::webhook_payloads::BanSafeClaimVerdict = + serde_json::from_value(json!(value)).unwrap(); + assert_eq!(serde_json::to_value(webhook).unwrap(), json!(value)); + } + let evidence: polymorfa_sdk::bansafe::ClaimEvidence = serde_json::from_value(json!({"attributionRuleVersion":3,"windowDays":30,"deviceEvidence":false,"otherDevices":0,"restrictedInWindow":false,"criticalFindingDays":0,"sharedConnection":false,"simultaneousCalls":false,"linkedDeviceInteractive":true,"measuredHours":0})).unwrap(); + assert_eq!(evidence.attribution_rule_version, Some(3)); + assert!(evidence.linked_device_interactive); + let encoded = serde_json::to_value(&evidence).unwrap(); + assert_eq!(encoded["linkedDeviceInteractive"], json!(true)); +} diff --git a/packages/rust/tests/bansafe.rs b/packages/rust/tests/bansafe.rs index a3b72ef7d..bab4f34f0 100644 --- a/packages/rust/tests/bansafe.rs +++ b/packages/rust/tests/bansafe.rs @@ -20,7 +20,7 @@ fn incident() -> Value { json!({"id":"incident","sessionId":"sid","session":"support","phoneNumber":"+1555","projectId":"project","kind":"customer_report","source":"customer","resolution":"open","ambiguous":true,"startedAt":"now","endsAt":null,"closedAt":null,"closedBy":null,"claimId":"claim","note":"reported","reportedBy":"member","createdAt":"now"}) } fn claim() -> Value { - json!({"id":"claim","incidentId":"incident","sessionId":"sid","session":"support","phoneNumber":"+1555","projectId":"project","status":"under_review","verdict":"inconclusive","windowStart":"then","windowEnd":"now","measuredCents":2.123456,"capCents":3.0,"amountCents":0.0,"evidence":{"attributionRuleVersion":1,"windowDays":7,"deviceEvidence":true,"otherDevices":2,"restrictedInWindow":true,"criticalFindingDays":1,"sharedConnection":false,"simultaneousCalls":false,"measuredHours":100},"summary":"Review","reason":"evidence","decidedAt":null,"paidAt":null,"createdAt":"now"}) + json!({"id":"claim","incidentId":"incident","sessionId":"sid","session":"support","phoneNumber":"+1555","projectId":"project","status":"under_review","verdict":"inconclusive","windowStart":"then","windowEnd":"now","measuredCents":2.123456,"capCents":3.0,"amountCents":0.0,"evidence":{"attributionRuleVersion":1,"windowDays":7,"deviceEvidence":true,"otherDevices":2,"restrictedInWindow":true,"criticalFindingDays":1,"sharedConnection":false,"simultaneousCalls":false,"linkedDeviceInteractive":false,"measuredHours":100},"summary":"Review","reason":"evidence","decidedAt":null,"paidAt":null,"createdAt":"now"}) } fn signal() -> Value { json!({"key":"delivery","label":"Delivery","group":"delivery","kind":"code_counts","unit":"count","description":"Codes","measured":true,"value":[1.0,2.0],"sampleSize":2,"codes":[{"code":429,"count":2}]}) diff --git a/packages/rust/tests/voip.rs b/packages/rust/tests/voip.rs index c2b27e24a..5aadda8d5 100644 --- a/packages/rust/tests/voip.rs +++ b/packages/rust/tests/voip.rs @@ -342,7 +342,7 @@ fn simultaneous_claim_verdicts_and_evidence() { serde_json::to_value(webhook).unwrap(), json!("simultaneous_calls") ); - let evidence: polymorfa_sdk::bansafe::ClaimEvidence = serde_json::from_value(json!({"attributionRuleVersion":null,"windowDays":30,"deviceEvidence":false,"otherDevices":0,"restrictedInWindow":false,"criticalFindingDays":0,"sharedConnection":false,"simultaneousCalls":true,"measuredHours":0})).unwrap(); + let evidence: polymorfa_sdk::bansafe::ClaimEvidence = serde_json::from_value(json!({"attributionRuleVersion":null,"windowDays":30,"deviceEvidence":false,"otherDevices":0,"restrictedInWindow":false,"criticalFindingDays":0,"sharedConnection":false,"simultaneousCalls":true,"linkedDeviceInteractive":false,"measuredHours":0})).unwrap(); assert!(evidence.simultaneous_calls); } diff --git a/packages/typescript/README.md b/packages/typescript/README.md index 2ed09b0eb..0eb2ac018 100644 --- a/packages/typescript/README.md +++ b/packages/typescript/README.md @@ -318,7 +318,11 @@ Claim `measuredCents`, `capCents`, and `amountCents` are credit quantities with up to six decimal places, not integer cents. A claim with verdict `simultaneous_calls` opens `denied` with amount 0 because simultaneous calls were on for the number during the 30 days before the ban; -`evidence.simultaneousCalls` reports that state for every claim. Finding acknowledgement and +`evidence.simultaneousCalls` reports that state for every claim. The verdict +`linked_device_interactive` (an interactive message sent from a linked device) +also opens `denied` with amount 0 when the send falls in that window; +`evidence.linkedDeviceInteractive` reports it, and is `false` on claims filed +before it was recorded. Finding acknowledgement and enforcement appeals require a signed-in dashboard session and are not SDK methods. diff --git a/packages/typescript/src/platform/types.ts b/packages/typescript/src/platform/types.ts index 58d5ea67c..40261c5a2 100644 --- a/packages/typescript/src/platform/types.ts +++ b/packages/typescript/src/platform/types.ts @@ -1267,7 +1267,13 @@ export type BanSafeClaimVerdict = * Simultaneous calls were on for the number during the 30 days before the * ban. The claim opens `denied` with amount 0 and cannot be approved. */ - | "simultaneous_calls"; + | "simultaneous_calls" + /** + * The number sent an interactive message from a linked device during the 30 + * days before the ban. Ban Credit does not cover it: the claim opens `denied` + * with amount 0 and cannot be approved. + */ + | "linked_device_interactive"; export interface BanSafeClaimEvidence { readonly attributionRuleVersion: number | null; @@ -1284,6 +1290,13 @@ export interface BanSafeClaimEvidence { * when filed. */ readonly simultaneousCalls: boolean; + /** + * Whether this number sent an interactive message (buttons, lists, product + * messages, Flows and similar) from a linked device inside the window. When + * `true`, Ban Credit does not cover the ban and the claim is denied when + * filed. `false` for claims filed before this was recorded. + */ + readonly linkedDeviceInteractive: boolean; } export interface BanSafeClaim { diff --git a/packages/typescript/src/webhooks/events.ts b/packages/typescript/src/webhooks/events.ts index 228b4daa6..f5cbfb5d3 100644 --- a/packages/typescript/src/webhooks/events.ts +++ b/packages/typescript/src/webhooks/events.ts @@ -944,7 +944,9 @@ export interface BanSafeClaimPayload { | "ours" | "inconclusive" /** Simultaneous calls voided Ban Insurance; the claim is denied when filed. */ - | "simultaneous_calls"; + | "simultaneous_calls" + /** An interactive message sent from a linked device voided Ban Credit; the claim is denied when filed. */ + | "linked_device_interactive"; readonly windowStart: string; readonly windowEnd: string; /** Decimal cent amounts with up to six fractional digits. */ diff --git a/packages/typescript/test/ban-credit-waivers-contract.test.ts b/packages/typescript/test/ban-credit-waivers-contract.test.ts new file mode 100644 index 000000000..b194d8db5 --- /dev/null +++ b/packages/typescript/test/ban-credit-waivers-contract.test.ts @@ -0,0 +1,83 @@ +import { readFileSync } from "node:fs"; +import { fileURLToPath } from "node:url"; +import { describe, expect, expectTypeOf, it } from "vitest"; + +import type { + BanSafeClaim, + BanSafeClaimEvidence, + BanSafeClaimPayload, + BanSafeClaimVerdict, + WebhookPayloadMap, +} from "../src/index.js"; + +interface Supplement { + readonly sourceCommit: string; + readonly verdicts: Readonly< + Record< + "BanSafeClaim" | "BanSafeClaimPayload", + { readonly enum: readonly string[] } + > + >; + readonly evidence: { + readonly BanSafeClaimEvidence: { + readonly required: readonly string[]; + readonly properties: Readonly>; + }; + }; +} + +// Pinned to the API source revision that adds the Ban Credit waiver. +const supplement = JSON.parse( + readFileSync( + fileURLToPath( + new URL("../../../contracts/ban-credit-waivers.json", import.meta.url), + ), + "utf8", + ), +) as Supplement; + +// Exhaustive maps: adding or removing a verdict in the SDK types without +// updating these fails the typecheck, and the tests compare them to the API. +const CLAIM_VERDICTS: Record = { + other_device: true, + customer_conduct: true, + shared_network: true, + ours: true, + inconclusive: true, + simultaneous_calls: true, + linked_device_interactive: true, +}; +const PAYLOAD_VERDICTS: Record = { + ...CLAIM_VERDICTS, +}; + +describe("Ban Credit waiver claim contract", () => { + it("types every claim verdict the API returns", () => { + expect(Object.keys(CLAIM_VERDICTS).sort()).toEqual( + [...supplement.verdicts.BanSafeClaim.enum].sort(), + ); + expect(Object.keys(PAYLOAD_VERDICTS).sort()).toEqual( + [...supplement.verdicts.BanSafeClaimPayload.enum].sort(), + ); + }); + + it("uses one verdict type for claim reads and the bansafe.claim webhook", () => { + expectTypeOf< + BanSafeClaim["verdict"] + >().toEqualTypeOf(); + expectTypeOf< + WebhookPayloadMap["bansafe.claim"]["verdict"] + >().toEqualTypeOf(); + }); + + it("types the waiver evidence flags as required booleans", () => { + const evidence = supplement.evidence.BanSafeClaimEvidence; + for (const field of ["linkedDeviceInteractive"]) { + expect(evidence.required).toContain(field); + expect(evidence.properties[field]?.type).toBe("boolean"); + } + expectTypeOf< + BanSafeClaimEvidence["linkedDeviceInteractive"] + >().toEqualTypeOf(); + }); +}); diff --git a/packages/typescript/test/calls-simultaneous-calls-contract.test.ts b/packages/typescript/test/calls-simultaneous-calls-contract.test.ts index 908fc0301..98bcf08dd 100644 --- a/packages/typescript/test/calls-simultaneous-calls-contract.test.ts +++ b/packages/typescript/test/calls-simultaneous-calls-contract.test.ts @@ -43,8 +43,13 @@ const platform = contract.sources.platform.schemas; const keys = (schema: Schema | undefined) => Object.keys(schema?.properties ?? {}).sort(); -// Every verdict must appear here; a missing or extra key fails to compile. -const VERDICTS: Record = { +// Every verdict at this supplement's API revision must appear here; a missing +// or extra key fails to compile. Verdicts added later are pinned by their own +// supplement (ban-credit-waivers.json). +const VERDICTS: Record< + Exclude, + true +> = { other_device: true, customer_conduct: true, shared_network: true, diff --git a/scripts/doc-snippets/recipes.mjs b/scripts/doc-snippets/recipes.mjs index 37f240bd2..d227bdcef 100644 --- a/scripts/doc-snippets/recipes.mjs +++ b/scripts/doc-snippets/recipes.mjs @@ -1,7 +1,7 @@ // Requests come from the pinned OpenAPI and existing native wire fixtures. // Calls are handwritten in the language modules. Never derive arguments from // contracts/coverage.json's display-only method names. -export const sourceCommit = "1e6fd9952e8183497a28f43c3987d960d9bf52eb"; +export const sourceCommit = "f8a64f81955e87f7a3ff64c3f15061a1e967bd0c"; export const apiVersion = "2026-09-22"; export const languages = [ "typescript",