better-auth-streampay 3.4.0 → 3.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/client.d.cts +2 -2
- package/dist/client.d.ts +2 -2
- package/dist/index.cjs +385 -46
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +385 -47
- package/dist/index.js.map +1 -1
- package/dist/{streampay-CzZfiZvE.d.cts → streampay-CKPv2wFz.d.cts} +288 -157
- package/dist/{streampay-CzZfiZvE.d.ts → streampay-CKPv2wFz.d.ts} +288 -157
- package/docs/integration.md +51 -0
- package/docs/staging-validation.md +1 -0
- package/docs/state-machines.md +15 -2
- package/package.json +1 -1
|
@@ -40,6 +40,7 @@ Tests cover the plugin's implemented features, not every feature of the Stream p
|
|
|
40
40
|
| A retried webhook skips its lifecycle callback | Live sandbox subscription with a later cancellation write: on the original code a retried `SUBSCRIPTION_ACTIVATED` completed without a successful `onSubscriptionActivated`; with the fix the retry delivered it. See [state machines](state-machines.md#live-sandbox-evidence-for-f9-and-streampay-timing). |
|
|
41
41
|
| A renewal written by another event skips its callback | Live sandbox subscription renewed from cycle 4 to 5: on the original code a plan-update event that wrote cycle 5 first left `INVOICE_COMPLETED` with no `onSubscriptionRenewed`; with the fix it ran once. See [state machines](state-machines.md#live-sandbox-evidence-for-f9-and-streampay-timing). |
|
|
42
42
|
| Renewal evidence for an unlinked checkout is dropped | Live sandbox subscription at cycle 5 with only its checkout reservation: on 3.3.0 the completed renewal invoice left the reservation unlinked with no callback; with the fix it linked the reservation and reported the renewal once. See [state machines](state-machines.md#live-sandbox-evidence-for-f9-and-streampay-timing). |
|
|
43
|
+
| A subscription without a local reservation is never linked | Live sandbox: a plugin checkout whose reservation row is gone was linked by its real renewal event, an API-created subscription was linked through `resolveUnlinkedSubscription`, and the admin link endpoint linked an active subscription without callbacks. On 3.3.1 none were linked. See [state machines](state-machines.md#live-sandbox-evidence-for-f9-and-streampay-timing). |
|
|
43
44
|
| Checkout activates the wrong reservation | Known payment-link and consumer mismatches cannot bind a pending checkout. |
|
|
44
45
|
| Portal client sends the wrong HTTP method | The real Better Auth client sends POST for the documented no-argument session call. |
|
|
45
46
|
| Consumer lookup misses an existing account | Exact identity searches follow pagination; later-page failures and repeated provider pages fail instead of creating a duplicate consumer. |
|
package/docs/state-machines.md
CHANGED
|
@@ -73,13 +73,14 @@ overlay: StreamPay keeps reporting `ACTIVE` while a renewal payment is outstandi
|
|
|
73
73
|
| S5 | `billingStatus = past_due` and provider `ACTIVE` imply local `past_due`. | `reconcileProjectionAgainstExisting` (`reconcile.ts`), the renewal stale branch (`sync.ts`). |
|
|
74
74
|
| S6 | `providerUpdatedAt` never moves backwards. | `isOlderProviderState` (`reconcile.ts`). The webhook path throws and retries (`persistReconciledProjection`). The endpoint path keeps the newer local row (`persistSubscriptionProjection`). |
|
|
75
75
|
| S7 | Every lifecycle write is a CAS on `providerUpdatedAt`, `status`, `billingStatus`, and the correlation IDs. | `lifecycleWriteGuard` (`reconcile.ts`, includes `renewedCycleNumber`), used by `persistReconciledProjection`, `persistSubscriptionProjection`, and `handleRenewalEvidence`, which adds the period, cycle, and callback owner (F31). |
|
|
76
|
+
| S9 | A checkout link stamped with another `appId` never links, through any path. Otherwise a subscription with no row ID or payment-link match is linked only with ownership evidence: StreamPay bills a configured plan product, and a `user` reference exists with a compatible consumer, an organization or custom reference passes `resolveSubscriptionReference`, or the app's `resolveUnlinkedSubscription` (only for subscriptions without any plugin metadata) or an admin chose the reference. An admin link never displaces another slot holder. | `verifyUnlinkedOwnership`, `resolveUnlinkedCorrelation`, `linkSubscriptionToReference` (`sync.ts`). `SUBSCRIPTION_CREATED` and `SUBSCRIPTION_ACTIVATED` keep linking unverified organization and custom references with a warning (3.x compatibility). |
|
|
76
77
|
| S8 | A stale event loses its lifecycle effects (callback, `past_due`, timestamp stamps) only when the fresh provider snapshot contradicts it. | `providerStateConfirmsEvent` in `reconcileFromStreamPay`; the latest-invoice check in `handleRenewalEvidence` (`sync.ts`). |
|
|
77
78
|
|
|
78
79
|
### Transitions
|
|
79
80
|
|
|
80
81
|
| # | Trigger | From | To | Guard and code |
|
|
81
82
|
| --- | --- | --- | --- | --- |
|
|
82
|
-
| L1 | Paid checkout confirmed by webhook | `incomplete`, `incomplete_expired`, or no row | provider status | Signed metadata row ID, then a payment-link match, then the newest matching reservation (`reconcileFromStreamPay`). Renewal evidence that finds no linked row links a reservation owning the subscription's checkout link the same way, with the link's signed metadata (`linkCheckoutFromRenewalEvidence`, F28). Takes the slot from an unpaid holder (S4). The `/subscription/success` fallback also confirms, but only for an `incomplete` row that still holds its slot, matched by consumer, product, and link (`isCheckoutSubscriptionCandidate`). |
|
|
83
|
+
| L1 | Paid checkout confirmed by webhook | `incomplete`, `incomplete_expired`, or no row | provider status | Signed metadata row ID, then a payment-link match, then the newest matching reservation (`reconcileFromStreamPay`). Renewal evidence that finds no linked row links a reservation owning the subscription's checkout link the same way, with the link's signed metadata (`linkCheckoutFromRenewalEvidence`, F28). The row that owns the payment link, in any status, comes before the newest-reservation fallback; with no local row, S9 decides. Takes the slot from an unpaid holder (S4). The `/subscription/success` fallback also confirms, but only for an `incomplete` row that still holds its slot, matched by consumer, product, and link (`isCheckoutSubscriptionCandidate`). |
|
|
83
84
|
| L2 | `SUBSCRIPTION_CYCLE_RENEWAL_FAILED`, not stale | `active` | `past_due`, billing `past_due` | `sync.ts` |
|
|
84
85
|
| L3 | `INVOICE_COMPLETED` or `SUBSCRIPTION_CYCLE_RENEWED_SUCCESSFULLY`, not stale, or stale while its invoice is the provider's `COMPLETED` `latest_invoice` | `past_due` | `active`, billing `current` | `handleRenewalEvidence` (`sync.ts`) |
|
|
85
86
|
| L4 | Any other projection while billing is `past_due` | `past_due` | `past_due` | S5 |
|
|
@@ -332,6 +333,8 @@ PostgreSQL 17. Run the end-to-end tests on PostgreSQL with `STREAMPAY_E2E_DB=pos
|
|
|
332
333
|
| F26 | Low | 2 | A released reservation whose link stays payable (breaks C2). | Found by Gemini 4 Neon on re-review. A stale-replacement release read the reservation without a link; its own request saved the link before the release write landed. | A payable link without a live reservation, next to the replacement's link. | The release CAS compares the link ID it read |
|
|
333
334
|
| F27 | Medium | 6 | A renewal callback lock owned by a `completed` event. | Found by GPT-6.2 Astra in the final check of F21's fix. The discard completes the event, then the process stops before it clears the lock. | Every later renewal for that subscription retries until it dead-letters. | Renewal evidence releases a lock whose owning event is completed and continues in the same attempt, so the release cannot spend its last retry; it never queries a disabled inbox |
|
|
334
335
|
| F28 | Medium | 1, 6 | A paid checkout left `incomplete` and its renewals dropped, while every renewal event is `completed`. | The creation webhooks fail past StreamPay's retry window (or are delayed), and renewal evidence arrives first. `handleRenewalEvidence` found no linked row and returned. A later creation replay then started the renewal baseline at the current cycle. This was R11. | The customer has no access until someone replays the creation event, and `onSubscriptionRenewed` never runs for the cycles in between. Reproduced live; see below. | Renewal evidence links the reservation that owns the subscription's checkout link (StreamPay bills every cycle through it), and a first link at a later cycle starts the baseline at cycle 1. If a creation webhook links the row while the evidence is correlating, the evidence continues with that row (found by GPT-6.2 Astra and Gemini 4 Neon in review). Linking reuses the snapshot the evidence fetched, and the cycle-1 baseline applies only to a subscription's first link, never to a linked row that first learns its cycle number |
|
|
336
|
+
| F32 | Medium | 1 | A row for a reference this app does not have, or a paid checkout that fails to link on every delivery. | Pre-existing, raised in the design consultation. A creation webhook without a reservation created a row from metadata alone, so in a StreamPay organization shared by two apps, the other app's checkout created rows here and could release a local unpaid reservation in the same slot. When a released reservation (`incomplete_expired`) owned the payment link and the metadata had no row ID, the insert failed on the unique link ID. | Junk rows and slot interference across apps; a dead-lettered activation. | S9, and the link owner is linked before any insert |
|
|
337
|
+
| F33 | Medium | 1, 6 | A paid subscription that is never linked: a dashboard or API subscription, or a plugin checkout whose reservation row is gone. Every renewal completes without effect. | The rest of R11. Nothing tied the subscription to a local row except data the plugin did not check. | No access and no `onSubscriptionRenewed`, silently. | `resolveUnlinkedSubscription` (opt-in), recovery under S9 on renewal and creation events, and `adminLinkSubscription` for manual repair. GPT-6.2 Astra's implementation review found six bypasses and races (a foreign `appId` through row-ID or link-owner paths, the creation exception on other events, admin races, resolver plan and error handling); all fixed with regression tests. Reproduced live; see below |
|
|
335
338
|
| F14 | High | 6 | `renewedCycleNumber` rolled back after its callback ran, so a second renewal event delivers `onSubscriptionRenewed` again. | Found in review of the F13 fix. A customer endpoint (or webhook) reads the row, `INVOICE_COMPLETED` then advances the marker and runs the callback, and the endpoint write restores the old marker. Its CAS matched because the provider timestamp was unchanged. `SUBSCRIPTION_CYCLE_RENEWED_SUCCESSFULLY` then counted as a new renewal. | Duplicate per-cycle side effects. | Projections only initialize the marker, and every CAS includes it |
|
|
336
339
|
| F15 | Medium | 7 | A due-queue retry before its backoff, or an automatic retry of a dead letter. | Pre-existing. Two overlapping `processDueStreampayWebhookEvents` runs select the same row. The first claims it and fails. The second replayed by event ID, re-read the updated row, and claimed it again at once, even after it was dead-lettered. | Extra provider calls and callback runs, and dead letters leaving manual review. | The processor passes the selected attempt (`dueAttemptCount`); replay requires the row to still be that pending attempt and due, and the claim CAS includes `attemptCount` |
|
|
337
340
|
| F16 | Medium | 7 | A repaired event parked as unreplayable. | Found in review of F12. Replay reads a pending row without payload; a redelivery then claims it, stores its payload, fails, and schedules a retry; the stale parking write still matched `pending` and `lockedAt = null`. | The retry time is erased, so the due processor never retries the event. | Parking CAS includes `attemptCount` |
|
|
@@ -401,6 +404,16 @@ reservation that owns that link, as if every creation webhook had failed, then d
|
|
|
401
404
|
| 3.3.0 | `completed` | still `incomplete`, unlinked | none |
|
|
402
405
|
| With the fix | `completed` | `active`, linked to `a74dcc6a`, cycle 5 | one, for cycle 5 |
|
|
403
406
|
|
|
407
|
+
**F33.** `probe-unlinked-live.mjs` runs 3.3.1 and this change against real sandbox objects. All
|
|
408
|
+
StreamPay calls were read-only except one subscription created through the API (`7695025f`),
|
|
409
|
+
canceled afterwards.
|
|
410
|
+
|
|
411
|
+
| Case | Real object | 3.3.1 | With the fix |
|
|
412
|
+
| --- | --- | --- | --- |
|
|
413
|
+
| Plugin checkout whose reservation row is gone; the local user exists with the same consumer; real cycle-4 `INVOICE_COMPLETED` | `068838a9` | no row, no callback | linked, `active`, slot held, `onSubscriptionRenewed` once (cycle 4) |
|
|
414
|
+
| Subscription created through the StreamPay API (no link, no metadata); `SUBSCRIPTION_CREATED` | `7695025f` | no row | `resolveUnlinkedSubscription` called once; linked (`inactive`, no slot); `onSubscriptionCreated` once |
|
|
415
|
+
| Admin link of an `ACTIVE` cycle-5 subscription | `a74dcc6a` | endpoint 404 | 200, linked, `active`, slot held, no lifecycle callback |
|
|
416
|
+
|
|
404
417
|
**F10.** The sandbox exposes `latest_invoice` with `id` and `status` on the subscription, and a
|
|
405
418
|
paid invoice reads `COMPLETED` (subscription `39143aaa`). An invoice's `period_end` does not match
|
|
406
419
|
the subscription's (12 seconds apart), so the fix compares invoice IDs, not periods.
|
|
@@ -478,7 +491,7 @@ file covers F15 and F16; `tests/integration/review-findings.test.ts` covers F18
|
|
|
478
491
|
| R8 | Confirmed as F12 and fixed. Parked rather than dead-lettered, so StreamPay retries still count (W4). | |
|
|
479
492
|
| R9 | Confirmed as F13 and fixed. | |
|
|
480
493
|
| R10 | Confirmed as F17 and fixed. | |
|
|
481
|
-
| R11 |
|
|
494
|
+
| R11 | Fixed: F28, F32, and F33. A subscription that no rule links stays unlinked by design; `adminLinkSubscription` repairs it. | |
|
|
482
495
|
|
|
483
496
|
### Module consolidation findings
|
|
484
497
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "better-auth-streampay",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.5.0",
|
|
4
4
|
"description": "Community Better Auth plugin for StreamPay with consumers, checkout, portal, subscriptions, and signed webhooks. Not affiliated with Stream.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|