@blocklet/payment-js 1.18.6 → 1.18.7

package/README.md

@@ -1,6 +1,10 @@
 # PaymentKit Node.js SDK
 
-A Node.js SDK for the PaymentKit API, can be used to manage resources in PaymentKit.
+A Node.js SDK for the PaymentKit API. This package allows you to manage resources in PaymentKit including customers, subscriptions, products, prices, payments, checkout sessions, usage records, and webhooks.
+
+## Related Links
+
+- [Payment Kit Documentation](https://www.arcblock.io/docs/arcblock-payment-kit/en/start-payment-js) - Official documentation with detailed guides and API references
 
 ## Installation
 
@@ -8,32 +12,113 @@ A Node.js SDK for the PaymentKit API, can be used to manage resources in Payment
 npm install @blocklet/payment-js
 ```
 
-## Usage
+## Getting Started
+
+### Configuration
+
+Configure the SDK with your desired environment and API key:
 
 ```js
 import payment from '@blocklet/payment-js';
 
-// Configure the SDK
-payment.environments.setTestMode(true);  // Use test environment
-payment.environments.setApiKey('your-api-key');  // Set API key if needed
+// Set environment mode
+payment.environments.setTestMode(true);      // Use test environment
+// payment.environments.setLiveMode(true);   // Use live environment
+
+```
+
+### Environment Variables
+
+The SDK supports the following environment variables for configuration:
+
+- `PAYMENT_LIVE_MODE`:  Set to 'true' for live mode, 'false' for test mode
+- `PAYMENT_TEST_MODE`: Set to 'true' to enable test mode
+
+## Usage Examples
+
+### Listing Subscriptions
 
-// List subscriptions
+```js
 const subscriptions = await payment.subscriptions.list({
-  order: 'updated_at:ASC',
-  activeFirst: true,
+  order: 'updated_at:ASC',    // Sort by update time
+  activeFirst: true,          // Show active first
 });
+```
+
+### Creating a Checkout Session
 
-// Create a checkout session
+```js
 const session = await payment.checkout.sessions.create({
   success_url: 'https://example.com/success',
   cancel_url: 'https://example.com/cancel',
   mode: 'payment',
   line_items: [
     { price_id: 'price_xxx', quantity: 1 }
+  ],
+  subscription_data: {
+    service_actions: [
+      {
+        type: 'notification',
+        text: { zh: '查看文档', en: 'View Documentation' },
+        link: 'https://docs.example.com',
+        triggerEvents: ['customer.subscription.started']
+      }
+    ]
+  },
+  expires_at: 1729243800
+});
+```
+
+### Managing Products and Prices
+
+```js
+// Create product
+const product = await payment.products.create({
+  name: 'Test Product',
+  description: 'Product description',
+  type: 'service'
+});
+
+// Create price with EVM support
+const price = await payment.prices.create({
+  product_id: product.id,
+  type: 'recurring',
+  unit_amount: '0.001',
+  currency_id: 'pc_xxx',
+  recurring: {
+    interval: 'month',
+    interval_count: 1,
+    usage_type: 'licensed'
+  },
+  quantity_available: 10,
+  quantity_limit_per_checkout: 2,
+  currency_options: [
+    {
+      currency_id: 'pc_xxx',
+      unit_amount: '0.001'
+    }
   ]
 });
+```
+
+### Managing Subscriptions
+
+```js
+// get subscription
+await payment.subscriptions.retrieve('sub_xxx');
+
+// Report usage
+await payment.subscriptionItems.createUsageRecord({
+  subscription_item_id: 'si_xxx',
+  quantity: 1,
+  action: 'increment',
+  timestamp: Math.floor(Date.now() / 1000)
+});
+```
 
-// Handle refunds
+### Handling Refunds
+
+```js
 const refund = await payment.paymentIntents.refund('pi_xxx', {
   amount: '0.001',
   reason: 'requested_by_customer',
@@ -41,61 +126,117 @@ const refund = await payment.paymentIntents.refund('pi_xxx', {
 });
 ```
 
-## Resources
+### Setting up Webhooks
 
-The SDK provides access to the following resources:
+```js
+const webhook = await payment.webhookEndpoints.create({
+  url: 'https://example.com/webhook',
+  enabled_events: [
+    'checkout.session.completed',
+    'checkout.session.nft_minted',
+    'customer.subscription.created',
+    'customer.subscription.deleted',
+    'customer.subscription.paused',
+    'customer.subscription.updated',
+    'customer.subscription.started',
+    'customer.subscription.renewed',
+    'payment_intent.created',
+    'payment_intent.succeeded'
+  ]
+});
+```
+
+## API Resources
 
 ### Customers
-- `payment.customers.create()`
 - `payment.customers.retrieve(id)`
 - `payment.customers.update(id, data)`
 - `payment.customers.list(params)`
 - `payment.customers.search(params)`
 - `payment.customers.del(id)`
+- `payment.customers.me()`
 
 ### Subscriptions
-- `payment.subscriptions.create()`
 - `payment.subscriptions.retrieve(id)`
 - `payment.subscriptions.update(id, data)`
 - `payment.subscriptions.list(params)`
+- `payment.subscriptions.search(params)`
 - `payment.subscriptions.cancel(id, options)`
 - `payment.subscriptions.recover(id)`
 - `payment.subscriptions.pause(id)`
 - `payment.subscriptions.resume(id)`
+- `payment.subscriptions.del(id)`
 
 ### Products & Prices
-- `payment.products.*` - Manage products
-- `payment.prices.*` - Manage prices and inventory
+- `payment.products.create(data)`
+- `payment.products.retrieve(id)`
+- `payment.products.update(id, data)`
+- `payment.products.list(params)`
+- `payment.products.search(params)`
+- `payment.products.archive(id)`
+- `payment.products.del(id)`
+- `payment.prices.create(data)`
+- `payment.prices.retrieve(id)`
+- `payment.prices.update(id, data)`
+- `payment.prices.list(params)`
+- `payment.prices.search(params)`
+- `payment.prices.archive(id)`
+- `payment.prices.del(id)`
+- `payment.prices.inventory(id, data)`
 
-### Payments
-- `payment.paymentIntents.*` - Handle payment intents
-- `payment.paymentMethods.*` - Manage payment methods
-- `payment.refunds.*` - Handle refunds
+### Payments & Refunds
+- `payment.paymentIntents.create(data)`
+- `payment.paymentIntents.retrieve(id)`
+- `payment.paymentIntents.update(id, data)`
+- `payment.paymentIntents.list(params)`
+- `payment.paymentIntents.search(params)`
+- `payment.paymentIntents.refund(id, data)`
+- `payment.refunds.create(data)`
+- `payment.refunds.retrieve(id)`
+- `payment.refunds.list(params)`
+- `payment.refunds.search(params)`
+
+### Payment Links
+- `payment.paymentLinks.create(data)`
+- `payment.paymentLinks.retrieve(id)`
+- `payment.paymentLinks.update(id, data)`
+- `payment.paymentLinks.archive(id)`
+- `payment.paymentLinks.list(params)`
 
 ### Checkout
-- `payment.checkout.sessions.*` - Create and manage checkout sessions
-- `payment.paymentLinks.*` - Handle payment links
+- `payment.checkout.sessions.create(data)`
+- `payment.checkout.sessions.retrieve(id)`
+- `payment.checkout.sessions.update(id, data)`
+- `payment.checkout.sessions.expire(id)`
+- `payment.checkout.sessions.list(params)`
 
 ### Usage & Metering
-- `payment.subscriptionItems.createUsageRecord()`
-- `payment.subscriptionItems.listUsageRecordSummaries()`
+- `payment.subscriptionItems.create(data)`
+- `payment.subscriptionItems.retrieve(id)`
+- `payment.subscriptionItems.update(id, data)`
+- `payment.subscriptionItems.list(params)`
+- `payment.subscriptionItems.del(id)`
+- `payment.subscriptionItems.createUsageRecord(data)`
+- `payment.subscriptionItems.listUsageRecordSummaries(id)`
+- `payment.subscriptionItems.listUsageRecords(params)`
 
 ### Webhooks
-- `payment.webhookEndpoints.*` - Manage webhook endpoints
-
-## Configuration
+- `payment.webhookEndpoints.create(data)`
+- `payment.webhookEndpoints.retrieve(id)`
+- `payment.webhookEndpoints.update(id, data)`
+- `payment.webhookEndpoints.list(params)`
+- `payment.webhookEndpoints.del(id)`
 
-The SDK can be configured with the following options:
+## Subscription Status
 
-```js
-// Set environment
-payment.environments.setTestMode(true);  // Use test environment
-payment.environments.setLiveMode(true);  // Use live environment
-
-// Set API configuration
-payment.environments.setApiKey('your-api-key');
-payment.environments.setEndpoint('https://api.example.com');
-```
+A subscription can have the following statuses:
+- `active`: The subscription is in good standing
+- `canceled`: The subscription has been canceled
+- `incomplete`: Initial payment attempt failed
+- `incomplete_expired`: Initial payment failed and retry period expired
+- `past_due`: Latest payment failed
+- `trialing`: In trial period
+- `paused`: Temporarily paused
 
 ## Error Handling
 
@@ -103,18 +244,14 @@ payment.environments.setEndpoint('https://api.example.com');
 try {
   const subscription = await payment.subscriptions.retrieve('sub_xxx');
 } catch (error) {
-  if (error.type === 'NotFoundError') {
-    console.error('Subscription not found');
-  } else {
-    console.error('An error occurred:', error.message);
-  }
+  console.error('An error occurred:', error.message);
 }
 ```
 
 ## TypeScript Support
 
-The SDK is written in TypeScript and provides full type definitions for all resources and methods.
+The SDK is written in TypeScript and includes full type definitions for all resources and methods.
 
 ## License
 
-MIT
+Apache-2.0

package/lib/index.d.ts

@@ -31,11 +31,6 @@ declare const _default: {
         };
     };
     customers: {
-        create: (data: Partial<import("sequelize").InferAttributes<import("@blocklet/payment-types").Customer, {
-            omit: never;
-        }>>, params?: never) => Promise<import("sequelize").InferAttributes<import("@blocklet/payment-types").Customer, {
-            omit: never;
-        }>>;
         retrieve: (_params: string, data?: never) => Promise<import("@blocklet/payment-types").TCustomerExpanded>;
         update: (_params: string, data?: Partial<import("sequelize").InferAttributes<import("@blocklet/payment-types").Customer, {
             omit: never;
@@ -46,9 +41,7 @@ declare const _default: {
             did?: string;
         }>, data?: never) => Promise<import("@blocklet/payment-types").Paginated<import("@blocklet/payment-types").TCustomerExpanded>>;
         search: (_params: any, data?: never) => Promise<import("@blocklet/payment-types").Paginated<import("@blocklet/payment-types").TCustomerExpanded>>;
-        del: (_params: string, data?: never) => Promise<import("sequelize").InferAttributes<import("@blocklet/payment-types").Customer, {
-            omit: never;
-        }>>;
+        me: (_params: never, data?: never) => Promise<import("@blocklet/payment-types").TCustomerExpanded>;
     };
     products: {
         create: (data: Partial<import("sequelize").InferAttributes<import("@blocklet/payment-types").Product, {
@@ -175,9 +168,6 @@ declare const _default: {
         }) => Promise<import("@blocklet/payment-types").TPriceExpanded>;
     };
     subscriptions: {
-        create: (data: Partial<import("@blocklet/payment-types").TSubscriptionExpanded>, params?: never) => Promise<import("sequelize").InferAttributes<import("@blocklet/payment-types").Subscription, {
-            omit: never;
-        }>>;
         retrieve: (_params: string, data?: never) => Promise<import("@blocklet/payment-types").TSubscriptionExpanded>;
         update: (_params: string, data?: Partial<import("sequelize").InferAttributes<import("@blocklet/payment-types").Subscription, {
             omit: never;

package/lib/resources/customer.d.ts

@@ -1,10 +1,5 @@
 import type { Paginated, Pagination, TCustomerExpanded } from '@blocklet/payment-types';
 declare const _default: {
-    create: (data: Partial<import("sequelize").InferAttributes<import("@blocklet/payment-types").Customer, {
-        omit: never;
-    }>>, params?: never) => Promise<import("sequelize").InferAttributes<import("@blocklet/payment-types").Customer, {
-        omit: never;
-    }>>;
     retrieve: (_params: string, data?: never) => Promise<TCustomerExpanded>;
     update: (_params: string, data?: Partial<import("sequelize").InferAttributes<import("@blocklet/payment-types").Customer, {
         omit: never;
@@ -15,8 +10,6 @@ declare const _default: {
         did?: string;
     }>, data?: never) => Promise<Paginated<TCustomerExpanded>>;
     search: (_params: any, data?: never) => Promise<Paginated<TCustomerExpanded>>;
-    del: (_params: string, data?: never) => Promise<import("sequelize").InferAttributes<import("@blocklet/payment-types").Customer, {
-        omit: never;
-    }>>;
+    me: (_params: never, data?: never) => Promise<TCustomerExpanded>;
 };
 export default _default;

package/lib/resources/customer.js

@@ -2,10 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const resource_1 = require("../resource");
 exports.default = {
-    create: (0, resource_1.createResourceCreateMethod)({
-        method: 'POST',
-        path: '/api/customers',
-    }),
+    // create: createResourceCreateMethod<TCustomer, Partial<TCustomer>, never>({
+    //   method: 'POST',
+    //   path: '/api/customers',
+    // }),
     // get customer by id or did
     retrieve: (0, resource_1.createResourceMethod)({ method: 'GET', path: '/api/customers/{id}' }),
     update: (0, resource_1.createResourceMethod)({
@@ -20,5 +20,9 @@ exports.default = {
         method: 'GET',
         path: '/api/customers/search',
     }),
-    del: (0, resource_1.createResourceMethod)({ method: 'DELETE', path: '/api/customers/{id}' }),
+    me: (0, resource_1.createResourceMethod)({
+        method: 'GET',
+        path: '/api/customers/me',
+    }),
+    // del: createResourceMethod<TCustomer, never, string>({ method: 'DELETE', path: '/api/customers/{id}' }),
 };

package/lib/resources/subscription.d.ts

@@ -13,9 +13,6 @@ type CancelBodyType = {
     cancel_from?: 'customer' | 'admin';
 };
 declare const _default: {
-    create: (data: Partial<TSubscriptionExpanded>, params?: never) => Promise<import("sequelize").InferAttributes<import("@blocklet/payment-types").Subscription, {
-        omit: never;
-    }>>;
     retrieve: (_params: string, data?: never) => Promise<TSubscriptionExpanded>;
     update: (_params: string, data?: Partial<import("sequelize").InferAttributes<import("@blocklet/payment-types").Subscription, {
         omit: never;

package/lib/resources/subscription.js

@@ -2,10 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const resource_1 = require("../resource");
 exports.default = {
-    create: (0, resource_1.createResourceCreateMethod)({
-        method: 'POST',
-        path: '/api/subscriptions',
-    }),
+    // create: createResourceCreateMethod<TSubscription, Partial<TSubscriptionExpanded>, never>({
+    //   method: 'POST',
+    //   path: '/api/subscriptions',
+    // }),
     retrieve: (0, resource_1.createResourceMethod)({
         method: 'GET',
         path: '/api/subscriptions/{id}',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocklet/payment-js",
-  "version": "1.18.6",
+  "version": "1.18.7",
   "description": "Node.js client for Payment Kit",
   "keywords": [
     "types",
@@ -36,7 +36,7 @@
     "url": "https://github.com/blocklet/payment-kit/issues"
   },
   "dependencies": {
-    "@blocklet/payment-types": "1.18.6",
+    "@blocklet/payment-types": "1.18.7",
     "@blocklet/sdk": "^1.16.38"
   },
   "importSort": {
@@ -63,5 +63,5 @@
     "type-fest": "^4.23.0",
     "typescript": "^5.5.4"
   },
-  "gitHead": "784ba57910d780a44d0792ef503b666ee8f8d9c3"
+  "gitHead": "b75168ab5e2cd939571e6e26543374c8d0dab963"
 }