@volter/twin-polar 2.0.37 → 3.0.0

package/README.md

@@ -1,36 +1,33 @@
 # @volter/twin-polar
 
-Local Polar twin for app tests that need customer, checkout, subscription,
-meter, and usage-event behavior without real Polar credentials.
+The Polar twin (Protocol 3): Polar's API (`api.polar.sh`) derived from its own OpenAPI document (`spec/`, provenance
+in `spec/SOURCE.md`), scoped to what the applications that bill through Polar call
+([journeys/demand.json](./journeys/demand.json)): Volter's platform biller (twin-world `apps/billing`) and Open Autonomy's patronage.
 
-```bash
-bun packages/twin/polar/src/cli.ts
-```
+| area | served |
+|---|---|
+| catalog | meters (listed, made) and products (listed, made) |
+| checkout | checkouts made, listed and read back by id, and Polar's hosted checkout page (`buy.polar.sh/<client secret>`), which reads and confirms it (making the order and, for a recurring product, the subscription) |
+| customers | made, listed, read by id, their state (active subscriptions, meter usage) by external id, and a customer session and its pre-authenticated portal overview (subscriptions and purchase history) |
+| usage | events ingested and listed |
+| subscriptions | listed |
+| orders | listed (by checkout, customer, product, subscription, status), each paid order told by `order.created` and `order.paid` |
+| webhooks | checkout creation and order events delivered, signed with Standard Webhooks, to endpoints registered and listed through the API (`/v1/webhooks/endpoints`) |
 
-## Coverage
+Portal email sign-in, cancellation, invoice downloads and payment-method changes are outside this scope. Calendar-month subscription renewals and trial conversion run on the World clock; payments use deterministic test confirmation tokens and succeed. Fixed/custom paid checkouts require the client confirmation token; trial orders are deferred. Production and sandbox credentials and records are independent. Checkouts expire after 24 hours.
 
-The capability manifest (`src/polar-capabilities.ts`) is an honest partial denominator for Polar's
-merchant-of-record API. Coverage is partial and will read low as the denominator grows — see the
-manifest's `todo` entries for what is enumerated but not yet modeled.
+Every other operation of Polar's API is the gap (`src/manifest.ts` `unmodeled`, and the operations no handler serves).
 
-**Modeled:** customers, products, checkouts, subscriptions, orders, benefits, meters and
-usage-events, license keys, discounts, webhooks, OAuth, and the connector's pull/push.
+## Credentials
 
