@commet/node 1.0.1 → 1.1.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
@@ -129,222 +129,89 @@ declare class CommetHTTPClient {
129
129
  private sleep;
130
130
  }
131
131
 
132
- interface Customer {
133
- id: CustomerID;
134
- organizationId: string;
135
- externalId?: string;
136
- legalName?: string;
137
- displayName?: string;
138
- domain?: string;
139
- website?: string;
140
- billingEmail: string;
141
- timezone?: string;
142
- language?: string;
143
- industry?: string;
144
- employeeCount?: string;
145
- metadata?: Record<string, unknown>;
146
- isActive: boolean;
147
- createdAt: string;
148
- updatedAt: string;
149
- }
150
- interface CustomerAddress {
151
- line1: string;
152
- line2?: string;
153
- city: string;
154
- state?: string;
155
- postalCode: string;
156
- country: string;
157
- }
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>;
169
- address?: CustomerAddress;
170
- }
171
- interface UpdateParams {
172
- externalId?: string;
173
- email?: string;
174
- legalName?: string;
175
- displayName?: string;
176
- domain?: string;
177
- website?: string;
178
- timezone?: string;
179
- language?: string;
180
- industry?: string;
181
- metadata?: Record<string, unknown>;
182
- }
183
- interface ListCustomersParams extends ListParams {
184
- externalId?: string;
185
- isActive?: boolean;
186
- search?: string;
187
- }
188
- interface BatchResult$1 {
189
- successful: Customer[];
190
- failed: Array<{
191
- index: number;
192
- error: string;
193
- data: CreateParams;
194
- }>;
195
- }
196
- /**
197
- * Customers resource - Manage your customers
198
- */
199
- declare class CustomersResource {
200
- private httpClient;
201
- constructor(httpClient: CommetHTTPClient);
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
- list(params?: ListCustomersParams): Promise<ApiResponse<Customer[]>>;
224
- /**
225
- * Archive a customer
226
- */
227
- archive(customerId: CustomerID, options?: RequestOptions): Promise<ApiResponse<Customer>>;
228
- }
229
-
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 {
132
+ interface FeatureAccess {
239
133
  code: string;
240
134
  name: string;
241
- type: FeatureType;
135
+ type: "boolean" | "metered" | "seats";
136
+ allowed: boolean;
242
137
  enabled?: boolean;
243
- includedAmount?: number;
138
+ current?: number;
139
+ included?: number;
140
+ remaining?: number;
141
+ overage?: number;
142
+ overageUnitPrice?: number;
244
143
  unlimited?: boolean;
245
144
  overageEnabled?: boolean;
246
- overageUnitPrice?: number;
247
145
  }
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[];
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
- }>;
275
- updatedAt: string;
146
+ interface CanUseResult {
147
+ allowed: boolean;
148
+ willBeCharged: boolean;
149
+ reason?: string;
276
150
  }
