Skip to content

feat(newsletters): preserve channel observations in six SDKs - #366

Open
purpshell wants to merge 22 commits into
mainfrom
codex/pol81-newsletter-observations
Open

purpshell wants to merge 22 commits into
mainfrom
codex/pol81-newsletter-observations

Conversation

@purpshell

@purpshell purpshell commented Oct 27, 2026 •

Copy link
Copy Markdown
Member

Preserve typed newsletter observations and milestones in all six server SDKs, including forwards and missing/zero/empty-map distinctions. The API baseline and separate newsletter supplement remain unchanged.

Current main is integrated. The genuine snippet producer binds the combined SDK source and emits 31 programs per language. The dependency audit repair updates the workspace cleanup/glob tooling while retaining Firestore and the public Node engine declarations. See the glob advisory and minimatch advisory.

Before the latest commit: formatting, lint, typechecking, workspace builds, 2,203 tests, snippet drift checking and the production dependency audit passed. The standard suite reports 113 skipped fixture tests. The audit reports zero production vulnerabilities; this is not all-dependency clearance. New-head hosted CI and code/security reviews remain required.

Companions: HyperMeow #53 → #54, backend #871 → #874, and CLI #92. Qualify the complete family before merging bottom-up.

No registry publication, API availability, deployment or activation is claimed or authorized.

Summary by CodeRabbit

  • New Features
    • Added newsletter webhook observation support across SDKs, including message-level views, forwards, reactions, timestamps, and milestone data.
    • Channel message results can now include an optional forwards count, distinguishing unreported counts from zero.
  • Documentation
    • Added guidance and examples for handling newsletter observations across supported languages.
  • Tests
    • Added fixture-based coverage for individual and batched events, payload preservation, and optional fields.

@coderabbitai

coderabbitai Bot commented Oct 27, 2026 •

Copy link
Copy Markdown

Explain Change →

Warning

Review limit reached

The included review limit has been reached and this organization has disabled usage-based review continuation. Wait for reviews to reset or ask a billing admin to change After included review limits.

  • Ask an admin to enable usage-based reviews

Open in CodeRabbit

Reviews can continue after your included limit without a manual trigger. An admin must approve usage-based billing.

Next included review available in 2 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 2 included reviews currently available. Your 66 included PR review attempts over the past 7 days set your current allowance at 2 reviews per hour.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Team
  • Run ID: 97681e0c-28d1-42b4-8c24-eb4c3ffbfd0d
Commits

Reviewing files that changed from the base of the PR and between c7af5b0 and b30fc84.

Files selected for processing: 51

  • .github/workflows/ci.yml
  • contracts/coverage.json
  • contracts/doc-snippets.json
  • contracts/fixtures/newsletter-observations/channel-message.json
  • contracts/fixtures/newsletter-observations/delivery.json
  • contracts/fixtures/newsletter-observations/live-update.json
  • contracts/fixtures/newsletter-observations/milestone-channel.json
  • contracts/fixtures/newsletter-observations/milestone.json
  • contracts/newsletter-observations.json
  • internal/agent-sessions/2026-10-28-sdk366-main-refresh.md
  • package.json
  • packages/dotnet/README.md
  • packages/dotnet/coverage.json
  • packages/dotnet/src/Polymorfa.Sdk/Channels.cs
  • packages/dotnet/src/Polymorfa.Sdk/WebhookPayloads.cs
  • packages/dotnet/tests/Polymorfa.Sdk.Tests/NewsletterObservationTests.cs
  • packages/dotnet/tests/Polymorfa.Sdk.Tests/Polymorfa.Sdk.Tests.csproj
  • packages/dotnet/tests/Polymorfa.Sdk.Tests/Program.cs
  • packages/go/README.md
  • packages/go/channels.go
  • packages/go/coverage.json
  • packages/go/newsletter_observations_test.go
  • packages/go/webhook_payloads.go
  • packages/php/README.md
  • packages/php/coverage.json
  • packages/php/src/ChannelModels.php
  • packages/php/src/WebhookEvent.php
  • packages/php/src/WebhookModels.php
  • packages/php/src/Webhooks.php
  • packages/php/tests/newsletter_observations.php
  • packages/php/tests/run.php
  • packages/php/tests/webhook_types.php
  • packages/python/README.md
  • packages/python/coverage.json
  • packages/python/src/polymorfa/channels.py
  • packages/python/src/polymorfa/webhook_models.py
  • packages/python/tests/test_newsletter_observations.py
  • packages/rust/README.md
  • packages/rust/coverage.json
  • packages/rust/src/channels.rs
  • packages/rust/src/webhook_payloads.rs
  • packages/rust/tests/newsletter_observations.rs
  • packages/typescript/README.md
  • packages/typescript/src/index.ts
  • packages/typescript/src/messaging/types.ts
  • packages/typescript/src/webhooks/events.ts
  • packages/typescript/src/webhooks/index.ts
  • packages/typescript/test/newsletter-observations.test.ts
  • packages/typescript/test/webhook-event-types.test.ts
  • scripts/check-newsletter-observations.mjs
  • scripts/doc-snippets/recipes.mjs

