@commet/node 0.8.0 → 0.10.0

package/README.md

@@ -1,15 +1,22 @@
-# @commet/node
+<div align="center">
+  <p align="center">
+    <a href="https://commet.co">
+      <img src="https://commet.co/logo-bg-dark.png" height="96">
+      <h3 align="center">Commet</h3>
+    </a>
+  </p>
+  <p>TypeScript SDK for Commet billing platform</p>
 
-TypeScript SDK for Commet billing platform - track usage, manage seats, and handle customers.
+  <a href="https://www.npmjs.com/package/@commet/node"><img alt="NPM version" src="https://img.shields.io/npm/v/@commet/node.svg?style=for-the-badge&labelColor=000000"></a>
+  <a href="https://docs.commet.co/docs/library/quickstart"><img alt="Documentation" src="https://img.shields.io/badge/docs-SDK-blue.svg?style=for-the-badge&labelColor=000000"></a>
+</div>
+
+<br/>
 
 ## Installation
 
 ```bash
 npm install @commet/node
-# or
-pnpm add @commet/node
-# or
-yarn add @commet/node
 ```
 
 ## Quick Start
@@ -18,260 +25,70 @@ yarn add @commet/node
 import { Commet } from '@commet/node';
 
 const commet = new Commet({
-  apiKey: process.env.COMMET_API_KEY!,
-  environment: 'production', // or 'sandbox' (default)
-  debug: false, // Enable debug logging
+  apiKey: process.env.COMMET_API_KEY,
+  environment: 'production' // or 'sandbox'
 });
 ```
 
-## Usage Examples
-
-### Subscriptions (Simple API)
+## Usage
 
 ```typescript
-// Create subscription - Minimal (fixed product)
-await commet.subscriptions.create({
-  productId: 'prod_enterprise_plan',
-  customerId: 'cus_acme'
-});
-// Backend auto-configures: quantity=1, billingDay=today
-
-// Create with custom quantity
-await commet.subscriptions.create({
-  productId: 'prod_api_platform',
-  externalId: 'my-customer-123', // Use your own ID
-  quantity: 5,
-  status: 'active' // Generate invoice immediately
-});
-
-// Usage-based product (no quantity needed)
-await commet.subscriptions.create({
-  productId: 'prod_api_calls',
-  customerId: 'cus_startup'
-});
-// Backend uses usageMetricId from product
-// Send events: commet.usage.create(...)
-
-// Seat-based product
-await commet.subscriptions.create({
-  productId: 'prod_saas_licenses',
-  customerId: 'cus_tech_company',
-  initialSeats: 10,
-  name: 'Tech Company - SaaS Plan'
-});
-// Backend uses seatTypeId from product
-// Adjust seats: commet.seats.add(...)
-
-// List subscriptions
-const subs = await commet.subscriptions.list({
-  customerId: 'cus_acme',
-  status: 'active'
-});
-
-// Get subscription
-const sub = await commet.subscriptions.retrieve('sub_abc123');
-
-// Cancel subscription
-await commet.subscriptions.cancel('sub_abc123');
-```
-
-### Usage Events (Consumption-Based Billing)
-
-```typescript
-// Send a single event using customerId (Commet's ID)
+// Track usage events
 await commet.usage.create({
   eventType: 'api_call',
-  customerId: 'cus_123',
-  timestamp: new Date().toISOString(),
-  properties: [
-    { property: 'endpoint', value: '/api/users' },
-    { property: 'method', value: 'GET' }
-  ]
-});
-
-// OR use your own externalId
-await commet.usage.create({
-  eventType: 'api_call',
-  externalId: 'my-customer-123', // Your own customer ID
-  timestamp: new Date().toISOString(),
-  properties: [
-    { property: 'endpoint', value: '/api/users' },
-    { property: 'method', value: 'GET' }
-  ]
-});
-
-// Batch events
-await commet.usage.createBatch({
-  events: [
-    { eventType: 'api_call', externalId: 'my-customer-123' },
-    { eventType: 'api_call', customerId: 'cus_456' },
-  ]
-});
-
-// List events
-const events = await commet.usage.list({
-  externalId: 'my-customer-123', // Or use customerId
-  limit: 100
+  customerId: 'cus_123'
 });
-```
-
-### Seat Management (Per-Seat Licensing)
 
-```typescript
-// Add seats using customerId or externalId
+// Manage seats
 await commet.seats.add({
-  externalId: 'my-customer-123', // Or use customerId: 'cus_123'
+  customerId: 'cus_123',
   seatType: 'admin',
   count: 5
 });
 
