@owlmeans/payment 0.1.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/LICENSE +21 -0
- package/README.md +524 -0
- package/build/.gitkeep +0 -0
- package/build/consts.d.ts +62 -0
- package/build/consts.d.ts.map +1 -0
- package/build/consts.js +87 -0
- package/build/consts.js.map +1 -0
- package/build/errors.d.ts +42 -0
- package/build/errors.d.ts.map +1 -0
- package/build/errors.js +81 -0
- package/build/errors.js.map +1 -0
- package/build/helper.d.ts +3 -0
- package/build/helper.d.ts.map +1 -0
- package/build/helper.js +3 -0
- package/build/helper.js.map +1 -0
- package/build/i18n/en.json +39 -0
- package/build/i18n.d.ts +2 -0
- package/build/i18n.d.ts.map +1 -0
- package/build/i18n.js +4 -0
- package/build/i18n.js.map +1 -0
- package/build/index.d.ts +9 -0
- package/build/index.d.ts.map +1 -0
- package/build/index.js +8 -0
- package/build/index.js.map +1 -0
- package/build/model/index.d.ts +6 -0
- package/build/model/index.d.ts.map +1 -0
- package/build/model/index.js +6 -0
- package/build/model/index.js.map +1 -0
- package/build/model/localization.d.ts +4 -0
- package/build/model/localization.d.ts.map +1 -0
- package/build/model/localization.js +19 -0
- package/build/model/localization.js.map +1 -0
- package/build/model/plan.d.ts +4 -0
- package/build/model/plan.d.ts.map +1 -0
- package/build/model/plan.js +43 -0
- package/build/model/plan.js.map +1 -0
- package/build/model/product.d.ts +4 -0
- package/build/model/product.d.ts.map +1 -0
- package/build/model/product.js +17 -0
- package/build/model/product.js.map +1 -0
- package/build/model/subscription.d.ts +5 -0
- package/build/model/subscription.d.ts.map +1 -0
- package/build/model/subscription.js +46 -0
- package/build/model/subscription.js.map +1 -0
- package/build/model/utils.d.ts +5 -0
- package/build/model/utils.d.ts.map +1 -0
- package/build/model/utils.js +28 -0
- package/build/model/utils.js.map +1 -0
- package/build/modules.d.ts +2 -0
- package/build/modules.d.ts.map +1 -0
- package/build/modules.js +9 -0
- package/build/modules.js.map +1 -0
- package/build/service.d.ts +5 -0
- package/build/service.d.ts.map +1 -0
- package/build/service.js +71 -0
- package/build/service.js.map +1 -0
- package/build/types.d.ts +116 -0
- package/build/types.d.ts.map +1 -0
- package/build/types.js +2 -0
- package/build/types.js.map +1 -0
- package/build/utils/index.d.ts +2 -0
- package/build/utils/index.d.ts.map +1 -0
- package/build/utils/index.js +2 -0
- package/build/utils/index.js.map +1 -0
- package/build/utils/types.d.ts +7 -0
- package/build/utils/types.d.ts.map +1 -0
- package/build/utils/types.js +2 -0
- package/build/utils/types.js.map +1 -0
- package/package.json +52 -0
- package/src/consts.ts +100 -0
- package/src/errors.ts +102 -0
- package/src/helper.ts +5 -0
- package/src/i18n/en.json +39 -0
- package/src/i18n.ts +6 -0
- package/src/index.ts +9 -0
- package/src/model/index.ts +6 -0
- package/src/model/localization.ts +24 -0
- package/src/model/plan.ts +51 -0
- package/src/model/product.ts +21 -0
- package/src/model/subscription.ts +49 -0
- package/src/model/utils.ts +32 -0
- package/src/modules.ts +15 -0
- package/src/service.ts +95 -0
- package/src/types.ts +119 -0
- package/src/utils/index.ts +2 -0
- package/src/utils/types.ts +9 -0
- package/tsconfig.json +15 -0
- package/tsconfig.tsbuildinfo +1 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 OwlMeans Common — Fullstack typescript framework
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,524 @@
|
|
|
1
|
+
# @owlmeans/payment
|
|
2
|
+
|
|
3
|
+
A comprehensive payment system library that provides the foundational components for implementing payment functionality in OwlMeans applications. This package includes product management, subscription handling, localization support, and capability-based access control.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
The `@owlmeans/payment` package is part of the OwlMeans Common library ecosystem and provides essential abstractions for payment systems. It follows the OwlMeans package structure conventions and integrates seamlessly with other OwlMeans packages for authentication, configuration, resources, and internationalization.
|
|
8
|
+
|
|
9
|
+
### Key Features
|
|
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
|
|
19
|
+
|
|
20
|
+
## Installation
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npm install @owlmeans/payment
|
|
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)
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
#### Creating Products
|
|
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
|
+
```
|
|
295
|
+
|
|
296
|
+
#### Subscription Management
|
|
297
|
+
|
|
298
|
+
```typescript
|
|
299
|
+
import { PlanSubscription, SubscriptionStatus } from '@owlmeans/payment'
|
|
300
|
+
|
|
301
|
+
const subscription: PlanSubscription = {
|
|
302
|
+
sku: 'premium-monthly',
|
|
303
|
+
entityId: 'user-123',
|
|
304
|
+
status: SubscriptionStatus.Active,
|
|
305
|
+
createdAt: new Date(),
|
|
306
|
+
startsdAt: new Date(),
|
|
307
|
+
expirationAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
|
|
308
|
+
paymentMethod: 'stripe-card-456',
|
|
309
|
+
capabilities: [
|
|
310
|
+
{ scope: 'premium', permissions: ['read', 'write'] }
|
|
311
|
+
],
|
|
312
|
+
limits: {
|
|
313
|
+
'api-calls': {
|
|
314
|
+
interval: PlanDuration.Monthly,
|
|
315
|
+
limit: 10000,
|
|
316
|
+
measurment: 'requests'
|
|
317
|
+
}
|
|
318
|
+
}
|
|
319
|
+
}
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
## Configuration
|
|
323
|
+
|
|
324
|
+
### Context Integration
|
|
325
|
+
|
|
326
|
+
The payment service integrates with the OwlMeans context system:
|
|
327
|
+
|
|
328
|
+
```typescript
|
|
329
|
+
import { makeContext } from '@owlmeans/context'
|
|
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:
|
|
339
|
+
|
|
340
|
+
```typescript
|
|
341
|
+
// Product record ID format
|
|
342
|
+
const productId = `${PRODUCT_RECORD_PREFIX}:${productSku}`
|
|
343
|
+
|
|
344
|
+
// Plan record ID format
|
|
345
|
+
const planId = `${PLAN_RECORD_PREFIX}:${planSku}`
|
|
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)
|
|
380
|
+
}
|
|
381
|
+
}
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
## Internationalization
|
|
385
|
+
|
|
386
|
+
### Built-in Translations
|
|
387
|
+
|
|
388
|
+
The package includes English translations for common payment terms:
|
|
389
|
+
|
|
390
|
+
```typescript
|
|
391
|
+
// Plan durations
|
|
392
|
+
"plan.duration.monthly": "Monthly subscription"
|
|
393
|
+
"plan.duration.yearly": "Yearly subscription"
|
|
394
|
+
|
|
395
|
+
// Trial periods
|
|
396
|
+
"plan.trial.gated": "Free trial — {{days}} days"
|
|
397
|
+
"plan.trial.open": "No card required — {{days}} free trial"
|
|
398
|
+
|
|
399
|
+
// Highlights
|
|
400
|
+
"plan.highlight.best-value": "Best value!"
|
|
401
|
+
"plan.highlight.custom": "Tell us about your custom needs"
|
|
402
|
+
|
|
403
|
+
// Actions
|
|
404
|
+
"action.start": "Start now"
|
|
405
|
+
"action.subscribe": "Subscribe now"
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
### Custom Localization
|
|
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
|
|
509
|
+
|
|
510
|
+
1. **Product SKUs**: Use descriptive, URL-friendly SKUs
|
|
511
|
+
2. **Plan Structure**: Organize plans logically by product and duration
|
|
512
|
+
3. **Localization**: Provide fallback translations for all supported languages
|
|
513
|
+
4. **Error Handling**: Use specific error types for better debugging
|
|
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
|
|
517
|
+
|
|
518
|
+
## Contributing
|
|
519
|
+
|
|
520
|
+
This package is part of the OwlMeans Common library ecosystem. Follow the established patterns and conventions when extending functionality.
|
|
521
|
+
|
|
522
|
+
## License
|
|
523
|
+
|
|
524
|
+
See the main repository LICENSE file for details.
|
package/build/.gitkeep
ADDED
|
File without changes
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import type { JSONSchemaType } from 'ajv';
|
|
2
|
+
export declare enum ProductType {
|
|
3
|
+
Simple = "simple",
|
|
4
|
+
Service = "service"
|
|
5
|
+
}
|
|
6
|
+
export declare enum PaymentEntityType {
|
|
7
|
+
Product = "product",
|
|
8
|
+
Plan = "plan",
|
|
9
|
+
CapabilitySet = "capability-set"
|
|
10
|
+
}
|
|
11
|
+
export declare enum PlanStatus {
|
|
12
|
+
Active = "active",
|
|
13
|
+
Custom = "custom",
|
|
14
|
+
Hidden = "hidden",
|
|
15
|
+
Archived = "archived",
|
|
16
|
+
Deprecated = "deprecated",
|
|
17
|
+
Suspended = "suspended"
|
|
18
|
+
}
|
|
19
|
+
export declare enum PlanDuration {
|
|
20
|
+
Monthly = "monthly",
|
|
21
|
+
Yearly = "yearly",
|
|
22
|
+
Lifetime = "lifetime",
|
|
23
|
+
Reusable = "reusable",
|
|
24
|
+
/**
|
|
25
|
+
* It means it requires some tokens to be consumed to use the
|
|
26
|
+
* capability.
|
|
27
|
+
*/
|
|
28
|
+
Consumable = "consumable"
|
|
29
|
+
}
|
|
30
|
+
export declare enum SubscriptionStatus {
|
|
31
|
+
Created = "created",
|
|
32
|
+
Trial = "trial",
|
|
33
|
+
Canceled = "canceled",
|
|
34
|
+
Expired = "expired",
|
|
35
|
+
Suspended = "suspended",
|
|
36
|
+
Blocked = "blocked",
|
|
37
|
+
Ended = "ended",
|
|
38
|
+
Free = "free",
|
|
39
|
+
Active = "active"
|
|
40
|
+
}
|
|
41
|
+
export declare const ProductTypeSchema: JSONSchemaType<ProductType>;
|
|
42
|
+
export declare const PaymentEntityTypeSchema: JSONSchemaType<PaymentEntityType>;
|
|
43
|
+
export declare const PlanStatusSchema: JSONSchemaType<PlanStatus>;
|
|
44
|
+
export declare const PlanDurationSchema: JSONSchemaType<PlanDuration>;
|
|
45
|
+
export declare const SubscriptionStatusSchema: JSONSchemaType<SubscriptionStatus>;
|
|
46
|
+
export declare const ProductTitleSchema: JSONSchemaType<string>;
|
|
47
|
+
export declare const ProductDescriptionSchema: JSONSchemaType<string>;
|
|
48
|
+
export declare const LocalizationLngSchema: JSONSchemaType<string>;
|
|
49
|
+
export declare const PRODUCT_RECORD_TYPE = "product";
|
|
50
|
+
export declare const PRODUCT_RECORD_PREFIX = "product";
|
|
51
|
+
export declare const PLAN_RECORD_TYPE = "plan";
|
|
52
|
+
export declare const PLAN_RECORD_PREFIX = "plan";
|
|
53
|
+
export declare const L10N_RECORD_TYPE = "l10n";
|
|
54
|
+
export declare const L10N_RECORD_PREFIX = "l10n";
|
|
55
|
+
export declare const DEFAULT_ALIAS = "payment";
|
|
56
|
+
export declare const paymentApi: {
|
|
57
|
+
subscription: {
|
|
58
|
+
base: string;
|
|
59
|
+
propogate: string;
|
|
60
|
+
};
|
|
61
|
+
};
|
|
62
|
+
//# sourceMappingURL=consts.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,KAAK,CAAA;AAEzC,oBAAY,WAAW;IACrB,MAAM,WAAW;IACjB,OAAO,YAAY;CACpB;AAED,oBAAY,iBAAiB;IAC3B,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,aAAa,mBAAmB;CACjC;AAED,oBAAY,UAAU;IACpB,MAAM,WAAW;IACjB,MAAM,WAAW;IACjB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,UAAU,eAAe;IACzB,SAAS,cAAc;CACxB;AAED,oBAAY,YAAY;IACtB,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB;;;OAGG;IACH,UAAU,eAAe;CAC1B;AAED,oBAAY,kBAAkB;IAC5B,OAAO,YAAY;IACnB,KAAK,UAAU;IACf,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,SAAS,cAAc;IACvB,OAAO,YAAY;IACnB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED,eAAO,MAAM,iBAAiB,EAAE,cAAc,CAAC,WAAW,CAGzD,CAAA;AAED,eAAO,MAAM,uBAAuB,EAAE,cAAc,CAAC,iBAAiB,CAGrE,CAAA;AAED,eAAO,MAAM,gBAAgB,EAAE,cAAc,CAAC,UAAU,CAGvD,CAAA;AAED,eAAO,MAAM,kBAAkB,EAAE,cAAc,CAAC,YAAY,CAG3D,CAAA;AAED,eAAO,MAAM,wBAAwB,EAAE,cAAc,CAAC,kBAAkB,CAGvE,CAAA;AAED,eAAO,MAAM,kBAAkB,EAAE,cAAc,CAAC,MAAM,CAErD,CAAA;AAED,eAAO,MAAM,wBAAwB,EAAE,cAAc,CAAC,MAAM,CAE3D,CAAA;AAED,eAAO,MAAM,qBAAqB,EAAE,cAAc,CAAC,MAAM,CAExD,CAAA;AAED,eAAO,MAAM,mBAAmB,YAAY,CAAA;AAC5C,eAAO,MAAM,qBAAqB,YAAsB,CAAA;AAExD,eAAO,MAAM,gBAAgB,SAAS,CAAA;AACtC,eAAO,MAAM,kBAAkB,SAAmB,CAAA;AAElD,eAAO,MAAM,gBAAgB,SAAS,CAAA;AACtC,eAAO,MAAM,kBAAkB,SAAmB,CAAA;AAElD,eAAO,MAAM,aAAa,YAAY,CAAA;AAEtC,eAAO,MAAM,UAAU;;;;;CAKtB,CAAA"}
|
package/build/consts.js
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
export var ProductType;
|
|
2
|
+
(function (ProductType) {
|
|
3
|
+
ProductType["Simple"] = "simple";
|
|
4
|
+
ProductType["Service"] = "service";
|
|
5
|
+
})(ProductType || (ProductType = {}));
|
|
6
|
+
export var PaymentEntityType;
|
|
7
|
+
(function (PaymentEntityType) {
|
|
8
|
+
PaymentEntityType["Product"] = "product";
|
|
9
|
+
PaymentEntityType["Plan"] = "plan";
|
|
10
|
+
PaymentEntityType["CapabilitySet"] = "capability-set";
|
|
11
|
+
})(PaymentEntityType || (PaymentEntityType = {}));
|
|
12
|
+
export var PlanStatus;
|
|
13
|
+
(function (PlanStatus) {
|
|
14
|
+
PlanStatus["Active"] = "active";
|
|
15
|
+
PlanStatus["Custom"] = "custom";
|
|
16
|
+
PlanStatus["Hidden"] = "hidden";
|
|
17
|
+
PlanStatus["Archived"] = "archived";
|
|
18
|
+
PlanStatus["Deprecated"] = "deprecated";
|
|
19
|
+
PlanStatus["Suspended"] = "suspended";
|
|
20
|
+
})(PlanStatus || (PlanStatus = {}));
|
|
21
|
+
export var PlanDuration;
|
|
22
|
+
(function (PlanDuration) {
|
|
23
|
+
PlanDuration["Monthly"] = "monthly";
|
|
24
|
+
PlanDuration["Yearly"] = "yearly";
|
|
25
|
+
PlanDuration["Lifetime"] = "lifetime";
|
|
26
|
+
PlanDuration["Reusable"] = "reusable";
|
|
27
|
+
/**
|
|
28
|
+
* It means it requires some tokens to be consumed to use the
|
|
29
|
+
* capability.
|
|
30
|
+
*/
|
|
31
|
+
PlanDuration["Consumable"] = "consumable";
|
|
32
|
+
})(PlanDuration || (PlanDuration = {}));
|
|
33
|
+
export var SubscriptionStatus;
|
|
34
|
+
(function (SubscriptionStatus) {
|
|
35
|
+
SubscriptionStatus["Created"] = "created";
|
|
36
|
+
SubscriptionStatus["Trial"] = "trial";
|
|
37
|
+
SubscriptionStatus["Canceled"] = "canceled";
|
|
38
|
+
SubscriptionStatus["Expired"] = "expired";
|
|
39
|
+
SubscriptionStatus["Suspended"] = "suspended";
|
|
40
|
+
SubscriptionStatus["Blocked"] = "blocked";
|
|
41
|
+
SubscriptionStatus["Ended"] = "ended";
|
|
42
|
+
SubscriptionStatus["Free"] = "free";
|
|
43
|
+
SubscriptionStatus["Active"] = "active";
|
|
44
|
+
})(SubscriptionStatus || (SubscriptionStatus = {}));
|
|
45
|
+
export const ProductTypeSchema = {
|
|
46
|
+
type: 'string',
|
|
47
|
+
enum: Object.values(ProductType)
|
|
48
|
+
};
|
|
49
|
+
export const PaymentEntityTypeSchema = {
|
|
50
|
+
type: 'string',
|
|
51
|
+
enum: Object.values(PaymentEntityType)
|
|
52
|
+
};
|
|
53
|
+
export const PlanStatusSchema = {
|
|
54
|
+
type: 'string',
|
|
55
|
+
enum: Object.values(PlanStatus)
|
|
56
|
+
};
|
|
57
|
+
export const PlanDurationSchema = {
|
|
58
|
+
type: 'string',
|
|
59
|
+
enum: Object.values(PlanDuration)
|
|
60
|
+
};
|
|
61
|
+
export const SubscriptionStatusSchema = {
|
|
62
|
+
type: 'string',
|
|
63
|
+
enum: Object.values(SubscriptionStatus)
|
|
64
|
+
};
|
|
65
|
+
export const ProductTitleSchema = {
|
|
66
|
+
type: 'string', minLength: 1, maxLength: 128
|
|
67
|
+
};
|
|
68
|
+
export const ProductDescriptionSchema = {
|
|
69
|
+
type: 'string', minLength: 0, maxLength: 1024, nullable: true
|
|
70
|
+
};
|
|
71
|
+
export const LocalizationLngSchema = {
|
|
72
|
+
type: 'string', minLength: 2, maxLength: 3
|
|
73
|
+
};
|
|
74
|
+
export const PRODUCT_RECORD_TYPE = 'product';
|
|
75
|
+
export const PRODUCT_RECORD_PREFIX = PRODUCT_RECORD_TYPE;
|
|
76
|
+
export const PLAN_RECORD_TYPE = 'plan';
|
|
77
|
+
export const PLAN_RECORD_PREFIX = PLAN_RECORD_TYPE;
|
|
78
|
+
export const L10N_RECORD_TYPE = 'l10n';
|
|
79
|
+
export const L10N_RECORD_PREFIX = L10N_RECORD_TYPE;
|
|
80
|
+
export const DEFAULT_ALIAS = 'payment';
|
|
81
|
+
export const paymentApi = {
|
|
82
|
+
subscription: {
|
|
83
|
+
base: 'payment-api:subscription',
|
|
84
|
+
propogate: 'payment-api:subscription:propogate',
|
|
85
|
+
}
|
|
86
|
+
};
|
|
87
|
+
//# sourceMappingURL=consts.js.map
|