277
- interface ListPlansParams extends ListParams {
278
- includePrivate?: boolean;
151
+ interface CheckResult {
152
+ allowed: boolean;
279
153
  }
280
154
  /**
281
- * Plans resource for listing available plans
155
+ * Features resource for checking feature access and usage
156
+ *
157
+ * Provides a clean API to check if a customer can use a feature
158
+ * without having to manually parse subscription data.
282
159
  */
283
- declare class PlansResource {
160
+ declare class FeaturesResource {
284
161
  private httpClient;
285
162
  constructor(httpClient: CommetHTTPClient);
286
163
  /**
287
- * List all available plans
164
+ * Get detailed feature access/usage for a customer
288
165
  *
289
166
  * @example
290
167
  * ```typescript
291
- * // List public plans
292
- * const plans = await commet.plans.list();
168
+ * const seats = await commet.features.get("team_members", "user_123");
169
+ * console.log(seats.current, seats.included, seats.remaining);
170
+ * ```
171
+ */
172
+ get(code: GeneratedFeatureCode, externalId: string, options?: RequestOptions): Promise<ApiResponse<FeatureAccess>>;
173
+ /**
174
+ * Check if a boolean feature is enabled for a customer
293
175
  *
294
- * // Include private plans
295
- * const allPlans = await commet.plans.list({ includePrivate: true });
176
+ * @example
177
+ * ```typescript
178
+ * const { allowed } = await commet.features.check("custom_branding", "user_123");
179
+ * if (!allowed) redirect("/upgrade");
296
180
  * ```
297
181
  */
298
- list(params?: ListPlansParams): Promise<ApiResponse<Plan[]>>;
182
+ check(code: GeneratedFeatureCode, externalId: string, options?: RequestOptions): Promise<ApiResponse<CheckResult>>;
299
183
  /**
300
- * Get a specific plan by code
184
+ * Check if customer can use one more unit of a feature
185
+ *
186
+ * Returns whether the customer can add one more (allowed)
187
+ * and whether they'll be charged extra (willBeCharged).
301
188
  *
302
189
  * @example
303
190
  * ```typescript
304
- * const plan = await commet.plans.get('pro');
305
- * console.log(plan.data.name); // "Pro"
306
- * console.log(plan.data.prices); // [{ billingInterval: 'monthly', price: 9900 }]
191
+ * const { allowed, willBeCharged } = await commet.features.canUse("team_members", "user_123");
192
+ *
193
+ * if (!allowed) {
194
+ * return { error: "Upgrade to add more members" };
195
+ * }
196
+ *
197
+ * if (willBeCharged) {
198
+ * // Show confirmation: "This will cost $10/month extra"
199
+ * }
307
200
  * ```
308
201
  */
309
- get(planCode: GeneratedPlanCode): 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);
202
+ canUse(code: GeneratedFeatureCode, externalId: string, options?: RequestOptions): Promise<ApiResponse<CanUseResult>>;
339
203
  /**
340
- * Get a portal URL
204
+ * List all features for a customer's active subscription
341
205
  *
342
206
  * @example
343
207
  * ```typescript
344
- * const portal = await commet.portal.getUrl({ externalId: 'user_123' });
208
+ * const features = await commet.features.list("user_123");
209
+ * for (const feature of features) {
210
+ * console.log(feature.code, feature.allowed);
211
+ * }
345
212
  * ```
346
213
  */
347
- getUrl(params: GetUrlParams, options?: RequestOptions): Promise<ApiResponse<PortalAccess>>;
214
+ list(externalId: string, options?: RequestOptions): Promise<ApiResponse<FeatureAccess[]>>;
348
215
  }
349
216
 
350
217
  interface SeatEvent {
@@ -441,40 +308,194 @@ declare class SeatsResource {
441
308
  */
442
309
  set(params: SetParams, options?: RequestOptions): Promise<ApiResponse<SeatEvent>>;
443
310
  /**
444
- * Set all seat types
311
+ * Set all seat types
312
+ *
313
+ * @example
314
+ * ```typescript
315
+ * await commet.seats.setAll({
316
+ * externalId: 'user_123',
317
+ * seats: { editor: 10, viewer: 50 }
318
+ * });
319
+ * ```
320
+ */
321
+ setAll(params: SetAllParams, options?: RequestOptions): Promise<ApiResponse<SeatEvent[]>>;
322
+ /**
323
+ * Get balance for a seat type
324
+ *
325
+ * @example
326
+ * ```typescript
327
+ * const balance = await commet.seats.getBalance({
328
+ * externalId: 'user_123',
329
+ * seatType: 'editor'
330
+ * });
331
+ * ```
332
+ */
333
+ getBalance(params: GetBalanceParams): Promise<ApiResponse<SeatBalance>>;
334
+ /**
335
+ * Get all seat balances
336
+ *
337
+ * @example
338
+ * ```typescript
339
+ * const balances = await commet.seats.getAllBalances({
340
+ * externalId: 'user_123'
341
+ * });
342
+ * ```
343
+ */
344
+ getAllBalances(params: GetAllBalancesParams): Promise<ApiResponse<Record<string, SeatBalance>>>;
345
+ }
346
+
347
+ interface UsageEvent {
348
+ id: EventID;
349
+ organizationId: string;
350
+ customerId: CustomerID;
351
+ eventType: GeneratedEventType;
352
+ idempotencyKey?: string;
353
+ ts: string;
354
+ properties?: UsageEventProperty[];
355
+ createdAt: string;
356
+ }
357
+ interface UsageEventProperty {
358
+ id: string;
359
+ usageEventId: EventID;
360
+ property: string;
361
+ value: string;
362
+ createdAt: string;
363
+ }
364
+ interface BatchResult$1<T> {
365
+ successful: T[];
366
+ failed: Array<{
367
+ index: number;
368
+ error: string;
369
+ data: TrackParams;
370
+ }>;
371
+ }
372
+ interface TrackParams {
373
+ eventType: GeneratedEventType;
374
+ customerId?: CustomerID;
375
+ externalId?: string;
376
+ idempotencyKey?: string;
377
+ value?: number;
378
+ timestamp?: string;
379
+ properties?: Record<string, string>;
380
+ }
381
+ /**
382
+ * Usage resource - Track consumption events for usage-based billing
383
+ */
384
+ declare class UsageResource {
385
+ private httpClient;
386
+ constructor(httpClient: CommetHTTPClient);
387
+ /**
388
+ * Track a usage event
389
+ *
390
+ * @example
391
+ * ```typescript
392
+ * await commet.usage.track({
393
+ * externalId: 'user_123',
394
+ * eventType: 'api_call',
395
+ * idempotencyKey: `evt_${requestId}`,
396
+ * properties: { endpoint: '/users', method: 'GET' }
397
+ * });
398
+ * ```
399
+ */
400
+ track(params: TrackParams, options?: RequestOptions): Promise<ApiResponse<UsageEvent>>;
401
+ /**
402
+ * Track multiple usage events in a batch
403
+ *
404
+ * @example
405
+ * ```typescript
406
+ * await commet.usage.trackBatch({
407
+ * events: [
408
+ * { externalId: 'user_123', eventType: 'api_call', idempotencyKey: 'evt_1' },
409
+ * { externalId: 'user_456', eventType: 'api_call', idempotencyKey: 'evt_2' }
410
+ * ]
411
+ * });
412
+ * ```
413
+ */
414
+ trackBatch(params: {
415
+ events: TrackParams[];
416
+ }, options?: RequestOptions): Promise<ApiResponse<BatchResult$1<UsageEvent>>>;
417
+ }
418
+
419
+ type PlanID = `plan_${string}`;
420
+ type BillingInterval = "monthly" | "quarterly" | "yearly";
421
+ type FeatureType = "boolean" | "metered" | "seats";
422
+ interface PlanPrice {
423
+ billingInterval: BillingInterval;
424
+ price: number;
425
+ isDefault: boolean;
426
+ }
427
+ interface PlanFeature {
428
+ code: string;
429
+ name: string;
430
+ type: FeatureType;
431
+ enabled?: boolean;
432
+ includedAmount?: number;
433
+ unlimited?: boolean;
434
+ overageEnabled?: boolean;
435
+ overageUnitPrice?: number;
436
+ }
437
+ interface Plan {
438
+ id: PlanID;
439
+ name: string;
440
+ description?: string;
441
+ isPublic: boolean;
442
+ isDefault: boolean;
443
+ trialDays: number;
444
+ sortOrder: number;
445
+ prices: PlanPrice[];
446
+ features: PlanFeature[];
447
+ createdAt: string;
448
+ }
449
+ interface PlanDetail extends Plan {
450
+ features: Array<PlanFeature & {
451
+ unitName?: string;
452
+ overage?: {
453
+ enabled: boolean;
454
+ model: "per_unit" | "tiered";
455
+ unitPrice: number;
456
+ tiers?: Array<{
457
+ order: number;
458
+ upTo: number | null;
459
+ unitAmount: number;
460
+ flatFee: number;
461
+ }>;
462
+ } | null;
463
+ }>;
464
+ updatedAt: string;
465
+ }
466
+ interface ListPlansParams extends ListParams {
467
+ includePrivate?: boolean;
468
+ }
469
+ /**
470
+ * Plans resource for listing available plans
471
+ */
472
+ declare class PlansResource {
473
+ private httpClient;
474
+ constructor(httpClient: CommetHTTPClient);
475
+ /**
476
+ * List all available plans
445
477
  *
446
478
  * @example
447
479
  * ```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
480
+ * // List public plans
481
+ * const plans = await commet.plans.list();
457
482
  *
458
- * @example
459
- * ```typescript
460
- * const balance = await commet.seats.getBalance({
461
- * externalId: 'user_123',
462
- * seatType: 'editor'
463
- * });
483
+ * // Include private plans
484
+ * const allPlans = await commet.plans.list({ includePrivate: true });
464
485
  * ```
465
486
  */
466
- getBalance(params: GetBalanceParams): Promise<ApiResponse<SeatBalance>>;
487
+ list(params?: ListPlansParams): Promise<ApiResponse<Plan[]>>;
467
488
  /**
468
- * Get all seat balances
489
+ * Get a specific plan by code
469
490
  *
470
491
  * @example
471
492
  * ```typescript
472
- * const balances = await commet.seats.getAllBalances({
473
- * externalId: 'user_123'
474
- * });
493
+ * const plan = await commet.plans.get('pro');
494
+ * console.log(plan.data.name); // "Pro"
495
+ * console.log(plan.data.prices); // [{ billingInterval: 'monthly', price: 9900 }]
475
496
  * ```
476
497
  */
477
- getAllBalances(params: GetAllBalancesParams): Promise<ApiResponse<Record<string, SeatBalance>>>;
498
+ get(planCode: GeneratedPlanCode): Promise<ApiResponse<PlanDetail>>;
478
499
  }
479
500
 
480
501
  type SubscriptionStatus = "draft" | "pending_payment" | "trialing" | "active" | "paused" | "past_due" | "canceled" | "expired";
@@ -487,6 +508,7 @@ interface FeatureSummary {
487
508
  current: number;
488
509
  included: number;
489
510
  overage: number;
511
+ overageUnitPrice?: number;
490
512
  };
491
513
  }
492
514
  interface ActiveSubscription {
@@ -619,76 +641,238 @@ declare class SubscriptionsResource {
619
641
  cancel(subscriptionId: string, params?: CancelParams, options?: RequestOptions): Promise<ApiResponse<Subscription>>;
620
642
  }
621
643
 
622
- interface UsageEvent {
623
- id: EventID;
624
- organizationId: string;
644
+ interface PortalAccess {
645
+ success: boolean;
646
+ message: string;
647
+ portalUrl: string;
648
+ }
649
+ interface GetUrlByCustomerId {
625
650
  customerId: CustomerID;
626
- eventType: GeneratedEventType;
627
- idempotencyKey?: string;
628
- ts: string;
629
- properties?: UsageEventProperty[];
630
- createdAt: string;
651
+ email?: never;
652
+ externalId?: never;
631
653
  }
632
- interface UsageEventProperty {
633
- id: string;
634
- usageEventId: EventID;
635
- property: string;
636
- value: string;
654
+ interface GetUrlByExternalId {
655
+ externalId: string;
656
+ email?: never;
657
+ customerId?: never;
658
+ }
659
+ interface GetUrlByEmail {
660
+ email: string;
661
+ customerId?: never;
662
+ externalId?: never;
663
+ }
664
+ type GetUrlParams = GetUrlByCustomerId | GetUrlByExternalId | GetUrlByEmail;
665
+ /**
666
+ * Portal resource - Generate customer portal access
667
+ */
668
+ declare class PortalResource {
669
+ private httpClient;
670
+ constructor(httpClient: CommetHTTPClient);
671
+ /**
672
+ * Get a portal URL
673
+ *
674
+ * @example
675
+ * ```typescript
676
+ * const portal = await commet.portal.getUrl({ externalId: 'user_123' });
677
+ * ```
678
+ */
679
+ getUrl(params: GetUrlParams, options?: RequestOptions): Promise<ApiResponse<PortalAccess>>;
680
+ }
681
+
682
+ /**
683
+ * Customer-scoped API context
684
+ *
685
+ * Provides a cleaner API where you don't have to pass externalId
686
+ * on every call. All operations are scoped to a specific customer.
687
+ *
688
+ * @example
689
+ * ```typescript
690
+ * const customer = commet.customer("user_123");
691
+ *
692
+ * // All operations are now scoped to this customer
693
+ * const seats = await customer.features.get("team_members");
694
+ * await customer.seats.add("member");
695
+ * await customer.usage.track("api_call");
696
+ * ```
697
+ */
698
+ declare class CustomerContext {
699
+ private readonly externalId;
700
+ private readonly httpClient;
701
+ constructor(httpClient: CommetHTTPClient, externalId: string);
702
+ /**
703
+ * Feature access methods - check what the customer can use
704
+ */
705
+ features: {
706
+ /**
707
+ * Get detailed feature access/usage
708
+ */
709
+ get: (code: GeneratedFeatureCode, options?: RequestOptions) => Promise<ApiResponse<FeatureAccess>>;
710
+ /**
711
+ * Check if a boolean feature is enabled
712
+ */
713
+ check: (code: GeneratedFeatureCode, options?: RequestOptions) => Promise<ApiResponse<CheckResult>>;
714
+ /**
715
+ * Check if customer can use one more unit
716
+ */
717
+ canUse: (code: GeneratedFeatureCode, options?: RequestOptions) => Promise<ApiResponse<CanUseResult>>;
718
+ /**
719
+ * List all features
720
+ */
721
+ list: (options?: RequestOptions) => Promise<ApiResponse<FeatureAccess[]>>;
722
+ };
723
+ /**
724
+ * Seat management methods
725
+ */
726
+ seats: {
727
+ /**
728
+ * Add seats
729
+ */
730
+ add: (seatType: GeneratedSeatType, count?: number, options?: RequestOptions) => Promise<ApiResponse<SeatEvent>>;
731
+ /**
732
+ * Remove seats
733
+ */
734
+ remove: (seatType: GeneratedSeatType, count?: number, options?: RequestOptions) => Promise<ApiResponse<SeatEvent>>;
735
+ /**
736
+ * Set total seat count
737
+ */
738
+ set: (seatType: GeneratedSeatType, count: number, options?: RequestOptions) => Promise<ApiResponse<SeatEvent>>;
739
+ /**
740
+ * Get current seat balance
741
+ */
742
+ getBalance: (seatType: GeneratedSeatType, options?: RequestOptions) => Promise<ApiResponse<SeatBalance>>;
743
+ };
744
+ /**
745
+ * Usage tracking methods
746
+ */
747
+ usage: {
748
+ /**
749
+ * Track a usage event
750
+ */
751
+ track: (eventType: GeneratedEventType, properties?: Record<string, string>, options?: RequestOptions) => Promise<ApiResponse<UsageEvent>>;
752
+ };
753
+ /**
754
+ * Subscription methods
755
+ */
756
+ subscription: {
757
+ /**
758
+ * Get active subscription
759
+ */
760
+ get: (options?: RequestOptions) => Promise<ApiResponse<ActiveSubscription | null>>;
761
+ /**
762
+ * Cancel subscription
763
+ */
764
+ cancel: (params?: {
765
+ reason?: string;
766
+ immediate?: boolean;
767
+ }, options?: RequestOptions) => Promise<ApiResponse<Subscription>>;
768
+ };
769
+ /**
770
+ * Portal methods
771
+ */
772
+ portal: {
773
+ /**
774
+ * Get customer portal URL
775
+ */
776
+ getUrl: (options?: RequestOptions) => Promise<ApiResponse<PortalAccess>>;
777
+ };
778
+ }
779
+
780
+ interface Customer {
781
+ id: CustomerID;
782
+ organizationId: string;
783
+ externalId?: string;
784
+ legalName?: string;
785
+ displayName?: string;
786
+ domain?: string;
787
+ website?: string;
788
+ billingEmail: string;
789
+ timezone?: string;
790
+ language?: string;
791
+ industry?: string;
792
+ employeeCount?: string;
793
+ metadata?: Record<string, unknown>;
794
+ isActive: boolean;
637
795
  createdAt: string;
796
+ updatedAt: string;
638
797
  }
639
- interface BatchResult<T> {
640
- successful: T[];
798
+ interface CustomerAddress {
799
+ line1: string;
800
+ line2?: string;
801
+ city: string;
802
+ state?: string;
803
+ postalCode: string;
804
+ country: string;
805
+ }
806
+ interface CreateParams {
807
+ email: string;
808
+ externalId?: string;
809
+ legalName?: string;
810
+ displayName?: string;
811
+ domain?: string;
812
+ website?: string;
813
+ timezone?: string;
814
+ language?: string;
815
+ industry?: string;
816
+ metadata?: Record<string, unknown>;
817
+ address?: CustomerAddress;
818
+ }
819
+ interface UpdateParams {
820
+ externalId?: string;
821
+ email?: string;
822
+ legalName?: string;
823
+ displayName?: string;
824
+ domain?: string;
825
+ website?: string;
826
+ timezone?: string;
827
+ language?: string;
828
+ industry?: string;
829
+ metadata?: Record<string, unknown>;
830
+ }
831
+ interface ListCustomersParams extends ListParams {
832
+ externalId?: string;
833
+ isActive?: boolean;
834
+ search?: string;
835
+ }
836
+ interface BatchResult {
837
+ successful: Customer[];
641
838
  failed: Array<{
642
839
  index: number;
643
840
  error: string;
644
- data: TrackParams;
841
+ data: CreateParams;
645
842
  }>;
646
843
  }
647
- interface TrackParams {
648
- eventType: GeneratedEventType;
649
- customerId?: CustomerID;
650
- externalId?: string;
651
- idempotencyKey?: string;
652
- value?: number;
653
- timestamp?: string;
654
- properties?: Record<string, string>;
655
- }
656
844
  /**
657
- * Usage resource - Track consumption events for usage-based billing
845
+ * Customers resource - Manage your customers
658
846
  */
659
- declare class UsageResource {
847
+ declare class CustomersResource {
660
848
  private httpClient;
661
849
  constructor(httpClient: CommetHTTPClient);
662
850
  /**
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
- * ```
851
+ * Create a customer (idempotent with externalId)
674
852
  */
675
- track(params: TrackParams, options?: RequestOptions): Promise<ApiResponse<UsageEvent>>;
853
+ create(params: CreateParams, options?: RequestOptions): Promise<ApiResponse<Customer>>;
676
854
  /**
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
- * ```
855
+ * Create multiple customers in batch
688
856
  */
689
- trackBatch(params: {
690
- events: TrackParams[];
691
- }, options?: RequestOptions): Promise<ApiResponse<BatchResult<UsageEvent>>>;
857
+ createBatch(params: {
858
+ customers: CreateParams[];
859
+ }, options?: RequestOptions): Promise<ApiResponse<BatchResult>>;
860
+ /**
861
+ * Get a customer by ID
862
+ */
863
+ get(customerId: CustomerID): Promise<ApiResponse<Customer>>;
864
+ /**
865
+ * Update a customer
866
+ */
867
+ update(customerId: CustomerID, params: UpdateParams, options?: RequestOptions): Promise<ApiResponse<Customer>>;
868
+ /**
869
+ * List customers with optional filters
870
+ */
871
+ list(params?: ListCustomersParams): Promise<ApiResponse<Customer[]>>;
872
+ /**
873
+ * Archive a customer
874
+ */
875
+ archive(customerId: CustomerID, options?: RequestOptions): Promise<ApiResponse<Customer>>;
692
876
  }
693
877
 
694
878
  /**
@@ -802,8 +986,23 @@ declare class Commet {
802
986
  readonly seats: SeatsResource;
803
987
  readonly subscriptions: SubscriptionsResource;
804
988
  readonly portal: PortalResource;
989
+ readonly features: FeaturesResource;
805
990
  readonly webhooks: Webhooks;
806
991
  constructor(config: CommetConfig);
992
+ /**
993
+ * Create a customer-scoped context for cleaner API usage
994
+ *
995
+ * @example
996
+ * ```typescript
997
+ * const customer = commet.customer("user_123");
998
+ *
999
+ * // All operations are now scoped to this customer
1000
+ * const seats = await customer.features.get("team_members");
1001
+ * await customer.seats.add("member");
1002
+ * await customer.usage.track("api_call");
1003
+ * ```
1004
+ */
1005
+ customer(externalId: string): CustomerContext;
807
1006
  getEnvironment(): Environment;
808
1007
  isSandbox(): boolean;
809
1008
  isProduction(): boolean;
@@ -822,4 +1021,4 @@ declare function isProduction(environment: Environment): boolean;
822
1021
  * Commet SDK - Billing and usage tracking for SaaS
823
1022
  */
824
1023
 
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 };
1024
+ export { type ActiveSubscription, type AddParams as AddSeatsParams, type ApiResponse, type BillingInterval, type CanUseResult, type CancelParams, type ChangePlanParams, type CheckResult, Commet, CommetAPIError, type CommetConfig, CommetError, type CommetGeneratedTypes, CommetValidationError, type CreateParams as CreateCustomerParams, type CreateSubscriptionParams, type Currency, type Customer, type CustomerAddress, CustomerContext, type CustomerID, type BatchResult as CustomersBatchResult, type Environment, type EventID, type FeatureAccess, 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$1 as UsageBatchResult, type UsageEvent, type UsageEventProperty, type WebhookData, type WebhookEvent, type WebhookPayload, Webhooks, Commet as default, isProduction, isSandbox };