@commet/node 0.3.0

package/README.md

@@ -0,0 +1,186 @@
+# @commet/node
+
+TypeScript SDK for Commet billing platform - track usage, manage seats, and handle customers.
+
+## Installation
+
+```bash
+npm install @commet/node
+# or
+pnpm add @commet/node
+# or
+yarn add @commet/node
+```
+
+## Quick Start
+
+```typescript
+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
+});
+```
+
+## Usage Examples
+
+### Usage Events (Consumption-Based Billing)
+
+```typescript
+// Send a single event
+await commet.usage.events.create({
+  eventType: 'api_call',
+  customerId: 'cus_123',
+  timestamp: new Date().toISOString(),
+  properties: [
+    { property: 'endpoint', value: '/api/users' },
+    { property: 'method', value: 'GET' }
+  ]
+});
+
+// Batch events
+await commet.usage.events.createBatch({
+  events: [
+    { eventType: 'api_call', customerId: 'cus_123' },
+    { eventType: 'api_call', customerId: 'cus_456' },
+  ]
+});
+
+// List events
+const events = await commet.usage.events.list({
+  customerId: 'cus_123',
+  limit: 100
+});
+```
+
+### Seat Management (Per-Seat Licensing)
+
+```typescript
+// Add seats
+await commet.seats.add('cus_123', 'admin_seat', 5);
+
+// Remove seats
+await commet.seats.remove('cus_123', 'admin_seat', 2);
+
+// Set exact count
+await commet.seats.set('cus_123', 'admin_seat', 10);
+
+// Get balance
+const balance = await commet.seats.getBalance('cus_123', 'admin_seat');
+console.log(balance.current); // 10
+
+// Bulk update
+await commet.seats.bulkUpdate('cus_123', {
+  admin_seat: 5,
+  editor_seat: 20,
+  viewer_seat: 100
+});
+```
+
+### 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'
+  },
+  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.usage.events` - Usage event tracking
+- `commet.usage.metrics` - Usage metrics (read-only)
+- `commet.seats` - Seat management
+- `commet.customers` - Customer CRUD operations
+
+### Error Handling
+
+```typescript
+import { CommetAPIError, CommetValidationError } from '@commet/node';
+
+try {
+  await commet.usage.events.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);
+  }
+}
+```
+
+## Environment Detection
+
+```typescript
+// Check environment
+console.log(commet.getEnvironment()); // 'sandbox' | 'production'
+console.log(commet.isSandbox());      // boolean
+console.log(commet.isProduction());   // boolean
+```
+
+## TypeScript Support
+
+Fully typed with TypeScript. All API responses and parameters are type-safe.
+
+```typescript
+import type {
+  Customer,
+  UsageEvent,
+  SeatBalance,
+  Currency
+} from '@commet/node';
+```
+
+## 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)
+
+## License
+
+MIT
+

package/dist/index.d.mts

@@ -0,0 +1,368 @@
+type Environment = "sandbox" | "production";
+type CommetConfig = {
+    apiKey: string;
+    environment?: Environment;
+    debug?: boolean;
+    timeout?: number;
+    retries?: number;
+};
+interface ApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    message?: string;
+    hasMore?: boolean;
+    nextCursor?: string;
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    hasMore: boolean;
+    nextCursor?: string;
+    totalCount?: number;
+}
+interface PaginatedList<T> extends PaginatedResponse<T> {
+    next(): Promise<PaginatedList<T>>;
+    all(): Promise<T[]>;
+}
+declare class CommetError extends Error {
+    code?: string | undefined;
+    statusCode?: number | undefined;
+    details?: unknown | undefined;
+    constructor(message: string, code?: string | undefined, statusCode?: number | undefined, details?: unknown | undefined);
+}
+declare class CommetAPIError extends CommetError {
+    statusCode: number;
+    code?: string | undefined;
+    details?: unknown | undefined;
+    constructor(message: string, statusCode: number, code?: string | undefined, details?: unknown | undefined);
+}
+declare class CommetValidationError extends CommetError {
+    validationErrors: Record<string, string[]>;
+    constructor(message: string, validationErrors: Record<string, string[]>);
+}
+type CustomerID = `cus_${string}`;
+type AgreementID = `agr_${string}`;
+type InvoiceID = `inv_${string}`;
+type PhaseID = `phs_${string}`;
+type ItemID = `itm_${string}`;
+type ProductID = `prd_${string}`;
+type EventID = `evt_${string}`;
+type WebhookID = `wh_${string}`;
+type Currency = "USD" | "EUR" | "GBP" | "CAD" | "AUD" | "JPY" | "ARS" | "BRL" | "MXN" | "CLP";
+interface ListParams extends Record<string, unknown> {
+    limit?: number;
+    cursor?: string;
+    startDate?: string;
+    endDate?: string;
+}
+interface RetrieveOptions {
+    expand?: string[];
+}
+interface RequestOptions {
+    idempotencyKey?: string;
+    timeout?: number;
+}
+
+declare class CommetHTTPClient {
+    private config;
+    private environment;
+    private retryConfig;
+    constructor(config: CommetConfig, environment: Environment);
+    get<T = unknown>(endpoint: string, params?: Record<string, unknown>, options?: RequestOptions): Promise<ApiResponse<T>>;
+    post<T = unknown>(endpoint: string, data?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+    put<T = unknown>(endpoint: string, data?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+    delete<T = unknown>(endpoint: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * Core request method with retry logic
+     */
+    private request;
+    /**
+     * Execute real API request with retry logic
+     */
+    private executeRequest;
+    /**
+     * Get base URL based on environment
+     */
+    private getBaseURL;
+    /**
+     * Build full URL from endpoint and params
+     */
+    private buildURL;
+    /**
+     * Generate idempotency key
+     */
+    private generateIdempotencyKey;
+    /**
+     * Sleep for specified milliseconds
+     */
+    private sleep;
+}
+
+interface Customer {
+    id: CustomerID;
+    organizationId: string;
+    externalId?: string;
+    legalName: string;
+    displayName?: string;
+    domain?: string;
+    website?: string;
+    taxStatus: "TAXED" | "TAX_EXEMPT" | "REVERSE_CHARGE" | "NOT_APPLICABLE";
+    currency: Currency;
+    addressId: string;
+    billingEmail?: string;
+    paymentTerms?: string;
+    timezone?: string;
+    language?: string;
+    industry?: string;
+    employeeCount?: string;
+    metadata?: Record<string, unknown>;
+    isActive: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateCustomerBaseParams {
+    externalId?: string;
+    legalName: string;
+    displayName?: string;
+    domain?: string;
+    website?: string;
+    currency?: Currency;
+    billingEmail?: string;
+    paymentTerms?: string;
+    timezone?: string;
+    language?: string;
+    industry?: string;
+    employeeCount?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CustomerAddress {
+    line1: string;
+    line2?: string;
+    city: string;
+    state?: string;
+    postalCode: string;
+    country: string;
+    region?: string;
+}
+interface CreateCustomerTaxed extends CreateCustomerBaseParams {
+    taxStatus: "TAXED";
+    address: CustomerAddress;
+}
+interface CreateCustomerOtherTaxStatus extends CreateCustomerBaseParams {
+    taxStatus?: "TAX_EXEMPT" | "REVERSE_CHARGE" | "NOT_APPLICABLE";
+    address?: CustomerAddress;
+}
+type CreateCustomerParams = CreateCustomerTaxed | CreateCustomerOtherTaxStatus;
+interface UpdateCustomerParams {
+    externalId?: string;
+    legalName?: string;
+    displayName?: string;
+    domain?: string;
+    website?: string;
+    taxStatus?: "TAXED" | "TAX_EXEMPT" | "REVERSE_CHARGE" | "NOT_APPLICABLE";
+    currency?: Currency;
+    billingEmail?: string;
+    paymentTerms?: string;
+    timezone?: string;
+    language?: string;
+    industry?: string;
+    employeeCount?: string;
+    metadata?: Record<string, unknown>;
+    isActive?: boolean;
+}
+interface ListCustomersParams extends ListParams {
+    externalId?: string;
+    taxStatus?: "TAXED" | "TAX_EXEMPT" | "REVERSE_CHARGE" | "NOT_APPLICABLE";
+    currency?: Currency;
+    isActive?: boolean;
+    search?: string;
+}
+/**
+ * Customer resource for managing customer data
+ */
+declare class CustomersResource {
+    private httpClient;
+    constructor(httpClient: CommetHTTPClient);
+    create(params: CreateCustomerParams, options?: RequestOptions): Promise<ApiResponse<Customer>>;
+    retrieve(customerId: CustomerID, options?: RetrieveOptions): Promise<ApiResponse<Customer>>;
+    update(customerId: CustomerID, params: UpdateCustomerParams, options?: RequestOptions): Promise<ApiResponse<Customer>>;
+    list(params?: ListCustomersParams): Promise<ApiResponse<Customer[]>>;
+    /**
+     * Deactivate a customer (soft delete)
+     */
+    deactivate(customerId: CustomerID, options?: RequestOptions): Promise<ApiResponse<Customer>>;
+}
+
+interface SeatBalance {
+    id: string;
+    organizationId: string;
+    customerId: CustomerID;
+    seatType: string;
+    balance: number;
+    asOf: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface SeatEvent {
+    id: string;
+    organizationId: string;
+    customerId: CustomerID;
+    seatType: string;
+    eventType: "add" | "remove" | "set";
+    quantity: number;
+    previousBalance?: number;
+    newBalance: number;
+    ts: string;
+    createdAt: string;
+}
+interface SeatBalanceResponse {
+    current: number;
+    asOf: string;
+}
+interface BulkSeatUpdate {
+    [seatType: string]: number;
+}
+interface ListSeatEventsParams extends ListParams {
+    customerId?: CustomerID;
+    seatType?: string;
+    eventType?: "add" | "remove" | "set";
+}
+/**
+ * Seats resource for seat-based billing management
+ */
+declare class SeatsResource {
+    private httpClient;
+    constructor(httpClient: CommetHTTPClient);
+    add(customerId: CustomerID, seatType: string, count: number, options?: RequestOptions): Promise<ApiResponse<SeatEvent>>;
+    remove(customerId: CustomerID, seatType: string, count: number, options?: RequestOptions): Promise<ApiResponse<SeatEvent>>;
+    set(customerId: CustomerID, seatType: string, count: number, options?: RequestOptions): Promise<ApiResponse<SeatEvent>>;
+    bulkUpdate(customerId: CustomerID, seats: BulkSeatUpdate, options?: RequestOptions): Promise<ApiResponse<SeatEvent[]>>;
+    getBalance(customerId: CustomerID, seatType: string): Promise<ApiResponse<SeatBalanceResponse>>;
+    getAllBalances(customerId: CustomerID): Promise<ApiResponse<Record<string, SeatBalanceResponse>>>;
+    getHistory(customerId: CustomerID, seatType: string, params?: ListSeatEventsParams): Promise<ApiResponse<SeatEvent[]>>;
+    listEvents(params?: ListSeatEventsParams): Promise<ApiResponse<SeatEvent[]>>;
+}
+
+interface UsageEvent {
+    id: EventID;
+    organizationId: string;
+    customerId: CustomerID;
+    eventType: string;
+    idempotencyKey?: string;
+    ts: string;
+    properties?: UsageEventProperty[];
+    createdAt: string;
+}
+interface UsageEventProperty {
+    id: string;
+    usageEventId: EventID;
+    property: string;
+    value: string;
+    createdAt: string;
+}
+interface CreateUsageEventParams {
+    eventType: string;
+    customerId: CustomerID;
+    idempotencyKey?: string;
+    timestamp?: string;
+    properties?: Array<{
+        property: string;
+        value: string;
+    }>;
+}
+interface CreateBatchUsageEventsParams {
+    events: CreateUsageEventParams[];
+}
+interface BatchResult<T> {
+    successful: T[];
+    failed: Array<{
+        index: number;
+        error: string;
+        data: CreateUsageEventParams;
+    }>;
+}
+interface ListUsageEventsParams extends ListParams {
+    customerId?: CustomerID;
+    eventType?: string;
+    idempotencyKey?: string;
+}
+/**
+ * Usage Events resource - Track business events for usage-based billing
+ */
+declare class UsageEventsResource {
+    private httpClient;
+    constructor(httpClient: CommetHTTPClient);
+    create(params: CreateUsageEventParams, options?: RequestOptions): Promise<ApiResponse<UsageEvent>>;
+    createBatch(params: CreateBatchUsageEventsParams, options?: RequestOptions): Promise<ApiResponse<BatchResult<UsageEvent>>>;
+    retrieve(eventId: EventID): Promise<ApiResponse<UsageEvent>>;
+    list(params?: ListUsageEventsParams): Promise<ApiResponse<UsageEvent[]>>;
+    delete(eventId: EventID, options?: RequestOptions): Promise<ApiResponse<{
+        deleted: boolean;
+    }>>;
+}
+interface UsageMetric {
+    id: string;
+    organizationId: string;
+    name: string;
+    eventType: string;
+    aggregation: "count" | "unique" | "sum";
+    property?: string;
+    filters?: UsageMetricFilter[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface UsageMetricFilter {
+    id: string;
+    usageMetricId: string;
+    property: string;
+    operator: "equals" | "not_equals" | "greater_than" | "less_than" | "contains";
+    value: string;
+    createdAt: string;
+}
+/**
+ * Usage Metrics resource - Read-only access to metrics
+ */
+declare class UsageMetricsResource {
+    private httpClient;
+    constructor(httpClient: CommetHTTPClient);
+    list(): Promise<ApiResponse<UsageMetric[]>>;
+    retrieve(metricId: string): Promise<ApiResponse<UsageMetric>>;
+}
+/**
+ * Usage resource combining events and metrics
+ */
+declare class UsageResource {
+    readonly events: UsageEventsResource;
+    readonly metrics: UsageMetricsResource;
+    constructor(httpClient: CommetHTTPClient);
+}
+
+/**
+ * Main Commet SDK client
+ */
+declare class Commet {
+    private httpClient;
+    private environment;
+    readonly customers: CustomersResource;
+    readonly usage: UsageResource;
+    readonly seats: SeatsResource;
+    constructor(config: CommetConfig);
+    getEnvironment(): Environment;
+    isSandbox(): boolean;
+    isProduction(): boolean;
+}
+
+/**
+ * Check if environment is sandbox
+ */
+declare function isSandbox(environment: Environment): boolean;
+/**
+ * Check if environment is production
+ */
+declare function isProduction(environment: Environment): boolean;
+
+/**
+ * Commet SDK - Billing and usage tracking SDK
+ */
+
+export { type AgreementID, type ApiResponse, type BatchResult, type BulkSeatUpdate, Commet, CommetAPIError, type CommetConfig, CommetError, CommetValidationError, type CreateBatchUsageEventsParams, type CreateCustomerParams, type CreateUsageEventParams, type Currency, type Customer, type CustomerID, type Environment, type EventID, type InvoiceID, type ItemID, type ListCustomersParams, type ListParams, type ListSeatEventsParams, type ListUsageEventsParams, type PaginatedList, type PaginatedResponse, type PhaseID, type ProductID, type RequestOptions, type RetrieveOptions, type SeatBalance, type SeatBalanceResponse, type SeatEvent, type UpdateCustomerParams, type UsageEvent, type UsageEventProperty, type UsageMetric, type UsageMetricFilter, type WebhookID, Commet as default, isProduction, isSandbox };