@stigg/typescript 0.1.0-beta.55 → 0.1.0-beta.57

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,
@@ -170,10 +170,9 @@ export class Customers extends APIResource {
   }
 
   /**
-   * Retrieves a customer's contracts, fetched live from the connected billing
-   * provider, each enriched with a preview of its upcoming (next) invoice when
-   * available. Returns an empty list when no billing provider is connected or the
-   * customer is not synced.
+   * Retrieves a customer's contracts. Each contract that has a billing contract is
+   * enriched with a preview of its upcoming (next) invoice when available. Returns
+   * an empty list when the customer has no contracts.
    */
   listContracts(
     id: string,
@@ -270,12 +269,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,44 +328,36 @@ 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 whose system holds the customer record
      */
-    vendorIdentifier:
-      | 'AUTH0'
-      | 'ZUORA'
-      | 'STRIPE'
-      | 'HUBSPOT'
-      | 'AWS_MARKETPLACE'
-      | 'SNOWFLAKE'
-      | 'SALESFORCE'
-      | 'BIG_QUERY'
-      | 'OPEN_FGA'
-      | 'APP_STORE'
-      | 'RECEIVED'
-      | 'PREQUEL'
-      | 'AIRWALLEX'
-      | 'STRIPE_INVOICING';
+    vendorIdentifier: 'STRIPE' | 'ZUORA' | 'HUBSPOT' | 'AWS_MARKETPLACE';
 
     /**
      * Price billing sync revision data containing billing ID, link URL, and price
@@ -616,7 +607,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 };
 
@@ -664,25 +659,29 @@ export namespace CustomerResponse {
       /**
        * The default payment method type
        */
-      type: 'CARD' | 'BANK' | 'CASH_APP';
+      type: 'CARD' | 'BANK' | 'CASH_APP' | 'PAYPAL' | null;
     }
 
     /**
-     * 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 +736,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 +976,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 +1205,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 };
 
@@ -1250,25 +1257,29 @@ export namespace CustomerListResponse {
     /**
      * The default payment method type
      */
-    type: 'CARD' | 'BANK' | 'CASH_APP';
+    type: 'CARD' | 'BANK' | 'CASH_APP' | 'PAYPAL' | null;
   }
 
   /**
-   * 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 +1334,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 +1574,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 +2001,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 +2288,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 +2679,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 +2718,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 +2791,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 +3031,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 +3204,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 +3245,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 +3511,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 };
 
@@ -3528,25 +3576,29 @@ export namespace CustomerProvisionParams {
     /**
      * The default payment method type
      */
-    type: 'CARD' | 'BANK' | 'CASH_APP';
+    type: 'CARD' | 'BANK' | 'CASH_APP' | 'PAYPAL' | null;
   }
 
   /**
-   * 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 +3653,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 +3893,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,37 +128,27 @@ 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 whose system holds the customer record
    */
-  vendorIdentifier:
-    | 'AUTH0'
-    | 'ZUORA'
-    | 'STRIPE'
-    | 'HUBSPOT'
-    | 'AWS_MARKETPLACE'
-    | 'SNOWFLAKE'
-    | 'SALESFORCE'
-    | 'BIG_QUERY'
-    | 'OPEN_FGA'
-    | 'APP_STORE'
-    | 'RECEIVED'
-    | 'PREQUEL'
-    | 'AIRWALLEX'
-    | 'STRIPE_INVOICING';
+  vendorIdentifier: 'STRIPE' | 'ZUORA' | 'HUBSPOT' | 'AWS_MARKETPLACE';
 
   /**
    * Price billing sync revision data containing billing ID, link URL, and price
@@ -246,7 +236,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;
 
@@ -269,22 +261,7 @@ export interface IntegrationListParams extends MyCursorIDPageParams {
    * Query param: Filter by vendor identifier. Supports comma-separated values for
    * multiple vendors (e.g., STRIPE,HUBSPOT)
    */
-  vendorIdentifier?: Array<
-    | 'AUTH0'
-    | 'ZUORA'
-    | 'STRIPE'
-    | 'HUBSPOT'
-    | 'AWS_MARKETPLACE'
-    | 'SNOWFLAKE'
-    | 'SALESFORCE'
-    | 'BIG_QUERY'
-    | 'OPEN_FGA'
-    | 'APP_STORE'
-    | 'RECEIVED'
-    | 'PREQUEL'
-    | 'AIRWALLEX'
-    | 'STRIPE_INVOICING'
-  >;
+  vendorIdentifier?: Array<'STRIPE' | 'ZUORA' | 'HUBSPOT' | 'AWS_MARKETPLACE'>;
 
   /**
    * Header param: Account ID — optional when authenticating with a user JWT (Bearer
@@ -302,33 +279,21 @@ 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 whose system holds the customer record
    */
-  vendorIdentifier:
-    | 'AUTH0'
-    | 'ZUORA'
-    | 'STRIPE'
-    | 'HUBSPOT'
-    | 'AWS_MARKETPLACE'
-    | 'SNOWFLAKE'
-    | 'SALESFORCE'
-    | 'BIG_QUERY'
-    | 'OPEN_FGA'
-    | 'APP_STORE'
-    | 'RECEIVED'
-    | 'PREQUEL'
-    | 'AIRWALLEX'
-    | 'STRIPE_INVOICING';
+  vendorIdentifier: 'STRIPE' | 'ZUORA' | 'HUBSPOT' | 'AWS_MARKETPLACE';
 
   /**
    * Header param: Account ID — optional when authenticating with a user JWT (Bearer

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 {
     /**