diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e770659e2..ab5670ff0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -41,6 +41,7 @@ jobs: - run: npm run check:machine-credentials - run: npm run check:coverage - run: node scripts/check-native-coverage.mjs + - run: npm run check:newsletter-observations - run: npm run check:functions - run: npm run check:names - run: npm pack --dry-run --workspaces --ignore-scripts diff --git a/contracts/coverage.json b/contracts/coverage.json index 07b4c49d7..81644e8ea 100644 --- a/contracts/coverage.json +++ b/contracts/coverage.json @@ -21913,6 +21913,12 @@ "baselineUnchanged": true, "published": false }, + "newsletterObservations": { + "inventory": "contracts/newsletter-observations.json", + "baselineUnchanged": true, + "published": false, + "wireEvidence": "POL-81 native fixtures: newsletter observations and optional channel forwards" + }, "interactiveMessages": { "inventory": "contracts/native-interactive-messages.json", "language": "typescript", diff --git a/contracts/doc-snippets.json b/contracts/doc-snippets.json index eb78bf338..625e3b402 100644 --- a/contracts/doc-snippets.json +++ b/contracts/doc-snippets.json @@ -1,7 +1,7 @@ { "schemaVersion": 1, - "sourceCommit": "4b6ce43985ab6e3d6b0427858da5792c06dbb520", - "sourceFilesSha256": "3efbdccb5efd4cf7ed8165b5eb25a37bd79a53a7860196250f8c3d36bbc4a282", + "sourceCommit": "47b1e92af97f13b86b2e86fde49a4d244412c632", + "sourceFilesSha256": "b5c30459bb3354b97dd6c2220f31ef17f608584de8b86c889c3f3e290476a4f2", "apiVersion": "2026-09-22", "apiSourceCommit": "f180dc1ee2bd45dbecf01702f73bdd75c664634b", "specs": { diff --git a/contracts/fixtures/newsletter-observations/channel-message.json b/contracts/fixtures/newsletter-observations/channel-message.json new file mode 100644 index 000000000..1595b387b --- /dev/null +++ b/contracts/fixtures/newsletter-observations/channel-message.json @@ -0,0 +1,16 @@ +{ + "position": 123, + "id": "9007199254740994", + "whatsapp_ids": { + "linked_devices": "native-observed" + }, + "whatsapp_id": "native-observed", + "conversation": { + "id": "9007199254740993" + }, + "type": "text", + "timestamp": "2023-11-14T22:13:21Z", + "views": 11, + "forwards": 0, + "reactionCounts": {} +} diff --git a/contracts/fixtures/newsletter-observations/delivery.json b/contracts/fixtures/newsletter-observations/delivery.json new file mode 100644 index 000000000..d66cd0431 --- /dev/null +++ b/contracts/fixtures/newsletter-observations/delivery.json @@ -0,0 +1,84 @@ +{ + "secret": "synthetic-newsletter-secret", + "batchId": "0198a2cb-0000-7000-8000-000000000081", + "events": [ + { + "id": "newsletter-event-0", + "session": "channel-number", + "timestamp": "2026-10-27T00:00:00.000Z", + "event": "newsletter.update", + "payload": { + "id": "9007199254740993", + "action": "live_update", + "sourceTimestamp": "2023-11-14T22:13:20Z", + "messages": [ + { + "position": 123, + "message": { + "id": "9007199254740994", + "whatsapp_ids": { + "linked_devices": "native-observed" + } + }, + "timestamp": "2023-11-14T22:13:21Z", + "viewCounts": [ + { + "count": 0 + }, + { + "type": "views", + "count": 11 + } + ], + "forwards": 0, + "reactionCounts": {} + }, + { + "position": 124 + } + ] + } + }, + { + "id": "newsletter-event-1", + "session": "channel-number", + "timestamp": "2026-10-27T00:00:00.000Z", + "event": "newsletter.update", + "payload": { + "id": "9007199254740993", + "action": "milestone", + "milestone": { + "position": 123, + "type": "FUTURE_MILESTONE", + "value": 0, + "reactionCode": "👍" + } + } + }, + { + "id": "legacy-mute", + "session": "channel-number", + "timestamp": "2026-10-27T00:00:00.000Z", + "event": "newsletter.update", + "payload": { + "id": "9007199254740993", + "action": "mute", + "muted": false + } + }, + { + "id": "newsletter-event-channel-milestone", + "session": "channel-number", + "timestamp": "2026-10-27T00:00:00.000Z", + "event": "newsletter.update", + "payload": { + "id": "9007199254740993", + "action": "milestone", + "milestone": { + "type": "FOLLOWS", + "value": 1000 + } + } + } + ] +} diff --git a/contracts/fixtures/newsletter-observations/live-update.json b/contracts/fixtures/newsletter-observations/live-update.json new file mode 100644 index 000000000..397d2debf --- /dev/null +++ b/contracts/fixtures/newsletter-observations/live-update.json @@ -0,0 +1,31 @@ +{ + "id": "9007199254740993", + "action": "live_update", + "sourceTimestamp": "2023-11-14T22:13:20Z", + "messages": [ + { + "position": 123, + "message": { + "id": "9007199254740994", + "whatsapp_ids": { + "linked_devices": "native-observed" + } + }, + "timestamp": "2023-11-14T22:13:21Z", + "viewCounts": [ + { + "count": 0 + }, + { + "type": "views", + "count": 11 + } + ], + "forwards": 0, + "reactionCounts": {} + }, + { + "position": 124 + } + ] +} diff --git a/contracts/fixtures/newsletter-observations/milestone-channel.json b/contracts/fixtures/newsletter-observations/milestone-channel.json new file mode 100644 index 000000000..639867e61 --- /dev/null +++ b/contracts/fixtures/newsletter-observations/milestone-channel.json @@ -0,0 +1,8 @@ +{ + "id": "9007199254740993", + "action": "milestone", + "milestone": { + "type": "FOLLOWS", + "value": 1000 + } +} diff --git a/contracts/fixtures/newsletter-observations/milestone.json b/contracts/fixtures/newsletter-observations/milestone.json new file mode 100644 index 000000000..85f0841e1 --- /dev/null +++ b/contracts/fixtures/newsletter-observations/milestone.json @@ -0,0 +1,10 @@ +{ + "id": "9007199254740993", + "action": "milestone", + "milestone": { + "position": 123, + "type": "FUTURE_MILESTONE", + "value": 0, + "reactionCode": "\ud83d\udc4d" + } +} diff --git a/contracts/newsletter-observations.json b/contracts/newsletter-observations.json new file mode 100644 index 000000000..c8d0fbdfa --- /dev/null +++ b/contracts/newsletter-observations.json @@ -0,0 +1,312 @@ +{ + "repository": "polymorfa/polymorfa", + "sourceCommit": "e292c7dc3f3a52c1c9f732af46af775437a2ecf9", + "sourcePath": "apps/api/docs/openapi.json", + "sourceSha256": "c1e81be3deb9d83e5467e4f4d128d58c67e88ca483fea650f9b9d139e5555ac8", + "polymorfaVersion": "2026-09-22", + "published": false, + "scope": "POL-81 newsletter.update metadata and optional ChannelMessage.forwards; baseline snapshots unchanged", + "components": { + "schemas": { + "NewsletterUpdatePayload": { + "type": "object", + "properties": { + "id": { + "type": "string", + "pattern": "^[1-9][0-9]{0,18}$", + "description": "Stable channel ID.", + "example": "739182640518203" + }, + "action": { + "type": "string", + "description": "Action, including join, leave, mute, unmute, live_update or milestone." + }, + "muted": { + "type": "boolean" + }, + "sourceTimestamp": { + "type": "string", + "format": "date-time", + "description": "Source notification time, when reported. The event envelope timestamp remains the publication time." + }, + "messages": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NewsletterMessageObservation" + }, + "maxItems": 300 + }, + "milestone": { + "$ref": "#/components/schemas/NewsletterMilestone" + } + }, + "required": ["id", "action"] + }, + "NewsletterMessageObservation": { + "type": "object", + "properties": { + "position": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991, + "exclusiveMinimum": true, + "description": "Channel ordering position. This is not an original WhatsApp message ID." + }, + "message": { + "type": "object", + "properties": { + "id": { + "type": "string", + "pattern": "^[1-9][0-9]{0,18}$", + "description": "Opaque Polymorfa resource ID. Keep this value as a string.", + "example": "739182640518203" + }, + "whatsapp_ids": { + "$ref": "#/components/schemas/WhatsAppMessageIds" + } + }, + "required": ["id", "whatsapp_ids"], + "description": "Reference present only when WhatsApp supplied an original message ID. A partial reference alone does not authorize message actions." + }, + "timestamp": { + "type": "string", + "format": "date-time" + }, + "viewCounts": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NewsletterViewCount" + }, + "maxItems": 2, + "description": "Reported view definitions, including typed and untyped values when both are present. No account-specific definition is inferred." + }, + "forwards": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "reactionCounts": { + "type": "object", + "additionalProperties": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "maxProperties": 1000 + } + }, + "required": ["position"] + }, + "NewsletterViewCount": { + "type": "object", + "properties": { + "type": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "count": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + } + }, + "required": ["count"] + }, + "NewsletterMilestone": { + "type": "object", + "properties": { + "position": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991, + "exclusiveMinimum": true, + "description": "Channel position of the related post. Absent for channel-level milestones such as follower counts." + }, + "type": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "value": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "reactionCode": { + "type": "string", + "minLength": 1, + "maxLength": 128 + } + }, + "required": ["type", "value"] + }, + "ChannelMessage": { + "type": "object", + "properties": { + "position": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true, + "maximum": 9007199254740991, + "description": "Channel ordering position. Use this value for before and after pagination cursors, not as a message ID." + }, + "id": { + "type": "string", + "pattern": "^[1-9][0-9]{0,18}$", + "description": "Opaque Polymorfa resource ID. Keep this value as a string.", + "example": "739182640518203" + }, + "whatsapp_ids": { + "$ref": "#/components/schemas/WhatsAppMessageIds" + }, + "whatsapp_id": { + "type": "string", + "minLength": 1, + "maxLength": 512, + "description": "Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.", + "deprecated": true + }, + "conversation": { + "$ref": "#/components/schemas/ConversationIdentity" + }, + "type": { + "type": "string" + }, + "timestamp": { + "type": "string", + "format": "date-time" + }, + "views": { + "type": "integer", + "minimum": 0 + }, + "forwards": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991, + "description": "Reported forward count. Missing means not reported; zero remains present." + }, + "reactionCounts": { + "type": "object", + "additionalProperties": { + "type": "integer", + "minimum": 0 + } + }, + "text": { + "type": "string" + } + }, + "required": [ + "position", + "id", + "whatsapp_ids", + "conversation", + "type", + "timestamp", + "views", + "reactionCounts" + ] + }, + "WhatsAppMessageIds": { + "anyOf": [ + { + "type": "object", + "properties": { + "linked_devices": { + "type": "string", + "minLength": 1, + "maxLength": 512 + }, + "official_api": { + "type": "string", + "minLength": 1, + "maxLength": 512 + } + }, + "required": ["linked_devices"], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "linked_devices": { + "type": "string", + "minLength": 1, + "maxLength": 512 + }, + "official_api": { + "type": "string", + "minLength": 1, + "maxLength": 512 + } + }, + "required": ["official_api"], + "additionalProperties": false + } + ], + "description": "Exact message references observed through Linked Devices, the Official API, or both. Use the Polymorfa message id for actions and replies. Unknown provider references are omitted." + }, + "ConversationIdentity": { + "type": "object", + "properties": { + "id": { + "type": "string", + "pattern": "^[1-9][0-9]{0,18}$", + "description": "Opaque Polymorfa resource ID. Keep this value as a string.", + "example": "739182640518203" + }, + "phoneNumber": { + "type": "string", + "pattern": "^\\+[1-9]\\d{1,14}$", + "description": "Phone number reported by WhatsApp, when available. It can differ from the number supplied for lookup. Use id for later actions and replies." + }, + "bsuid": { + "type": "string", + "pattern": "^[A-Z]{2}\\.[A-Za-z0-9]{1,128}$" + }, + "username": { + "type": "string", + "minLength": 1, + "maxLength": 256 + } + }, + "required": ["id"], + "additionalProperties": false + } + } + }, + "nativeCounterparts": { + "typescript": { + "testFile": "packages/typescript/test/newsletter-observations.test.ts", + "status": "source-implemented", + "release": "unpublished" + }, + "go": { + "testFile": "packages/go/newsletter_observations_test.go", + "status": "source-implemented", + "release": "unpublished" + }, + "python": { + "testFile": "packages/python/tests/test_newsletter_observations.py", + "status": "source-implemented", + "release": "unpublished" + }, + "php": { + "testFile": "packages/php/tests/newsletter_observations.php", + "status": "source-implemented", + "release": "unpublished" + }, + "rust": { + "testFile": "packages/rust/tests/newsletter_observations.rs", + "status": "source-implemented", + "release": "unpublished" + }, + "dotnet": { + "testFile": "packages/dotnet/tests/Polymorfa.Sdk.Tests/NewsletterObservationTests.cs", + "status": "source-implemented", + "release": "unpublished" + } + } +} diff --git a/internal/agent-sessions/2026-10-28-sdk366-main-refresh.md b/internal/agent-sessions/2026-10-28-sdk366-main-refresh.md new file mode 100644 index 000000000..a57373c73 --- /dev/null +++ b/internal/agent-sessions/2026-10-28-sdk366-main-refresh.md @@ -0,0 +1,39 @@ +# SDK366 accepted-main reconciliation, 2026-10-28 + +Owner/writer: purpshell's Codex session in T3 Code, OpenAI gpt-6.1-sol, +xhigh reasoning. Thread: 8bdb3d2e-6309-423e-ab7e-3e4db36e8841. +Registration: monorepo PR511. No subagents or additional writer. +This checkpoint records selected visible instructions and tool evidence; +it is not a complete transcript or independent approval. + +The owner authorized only SDK366 to incorporate accepted SDK358 main +4357c53b50c7292290740c0d08022f7e79cb875b. The former source head +59ce77d094f255de74f225700095840f1ad8c48f is preserved remotely at +backup/parity-sdk366-refresh-20261028/pr-366-59ce77d0. Original index, +patches, conflict stages and author mapping were retained privately. + +An actual merge-preserving rebase replayed all nine authored commits with +unchanged author names, emails, dates and subjects. The only conflicts were +catalog provenance values. Accepted main's version/example edits and all +six newsletter implementations, fixtures and supplemental API boundaries +were preserved. Package versions and coverage were not reduced or advanced. + +The combined committed SDK source is b3837b2388da5718f5c42a1d46ec83db5d613eeb. +Existing generation binds the exported catalog to that source with digest +e02c84247166b51207a21a72b629fce5b75c7010472b877c48580eb05d24e2a9. +All other catalog fields and 186 exported programs remain unchanged. +The baseline API source and separate newsletter supplement were not rebound. + +One serialized 180-second-maximum Node24 no-install claim completed: +generation, drift check, structural catalog tests, newsletter fixture check, +shared/native coverage attribution, 42 focused tests in four files, +changed-file formatting and git diff checks. Native checker and physical +package verification for this new combined source are not claimed locally. +Natural exact-head hosted CI must qualify the successor; prior green checks +remain historical. No reviewer request, manual CI dispatch/rerun, source +merge, tag, package publication, API activation or deployment was performed. + +H53/H54/871/874/875 unchanged mappings, completed CLI92 delivery, H44/H5 +parks, Business H55/migration20 and unconfirmed POL35 remain separate. +Release alone executes merges. Legal, independent-approval, effective +deployment-pause, package and availability gates remain in force. diff --git a/package.json b/package.json index b6aad2209..f6a92a181 100644 --- a/package.json +++ b/package.json @@ -34,7 +34,8 @@ "check:doc-snippets": "node scripts/generate-doc-snippets.mjs --check", "test:doc-snippets": "node --test scripts/doc-snippets.test.mjs", "verify:doc-snippets": "node scripts/verify-doc-snippets.mjs", - "check:machine-credentials": "node scripts/check-machine-credentials.mjs" + "check:machine-credentials": "node scripts/check-machine-credentials.mjs", + "check:newsletter-observations": "node scripts/check-newsletter-observations.mjs" }, "devDependencies": { "@aws-sdk/client-dynamodb": "^3.1149.0", diff --git a/packages/dotnet/README.md b/packages/dotnet/README.md index 0cae7e072..febe0e93f 100644 --- a/packages/dotnet/README.md +++ b/packages/dotnet/README.md @@ -1034,6 +1034,35 @@ whole-body signature verification before decoding and deduplicate batch members. See [the scoped source contract and compatibility notes](../../docs/campaign-webhook-metadata.md). Package publication and matching API environment acceptance remain separate gates. +## Channel observations + +`newsletter.update` can include metadata-only `messages` for `live_update`, or a +`milestone` object. Counts are reported observations. Missing is distinct from +zero, and an explicitly empty reaction map stays present. `viewCounts` preserves +each typed or untyped definition; do not choose one by list order. Unknown valid +milestone types remain strings. Existing channel reads also expose optional +`forwards`. + +A row's `position` is an ordering cursor. Its optional `message` reference is +present only when an original WhatsApp message ID was observed. A partial +reference alone does not authorize message actions. No message body is included. + +`NewsletterMilestone.Position` names the related post. It is `null` for +channel-level milestones, such as follower counts (`FOLLOWS`). + +After verifying the delivery signature and dispatching individual batch members: + +```csharp +if (webhookEvent is TypedWebhookEvent update) { + foreach (var row in update.Payload.Messages ?? []) { + if (row.Forwards is long forwards) Console.WriteLine($"{row.Position}: {forwards}"); + } +} +``` + +Source contract: [`newsletter-observations.json`](../../contracts/newsletter-observations.json). +This source supplement does not establish registry publication or API deployment. + ### Interactive-message candidate (unreleased) diff --git a/packages/dotnet/coverage.json b/packages/dotnet/coverage.json index 96cf089ee..aa1267de5 100644 --- a/packages/dotnet/coverage.json +++ b/packages/dotnet/coverage.json @@ -5246,6 +5246,13 @@ "published": false, "language": "dotnet" }, + "newsletterObservations": { + "inventory": "contracts/newsletter-observations.json", + "baselineUnchanged": true, + "published": false, + "language": "dotnet", + "testFile": "packages/dotnet/tests/Polymorfa.Sdk.Tests/NewsletterObservationTests.cs" + }, "interactiveMessages": { "inventory": "contracts/native-interactive-messages.json", "language": "dotnet", diff --git a/packages/dotnet/src/Polymorfa.Sdk/Channels.cs b/packages/dotnet/src/Polymorfa.Sdk/Channels.cs index 3b7161d78..075992867 100644 --- a/packages/dotnet/src/Polymorfa.Sdk/Channels.cs +++ b/packages/dotnet/src/Polymorfa.Sdk/Channels.cs @@ -4,7 +4,10 @@ namespace Polymorfa.Sdk; public sealed record Channel(string? Id = null, string? Name = null, string? Description = null, string? ProfileUrl = null, long? Followers = null, bool? Muted = null, bool? Preview = null); public sealed record CreateChannelRequest(string Name, string? Description = null, string? Picture = null); -public sealed record ChannelMessage(long Position, string Id, [property: JsonPropertyName("whatsapp_ids")] WhatsAppMessageIds WhatsAppIds, ConversationReference Conversation, string Type, string Timestamp, long Views, IReadOnlyDictionary ReactionCounts, string? Text = null, [property: JsonPropertyName("whatsapp_id")] string? WhatsAppId = null); +public sealed record ChannelMessage(long Position, string Id, [property: JsonPropertyName("whatsapp_ids")] WhatsAppMessageIds WhatsAppIds, ConversationReference Conversation, string Type, string Timestamp, long Views, IReadOnlyDictionary ReactionCounts, string? Text = null, [property: JsonPropertyName("whatsapp_id")] string? WhatsAppId = null) +{ + public long? Forwards { get; init; } +} public sealed record ChannelMessagesParameters(int? Count = null, long? Before = null); public sealed record ChannelMessageUpdatesParameters(int? Count = null, long? Since = null, long? After = null); public sealed record ChannelReactionRequest(string Reaction); diff --git a/packages/dotnet/src/Polymorfa.Sdk/WebhookPayloads.cs b/packages/dotnet/src/Polymorfa.Sdk/WebhookPayloads.cs index 7ce24ea0c..a03efdae9 100644 --- a/packages/dotnet/src/Polymorfa.Sdk/WebhookPayloads.cs +++ b/packages/dotnet/src/Polymorfa.Sdk/WebhookPayloads.cs @@ -61,7 +61,17 @@ public sealed record CallParticipantLeftPayload(string CallId, string Participan public sealed record CallConnection(string Id, string Participant, string Transport); public sealed record CallConnectionJoinedPayload(string CallId, CallConnection Connection); public sealed record CallConnectionLeftPayload(string CallId, string ConnectionId, string Participant, string Reason); -public sealed record NewsletterUpdatePayload(string Id, string Action, bool? Muted = null); +public sealed record NewsletterViewCount(long Count, string? Type = null); +public sealed record NewsletterMessageReference(string Id, [property: JsonPropertyName("whatsapp_ids")] WhatsAppMessageIds WhatsAppIds); +public sealed record NewsletterMessageObservation(long Position, NewsletterMessageReference? Message = null, string? Timestamp = null, IReadOnlyList? ViewCounts = null, long? Forwards = null, IReadOnlyDictionary? ReactionCounts = null); +/// Position is the related post's channel position. It is null for channel-level milestones such as follower counts. +public sealed record NewsletterMilestone(string Type, long Value, long? Position = null, string? ReactionCode = null); +public sealed record NewsletterUpdatePayload(string Id, string Action, bool? Muted = null) +{ + public string? SourceTimestamp { get; init; } + public IReadOnlyList? Messages { get; init; } + public NewsletterMilestone? Milestone { get; init; } +} public sealed record BlocklistChange(string Action, string Id, string? PhoneNumber = null, string? Bsuid = null, string? Username = null); public sealed record BlocklistUpdatePayload(string Action, IReadOnlyList Changes); public sealed record LabelsUpdatePayload(string Action, string? LabelId = null, IdentityReference? From = null, string? Label = null, string? Name = null, int? Color = null, int? OrderIndex = null, bool? Deleted = null, bool? Labeled = null, long? ObservedAt = null, string? MessageId = null, bool? Starred = null); diff --git a/packages/dotnet/tests/Polymorfa.Sdk.Tests/NewsletterObservationTests.cs b/packages/dotnet/tests/Polymorfa.Sdk.Tests/NewsletterObservationTests.cs new file mode 100644 index 000000000..f066567a8 --- /dev/null +++ b/packages/dotnet/tests/Polymorfa.Sdk.Tests/NewsletterObservationTests.cs @@ -0,0 +1,56 @@ +using System.Security.Cryptography; +using System.Text; +using System.Text.Json; +using System.Text.Json.Serialization; +using System.Text.Json.Nodes; +using Polymorfa.Sdk; + +internal static class NewsletterObservationTests +{ + public static void Run() + { + var json = new JsonSerializerOptions(JsonSerializerDefaults.Web) { DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull }; + var path = Path.Combine(AppContext.BaseDirectory, "newsletter-fixtures"); + using var fixture = JsonDocument.Parse(File.ReadAllText(Path.Combine(path, "delivery.json"))); + var root = fixture.RootElement; + var secret = root.GetProperty("secret").GetString()!; + var events = root.GetProperty("events").EnumerateArray().ToArray(); + VerifiedWebhookDelivery Signed(byte[] bytes) => Webhooks.ConstructDelivery(bytes, Convert.ToHexString(HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), bytes)), secret); + void Check(WebhookEvent e, JsonElement expected) + { + var typed = e as TypedWebhookEvent ?? throw new Exception("newsletter typed event lost"); + var (_, _, _) = typed.Payload; // Preserve the existing public Deconstruct arity. + var encoded = JsonSerializer.SerializeToElement(typed.Payload, json); + if (!JsonNode.DeepEquals(JsonNode.Parse(encoded.GetRawText()), JsonNode.Parse(expected.GetProperty("payload").GetRawText()))) throw new Exception("newsletter omission/zero/map roundtrip"); + if (typed.Payload.Action == "live_update") + { + var rows = typed.Payload.Messages!; + if (rows[0].Forwards != 0 || rows[0].ReactionCounts?.Count != 0 || rows[1].Message is not null || rows[1].Forwards is not null) throw new Exception("newsletter metadata lost"); + } + if (typed.Payload.Milestone is { } milestone) + { + var ok = milestone.Type switch + { + "FUTURE_MILESTONE" => milestone.Position == 123, + "FOLLOWS" => milestone.Position is null && milestone.Value == 1000, + _ => false, + }; + if (!ok) throw new Exception("newsletter milestone position lost"); + } + } + foreach (var expected in events) + { + var e = ((SingleWebhookDelivery)Signed(Encoding.UTF8.GetBytes(expected.GetRawText()))).Event; + Check(e, expected); + var encoded = Webhooks.CreateFixture(e, secret); + Check(((SingleWebhookDelivery)Webhooks.ConstructDelivery(encoded.Body, encoded.Signature, secret)).Event, expected); + } + var batchBytes = JsonSerializer.SerializeToUtf8Bytes(new { @object = "event_batch", version = 1, id = root.GetProperty("batchId").GetString(), events }); + var batch = (WebhookEventBatch)Signed(batchBytes); + if (batch.Events.Count != 4) throw new Exception("newsletter batch lost"); + for (var i = 0; i < events.Length; i++) Check(batch.Events[i], events[i]); + var channel = JsonSerializer.Deserialize(File.ReadAllText(Path.Combine(path, "channel-message.json")), json)!; + if (channel.Forwards != 0) throw new Exception("channel forward zero lost"); + Console.WriteLine("PASS newsletter observations, milestones, omission/zero/map and batch roundtrips"); + } +} diff --git a/packages/dotnet/tests/Polymorfa.Sdk.Tests/Polymorfa.Sdk.Tests.csproj b/packages/dotnet/tests/Polymorfa.Sdk.Tests/Polymorfa.Sdk.Tests.csproj index a9af0fd96..d3bc0fe59 100644 --- a/packages/dotnet/tests/Polymorfa.Sdk.Tests/Polymorfa.Sdk.Tests.csproj +++ b/packages/dotnet/tests/Polymorfa.Sdk.Tests/Polymorfa.Sdk.Tests.csproj @@ -4,4 +4,5 @@ + diff --git a/packages/dotnet/tests/Polymorfa.Sdk.Tests/Program.cs b/packages/dotnet/tests/Polymorfa.Sdk.Tests/Program.cs index 6b175d2aa..23d3b4f3b 100644 --- a/packages/dotnet/tests/Polymorfa.Sdk.Tests/Program.cs +++ b/packages/dotnet/tests/Polymorfa.Sdk.Tests/Program.cs @@ -9,6 +9,9 @@ if (args.Contains("--official-round2-only")) { await OfficialRound2Tests.RunAsync(); return; } +NewsletterObservationTests.Run(); +if (args.Contains("--newsletter-only")) return; + OpaqueCredentialTests.Run(); await OpaqueCredentialTests.WireAsync(); if (args.Contains("--credential-opaque-only")) { Console.WriteLine("PASS opaque credential shapes"); return; } diff --git a/packages/go/README.md b/packages/go/README.md index 1a49fb10a..543ac01de 100644 --- a/packages/go/README.md +++ b/packages/go/README.md @@ -835,6 +835,37 @@ whole-body signature verification before decoding and deduplicate batch members. See [the scoped source contract and compatibility notes](../../docs/campaign-webhook-metadata.md). Package publication and matching API environment acceptance remain separate gates. +## Channel observations + +`newsletter.update` can include metadata-only `messages` for `live_update`, or a +`milestone` object. Counts are reported observations. Missing is distinct from +zero, and an explicitly empty reaction map stays present. `viewCounts` preserves +each typed or untyped definition; do not choose one by list order. Unknown valid +milestone types remain strings. Existing channel reads also expose optional +`forwards`. + +A row's `position` is an ordering cursor. Its optional `message` reference is +present only when an original WhatsApp message ID was observed. A partial +reference alone does not authorize message actions. No message body is included. + +`NewsletterMilestone.Position` names the related post. It is nil for +channel-level milestones, such as follower counts (`FOLLOWS`). + +After verifying the delivery signature and dispatching individual batch members: + +```go +if payload, known, err := event.TypedPayload(); err == nil && known { + if update, ok := payload.(*polymorfa.NewsletterUpdatePayload); ok && update.Messages != nil { + for _, row := range *update.Messages { + if row.Forwards != nil { fmt.Println(row.Position, *row.Forwards) } + } + } +} +``` + +Source contract: [`newsletter-observations.json`](../../contracts/newsletter-observations.json). +This source supplement does not establish registry publication or API deployment. + ### Interactive-message candidate (unreleased) diff --git a/packages/go/channels.go b/packages/go/channels.go index ab8f0ed68..01b47bbb0 100644 --- a/packages/go/channels.go +++ b/packages/go/channels.go @@ -66,6 +66,7 @@ type ChannelMessage struct { Type string `json:"type"` Timestamp string `json:"timestamp"` Views int64 `json:"views"` + Forwards *int64 `json:"forwards,omitempty"` ReactionCounts map[string]int64 `json:"reactionCounts"` Text string `json:"text,omitempty"` } diff --git a/packages/go/coverage.json b/packages/go/coverage.json index 8494c9919..93c75f222 100644 --- a/packages/go/coverage.json +++ b/packages/go/coverage.json @@ -5246,6 +5246,13 @@ "published": false, "language": "go" }, + "newsletterObservations": { + "inventory": "contracts/newsletter-observations.json", + "baselineUnchanged": true, + "published": false, + "language": "go", + "testFile": "packages/go/newsletter_observations_test.go" + }, "interactiveMessages": { "inventory": "contracts/native-interactive-messages.json", "language": "go", diff --git a/packages/go/newsletter_observations_test.go b/packages/go/newsletter_observations_test.go new file mode 100644 index 000000000..704981042 --- /dev/null +++ b/packages/go/newsletter_observations_test.go @@ -0,0 +1,100 @@ +package polymorfa + +import ( + "crypto/hmac" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "os" + "reflect" + "testing" +) + +func TestNewsletterObservationDelivery(t *testing.T) { + raw, err := os.ReadFile("../../contracts/fixtures/newsletter-observations/delivery.json") + if err != nil { + t.Fatal(err) + } + var fixture struct { + Secret string + BatchID string + Events []json.RawMessage + } + if err := json.Unmarshal(raw, &fixture); err != nil { + t.Fatal(err) + } + check := func(event WebhookEvent, expected json.RawMessage) { + t.Helper() + value, known, err := event.TypedPayload() + if err != nil || !known { + t.Fatalf("typed newsletter: %v %v", known, err) + } + typed, ok := value.(*NewsletterUpdatePayload) + if !ok { + t.Fatalf("payload=%T", value) + } + var want struct{ Payload json.RawMessage } + if err := json.Unmarshal(expected, &want); err != nil { + t.Fatal(err) + } + encoded, err := json.Marshal(typed) + if err != nil { + t.Fatal(err) + } + var a, b any + _ = json.Unmarshal(encoded, &a) + _ = json.Unmarshal(want.Payload, &b) + if !reflect.DeepEqual(a, b) { + t.Fatalf("newsletter omission/zero/map roundtrip: %s != %s", encoded, want.Payload) + } + if typed.Action == "live_update" { + rows := *typed.Messages + if rows[0].Forwards == nil || *rows[0].Forwards != 0 || rows[0].ReactionCounts == nil || len(*rows[0].ReactionCounts) != 0 || rows[1].Message != nil || rows[1].Forwards != nil { + t.Fatal("missing/zero/empty metadata lost") + } + } + if typed.Action == "milestone" { + m := typed.Milestone + post := m.Type == "FUTURE_MILESTONE" && m.Value == 0 && m.Position != nil && *m.Position == 123 + channel := m.Type == "FOLLOWS" && m.Value == 1000 && m.Position == nil + if !post && !channel { + t.Fatalf("milestone lost: %+v", m) + } + } + } + signed := func(raw []byte) VerifiedWebhookDelivery { + t.Helper() + mac := hmac.New(sha256.New, []byte(fixture.Secret)) + mac.Write(raw) + v, e := ConstructWebhookDelivery(raw, hex.EncodeToString(mac.Sum(nil)), fixture.Secret) + if e != nil { + t.Fatal(e) + } + return v + } + for _, expected := range fixture.Events { + v := signed(expected) + check(*v.Event, expected) + roundtrip, e := CreateWebhookFixture(*v.Event, fixture.Secret) + if e != nil { + t.Fatal(e) + } + check(*signed(roundtrip.Body).Event, expected) + } + batch, _ := json.Marshal(map[string]any{"object": "event_batch", "version": 1, "id": fixture.BatchID, "events": fixture.Events}) + delivery := signed(batch) + if delivery.Batch == nil || len(delivery.Batch.Events) != 4 { + t.Fatal("batch lost") + } + for i, event := range delivery.Batch.Events { + check(event, fixture.Events[i]) + } + channelRaw, e := os.ReadFile("../../contracts/fixtures/newsletter-observations/channel-message.json") + if e != nil { + t.Fatal(e) + } + var channel ChannelMessage + if e = json.Unmarshal(channelRaw, &channel); e != nil || channel.Forwards == nil || *channel.Forwards != 0 { + t.Fatal("forward zero lost", e) + } +} diff --git a/packages/go/webhook_payloads.go b/packages/go/webhook_payloads.go index a7dbe92cc..a524dab3a 100644 --- a/packages/go/webhook_payloads.go +++ b/packages/go/webhook_payloads.go @@ -443,11 +443,38 @@ type CallConnectionLeftPayload struct { Participant string `json:"participant"` Reason string `json:"reason"` } +type NewsletterViewCount struct { + Type *string `json:"type,omitempty"` + Count int64 `json:"count"` +} +type NewsletterMessageReference struct { + ID string `json:"id"` + WhatsAppIDs WhatsAppMessageIDs `json:"whatsapp_ids"` +} +type NewsletterMessageObservation struct { + Position int64 `json:"position"` + Message *NewsletterMessageReference `json:"message,omitempty"` + Timestamp *string `json:"timestamp,omitempty"` + ViewCounts *[]NewsletterViewCount `json:"viewCounts,omitempty"` + Forwards *int64 `json:"forwards,omitempty"` + ReactionCounts *map[string]int64 `json:"reactionCounts,omitempty"` +} +type NewsletterMilestone struct { + // Position is the related post's channel position. It is nil for + // channel-level milestones such as follower counts. + Position *int64 `json:"position,omitempty"` + Type string `json:"type"` + Value int64 `json:"value"` + ReactionCode *string `json:"reactionCode,omitempty"` +} type NewsletterUpdatePayload struct { webhookPayloadBase - ID string `json:"id"` - Action string `json:"action"` - Muted *bool `json:"muted,omitempty"` + ID string `json:"id"` + Action string `json:"action"` + Muted *bool `json:"muted,omitempty"` + SourceTimestamp *string `json:"sourceTimestamp,omitempty"` + Messages *[]NewsletterMessageObservation `json:"messages,omitempty"` + Milestone *NewsletterMilestone `json:"milestone,omitempty"` } type WebhookBlocklistChange struct { Action string `json:"action"` diff --git a/packages/php/README.md b/packages/php/README.md index 9d7415bf3..9b7150219 100644 --- a/packages/php/README.md +++ b/packages/php/README.md @@ -988,6 +988,39 @@ whole-body signature verification before decoding and deduplicate batch members. See [the scoped source contract and compatibility notes](../../docs/campaign-webhook-metadata.md). Package publication and matching API environment acceptance remain separate gates. +## Channel observations + +`newsletter.update` can include metadata-only `messages` for `live_update`, or a +`milestone` object. Counts are reported observations. Missing is distinct from +zero, and an explicitly empty reaction map stays present. `viewCounts` preserves +each typed or untyped definition; do not choose one by list order. Unknown valid +milestone types remain strings. Existing channel reads also expose optional +`forwards`. + +A row's `position` is an ordering cursor. Its optional `message` reference is +present only when an original WhatsApp message ID was observed. A partial +reference alone does not authorize message actions. No message body is included. + +A milestone's `position` key names the related post. It is absent for +channel-level milestones, such as follower counts (`FOLLOWS`). + +After verifying the delivery signature and dispatching individual batch members: + +```php +$known = $event->knownEvent(); +if ($known !== null && $known['event'] === 'newsletter.update') { + $rows = $known['payload']['messages'] ?? []; + if (is_array($rows)) { + foreach ($rows as $row) { + if (array_key_exists('forwards', $row)) { echo $row['position'].': '.$row['forwards']; } + } + } +} +``` + +Source contract: [`newsletter-observations.json`](../../contracts/newsletter-observations.json). +This source supplement does not establish registry publication or API deployment. + ### Interactive-message candidate (unreleased) diff --git a/packages/php/coverage.json b/packages/php/coverage.json index 168765acb..bb0d14a7f 100644 --- a/packages/php/coverage.json +++ b/packages/php/coverage.json @@ -5383,6 +5383,13 @@ "published": false, "language": "php" }, + "newsletterObservations": { + "inventory": "contracts/newsletter-observations.json", + "baselineUnchanged": true, + "published": false, + "language": "php", + "testFile": "packages/php/tests/newsletter_observations.php" + }, "interactiveMessages": { "inventory": "contracts/native-interactive-messages.json", "language": "php", diff --git a/packages/php/src/ChannelModels.php b/packages/php/src/ChannelModels.php index f43db90e5..9ca7a409f 100644 --- a/packages/php/src/ChannelModels.php +++ b/packages/php/src/ChannelModels.php @@ -9,7 +9,7 @@ * @phpstan-import-type ProviderIds from HistoryModels * @phpstan-type Channel array{id?:string,name?:string,description?:string,profileUrl?:string,followers?:int,muted?:bool,preview?:bool} * @phpstan-type CreateChannel array{name:string,description?:string,picture?:string} - * @phpstan-type ChannelMessage array{position:int,id:string,whatsapp_ids:ProviderIds,whatsapp_id?:string,conversation:Identity,type:string,timestamp:string,views:int,reactionCounts:array,text?:string} + * @phpstan-type ChannelMessage array{position:int,id:string,whatsapp_ids:ProviderIds,whatsapp_id?:string,conversation:Identity,type:string,timestamp:string,views:int,forwards?:int,reactionCounts:array,text?:string} * @phpstan-type MessagesParams array{count?:int,before?:int} * @phpstan-type UpdatesParams array{count?:int,since?:int,after?:int} * @phpstan-type Reaction array{reaction:string} diff --git a/packages/php/src/WebhookEvent.php b/packages/php/src/WebhookEvent.php index 072057f57..5f8f61d2d 100644 --- a/packages/php/src/WebhookEvent.php +++ b/packages/php/src/WebhookEvent.php @@ -17,9 +17,16 @@ public function __construct( public mixed $payload, public array $raw, public bool $known, - public ?string $externalId = null + public ?string $externalId = null, + private ?string $verifiedBody = null ) { } + /** @internal Preserve JSON objects and arrays in verified fixture round trips. */ + public function fixtureBody(): string + { + $wire = $this->verifiedBody === null ? $this->raw : json_decode($this->verifiedBody, false, 512, JSON_THROW_ON_ERROR); + return json_encode($wire, JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE); + } /** Typed view of known event names, not a general payload schema validator. * Signed/verified parsing narrowly validates projected descriptor history. Raw forward fields remain available. * @return KnownEvent|null */ diff --git a/packages/php/src/WebhookModels.php b/packages/php/src/WebhookModels.php index 26f0af295..7d45dc953 100644 --- a/packages/php/src/WebhookModels.php +++ b/packages/php/src/WebhookModels.php @@ -96,7 +96,12 @@ * @phpstan-type CampaignCold array{campaignId:string,recipientId:string,phone:string,surface:string,reason:string,at:int|float} * @phpstan-type VoiceReady array{eventId:string,occurredAt:string,teamId:string,projectId:string,assetId:string,name:string,source:string,durationMs:int|float,contentSha256:string,originalFormat:string} * @phpstan-type VoiceFailed array{eventId:string,occurredAt:string,teamId:string,projectId:string,assetId:string,name:string,source:string,failureReason:string} - * @phpstan-type KnownEvent array{id:string,session:string,externalId?:string,timestamp:string,event:'marketing.onboarding_updated',payload:MarketingOnboarding}|array{id:string,session:string,externalId?:string,timestamp:string,event:'contact.marketing_preference_updated',payload:MarketingPreference}|array{id:string,session:string,externalId?:string,timestamp:string,event:'message.received'|'message.reaction',payload:Received}|array{id:string,session:string,externalId?:string,timestamp:string,event:'message.edited'|'message.revoked'|'message.update',payload:LinkedMessage}|array{id:string,session:string,externalId?:string,timestamp:string,event:'message.sent',payload:Sent}|array{id:string,session:string,externalId?:string,timestamp:string,event:'message.ack',payload:Ack}|array{id:string,session:string,externalId?:string,timestamp:string,event:'message.delete',payload:Deleted}|array{id:string,session:string,externalId?:string,timestamp:string,event:'message.vote',payload:Vote}|array{id:string,session:string,externalId?:string,timestamp:string,event:'message.failed',payload:Failed}|array{id:string,session:string,externalId?:string,timestamp:string,event:'message.echo',payload:array{source:'whatsapp_business_app',value:array}}|array{id:string,session:string,externalId?:string,timestamp:string,event:'session.status',payload:RuntimeStatus|CloudStatus}|array{id:string,session:string,externalId?:string,timestamp:string,event:'session.connected',payload:Connected}|array{id:string,session:string,externalId?:string,timestamp:string,event:'session.logged_out',payload:array{reason:'banned'|'device_removed'|'unknown',code:int|float}}|array{id:string,session:string,externalId?:string,timestamp:string,event:'session.phone_offline',payload:Offline}|array{id:string,session:string,externalId?:string,timestamp:string,event:'session.restriction_updated',payload:Restriction}|array{id:string,session:string,externalId?:string,timestamp:string,event:'session.capabilities_updated',payload:array{session:string,projectId:string,status:'synced'|'unknown',syncedAt:?string,checkedAt:?string,accountType:'business'|'personal'|null,capabilities:list,changedKeys:list}}|array{id:string,session:string,externalId?:string,timestamp:string,event:'group.update',payload:GroupUpdate}|array{id:string,session:string,externalId?:string,timestamp:string,event:'group.participant',payload:GroupParticipant}|array{id:string,session:string,externalId?:string,timestamp:string,event:'presence.update',payload:Presence}|array{id:string,session:string,externalId?:string,timestamp:string,event:'contact.opted_in'|'contact.opted_out',payload:ContactOpt}|array{id:string,session:string,externalId?:string,timestamp:string,event:'contact.update',payload:ContactUpdate}|array{id:string,session:string,externalId?:string,timestamp:string,event:'contact.sync',payload:array{kind:'contacts',value:array}}|array{id:string,session:string,externalId?:string,timestamp:string,event:'chat.archive',payload:Archive}|array{id:string,session:string,externalId?:string,timestamp:string,event:'chat.mute',payload:Mute}|array{id:string,session:string,externalId?:string,timestamp:string,event:'chat.read',payload:Read}|array{id:string,session:string,externalId?:string,timestamp:string,event:'chat.clear'|'chat.delete',payload:array{from:Identity}}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.received',payload:CallReceived}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.accepted',payload:CallAccepted}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.rejected',payload:array{from:Identity,callId:string}}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.missed',payload:array{from:Identity,callId:string,reason:string}}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.ended',payload:CallEnded}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.telemetry',payload:CallTelemetry}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.participant_joined'|'call.participant_state',payload:ParticipantEvent}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.participant_left',payload:array{callId:string,participantId:string,reason?:string}}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.connection_joined',payload:ConnectionJoined}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.connection_left',payload:ConnectionLeft}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.permission_changed',payload:Permission}|array{id:string,session:string,externalId?:string,timestamp:string,event:'order.payment_updated',payload:PaymentStatus|PaymentMethod}|array{id:string,session:string,externalId?:string,timestamp:string,event:'newsletter.update',payload:array{id:string,action:string,muted?:bool}}|array{id:string,session:string,externalId?:string,timestamp:string,event:'blocklist.update',payload:Blocklist}|array{id:string,session:string,externalId?:string,timestamp:string,event:'labels.update',payload:Labels}|array{id:string,session:string,externalId?:string,timestamp:string,event:'history.sync',payload:LinkedHistory|DirectHistory|array{kind:'history',value:array}}|array{id:string,session:string,externalId?:string,timestamp:string,event:'command.result',payload:Command}|array{id:string,session:string,externalId?:string,timestamp:string,event:'business.quick_reply.update',payload:QuickReply}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.created'|'customer.archived'|'customer.restored',payload:Customer}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.updated',payload:CustomerUpdated}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.enabled',payload:CustomerEnabled}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.archiving',payload:CustomerArchiving}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.pairing_link.created'|'customer.pairing_link.opened'|'customer.pairing_link.expired',payload:Pairing}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.pairing_link.connected',payload:PairingConnected}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.pairing_link.failed',payload:PairingFailed}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.pairing_link.revoked',payload:PairingRevoked}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.number.attached',payload:NumberAttached}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.number.transferred',payload:NumberTransferred}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.number.disconnected',payload:NumberDisconnected}|array{id:string,session:string,externalId?:string,timestamp:string,event:'bansafe.health_threshold',payload:HealthThreshold}|array{id:string,session:string,externalId?:string,timestamp:string,event:'bansafe.action',payload:BanSafeAction}|array{id:string,session:string,externalId?:string,timestamp:string,event:'bansafe.incident',payload:BanSafeIncident}|array{id:string,session:string,externalId?:string,timestamp:string,event:'bansafe.claim',payload:BanSafeClaim}|array{id:string,session:string,externalId?:string,timestamp:string,event:'template.status',payload:RuntimeTemplate|CloudTemplate}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.launched',payload:CampaignLaunched}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.paused',payload:CampaignPaused}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.rescheduled',payload:CampaignRescheduled}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.resumed',payload:CampaignResumed}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.completed',payload:CampaignCompleted}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.failed',payload:CampaignFailed}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.stopped',payload:CampaignStopped}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.recipient_sent',payload:RecipientSent}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.recipient_failed',payload:RecipientFailed}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.recipient_skipped',payload:RecipientSkipped}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.throttled',payload:CampaignThrottled}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.cap_reached',payload:CampaignCap}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.cold_blocked',payload:CampaignCold}|array{id:string,session:string,externalId?:string,timestamp:string,event:'usage.recorded',payload:UsageRecord}|array{id:string,session:string,externalId?:string,timestamp:string,event:'voice.asset_ready',payload:VoiceReady}|array{id:string,session:string,externalId?:string,timestamp:string,event:'voice.asset_failed',payload:VoiceFailed} + * @phpstan-type NewsletterViewCount array{type?:string,count:int} + * @phpstan-type NewsletterMessageReference array{id:string,whatsapp_ids:MessageIds} + * @phpstan-type NewsletterMessageObservation array{position:int,message?:NewsletterMessageReference,timestamp?:string,viewCounts?:list,forwards?:int,reactionCounts?:array} + * @phpstan-type NewsletterMilestone array{position?:int,type:string,value:int,reactionCode?:string} + * @phpstan-type NewsletterUpdate array{id:string,action:string,muted?:bool,sourceTimestamp?:string,messages?:list,milestone?:NewsletterMilestone} + * @phpstan-type KnownEvent array{id:string,session:string,externalId?:string,timestamp:string,event:'marketing.onboarding_updated',payload:MarketingOnboarding}|array{id:string,session:string,externalId?:string,timestamp:string,event:'contact.marketing_preference_updated',payload:MarketingPreference}|array{id:string,session:string,externalId?:string,timestamp:string,event:'message.received'|'message.reaction',payload:Received}|array{id:string,session:string,externalId?:string,timestamp:string,event:'message.edited'|'message.revoked'|'message.update',payload:LinkedMessage}|array{id:string,session:string,externalId?:string,timestamp:string,event:'message.sent',payload:Sent}|array{id:string,session:string,externalId?:string,timestamp:string,event:'message.ack',payload:Ack}|array{id:string,session:string,externalId?:string,timestamp:string,event:'message.delete',payload:Deleted}|array{id:string,session:string,externalId?:string,timestamp:string,event:'message.vote',payload:Vote}|array{id:string,session:string,externalId?:string,timestamp:string,event:'message.failed',payload:Failed}|array{id:string,session:string,externalId?:string,timestamp:string,event:'message.echo',payload:array{source:'whatsapp_business_app',value:array}}|array{id:string,session:string,externalId?:string,timestamp:string,event:'session.status',payload:RuntimeStatus|CloudStatus}|array{id:string,session:string,externalId?:string,timestamp:string,event:'session.connected',payload:Connected}|array{id:string,session:string,externalId?:string,timestamp:string,event:'session.logged_out',payload:array{reason:'banned'|'device_removed'|'unknown',code:int|float}}|array{id:string,session:string,externalId?:string,timestamp:string,event:'session.phone_offline',payload:Offline}|array{id:string,session:string,externalId?:string,timestamp:string,event:'session.restriction_updated',payload:Restriction}|array{id:string,session:string,externalId?:string,timestamp:string,event:'session.capabilities_updated',payload:array{session:string,projectId:string,status:'synced'|'unknown',syncedAt:?string,checkedAt:?string,accountType:'business'|'personal'|null,capabilities:list,changedKeys:list}}|array{id:string,session:string,externalId?:string,timestamp:string,event:'group.update',payload:GroupUpdate}|array{id:string,session:string,externalId?:string,timestamp:string,event:'group.participant',payload:GroupParticipant}|array{id:string,session:string,externalId?:string,timestamp:string,event:'presence.update',payload:Presence}|array{id:string,session:string,externalId?:string,timestamp:string,event:'contact.opted_in'|'contact.opted_out',payload:ContactOpt}|array{id:string,session:string,externalId?:string,timestamp:string,event:'contact.update',payload:ContactUpdate}|array{id:string,session:string,externalId?:string,timestamp:string,event:'contact.sync',payload:array{kind:'contacts',value:array}}|array{id:string,session:string,externalId?:string,timestamp:string,event:'chat.archive',payload:Archive}|array{id:string,session:string,externalId?:string,timestamp:string,event:'chat.mute',payload:Mute}|array{id:string,session:string,externalId?:string,timestamp:string,event:'chat.read',payload:Read}|array{id:string,session:string,externalId?:string,timestamp:string,event:'chat.clear'|'chat.delete',payload:array{from:Identity}}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.received',payload:CallReceived}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.accepted',payload:CallAccepted}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.rejected',payload:array{from:Identity,callId:string}}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.missed',payload:array{from:Identity,callId:string,reason:string}}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.ended',payload:CallEnded}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.telemetry',payload:CallTelemetry}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.participant_joined'|'call.participant_state',payload:ParticipantEvent}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.participant_left',payload:array{callId:string,participantId:string,reason?:string}}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.connection_joined',payload:ConnectionJoined}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.connection_left',payload:ConnectionLeft}|array{id:string,session:string,externalId?:string,timestamp:string,event:'call.permission_changed',payload:Permission}|array{id:string,session:string,externalId?:string,timestamp:string,event:'order.payment_updated',payload:PaymentStatus|PaymentMethod}|array{id:string,session:string,externalId?:string,timestamp:string,event:'newsletter.update',payload:NewsletterUpdate}|array{id:string,session:string,externalId?:string,timestamp:string,event:'blocklist.update',payload:Blocklist}|array{id:string,session:string,externalId?:string,timestamp:string,event:'labels.update',payload:Labels}|array{id:string,session:string,externalId?:string,timestamp:string,event:'history.sync',payload:LinkedHistory|DirectHistory|array{kind:'history',value:array}}|array{id:string,session:string,externalId?:string,timestamp:string,event:'command.result',payload:Command}|array{id:string,session:string,externalId?:string,timestamp:string,event:'business.quick_reply.update',payload:QuickReply}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.created'|'customer.archived'|'customer.restored',payload:Customer}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.updated',payload:CustomerUpdated}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.enabled',payload:CustomerEnabled}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.archiving',payload:CustomerArchiving}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.pairing_link.created'|'customer.pairing_link.opened'|'customer.pairing_link.expired',payload:Pairing}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.pairing_link.connected',payload:PairingConnected}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.pairing_link.failed',payload:PairingFailed}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.pairing_link.revoked',payload:PairingRevoked}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.number.attached',payload:NumberAttached}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.number.transferred',payload:NumberTransferred}|array{id:string,session:string,externalId?:string,timestamp:string,event:'customer.number.disconnected',payload:NumberDisconnected}|array{id:string,session:string,externalId?:string,timestamp:string,event:'bansafe.health_threshold',payload:HealthThreshold}|array{id:string,session:string,externalId?:string,timestamp:string,event:'bansafe.action',payload:BanSafeAction}|array{id:string,session:string,externalId?:string,timestamp:string,event:'bansafe.incident',payload:BanSafeIncident}|array{id:string,session:string,externalId?:string,timestamp:string,event:'bansafe.claim',payload:BanSafeClaim}|array{id:string,session:string,externalId?:string,timestamp:string,event:'template.status',payload:RuntimeTemplate|CloudTemplate}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.launched',payload:CampaignLaunched}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.paused',payload:CampaignPaused}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.rescheduled',payload:CampaignRescheduled}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.resumed',payload:CampaignResumed}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.completed',payload:CampaignCompleted}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.failed',payload:CampaignFailed}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.stopped',payload:CampaignStopped}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.recipient_sent',payload:RecipientSent}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.recipient_failed',payload:RecipientFailed}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.recipient_skipped',payload:RecipientSkipped}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.throttled',payload:CampaignThrottled}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.cap_reached',payload:CampaignCap}|array{id:string,session:string,externalId?:string,timestamp:string,event:'campaign.cold_blocked',payload:CampaignCold}|array{id:string,session:string,externalId?:string,timestamp:string,event:'usage.recorded',payload:UsageRecord}|array{id:string,session:string,externalId?:string,timestamp:string,event:'voice.asset_ready',payload:VoiceReady}|array{id:string,session:string,externalId?:string,timestamp:string,event:'voice.asset_failed',payload:VoiceFailed} */ final class WebhookModels { diff --git a/packages/php/src/Webhooks.php b/packages/php/src/Webhooks.php index 2d81de731..0fc4c1e61 100644 --- a/packages/php/src/Webhooks.php +++ b/packages/php/src/Webhooks.php @@ -46,8 +46,8 @@ public static function parseVerifiedDelivery(string $rawBody): WebhookEvent|Webh if (!$tree instanceof \stdClass || !is_array($tree->events ?? null)) { throw new ValidationException('Invalid event batch array.', 'invalid_webhook_batch'); } if (count($value) !== 4 || ($value['version'] ?? null) !== 1 || !is_string($value['id'] ?? null) || !preg_match('/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/iD', $value['id']) || !is_array($value['events'] ?? null) || !array_is_list($value['events']) || count($value['events']) < 1 || count($value['events']) > 100) { throw new ValidationException('Invalid version 1 event batch.', 'invalid_webhook_batch'); } $events = []; - foreach ($value['events'] as $member) { - if (!is_array($member) || array_key_exists('object', $member)) { throw new ValidationException('Nested or invalid event batch.', 'invalid_webhook_batch'); } + foreach ($tree->events as $member) { + if (!$member instanceof \stdClass || property_exists($member, 'object')) { throw new ValidationException('Nested or invalid event batch.', 'invalid_webhook_batch'); } $events[] = self::parseVerifiedEvent(json_encode($member, JSON_THROW_ON_ERROR)); } return new WebhookEventBatch($value['id'], $events); @@ -86,7 +86,7 @@ public static function verifyLocal(string $rawBody, string $signature, #[\Sensit /** @return array{body:string,contentType:'application/json',signature:string,headers:array{'content-type':'application/json','x-webhook-signature':string}} */ public static function createFixture(WebhookEvent $event, #[\SensitiveParameter] string $secret): array { - $body = json_encode($event->raw, JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE); + $body = $event->fixtureBody(); $signature = hash_hmac('sha256', $body, $secret); return ['body' => $body,'contentType' => 'application/json','signature' => $signature,'headers' => ['content-type' => 'application/json','x-webhook-signature' => $signature]]; } @@ -111,6 +111,6 @@ public static function parseVerifiedEvent(string $rawBody): WebhookEvent ProjectedHistory::validate($tree->payload); } /** @var array $value */ - return new WebhookEvent($value['id'], $value['session'], $value['timestamp'], $value['event'], $value['payload'], $value, in_array($value['event'], self::KNOWN_TYPES, true), is_string($value['externalId'] ?? null) ? $value['externalId'] : null); + return new WebhookEvent($value['id'], $value['session'], $value['timestamp'], $value['event'], $value['payload'], $value, in_array($value['event'], self::KNOWN_TYPES, true), is_string($value['externalId'] ?? null) ? $value['externalId'] : null, $rawBody); } } diff --git a/packages/php/tests/newsletter_observations.php b/packages/php/tests/newsletter_observations.php new file mode 100644 index 000000000..42e261f5a --- /dev/null +++ b/packages/php/tests/newsletter_observations.php @@ -0,0 +1,31 @@ +secret), $newsletterFixture->secret); +}; +$newsletterBatch = $newsletterSigned((object) ['object'=>'event_batch','version'=>1,'id'=>$newsletterFixture->batchId,'events'=>$newsletterFixture->events]); +check($newsletterBatch instanceof Polymorfa\WebhookEventBatch && count($newsletterBatch->events) === 4, 'newsletter batch'); +foreach ($newsletterFixture->events as $i => $expected) { + $event = $newsletterSigned($expected); + check($event instanceof Polymorfa\WebhookEvent && $event->knownEvent() !== null, 'newsletter typed event'); + check($event->payload === $newsletterBatch->events[$i]->payload, 'newsletter batch metadata'); + foreach ([$event, $newsletterBatch->events[$i]] as $member) { + $roundtrip = Polymorfa\Webhooks::createFixture($member, $newsletterFixture->secret); + $tree = json_decode($roundtrip['body'], false, 512, JSON_THROW_ON_ERROR); + check(json_encode($tree->payload) === json_encode($expected->payload), 'newsletter wire zero/object/omission roundtrip'); + } +} +$newsletterLive = $newsletterBatch->events[0]->knownEvent()['payload']; +check($newsletterLive['messages'][0]['forwards'] === 0 && $newsletterLive['messages'][0]['reactionCounts'] === [], 'newsletter explicit zero/empty map'); +check($newsletterLive['messages'][1] === ['position'=>124], 'newsletter missing reference'); +$newsletterMilestone = $newsletterBatch->events[1]->knownEvent()['payload']; +check($newsletterMilestone['milestone']['type'] === 'FUTURE_MILESTONE' && $newsletterMilestone['milestone']['value'] === 0, 'newsletter unknown milestone'); +$newsletterChannelMilestone = $newsletterBatch->events[3]->knownEvent()['payload']['milestone']; +check($newsletterChannelMilestone === ['type'=>'FOLLOWS','value'=>1000] && !array_key_exists('position', $newsletterChannelMilestone), 'newsletter channel-level milestone without position'); +$newsletterChannel = json_decode(file_get_contents($newsletterDir.'channel-message.json'), true, 512, JSON_THROW_ON_ERROR); +check($newsletterChannel['forwards'] === 0, 'channel reported forward zero'); diff --git a/packages/php/tests/run.php b/packages/php/tests/run.php index f69e508ad..7cb511d1f 100644 --- a/packages/php/tests/run.php +++ b/packages/php/tests/run.php @@ -271,4 +271,6 @@ function mocked(array $responses, array &$history): HttpClient require __DIR__.'/campaign_webhook_metadata.php'; +require __DIR__.'/newsletter_observations.php'; + require __DIR__.'/passkeys.php'; diff --git a/packages/php/tests/webhook_types.php b/packages/php/tests/webhook_types.php index c1d97c3a2..8bc1ad668 100644 --- a/packages/php/tests/webhook_types.php +++ b/packages/php/tests/webhook_types.php @@ -26,6 +26,17 @@ function typedWebhookConsumer(Polymorfa\WebhookEvent $event): void typedWebhookString($known['payload']['status']); } break; + case 'newsletter.update': + $newsletterRows = $known['payload']['messages'] ?? []; + if (is_array($newsletterRows)) { + foreach ($newsletterRows as $row) { + typedWebhookNumber($row['position']); + if (isset($row['forwards'])) { typedWebhookNumber($row['forwards']); } + if (isset($row['message'])) { typedWebhookString($row['message']['id']); } + } + } + if (isset($known['payload']['milestone'])) { typedWebhookString($known['payload']['milestone']['type']); } + break; case 'campaign.paused': if (isset($known['payload']['reason'])) { typedWebhookString($known['payload']['reason']); } if (isset($known['payload']['code'])) { typedWebhookString($known['payload']['code']); } diff --git a/packages/python/README.md b/packages/python/README.md index cf954debb..cf762a104 100644 --- a/packages/python/README.md +++ b/packages/python/README.md @@ -855,6 +855,34 @@ whole-body signature verification before decoding and deduplicate batch members. See [the scoped source contract and compatibility notes](../../docs/campaign-webhook-metadata.md). Package publication and matching API environment acceptance remain separate gates. +## Channel observations + +`newsletter.update` can include metadata-only `messages` for `live_update`, or a +`milestone` object. Counts are reported observations. Missing is distinct from +zero, and an explicitly empty reaction map stays present. `viewCounts` preserves +each typed or untyped definition; do not choose one by list order. Unknown valid +milestone types remain strings. Existing channel reads also expose optional +`forwards`. + +A row's `position` is an ordering cursor. Its optional `message` reference is +present only when an original WhatsApp message ID was observed. A partial +reference alone does not authorize message actions. No message body is included. + +A milestone's `position` key names the related post. It is absent for +channel-level milestones, such as follower counts (`FOLLOWS`). + +After verifying the delivery signature and dispatching individual batch members: + +```python +if is_event(event, "newsletter.update"): + for row in event.payload.get("messages", []): + if "forwards" in row: + print(row["position"], row["forwards"]) +``` + +Source contract: [`newsletter-observations.json`](../../contracts/newsletter-observations.json). +This source supplement does not establish registry publication or API deployment. + ### Interactive-message candidate (unreleased) diff --git a/packages/python/coverage.json b/packages/python/coverage.json index 840cd54c6..25bf4df74 100644 --- a/packages/python/coverage.json +++ b/packages/python/coverage.json @@ -5383,6 +5383,13 @@ "published": false, "language": "python" }, + "newsletterObservations": { + "inventory": "contracts/newsletter-observations.json", + "baselineUnchanged": true, + "published": false, + "language": "python", + "testFile": "packages/python/tests/test_newsletter_observations.py" + }, "interactiveMessages": { "inventory": "contracts/native-interactive-messages.json", "language": "python", diff --git a/packages/python/src/polymorfa/channels.py b/packages/python/src/polymorfa/channels.py index f2eef20b3..ce46ad90c 100644 --- a/packages/python/src/polymorfa/channels.py +++ b/packages/python/src/polymorfa/channels.py @@ -38,6 +38,7 @@ class ChannelMessage(TypedDict): type: str timestamp: str views: int + forwards: NotRequired[int] reactionCounts: dict[str, int] text: NotRequired[str] diff --git a/packages/python/src/polymorfa/webhook_models.py b/packages/python/src/polymorfa/webhook_models.py index 2b19ece01..bbe632965 100644 --- a/packages/python/src/polymorfa/webhook_models.py +++ b/packages/python/src/polymorfa/webhook_models.py @@ -457,10 +457,40 @@ class CallConnectionLeftPayload(TypedDict): ] +class NewsletterViewCount(TypedDict): + type: NotRequired[str] + count: int + + +class NewsletterMessageReference(TypedDict): + id: str + whatsapp_ids: WhatsAppMessageIds + + +class NewsletterMessageObservation(TypedDict): + position: int + message: NotRequired[NewsletterMessageReference] + timestamp: NotRequired[str] + viewCounts: NotRequired[list[NewsletterViewCount]] + forwards: NotRequired[int] + reactionCounts: NotRequired[dict[str, int]] + + +class NewsletterMilestone(TypedDict): + # Related post position. Absent for channel-level milestones such as follower counts. + position: NotRequired[int] + type: str + value: int + reactionCode: NotRequired[str] + + class NewsletterUpdatePayload(TypedDict): id: str action: str muted: NotRequired[bool] + sourceTimestamp: NotRequired[str] + messages: NotRequired[list[NewsletterMessageObservation]] + milestone: NotRequired[NewsletterMilestone] class BlocklistChange(TypedDict): diff --git a/packages/python/tests/test_newsletter_observations.py b/packages/python/tests/test_newsletter_observations.py new file mode 100644 index 000000000..f8bd34263 --- /dev/null +++ b/packages/python/tests/test_newsletter_observations.py @@ -0,0 +1,53 @@ +import hashlib +import hmac +import json +from pathlib import Path +from typing import cast + +from polymorfa import construct_webhook_delivery, create_webhook_fixture, is_event +from polymorfa.channels import ChannelMessage +from polymorfa.webhook_models import NewsletterUpdatePayload +from polymorfa.webhooks import WebhookEventBatch + +FIXTURES = Path(__file__).parents[3] / "contracts/fixtures/newsletter-observations" + + +def test_newsletter_single_batch_and_fixture_roundtrip() -> None: + fixture = json.loads((FIXTURES / "delivery.json").read_text()) + + def signed(value: object): + raw = json.dumps(value, ensure_ascii=False).encode() + signature = hmac.new(fixture["secret"].encode(), raw, hashlib.sha256).hexdigest() + return construct_webhook_delivery(raw, signature, fixture["secret"]) + + batch = signed( + { + "object": "event_batch", + "version": 1, + "id": fixture["batchId"], + "events": fixture["events"], + } + ) + assert isinstance(batch, WebhookEventBatch) + for index, expected in enumerate(fixture["events"]): + event = signed(expected) + assert not isinstance(event, WebhookEventBatch) + assert is_event(event, "newsletter.update") + payload: NewsletterUpdatePayload = event.payload + assert payload == expected["payload"] == batch.events[index].payload + encoded = create_webhook_fixture(event, fixture["secret"]) + again = construct_webhook_delivery(encoded.body, encoded.signature, fixture["secret"]) + assert not isinstance(again, WebhookEventBatch) + assert again.payload == payload + live = cast(NewsletterUpdatePayload, batch.events[0].payload) + assert live["messages"][0]["forwards"] == 0 + assert live["messages"][0]["reactionCounts"] == {} + assert live["messages"][1] == {"position": 124} + assert live["messages"][0]["viewCounts"] == [{"count": 0}, {"type": "views", "count": 11}] + channel_milestone = cast(NewsletterUpdatePayload, batch.events[3].payload)["milestone"] + assert channel_milestone == {"type": "FOLLOWS", "value": 1000} + assert "position" not in channel_milestone + standalone = json.loads((FIXTURES / "milestone-channel.json").read_text()) + assert "position" not in standalone["milestone"] + channel = cast(ChannelMessage, json.loads((FIXTURES / "channel-message.json").read_text())) + assert channel["forwards"] == 0 diff --git a/packages/rust/README.md b/packages/rust/README.md index 4640826eb..3fa221297 100644 --- a/packages/rust/README.md +++ b/packages/rust/README.md @@ -929,6 +929,39 @@ whole-body signature verification before decoding and deduplicate batch members. See [the scoped source contract and compatibility notes](../../docs/campaign-webhook-metadata.md). Package publication and matching API environment acceptance remain separate gates. +## Channel observations + +`newsletter.update` can include metadata-only `messages` for `live_update`, or a +`milestone` object. Counts are reported observations. Missing is distinct from +zero, and an explicitly empty reaction map stays present. `viewCounts` preserves +each typed or untyped definition; do not choose one by list order. Unknown valid +milestone types remain strings. Existing channel reads also expose optional +`forwards`. + +A row's `position` is an ordering cursor. Its optional `message` reference is +present only when an original WhatsApp message ID was observed. A partial +reference alone does not authorize message actions. No message body is included. + +`NewsletterMilestone::position` names the related post. It is `None` for +channel-level milestones, such as follower counts (`FOLLOWS`). + +After verifying the delivery signature and dispatching individual batch members: + +```rust +use polymorfa_sdk::{webhook_payloads::KnownWebhookPayload, webhooks::WebhookEvent}; + +fn report_channel_observations(event: WebhookEvent) { + if let WebhookEvent::Known { payload: KnownWebhookPayload::NewsletterUpdate(update), .. } = event { + for row in update.messages.unwrap_or_default() { + if let Some(forwards) = row.forwards { println!("{}: {}", row.position, forwards); } + } + } +} +``` + +Source contract: [`newsletter-observations.json`](../../contracts/newsletter-observations.json). +This source supplement does not establish registry publication or API deployment. + ### Interactive-message candidate (unreleased) diff --git a/packages/rust/coverage.json b/packages/rust/coverage.json index 6e745485d..1e28d0287 100644 --- a/packages/rust/coverage.json +++ b/packages/rust/coverage.json @@ -5383,6 +5383,13 @@ "published": false, "language": "rust" }, + "newsletterObservations": { + "inventory": "contracts/newsletter-observations.json", + "baselineUnchanged": true, + "published": false, + "language": "rust", + "testFile": "packages/rust/tests/newsletter_observations.rs" + }, "interactiveMessages": { "inventory": "contracts/native-interactive-messages.json", "language": "rust", diff --git a/packages/rust/src/channels.rs b/packages/rust/src/channels.rs index defff0db5..4ed5100b0 100644 --- a/packages/rust/src/channels.rs +++ b/packages/rust/src/channels.rs @@ -48,6 +48,8 @@ pub struct ChannelMessage { pub message_type: String, pub timestamp: String, pub views: u64, + #[serde(skip_serializing_if = "Option::is_none")] + pub forwards: Option, pub reaction_counts: BTreeMap, #[serde(skip_serializing_if = "Option::is_none")] pub text: Option, diff --git a/packages/rust/src/webhook_payloads.rs b/packages/rust/src/webhook_payloads.rs index 531e07b23..89e097fe0 100644 --- a/packages/rust/src/webhook_payloads.rs +++ b/packages/rust/src/webhook_payloads.rs @@ -324,7 +324,51 @@ pub enum CallConnectionLeftReason { SipAuthFailed, } payload!(CallConnectionLeftPayload {call_id:String,connection_id:String,participant:String,reason:CallConnectionLeftReason} {}); -payload!(NewsletterUpdatePayload {id:String,action:String} {muted:bool}); +#[derive(Clone, Debug, Serialize, Deserialize)] +pub struct NewsletterMessageReference { + pub id: String, + #[serde(serialize_with = "serialize_newsletter_message_ids")] + pub whatsapp_ids: WhatsAppMessageIds, +} +// Keep absent transports absent on the new metadata reference, without changing +// the existing shared identity serializer used by other resource models. +fn serialize_newsletter_message_ids( + value: &WhatsAppMessageIds, + serializer: S, +) -> Result +where + S: serde::Serializer, +{ + use serde::ser::SerializeMap; + let mut map = serializer.serialize_map(None)?; + if let Some(id) = &value.linked_devices { + map.serialize_entry("linked_devices", id)?; + } + if let Some(id) = &value.official_api { + map.serialize_entry("official_api", id)?; + } + map.end() +} +#[derive(Clone, Debug, Serialize, Deserialize)] +pub struct NewsletterViewCount { + #[serde(rename = "type", skip_serializing_if = "Option::is_none")] + pub view_type: Option, + pub count: u64, +} +payload!(NewsletterMessageObservation {position:u64} {message:NewsletterMessageReference,timestamp:String,view_counts:Vec,forwards:u64,reaction_counts:BTreeMap}); +#[derive(Clone, Debug, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct NewsletterMilestone { + /// Related post position. `None` for channel-level milestones such as follower counts. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub position: Option, + #[serde(rename = "type")] + pub milestone_type: String, + pub value: u64, + #[serde(skip_serializing_if = "Option::is_none")] + pub reaction_code: Option, +} +payload!(NewsletterUpdatePayload {id:String,action:String} {muted:bool,source_timestamp:String,messages:Vec,milestone:NewsletterMilestone}); payload!(BlocklistChange {action:String,id:String} {phone_number:String,bsuid:String,username:String}); payload!(BlocklistUpdatePayload {action:String,changes:Vec} {}); payload!(LabelsUpdatePayload {action:String} {label_id:String,from:ConversationIdentity,label:String,name:String,color:u32,order_index:u32,deleted:bool,labeled:bool,observed_at:u64,message_id:String,starred:bool}); diff --git a/packages/rust/tests/newsletter_observations.rs b/packages/rust/tests/newsletter_observations.rs new file mode 100644 index 000000000..0b338473b --- /dev/null +++ b/packages/rust/tests/newsletter_observations.rs @@ -0,0 +1,61 @@ +use polymorfa_sdk::{channels::ChannelMessage, webhook_payloads::KnownWebhookPayload, webhooks::*}; +use serde_json::{json, Value}; + +#[test] +fn newsletter_metadata_roundtrips_in_native_single_and_batch_deliveries() { + let fixture: Value = serde_json::from_str(include_str!( + "../../../contracts/fixtures/newsletter-observations/delivery.json" + )) + .unwrap(); + let secret = fixture["secret"].as_str().unwrap(); + let check = |event: &WebhookEvent, expected: &Value| { + let payload = match event { + WebhookEvent::Known { + payload: KnownWebhookPayload::NewsletterUpdate(payload), + .. + } => payload, + _ => panic!("newsletter typed event lost"), + }; + assert_eq!(serde_json::to_value(payload).unwrap(), expected["payload"]); + if payload.action == "live_update" { + let rows = payload.messages.as_ref().unwrap(); + assert_eq!(rows[0].forwards, Some(0)); + assert!(rows[0].reaction_counts.as_ref().unwrap().is_empty()); + assert!(rows[1].message.is_none()); + assert!(rows[1].forwards.is_none()); + } + if let Some(milestone) = payload.milestone.as_ref() { + match milestone.milestone_type.as_str() { + "FUTURE_MILESTONE" => assert_eq!(milestone.position, Some(123)), + "FOLLOWS" => { + assert_eq!(milestone.position, None); + assert_eq!(milestone.value, 1000); + } + other => panic!("unexpected milestone {other}"), + } + } + }; + for expected in fixture["events"].as_array().unwrap() { + let event = parse_verified_event(&serde_json::to_vec(expected).unwrap()).unwrap(); + check(&event, expected); + let encoded = create_fixture(&event, secret).unwrap(); + check( + &construct_event(&encoded.body, &encoded.signature, secret).unwrap(), + expected, + ); + } + let raw = serde_json::to_vec(&json!({"object":"event_batch","version":1,"id":fixture["batchId"],"events":fixture["events"]})).unwrap(); + let batch = match parse_verified_delivery(&raw).unwrap() { + WebhookDelivery::Batch(batch) => batch, + _ => panic!("batch lost"), + }; + assert_eq!(batch.events.len(), 4); + for (index, event) in batch.events.iter().enumerate() { + check(event, &fixture["events"][index]); + } + let channel: ChannelMessage = serde_json::from_str(include_str!( + "../../../contracts/fixtures/newsletter-observations/channel-message.json" + )) + .unwrap(); + assert_eq!(channel.forwards, Some(0)); +} diff --git a/packages/typescript/README.md b/packages/typescript/README.md index 387c55d37..6174755f5 100644 --- a/packages/typescript/README.md +++ b/packages/typescript/README.md @@ -3475,6 +3475,35 @@ whole-body signature verification before decoding and deduplicate batch members. See [the scoped source contract and compatibility notes](../../docs/campaign-webhook-metadata.md). Package publication and matching API environment acceptance remain separate gates. +## Channel observations + +`newsletter.update` can include metadata-only `messages` for `live_update`, or a +`milestone` object. Counts are reported observations. Missing is distinct from +zero, and an explicitly empty reaction map stays present. `viewCounts` preserves +each typed or untyped definition; do not choose one by list order. Unknown valid +milestone types remain strings. Existing channel reads also expose optional +`forwards`. + +A row's `position` is an ordering cursor. Its optional `message` reference is +present only when an original WhatsApp message ID was observed. A partial +reference alone does not authorize message actions. No message body is included. + +A milestone's optional `position` names the related post. It is absent for +channel-level milestones, such as follower counts (`FOLLOWS`). + +After verifying the delivery signature and dispatching individual batch members: + +```typescript +if (isEvent(event, "newsletter.update")) { + for (const row of event.payload.messages ?? []) { + if (row.forwards !== undefined) console.log(row.position, row.forwards); + } +} +``` + +Source contract: [`newsletter-observations.json`](../../contracts/newsletter-observations.json). +This source supplement does not establish registry publication or API deployment. + ### Interactive-message candidate These types target candidate API PR #562. They require its backend implementation; diff --git a/packages/typescript/src/index.ts b/packages/typescript/src/index.ts index 2d9ec2f8e..d8db43818 100644 --- a/packages/typescript/src/index.ts +++ b/packages/typescript/src/index.ts @@ -1239,6 +1239,9 @@ export { type NativeFlowResponse, type ReplyChoice, type NewsletterUpdatePayload, + type NewsletterMessageObservation, + type NewsletterViewCount, + type NewsletterMilestone, type PollOption, type PollVotePayload, type PresenceUpdatePayload, diff --git a/packages/typescript/src/messaging/types.ts b/packages/typescript/src/messaging/types.ts index e48d66f0b..faf85ef2b 100644 --- a/packages/typescript/src/messaging/types.ts +++ b/packages/typescript/src/messaging/types.ts @@ -1490,6 +1490,8 @@ export interface ChannelMessage { readonly type: string; readonly timestamp: string; readonly views: number; + /** Reported forward count. Missing is distinct from zero. */ + readonly forwards?: number; readonly reactionCounts: Readonly>; readonly text?: string; } diff --git a/packages/typescript/src/webhooks/events.ts b/packages/typescript/src/webhooks/events.ts index 228b4daa6..f457b2a4e 100644 --- a/packages/typescript/src/webhooks/events.ts +++ b/packages/typescript/src/webhooks/events.ts @@ -642,10 +642,37 @@ export interface CallConnectionLeftPayload { readonly reason: CallConnectionLeftReason; } +/** A reported view definition. An absent type denotes the untyped definition. */ +export interface NewsletterViewCount { + readonly type?: string; + readonly count: number; +} +/** Counts observed at a channel position. No message body is included. */ +export interface NewsletterMessageObservation { + readonly position: number; + readonly message?: { + readonly id: string; + readonly whatsapp_ids: WhatsAppMessageIds; + }; + readonly timestamp?: string; + readonly viewCounts?: readonly NewsletterViewCount[]; + readonly forwards?: number; + readonly reactionCounts?: Readonly>; +} +export interface NewsletterMilestone { + /** Channel position of the related post. Absent for channel-level milestones such as follower counts. */ + readonly position?: number; + readonly type: string; + readonly value: number; + readonly reactionCode?: string; +} export interface NewsletterUpdatePayload { readonly id: string; readonly action: string; readonly muted?: boolean; + readonly sourceTimestamp?: string; + readonly messages?: readonly NewsletterMessageObservation[]; + readonly milestone?: NewsletterMilestone; } export interface BlocklistChange { diff --git a/packages/typescript/src/webhooks/index.ts b/packages/typescript/src/webhooks/index.ts index 2a5ac701f..ba77139b2 100644 --- a/packages/typescript/src/webhooks/index.ts +++ b/packages/typescript/src/webhooks/index.ts @@ -101,6 +101,9 @@ export { type NativeFlowResponse, type ReplyChoice, type NewsletterUpdatePayload, + type NewsletterMessageObservation, + type NewsletterViewCount, + type NewsletterMilestone, type PollOption, type PollVotePayload, type PresenceUpdatePayload, diff --git a/packages/typescript/test/newsletter-observations.test.ts b/packages/typescript/test/newsletter-observations.test.ts new file mode 100644 index 000000000..38e442f07 --- /dev/null +++ b/packages/typescript/test/newsletter-observations.test.ts @@ -0,0 +1,90 @@ +import { createHmac } from "node:crypto"; +import { readFileSync } from "node:fs"; +import { describe, expect, expectTypeOf, it } from "vitest"; +import { + constructWebhookDelivery, + isWebhookEventBatch, + isEvent, + webhooks, + type NewsletterMessageObservation, + type NewsletterMilestone, + type NewsletterViewCount, + type ChannelMessage, +} from "../src/index.js"; +const load = (name: string) => + JSON.parse( + readFileSync( + new URL( + `../../../contracts/fixtures/newsletter-observations/${name}.json`, + import.meta.url, + ), + "utf8", + ), + ); +const fixture = load("delivery"); +const signed = (value: unknown) => { + const raw = Buffer.from(JSON.stringify(value)); + return constructWebhookDelivery( + raw, + createHmac("sha256", fixture.secret).update(raw).digest("hex"), + fixture.secret, + ); +}; +describe("newsletter metadata", () => { + it("retains native single and batch observations, including missing, zero and empty fields", async () => { + const batch = await signed({ + object: "event_batch", + version: 1, + id: fixture.batchId, + events: fixture.events, + }); + if (!isWebhookEventBatch(batch)) throw new Error("Expected batch"); + for (const [index, expected] of fixture.events.entries()) { + const event = await signed(expected); + if (isWebhookEventBatch(event) || !isEvent(event, "newsletter.update")) + throw new Error("Expected newsletter event"); + expect(event.payload).toEqual(expected.payload); + expect(batch.events[index]).toEqual(event); + expectTypeOf(event.payload.messages).toEqualTypeOf< + readonly NewsletterMessageObservation[] | undefined + >(); + expectTypeOf(event.payload.milestone).toEqualTypeOf< + NewsletterMilestone | undefined + >(); + const roundtrip = await webhooks.createFixture({ + event, + secret: fixture.secret, + }); + expect( + await constructWebhookDelivery( + roundtrip.body, + roundtrip.signature, + fixture.secret, + ), + ).toEqual(event); + } + const live = batch.events[0]; + if (!live || !isEvent(live, "newsletter.update")) + throw new Error("Expected live update"); + expect(live.payload.messages?.[0]?.forwards).toBe(0); + expect(live.payload.messages?.[0]?.reactionCounts).toEqual({}); + expect(live.payload.messages?.[1]).toEqual({ position: 124 }); + const channelMilestone = batch.events[3]; + if (!channelMilestone || !isEvent(channelMilestone, "newsletter.update")) + throw new Error("Expected channel milestone"); + expect(channelMilestone.payload.milestone).toEqual({ + type: "FOLLOWS", + value: 1000, + }); + expect("position" in (channelMilestone.payload.milestone ?? {})).toBe( + false, + ); + expectTypeOf().toEqualTypeOf< + number | undefined + >(); + expectTypeOf().toEqualTypeOf(); + const channel: ChannelMessage = load("channel-message"); + expect(channel.forwards).toBe(0); + expectTypeOf(channel.forwards).toEqualTypeOf(); + }); +}); diff --git a/packages/typescript/test/webhook-event-types.test.ts b/packages/typescript/test/webhook-event-types.test.ts index 864458b5d..d0c78184e 100644 --- a/packages/typescript/test/webhook-event-types.test.ts +++ b/packages/typescript/test/webhook-event-types.test.ts @@ -430,6 +430,27 @@ type ExpectedPayloads = { readonly id: string; readonly action: string; readonly muted?: boolean; + readonly sourceTimestamp?: string; + readonly messages?: readonly { + readonly position: number; + readonly message?: { + readonly id: string; + readonly whatsapp_ids: WhatsAppMessageIds; + }; + readonly timestamp?: string; + readonly viewCounts?: readonly { + readonly type?: string; + readonly count: number; + }[]; + readonly forwards?: number; + readonly reactionCounts?: Readonly>; + }[]; + readonly milestone?: { + readonly position?: number; + readonly type: string; + readonly value: number; + readonly reactionCode?: string; + }; }; readonly "presence.update": { readonly observedAt: number; diff --git a/scripts/check-newsletter-observations.mjs b/scripts/check-newsletter-observations.mjs new file mode 100644 index 000000000..02bc4ce28 --- /dev/null +++ b/scripts/check-newsletter-observations.mjs @@ -0,0 +1,96 @@ +import assert from "node:assert/strict"; +import { existsSync, readFileSync } from "node:fs"; +import { resolve } from "node:path"; +import Ajv from "ajv"; +import addFormats from "ajv-formats"; +const root = resolve(import.meta.dirname, ".."); +const read = (path) => JSON.parse(readFileSync(resolve(root, path), "utf8")); +const contract = read("contracts/newsletter-observations.json"); +assert.match(contract.sourceCommit, /^[a-f0-9]{40}$/); +assert.match(contract.sourceSha256, /^[a-f0-9]{64}$/); +assert.equal(contract.published, false); +assert.equal(contract.polymorfaVersion, "2026-09-22"); +const ajv = new Ajv({ strict: false }); +addFormats(ajv); +// OpenAPI 3.0 uses boolean exclusive bounds; Ajv consumes JSON Schema bounds. +function jsonSchema(value) { + if (Array.isArray(value)) return value.map(jsonSchema); + if (value === null || typeof value !== "object") return value; + const result = Object.fromEntries( + Object.entries(value).map(([key, item]) => [key, jsonSchema(item)]), + ); + for (const bound of ["Minimum", "Maximum"]) { + const exclusive = `exclusive${bound}`, + inclusive = bound.toLowerCase(); + if (typeof result[exclusive] === "boolean") { + if (result[exclusive]) result[exclusive] = result[inclusive]; + else delete result[exclusive]; + } + } + return result; +} +const validate = (name) => + ajv.compile({ + components: jsonSchema(contract.components), + $ref: `#/components/schemas/${name}`, + }); +const payload = validate("NewsletterUpdatePayload"); +const fixture = read( + "contracts/fixtures/newsletter-observations/delivery.json", +); +for (const event of fixture.events) + assert.ok(payload(event.payload), JSON.stringify(payload.errors)); +assert.equal( + payload({ id: "123", action: "live_update", messages: [{ position: 0 }] }), + false, +); +const channel = validate("ChannelMessage"); +assert.ok( + channel( + read("contracts/fixtures/newsletter-observations/channel-message.json"), + ), + JSON.stringify(channel.errors), +); +const live = fixture.events[0].payload; +assert.equal(live.messages[0].forwards, 0); +assert.deepEqual(live.messages[0].reactionCounts, {}); +assert.deepEqual(live.messages[1], { position: 124 }); +assert.deepEqual(live.messages[0].viewCounts, [ + { count: 0 }, + { type: "views", count: 11 }, +]); +assert.equal(fixture.events[1].payload.milestone.type, "FUTURE_MILESTONE"); +assert.equal(fixture.events[3].payload.milestone.type, "FOLLOWS"); +assert.equal("position" in fixture.events[3].payload.milestone, false); +for (const name of ["milestone", "milestone-channel"]) + assert.ok( + payload(read(`contracts/fixtures/newsletter-observations/${name}.json`)), + JSON.stringify(payload.errors), + ); +assert.equal( + payload({ + id: "123", + action: "milestone", + milestone: { position: 0, type: "FOLLOWS", value: 1 }, + }), + false, +); +for (const [language, evidence] of Object.entries( + contract.nativeCounterparts, +)) { + assert.ok( + existsSync(resolve(root, evidence.testFile)), + `${language} native evidence missing`, + ); + if (language !== "typescript") { + const ledger = read(`packages/${language}/coverage.json`).supplements + .newsletterObservations; + assert.equal(ledger.testFile, evidence.testFile); + assert.equal(ledger.inventory, "contracts/newsletter-observations.json"); + assert.equal(ledger.published, false); + } +} +assert.equal(Object.keys(contract.nativeCounterparts).length, 6); +console.log( + "Newsletter contract fixtures and six native coverage receipts match the candidate supplement.", +); diff --git a/scripts/doc-snippets/recipes.mjs b/scripts/doc-snippets/recipes.mjs index 8a64abb33..55cecbbaf 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 = "4b6ce43985ab6e3d6b0427858da5792c06dbb520"; +export const sourceCommit = "47b1e92af97f13b86b2e86fde49a4d244412c632"; export const apiVersion = "2026-09-22"; export const languages = [ "typescript",