-**Out of scope** (each genuinely impossible for a local twin, with the reason recorded on the
-capability):
+An organization's operations take an Organization Access Token the World issued (held by its SHA-256); a customer
+portal operation takes a live customer session's token; the checkout's client operations take the checkout's client
+secret in their path (each operation's security schemes, from the spec's security as the derive keeps them). The World's application is issued its token when
+the World boots (`POST /_twin/app-credentials`, the descriptor's credential door), the same at every boot.
 
-- `polar.payments.real_processing` — a local twin must not contact or emulate real card networks;
-  it returns deterministic checkout/order shapes and "confirms" payment offline.
-- `polar.tax.real_calculation` — tax-authority integrations and live jurisdiction rules are
-  outside a deterministic local twin.
+## Doors
 
-### UI mirror — a tracked gap
-
-This pack ships **no mirror UI, and that is an unfinished gap rather than a decision.** Polar is a
-merchant-of-record billing product with a real operator dashboard — the same shape as `stripe`,
-which does mirror — so under the rule in
-[../../../docs/contributing/adding-a-twin.md](../../../docs/contributing/adding-a-twin.md) ("Does this vendor get a mirror?") it
-should have one. The work is tracked in the manifest as `polar.mirror.ui`
-(operator mirror for customers/subscriptions/orders/events).
-
-Do **not** cite this pack as precedent for omitting a mirror.
+- `POST /_twin/access-tokens {comment, expires_in_days?}` and `DELETE /_twin/access-tokens/{n}`: tokens (including their returned id) made and revoked
+  on the settings page.
+- `POST /_twin/app-credentials`: the application's token.
+- `GET /_twin/deliveries?to=&type=`: every webhook sent, as the receiving server got it.

package/dist/generated/pack-facts.json

@@ -0,0 +1,69 @@
+{
+  "//": "GENERATED by scripts/pack-facts.ts — current pack descriptors and explicit world-runtime server backings; no prior-artifact entries are retained.",
+  "packs": {
+    "polar": {
+      "adoption": {
+        "sdks": [
+          "@polar-sh/sdk"
+        ],
+        "pypi": [
+          "polar-sdk"
+        ],
+        "scopes": [
+          "@polar-sh/"
+        ],
+        "envStems": [
+          "POLAR"
+        ]
+      },
+      "hosts": [
+        {
+          "host": "api.polar.sh"
+        },
+        {
+          "host": "sandbox-api.polar.sh"
+        },
+        {
+          "host": "buy.polar.sh"
+        },
+        {
+          "host": "polar.sh",
+          "pathPattern": "^/[^/]+/portal"
+        },
+        {
+          "host": "sandbox.polar.sh"
+        }
+      ],
+      "archetype": "crud",
+      "protocol": {
+        "declared": "3",
+        "major": 3,
+        "standing": "current"
+      },
+      "transport": "rest",
+      "resources": [
+        "customer",
+        "product",
+        "checkout",
+        "subscription",
+        "order",
+        "event",
+        "meter",
+        "customer_session",
+        "webhook_endpoint"
+      ],
+      "endpointEnvNone": "@polar-sh/sdk reads no base-URL variable: its `server` option picks production or sandbox, both claimed by the host rules.",
+      "credentialDoor": {
+        "path": "/_twin/app-credentials",
+        "body": {},
+        "fill": {
+          "POLAR_ACCESS_TOKEN": "access_token",
+          "POLAR_API_KEY": "access_token",
+          "POLAR_ORGANIZATION_TOKEN": "access_token"
+        }
+      },
+      "serveExport": "createPolarTwinServer"
+    }
+  },
+  "undeclared": []
+}

package/dist/journeys/coverage.json

@@ -0,0 +1,223 @@
+{
+  "vendor": "polar",
+  "missing": 27,
+  "stale": [],
+  "code": {
+    "lines": 763,
+    "run": 750,
+    "recorded": 2,
+    "missing": 11
+  },
+  "state": {
+    "declared": 9,
+    "reached": 2,
+    "recorded": 0,
+    "missing": [
+      "refusal Checkout.status: checkouts:client_confirm confirmed|succeeded|failed|expired → (stays)",
+      "move Checkout.status: vendor confirmed → succeeded",
+      "move Checkout.status: time open → expired",
+      "refusal Subscription.status: checkouts:client_confirm active|trialing → (stays)",
+      "move Subscription.status: vendor incomplete → active",
+      "move Subscription.status: vendor incomplete → trialing",
+      "move Subscription.status: time trialing → active"
+    ],
+    "undeclared": [
+      "Checkout.status: confirmed → succeeded by checkout.update",
+      "Checkout.status: confirmed → succeeded by checkouts:client_confirm",
+      "Checkout.status: open → expired by checkout.update",
+      "Order.status: pending → paid by checkouts:client_confirm",
+      "Order.status: pending → paid by order.pay",
+      "Subscription.status: incomplete → active by checkouts:client_confirm",
+      "Subscription.status: incomplete → active by subscription.activate",
+      "Subscription.status: incomplete → trialing by subscription.activate",
+      "Subscription.status: trialing → active by subscription.update"
+    ]
+  },
+  "files": [
+    {
+      "file": "semantics/doors.ts",
+      "lines": {
+        "found": 28,
+        "hit": 28
+      },
+      "missing": []
+    },
+    {
+      "file": "semantics/states.ts",
+      "lines": {
+        "found": 34,
+        "hit": 34
+      },
+      "missing": []
+    },
+    {
+      "file": "semantics/customers.ts",
+      "lines": {
+        "found": 34,
+        "hit": 32
+      },
+      "missing": [
+        {
+          "from": 60,
+          "to": 60,
+          "fn": "duplicateExternal"
+        },
+        {
+          "from": 66,
+          "to": 66,
+          "fn": "duplicateEmail"
+        }
+      ]
+    },
+    {
+      "file": "semantics/customer-sessions.ts",
+      "lines": {
+        "found": 7,
+        "hit": 7
+      },
+      "missing": []
+    },
+    {
+      "file": "semantics/webhooks.ts",
+      "lines": {
+        "found": 17,
+        "hit": 17
+      },
+      "missing": []
+    },
+    {
+      "file": "semantics/shared.ts",
+      "lines": {
+        "found": 245,
+        "hit": 236
+      },
+      "missing": [
+        {
+          "from": 331,
+          "to": 339,
+          "fn": "compareClause"
+        }
+      ]
+    },
+    {
+      "file": "semantics/around.ts",
+      "lines": {
+        "found": 12,
+        "hit": 12
+      },
+      "missing": []
+    },
+    {
+      "file": "semantics/products.ts",
+      "lines": {
+        "found": 34,
+        "hit": 34
+      },
+      "missing": []
+    },
+    {
+      "file": "semantics/orders.ts",
+      "lines": {
+        "found": 7,
+        "hit": 7
+      },
+      "missing": []
+    },
+    {
+      "file": "semantics/subscriptions.ts",
+      "lines": {
+        "found": 10,
+        "hit": 10
+      },
+      "missing": []
+    },
+    {
+      "file": "semantics/clock.ts",
+      "lines": {
+        "found": 17,
+        "hit": 17
+      },
+      "missing": []
+    },
+    {
+      "file": "semantics/events.ts",
+      "lines": {
+        "found": 37,
+        "hit": 37
+      },
+      "missing": []
+    },
+    {
+      "file": "semantics/index.ts",
+      "lines": {
+        "found": 27,
+        "hit": 27
+      },
+      "missing": []
+    },
+    {
+      "file": "semantics/tenant.ts",
+      "lines": {
+        "found": 2,
+        "hit": 2
+      },
+      "missing": []
+    },
+    {
+      "file": "semantics/checkouts.ts",
+      "lines": {
+        "found": 85,
+        "hit": 85
+      },
+      "missing": []
+    },
+    {
+      "file": "screens/checkout.ts",
+      "lines": {
+        "found": 21,
+        "hit": 21
+      },
+      "missing": []
+    },
+    {
+      "file": "screens/portal.ts",
+      "lines": {
+        "found": 13,
+        "hit": 13
+      },
+      "missing": []
+    },
+    {
+      "file": "manifest.ts",
+      "lines": {
+        "found": 101,
+        "hit": 101
+      },
+      "missing": []
+    },
+    {
+      "file": "index.ts",
+      "lines": {
+        "found": 7,
+        "hit": 7
+      },
+      "missing": []
+    },
+    {
+      "file": "server.ts",
+      "lines": {
+        "found": 4,
+        "hit": 2
+      },
+      "missing": []
+    },
+    {
+      "file": "fetch.ts",
+      "lines": {
+        "found": 21,
+        "hit": 21
+      },
+      "missing": []
+    }
+  ]
+}