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 +37 -21
- package/dist/client.d.cts +1 -1
- package/dist/client.d.ts +1 -1
- package/dist/index.cjs +437 -289
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +434 -290
- package/dist/index.js.map +1 -1
- package/dist/{streampay-CJUUF6VM.d.cts → streampay-DtFFwULq.d.cts} +303 -269
- package/dist/{streampay-CJUUF6VM.d.ts → streampay-DtFFwULq.d.ts} +303 -269
- package/package.json +3 -2
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/
|
|
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
|
-
-
|
|
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:
|
|
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` |
|
|
124
|
-
| `claimExistingConsumerBy` | `"email" \| "phone"
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
135
|
-
- `"email"` — reclaim duplicates that match the same email
|
|
136
|
-
- `"phone"` — reclaim duplicates that match the same phone number
|
|
137
|
-
- `"
|
|
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
|
-
|
|
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: "
|
|
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
|
|
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
|
|
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
|
|
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
package/dist/client.d.ts
CHANGED