@stigg/typescript 0.1.0-beta.54 → 0.1.0-beta.56

package/src/resources/v1/customers/customers.ts

@@ -124,12 +124,12 @@ export class Customers extends APIResource {
   /**
    * Checks a single entitlement (feature or credit) for a customer or resource.
    * Supports `requestedUsage` and `requestedValues` to evaluate against limits or
-   * enum values.
-   *
-   * **Warning:** This REST API endpoint lacks built-in client-side caching, fallback
-   * mechanisms, and low-latency guarantees. It is not recommended for hot-path
-   * entitlement checks. For production use, consider using the Stigg Node Server SDK
-   * with caching or the Sidecar for low-latency cached responses.
+   * enum values. Each call reaches the Stigg API directly, so latency reflects a
+   * network round trip. For entitlement checks on a hot path (e.g. gating a request
+   * in real time), the Stigg Node Server SDK (with its built-in cache) or the
+   * Sidecar will typically respond faster and keep working through brief Stigg
+   * outages; reach for this endpoint when a live HTTP call is the natural fit, such
+   * as from a non-Node backend or a server-side job.
    */
   checkEntitlement(
     id: string,
@@ -270,12 +270,12 @@ export class Customers extends APIResource {
 
   /**
    * Retrieves the effective entitlements for a customer or resource, including
-   * feature and credit entitlements.
-   *
-   * **Warning:** This REST API endpoint lacks built-in client-side caching, fallback
-   * mechanisms, and low-latency guarantees. It is not recommended for hot-path
-   * entitlement checks. For production use, consider using the Stigg Node Server SDK
-   * with caching or the Sidecar for low-latency cached responses.
+   * feature and credit entitlements. Each call reaches the Stigg API directly, so
+   * latency reflects a network round trip. For entitlement checks on a hot path
+   * (e.g. gating a request in real time), the Stigg Node Server SDK (with its
+   * built-in cache) or the Sidecar will typically respond faster and keep working
+   * through brief Stigg outages; reach for this endpoint when a live HTTP call is
+   * the natural fit, such as from a non-Node backend or a server-side job.
    */
   retrieveEntitlements(
     id: string,
@@ -329,28 +329,34 @@ export type CustomerListResourcesResponsesMyCursorIDPage = MyCursorIDPage<Custom
  */
 export interface CustomerIntegrationResponse {
   /**
-   * External billing or CRM integration link
+   * Links this customer to their record in a specific configured integration (e.g.
+   * their Stripe customer ID under your Stripe integration). A customer has at most
+   * one link per integration.
    */
   data: CustomerIntegrationResponse.Data;
 }
 
 export namespace CustomerIntegrationResponse {
   /**
-   * External billing or CRM integration link
+   * Links this customer to their record in a specific configured integration (e.g.
+   * their Stripe customer ID under your Stripe integration). A customer has at most
+   * one link per integration.
    */
   export interface Data {
     /**
-     * Integration details
+     * The internal ID of the integration this record is linked to
      */
     id: string;
 
     /**
-     * Synced entity id
+     * The external entity ID this record is linked to in the vendor system (e.g. the
+     * Stripe customer ID). Null until the link has synced; required when creating the
+     * link.
      */
     syncedEntityId: string | null;
 
     /**
-     * The vendor identifier of integration
+     * The vendor identifier of the integration (e.g. STRIPE, SALESFORCE, SNOWFLAKE)
      */
     vendorIdentifier:
       | 'AUTH0'
@@ -616,7 +622,11 @@ export namespace CustomerResponse {
     language?: string | null;
 
     /**
-     * Additional metadata
+     * Custom key-value metadata to attach to the customer. When creating a customer,
+     * this sets the initial metadata. When updating a customer, this replaces the
+     * customer's existing metadata object entirely — it is not merged key by key. Omit
+     * this field on update to leave the customer's existing metadata untouched; pass
+     * an empty object to clear it.
      */
     metadata?: { [key: string]: string };
 
@@ -668,21 +678,25 @@ export namespace CustomerResponse {
     }
 
     /**
-     * External billing or CRM integration link
+     * Links this customer to their record in a specific configured integration (e.g.
+     * their Stripe customer ID under your Stripe integration). A customer has at most
+     * one link per integration.
      */
     export interface Integration {
       /**
-       * Integration details
+       * The internal ID of the integration this record is linked to
        */
       id: string;
 
       /**
-       * Synced entity id
+       * The external entity ID this record is linked to in the vendor system (e.g. the
+       * Stripe customer ID). Null until the link has synced; required when creating the
+       * link.
        */
       syncedEntityId: string | null;
 
       /**
-       * The vendor identifier of integration
+       * The vendor identifier of the integration (e.g. STRIPE, SALESFORCE, SNOWFLAKE)
        */
       vendorIdentifier:
         | 'AUTH0'
@@ -737,7 +751,9 @@ export namespace CustomerResponse {
         invoiceCustomFields?: { [key: string]: string };
 
         /**
-         * Additional metadata
+         * Additional metadata to pass through to the billing provider on the customer's
+         * record there. This is separate from the customer's own metadata field — it's
+         * stored only on the billing-provider side, not on the Stigg customer object.
          */
         metadata?: { [key: string]: string };
 
@@ -975,7 +991,9 @@ export namespace CustomerResponse {
           | 'xpf';
 
         /**
-         * Additional metadata
+         * Additional metadata to pass through to the billing provider on the customer's
+         * record there. This is separate from the customer's own metadata field — it's
+         * stored only on the billing-provider side, not on the Stigg customer object.
          */
         metadata?: { [key: string]: string };
 
@@ -1202,7 +1220,11 @@ export interface CustomerListResponse {
   language?: string | null;
 
   /**
-   * Additional metadata
+   * Custom key-value metadata to attach to the customer. When creating a customer,
+   * this sets the initial metadata. When updating a customer, this replaces the
+   * customer's existing metadata object entirely — it is not merged key by key. Omit
+   * this field on update to leave the customer's existing metadata untouched; pass
+   * an empty object to clear it.
    */
   metadata?: { [key: string]: string };
 
@@ -1254,21 +1276,25 @@ export namespace CustomerListResponse {
   }
 
   /**
-   * External billing or CRM integration link
+   * Links this customer to their record in a specific configured integration (e.g.
+   * their Stripe customer ID under your Stripe integration). A customer has at most
+   * one link per integration.
    */
   export interface Integration {
     /**
-     * Integration details
+     * The internal ID of the integration this record is linked to
      */
     id: string;
 
     /**
-     * Synced entity id
+     * The external entity ID this record is linked to in the vendor system (e.g. the
+     * Stripe customer ID). Null until the link has synced; required when creating the
+     * link.
      */
     syncedEntityId: string | null;
 
     /**
-     * The vendor identifier of integration
+     * The vendor identifier of the integration (e.g. STRIPE, SALESFORCE, SNOWFLAKE)
      */
     vendorIdentifier:
       | 'AUTH0'
@@ -1323,7 +1349,9 @@ export namespace CustomerListResponse {
       invoiceCustomFields?: { [key: string]: string };
 
       /**
-       * Additional metadata
+       * Additional metadata to pass through to the billing provider on the customer's
+       * record there. This is separate from the customer's own metadata field — it's
+       * stored only on the billing-provider side, not on the Stigg customer object.
        */
       metadata?: { [key: string]: string };
 
@@ -1561,7 +1589,9 @@ export namespace CustomerListResponse {
         | 'xpf';
 
       /**
-       * Additional metadata
+       * Additional metadata to pass through to the billing provider on the customer's
+       * record there. This is separate from the customer's own metadata field — it's
+       * stored only on the billing-provider side, not on the Stigg customer object.
        */
       metadata?: { [key: string]: string };
 
@@ -1986,6 +2016,11 @@ export namespace CustomerListContractsResponse {
        */
       dueDate: string | null;
 
+      /**
+       * The billing provider ID of the draft invoice this preview describes
+       */
+      invoiceId: string | null;
+
       /**
        * The end of the billing period the upcoming invoice covers
        */
@@ -2268,7 +2303,12 @@ export namespace CustomerListInvoicesResponse {
 }
 
 /**
- * Resource object that belongs to a customer
+ * Resource object that belongs to a customer, used to scope subscriptions and
+ * entitlements to a specific instance within the customer's account (e.g. a
+ * website, project, or workspace) for multi-resource pricing. A resource is
+ * identified only by its resourceId — there's no separate display name or metadata
+ * field on the resource itself; if you need to attach descriptive data, keep it in
+ * your own system keyed by resourceId.
  */
 export interface CustomerListResourcesResponse {
   /**
@@ -2654,7 +2694,11 @@ export interface CustomerUpdateParams {
   language?: string | null;
 
   /**
-   * Body param: Additional metadata
+   * Body param: Custom key-value metadata to attach to the customer. When creating a
+   * customer, this sets the initial metadata. When updating a customer, this
+   * replaces the customer's existing metadata object entirely — it is not merged key
+   * by key. Omit this field on update to leave the customer's existing metadata
+   * untouched; pass an empty object to clear it.
    */
   metadata?: { [key: string]: string };
 
@@ -2689,21 +2733,25 @@ export interface CustomerUpdateParams {
 
 export namespace CustomerUpdateParams {
   /**
-   * External billing or CRM integration link
+   * Links this customer to their record in a specific configured integration (e.g.
+   * their Stripe customer ID under your Stripe integration). A customer has at most
+   * one link per integration.
    */
   export interface Integration {
     /**
-     * Integration details
+     * The internal ID of the integration this record is linked to
      */
     id: string;
 
     /**
-     * Synced entity id
+     * The external entity ID this record is linked to in the vendor system (e.g. the
+     * Stripe customer ID). Null until the link has synced; required when creating the
+     * link.
      */
     syncedEntityId: string | null;
 
     /**
-     * The vendor identifier of integration
+     * The vendor identifier of the integration (e.g. STRIPE, SALESFORCE, SNOWFLAKE)
      */
     vendorIdentifier:
       | 'AUTH0'
@@ -2758,7 +2806,9 @@ export namespace CustomerUpdateParams {
       invoiceCustomFields?: { [key: string]: string };
 
       /**
-       * Additional metadata
+       * Additional metadata to pass through to the billing provider on the customer's
+       * record there. This is separate from the customer's own metadata field — it's
+       * stored only on the billing-provider side, not on the Stigg customer object.
        */
       metadata?: { [key: string]: string };
 
@@ -2996,7 +3046,9 @@ export namespace CustomerUpdateParams {
         | 'xpf';
 
       /**
-       * Additional metadata
+       * Additional metadata to pass through to the billing provider on the customer's
+       * record there. This is separate from the customer's own metadata field — it's
+       * stored only on the billing-provider side, not on the Stigg customer object.
        */
       metadata?: { [key: string]: string };
 
@@ -3167,7 +3219,7 @@ export interface CustomerImportParams {
   customers: Array<CustomerImportParams.Customer>;
 
   /**
-   * Body param: Integration details
+   * Body param: The internal ID of the integration this record is linked to
    */
   integrationId?: string;
 
@@ -3208,12 +3260,19 @@ export namespace CustomerImportParams {
     billingId?: string;
 
     /**
-     * Additional metadata
+     * Custom key-value metadata to attach to the customer. When creating a customer,
+     * this sets the initial metadata. When updating a customer, this replaces the
+     * customer's existing metadata object entirely — it is not merged key by key. Omit
+     * this field on update to leave the customer's existing metadata untouched; pass
+     * an empty object to clear it.
      */
     metadata?: { [key: string]: string };
 
     /**
-     * Billing provider payment method id
+     * Billing provider payment method id. Attaching it makes it the customer's new
+     * default payment method for future charges; any previously attached payment
+     * method is no longer used as the default, though it is not removed from the
+     * billing provider.
      */
     paymentMethodId?: string;
 
@@ -3467,7 +3526,11 @@ export interface CustomerProvisionParams {
   language?: string | null;
 
   /**
-   * Body param: Additional metadata
+   * Body param: Custom key-value metadata to attach to the customer. When creating a
+   * customer, this sets the initial metadata. When updating a customer, this
+   * replaces the customer's existing metadata object entirely — it is not merged key
+   * by key. Omit this field on update to leave the customer's existing metadata
+   * untouched; pass an empty object to clear it.
    */
   metadata?: { [key: string]: string };
 
@@ -3532,21 +3595,25 @@ export namespace CustomerProvisionParams {
   }
 
   /**
-   * External billing or CRM integration link
+   * Links this customer to their record in a specific configured integration (e.g.
+   * their Stripe customer ID under your Stripe integration). A customer has at most
+   * one link per integration.
    */
   export interface Integration {
     /**
-     * Integration details
+     * The internal ID of the integration this record is linked to
      */
     id: string;
 
     /**
-     * Synced entity id
+     * The external entity ID this record is linked to in the vendor system (e.g. the
+     * Stripe customer ID). Null until the link has synced; required when creating the
+     * link.
      */
     syncedEntityId: string | null;
 
     /**
-     * The vendor identifier of integration
+     * The vendor identifier of the integration (e.g. STRIPE, SALESFORCE, SNOWFLAKE)
      */
     vendorIdentifier:
       | 'AUTH0'
@@ -3601,7 +3668,9 @@ export namespace CustomerProvisionParams {
       invoiceCustomFields?: { [key: string]: string };
 
       /**
-       * Additional metadata
+       * Additional metadata to pass through to the billing provider on the customer's
+       * record there. This is separate from the customer's own metadata field — it's
+       * stored only on the billing-provider side, not on the Stigg customer object.
        */
       metadata?: { [key: string]: string };
 
@@ -3839,7 +3908,9 @@ export namespace CustomerProvisionParams {
         | 'xpf';
 
       /**
-       * Additional metadata
+       * Additional metadata to pass through to the billing provider on the customer's
+       * record there. This is separate from the customer's own metadata field — it's
+       * stored only on the billing-provider side, not on the Stigg customer object.
        */
       metadata?: { [key: string]: string };
 

package/src/resources/v1/customers/integrations.ts

@@ -128,21 +128,25 @@ export class Integrations extends APIResource {
 export type IntegrationListResponsesMyCursorIDPage = MyCursorIDPage<IntegrationListResponse>;
 
 /**
- * External billing or CRM integration link
+ * Links this customer to their record in a specific configured integration (e.g.
+ * their Stripe customer ID under your Stripe integration). A customer has at most
+ * one link per integration.
  */
 export interface IntegrationListResponse {
   /**
-   * Integration details
+   * The internal ID of the integration this record is linked to
    */
   id: string;
 
   /**
-   * Synced entity id
+   * The external entity ID this record is linked to in the vendor system (e.g. the
+   * Stripe customer ID). Null until the link has synced; required when creating the
+   * link.
    */
   syncedEntityId: string | null;
 
   /**
-   * The vendor identifier of integration
+   * The vendor identifier of the integration (e.g. STRIPE, SALESFORCE, SNOWFLAKE)
    */
   vendorIdentifier:
     | 'AUTH0'
@@ -246,7 +250,9 @@ export interface IntegrationUpdateParams {
   id: string;
 
   /**
-   * Body param: Synced entity id
+   * Body param: The external entity ID this record is linked to in the vendor system
+   * (e.g. the Stripe customer ID). Null until the link has synced; required when
+   * creating the link.
    */
   syncedEntityId: string | null;
 
@@ -302,17 +308,20 @@ export interface IntegrationListParams extends MyCursorIDPageParams {
 
 export interface IntegrationLinkParams {
   /**
-   * Body param: Integration details
+   * Body param: The internal ID of the integration this record is linked to
    */
   id: string;
 
   /**
-   * Body param: Synced entity id
+   * Body param: The external entity ID this record is linked to in the vendor system
+   * (e.g. the Stripe customer ID). Null until the link has synced; required when
+   * creating the link.
    */
   syncedEntityId: string;
 
   /**
-   * Body param: The vendor identifier of integration
+   * Body param: The vendor identifier of the integration (e.g. STRIPE, SALESFORCE,
+   * SNOWFLAKE)
    */
   vendorIdentifier:
     | 'AUTH0'

package/src/resources/v1/customers/payment-method.ts

@@ -59,17 +59,21 @@ export class PaymentMethod extends APIResource {
 
 export interface PaymentMethodAttachParams {
   /**
-   * Body param: Integration details
+   * Body param: The internal ID of the integration this record is linked to
    */
   integrationId: string;
 
   /**
-   * Body param: Billing provider payment method id
+   * Body param: Billing provider payment method id. Attaching it makes it the
+   * customer's new default payment method for future charges; any previously
+   * attached payment method is no longer used as the default, though it is not
+   * removed from the billing provider.
    */
   paymentMethodId: string;
 
   /**
-   * Body param: The vendor identifier of integration
+   * Body param: The vendor identifier of the integration (e.g. STRIPE, SALESFORCE,
+   * SNOWFLAKE)
    */
   vendorIdentifier:
     | 'AUTH0'

package/src/resources/v1/customers/promotional-entitlements.ts

@@ -95,7 +95,11 @@ export interface PromotionalEntitlementCreateResponse {
 
 export namespace PromotionalEntitlementCreateResponse {
   /**
-   * Granted feature entitlement
+   * A feature entitlement granted to a customer outside of their subscription plan.
+   * Promotional entitlements are applied on top of whatever the subscription already
+   * grants and are not removed when a plan or subscription changes; once past their
+   * end date they keep appearing in the customer's entitlement list with an Expired
+   * status rather than disappearing.
    */
   export interface Data {
     /**
@@ -235,7 +239,11 @@ export namespace PromotionalEntitlementCreateResponse {
 }
 
 /**
- * Granted feature entitlement
+ * A feature entitlement granted to a customer outside of their subscription plan.
+ * Promotional entitlements are applied on top of whatever the subscription already
+ * grants and are not removed when a plan or subscription changes; once past their
+ * end date they keep appearing in the customer's entitlement list with an Expired
+ * status rather than disappearing.
  */
 export interface PromotionalEntitlementListResponse {
   /**
@@ -378,14 +386,22 @@ export namespace PromotionalEntitlementListResponse {
  */
 export interface PromotionalEntitlementRevokeResponse {
   /**
-   * Granted feature entitlement
+   * A feature entitlement granted to a customer outside of their subscription plan.
+   * Promotional entitlements are applied on top of whatever the subscription already
+   * grants and are not removed when a plan or subscription changes; once past their
+   * end date they keep appearing in the customer's entitlement list with an Expired
+   * status rather than disappearing.
    */
   data: PromotionalEntitlementRevokeResponse.Data;
 }
 
 export namespace PromotionalEntitlementRevokeResponse {
   /**
-   * Granted feature entitlement
+   * A feature entitlement granted to a customer outside of their subscription plan.
+   * Promotional entitlements are applied on top of whatever the subscription already
+   * grants and are not removed when a plan or subscription changes; once past their
+   * end date they keep appearing in the customer's entitlement list with an Expired
+   * status rather than disappearing.
    */
   export interface Data {
     /**
@@ -546,7 +562,9 @@ export interface PromotionalEntitlementCreateParams {
 
 export namespace PromotionalEntitlementCreateParams {
   /**
-   * Single entitlement grant config
+   * Single entitlement grant config. Granting again for the same customer and
+   * feature replaces the existing promotional entitlement for that feature rather
+   * than stacking a second one.
    */
   export interface PromotionalEntitlement {
     /**

package/src/resources/v1/events/events.ts

@@ -45,8 +45,8 @@ export class Events extends APIResource {
   }
 
   /**
-   * Reports raw usage events for event-based metering. Events are ingested
-   * asynchronously and aggregated into usage totals.
+   * Reports raw usage events for event-based metering. Events are validated and
+   * stored synchronously, then aggregated into usage totals asynchronously.
    */
   report(params: EventReportParams, options?: RequestOptions): APIPromise<EventReportResponse> {
     const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
@@ -172,7 +172,10 @@ export interface EventEstimateParams {
   dimensions?: { [key: string]: string | number | boolean };
 
   /**
-   * Body param: Resource id
+   * Body param: The customer resource this usage applies to. Optional — only
+   * required if the customer has multiple resources (for example, one subscription
+   * per workspace or site) and usage needs to be tracked separately per resource;
+   * omit it to report usage at the customer level.
    */
   resourceId?: string | null;
 
@@ -226,7 +229,9 @@ export namespace EventReportParams {
     eventName: string;
 
     /**
-     * Idempotency key
+     * A key you provide to safely retry the same usage report without double-counting
+     * it. Reports with a previously-seen idempotency key are deduplicated for 7 days;
+     * after that window a retry is treated as new usage.
      */
     idempotencyKey: string;
 
@@ -236,7 +241,10 @@ export namespace EventReportParams {
     dimensions?: { [key: string]: string | number | boolean };
 
     /**
-     * Resource id
+     * The customer resource this usage applies to. Optional — only required if the
+     * customer has multiple resources (for example, one subscription per workspace or
+     * site) and usage needs to be tracked separately per resource; omit it to report
+     * usage at the customer level.
      */
     resourceId?: string | null;