@owlmeans/payment 0.1.2 → 0.1.4
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 +51 -491
- package/build/modules.d.ts +2 -2
- package/build/modules.d.ts.map +1 -1
- package/build/modules.js +9 -9
- package/build/modules.js.map +1 -1
- package/package.json +12 -11
- package/src/modules.ts +9 -9
- package/tsconfig.json +5 -10
package/README.md
CHANGED
|
@@ -1,524 +1,84 @@
|
|
|
1
1
|
# @owlmeans/payment
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Payment service abstraction — product catalog, subscription management, and Stripe checkout integration.
|
|
4
4
|
|
|
5
5
|
## Overview
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
- **Product Management**: Define and manage products with different types (simple, service)
|
|
12
|
-
- **Subscription Plans**: Create flexible pricing plans with various durations and trial periods
|
|
13
|
-
- **Subscription Lifecycle**: Handle subscription states from creation to cancellation
|
|
14
|
-
- **Multi-language Support**: Built-in internationalization for global applications
|
|
15
|
-
- **Capability-based Access**: Integration with OwlMeans auth system for permissions
|
|
16
|
-
- **Usage Tracking**: Monitor and limit resource consumption
|
|
17
|
-
- **Multiple Payment Gateways**: Support for various payment providers
|
|
18
|
-
- **Flexible Configuration**: Easy integration with OwlMeans configuration system
|
|
7
|
+
- `makePaymentService(alias?)` — creates a payment service for context registration
|
|
8
|
+
- `appendPaymentService(context, alias?)` — registers the payment service in the context
|
|
9
|
+
- `PaymentService` — interface for products, plans, subscriptions, and checkout session creation
|
|
10
|
+
- `CreateCheckoutBody` / `CreateCheckoutResponse` — request/response types for checkout
|
|
19
11
|
|
|
20
12
|
## Installation
|
|
21
13
|
|
|
22
14
|
```bash
|
|
23
|
-
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
### Peer Dependencies
|
|
27
|
-
|
|
28
|
-
This package requires the following peer dependencies:
|
|
29
|
-
|
|
30
|
-
```bash
|
|
31
|
-
npm install ajv
|
|
32
|
-
```
|
|
33
|
-
|
|
34
|
-
## Core Concepts
|
|
35
|
-
|
|
36
|
-
### Products
|
|
37
|
-
|
|
38
|
-
Products represent items or services that can be purchased. Each product has:
|
|
39
|
-
|
|
40
|
-
- **Type**: `simple` for physical/digital goods, `service` for software services
|
|
41
|
-
- **SKU**: Unique identifier for the product
|
|
42
|
-
- **Title & Description**: Human-readable information
|
|
43
|
-
- **Services**: Related software services
|
|
44
|
-
- **Capabilities**: Permission sets granted when purchased
|
|
45
|
-
|
|
46
|
-
### Plans
|
|
47
|
-
|
|
48
|
-
Plans define pricing and access terms for products:
|
|
49
|
-
|
|
50
|
-
- **Duration**: Monthly, yearly, lifetime, reusable, or consumable
|
|
51
|
-
- **Pricing**: Base price, currency, discounts, and original price
|
|
52
|
-
- **Trials**: Free trial periods (gated or open)
|
|
53
|
-
- **Capabilities**: Specific permissions granted
|
|
54
|
-
- **Limits**: Usage restrictions and quotas
|
|
55
|
-
|
|
56
|
-
### Subscriptions
|
|
57
|
-
|
|
58
|
-
Subscriptions represent active plan purchases:
|
|
59
|
-
|
|
60
|
-
- **Status**: Created, trial, active, canceled, expired, etc.
|
|
61
|
-
- **Dates**: Creation, start, expiration, and cancellation timestamps
|
|
62
|
-
- **Consumption**: Track usage against limits
|
|
63
|
-
- **Payment Method**: Associated payment gateway information
|
|
64
|
-
|
|
65
|
-
### Localization
|
|
66
|
-
|
|
67
|
-
Multi-language support for products, plans, and capabilities:
|
|
68
|
-
|
|
69
|
-
- **Language-specific**: Titles, descriptions, and keywords
|
|
70
|
-
- **Fallback Support**: Default language fallback system
|
|
71
|
-
- **Dynamic Loading**: Runtime language switching
|
|
72
|
-
|
|
73
|
-
## API Reference
|
|
74
|
-
|
|
75
|
-
### Types
|
|
76
|
-
|
|
77
|
-
#### Product
|
|
78
|
-
|
|
79
|
-
```typescript
|
|
80
|
-
interface Product {
|
|
81
|
-
type: ProductType // 'simple' | 'service'
|
|
82
|
-
sku: string // Unique product identifier
|
|
83
|
-
title: string // Product name
|
|
84
|
-
description?: string // Product description
|
|
85
|
-
defaultLng?: string // Default language code
|
|
86
|
-
services?: string[] // Related software services
|
|
87
|
-
capabilities?: PermissionSet[] // Granted permissions
|
|
88
|
-
}
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
#### ProductPlan
|
|
92
|
-
|
|
93
|
-
```typescript
|
|
94
|
-
interface ProductPlan {
|
|
95
|
-
productSku: string // Parent product SKU
|
|
96
|
-
sku: string // Unique plan identifier
|
|
97
|
-
status: PlanStatus // Plan availability status
|
|
98
|
-
duration: PlanDuration // Billing cycle
|
|
99
|
-
price: number // Plan price
|
|
100
|
-
currency?: string // Currency code (e.g., 'USD')
|
|
101
|
-
title: string // Plan name
|
|
102
|
-
description?: string // Plan description
|
|
103
|
-
|
|
104
|
-
// Trial configuration
|
|
105
|
-
trial?: number // Trial period in days
|
|
106
|
-
gatedTrial?: boolean // Requires payment method
|
|
107
|
-
|
|
108
|
-
// Pricing details
|
|
109
|
-
originalPrice?: number // Before discount
|
|
110
|
-
discount?: number // Discount percentage
|
|
111
|
-
highlight?: string // Special badge/label
|
|
112
|
-
|
|
113
|
-
// Scheduling
|
|
114
|
-
createdAt?: Date // Creation timestamp
|
|
115
|
-
archivedAt?: Date // Archive timestamp
|
|
116
|
-
deprecatedAt?: Date // Deprecation date
|
|
117
|
-
supsendedAt?: Date // Suspension date
|
|
118
|
-
|
|
119
|
-
// Access control
|
|
120
|
-
capabilities?: PermissionSet[] // Granted permissions
|
|
121
|
-
limits?: { [key: string]: LimitConfig } // Usage limits
|
|
122
|
-
|
|
123
|
-
// Payment gateway integration
|
|
124
|
-
payagateAliases?: { [paygate: string]: string }
|
|
125
|
-
}
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
#### PlanSubscription
|
|
129
|
-
|
|
130
|
-
```typescript
|
|
131
|
-
interface PlanSubscription {
|
|
132
|
-
sku: string // Plan SKU
|
|
133
|
-
entityId: string // Subscriber entity ID
|
|
134
|
-
status: SubscriptionStatus // Current status
|
|
135
|
-
|
|
136
|
-
// Timestamps
|
|
137
|
-
createdAt: Date // Creation time
|
|
138
|
-
startsdAt: Date // Start time
|
|
139
|
-
expirationAt?: Date // Expiration time
|
|
140
|
-
endsAt?: Date // End time
|
|
141
|
-
trialUntil?: Date // Trial end time
|
|
142
|
-
lastPaymentAt?: Date // Last payment time
|
|
143
|
-
|
|
144
|
-
// State management
|
|
145
|
-
canceledAt?: Date // Cancellation time
|
|
146
|
-
suspendedAt?: Date // Suspension time
|
|
147
|
-
suspendedUntil?: Date // Suspension end time
|
|
148
|
-
blockedAt?: Date // Block time
|
|
149
|
-
archiveAt?: Date // Archive time
|
|
150
|
-
|
|
151
|
-
// Payment integration
|
|
152
|
-
paymentMethod?: string // Payment method ID
|
|
153
|
-
externalId?: string // External payment system ID
|
|
154
|
-
|
|
155
|
-
// Access control
|
|
156
|
-
capabilities?: PermissionSet[] // Custom permissions
|
|
157
|
-
limits?: { [key: string]: LimitConfig } // Custom limits
|
|
158
|
-
consumptions?: { [key: string]: CapabilityUsage } // Usage tracking
|
|
159
|
-
}
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
#### Localization
|
|
163
|
-
|
|
164
|
-
```typescript
|
|
165
|
-
interface Localization {
|
|
166
|
-
sku: string // Entity SKU
|
|
167
|
-
type: PaymentEntityType // Entity type
|
|
168
|
-
lng: string // Language code
|
|
169
|
-
title?: string // Localized title
|
|
170
|
-
description?: string // Localized description
|
|
171
|
-
keywords?: { [key: string]: string } // Localized keywords
|
|
172
|
-
}
|
|
173
|
-
```
|
|
174
|
-
|
|
175
|
-
### Enums
|
|
176
|
-
|
|
177
|
-
#### ProductType
|
|
178
|
-
|
|
179
|
-
```typescript
|
|
180
|
-
enum ProductType {
|
|
181
|
-
Simple = 'simple', // Physical or digital goods
|
|
182
|
-
Service = 'service' // Software services
|
|
183
|
-
}
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
#### PlanStatus
|
|
187
|
-
|
|
188
|
-
```typescript
|
|
189
|
-
enum PlanStatus {
|
|
190
|
-
Active = 'active', // Available for purchase
|
|
191
|
-
Custom = 'custom', // Custom/negotiated plan
|
|
192
|
-
Hidden = 'hidden', // Hidden from public
|
|
193
|
-
Archived = 'archived', // No longer available
|
|
194
|
-
Deprecated = 'deprecated', // Will be removed
|
|
195
|
-
Suspended = 'suspended' // Temporarily unavailable
|
|
196
|
-
}
|
|
197
|
-
```
|
|
198
|
-
|
|
199
|
-
#### PlanDuration
|
|
200
|
-
|
|
201
|
-
```typescript
|
|
202
|
-
enum PlanDuration {
|
|
203
|
-
Monthly = 'monthly', // Monthly billing
|
|
204
|
-
Yearly = 'yearly', // Yearly billing
|
|
205
|
-
Lifetime = 'lifetime', // One-time payment
|
|
206
|
-
Reusable = 'reusable', // Can be used multiple times
|
|
207
|
-
Consumable = 'consumable' // Requires tokens/credits
|
|
208
|
-
}
|
|
209
|
-
```
|
|
210
|
-
|
|
211
|
-
#### SubscriptionStatus
|
|
212
|
-
|
|
213
|
-
```typescript
|
|
214
|
-
enum SubscriptionStatus {
|
|
215
|
-
Created = 'created', // Just created
|
|
216
|
-
Trial = 'trial', // In trial period
|
|
217
|
-
Active = 'active', // Active subscription
|
|
218
|
-
Canceled = 'canceled', // User canceled
|
|
219
|
-
Expired = 'expired', // Expired subscription
|
|
220
|
-
Suspended = 'suspended', // Temporarily suspended
|
|
221
|
-
Blocked = 'blocked', // Blocked by admin
|
|
222
|
-
Ended = 'ended', // Naturally ended
|
|
223
|
-
Free = 'free' // Free tier
|
|
224
|
-
}
|
|
225
|
-
```
|
|
226
|
-
|
|
227
|
-
### PaymentService
|
|
228
|
-
|
|
229
|
-
The main service interface for payment operations:
|
|
230
|
-
|
|
231
|
-
```typescript
|
|
232
|
-
interface PaymentService extends InitializedService {
|
|
233
|
-
// Get product by SKU
|
|
234
|
-
product(sku: string): Promise<Product>
|
|
235
|
-
|
|
236
|
-
// Get plans for a product and duration
|
|
237
|
-
plans(productSku: string, duration: PlanDuration): Promise<ProductPlan[]>
|
|
238
|
-
|
|
239
|
-
// Get localization for an entity
|
|
240
|
-
localize(lng: string, entity: PaymentEntity): Promise<Localization | null>
|
|
241
|
-
|
|
242
|
-
// Authenticate user from token
|
|
243
|
-
shallowAuthentication(token: string | null): Promise<string>
|
|
244
|
-
}
|
|
245
|
-
```
|
|
246
|
-
|
|
247
|
-
### Service Creation
|
|
248
|
-
|
|
249
|
-
```typescript
|
|
250
|
-
import { makePaymentService, appendPaymentService } from '@owlmeans/payment'
|
|
251
|
-
|
|
252
|
-
// Create payment service
|
|
253
|
-
const paymentService = makePaymentService('payment')
|
|
254
|
-
|
|
255
|
-
// Add to context
|
|
256
|
-
const contextWithPayment = appendPaymentService(context, 'payment')
|
|
257
|
-
```
|
|
258
|
-
|
|
259
|
-
### Usage Examples
|
|
260
|
-
|
|
261
|
-
#### Basic Product Management
|
|
262
|
-
|
|
263
|
-
```typescript
|
|
264
|
-
import { makePaymentService } from '@owlmeans/payment'
|
|
265
|
-
|
|
266
|
-
const paymentService = makePaymentService()
|
|
267
|
-
|
|
268
|
-
// Get a product
|
|
269
|
-
const product = await paymentService.product('premium-software')
|
|
270
|
-
|
|
271
|
-
// Get plans for monthly billing
|
|
272
|
-
const monthlyPlans = await paymentService.plans('premium-software', PlanDuration.Monthly)
|
|
273
|
-
|
|
274
|
-
// Get localization
|
|
275
|
-
const localization = await paymentService.localize('en', product)
|
|
15
|
+
bun add @owlmeans/payment
|
|
276
16
|
```
|
|
277
17
|
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
```typescript
|
|
281
|
-
import { Product, ProductType } from '@owlmeans/payment'
|
|
282
|
-
|
|
283
|
-
const product: Product = {
|
|
284
|
-
type: ProductType.Service,
|
|
285
|
-
sku: 'premium-service',
|
|
286
|
-
title: 'Premium Service',
|
|
287
|
-
description: 'Advanced features and priority support',
|
|
288
|
-
defaultLng: 'en',
|
|
289
|
-
services: ['api-service', 'analytics-service'],
|
|
290
|
-
capabilities: [
|
|
291
|
-
{ scope: 'premium', permissions: ['read', 'write'] }
|
|
292
|
-
]
|
|
293
|
-
}
|
|
294
|
-
```
|
|
18
|
+
## Usage
|
|
295
19
|
|
|
296
|
-
|
|
20
|
+
Create a checkout session:
|
|
297
21
|
|
|
298
22
|
```typescript
|
|
299
|
-
import {
|
|
23
|
+
import type { CreateCheckoutBody, CreateCheckoutResponse } from '@owlmeans/payment'
|
|
300
24
|
|
|
301
|
-
const
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
limits: {
|
|
313
|
-
'api-calls': {
|
|
314
|
-
interval: PlanDuration.Monthly,
|
|
315
|
-
limit: 10000,
|
|
316
|
-
measurment: 'requests'
|
|
317
|
-
}
|
|
318
|
-
}
|
|
319
|
-
}
|
|
25
|
+
const [result] = await ctx.module<ClientModule<CreateCheckoutResponse>>(
|
|
26
|
+
paymentApi.service.checkout.session.external.create
|
|
27
|
+
).call({
|
|
28
|
+
body: {
|
|
29
|
+
productSku: 'vib-tokens',
|
|
30
|
+
entityId,
|
|
31
|
+
service: VIB_ALIAS,
|
|
32
|
+
successUrl: helper.makeUrl(service)
|
|
33
|
+
} satisfies CreateCheckoutBody
|
|
34
|
+
})
|
|
35
|
+
window.open(result.url, '_blank')
|
|
320
36
|
```
|
|
321
37
|
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
### Context Integration
|
|
325
|
-
|
|
326
|
-
The payment service integrates with the OwlMeans context system:
|
|
38
|
+
Handle subscription propagation:
|
|
327
39
|
|
|
328
40
|
```typescript
|
|
329
|
-
import {
|
|
330
|
-
import { appendPaymentService } from '@owlmeans/payment'
|
|
331
|
-
|
|
332
|
-
const context = makeContext(config)
|
|
333
|
-
const paymentContext = appendPaymentService(context, 'payment')
|
|
334
|
-
```
|
|
335
|
-
|
|
336
|
-
### Resource Configuration
|
|
337
|
-
|
|
338
|
-
Products, plans, and localizations are stored as configuration records:
|
|
41
|
+
import { SubscriptionPropagateBody, PlanDuration, SubscriptionStatus } from '@owlmeans/payment'
|
|
339
42
|
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
const
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
// Localization record ID format
|
|
348
|
-
const l10nId = `${L10N_RECORD_PREFIX}:${type}:${sku}:${lng}`
|
|
349
|
-
```
|
|
350
|
-
|
|
351
|
-
## Error Handling
|
|
352
|
-
|
|
353
|
-
The package provides comprehensive error types for different scenarios:
|
|
354
|
-
|
|
355
|
-
### Error Hierarchy
|
|
356
|
-
|
|
357
|
-
```typescript
|
|
358
|
-
PaymentError // Base payment error
|
|
359
|
-
├── PaygateError // Payment gateway errors
|
|
360
|
-
│ ├── UnknownPaygate // Unknown payment gateway
|
|
361
|
-
│ └── PaygateMappingError // Gateway mapping issues
|
|
362
|
-
├── ProductError // Product-related errors
|
|
363
|
-
│ ├── UnknownProduct // Product not found
|
|
364
|
-
│ └── UnknownPlan // Plan not found
|
|
365
|
-
├── PaymentIdentificationError // Authentication issues
|
|
366
|
-
└── SubscriptionError // Subscription errors
|
|
367
|
-
└── UnknownSubscription // Subscription not found
|
|
368
|
-
```
|
|
369
|
-
|
|
370
|
-
### Error Usage
|
|
371
|
-
|
|
372
|
-
```typescript
|
|
373
|
-
import { UnknownProduct, PaymentIdentificationError } from '@owlmeans/payment'
|
|
374
|
-
|
|
375
|
-
try {
|
|
376
|
-
const product = await paymentService.product('invalid-sku')
|
|
377
|
-
} catch (error) {
|
|
378
|
-
if (error instanceof UnknownProduct) {
|
|
379
|
-
console.log('Product not found:', error.message)
|
|
43
|
+
const handler = handleBody<SubscriptionPropagateBody>(async (body, context) => {
|
|
44
|
+
if (body.status === SubscriptionStatus.Consumable) {
|
|
45
|
+
const tokens = body.capabilities?.find(
|
|
46
|
+
c => c.scope === PlanDuration.Consumable
|
|
47
|
+
)?.permissions.units ?? 0
|
|
48
|
+
await ctx.agentToken().topUpTokens(entityId, tokens * 1000)
|
|
380
49
|
}
|
|
381
|
-
}
|
|
50
|
+
})
|
|
382
51
|
```
|
|
383
52
|
|
|
384
|
-
##
|
|
385
|
-
|
|
386
|
-
### Built-in Translations
|
|
53
|
+
## API
|
|
387
54
|
|
|
388
|
-
|
|
55
|
+
### `makePaymentService(alias?): PaymentService`
|
|
389
56
|
|
|
390
|
-
|
|
391
|
-
// Plan durations
|
|
392
|
-
"plan.duration.monthly": "Monthly subscription"
|
|
393
|
-
"plan.duration.yearly": "Yearly subscription"
|
|
57
|
+
Creates the payment service.
|
|
394
58
|
|
|
395
|
-
|
|
396
|
-
"plan.trial.gated": "Free trial — {{days}} days"
|
|
397
|
-
"plan.trial.open": "No card required — {{days}} free trial"
|
|
59
|
+
### `PaymentService`
|
|
398
60
|
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
"action.subscribe": "Subscribe now"
|
|
406
|
-
```
|
|
61
|
+
- `product(sku): Promise<Product>` — get a product by SKU
|
|
62
|
+
- `products(): Promise<Product[]>` — list all products
|
|
63
|
+
- `plans(productSku, duration): Promise<ProductPlan[]>` — list plans for a product
|
|
64
|
+
- `plan(planSku): Promise<ProductPlan>` — get a plan by SKU
|
|
65
|
+
- `shallowAuthentication(token): Promise<string>` — shallow auth for payment flows
|
|
66
|
+
- `localize(lng, entity): Promise<Localization | null>` — get localized payment content
|
|
407
67
|
|
|
408
|
-
###
|
|
409
|
-
|
|
410
|
-
```typescript
|
|
411
|
-
import { Localization, PaymentEntityType } from '@owlmeans/payment'
|
|
412
|
-
|
|
413
|
-
const localization: Localization = {
|
|
414
|
-
sku: 'premium-service',
|
|
415
|
-
type: PaymentEntityType.Product,
|
|
416
|
-
lng: 'es',
|
|
417
|
-
title: 'Servicio Premium',
|
|
418
|
-
description: 'Características avanzadas y soporte prioritario',
|
|
419
|
-
keywords: {
|
|
420
|
-
'premium': 'premium',
|
|
421
|
-
'support': 'soporte'
|
|
422
|
-
}
|
|
423
|
-
}
|
|
424
|
-
```
|
|
425
|
-
|
|
426
|
-
## API Routes
|
|
427
|
-
|
|
428
|
-
The package provides pre-configured API routes:
|
|
429
|
-
|
|
430
|
-
### Subscription API
|
|
431
|
-
|
|
432
|
-
```typescript
|
|
433
|
-
import { modules } from '@owlmeans/payment'
|
|
434
|
-
|
|
435
|
-
// Available routes:
|
|
436
|
-
// GET /subscription - Base subscription endpoint
|
|
437
|
-
// POST /subscription/propogate - Propagate subscription changes
|
|
438
|
-
```
|
|
439
|
-
|
|
440
|
-
### Route Configuration
|
|
441
|
-
|
|
442
|
-
```typescript
|
|
443
|
-
import { paymentApi } from '@owlmeans/payment'
|
|
444
|
-
|
|
445
|
-
// API endpoint constants
|
|
446
|
-
paymentApi.subscription.base // 'payment-api:subscription'
|
|
447
|
-
paymentApi.subscription.propogate // 'payment-api:subscription:propogate'
|
|
448
|
-
```
|
|
449
|
-
|
|
450
|
-
## JSON Schema Validation
|
|
451
|
-
|
|
452
|
-
All data types include JSON Schema definitions for validation:
|
|
453
|
-
|
|
454
|
-
```typescript
|
|
455
|
-
import { ProductSchema, ProductPlanSchema, PlanSubscriptionSchema } from '@owlmeans/payment'
|
|
456
|
-
|
|
457
|
-
// Validate product data
|
|
458
|
-
const isValidProduct = ajv.validate(ProductSchema, productData)
|
|
459
|
-
|
|
460
|
-
// Validate plan data
|
|
461
|
-
const isValidPlan = ajv.validate(ProductPlanSchema, planData)
|
|
462
|
-
|
|
463
|
-
// Validate subscription data
|
|
464
|
-
const isValidSubscription = ajv.validate(PlanSubscriptionSchema, subscriptionData)
|
|
465
|
-
```
|
|
466
|
-
|
|
467
|
-
## Integration with Other OwlMeans Packages
|
|
468
|
-
|
|
469
|
-
### Dependencies
|
|
470
|
-
|
|
471
|
-
- `@owlmeans/auth` - Authentication and permissions
|
|
472
|
-
- `@owlmeans/basic-envelope` - Message envelope handling
|
|
473
|
-
- `@owlmeans/config` - Configuration management
|
|
474
|
-
- `@owlmeans/context` - Application context
|
|
475
|
-
- `@owlmeans/error` - Error handling
|
|
476
|
-
- `@owlmeans/i18n` - Internationalization
|
|
477
|
-
- `@owlmeans/module` - Module system
|
|
478
|
-
- `@owlmeans/resource` - Resource management
|
|
479
|
-
- `@owlmeans/route` - Route definitions
|
|
480
|
-
|
|
481
|
-
### Common Integration Patterns
|
|
482
|
-
|
|
483
|
-
```typescript
|
|
484
|
-
// With authentication
|
|
485
|
-
import { PermissionSet } from '@owlmeans/auth'
|
|
486
|
-
import { Product } from '@owlmeans/payment'
|
|
487
|
-
|
|
488
|
-
const product: Product = {
|
|
489
|
-
// ... other properties
|
|
490
|
-
capabilities: [
|
|
491
|
-
{ scope: 'premium', permissions: ['read', 'write'] }
|
|
492
|
-
]
|
|
493
|
-
}
|
|
494
|
-
|
|
495
|
-
// With configuration
|
|
496
|
-
import { fromConfigRecord } from '@owlmeans/config'
|
|
497
|
-
import { Product } from '@owlmeans/payment'
|
|
498
|
-
|
|
499
|
-
const product = fromConfigRecord<ConfigRecord, Product>(configRecord)
|
|
500
|
-
|
|
501
|
-
// With resources
|
|
502
|
-
import { ResourceRecord } from '@owlmeans/resource'
|
|
503
|
-
import { Product } from '@owlmeans/payment'
|
|
504
|
-
|
|
505
|
-
type ProductRecord = Product & ResourceRecord
|
|
506
|
-
```
|
|
507
|
-
|
|
508
|
-
## Best Practices
|
|
68
|
+
### Types
|
|
509
69
|
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
5. **Capabilities**: Define granular permissions for fine-grained access control
|
|
515
|
-
6. **Limits**: Set reasonable usage limits with appropriate intervals
|
|
516
|
-
7. **Trials**: Use gated trials for premium features, open trials for basic access
|
|
70
|
+
- `CreateCheckoutBody` — `{ productSku, entityId, service, successUrl?, cancelUrl? }`
|
|
71
|
+
- `CreateCheckoutResponse` — `{ url: string }`
|
|
72
|
+
- `SubscriptionPropagateBody` — extends `PlanSubscription`
|
|
73
|
+
- `PlanSubscription` — `{ sku, entityId, createdAt, status, capabilities? }`
|
|
517
74
|
|
|
518
|
-
|
|
75
|
+
### Enums
|
|
519
76
|
|
|
520
|
-
|
|
77
|
+
- `PlanDuration` — `Monthly`, `Yearly`, `Consumable`, etc.
|
|
78
|
+
- `SubscriptionStatus` — `Active`, `Consumable`, `Canceled`, etc.
|
|
79
|
+
- `ProductType` — product category enum
|
|
80
|
+
- `PaymentEntityType` — entity classification enum
|
|
521
81
|
|
|
522
|
-
##
|
|
82
|
+
## Related Packages
|
|
523
83
|
|
|
524
|
-
|
|
84
|
+
- [`@owlmeans/client-payment`](../client-payment) — client-side wrapper for browser contexts
|
package/build/modules.d.ts
CHANGED
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
export declare const modules: import("@owlmeans/
|
|
2
|
-
export declare const serviceModules: import("@owlmeans/
|
|
1
|
+
export declare const modules: import("@owlmeans/entrypoint").CommonEntrypoint[];
|
|
2
|
+
export declare const serviceModules: import("@owlmeans/entrypoint").CommonEntrypoint[];
|
|
3
3
|
//# sourceMappingURL=modules.d.ts.map
|
package/build/modules.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"modules.d.ts","sourceRoot":"","sources":["../src/modules.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,OAAO,
|
|
1
|
+
{"version":3,"file":"modules.d.ts","sourceRoot":"","sources":["../src/modules.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,OAAO,mDAgBnB,CAAA;AAED,eAAO,MAAM,cAAc,mDAkB1B,CAAA"}
|
package/build/modules.js
CHANGED
|
@@ -1,18 +1,18 @@
|
|
|
1
|
-
import { body, filter,
|
|
1
|
+
import { body, filter, entrypoint } from '@owlmeans/entrypoint';
|
|
2
2
|
import { route, backend, RouteMethod } from '@owlmeans/route';
|
|
3
3
|
import { paymentApi } from './consts.js';
|
|
4
4
|
import { SubscriptionPropagateBodySchema } from './model/subscription.js';
|
|
5
5
|
import { CreateCheckoutBodySchema } from './model/checkout.js';
|
|
6
6
|
export const modules = [
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
7
|
+
entrypoint(route(paymentApi.subscription.base, '/subscription', backend())),
|
|
8
|
+
entrypoint(route(paymentApi.subscription.propogate, '/propogate', backend(paymentApi.subscription.base, RouteMethod.POST)), filter(body(SubscriptionPropagateBodySchema))),
|
|
9
|
+
entrypoint(route(paymentApi.subscription.propagate, '/propagate', backend(paymentApi.subscription.base, RouteMethod.POST)), filter(body(SubscriptionPropagateBodySchema)))
|
|
10
10
|
];
|
|
11
11
|
export const serviceModules = [
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
12
|
+
entrypoint(route(paymentApi.service.base, '/payment-service', backend())),
|
|
13
|
+
entrypoint(route(paymentApi.service.checkout.base, '/checkout', backend(paymentApi.service.base))),
|
|
14
|
+
entrypoint(route(paymentApi.service.checkout.session.base, '/session', backend(paymentApi.service.checkout.base))),
|
|
15
|
+
entrypoint(route(paymentApi.service.checkout.session.external.base, '/external', backend(paymentApi.service.checkout.session.base))),
|
|
16
|
+
entrypoint(route(paymentApi.service.checkout.session.external.create, '/create', backend(paymentApi.service.checkout.session.external.base, RouteMethod.POST)), filter(body(CreateCheckoutBodySchema)))
|
|
17
17
|
];
|
|
18
18
|
//# sourceMappingURL=modules.js.map
|
package/build/modules.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"modules.js","sourceRoot":"","sources":["../src/modules.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,
|
|
1
|
+
{"version":3,"file":"modules.js","sourceRoot":"","sources":["../src/modules.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,+BAA+B,EAAE,MAAM,yBAAyB,CAAA;AACzE,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AAE9D,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3E,UAAU,CACR,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,CAC5D,UAAU,CAAC,YAAY,CAAC,IAAI,EAC5B,WAAW,CAAC,IAAI,CACjB,CAAC,EACF,MAAM,CAAC,IAAI,CAAC,+BAA+B,CAAC,CAAC,CAC9C;IACD,UAAU,CACR,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,CAC5D,UAAU,CAAC,YAAY,CAAC,IAAI,EAC5B,WAAW,CAAC,IAAI,CACjB,CAAC,EACF,MAAM,CAAC,IAAI,CAAC,+BAA+B,CAAC,CAAC,CAC9C;CACF,CAAA;AAED,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,CAAC,CAAC;IACzE,UAAU,CACR,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CACvF;IACD,UAAU,CACR,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CACvG;IACD,UAAU,CACR,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CACzH;IACD,UAAU,CACR,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAC3E,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,EACjD,WAAW,CAAC,IAAI,CACjB,CAAC,EACF,MAAM,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC,CACvC;CACF,CAAA"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@owlmeans/payment",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.4",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"scripts": {
|
|
@@ -31,20 +31,21 @@
|
|
|
31
31
|
"ajv": "*"
|
|
32
32
|
},
|
|
33
33
|
"dependencies": {
|
|
34
|
-
"@owlmeans/auth": "^0.1.
|
|
35
|
-
"@owlmeans/basic-envelope": "^0.1.
|
|
36
|
-
"@owlmeans/config": "^0.1.
|
|
37
|
-
"@owlmeans/context": "^0.1.
|
|
38
|
-
"@owlmeans/error": "^0.1.
|
|
39
|
-
"@owlmeans/i18n": "^0.1.
|
|
40
|
-
"@owlmeans/
|
|
41
|
-
"@owlmeans/resource": "^0.1.
|
|
42
|
-
"@owlmeans/route": "^0.1.
|
|
34
|
+
"@owlmeans/auth": "^0.1.4",
|
|
35
|
+
"@owlmeans/basic-envelope": "^0.1.4",
|
|
36
|
+
"@owlmeans/config": "^0.1.4",
|
|
37
|
+
"@owlmeans/context": "^0.1.4",
|
|
38
|
+
"@owlmeans/error": "^0.1.4",
|
|
39
|
+
"@owlmeans/i18n": "^0.1.4",
|
|
40
|
+
"@owlmeans/entrypoint": "^0.1.4",
|
|
41
|
+
"@owlmeans/resource": "^0.1.4",
|
|
42
|
+
"@owlmeans/route": "^0.1.4"
|
|
43
43
|
},
|
|
44
44
|
"devDependencies": {
|
|
45
|
+
"@owlmeans/dep-config": "workspace:*",
|
|
45
46
|
"nodemon": "^3.1.11",
|
|
46
47
|
"npm-check": "^6.0.1",
|
|
47
|
-
"typescript": "^
|
|
48
|
+
"typescript": "^6.0.2"
|
|
48
49
|
},
|
|
49
50
|
"publishConfig": {
|
|
50
51
|
"access": "public"
|
package/src/modules.ts
CHANGED
|
@@ -1,19 +1,19 @@
|
|
|
1
|
-
import { body, filter,
|
|
1
|
+
import { body, filter, entrypoint } from '@owlmeans/entrypoint'
|
|
2
2
|
import { route, backend, RouteMethod } from '@owlmeans/route'
|
|
3
3
|
import { paymentApi } from './consts.js'
|
|
4
4
|
import { SubscriptionPropagateBodySchema } from './model/subscription.js'
|
|
5
5
|
import { CreateCheckoutBodySchema } from './model/checkout.js'
|
|
6
6
|
|
|
7
7
|
export const modules = [
|
|
8
|
-
|
|
9
|
-
|
|
8
|
+
entrypoint(route(paymentApi.subscription.base, '/subscription', backend())),
|
|
9
|
+
entrypoint(
|
|
10
10
|
route(paymentApi.subscription.propogate, '/propogate', backend(
|
|
11
11
|
paymentApi.subscription.base,
|
|
12
12
|
RouteMethod.POST
|
|
13
13
|
)),
|
|
14
14
|
filter(body(SubscriptionPropagateBodySchema))
|
|
15
15
|
),
|
|
16
|
-
|
|
16
|
+
entrypoint(
|
|
17
17
|
route(paymentApi.subscription.propagate, '/propagate', backend(
|
|
18
18
|
paymentApi.subscription.base,
|
|
19
19
|
RouteMethod.POST
|
|
@@ -23,17 +23,17 @@ export const modules = [
|
|
|
23
23
|
]
|
|
24
24
|
|
|
25
25
|
export const serviceModules = [
|
|
26
|
-
|
|
27
|
-
|
|
26
|
+
entrypoint(route(paymentApi.service.base, '/payment-service', backend())),
|
|
27
|
+
entrypoint(
|
|
28
28
|
route(paymentApi.service.checkout.base, '/checkout', backend(paymentApi.service.base)),
|
|
29
29
|
),
|
|
30
|
-
|
|
30
|
+
entrypoint(
|
|
31
31
|
route(paymentApi.service.checkout.session.base, '/session', backend(paymentApi.service.checkout.base)),
|
|
32
32
|
),
|
|
33
|
-
|
|
33
|
+
entrypoint(
|
|
34
34
|
route(paymentApi.service.checkout.session.external.base, '/external', backend(paymentApi.service.checkout.session.base)),
|
|
35
35
|
),
|
|
36
|
-
|
|
36
|
+
entrypoint(
|
|
37
37
|
route(paymentApi.service.checkout.session.external.create, '/create', backend(
|
|
38
38
|
paymentApi.service.checkout.session.external.base,
|
|
39
39
|
RouteMethod.POST
|
package/tsconfig.json
CHANGED
|
@@ -1,15 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"extends": [
|
|
3
|
-
"
|
|
3
|
+
"@owlmeans/dep-config/tsconfig.base.json"
|
|
4
4
|
],
|
|
5
5
|
"compilerOptions": {
|
|
6
|
-
"rootDir": "./src/",
|
|
7
|
-
"outDir": "./build/"
|
|
8
|
-
"moduleResolution": "Bundler"
|
|
6
|
+
"rootDir": "./src/",
|
|
7
|
+
"outDir": "./build/"
|
|
9
8
|
},
|
|
10
|
-
"exclude": [
|
|
11
|
-
|
|
12
|
-
"./build/**/*",
|
|
13
|
-
"./*.ts"
|
|
14
|
-
]
|
|
15
|
-
}
|
|
9
|
+
"exclude": ["./dist/**/*", "./build/**/*", "./*.ts"]
|
|
10
|
+
}
|