-// Remove seats
-await commet.seats.remove({
-  externalId: 'my-customer-123',
-  seatType: 'admin',
-  count: 2
-});
-
-// Set exact count
-await commet.seats.set({
-  externalId: 'my-customer-123',
-  seatType: 'admin',
-  count: 10
-});
-
-// Get balance
-const balance = await commet.seats.getBalance({
-  externalId: 'my-customer-123',
-  seatType: 'admin'
-});
-console.log(balance.data.current); // 10
-
-// Get all balances for a customer
-const allBalances = await commet.seats.getAllBalances({
-  externalId: 'my-customer-123'
-});
-
-// Bulk update multiple seat types
-await commet.seats.bulkUpdate({
-  externalId: 'my-customer-123',
-  seats: {
-    admin: 5,
-    editor: 20,
-    viewer: 100
-  }
-});
-
-// List seat events
-const events = await commet.seats.listEvents({
-  externalId: 'my-customer-123',
-  limit: 50
+// Create subscriptions
+await commet.subscriptions.create({
+  productId: 'prod_xxx',
+  customerId: 'cus_123',
+  status: 'active'
 });
-```
 
-### Customer Management
-
-```typescript
-// Create customer
-const customer = await commet.customers.create({
-  legalName: 'Acme Corporation',
-  displayName: 'Acme',
-  currency: 'USD',
-  taxStatus: 'TAXED',
-  address: {
-    line1: '123 Main St',
-    city: 'San Francisco',
-    state: 'CA',
-    postalCode: '94105',
-    country: 'US'
-  },
+// Manage customers
+await commet.customers.create({
+  legalName: 'Acme Corp',
   billingEmail: 'billing@acme.com'
 });
-
-// Update customer
-await commet.customers.update('cus_123', {
-  displayName: 'Acme Inc',
-  billingEmail: 'finance@acme.com'
-});
-
-// List customers
-const customers = await commet.customers.list({
-  isActive: true,
-  limit: 50
-});
-
-// Deactivate customer
-await commet.customers.deactivate('cus_123');
 ```
 
-## API Reference
-
-### Configuration
-
-```typescript
-interface CommetConfig {
-  apiKey: string;           // Required: Your Commet API key
-  environment?: 'sandbox' | 'production'; // Default: 'sandbox'
-  debug?: boolean;          // Default: false
-  timeout?: number;         // Request timeout in ms (default: 30000)
-  retries?: number;         // Max retry attempts (default: 3)
-}
-```
-
-### Resources
-
-- `commet.subscriptions` - Simple subscription management
-- `commet.usage` - Usage event tracking
-- `commet.seats` - Seat management
-- `commet.customers` - Customer CRUD operations
+## Type Safety
 
-### Error Handling
+Use the [Commet CLI](https://www.npmjs.com/package/commet) to generate TypeScript types from your organization:
 
-```typescript
-import { CommetAPIError, CommetValidationError } from '@commet/node';
-
-try {
-  await commet.usage.create({ ... });
-} catch (error) {
-  if (error instanceof CommetValidationError) {
-    console.error('Validation errors:', error.validationErrors);
-  } else if (error instanceof CommetAPIError) {
-    console.error('API error:', error.statusCode, error.message);
-  }
-}
+```bash
+npm install -g commet
+commet login
+commet link
+commet pull
 ```
 
-## Environment Detection
+This generates type-safe autocomplete for your event types, seat types, and products.
 
-```typescript
-// Check environment
-console.log(commet.getEnvironment()); // 'sandbox' | 'production'
-console.log(commet.isSandbox());      // boolean
-console.log(commet.isProduction());   // boolean
-```
+## Documentation
 
-## TypeScript Support
+Visit [docs.commet.co/docs/library/quickstart](https://docs.commet.co/docs/library/quickstart) for:
 
-Fully typed with TypeScript. All API responses and parameters are type-safe.
+- Complete API reference
+- Advanced usage examples
+- Error handling
+- Best practices
 
-```typescript
-import type {
-  Subscription,
-  CreateSubscriptionParams,
-  Customer,
-  UsageEvent,
-  SeatBalance,
-  Currency
-} from '@commet/node';
-```
+## Resources
 
-## Links
-
-- [Documentation](https://docs.commet.co)
-- [API Reference](https://docs.commet.co/api)
-- [GitHub](https://github.com/commet-labs/commet-node)
-- [Issues](https://github.com/commet-labs/commet-node/issues)
+- [CLI Documentation](https://docs.commet.co/docs/library/cli/overview)
+- [SDK Reference](https://docs.commet.co/docs/library/quickstart)
+- [GitHub](https://github.com/commet-labs/commet)
+- [Issues](https://github.com/commet-labs/commet/issues)
 
 ## License
 
 MIT
-

package/dist/index.d.mts

@@ -90,6 +90,12 @@ type GeneratedEventType = CommetGeneratedTypes extends {
 type GeneratedSeatType = CommetGeneratedTypes extends {
     seatType: infer T;
 } ? T : string;
+/**
+ * Helper type that provides fallback to string if types are not generated
+ */
+type GeneratedProductId = CommetGeneratedTypes extends {
+    productId: infer T;
+} ? T : string;
 
 declare class CommetHTTPClient {
     private config;
@@ -306,10 +312,9 @@ declare class SeatsResource {
 interface Subscription {
     id: string;
     customerId: string;
-    productId?: string;
     name: string;
     description?: string;
-    status: "draft" | "active" | "completed" | "canceled";
+    status: "draft" | "pending_payment" | "active" | "completed" | "canceled";
     startDate: string;
     endDate?: string;
     billingDayOfMonth: number;
@@ -317,9 +322,15 @@ interface Subscription {
     poNumber?: string;
     reference?: string;
     isTemplate?: boolean;
+    checkoutUrl?: string;
     createdAt: string;
     updatedAt: string;
 }
+interface SubscriptionItem {
+    priceId: string;
+    quantity?: number;
+    initialSeats?: number;
+}
 type CustomerIdentifier = {
     customerId: string;
     externalId?: never;
@@ -328,17 +339,15 @@ type CustomerIdentifier = {
     externalId: string;
 };
 type CreateSubscriptionParams = CustomerIdentifier & {
-    productId: string;
+    items: SubscriptionItem[];
     name?: string;
     startDate?: string;
-    status?: "draft" | "active";
-    quantity?: number;
-    initialSeats?: number;
+    status?: "draft" | "pending_payment" | "active";
 };
 interface ListSubscriptionsParams extends ListParams {
     customerId?: string;
     externalId?: string;
-    status?: "draft" | "active" | "completed" | "canceled";
+    status?: "draft" | "pending_payment" | "active" | "completed" | "canceled";
 }
 /**
  * Subscription resource for managing subscriptions
@@ -347,29 +356,29 @@ declare class SubscriptionsResource {
     private httpClient;
     constructor(httpClient: CommetHTTPClient);
     /**
-     * Create a simple subscription with smart defaults
+     * Create a subscription with multiple items (products)
      *
      * @example
      * ```typescript
-     * // Minimal - Fixed product
-     * await commet.subscriptions.create({
-     *   productId: "prod_xxx",
-     *   customerId: "cus_xxx"
-     * });
-     *
-     * // With custom quantity
+     * // Free plan - Multiple products
      * await commet.subscriptions.create({
-     *   productId: "prod_xxx",
-     *   externalId: "my-customer-123",
-     *   quantity: 5,
-     *   status: "active"
+     *   externalId: "org_123",
+     *   items: [
+     *     { priceId: "price_tasks_free", quantity: 1 },
+     *     { priceId: "price_usage_free" },
+     *     { priceId: "price_seats_free", initialSeats: 1 }
+     *   ]
      * });
      *
-     * // Seat-based product
+     * // Pro plan upgrade
      * await commet.subscriptions.create({
-     *   productId: "prod_saas",
      *   customerId: "cus_xxx",
-     *   initialSeats: 10
+     *   items: [
+     *     { priceId: "price_tasks_pro" },
+     *     { priceId: "price_usage_pro" },
+     *     { priceId: "price_seats_pro", initialSeats: 5 }
+     *   ],
+     *   status: "active"
      * });
      * ```
      */
@@ -467,6 +476,105 @@ declare class UsageResource {
     }>>;
 }
 
+/**
+ * Webhook payload structure from Commet
+ */
+interface WebhookPayload {
+    event: WebhookEvent;
+    timestamp: string;
+    organizationId: string;
+    data: WebhookData;
+}
+/**
+ * Webhook data structure (subscription-related fields)
+ */
+interface WebhookData {
+    id?: string;
+    publicId?: string;
+    subscriptionId?: string;
+    customerId?: string;
+    externalId?: string;
+    status?: string;
+    name?: string;
+    canceledAt?: string;
+    [key: string]: unknown;
+}
+/**
+ * Supported webhook events
+ */
+type WebhookEvent = "subscription.created" | "subscription.activated" | "subscription.canceled" | "subscription.updated";
+/**
+ * Webhooks resource for signature verification
+ */
+declare class Webhooks {
+    /**
+     * Verify HMAC-SHA256 webhook signature
+     *
+     * Use this method to verify that webhooks are authentically from Commet.
+     * The signature is included in the `X-Commet-Signature` header.
+     *
+     * @param payload - Raw request body as string (IMPORTANT: Do not parse JSON first)
+     * @param signature - Value from X-Commet-Signature header
+     * @param secret - Your webhook secret from Commet dashboard
+     * @returns true if signature is valid, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Next.js API route example
+     * export async function POST(request: Request) {
+     *   const rawBody = await request.text();
+     *   const signature = request.headers.get('x-commet-signature');
+     *
+     *   const isValid = commet.webhooks.verify(
+     *     rawBody,
+     *     signature,
+     *     process.env.COMMET_WEBHOOK_SECRET
+     *   );
+     *
+     *   if (!isValid) {
+     *     return new Response('Invalid signature', { status: 401 });
+     *   }
+     *
+     *   const payload = JSON.parse(rawBody);
+     *   // Handle webhook event...
+     * }
+     * ```
+     */
+    verify(payload: string, signature: string | null, secret: string): boolean;
+    /**
+     * Generate HMAC-SHA256 signature (internal use)
+     * @internal
+     */
+    private generateSignature;
+    /**
+     * Parse and verify webhook payload in one step
+     *
+     * @param rawBody - Raw request body as string
+     * @param signature - Value from X-Commet-Signature header
+     * @param secret - Your webhook secret from Commet dashboard
+     * @returns Parsed payload if valid, null if invalid
+     *
+     * @example
+     * ```typescript
+     * const payload = commet.webhooks.verifyAndParse(
+     *   rawBody,
+     *   signature,
+     *   process.env.COMMET_WEBHOOK_SECRET
+     * );
+     *
+     * if (!payload) {
+     *   return new Response('Invalid signature', { status: 401 });
+     * }
+     *
+     * // payload is typed and validated
+     * if (payload.event === 'subscription.activated') {
+     *   // Handle activation...
+     * }
+     * ```
+     */
+    verifyAndParse(rawBody: string, signature: string | null, secret: string): WebhookPayload | null;
+}
+
 /**
  * Main Commet SDK client
  */
@@ -477,6 +585,7 @@ declare class Commet {
     readonly usage: UsageResource;
     readonly seats: SeatsResource;
     readonly subscriptions: SubscriptionsResource;
+    readonly webhooks: Webhooks;
     constructor(config: CommetConfig);
     getEnvironment(): Environment;
     isSandbox(): boolean;
@@ -496,4 +605,4 @@ declare function isProduction(environment: Environment): boolean;
  * Commet SDK - Billing and usage tracking SDK
  */
 
-export { type AddSeatsParams, type AgreementID, type ApiResponse, type BatchResult, type BulkSeatUpdate, type BulkUpdateSeatsParams, Commet, CommetAPIError, type CommetConfig, CommetError, type CommetGeneratedTypes, CommetValidationError, type CreateBatchUsageEventsParams, type CreateCustomerParams, type CreateSubscriptionParams, type CreateUsageEventParams, type Currency, type Customer, type CustomerID, type Environment, type EventID, type GeneratedEventType, type GeneratedSeatType, type GetAllBalancesParams, type GetBalanceParams, type InvoiceID, type ItemID, type ListCustomersParams, type ListParams, type ListSeatEventsParams, type ListSubscriptionsParams, type ListUsageEventsParams, type PaginatedList, type PaginatedResponse, type PhaseID, type ProductID, type RemoveSeatsParams, type RequestOptions, type RetrieveOptions, type SeatBalance, type SeatBalanceResponse, type SeatEvent, type SetSeatsParams, type Subscription, type UpdateCustomerParams, type UsageEvent, type UsageEventProperty, type WebhookID, Commet as default, isProduction, isSandbox };
+export { type AddSeatsParams, type AgreementID, type ApiResponse, type BatchResult, type BulkSeatUpdate, type BulkUpdateSeatsParams, Commet, CommetAPIError, type CommetConfig, CommetError, type CommetGeneratedTypes, CommetValidationError, type CreateBatchUsageEventsParams, type CreateCustomerParams, type CreateSubscriptionParams, type CreateUsageEventParams, type Currency, type Customer, type CustomerID, type Environment, type EventID, type GeneratedEventType, type GeneratedProductId, type GeneratedSeatType, type GetAllBalancesParams, type GetBalanceParams, type InvoiceID, type ItemID, type ListCustomersParams, type ListParams, type ListSeatEventsParams, type ListSubscriptionsParams, type ListUsageEventsParams, type PaginatedList, type PaginatedResponse, type PhaseID, type ProductID, type RemoveSeatsParams, type RequestOptions, type RetrieveOptions, type SeatBalance, type SeatBalanceResponse, type SeatEvent, type SetSeatsParams, type Subscription, type SubscriptionItem, type UpdateCustomerParams, type UsageEvent, type UsageEventProperty, type WebhookData, type WebhookEvent, type WebhookID, type WebhookPayload, Commet as default, isProduction, isSandbox };