commet 0.0.1 → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,353 @@
+type Environment = "development" | "production";
+type CommetConfig = {
+    apiKey: string;
+    environment?: "auto" | Environment;
+    debug?: boolean;
+    timeout?: number;
+    retries?: number;
+};
+interface ApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    message?: string;
+    devMode?: boolean;
+}
+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 and dev mode support
+     */
+    private request;
+    /**
+     * Log request in development mode instead of sending to API
+     */
+    private logDevRequest;
+    /**
+     * Execute real API request with retry logic
+     */
+    private executeRequest;
+    /**
+     * 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;
+    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 CreateCustomerParams {
+    legalName: string;
+    displayName?: string;
+    domain?: string;
+    website?: string;
+    taxStatus?: "TAXED" | "TAX_EXEMPT" | "REVERSE_CHARGE" | "NOT_APPLICABLE";
+    currency?: Currency;
+    address: {
+        line1: string;
+        line2?: string;
+        city: string;
+        state?: string;
+        postalCode: string;
+        country: string;
+        region?: string;
+    };
+    billingEmail?: string;
+    paymentTerms?: string;
+    timezone?: string;
+    language?: string;
+    industry?: string;
+    employeeCount?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UpdateCustomerParams {
+    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 {
+    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;
+    isDevelopment(): boolean;
+    isProduction(): boolean;
+}
+
+/**
+ * Detect the current environment based on NODE_ENV and hostname
+ */
+declare function detectEnvironment(): Environment;
+declare function isDevelopment(environment: Environment): boolean;
+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, detectEnvironment, isDevelopment, isProduction };