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 +29 -15
- package/dist/client.d.cts +1 -1
- package/dist/client.d.ts +1 -1
- package/dist/index.cjs +437 -288
- 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 -289
- package/dist/index.js.map +1 -1
- package/dist/{streampay-DeyntFo9.d.cts → streampay-DtFFwULq.d.cts} +297 -264
- package/dist/{streampay-DeyntFo9.d.ts → streampay-DtFFwULq.d.ts} +297 -264
- package/package.json +2 -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,15 +122,19 @@ npx prisma migrate dev # Prisma
|
|
|
120
122
|
|
|
121
123
|
| Option | Type | Description |
|
|
122
124
|
| ------------------------- | ---------- | ------------------------------------------------------------------ |
|
|
123
|
-
| `createConsumerOnSignUp` | `boolean` |
|
|
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
|
-
|
|
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
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
|
|
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
|
|
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
|
|
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
|
|
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
package/dist/client.d.ts
CHANGED