@sudobility/consumables_service 0.0.8 → 0.0.9
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/CLAUDE.md +0 -8
- package/README.md +76 -0
- package/package.json +3 -3
package/CLAUDE.md
CHANGED
|
@@ -135,14 +135,6 @@ Dependency direction: `svgr_api` --> `consumables_service` (library dep); `consu
|
|
|
135
135
|
- **`db` is typed as `any`**: The ConsumablesHelper constructor accepts `db: any` to avoid version coupling with drizzle-orm. This sacrifices type safety for flexibility.
|
|
136
136
|
- **`recordPurchase` calls `getBalance` first**: This ensures the balance row exists before incrementing. The extra query is intentional for the get-or-create pattern.
|
|
137
137
|
|
|
138
|
-
## Testing
|
|
139
|
-
|
|
140
|
-
- Run tests: `bun test` (uses vitest)
|
|
141
|
-
- Tests use a **mock database** -- they do not connect to a real PostgreSQL instance.
|
|
142
|
-
- `ConsumablesHelper.test.ts` tests core business logic: balance get-or-create, purchase recording, usage recording, pagination, and idempotent webhook processing.
|
|
143
|
-
- `WebhookHelper.test.ts` tests HMAC signature validation and event parsing.
|
|
144
|
-
- When adding new helper methods, add corresponding tests with both success and failure cases (e.g., insufficient balance, duplicate webhook).
|
|
145
|
-
|
|
146
138
|
## Publishing
|
|
147
139
|
|
|
148
140
|
- Package: `@sudobility/consumables_service` (public on npm)
|
package/README.md
ADDED
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# @sudobility/consumables_service
|
|
2
|
+
|
|
3
|
+
Shared backend library for consumable credits management with Drizzle ORM and PostgreSQL.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
bun add @sudobility/consumables_service
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Usage
|
|
12
|
+
|
|
13
|
+
```typescript
|
|
14
|
+
import {
|
|
15
|
+
createConsumablesSchema,
|
|
16
|
+
ConsumablesHelper,
|
|
17
|
+
validateWebhookSignature,
|
|
18
|
+
parseConsumablePurchaseEvent,
|
|
19
|
+
} from '@sudobility/consumables_service';
|
|
20
|
+
|
|
21
|
+
// Create schema tables within your Drizzle PgSchema
|
|
22
|
+
const tables = createConsumablesSchema(mySchema);
|
|
23
|
+
|
|
24
|
+
// Initialize helper with DB and config
|
|
25
|
+
const helper = new ConsumablesHelper(db, tables, { initialFreeCredits: 3 });
|
|
26
|
+
|
|
27
|
+
// Core operations
|
|
28
|
+
const balance = await helper.getBalance(userId);
|
|
29
|
+
const updated = await helper.recordPurchase(userId, { credits: 25, source: 'web' });
|
|
30
|
+
const result = await helper.recordUsage(userId, 'logo.svg');
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## API
|
|
34
|
+
|
|
35
|
+
### Schema
|
|
36
|
+
|
|
37
|
+
| Export | Description |
|
|
38
|
+
|--------|-------------|
|
|
39
|
+
| `createConsumablesSchema(pgSchema)` | Creates `consumable_balances`, `consumable_purchases`, `consumable_usages` tables |
|
|
40
|
+
|
|
41
|
+
### ConsumablesHelper
|
|
42
|
+
|
|
43
|
+
| Method | Description |
|
|
44
|
+
|--------|-------------|
|
|
45
|
+
| `getBalance(userId)` | Get-or-create balance (auto-grants initial free credits) |
|
|
46
|
+
| `recordPurchase(userId, request)` | Record purchase + atomic balance increment |
|
|
47
|
+
| `recordUsage(userId, filename?)` | Atomic decrement with insufficient-balance guard |
|
|
48
|
+
| `getPurchaseHistory(userId, limit?, offset?)` | Paginated purchase audit trail |
|
|
49
|
+
| `getUsageHistory(userId, limit?, offset?)` | Paginated usage audit trail |
|
|
50
|
+
| `recordPurchaseFromWebhook(...)` | Idempotent webhook-driven purchase recording |
|
|
51
|
+
|
|
52
|
+
### Webhook Helpers
|
|
53
|
+
|
|
54
|
+
| Export | Description |
|
|
55
|
+
|--------|-------------|
|
|
56
|
+
| `validateWebhookSignature(rawBody, signature, secret)` | HMAC-SHA256 validation for RevenueCat webhooks |
|
|
57
|
+
| `parseConsumablePurchaseEvent(event)` | Extract purchase data from RevenueCat webhook events |
|
|
58
|
+
|
|
59
|
+
### Types
|
|
60
|
+
|
|
61
|
+
`ConsumableBalance`, `ConsumablePurchase`, `ConsumableUsage`, `RevenueCatWebhookEvent`, `ConsumablesConfig`
|
|
62
|
+
|
|
63
|
+
## Development
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
bun run build # Build ESM via tsc
|
|
67
|
+
bun run dev # Watch mode
|
|
68
|
+
bun test # Run tests (vitest, mock DB)
|
|
69
|
+
bun run typecheck # TypeScript check
|
|
70
|
+
bun run lint # ESLint
|
|
71
|
+
bun run verify # All checks + build (typecheck && lint && test && build)
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## License
|
|
75
|
+
|
|
76
|
+
BUSL-1.1
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sudobility/consumables_service",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.9",
|
|
4
4
|
"description": "Shared backend library for consumable credits management with Drizzle ORM",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -39,11 +39,11 @@
|
|
|
39
39
|
"author": "Sudobility",
|
|
40
40
|
"license": "BUSL-1.1",
|
|
41
41
|
"peerDependencies": {
|
|
42
|
-
"@sudobility/types": "^1.9.
|
|
42
|
+
"@sudobility/types": "^1.9.57",
|
|
43
43
|
"drizzle-orm": ">=0.44.0"
|
|
44
44
|
},
|
|
45
45
|
"devDependencies": {
|
|
46
|
-
"@sudobility/types": "^1.9.
|
|
46
|
+
"@sudobility/types": "^1.9.57",
|
|
47
47
|
"drizzle-orm": "^0.45.1",
|
|
48
48
|
"vitest": "^4.0.4",
|
|
49
49
|
"@types/bun": "latest",
|