better-auth-streampay 0.2.0 → 1.0.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/README.md CHANGED
@@ -1,17 +1,17 @@
1
1
  # better-auth-streampay
2
2
 
3
- > **Community plugin — not affiliated with Stream or StreamPay.** For plugin bugs, [open an issue here](https://github.com/y0u-0/better-auth-streampay/issues). For StreamPay bugs, contact [Stream support](https://streampay.sa).
3
+ > **Community plugin — not affiliated with Stream or StreamPay.** For plugin bugs, [open an issue here](https://github.com/Genie-sa/better-auth-streampay/issues). For StreamPay bugs, contact [Stream support](https://streampay.sa).
4
4
 
5
5
  A [Better Auth](https://better-auth.com) plugin for integrating [StreamPay](https://streampay.sa) payments and subscriptions into your authentication flow.
6
6
 
7
7
  ## Features
8
8
 
9
- - Checkout Integration
9
+ - Checkout Integration (lazy-creates a StreamPay consumer on first payment)
10
10
  - Consumer Portal (subscriptions, invoices, payments)
11
11
  - Subscription Management (cancel, freeze)
12
- - Automatic Consumer creation on signup
12
+ - Optional eager consumer creation on signup (`createConsumerOnSignUp: true`)
13
13
  - Handle StreamPay Webhooks securely with HMAC-SHA256 signature verification
14
- - Consumer sync on user update/delete
14
+ - Consumer sync on user update/delete (when eager mode is on)
15
15
 
16
16
  ## Installation
17
17
 
@@ -59,7 +59,9 @@ const auth = betterAuth({
59
59
  plugins: [
60
60
  streampay({
61
61
  client: streamPayClient,
62
- createConsumerOnSignUp: true,
62
+ // createConsumerOnSignUp defaults to false: consumers are created
63
+ // lazily at first checkout or subscription mutation. Set to `true`
64
+ // to provision a StreamPay consumer at signup instead.
63
65
  use: [
64
66
  checkout({
65
67
  products: [
@@ -120,15 +122,19 @@ npx prisma migrate dev # Prisma
120
122
 
121
123
  | Option | Type | Description |
122
124
  | ------------------------- | ---------- | ------------------------------------------------------------------ |
123
- | `createConsumerOnSignUp` | `boolean` | Automatically create a StreamPay consumer when a user signs up |
125
+ | `createConsumerOnSignUp` | `boolean` | Create a StreamPay consumer eagerly at signup. Default: `false` (lazy — consumer is created on first checkout / subscription mutation). |
124
126
  | `claimExistingConsumerBy` | `("email" \| "phone")[]` | Reclaim a duplicate linked consumer by the listed identifier(s) |
125
127
  | `getConsumerCreateParams` | `function` | Provide additional consumer fields (phone, language, IBAN, etc.) |
126
128
 
127
129
  ### Consumers
128
130
 
129
- When `createConsumerOnSignUp` is enabled, a new StreamPay Consumer is automatically created when a new user signs up. All consumers are created with an `external_id` matching the user's database ID — no mapping table needed. The resulting consumer ID is stored as `streampayConsumerId` on the user row.
131
+ **Lazy by default (`createConsumerOnSignUp: false`).** A StreamPay Consumer is created on demand the first time an authenticated user hits `/checkout` or a subscription mutation — not at signup. This keeps the signup hot path off StreamPay and the consumer table free of users who never pay. It matches the convention used by every other Better Auth billing plugin (Stripe, Polar, Dodo Payments).
130
132
 
131
- If StreamPay rejects sign-up with `DUPLICATE_CONSUMER`, the plugin normally reuses only stranded consumers whose `external_id` is empty. If you set `claimExistingConsumerBy`, the plugin can also reuse an existing consumer that matches one of the listed identifiers even if it is already linked to a different `external_id`. The `after` hook then rewrites that `external_id` to the new Better Auth user id.
133
+ **Eager opt-in (`createConsumerOnSignUp: true`).** Set the flag to `true` to provision a StreamPay Consumer inside the signup transaction — useful when your product needs portal data (invoices, subscriptions) immediately after signup. The `before` hook aborts signup if StreamPay rejects, keeping the two systems atomic.
134
+
135
+ All consumers — lazy or eager — are created with `external_id` matching the user's database ID, so no mapping table is needed. The resulting consumer ID is stored as `streampayConsumerId` on the user row.
136
+
137
+ If StreamPay rejects with `DUPLICATE_CONSUMER`, the plugin normally reuses only stranded consumers whose `external_id` is empty. If you set `claimExistingConsumerBy`, the plugin can also reuse an existing consumer that matches one of the listed identifiers even if it is already linked to a different `external_id`. The `after` hook then rewrites that `external_id` to the new Better Auth user id.
132
138
 
133
139
  Claim modes:
134
140
  - omitted / `[]` — only reuse stranded consumers
@@ -138,16 +144,18 @@ Claim modes:
138
144
 
139
145
  > **Breaking in 0.2.0:** `claimExistingConsumerBy` now takes an array. Replace `"email"` → `["email"]`, `"phone"` → `["phone"]`, `"both"` → `["email", "phone"]`. `null` is no longer accepted — omit the option or pass `[]` to disable.
140
146
 
141
- Consumer data is also kept in sync:
147
+ Consumer data is kept in sync for any user with a linked `streampayConsumerId` — independent of `createConsumerOnSignUp`:
142
148
  - **User update** — name/email changes are synced to StreamPay
143
149
  - **User delete** — the StreamPay consumer is deleted
144
150
 
151
+ Users with no linked consumer (pre-first-payment in lazy mode, legacy pre-schema users) are skipped cheaply — there is no list-scan on the user-update hot path.
152
+
145
153
  #### Custom Consumer Fields
146
154
 
147
155
  ```typescript
148
156
  streampay({
149
157
  client: streamPayClient,
150
- createConsumerOnSignUp: true,
158
+ createConsumerOnSignUp: true, // opt into eager mode
151
159
  claimExistingConsumerBy: ["email", "phone"],
152
160
  getConsumerCreateParams: async ({ user }, request) => ({
153
161
  phone_number: "+966501234567",
@@ -158,6 +166,8 @@ streampay({
158
166
  });
159
167
  ```
160
168
 
169
+ `getConsumerCreateParams` also runs during lazy provisioning at checkout, so it applies in both modes.
170
+
161
171
  ## Checkout Plugin
162
172
 
163
173
  ```typescript
@@ -239,15 +249,18 @@ portal({ consumerLookupMaxPages: 20 });
239
249
  ### Client Usage
240
250
 
241
251
  ```typescript
242
- // Get consumer state
243
- const { data: consumer } = await authClient.state();
252
+ // Get consumer state — returns { hasConsumer, consumer }
253
+ const { data } = await authClient.state();
254
+ if (!data.hasConsumer) {
255
+ // User has not triggered lazy consumer creation yet — render "no billing activity" state
256
+ }
244
257
 
245
- // List subscriptions (paginated)
258
+ // List subscriptions — returns { hasConsumer, data, pagination }
246
259
  const { data: subs } = await authClient.subscriptions({
247
260
  query: { page: 1, limit: 20 },
248
261
  });
249
262
 
250
- // List invoices (paginated)
263
+ // List invoices
251
264
  const { data: invoices } = await authClient.invoices({
252
265
  query: { page: 1, limit: 20 },
253
266
  });
@@ -256,6 +269,8 @@ const { data: invoices } = await authClient.invoices({
256
269
  const { data: payments } = await authClient.payments();
257
270
  ```
258
271
 
272
+ > **Response shape:** portal reads never eagerly create a consumer. When a user has no StreamPay consumer yet, every read returns `200 OK` with `{ hasConsumer: false, data: [], pagination: null }` (or `consumer: null` for `/state`) instead of `404`. This is additive — the `data` / `consumer` / `pagination` fields keep their shape when `hasConsumer` is true.
273
+
259
274
  ## Subscriptions Plugin
260
275
 
261
276
  ```typescript
@@ -356,7 +371,6 @@ Webhooks are verified using HMAC-SHA256 with replay protection. The signature he
356
371
  | `state` | GET | `/consumer/state` | Required | `portal()` |
357
372
  | `subscriptions` | GET | `/consumer/subscriptions/list` | Required | `portal()` |
358
373
  | `invoices` | GET | `/consumer/invoices/list` | Required | `portal()` |
359
- | `payments` | GET | `/consumer/payments/list` | Required | `portal()` |
360
374
  | `cancelSubscription` | POST | `/consumer/subscriptions/cancel` | Required | `subscriptions()` |
361
375
  | `freezeSubscription` | POST | `/consumer/subscriptions/freeze` | Required | `subscriptions()` |
362
376
  | `streampayWebhooks` | POST | `/streampay/webhooks` | Signature | `webhooks()` |
package/dist/client.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { s as streampay } from './streampay-DeyntFo9.cjs';
1
+ import { s as streampay } from './streampay-DtFFwULq.cjs';
2
2
  import 'better-auth';
3
3
  import 'zod/v4/core';
4
4
  import 'zod';
package/dist/client.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { s as streampay } from './streampay-DeyntFo9.js';
1
+ import { s as streampay } from './streampay-DtFFwULq.js';
2
2
  import 'better-auth';
3
3
  import 'zod/v4/core';
4
4
  import 'zod';