@blocklet/payment-js 1.19.0 → 1.19.2

package/README.md

@@ -1,6 +1,6 @@
 # PaymentKit Node.js SDK
 
-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.
+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, webhooks, and **credit-based billing with meters and credit grants**.
 
 ## Related Links
 
@@ -116,6 +116,54 @@ await payment.subscriptionItems.createUsageRecord({
 });
 ```
 
+### Credit-Based Billing with Meters
+
+```js
+// Create a meter to track usage
+const meter = await payment.meters.create({
+  name: 'API Calls',
+  event_name: 'api_calls',
+  aggregation_method: 'sum',
+  unit: 'calls',
+  description: 'Track API usage'
+});
+
+// Create a credit grant for a customer
+const creditGrant = await payment.creditGrants.create({
+  customer_id: 'cus_xxx',
+  amount: '1000',
+  currency_id: 'pc_xxx',
+  category: 'promotional',
+  name: 'New user bonus credits',
+  expires_at: Math.floor(Date.now() / 1000) + (30 * 24 * 60 * 60) // 30 days
+});
+
+// Report usage events
+const meterEvent = await payment.meterEvents.create({
+  event_name: 'api_calls',
+  payload: {
+    customer_id: 'cus_xxx',
+    value: '10',
+    subscription_id: 'sub_xxx'
+  },
+  identifier: `unique_${Date.now()}`,
+  timestamp: Math.floor(Date.now() / 1000)
+});
+
+// Check credit balance
+const creditSummary = await payment.creditGrants.summary({
+  customer_id: 'cus_xxx'
+});
+
+
+// View transaction history
+const transactions = await payment.creditTransactions.list({
+  customer_id: 'cus_xxx',
+  page: 1,
+  pageSize: 20
+});
+```
+
 ### Handling Refunds
 
 ```js
