@commet/node 1.7.0 → 1.8.0

package/README.md

@@ -13,13 +13,26 @@
 
 <br/>
 
+[Commet](https://commet.co) is an all-in-one billing and payments platform for SaaS and AI products. `@commet/node` is the core SDK — use it to manage customers, track usage, handle subscriptions, and more from your server.
+
 ## Installation
 
 ```bash
 npm install @commet/node
 ```
 
-## Quick Start
+## Getting Started
+
+### 1. Create a Commet account
+
+Sign up at [commet.co](https://commet.co) and create an organization. Go to **Settings → API Keys** to get your key.
+
+```bash
+# .env
+COMMET_API_KEY=ck_...
+```
+
+### 2. Initialize the SDK
 
 ```typescript
 import { Commet } from '@commet/node';
@@ -30,9 +43,22 @@ const commet = new Commet({
 });
 ```
 
-## Usage
+### 3. Start using it
 
 ```typescript
+// Create a customer
+const customer = await commet.customers.create({
+  fullName: 'Acme Corp',
+  billingEmail: 'billing@acme.com'
+});
+
+// Subscribe them to a plan
+await commet.subscriptions.create({
+  externalId: 'user_123',
+  planCode: 'pro', // autocomplete works after `commet pull`
+  billingInterval: 'yearly',
+});
+
 // Track usage events
 await commet.usage.create({
   feature: 'api_call',
@@ -47,22 +73,15 @@ await commet.seats.add({
   count: 5
 });
 
-// Create subscriptions
-await commet.subscriptions.create({
+// Check feature access
+const feature = await commet.features.check({
   externalId: 'user_123',
-  planCode: 'pro', // autocomplete works after `commet pull`
-  billingInterval: 'yearly',
-});
-
-// Manage customers
-await commet.customers.create({
-  fullName: 'Acme Corp',
-  billingEmail: 'billing@acme.com'
+  code: 'api_calls'
 });
 
-// Generate customer portal access
-await commet.portal.getUrl({
-    externalId: 'my-customer-123'
+// Generate customer portal link
+const portal = await commet.portal.getUrl({
+  externalId: 'user_123'
 });
 ```
 

package/dist/index.d.mts

@@ -41,7 +41,7 @@ declare class CommetValidationError extends CommetError {
     validationErrors: Record<string, string[]>;
     constructor(message: string, validationErrors: Record<string, string[]>);
 }
-type CustomerID = `cus_${string}`;
+type CustomerID = string;
 type EventID = `evt_${string}`;
 type Currency = "USD" | "EUR" | "GBP" | "CAD" | "AUD" | "JPY" | "ARS" | "BRL" | "MXN" | "CLP";
 interface ListParams extends Record<string, unknown> {
@@ -116,7 +116,7 @@ declare class CommetHTTPClient {
 }
 
 interface FeatureParams {
-    externalId: string;
+    customerId: CustomerID;
     code: GeneratedFeatureCode;
 }
 type GetFeatureParams = FeatureParams;
@@ -144,73 +144,13 @@ interface CanUseResult {
 interface CheckResult {
     allowed: boolean;
 }
-/**
- * Features resource for checking feature access and usage
- *
- * Provides a clean API to check if a customer can use a feature
- * without having to manually parse subscription data.
- */
 declare class FeaturesResource {
     private httpClient;
     constructor(httpClient: CommetHTTPClient);
-    /**
-     * Get detailed feature access/usage for a customer
-     *
-     * @example
-     * ```typescript
-     * const seats = await commet.features.get({ code: "team_members", externalId: "user_123" });
-     * console.log(seats.current, seats.included, seats.remaining);
-     * ```
-     */
     get(params: GetFeatureParams, options?: RequestOptions): Promise<ApiResponse<FeatureAccess>>;
-    /**
-     * Check if a boolean feature is enabled for a customer
-     *
-     * @example
-     * ```typescript
-     * const { allowed } = await commet.features.check({
-     *   code: "custom_branding",
-     *   externalId: "user_123"
-     * });
-     * if (!allowed) redirect("/upgrade");
-     * ```
-     */
     check(params: CheckFeatureParams, options?: RequestOptions): Promise<ApiResponse<CheckResult>>;
-    /**
-     * Check if customer can use one more unit of a feature
-     *
-     * Returns whether the customer can add one more (allowed)
-     * and whether they'll be charged extra (willBeCharged).
-     *
-     * @example
-     * ```typescript
-     * const { allowed, willBeCharged } = await commet.features.canUse({
-     *   code: "team_members",
-     *   externalId: "user_123"
-     * });
-     *
-     * if (!allowed) {
-     *   return { error: "Upgrade to add more members" };
-     * }
-     *
-     * if (willBeCharged) {
-     *   // Show confirmation: "This will cost $10/month extra"
-     * }
-     * ```
-     */
     canUse(params: CanUseFeatureParams, options?: RequestOptions): Promise<ApiResponse<CanUseResult>>;
-    /**
-     * List all features for a customer's active subscription
-     *
-     * @example
-     * ```typescript
-     * const features = await commet.features.list({ externalId: "user_123" });
-     * for (const feature of features) {
-     *   console.log(feature.code, feature.allowed);
-     * }
-     * ```
-     */
-    list(externalId: string, options?: RequestOptions): Promise<ApiResponse<FeatureAccess[]>>;
+    list(customerId: CustomerID, options?: RequestOptions): Promise<ApiResponse<FeatureAccess[]>>;
 }
 
 interface PortalAccess {
@@ -221,33 +161,15 @@ interface PortalAccess {
 interface GetUrlByCustomerId {
     customerId: CustomerID;
     email?: never;
-    externalId?: never;
-}
-interface GetUrlByExternalId {
-    externalId: string;
-    email?: never;
-    customerId?: never;
 }
 interface GetUrlByEmail {
     email: string;
     customerId?: never;
-    externalId?: never;
 }
-type GetUrlParams = GetUrlByCustomerId | GetUrlByExternalId | GetUrlByEmail;
-/**
- * Portal resource - Generate customer portal access
- */
+type GetUrlParams = GetUrlByCustomerId | GetUrlByEmail;
 declare class PortalResource {
     private httpClient;
     constructor(httpClient: CommetHTTPClient);
-    /**
-     * Get a portal URL
-     *
-     * @example
-     * ```typescript
-     * const portal = await commet.portal.getUrl({ externalId: 'user_123' });
-     * ```
-     */
     getUrl(params: GetUrlParams, options?: RequestOptions): Promise<ApiResponse<PortalAccess>>;
 }
 
@@ -268,116 +190,39 @@ interface SeatBalance {
     asOf: string;
 }
 interface AddParams {
-    customerId?: CustomerID;
-    externalId?: string;
+    customerId: CustomerID;
     seatType: GeneratedSeatType;
     count: number;
 }
 interface RemoveParams {
-    customerId?: CustomerID;
-    externalId?: string;
+    customerId: CustomerID;
     seatType: GeneratedSeatType;
     count: number;
 }
 interface SetParams {
-    customerId?: CustomerID;
-    externalId?: string;
+    customerId: CustomerID;
     seatType: GeneratedSeatType;
     count: number;
 }
 interface SetAllParams {
-    customerId?: CustomerID;
-    externalId?: string;
+    customerId: CustomerID;
     seats: Record<string, number>;
 }
 interface GetBalanceParams {
-    customerId?: CustomerID;
-    externalId?: string;
+    customerId: CustomerID;
     seatType: GeneratedSeatType;
 }
 interface GetAllBalancesParams {
-    customerId?: CustomerID;
-    externalId?: string;
+    customerId: CustomerID;
 }
-/**
- * Seats resource - Manage seat-based licenses
- */
 declare class SeatsResource {
     private httpClient;
     constructor(httpClient: CommetHTTPClient);
-    /**
-     * Add seats
-     *
-     * @example
-     * ```typescript
-     * await commet.seats.add({
-     *   externalId: 'user_123',
-     *   seatType: 'editor',
-     *   count: 5
-     * });
-     * ```
-     */
     add(params: AddParams, options?: RequestOptions): Promise<ApiResponse<SeatEvent>>;
-    /**
-     * Remove seats
-     *
-     * @example
-     * ```typescript
-     * await commet.seats.remove({
-     *   externalId: 'user_123',
-     *   seatType: 'editor',
-     *   count: 2
-     * });
-     * ```
-     */
     remove(params: RemoveParams, options?: RequestOptions): Promise<ApiResponse<SeatEvent>>;
-    /**
-     * Set seats to a specific count
-     *
-     * @example
-     * ```typescript
-     * await commet.seats.set({
-     *   externalId: 'user_123',
-     *   seatType: 'editor',
-     *   count: 10
-     * });
-     * ```
-     */
     set(params: SetParams, options?: RequestOptions): Promise<ApiResponse<SeatEvent>>;
-    /**
-     * Set all seat types
-     *
-     * @example
-     * ```typescript
-     * await commet.seats.setAll({
-     *   externalId: 'user_123',
-     *   seats: { editor: 10, viewer: 50 }
-     * });
-     * ```
-     */
     setAll(params: SetAllParams, options?: RequestOptions): Promise<ApiResponse<SeatEvent[]>>;
-    /**
-     * Get balance for a seat type
-     *
-     * @example
-     * ```typescript
-     * const balance = await commet.seats.getBalance({
-     *   externalId: 'user_123',
-     *   seatType: 'editor'
-     * });
-     * ```
-     */
     getBalance(params: GetBalanceParams): Promise<ApiResponse<SeatBalance>>;
-    /**
-     * Get all seat balances
-     *
-     * @example
-     * ```typescript
-     * const balances = await commet.seats.getAllBalances({
-     *   externalId: 'user_123'
-     * });
-     * ```
-     */
     getAllBalances(params: GetAllBalancesParams): Promise<ApiResponse<Record<string, SeatBalance>>>;
 }
 
@@ -524,7 +369,6 @@ interface ActiveSubscription {
 interface CreatedSubscription {
     id: string;
     customerId: string;
-    externalId: string;
     planId: string;
     planName: string;
     name: string;
@@ -562,13 +406,6 @@ interface Subscription {
     createdAt: string;
     updatedAt: string;
 }
-type CustomerIdentifier = {
-    customerId: string;
-    externalId?: never;
-} | {
-    customerId?: never;
-    externalId: string;
-};
 type PlanIdentifier = {
     planCode: GeneratedPlanCode;
     planId?: never;
@@ -576,7 +413,9 @@ type PlanIdentifier = {
     planCode?: never;
     planId: string;
 };
-type CreateSubscriptionParams = CustomerIdentifier & PlanIdentifier & {
+type CreateSubscriptionParams = PlanIdentifier & {
+    customerId: string;
+} & {
     billingInterval?: BillingInterval;
     initialSeats?: Record<string, number>;
     skipTrial?: boolean;
@@ -619,7 +458,7 @@ declare class SubscriptionsResource {
      * const sub = await commet.subscriptions.get('user_123');
      * ```
      */
-    get(externalId: string): Promise<ApiResponse<ActiveSubscription | null>>;
+    get(customerId: string): Promise<ApiResponse<ActiveSubscription | null>>;
     /**
      * Cancel a subscription
      *
@@ -651,18 +490,9 @@ interface UsageEventProperty {
     value: string;
     createdAt: string;
 }
-interface BatchResult$1<T> {
-    successful: T[];
-    failed: Array<{
-        index: number;
-        error: string;
-        data: TrackParams;
-    }>;
-}
 interface TrackBaseParams {
     feature: GeneratedFeatureCode;
-    customerId?: CustomerID;
-    externalId?: string;
+    customerId: CustomerID;
     idempotencyKey?: string;
     timestamp?: string;
     properties?: Record<string, string>;
@@ -684,15 +514,12 @@ declare class UsageResource {
     private httpClient;
     constructor(httpClient: CommetHTTPClient);
     track(params: TrackParams, options?: RequestOptions): Promise<ApiResponse<UsageEvent>>;
-    trackBatch(params: {
-        events: TrackParams[];
-    }, options?: RequestOptions): Promise<ApiResponse<BatchResult$1<UsageEvent>>>;
 }
 
 /**
  * Customer-scoped API context
  *
- * Provides a cleaner API where you don't have to pass externalId
+ * Provides a cleaner API where you don't have to pass customerId
  * on every call. All operations are scoped to a specific customer.
  *
  * @example
@@ -706,52 +533,37 @@ declare class UsageResource {
  * ```
  */
 declare class CustomerContext {
-    private readonly externalId;
+    private readonly customerId;
     private readonly featuresResource;
     private readonly seatsResource;
     private readonly usageResource;
     private readonly subscriptionsResource;
     private readonly portalResource;
-    constructor(externalId: string, resources: {
+    constructor(customerId: string, resources: {
         features: FeaturesResource;
         seats: SeatsResource;
         usage: UsageResource;
         subscriptions: SubscriptionsResource;
         portal: PortalResource;
     });
-    /**
-     * Feature access methods - delegates to FeaturesResource
-     */
     features: {
         get: (code: string, options?: RequestOptions) => Promise<ApiResponse<FeatureAccess>>;
         check: (code: string, options?: RequestOptions) => Promise<ApiResponse<CheckResult>>;
         canUse: (code: string, options?: RequestOptions) => Promise<ApiResponse<CanUseResult>>;
         list: (options?: RequestOptions) => Promise<ApiResponse<FeatureAccess[]>>;
     };
-    /**
-     * Seat management methods - delegates to SeatsResource
-     */
     seats: {
         add: (seatType: string, count?: number, options?: RequestOptions) => Promise<ApiResponse<SeatEvent>>;
         remove: (seatType: string, count?: number, options?: RequestOptions) => Promise<ApiResponse<SeatEvent>>;
         set: (seatType: string, count: number, options?: RequestOptions) => Promise<ApiResponse<SeatEvent>>;
         getBalance: (seatType: string) => Promise<ApiResponse<SeatBalance>>;
     };
-    /**
-     * Usage tracking methods - delegates to UsageResource
-     */
     usage: {
         track: (feature: string, value?: number, properties?: Record<string, string>, options?: RequestOptions) => Promise<ApiResponse<UsageEvent>>;
     };
-    /**
-     * Subscription methods - delegates to SubscriptionsResource
-     */
     subscription: {
         get: () => Promise<ApiResponse<ActiveSubscription | null>>;
     };
-    /**
-     * Portal methods - delegates to PortalResource
-     */
     portal: {
         getUrl: (options?: RequestOptions) => Promise<ApiResponse<PortalAccess>>;
     };
@@ -810,7 +622,7 @@ interface CustomerAddress {
 }
 interface CreateParams {
     email: string;
-    externalId?: string;
+    id?: string;
     fullName?: string;
     domain?: string;
     website?: string;
@@ -822,7 +634,6 @@ interface CreateParams {
 }
 interface UpdateParams {
     customerId: CustomerID;
-    externalId?: string;
     email?: string;
     fullName?: string;
     domain?: string;
@@ -831,9 +642,9 @@ interface UpdateParams {
     language?: string;
     industry?: string;
     metadata?: Record<string, unknown>;
+    address?: CustomerAddress;
 }
 interface ListCustomersParams extends ListParams {
-    externalId?: string;
     isActive?: boolean;
     search?: string;
 }
@@ -852,7 +663,7 @@ declare class CustomersResource {
     private httpClient;
     constructor(httpClient: CommetHTTPClient);
     /**
-     * Create a customer (idempotent with externalId)
+     * Create a customer (idempotent when id is provided)
      */
     create(params: CreateParams, options?: RequestOptions): Promise<ApiResponse<Customer>>;
     /**
@@ -1012,7 +823,7 @@ declare class Commet {
      * await customer.usage.track("api_call");
      * ```
      */
-    customer(externalId: string): CustomerContext;
+    customer(customerId: string): CustomerContext;
     getEnvironment(): Environment;
     isSandbox(): boolean;
     isProduction(): boolean;
@@ -1031,4 +842,4 @@ declare function isProduction(environment: Environment): boolean;
  * Commet SDK - Billing and usage tracking for SaaS
  */
 
-export { type ActiveSubscription, type AddParams as AddSeatsParams, type ApiResponse, type BillingInterval, type CanUseFeatureParams, type CanUseResult, type CancelParams, type CheckFeatureParams, type CheckResult, Commet, CommetAPIError, type CommetConfig, CommetError, type CommetGeneratedTypes, CommetValidationError, type CreateParams as CreateCustomerParams, type CreateSubscriptionParams, type CreatedSubscription, type CreditPack, type Currency, type Customer, type CustomerAddress, CustomerContext, type CustomerID, type BatchResult as CustomersBatchResult, type Environment, type EventID, type FeatureAccess, type FeatureSummary, type FeatureType, type GeneratedFeatureCode, type GeneratedPlanCode, type GeneratedSeatType, type GetAllBalancesParams, type GetBalanceParams, type GetFeatureParams, type GetUrlParams, type ListCustomersParams, type ListPlansParams, type PaginatedList, type PaginatedResponse, type Plan, type PlanDetail, type PlanFeature, type PlanID, type PlanPrice, type PortalAccess, type RemoveParams as RemoveSeatsParams, type RequestOptions, type SeatBalance, type SeatEvent, type SetAllParams as SetAllSeatsParams, type SetParams as SetSeatsParams, type Subscription, type SubscriptionStatus, type TrackModelTokensParams, type TrackParams, type TrackUsageParams, type UpdateParams as UpdateCustomerParams, type BatchResult$1 as UsageBatchResult, type UsageEvent, type UsageEventProperty, type WebhookData, type WebhookEvent, type WebhookPayload, Webhooks, Commet as default, isProduction, isSandbox };
+export { type ActiveSubscription, type AddParams as AddSeatsParams, type ApiResponse, type BillingInterval, type CanUseFeatureParams, type CanUseResult, type CancelParams, type CheckFeatureParams, type CheckResult, Commet, CommetAPIError, type CommetConfig, CommetError, type CommetGeneratedTypes, CommetValidationError, type CreateParams as CreateCustomerParams, type CreateSubscriptionParams, type CreatedSubscription, type CreditPack, type Currency, type Customer, type CustomerAddress, CustomerContext, type CustomerID, type BatchResult as CustomersBatchResult, type Environment, type EventID, type FeatureAccess, type FeatureSummary, type FeatureType, type GeneratedFeatureCode, type GeneratedPlanCode, type GeneratedSeatType, type GetAllBalancesParams, type GetBalanceParams, type GetFeatureParams, type GetUrlParams, type ListCustomersParams, type ListPlansParams, type PaginatedList, type PaginatedResponse, type Plan, type PlanDetail, type PlanFeature, type PlanID, type PlanPrice, type PortalAccess, type RemoveParams as RemoveSeatsParams, type RequestOptions, type SeatBalance, type SeatEvent, type SetAllParams as SetAllSeatsParams, type SetParams as SetSeatsParams, type Subscription, type SubscriptionStatus, type TrackModelTokensParams, type TrackParams, type TrackUsageParams, type UpdateParams as UpdateCustomerParams, type UsageEvent, type UsageEventProperty, type WebhookData, type WebhookEvent, type WebhookPayload, Webhooks, Commet as default, isProduction, isSandbox };