@volter/twin-polar 2.0.37 → 3.0.0

package/dist/journeys/vendor-examples.verdict.json

@@ -0,0 +1,33 @@
+{
+  "sha256": "0e592340767893352c2e894c4624913d76081aef48ebffe8cedcae8d816e9532",
+  "plausible": true,
+  "bar": "829132787d94a2d4",
+  "judge": {
+    "agent": "Contributor 16",
+    "model": "GPT-6 (Codex)",
+    "review": "Independent read-only review, 2026-10-01; did not author these files"
+  },
+  "authors": [
+    "Contributor 39"
+  ],
+  "rounds": 1,
+  "ruledSteps": [
+    "fields",
+    "0",
+    "4",
+    "11"
+  ],
+  "rulings": "REJECTED. Exhaustive one-round review of original steps 0 through 11 against published requests, preconditions, effect checks, decided values, environments and the current bar.\nE1. Steps 0,4: create a distinct sandbox organization/token and the sandbox product as setup for the sandbox list; 4 must send that sandbox credential and assert its own sandbox state. The current step reuses the production token and product. Polar's API introduction and Sandbox Environment explicitly isolate data, users, tokens and organizations and state a production access token cannot be used in sandbox. Fix this twin isolation defect rather than using exampleDiffers/notReplayed to excuse it. Add the independent sandbox setup immediately after original 0, and retain production setup for the production examples.\nE2. Fields and step 11 (append after it): the inventory omits published operation requests already present in vendored spec paths[*][*].x-codeSamples, two equivalent SDK spellings per served operation. Transcribe and replay each distinct wire request (or explicitly cross-reference identical wire spellings): subscriptions:list, webhooks:list_webhook_endpoints, webhooks:create_webhook_endpoint, products:list, products:create, orders:list, checkouts:list, checkouts:create, checkouts:get, checkouts:client_get, checkouts:client_confirm, customers:list, customers:create, customers:get, customers:get_state_external, customer-sessions:create, events:list, events:ingest, meters:list, meters:create. The snippets include meters sorting=name; zero fixed-price daily product; checkout allow_discount_codes/require_billing_address/allow_trial/is_business_customer defaults; customer external_id=usr_1337,type=individual,email=customer@example.com; session return_url=https://example.com/account; event customer_id; webhook checkout.created. Keep published literals and flags unchanged; map only documented placeholder ids/secrets to captured setup values. For SDK confirm with empty body, use a free product precondition so no required Stripe confirmation token is being silently invented or omitted. Each new setup must only establish an example's precondition or verify its effect, with every value it decides asserted. Add setup/pay steps needed by order/subscription examples and effect read-backs for writes; no contrived refusals.\nE3. Fields and step 11 (same appended block): include additional requests on the already cited pages: API introduction's SDK customers.getStateExternal example and paged product request page=1&limit=100; checkout/session's customer-IP forwarding request (preserve customer_ip_address alongside products) and Python SDK checkout request (the older product_id/allow_discount_codes spelling contradicts the vendored create schema, so preserve it and document that vendor contradiction with exampleDiffers.status rather than altering it); event-ingestion's concrete ai_usage event with its model, request and token metadata, wrapped in the batch ingestion request. A rendered pagination illustration with ellipses is an abridged illustration, not literal JSON; record its condition (250 products,limit100 => max_page3) and implement it as a setup-backed pagination example if counting it, without pinning a guessed response.\nAll existing production SDK checkout, ad-hoc pricing, portal and ingestion request bodies and their present assertions were checked; no further defect found in their intended wire requests. Missing examples are not excused by the current tool enumerating only six doc-examples: Published examples requires all requests the vendor publishes for served operations. Sources: polar/spec/openapi.json.gz x-codeSamples at each named operation; https://polar.sh/docs/api-reference/introduction; https://polar.sh/docs/integrate/sandbox; https://polar.sh/docs/features/checkout/session; https://polar.sh/docs/features/usage-based-billing/event-ingestion; https://polar.sh/docs/features/customer-portal/navigate-customers.",
+  "doubts": [],
+  "applied": {
+    "from": "41277cb22a3fd5d943918952d5eaacb190bfc742b493814b7489ec22544510e8",
+    "wasPlausible": false,
+    "steps": [
+      "fields",
+      "0",
+      "4",
+      "11"
+    ],
+    "rulings": "REJECTED. Exhaustive one-round review of original steps 0 through 11 against published requests, preconditions, effect checks, decided values, environments and the current bar.\nE1. Steps 0,4: create a distinct sandbox organization/token and the sandbox product as setup for the sandbox list; 4 must send that sandbox credential and assert its own sandbox state. The current step reuses the production token and product. Polar's API introduction and Sandbox Environment explicitly isolate data, users, tokens and organizations and state a production access token cannot be used in sandbox. Fix this twin isolation defect rather than using exampleDiffers/notReplayed to excuse it. Add the independent sandbox setup immediately after original 0, and retain production setup for the production examples.\nE2. Fields and step 11 (append after it): the inventory omits published operation requests already present in vendored spec paths[*][*].x-codeSamples, two equivalent SDK spellings per served operation. Transcribe and replay each distinct wire request (or explicitly cross-reference identical wire spellings): subscriptions:list, webhooks:list_webhook_endpoints, webhooks:create_webhook_endpoint, products:list, products:create, orders:list, checkouts:list, checkouts:create, checkouts:get, checkouts:client_get, checkouts:client_confirm, customers:list, customers:create, customers:get, customers:get_state_external, customer-sessions:create, events:list, events:ingest, meters:list, meters:create. The snippets include meters sorting=name; zero fixed-price daily product; checkout allow_discount_codes/require_billing_address/allow_trial/is_business_customer defaults; customer external_id=usr_1337,type=individual,email=customer@example.com; session return_url=https://example.com/account; event customer_id; webhook checkout.created. Keep published literals and flags unchanged; map only documented placeholder ids/secrets to captured setup values. For SDK confirm with empty body, use a free product precondition so no required Stripe confirmation token is being silently invented or omitted. Each new setup must only establish an example's precondition or verify its effect, with every value it decides asserted. Add setup/pay steps needed by order/subscription examples and effect read-backs for writes; no contrived refusals.\nE3. Fields and step 11 (same appended block): include additional requests on the already cited pages: API introduction's SDK customers.getStateExternal example and paged product request page=1&limit=100; checkout/session's customer-IP forwarding request (preserve customer_ip_address alongside products) and Python SDK checkout request (the older product_id/allow_discount_codes spelling contradicts the vendored create schema, so preserve it and document that vendor contradiction with exampleDiffers.status rather than altering it); event-ingestion's concrete ai_usage event with its model, request and token metadata, wrapped in the batch ingestion request. A rendered pagination illustration with ellipses is an abridged illustration, not literal JSON; record its condition (250 products,limit100 => max_page3) and implement it as a setup-backed pagination example if counting it, without pinning a guessed response.\nAll existing production SDK checkout, ad-hoc pricing, portal and ingestion request bodies and their present assertions were checked; no further defect found in their intended wire requests. Missing examples are not excused by the current tool enumerating only six doc-examples: Published examples requires all requests the vendor publishes for served operations. Sources: polar/spec/openapi.json.gz x-codeSamples at each named operation; https://polar.sh/docs/api-reference/introduction; https://polar.sh/docs/integrate/sandbox; https://polar.sh/docs/features/checkout/session; https://polar.sh/docs/features/usage-based-billing/event-ingestion; https://polar.sh/docs/features/customer-portal/navigate-customers."
+  }
+}