@@ -220,6 +268,35 @@ const webhook = await payment.webhookEndpoints.create({
 - `payment.subscriptionItems.listUsageRecordSummaries(id)`
 - `payment.subscriptionItems.listUsageRecords(params)`
 
+### Credit-Based Billing
+
+#### Meters
+- `payment.meters.create(data)` - Create a meter to track usage events
+- `payment.meters.retrieve(id)` - Get meter details
+- `payment.meters.update(id, data)` - Update meter configuration
+- `payment.meters.list(params)` - List all meters
+- `payment.meters.activate(id)` - Activate a meter
+- `payment.meters.deactivate(id)` - Deactivate a meter
+
+#### Meter Events
+- `payment.meterEvents.create(data)` - Report usage events
+- `payment.meterEvents.retrieve(id)` - Get meter event details
+- `payment.meterEvents.list(params)` - List meter events
+- `payment.meterEvents.stats(params)` - Get usage statistics
+- `payment.meterEvents.pendingAmount(params)` - Get pending credit consumption
+
+#### Credit Grants
+- `payment.creditGrants.create(data)` - Create credit grants for customers
+- `payment.creditGrants.retrieve(id)` - Get credit grant details
+- `payment.creditGrants.update(id, data)` - Update credit grant metadata
+- `payment.creditGrants.list(params)` - List credit grants
+- `payment.creditGrants.summary(params)` - Get credit balance summary
+
+#### Credit Transactions
+- `payment.creditTransactions.retrieve(id)` - Get transaction details
+- `payment.creditTransactions.list(params)` - List credit transactions
+- `payment.creditTransactions.summary(params)` - Get usage and credit summary
+
 ### Webhooks
 - `payment.webhookEndpoints.create(data)`
 - `payment.webhookEndpoints.retrieve(id)`
@@ -227,6 +304,25 @@ const webhook = await payment.webhookEndpoints.create({
 - `payment.webhookEndpoints.list(params)`
 - `payment.webhookEndpoints.del(id)`
 
+## Credit-Based Billing
+
+The PaymentKit SDK supports credit-based billing, allowing you to:
+
+1. **Track Usage with Meters**: Create meters to track specific usage events (API calls, storage usage, etc.)
+2. **Grant Credits**: Issue credits to customers through various methods (purchases, promotions, etc.)
+3. **Report Usage**: Submit usage events that consume credits automatically
+4. **Monitor Balances**: Check remaining credit balances and transaction history
+5. **Usage Analytics**: Get detailed statistics on usage patterns
+
+### Credit Grant Categories
+- `paid`: Credits purchased by the customer
+- `promotional`: Free credits given as promotions or bonuses
+
+### Meter Aggregation Methods
+- `sum`: Sum all usage values
+- `count`: Count number of events
+- `last`: Use the last reported value
+
 ## Subscription Status
 
 A subscription can have the following statuses:

package/lib/index.d.ts

@@ -289,6 +289,109 @@ declare const _default: {
             omit: never;
         }>>;
     };
+    meters: {
+        create: (data: import("./resources/meter").CreateMeterData, params?: never) => Promise<import("./resources/meter").TMeterExpanded>;
+        retrieve: (_params: string, data?: never) => Promise<import("./resources/meter").TMeterExpanded>;
+        update: (_params: string, data?: import("./resources/meter").UpdateMeterData) => Promise<import("./resources/meter").TMeterExpanded>;
+        list: (_params: {
+            event_name?: string;
+            livemode?: boolean;
+            q?: string;
+        } & {
+            page?: number;
+            pageSize?: number;
+            limit?: number;
+            starting_after?: string;
+            ending_before?: string;
+            order?: import("@blocklet/payment-types").OrderInput;
+        }, data?: never) => Promise<import("@blocklet/payment-types").Paginated<import("./resources/meter").TMeterExpanded>>;
+        activate: (_params: string, data?: never) => Promise<import("./resources/meter").TMeterExpanded>;
+        deactivate: (_params: string, data?: never) => Promise<import("./resources/meter").TMeterExpanded>;
+    };
+    meterEvents: {
+        create: (data: import("./resources/meter-event").CreateMeterEventData, params?: never) => Promise<import("@blocklet/payment-types").TMeterEventExpanded>;
+        retrieve: (_params: string, data?: never) => Promise<import("@blocklet/payment-types").TMeterEventExpanded>;
+        list: (_params: {
+            event_name?: string;
+            meter_id?: string;
+            customer_id?: string;
+            start?: number;
+            end?: number;
+            livemode?: boolean;
+            q?: string;
+        } & {
+            page?: number;
+            pageSize?: number;
+            limit?: number;
+            starting_after?: string;
+            ending_before?: string;
+            order?: import("@blocklet/payment-types").OrderInput;
+        }, data?: never) => Promise<import("@blocklet/payment-types").Paginated<import("@blocklet/payment-types").TMeterEventExpanded>>;
+        stats: (_params: {
+            meter_id: string;
+            start: number;
+            end: number;
+            customer_id?: string;
+            granularity?: "minute" | "hour" | "day";
+        }, data?: never) => Promise<import("@blocklet/payment-types").Paginated<import("./resources/meter-event").MeterEventStats>>;
+        pendingAmount: (_params: {
+            subscription_id?: string;
+            customer_id?: string;
+            currency_id?: string;
+        }, data?: never) => Promise<import("./resources/meter-event").PendingAmountSummary>;
+    };
+    creditGrants: {
+        create: (data: import("./resources/credit-grant").CreateCreditGrantData, params?: never) => Promise<import("@blocklet/payment-types").TCreditGrantExpanded>;
+        retrieve: (_params: string, data?: never) => Promise<import("@blocklet/payment-types").TCreditGrantExpanded>;
+        update: (_params: string, data?: import("./resources/credit-grant").UpdateCreditGrantData) => Promise<{
+            success: boolean;
+        }>;
+        list: (_params: {
+            customer_id?: string;
+            currency_id?: string;
+            status?: string;
+            livemode?: boolean;
+            q?: string;
+        } & {
+            page?: number;
+            pageSize?: number;
+            limit?: number;
+            starting_after?: string;
+            ending_before?: string;
+            order?: import("@blocklet/payment-types").OrderInput;
+        }, data?: never) => Promise<import("@blocklet/payment-types").Paginated<import("@blocklet/payment-types").TCreditGrantExpanded>>;
+        summary: (_params: {
+            customer_id: string;
+            subscription_id?: string;
+        }, data?: never) => Promise<import("./resources/credit-grant").CreditSummary>;
+    };
+    creditTransactions: {
+        retrieve: (_params: string, data?: never) => Promise<import("@blocklet/payment-types").TCreditTransactionExpanded>;
+        list: (_params: {
+            customer_id?: string;
+            subscription_id?: string;
+            credit_grant_id?: string;
+            source?: string;
+            start?: number;
+            end?: number;
+            livemode?: boolean;
+            q?: string;
+        } & {
+            page?: number;
+            pageSize?: number;
+            limit?: number;
+            starting_after?: string;
+            ending_before?: string;
+            order?: import("@blocklet/payment-types").OrderInput;
+        }, data?: never) => Promise<import("@blocklet/payment-types").Paginated<import("@blocklet/payment-types").TCreditTransactionExpanded>>;
+        summary: (_params: {
+            customer_id?: string;
+            subscription_id?: string;
+            currency_id?: string;
+            start?: number;
+            end?: number;
+        }, data?: never) => Promise<import("./resources/credit-transaction").UsageSummary>;
+    };
     environments: {
         getLivemode: () => boolean;
         setLivemode: (value: boolean) => void;

package/lib/index.js

@@ -31,6 +31,10 @@ const subscription_item_1 = __importDefault(require("./resources/subscription-it
 const webhook_endpoint_1 = __importDefault(require("./resources/webhook-endpoint"));
 const refund_1 = __importDefault(require("./resources/refund"));
 const setting_1 = __importDefault(require("./resources/setting"));
+const meter_1 = __importDefault(require("./resources/meter"));
+const meter_event_1 = __importDefault(require("./resources/meter-event"));
+const credit_grant_1 = __importDefault(require("./resources/credit-grant"));
+const credit_transaction_1 = __importDefault(require("./resources/credit-transaction"));
 // auto detect livemode
 if (process.env.PAYMENT_LIVEMODE) {
     resource_1.environments.setLivemode(process.env.PAYMENT_LIVEMODE === 'true');
@@ -55,6 +59,10 @@ exports.default = {
     subscriptions: subscription_1.default,
     subscriptionItems: subscription_item_1.default,
     webhookEndpoints: webhook_endpoint_1.default,
+    meters: meter_1.default,
+    meterEvents: meter_event_1.default,
+    creditGrants: credit_grant_1.default,
+    creditTransactions: credit_transaction_1.default,
     environments: resource_1.environments,
     refunds: refund_1.default,
     settings: setting_1.default,

package/lib/resources/credit-grant.d.ts

@@ -0,0 +1,56 @@
+import type { Paginated, Pagination, TCreditGrantExpanded } from '@blocklet/payment-types';
+export interface CreateCreditGrantData {
+    amount: string;
+    currency_id: string;
+    customer_id: string;
+    name?: string;
+    category: 'paid' | 'promotional';
+    priority?: number;
+    effective_at?: number;
+    expires_at?: number;
+    applicability_config?: {
+        scope?: {
+            prices?: string[];
+            price_type?: string;
+        };
+    };
+    metadata?: Record<string, any>;
+}
+export interface UpdateCreditGrantData {
+    metadata?: Record<string, any>;
+}
+export interface CreditSummary {
+    customer_id: string;
+    total_balance: Record<string, {
+        currency_id: string;
+        total_amount: string;
+        available_amount: string;
+        pending_amount: string;
+        currency: {
+            id: string;
+            symbol: string;
+            decimal: number;
+        };
+    }>;
+}
+type ListParams = Pagination<{
+    customer_id?: string;
+    currency_id?: string;
+    status?: string;
+    livemode?: boolean;
+    q?: string;
+}>;
+type SummaryParams = {
+    customer_id: string;
+    subscription_id?: string;
+};
+declare const _default: {
+    create: (data: CreateCreditGrantData, params?: never) => Promise<TCreditGrantExpanded>;
+    retrieve: (_params: string, data?: never) => Promise<TCreditGrantExpanded>;
+    update: (_params: string, data?: UpdateCreditGrantData) => Promise<{
+        success: boolean;
+    }>;
+    list: (_params: ListParams, data?: never) => Promise<Paginated<TCreditGrantExpanded>>;
+    summary: (_params: SummaryParams, data?: never) => Promise<CreditSummary>;
+};
+export default _default;

package/lib/resources/credit-grant.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const resource_1 = require("../resource");
+exports.default = {
+    create: (0, resource_1.createResourceCreateMethod)({
+        method: 'POST',
+        path: '/api/credit-grants',
+    }),
+    retrieve: (0, resource_1.createResourceMethod)({
+        method: 'GET',
+        path: '/api/credit-grants/{id}',
+    }),
+    update: (0, resource_1.createResourceMethod)({
+        method: 'PUT',
+        path: '/api/credit-grants/{id}',
+    }),
+    list: (0, resource_1.createResourceMethod)({
+        method: 'GET',
+        path: '/api/credit-grants',
+    }),
+    summary: (0, resource_1.createResourceMethod)({
+        method: 'GET',
+        path: '/api/credit-grants/summary',
+    }),
+};

package/lib/resources/credit-transaction.d.ts

@@ -0,0 +1,62 @@
+import type { Paginated, Pagination, TCreditTransactionExpanded } from '@blocklet/payment-types';
+export interface TCreditTransaction {
+    id: string;
+    customer_id: string;
+    credit_grant_id: string;
+    meter_id?: string;
+    subscription_id?: string;
+    meter_event_id?: string;
+    type: 'grant' | 'consumption' | 'adjustment' | 'expiration';
+    amount: string;
+    running_balance: string;
+    description?: string;
+    livemode: boolean;
+    created_at: string;
+    updated_at: string;
+    metadata?: Record<string, any>;
+}
+export interface UsageSummary {
+    customer_id?: string;
+    subscription_id?: string;
+    currency_id?: string;
+    total_consumption: string;
+    total_grants: string;
+    net_balance: string;
+    transaction_count: number;
+    period_start?: string;
+    period_end?: string;
+    breakdown: {
+        by_type: Record<string, {
+            amount: string;
+            count: number;
+        }>;
+        by_meter?: Record<string, {
+            amount: string;
+            count: number;
+            meter_name: string;
+        }>;
+    };
+}
+type ListParams = Pagination<{
+    customer_id?: string;
+    subscription_id?: string;
+    credit_grant_id?: string;
+    source?: string;
+    start?: number;
+    end?: number;
+    livemode?: boolean;
+    q?: string;
+}>;
+type SummaryParams = {
+    customer_id?: string;
+    subscription_id?: string;
+    currency_id?: string;
+    start?: number;
+    end?: number;
+};
+declare const _default: {
+    retrieve: (_params: string, data?: never) => Promise<TCreditTransactionExpanded>;
+    list: (_params: ListParams, data?: never) => Promise<Paginated<TCreditTransactionExpanded>>;
+    summary: (_params: SummaryParams, data?: never) => Promise<UsageSummary>;
+};
+export default _default;

package/lib/resources/credit-transaction.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const resource_1 = require("../resource");
+exports.default = {
+    retrieve: (0, resource_1.createResourceMethod)({
+        method: 'GET',
+        path: '/api/credit-transactions/{id}',
+    }),
+    list: (0, resource_1.createResourceMethod)({
+        method: 'GET',
+        path: '/api/credit-transactions',
+    }),
+    summary: (0, resource_1.createResourceMethod)({
+        method: 'GET',
+        path: '/api/credit-transactions/summary',
+    }),
+};

package/lib/resources/meter-event.d.ts

@@ -0,0 +1,52 @@
+import type { Paginated, Pagination, TMeterEventExpanded } from '@blocklet/payment-types';
+export interface CreateMeterEventData {
+    event_name: string;
+    payload: {
+        customer_id: string;
+        value: string;
+        subscription_id?: string;
+    };
+    timestamp?: number;
+    identifier: string;
+    metadata?: Record<string, any>;
+}
+export interface MeterEventStats {
+    date: string;
+    timestamp: string;
+    event_count: number;
+    total_value: string;
+}
+export interface PendingAmountSummary {
+    currency_id: string;
+    total_pending: string;
+    count: number;
+}
+type ListParams = Pagination<{
+    event_name?: string;
+    meter_id?: string;
+    customer_id?: string;
+    start?: number;
+    end?: number;
+    livemode?: boolean;
+    q?: string;
+}>;
+type StatsParams = {
+    meter_id: string;
+    start: number;
+    end: number;
+    customer_id?: string;
+    granularity?: 'minute' | 'hour' | 'day';
+};
+type PendingAmountParams = {
+    subscription_id?: string;
+    customer_id?: string;
+    currency_id?: string;
+};
+declare const _default: {
+    create: (data: CreateMeterEventData, params?: never) => Promise<TMeterEventExpanded>;
+    retrieve: (_params: string, data?: never) => Promise<TMeterEventExpanded>;
+    list: (_params: ListParams, data?: never) => Promise<Paginated<TMeterEventExpanded>>;
+    stats: (_params: StatsParams, data?: never) => Promise<Paginated<MeterEventStats>>;
+    pendingAmount: (_params: PendingAmountParams, data?: never) => Promise<PendingAmountSummary>;
+};
+export default _default;

package/lib/resources/meter-event.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const resource_1 = require("../resource");
+exports.default = {
+    create: (0, resource_1.createResourceCreateMethod)({
+        method: 'POST',
+        path: '/api/meter-events',
+    }),
+    retrieve: (0, resource_1.createResourceMethod)({
+        method: 'GET',
+        path: '/api/meter-events/{id}',
+    }),
+    list: (0, resource_1.createResourceMethod)({
+        method: 'GET',
+        path: '/api/meter-events',
+    }),
+    stats: (0, resource_1.createResourceMethod)({
+        method: 'GET',
+        path: '/api/meter-events/stats',
+    }),
+    pendingAmount: (0, resource_1.createResourceMethod)({
+        method: 'GET',
+        path: '/api/meter-events/pending-amount',
+    }),
+};

package/lib/resources/meter.d.ts

@@ -0,0 +1,39 @@
+import type { Paginated, Pagination, TMeter } from '@blocklet/payment-types';
+export interface TMeterExpanded extends TMeter {
+    paymentCurrency?: {
+        id: string;
+        name: string;
+        symbol: string;
+        decimal: number;
+        type: string;
+    };
+}
+export interface CreateMeterData {
+    name: string;
+    event_name: string;
+    aggregation_method?: 'sum' | 'count' | 'last';
+    unit: string;
+    currency_id?: string;
+    description?: string;
+    metadata?: Record<string, any>;
+}
+export interface UpdateMeterData {
+    name?: string;
+    description?: string;
+    status?: 'active' | 'inactive';
+    metadata?: Record<string, any>;
+}
+type ListParams = Pagination<{
+    event_name?: string;
+    livemode?: boolean;
+    q?: string;
+}>;
+declare const _default: {
+    create: (data: CreateMeterData, params?: never) => Promise<TMeterExpanded>;
+    retrieve: (_params: string, data?: never) => Promise<TMeterExpanded>;
+    update: (_params: string, data?: UpdateMeterData) => Promise<TMeterExpanded>;
+    list: (_params: ListParams, data?: never) => Promise<Paginated<TMeterExpanded>>;
+    activate: (_params: string, data?: never) => Promise<TMeterExpanded>;
+    deactivate: (_params: string, data?: never) => Promise<TMeterExpanded>;
+};
+export default _default;

package/lib/resources/meter.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const resource_1 = require("../resource");
+exports.default = {
+    create: (0, resource_1.createResourceCreateMethod)({
+        method: 'POST',
+        path: '/api/meters',
+    }),
+    retrieve: (0, resource_1.createResourceMethod)({
+        method: 'GET',
+        path: '/api/meters/{id}',
+    }),
+    update: (0, resource_1.createResourceMethod)({
+        method: 'PUT',
+        path: '/api/meters/{id}',
+    }),
+    list: (0, resource_1.createResourceMethod)({
+        method: 'GET',
+        path: '/api/meters',
+    }),
+    activate: (0, resource_1.createResourceMethod)({
+        method: 'PUT',
+        path: '/api/meters/{id}/activate',
+    }),
+    deactivate: (0, resource_1.createResourceMethod)({
+        method: 'PUT',
+        path: '/api/meters/{id}/deactivate',
+    }),
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocklet/payment-js",
-  "version": "1.19.0",
+  "version": "1.19.2",
   "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.19.0",
+    "@blocklet/payment-types": "1.19.2",
     "@blocklet/sdk": "^1.16.44"
   },
   "importSort": {
@@ -63,5 +63,5 @@
     "type-fest": "^4.41.0",
     "typescript": "5.5.4"
   },
-  "gitHead": "2810263174bb900ebb5a431dc53930b08b4a8d6d"
+  "gitHead": "741c897204afc412721a942201516932bff59235"
 }