No actionable comments were generated in the recent review.

Walkthrough

The change adds an unpublished newsletter-observations contract and fixtures, typed support across six SDKs, optional channel-message forward counts, and fixture-based tests. It also adds a validation script and CI step.

Changes: Newsletter Observations

Layer / File(s) Summary
Contract and observation fixtures
contracts/newsletter-observations.json, contracts/fixtures/newsletter-observations/*, contracts/coverage.json
The contract defines newsletter update, message observation, view count, milestone, channel message, and identity shapes. Fixtures cover live updates, milestones, mute events, and channel messages.
SDK payload models and documentation
packages/dotnet/src/Polymorfa.Sdk/*, packages/go/*, packages/php/src/*, packages/python/src/polymorfa/*, packages/rust/src/*, packages/typescript/src/*, packages/{dotnet,go,php,python,rust,typescript}/README.md
Each SDK adds newsletter observation and milestone types, and an optional forwards field on channel messages. PHP also changes batch-member validation and preserves the original verified body for fixture creation.
Fixture validation and SDK test coverage
packages/{dotnet,go,php,python,rust,typescript}/tests/*, packages/typescript/test/*, scripts/check-newsletter-observations.mjs, package.json, .github/workflows/ci.yml, contracts/doc-snippets.json, scripts/doc-snippets/recipes.mjs, internal/agent-sessions/*
SDK tests cover signed event delivery, batch handling, fixture round-trips, and optional, zero, and empty values. The validation script checks the contract, fixtures, counterpart evidence, and coverage metadata; CI runs it.

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Possibly related PRs

  • polymorfa/sdks#350: Both changes update documentation-snippet provenance metadata tied to SDK source.
Merge Risk: Minimal · previous review c7af5

The change adds typed newsletter observation and milestone support across six SDKs, with fixtures, tests and a validation script. No concrete defect was established. Final-head hosted CI should still pass before merge, as the PR owner already requires.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: preserving typed newsletter channel observations and milestones across six SDKs. The changeset adds newsletter observation types, forwards, milestones, fixtures, and t…
Description check Passed The description follows the template's three areas: Summary, Verification, and Release status. The Summary states the SDK behavior change and the unchanged API baseline. Verification lists the checks …
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the main change: preserving typed newsletter channel observations and milestones across six SDKs. The changeset adds newsletter observation types, forwards, milestones, fixtures, and tests in TypeScript, Go, Python, PHP, Rust, and .NET, so the title matches the primary change. It is concise and uses the conventional feat(scope) format.

Full details: Description check

Explanation

The description follows the template's three areas: Summary, Verification, and Release status. The Summary states the SDK behavior change and the unchanged API baseline. Verification lists the checks that passed, the skipped fixture tests, the audit scope, and the required remaining CI and reviews. Release status states that no publication, deployment, or activation is claimed. The description includes a companion PR chain and dependency advisory links, which are extra but not harmful. The Summary is somewhat long for the template's 'keep this short' guidance, and the Verification section does not link a demo or evidence artifact. These are minor gaps.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Team
  • Run ID: b1049ded-84bd-483d-b261-f8592997feb3
Commits

Reviewing files that changed from the base of the PR and between ccc8eeb and c7af5b0.

Files selected for processing: 51

  • .github/workflows/ci.yml
  • contracts/coverage.json
  • contracts/doc-snippets.json
  • contracts/fixtures/newsletter-observations/channel-message.json
  • contracts/fixtures/newsletter-observations/delivery.json
  • contracts/fixtures/newsletter-observations/live-update.json
  • contracts/fixtures/newsletter-observations/milestone-channel.json
  • contracts/fixtures/newsletter-observations/milestone.json
  • contracts/newsletter-observations.json
  • internal/agent-sessions/2026-10-28-sdk366-main-refresh.md
  • package.json
  • packages/dotnet/README.md
  • packages/dotnet/coverage.json
  • packages/dotnet/src/Polymorfa.Sdk/Channels.cs
  • packages/dotnet/src/Polymorfa.Sdk/WebhookPayloads.cs
  • packages/dotnet/tests/Polymorfa.Sdk.Tests/NewsletterObservationTests.cs
  • packages/dotnet/tests/Polymorfa.Sdk.Tests/Polymorfa.Sdk.Tests.csproj
  • packages/dotnet/tests/Polymorfa.Sdk.Tests/Program.cs
  • packages/go/README.md
  • packages/go/channels.go
  • packages/go/coverage.json
  • packages/go/newsletter_observations_test.go
  • packages/go/webhook_payloads.go
  • packages/php/README.md
  • packages/php/coverage.json
  • packages/php/src/ChannelModels.php
  • packages/php/src/WebhookEvent.php
  • packages/php/src/WebhookModels.php
  • packages/php/src/Webhooks.php
  • packages/php/tests/newsletter_observations.php
  • packages/php/tests/run.php
  • packages/php/tests/webhook_types.php
  • packages/python/README.md
  • packages/python/coverage.json
  • packages/python/src/polymorfa/channels.py
  • packages/python/src/polymorfa/webhook_models.py
  • packages/python/tests/test_newsletter_observations.py
  • packages/rust/README.md
  • packages/rust/coverage.json
  • packages/rust/src/channels.rs
  • packages/rust/src/webhook_payloads.rs
  • packages/rust/tests/newsletter_observations.rs
  • packages/typescript/README.md
  • packages/typescript/src/index.ts
  • packages/typescript/src/messaging/types.ts
  • packages/typescript/src/webhooks/events.ts
  • packages/typescript/src/webhooks/index.ts
  • packages/typescript/test/newsletter-observations.test.ts
  • packages/typescript/test/webhook-event-types.test.ts
  • scripts/check-newsletter-observations.mjs
  • scripts/doc-snippets/recipes.mjs

Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 2 reviews per hour.

@purpshell
purpshell force-pushed the codex/pol81-newsletter-observations branch from 59ce77d to ca3ea79 Compare October 28, 2026 05:18
@purpshell
purpshell marked this pull request as ready for review October 31, 2026 04:46
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 31, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-12T09:44:50.484395Z f81237c Manual request
🔒 Security Review ✅ Completed 2026-11-12T09:47:12.294338Z f81237c Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Copy link
Copy Markdown
Member Author

@codex review

The human's November 5 workflow requires exhaustive current-head code review and paired security review before merge. Review the complete PR against actual main across TypeScript, Go, Python, PHP, Rust and .NET: optional/zero/empty observation semantics, typed milestones, native fixtures, omission/null/unknown values, credential/data boundaries and genuine catalog/source provenance. Accepted main is integrated without rebinding the API baseline or newsletter supplement. Report all remaining actionable findings. Additional local validation is waived; current-head hosted CI remains required.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Nice work!

Reviewed commit: a9ecdf87d7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@chatgpt-codex-connector

Copy link
Copy Markdown

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: a9ecdf87d7

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

  • You comment "@codex security review"
  • A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

Copy link
Copy Markdown
Member Author

@codex review

Please review the complete current PR and its paired security review at the current source, including the dependency-audit correction. The workspace override resolves both observed Firestore cleanup dependency routes with officially patched packages, retaining the existing Firestore version and public Node engines. Relevant formatting, lint, types, builds, tests, catalog drift check and the unchanged production audit command passed before this commit. Review all newsletter implementations/fixtures, genuine source/catalog provenance and dependency/engine compatibility. The human requires no remaining code/security findings before the complete stack merges.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Nice work!

Reviewed commit: 07bb625640

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@chatgpt-codex-connector

Copy link
Copy Markdown

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: 07bb625640

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

  • You comment "@codex security review"
  • A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

@purpshell

purpshell commented Nov 12, 2026 •

Copy link
Copy Markdown
Member Author

@codex review

Please review the current head f81237c1d4d04cf1d51f7cca0ce2e6b793ab228d.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Keep them coming!

Reviewed commit: f81237c1d4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@chatgpt-codex-connector

Copy link
Copy Markdown

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: f81237c1d4

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

  • You comment "@codex security review"
  • A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

Channel-level milestones such as follower counts (FOLLOWS) arrive without
a related post, so NewsletterMilestone.position is no longer required.
Rebind the newsletter supplement to polymorfa/polymorfa e292c7dc3f
(apps/api/docs/openapi.json) and add a no-position milestone fixture.

TypeScript, Go, Python, PHP, Rust and .NET now decode a missing position
without error and re-encode it as absent; each native test covers it.
# Conflicts:
#	contracts/doc-snippets.json
#	packages/php/src/WebhookModels.php
#	scripts/doc-snippets/recipes.mjs
@purpshell

Copy link
Copy Markdown
Member Author

Integration handoff to this PR's owner: I pushed this branch to edaf469d during the Nov 12 merge sweep (main merged, CI fixes, review threads answered; deferred P2s are in Linear). I'm no longer writing to it. It now conflicts with main ccc8eeba; so far conflicts have been snippet provenance (take main's side, then regenerate the export) plus small additive README/CHANGELOG edits. Final-head CI and a Codex review are still needed before merge.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant