@commet/node 0.10.1 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -41,13 +41,7 @@ declare class CommetValidationError extends CommetError {
41
41
  constructor(message: string, validationErrors: Record<string, string[]>);
42
42
  }
43
43
  type CustomerID = `cus_${string}`;
44
- type AgreementID = `agr_${string}`;
45
- type InvoiceID = `inv_${string}`;
46
- type PhaseID = `phs_${string}`;
47
- type ItemID = `itm_${string}`;
48
- type ProductID = `prd_${string}`;
49
44
  type EventID = `evt_${string}`;
50
- type WebhookID = `wh_${string}`;
51
45
  type Currency = "USD" | "EUR" | "GBP" | "CAD" | "AUD" | "JPY" | "ARS" | "BRL" | "MXN" | "CLP";
52
46
  interface ListParams extends Record<string, unknown> {
53
47
  limit?: number;
@@ -55,9 +49,6 @@ interface ListParams extends Record<string, unknown> {
55
49
  startDate?: string;
56
50
  endDate?: string;
57
51
  }
58
- interface RetrieveOptions {
59
- expand?: string[];
60
- }
61
52
  interface RequestOptions {
62
53
  idempotencyKey?: string;
63
54
  timeout?: number;
@@ -93,8 +84,14 @@ type GeneratedSeatType = CommetGeneratedTypes extends {
93
84
  /**
94
85
  * Helper type that provides fallback to string if types are not generated
95
86
  */
96
- type GeneratedProductId = CommetGeneratedTypes extends {
97
- productId: infer T;
87
+ type GeneratedPlanCode = CommetGeneratedTypes extends {
88
+ planCode: infer T;
89
+ } ? T : string;
90
+ /**
91
+ * Helper type that provides fallback to string if types are not generated
92
+ */
93
+ type GeneratedFeatureCode = CommetGeneratedTypes extends {
94
+ featureCode: infer T;
98
95
  } ? T : string;
99
96
 
100
97
  declare class CommetHTTPClient {
@@ -136,15 +133,11 @@ interface Customer {
136
133
  id: CustomerID;
137
134
  organizationId: string;
138
135
  externalId?: string;
139
- legalName: string;
136
+ legalName?: string;
140
137
  displayName?: string;
141
138
  domain?: string;
142
139
  website?: string;
143
- taxStatus: "TAXED" | "TAX_EXEMPT" | "REVERSE_CHARGE" | "NOT_APPLICABLE";
144
- currency: Currency;
145
- addressId: string;
146
- billingEmail?: string;
147
- paymentTerms?: string;
140
+ billingEmail: string;
148
141
  timezone?: string;
149
142
  language?: string;
150
143
  industry?: string;
@@ -154,21 +147,6 @@ interface Customer {
154
147
  createdAt: string;
155
148
  updatedAt: string;
156
149
  }
157
- interface CreateCustomerBaseParams {
158
- externalId?: string;
159
- legalName: string;
160
- displayName?: string;
161
- domain?: string;
162
- website?: string;
163
- currency?: Currency;
164
- billingEmail?: string;
165
- paymentTerms?: string;
166
- timezone?: string;
167
- language?: string;
168
- industry?: string;
169
- employeeCount?: string;
170
- metadata?: Record<string, unknown>;
171
- }
172
150
  interface CustomerAddress {
173
151
  line1: string;
174
152
  line2?: string;
@@ -176,67 +154,199 @@ interface CustomerAddress {
176
154
  state?: string;
177
155
  postalCode: string;
178
156
  country: string;
179
- region?: string;
180
157
  }
181
- interface CreateCustomerTaxed extends CreateCustomerBaseParams {
182
- taxStatus: "TAXED";
183
- address: CustomerAddress;
184
- }
185
- interface CreateCustomerOtherTaxStatus extends CreateCustomerBaseParams {
186
- taxStatus?: "TAX_EXEMPT" | "REVERSE_CHARGE" | "NOT_APPLICABLE";
158
+ interface CreateParams {
159
+ email: string;
160
+ externalId?: string;
161
+ legalName?: string;
162
+ displayName?: string;
163
+ domain?: string;
164
+ website?: string;
165
+ timezone?: string;
166
+ language?: string;
167
+ industry?: string;
168
+ metadata?: Record<string, unknown>;
187
169
  address?: CustomerAddress;
188
170
  }
189
- type CreateCustomerParams = CreateCustomerTaxed | CreateCustomerOtherTaxStatus;
190
- interface UpdateCustomerParams {
171
+ interface UpdateParams {
191
172
  externalId?: string;
173
+ email?: string;
192
174
  legalName?: string;
193
175
  displayName?: string;
194
176
  domain?: string;
195
177
  website?: string;
196
- taxStatus?: "TAXED" | "TAX_EXEMPT" | "REVERSE_CHARGE" | "NOT_APPLICABLE";
197
- currency?: Currency;
198
- billingEmail?: string;
199
- paymentTerms?: string;
200
178
  timezone?: string;
201
179
  language?: string;
202
180
  industry?: string;
203
- employeeCount?: string;
204
181
  metadata?: Record<string, unknown>;
205
- isActive?: boolean;
206
182
  }
207
183
  interface ListCustomersParams extends ListParams {
208
184
  externalId?: string;
209
- taxStatus?: "TAXED" | "TAX_EXEMPT" | "REVERSE_CHARGE" | "NOT_APPLICABLE";
210
- currency?: Currency;
211
185
  isActive?: boolean;
212
186
  search?: string;
213
187
  }
188
+ interface BatchResult$1 {
189
+ successful: Customer[];
190
+ failed: Array<{
191
+ index: number;
192
+ error: string;
193
+ data: CreateParams;
194
+ }>;
195
+ }
214
196
  /**
215
- * Customer resource for managing customer data
197
+ * Customers resource - Manage your customers
216
198
  */
217
199
  declare class CustomersResource {
218
200
  private httpClient;
219
201
  constructor(httpClient: CommetHTTPClient);
220
- create(params: CreateCustomerParams, options?: RequestOptions): Promise<ApiResponse<Customer>>;
221
- retrieve(customerId: CustomerID, options?: RetrieveOptions): Promise<ApiResponse<Customer>>;
222
- update(customerId: CustomerID, params: UpdateCustomerParams, options?: RequestOptions): Promise<ApiResponse<Customer>>;
202
+ /**
203
+ * Create a customer (idempotent with externalId)
204
+ */
205
+ create(params: CreateParams, options?: RequestOptions): Promise<ApiResponse<Customer>>;
206
+ /**
207
+ * Create multiple customers in batch
208
+ */
209
+ createBatch(params: {
210
+ customers: CreateParams[];
211
+ }, options?: RequestOptions): Promise<ApiResponse<BatchResult$1>>;
212
+ /**
213
+ * Get a customer by ID
214
+ */
215
+ get(customerId: CustomerID): Promise<ApiResponse<Customer>>;
216
+ /**
217
+ * Update a customer
218
+ */
219
+ update(customerId: CustomerID, params: UpdateParams, options?: RequestOptions): Promise<ApiResponse<Customer>>;
220
+ /**
221
+ * List customers with optional filters
222
+ */
223
223
  list(params?: ListCustomersParams): Promise<ApiResponse<Customer[]>>;
224
224
  /**
225
- * Deactivate a customer (soft delete)
225
+ * Archive a customer
226
226
  */
227
- deactivate(customerId: CustomerID, options?: RequestOptions): Promise<ApiResponse<Customer>>;
227
+ archive(customerId: CustomerID, options?: RequestOptions): Promise<ApiResponse<Customer>>;
228
228
  }
229
229
 
230
- interface SeatBalance {
231
- id: string;
232
- organizationId: string;
233
- customerId: CustomerID;
234
- seatType: GeneratedSeatType;
235
- balance: number;
236
- asOf: string;
230
+ type PlanID = `plan_${string}`;
231
+ type BillingInterval = "monthly" | "quarterly" | "yearly";
232
+ type FeatureType = "boolean" | "metered" | "seats";
233
+ interface PlanPrice {
234
+ billingInterval: BillingInterval;
235
+ price: number;
236
+ isDefault: boolean;
237
+ }
238
+ interface PlanFeature {
239
+ code: string;
240
+ name: string;
241
+ type: FeatureType;
242
+ enabled?: boolean;
243
+ includedAmount?: number;
244
+ unlimited?: boolean;
245
+ overageEnabled?: boolean;
246
+ overageUnitPrice?: number;
247
+ }
248
+ interface Plan {
249
+ id: PlanID;
250
+ name: string;
251
+ description?: string;
252
+ isPublic: boolean;
253
+ isDefault: boolean;
254
+ trialDays: number;
255
+ sortOrder: number;
256
+ prices: PlanPrice[];
257
+ features: PlanFeature[];
237
258
  createdAt: string;
259
+ }
260
+ interface PlanDetail extends Plan {
261
+ features: Array<PlanFeature & {
262
+ unitName?: string;
263
+ overage?: {
264
+ enabled: boolean;
265
+ model: "per_unit" | "tiered";
266
+ unitPrice: number;
267
+ tiers?: Array<{
268
+ order: number;
269
+ upTo: number | null;
270
+ unitAmount: number;
271
+ flatFee: number;
272
+ }>;
273
+ } | null;
274
+ }>;
238
275
  updatedAt: string;
239
276
  }
277
+ interface ListPlansParams extends ListParams {
278
+ includePrivate?: boolean;
279
+ }
280
+ /**
281
+ * Plans resource for listing available plans
282
+ */
283
+ declare class PlansResource {
284
+ private httpClient;
285
+ constructor(httpClient: CommetHTTPClient);
286
+ /**
287
+ * List all available plans
288
+ *
289
+ * @example
290
+ * ```typescript
291
+ * // List public plans
292
+ * const plans = await commet.plans.list();
293
+ *
294
+ * // Include private plans
295
+ * const allPlans = await commet.plans.list({ includePrivate: true });
296
+ * ```
297
+ */
298
+ list(params?: ListPlansParams): Promise<ApiResponse<Plan[]>>;
299
+ /**
300
+ * Get a specific plan by ID
301
+ *
302
+ * @example
303
+ * ```typescript
304
+ * const plan = await commet.plans.get('plan_xxx');
305
+ * console.log(plan.data.name); // "Pro"
306
+ * console.log(plan.data.prices); // [{ billingInterval: 'monthly', price: 9900 }]
307
+ * ```
308
+ */
309
+ get(planId: string): Promise<ApiResponse<PlanDetail>>;
310
+ }
311
+
312
+ interface PortalAccess {
313
+ success: boolean;
314
+ message: string;
315
+ portalUrl: string;
316
+ }
317
+ interface GetUrlByCustomerId {
318
+ customerId: CustomerID;
319
+ email?: never;
320
+ externalId?: never;
321
+ }
322
+ interface GetUrlByExternalId {
323
+ externalId: string;
324
+ email?: never;
325
+ customerId?: never;
326
+ }
327
+ interface GetUrlByEmail {
328
+ email: string;
329
+ customerId?: never;
330
+ externalId?: never;
331
+ }
332
+ type GetUrlParams = GetUrlByCustomerId | GetUrlByExternalId | GetUrlByEmail;
333
+ /**
334
+ * Portal resource - Generate customer portal access
335
+ */
336
+ declare class PortalResource {
337
+ private httpClient;
338
+ constructor(httpClient: CommetHTTPClient);
339
+ /**
340
+ * Get a portal URL
341
+ *
342
+ * @example
343
+ * ```typescript
344
+ * const portal = await commet.portal.getUrl({ externalId: 'user_123' });
345
+ * ```
346
+ */
347
+ getUrl(params: GetUrlParams, options?: RequestOptions): Promise<ApiResponse<PortalAccess>>;
348
+ }
349
+
240
350
  interface SeatEvent {
241
351
  id: string;
242
352
  organizationId: string;
@@ -249,35 +359,32 @@ interface SeatEvent {
249
359
  ts: string;
250
360
  createdAt: string;
251
361
  }
252
- interface SeatBalanceResponse {
362
+ interface SeatBalance {
253
363
  current: number;
254
364
  asOf: string;
255
365
  }
256
- interface BulkSeatUpdate {
257
- [seatType: string]: number;
258
- }
259
- interface AddSeatsParams {
366
+ interface AddParams {
260
367
  customerId?: CustomerID;
261
368
  externalId?: string;
262
369
  seatType: GeneratedSeatType;
263
370
  count: number;
264
371
  }
265
- interface RemoveSeatsParams {
372
+ interface RemoveParams {
266
373
  customerId?: CustomerID;
267
374
  externalId?: string;
268
375
  seatType: GeneratedSeatType;
269
376
  count: number;
270
377
  }
271
- interface SetSeatsParams {
378
+ interface SetParams {
272
379
  customerId?: CustomerID;
273
380
  externalId?: string;
274
381
  seatType: GeneratedSeatType;
275
382
  count: number;
276
383
  }
277
- interface BulkUpdateSeatsParams {
384
+ interface SetAllParams {
278
385
  customerId?: CustomerID;
279
386
  externalId?: string;
280
- seats: BulkSeatUpdate;
387
+ seats: Record<string, number>;
281
388
  }
282
389
  interface GetBalanceParams {
283
390
  customerId?: CustomerID;
@@ -288,48 +395,145 @@ interface GetAllBalancesParams {
288
395
  customerId?: CustomerID;
289
396
  externalId?: string;
290
397
  }
291
- interface ListSeatEventsParams extends ListParams {
292
- customerId?: CustomerID;
293
- externalId?: string;
294
- seatType?: GeneratedSeatType;
295
- eventType?: "add" | "remove" | "set";
296
- }
297
398
  /**
298
- * Seats resource for seat-based billing management
399
+ * Seats resource - Manage seat-based licenses
299
400
  */
300
401
  declare class SeatsResource {
301
402
  private httpClient;
302
403
  constructor(httpClient: CommetHTTPClient);
303
- add(params: AddSeatsParams, options?: RequestOptions): Promise<ApiResponse<SeatEvent>>;
304
- remove(params: RemoveSeatsParams, options?: RequestOptions): Promise<ApiResponse<SeatEvent>>;
305
- set(params: SetSeatsParams, options?: RequestOptions): Promise<ApiResponse<SeatEvent>>;
306
- bulkUpdate(params: BulkUpdateSeatsParams, options?: RequestOptions): Promise<ApiResponse<SeatEvent[]>>;
307
- getBalance(params: GetBalanceParams): Promise<ApiResponse<SeatBalanceResponse>>;
308
- getAllBalances(params: GetAllBalancesParams): Promise<ApiResponse<Record<string, SeatBalanceResponse>>>;
309
- listEvents(params?: ListSeatEventsParams): Promise<ApiResponse<SeatEvent[]>>;
404
+ /**
405
+ * Add seats
406
+ *
407
+ * @example
408
+ * ```typescript
409
+ * await commet.seats.add({
410
+ * externalId: 'user_123',
411
+ * seatType: 'editor',
412
+ * count: 5
413
+ * });
414
+ * ```
415
+ */
416
+ add(params: AddParams, options?: RequestOptions): Promise<ApiResponse<SeatEvent>>;
417
+ /**
418
+ * Remove seats
419
+ *
420
+ * @example
421
+ * ```typescript
422
+ * await commet.seats.remove({
423
+ * externalId: 'user_123',
424
+ * seatType: 'editor',
425
+ * count: 2
426
+ * });
427
+ * ```
428
+ */
429
+ remove(params: RemoveParams, options?: RequestOptions): Promise<ApiResponse<SeatEvent>>;
430
+ /**
431
+ * Set seats to a specific count
432
+ *
433
+ * @example
434
+ * ```typescript
435
+ * await commet.seats.set({
436
+ * externalId: 'user_123',
437
+ * seatType: 'editor',
438
+ * count: 10
439
+ * });
440
+ * ```
441
+ */
442
+ set(params: SetParams, options?: RequestOptions): Promise<ApiResponse<SeatEvent>>;
443
+ /**
444
+ * Set all seat types
445
+ *
446
+ * @example
447
+ * ```typescript
448
+ * await commet.seats.setAll({
449
+ * externalId: 'user_123',
450
+ * seats: { editor: 10, viewer: 50 }
451
+ * });
452
+ * ```
453
+ */
454
+ setAll(params: SetAllParams, options?: RequestOptions): Promise<ApiResponse<SeatEvent[]>>;
455
+ /**
456
+ * Get balance for a seat type
457
+ *
458
+ * @example
459
+ * ```typescript
460
+ * const balance = await commet.seats.getBalance({
461
+ * externalId: 'user_123',
462
+ * seatType: 'editor'
463
+ * });
464
+ * ```
465
+ */
466
+ getBalance(params: GetBalanceParams): Promise<ApiResponse<SeatBalance>>;
467
+ /**
468
+ * Get all seat balances
469
+ *
470
+ * @example
471
+ * ```typescript
472
+ * const balances = await commet.seats.getAllBalances({
473
+ * externalId: 'user_123'
474
+ * });
475
+ * ```
476
+ */
477
+ getAllBalances(params: GetAllBalancesParams): Promise<ApiResponse<Record<string, SeatBalance>>>;
310
478
  }
311
479
 
312
- interface Subscription {
480
+ type SubscriptionStatus = "draft" | "pending_payment" | "trialing" | "active" | "paused" | "past_due" | "canceled" | "expired";
481
+ interface FeatureSummary {
482
+ code: string;
483
+ name: string;
484
+ type: "boolean" | "metered" | "seats";
485
+ enabled?: boolean;
486
+ usage?: {
487
+ current: number;
488
+ included: number;
489
+ overage: number;
490
+ };
491
+ }
492
+ interface ActiveSubscription {
313
493
  id: string;
314
494
  customerId: string;
495
+ plan: {
496
+ id: string;
497
+ name: string;
498
+ basePrice: number;
499
+ billingInterval: BillingInterval;
500
+ };
315
501
  name: string;
316
502
  description?: string;
317
- status: "draft" | "pending_payment" | "active" | "completed" | "canceled";
503
+ status: SubscriptionStatus;
504
+ trialEndsAt?: string;
505
+ currentPeriod: {
506
+ start: string;
507
+ end: string;
508
+ daysRemaining: number;
509
+ };
510
+ features: FeatureSummary[];
318
511
  startDate: string;
319
512
  endDate?: string;
320
513
  billingDayOfMonth: number;
321
- totalContractValue?: number;
322
- poNumber?: string;
323
- reference?: string;
324
- isTemplate?: boolean;
514
+ nextBillingDate: string;
325
515
  checkoutUrl?: string;
326
516
  createdAt: string;
327
517
  updatedAt: string;
328
518
  }
329
- interface SubscriptionItem {
330
- priceId: string;
331
- quantity?: number;
332
- initialSeats?: number;
519
+ interface Subscription {
520
+ id: string;
521
+ customerId: string;
522
+ planId: string;
523
+ planName: string;
524
+ name: string;
525
+ description?: string;
526
+ status: SubscriptionStatus;
527
+ billingInterval: BillingInterval;
528
+ trialEndsAt?: string;
529
+ startDate: string;
530
+ endDate?: string;
531
+ currentPeriodStart?: string;
532
+ currentPeriodEnd?: string;
533
+ billingDayOfMonth: number;
534
+ checkoutUrl?: string;
535
+ createdAt: string;
536
+ updatedAt: string;
333
537
  }
334
538
  type CustomerIdentifier = {
335
539
  customerId: string;
@@ -338,82 +542,81 @@ type CustomerIdentifier = {
338
542
  customerId?: never;
339
543
  externalId: string;
340
544
  };
341
- type CreateSubscriptionParams = CustomerIdentifier & {
342
- items: SubscriptionItem[];
545
+ type PlanIdentifier = {
546
+ planCode: GeneratedPlanCode;
547
+ planId?: never;
548
+ } | {
549
+ planCode?: never;
550
+ planId: string;
551
+ };
552
+ type CreateSubscriptionParams = CustomerIdentifier & PlanIdentifier & {
553
+ billingInterval?: BillingInterval;
554
+ initialSeats?: Record<string, number>;
555
+ skipTrial?: boolean;
343
556
  name?: string;
344
557
  startDate?: string;
345
- status?: "draft" | "pending_payment" | "active";
346
558
  };
347
- interface ListSubscriptionsParams extends ListParams {
348
- customerId?: string;
349
- externalId?: string;
350
- status?: "draft" | "pending_payment" | "active" | "completed" | "canceled";
559
+ type ChangePlanParams = PlanIdentifier & {
560
+ billingInterval?: BillingInterval;
561
+ };
562
+ interface CancelParams {
563
+ reason?: string;
564
+ immediate?: boolean;
351
565
  }
566
+ type GetSubscriptionParams = CustomerIdentifier;
352
567
  /**
353
- * Subscription resource for managing subscriptions
568
+ * Subscription resource for managing subscriptions (plan-first model)
569
+ *
570
+ * Each customer can only have ONE active subscription at a time.
354
571
  */
355
572
  declare class SubscriptionsResource {
356
573
  private httpClient;
357
574
  constructor(httpClient: CommetHTTPClient);
358
575
  /**
359
- * Create a subscription with multiple items (products)
576
+ * Create a subscription with a plan
360
577
  *
361
578
  * @example
362
579
  * ```typescript
363
- * // Free plan - Multiple products
364
580
  * await commet.subscriptions.create({
365
- * externalId: "org_123",
366
- * items: [
367
- * { priceId: "price_tasks_free", quantity: 1 },
368
- * { priceId: "price_usage_free" },
369
- * { priceId: "price_seats_free", initialSeats: 1 }
370
- * ]
371
- * });
372
- *
373
- * // Pro plan upgrade
374
- * await commet.subscriptions.create({
375
- * customerId: "cus_xxx",
376
- * items: [
377
- * { priceId: "price_tasks_pro" },
378
- * { priceId: "price_usage_pro" },
379
- * { priceId: "price_seats_pro", initialSeats: 5 }
380
- * ],
381
- * status: "active"
581
+ * externalId: 'user_123',
582
+ * planCode: 'pro', // autocomplete works after `commet pull`
583
+ * billingInterval: 'yearly',
584
+ * initialSeats: { editor: 5 }
382
585
  * });
383
586
  * ```
384
587
  */
385
588
  create(params: CreateSubscriptionParams, options?: RequestOptions): Promise<ApiResponse<Subscription>>;
386
589
  /**
387
- * Retrieve a subscription by ID
590
+ * Get the active subscription for a customer
591
+ *
592
+ * @example
593
+ * ```typescript
594
+ * const sub = await commet.subscriptions.get({ externalId: 'user_123' });
595
+ * ```
388
596
  */
389
- retrieve(subscriptionId: string, options?: RetrieveOptions): Promise<ApiResponse<Subscription>>;
597
+ get(params: GetSubscriptionParams): Promise<ApiResponse<ActiveSubscription | null>>;
390
598
  /**
391
- * List subscriptions with optional filters
599
+ * Change the plan of a subscription (upgrade/downgrade)
392
600
  *
393
601
  * @example
394
602
  * ```typescript
395
- * // List all active subscriptions for a customer
396
- * await commet.subscriptions.list({
397
- * customerId: "cus_xxx",
398
- * status: "active"
399
- * });
400
- *
401
- * // Using externalId
402
- * await commet.subscriptions.list({
403
- * externalId: "my-customer-123"
603
+ * await commet.subscriptions.changePlan('sub_xxx', {
604
+ * planCode: 'enterprise' // autocomplete works after `commet pull`
404
605
  * });
405
606
  * ```
406
607
  */
407
- list(params?: ListSubscriptionsParams): Promise<ApiResponse<Subscription[]>>;
608
+ changePlan(subscriptionId: string, params: ChangePlanParams, options?: RequestOptions): Promise<ApiResponse<Subscription>>;
408
609
  /**
409
610
  * Cancel a subscription
410
611
  *
411
612
  * @example
412
613
  * ```typescript
413
- * await commet.subscriptions.cancel("sub_xxx");
614
+ * await commet.subscriptions.cancel('sub_xxx', {
615
+ * reason: 'switched_to_competitor'
616
+ * });
414
617
  * ```
415
618
  */
416
- cancel(subscriptionId: string, options?: RequestOptions): Promise<ApiResponse<Subscription>>;
619
+ cancel(subscriptionId: string, params?: CancelParams, options?: RequestOptions): Promise<ApiResponse<Subscription>>;
417
620
  }
418
621
 
419
622
  interface UsageEvent {
@@ -433,47 +636,59 @@ interface UsageEventProperty {
433
636
  value: string;
434
637
  createdAt: string;
435
638
  }
436
- interface CreateUsageEventParams {
437
- eventType: GeneratedEventType;
438
- customerId?: CustomerID;
439
- externalId?: string;
440
- idempotencyKey?: string;
441
- timestamp?: string;
442
- properties?: Array<{
443
- property: string;
444
- value: string;
445
- }>;
446
- }
447
- interface CreateBatchUsageEventsParams {
448
- events: CreateUsageEventParams[];
449
- }
450
639
  interface BatchResult<T> {
451
640
  successful: T[];
452
641
  failed: Array<{
453
642
  index: number;
454
643
  error: string;
455
- data: CreateUsageEventParams;
644
+ data: TrackParams;
456
645
  }>;
457
646
  }
458
- interface ListUsageEventsParams extends ListParams {
647
+ interface TrackParams {
648
+ eventType: GeneratedEventType;
459
649
  customerId?: CustomerID;
460
650
  externalId?: string;
461
- eventType?: GeneratedEventType;
462
651
  idempotencyKey?: string;
652
+ value?: number;
653
+ timestamp?: string;
654
+ properties?: Record<string, string>;
463
655
  }
464
656
  /**
465
- * Usage Events resource - Track business events for usage-based billing
657
+ * Usage resource - Track consumption events for usage-based billing
466
658
  */
467
659
  declare class UsageResource {
468
660
  private httpClient;
469
661
  constructor(httpClient: CommetHTTPClient);
470
- create(params: CreateUsageEventParams, options?: RequestOptions): Promise<ApiResponse<UsageEvent>>;
471
- createBatch(params: CreateBatchUsageEventsParams, options?: RequestOptions): Promise<ApiResponse<BatchResult<UsageEvent>>>;
472
- retrieve(eventId: EventID): Promise<ApiResponse<UsageEvent>>;
473
- list(params?: ListUsageEventsParams): Promise<ApiResponse<UsageEvent[]>>;
474
- delete(eventId: EventID, options?: RequestOptions): Promise<ApiResponse<{
475
- deleted: boolean;
476
- }>>;
662
+ /**
663
+ * Track a usage event
664
+ *
665
+ * @example
666
+ * ```typescript
667
+ * await commet.usage.track({
668
+ * externalId: 'user_123',
669
+ * eventType: 'api_call',
670
+ * idempotencyKey: `evt_${requestId}`,
671
+ * properties: { endpoint: '/users', method: 'GET' }
672
+ * });
673
+ * ```
674
+ */
675
+ track(params: TrackParams, options?: RequestOptions): Promise<ApiResponse<UsageEvent>>;
676
+ /**
677
+ * Track multiple usage events in a batch
678
+ *
679
+ * @example
680
+ * ```typescript
681
+ * await commet.usage.trackBatch({
682
+ * events: [
683
+ * { externalId: 'user_123', eventType: 'api_call', idempotencyKey: 'evt_1' },
684
+ * { externalId: 'user_456', eventType: 'api_call', idempotencyKey: 'evt_2' }
685
+ * ]
686
+ * });
687
+ * ```
688
+ */
689
+ trackBatch(params: {
690
+ events: TrackParams[];
691
+ }, options?: RequestOptions): Promise<ApiResponse<BatchResult<UsageEvent>>>;
477
692
  }
478
693
 
479
694
  /**
@@ -582,9 +797,11 @@ declare class Commet {
582
797
  private httpClient;
583
798
  private environment;
584
799
  readonly customers: CustomersResource;
800
+ readonly plans: PlansResource;
585
801
  readonly usage: UsageResource;
586
802
  readonly seats: SeatsResource;
587
803
  readonly subscriptions: SubscriptionsResource;
804
+ readonly portal: PortalResource;
588
805
  readonly webhooks: Webhooks;
589
806
  constructor(config: CommetConfig);
590
807
  getEnvironment(): Environment;
@@ -602,7 +819,7 @@ declare function isSandbox(environment: Environment): boolean;
602
819
  declare function isProduction(environment: Environment): boolean;
603
820
 
604
821
  /**
605
- * Commet SDK - Billing and usage tracking SDK
822
+ * Commet SDK - Billing and usage tracking for SaaS
606
823
  */
607
824
 
608
- 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, Webhooks, Commet as default, isProduction, isSandbox };
825
+ export { type ActiveSubscription, type AddParams as AddSeatsParams, type ApiResponse, type BillingInterval, type CancelParams, type ChangePlanParams, Commet, CommetAPIError, type CommetConfig, CommetError, type CommetGeneratedTypes, CommetValidationError, type CreateParams as CreateCustomerParams, type CreateSubscriptionParams, type Currency, type Customer, type CustomerAddress, type CustomerID, type BatchResult$1 as CustomersBatchResult, type Environment, type EventID, type FeatureSummary, type FeatureType, type GeneratedEventType, type GeneratedFeatureCode, type GeneratedPlanCode, type GeneratedSeatType, type GetAllBalancesParams, type GetBalanceParams, type GetSubscriptionParams, 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 TrackParams, type UpdateParams as UpdateCustomerParams, type BatchResult as UsageBatchResult, type UsageEvent, type UsageEventProperty, type WebhookData, type WebhookEvent, type WebhookPayload, Webhooks, Commet as default, isProduction, isSandbox };