package/dist/spec/SOURCE.md

@@ -0,0 +1,25 @@
+# Polar API spec — provenance
+
+- **File:** `openapi.json.gz`, Polar's own OpenAPI document, the vendor's bytes unchanged and gzipped (`gzip -9 -n`):
+  OpenAPI 3.1.0, `info.title` "Polar API", `info.version` `2026-04`, 2,691,391 bytes, 186 operations across 127 paths,
+  served at `https://api.polar.sh` (production) and `https://sandbox-api.polar.sh` (sandbox).
+- **Upstream:** https://polar.sh/docs/openapi.json, fetched 2026-09-29 (the document Polar's API reference is built
+  from; the same URL the retired census fixture was cut from on 2026-09-02).
+- **SHA-256 of the vendor's bytes** (uncompressed): `b5fafab90f8de4ef5cd839217229b934b6ff8862614055e6010dc03d5f8d15d7`.
+- **Corrections:** none yet (no `patches.json`).
+- **Read by:** `bun scripts/derive-pack.ts polar`, which writes `../src/generated/`.
+
+
+Published reference pages read for semantics and examples (2026-10-01):
+- https://polar.sh/docs/api-reference/introduction (production/sandbox product lists, paging and allowances).
+- https://polar.sh/docs/features/checkout/session (SDK checkout and ad-hoc prices).
+- https://polar.sh/docs/features/customer-portal and its navigate-customers page (pre-authenticated portal).
+- https://polar.sh/docs/features/subscriptions/introduction and trials (calendar renewals and deferred trial charge).
+- https://polar.sh/docs/features/usage-based-billing/event-ingestion and meters (immutable events, filters and aggregation).
+- https://polar.sh/docs/integrate/customer-state (the current customer state).
+`doc-examples.json` transcribes published requests; the API reference pages embed this same OpenAPI document and publish no operation response samples. `sources.json` records checked rule citations. The ingestion SDK example's `<value>` name and `<id>` external customer are placeholders; its metadata key/value stays literal.
+
+Reviewed primary implementation for checkout TTL and event ingestion, 2026-10-01:
+- https://github.com/polarsource/polar/blob/main/server/polar/config.py and models/checkout.py (24-hour expiry).
+- https://github.com/polarsource/polar/blob/main/server/polar/event/service.py (batch ingestion does not create unresolved customers).
+The spec's x-codeSamples have two equivalent SDK spellings per served operation; doc-examples records each distinct wire request and cross-references both spellings.