better-auth-streampay 0.1.5 → 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,33 +122,41 @@ 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 |
124
- | `claimExistingConsumerBy` | `"email" \| "phone" \| "both" \| null` | Reclaim a duplicate linked consumer by the selected identifier(s) |
125
+ | `createConsumerOnSignUp` | `boolean` | Create a StreamPay consumer eagerly at signup. Default: `false` (lazy — consumer is created on first checkout / subscription mutation). |
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 the selected identifier 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
- - `null` / `undefined` — only reuse stranded consumers
135
- - `"email"` — reclaim duplicates that match the same email
136
- - `"phone"` — reclaim duplicates that match the same phone number
137
- - `"both"` — reclaim duplicates that match either email or phone
140
+ - omitted / `[]` — only reuse stranded consumers
141
+ - `["email"]` — reclaim duplicates that match the same email
142
+ - `["phone"]` — reclaim duplicates that match the same phone number
143
+ - `["email", "phone"]` — reclaim duplicates that match either email or phone
138
144
 
139
- Consumer data is also kept in sync:
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.
146
+
147
+ Consumer data is kept in sync for any user with a linked `streampayConsumerId` — independent of `createConsumerOnSignUp`:
140
148
  - **User update** — name/email changes are synced to StreamPay
141
149
  - **User delete** — the StreamPay consumer is deleted
142
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
+
143
153
  #### Custom Consumer Fields
144
154
 
145
155
  ```typescript
146
156
  streampay({
147
157
  client: streamPayClient,
148
- createConsumerOnSignUp: true,
149
- claimExistingConsumerBy: "both",
158
+ createConsumerOnSignUp: true, // opt into eager mode
159
+ claimExistingConsumerBy: ["email", "phone"],
150
160
  getConsumerCreateParams: async ({ user }, request) => ({
151
161
  phone_number: "+966501234567",
152
162
  preferred_language: "ar",
@@ -156,6 +166,8 @@ streampay({
156
166
  });
157
167
  ```
158
168
 
169
+ `getConsumerCreateParams` also runs during lazy provisioning at checkout, so it applies in both modes.
170
+
159
171
  ## Checkout Plugin
160
172
 
161
173
  ```typescript
@@ -237,15 +249,18 @@ portal({ consumerLookupMaxPages: 20 });
237
249
  ### Client Usage
238
250
 
239
251
  ```typescript
240
- // Get consumer state
241
- 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
+ }
242
257
 
243
- // List subscriptions (paginated)
258
+ // List subscriptions — returns { hasConsumer, data, pagination }
244
259
  const { data: subs } = await authClient.subscriptions({
245
260
  query: { page: 1, limit: 20 },
246
261
  });
247
262
 
248
- // List invoices (paginated)
263
+ // List invoices
249
264
  const { data: invoices } = await authClient.invoices({
250
265
  query: { page: 1, limit: 20 },
251
266
  });
@@ -254,6 +269,8 @@ const { data: invoices } = await authClient.invoices({
254
269
  const { data: payments } = await authClient.payments();
255
270
  ```
256
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
+
257
274
  ## Subscriptions Plugin
258
275
 
259
276
  ```typescript
@@ -354,7 +371,6 @@ Webhooks are verified using HMAC-SHA256 with replay protection. The signature he
354
371
  | `state` | GET | `/consumer/state` | Required | `portal()` |
355
372
  | `subscriptions` | GET | `/consumer/subscriptions/list` | Required | `portal()` |
356
373
  | `invoices` | GET | `/consumer/invoices/list` | Required | `portal()` |
357
- | `payments` | GET | `/consumer/payments/list` | Required | `portal()` |
358
374
  | `cancelSubscription` | POST | `/consumer/subscriptions/cancel` | Required | `subscriptions()` |
359
375
  | `freezeSubscription` | POST | `/consumer/subscriptions/freeze` | Required | `subscriptions()` |
360
376
  | `streampayWebhooks` | POST | `/streampay/webhooks` | Signature | `webhooks()` |
package/dist/client.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { s as streampay } from './streampay-CJUUF6VM.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-CJUUF6VM.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';