@stigg/typescript 0.1.0-alpha.4 → 0.1.0-alpha.8

package/src/resources/v1/subscriptions/future-update.ts

@@ -7,14 +7,15 @@ import { path } from '../../../internal/utils/path';
 
 export class FutureUpdate extends APIResource {
   /**
-   * Cancel pending payment update
+   * Cancels a subscription update that is pending payment completion.
    */
   cancelPendingPayment(id: string, options?: RequestOptions): APIPromise<CancelSubscription> {
     return this._client.delete(path`/api/v1/subscriptions/${id}/future-update/pending-payment`, options);
   }
 
   /**
-   * Cancel scheduled update
+   * Cancels a scheduled subscription update, such as a future downgrade or plan
+   * change.
    */
   cancelSchedule(id: string, options?: RequestOptions): APIPromise<CancelSubscription> {
     return this._client.delete(path`/api/v1/subscriptions/${id}/future-update/schedule`, options);

package/src/resources/v1/subscriptions/index.ts

@@ -1,6 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 export { FutureUpdate, type CancelSubscription } from './future-update';
+export { Invoice, type InvoiceMarkAsPaidResponse } from './invoice';
 export {
   Subscriptions,
   type Subscription,
@@ -19,3 +20,9 @@ export {
   type SubscriptionTransferParams,
   type SubscriptionListResponsesMyCursorIDPage,
 } from './subscriptions';
+export {
+  Usage,
+  type UsageChargeUsageResponse,
+  type UsageSyncResponse,
+  type UsageChargeUsageParams,
+} from './usage';

package/src/resources/v1/subscriptions/invoice.ts

@@ -0,0 +1,42 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+export class Invoice extends APIResource {
+  /**
+   * Marks the latest invoice of a subscription as paid in the billing provider. The
+   * invoice must exist and have an OPEN status.
+   */
+  markAsPaid(id: string, options?: RequestOptions): APIPromise<InvoiceMarkAsPaidResponse> {
+    return this._client.post(path`/api/v1/subscriptions/${id}/invoice/paid`, options);
+  }
+}
+
+/**
+ * Response object
+ */
+export interface InvoiceMarkAsPaidResponse {
+  /**
+   * Result of marking a subscription invoice as paid.
+   */
+  data: InvoiceMarkAsPaidResponse.Data;
+}
+
+export namespace InvoiceMarkAsPaidResponse {
+  /**
+   * Result of marking a subscription invoice as paid.
+   */
+  export interface Data {
+    /**
+     * The subscription ID whose invoice was marked as paid
+     */
+    id: string;
+  }
+}
+
+export declare namespace Invoice {
+  export { type InvoiceMarkAsPaidResponse as InvoiceMarkAsPaidResponse };
+}

package/src/resources/v1/subscriptions/subscriptions.ts

@@ -3,6 +3,10 @@
 import { APIResource } from '../../../core/resource';
 import * as FutureUpdateAPI from './future-update';
 import { CancelSubscription, FutureUpdate } from './future-update';
+import * as InvoiceAPI from './invoice';
+import { Invoice, InvoiceMarkAsPaidResponse } from './invoice';
+import * as UsageAPI from './usage';
+import { Usage, UsageChargeUsageParams, UsageChargeUsageResponse, UsageSyncResponse } from './usage';
 import { APIPromise } from '../../../core/api-promise';
 import { MyCursorIDPage, type MyCursorIDPageParams, PagePromise } from '../../../core/pagination';
 import { RequestOptions } from '../../../internal/request-options';
@@ -10,23 +14,28 @@ import { path } from '../../../internal/utils/path';
 
 export class Subscriptions extends APIResource {
   futureUpdate: FutureUpdateAPI.FutureUpdate = new FutureUpdateAPI.FutureUpdate(this._client);
+  usage: UsageAPI.Usage = new UsageAPI.Usage(this._client);
+  invoice: InvoiceAPI.Invoice = new InvoiceAPI.Invoice(this._client);
 
   /**
-   * Get a single subscription by ID
+   * Retrieves a subscription by its unique identifier, including plan details,
+   * billing period, status, and add-ons.
    */
   retrieve(id: string, options?: RequestOptions): APIPromise<Subscription> {
     return this._client.get(path`/api/v1/subscriptions/${id}`, options);
   }
 
   /**
-   * Update a subscription
+   * Updates an active subscription's properties including billing period, add-ons,
+   * unit quantities, and discounts.
    */
   update(id: string, body: SubscriptionUpdateParams, options?: RequestOptions): APIPromise<Subscription> {
     return this._client.patch(path`/api/v1/subscriptions/${id}`, { body, ...options });
   }
 
   /**
-   * Get a list of subscriptions
+   * Retrieves a paginated list of subscriptions, with optional filters for customer,
+   * status, and plan.
    */
   list(
     query: SubscriptionListParams | null | undefined = {},
@@ -39,35 +48,40 @@ export class Subscriptions extends APIResource {
   }
 
   /**
-   * Cancel subscription
+   * Cancels an active subscription, either immediately or at a specified time such
+   * as end of billing period.
    */
   cancel(id: string, body: SubscriptionCancelParams, options?: RequestOptions): APIPromise<Subscription> {
     return this._client.post(path`/api/v1/subscriptions/${id}/cancel`, { body, ...options });
   }
 
   /**
-   * Delegate subscription payment to customer
+   * Delegates the payment responsibility of a subscription to a different customer.
+   * The delegated customer will be billed for this subscription.
    */
   delegate(id: string, body: SubscriptionDelegateParams, options?: RequestOptions): APIPromise<Subscription> {
     return this._client.post(path`/api/v1/subscriptions/${id}/delegate`, { body, ...options });
   }
 
   /**
-   * Bulk import subscriptions
+   * Imports multiple subscriptions in bulk. Used for migrating subscription data
+   * from external systems.
    */
   import(body: SubscriptionImportParams, options?: RequestOptions): APIPromise<SubscriptionImportResponse> {
     return this._client.post('/api/v1/subscriptions/import', { body, ...options });
   }
 
   /**
-   * Migrate subscription to latest plan version
+   * Migrates a subscription to the latest published version of its plan or add-ons.
+   * Handles prorated charges or credits automatically.
    */
   migrate(id: string, body: SubscriptionMigrateParams, options?: RequestOptions): APIPromise<Subscription> {
     return this._client.post(path`/api/v1/subscriptions/${id}/migrate`, { body, ...options });
   }
 
   /**
-   * Preview subscription
+   * Previews the pricing impact of creating or updating a subscription without
+   * making changes. Returns estimated costs, taxes, and proration details.
    */
   preview(
     body: SubscriptionPreviewParams,
@@ -77,7 +91,8 @@ export class Subscriptions extends APIResource {
   }
 
   /**
-   * Provision subscription
+   * Creates a new subscription for an existing customer. When payment is required
+   * and no payment method exists, returns a checkout URL.
    */
   provision(
     body: SubscriptionProvisionParams,
@@ -87,7 +102,8 @@ export class Subscriptions extends APIResource {
   }
 
   /**
-   * Transfer subscription to resource
+   * Transfers a subscription to a different resource ID. Used for multi-resource
+   * products where subscriptions apply to specific entities like websites or apps.
    */
   transfer(id: string, body: SubscriptionTransferParams, options?: RequestOptions): APIPromise<Subscription> {
     return this._client.post(path`/api/v1/subscriptions/${id}/transfer`, { body, ...options });
@@ -777,80 +793,184 @@ export namespace SubscriptionProvisionResponse {
      */
     id: string;
 
-    entitlements: Array<Data.Entitlement>;
+    entitlements: Array<Data.UnionObjectVariant0 | Data.UnionObjectVariant1> | null;
 
     /**
      * Provision status: SUCCESS or PAYMENT_REQUIRED
      */
     status: 'SUCCESS' | 'PAYMENT_REQUIRED';
 
+    /**
+     * Created subscription (when status is SUCCESS)
+     */
+    subscription: Data.Subscription | null;
+
     /**
      * Checkout billing ID when payment is required
      */
-    checkoutBillingId?: string | null;
+    checkoutBillingId?: string;
 
     /**
      * URL to complete payment when PAYMENT_REQUIRED
      */
-    checkoutUrl?: string | null;
+    checkoutUrl?: string;
 
     /**
      * Whether the subscription is scheduled for future activation
      */
     isScheduled?: boolean;
-
-    /**
-     * Created subscription (when status is SUCCESS)
-     */
-    subscription?: Data.Subscription;
   }
 
   export namespace Data {
-    export interface Entitlement {
-      accessDeniedReason?: string | null;
+    export interface UnionObjectVariant0 {
+      accessDeniedReason:
+        | 'FeatureNotFound'
+        | 'CustomerNotFound'
+        | 'CustomerIsArchived'
+        | 'CustomerResourceNotFound'
+        | 'NoActiveSubscription'
+        | 'NoFeatureEntitlementInSubscription'
+        | 'RequestedUsageExceedingLimit'
+        | 'RequestedValuesMismatch'
+        | 'BudgetExceeded'
+        | 'Unknown'
+        | 'FeatureTypeMismatch'
+        | 'Revoked'
+        | 'InsufficientCredits'
+        | 'EntitlementNotFound'
+        | null;
+
+      isGranted: boolean;
+
+      type: 'FEATURE';
 
       currentUsage?: number;
 
       /**
-       * entitlement updated at
+       * Timestamp of the last update to the entitlement grant or configuration.
        */
-      entitlementUpdatedAt?: string | null;
-
-      feature?: Entitlement.Feature | null;
+      entitlementUpdatedAt?: string;
 
-      hasUnlimitedUsage?: boolean | null;
+      feature?: UnionObjectVariant0.Feature;
 
-      isGranted?: boolean;
+      hasUnlimitedUsage?: boolean;
 
       resetPeriod?: 'YEAR' | 'MONTH' | 'WEEK' | 'DAY' | 'HOUR' | null;
 
       usageLimit?: number | null;
 
       /**
-       * usage period anchor
+       * The anchor for calculating the usage period for metered entitlements with a
+       * reset period configured
+       */
+      usagePeriodAnchor?: string;
+
+      /**
+       * The end date of the usage period for metered entitlements with a reset period
+       * configured
        */
-      usagePeriodAnchor?: string | null;
+      usagePeriodEnd?: string;
 
       /**
-       * usage period end
+       * The start date of the usage period for metered entitlements with a reset period
+       * configured
        */
-      usagePeriodEnd?: string | null;
+      usagePeriodStart?: string;
 
       /**
-       * usage period start
+       * The next time the entitlement should be recalculated
        */
-      usagePeriodStart?: string | null;
+      validUntil?: string;
     }
 
-    export namespace Entitlement {
+    export namespace UnionObjectVariant0 {
       export interface Feature {
         /**
-         * Feature ID
+         * The human-readable name of the entitlement, shown in UI elements.
+         */
+        displayName: string;
+
+        /**
+         * The current status of the feature.
+         */
+        featureStatus: 'NEW' | 'SUSPENDED' | 'ACTIVE';
+
+        /**
+         * The type of feature associated with the entitlement.
+         */
+        featureType: 'BOOLEAN' | 'NUMBER' | 'ENUM';
+
+        /**
+         * The unique reference ID of the entitlement.
          */
         refId: string;
       }
     }
 
+    export interface UnionObjectVariant1 {
+      accessDeniedReason:
+        | 'FeatureNotFound'
+        | 'CustomerNotFound'
+        | 'CustomerIsArchived'
+        | 'CustomerResourceNotFound'
+        | 'NoActiveSubscription'
+        | 'NoFeatureEntitlementInSubscription'
+        | 'RequestedUsageExceedingLimit'
+        | 'RequestedValuesMismatch'
+        | 'BudgetExceeded'
+        | 'Unknown'
+        | 'FeatureTypeMismatch'
+        | 'Revoked'
+        | 'InsufficientCredits'
+        | 'EntitlementNotFound'
+        | null;
+
+      /**
+       * The currency associated with a credit entitlement.
+       */
+      currency: UnionObjectVariant1.Currency;
+
+      currentUsage: number;
+
+      isGranted: boolean;
+
+      type: 'CREDIT';
+
+      usageLimit: number;
+
+      /**
+       * Timestamp of the last update to the credit usage.
+       */
+      usageUpdatedAt: string;
+
+      /**
+       * Timestamp of the last update to the entitlement grant or configuration.
+       */
+      entitlementUpdatedAt?: string;
+
+      /**
+       * The end date of the current billing period for recurring credit grants.
+       */
+      usagePeriodEnd?: string;
+
+      /**
+       * The next time the entitlement should be recalculated
+       */
+      validUntil?: string;
+    }
+
+    export namespace UnionObjectVariant1 {
+      /**
+       * The currency associated with a credit entitlement.
+       */
+      export interface Currency {
+        /**
+         * The unique identifier of the custom currency.
+         */
+        currencyId: string;
+      }
+    }
+
     /**
      * Created subscription (when status is SUCCESS)
      */
@@ -1859,10 +1979,25 @@ export namespace SubscriptionUpdateParams {
   }
 
   export interface PriceOverride {
+    /**
+     * Addon ID
+     */
+    addonId?: string;
+
+    /**
+     * Whether this is a base charge override
+     */
+    baseCharge?: boolean;
+
+    /**
+     * The corresponding custom currency id of the recurring credits price
+     */
+    currencyId?: string;
+
     /**
      * Feature ID
      */
-    featureId: string;
+    featureId?: string;
 
     price?: PriceOverride.Price;
   }
@@ -2035,17 +2170,65 @@ export namespace SubscriptionUpdateParams {
 }
 
 export interface SubscriptionListParams extends MyCursorIDPageParams {
+  /**
+   * Filter by creation date using range operators: gt, gte, lt, lte
+   */
+  createdAt?: SubscriptionListParams.CreatedAt;
+
   /**
    * Filter by customer ID
    */
   customerId?: string;
 
   /**
-   * Filter by status (comma-separated)
+   * Filter by plan ID
+   */
+  planId?: string;
+
+  /**
+   * Filter by pricing type. Supports comma-separated values for multiple types
+   */
+  pricingType?: string;
+
+  /**
+   * Filter by resource ID
+   */
+  resourceId?: string;
+
+  /**
+   * Filter by subscription status. Supports comma-separated values for multiple
+   * statuses
    */
   status?: string;
 }
 
+export namespace SubscriptionListParams {
+  /**
+   * Filter by creation date using range operators: gt, gte, lt, lte
+   */
+  export interface CreatedAt {
+    /**
+     * Greater than the specified createdAt value
+     */
+    gt?: string;
+
+    /**
+     * Greater than or equal to the specified createdAt value
+     */
+    gte?: string;
+
+    /**
+     * Less than the specified createdAt value
+     */
+    lt?: string;
+
+    /**
+     * Less than or equal to the specified createdAt value
+     */
+    lte?: string;
+  }
+}
+
 export interface SubscriptionCancelParams {
   /**
    * Action on cancellation (downgrade or revoke)
@@ -2082,6 +2265,11 @@ export interface SubscriptionImportParams {
    * List of subscription objects to import
    */
   subscriptions: Array<SubscriptionImportParams.Subscription>;
+
+  /**
+   * Integration ID to use for importing subscriptions
+   */
+  integrationId?: string | null;
 }
 
 export namespace SubscriptionImportParams {
@@ -3725,6 +3913,8 @@ export interface SubscriptionTransferParams {
 }
 
 Subscriptions.FutureUpdate = FutureUpdate;
+Subscriptions.Usage = Usage;
+Subscriptions.Invoice = Invoice;
 
 export declare namespace Subscriptions {
   export {
@@ -3746,4 +3936,13 @@ export declare namespace Subscriptions {
   };
 
   export { FutureUpdate as FutureUpdate, type CancelSubscription as CancelSubscription };
+
+  export {
+    Usage as Usage,
+    type UsageChargeUsageResponse as UsageChargeUsageResponse,
+    type UsageSyncResponse as UsageSyncResponse,
+    type UsageChargeUsageParams as UsageChargeUsageParams,
+  };
+
+  export { Invoice as Invoice, type InvoiceMarkAsPaidResponse as InvoiceMarkAsPaidResponse };
 }

package/src/resources/v1/subscriptions/usage.ts

@@ -0,0 +1,126 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+export class Usage extends APIResource {
+  /**
+   * Immediately charges usage for a subscription via the billing integration.
+   * Calculates usage since the last charge and creates an invoice.
+   */
+  chargeUsage(
+    id: string,
+    body: UsageChargeUsageParams,
+    options?: RequestOptions,
+  ): APIPromise<UsageChargeUsageResponse> {
+    return this._client.post(path`/api/v1/subscriptions/${id}/usage/charge`, { body, ...options });
+  }
+
+  /**
+   * Triggers a usage sync for a subscription, reporting current usage to the billing
+   * provider.
+   */
+  sync(id: string, options?: RequestOptions): APIPromise<UsageSyncResponse> {
+    return this._client.post(path`/api/v1/subscriptions/${id}/usage/sync`, options);
+  }
+}
+
+/**
+ * Response object
+ */
+export interface UsageChargeUsageResponse {
+  /**
+   * Result of charging subscription usage including the billing period and charged
+   * items.
+   */
+  data: UsageChargeUsageResponse.Data;
+}
+
+export namespace UsageChargeUsageResponse {
+  /**
+   * Result of charging subscription usage including the billing period and charged
+   * items.
+   */
+  export interface Data {
+    /**
+     * The invoice ID in the billing integration
+     */
+    invoiceBillingId: string | null;
+
+    /**
+     * End of the usage billing period
+     */
+    periodEnd: string;
+
+    /**
+     * Start of the usage billing period
+     */
+    periodStart: string;
+
+    /**
+     * The subscription ID for which usage was charged
+     */
+    subscriptionId: string;
+
+    /**
+     * Usage items that were charged
+     */
+    usageCharged: Array<Data.UsageCharged>;
+  }
+
+  export namespace Data {
+    /**
+     * A single usage item that was charged.
+     */
+    export interface UsageCharged {
+      /**
+       * The feature ID for which usage was charged
+       */
+      featureId: string | null;
+
+      /**
+       * The number of units charged
+       */
+      usageAmount: number;
+    }
+  }
+}
+
+/**
+ * Response object
+ */
+export interface UsageSyncResponse {
+  /**
+   * Result of triggering a subscription usage sync.
+   */
+  data: UsageSyncResponse.Data;
+}
+
+export namespace UsageSyncResponse {
+  /**
+   * Result of triggering a subscription usage sync.
+   */
+  export interface Data {
+    /**
+     * Whether usage was synced to the billing provider
+     */
+    triggered: boolean;
+  }
+}
+
+export interface UsageChargeUsageParams {
+  /**
+   * Cutoff date for usage calculation. If not provided, the current time is used.
+   */
+  untilDate?: string;
+}
+
+export declare namespace Usage {
+  export {
+    type UsageChargeUsageResponse as UsageChargeUsageResponse,
+    type UsageSyncResponse as UsageSyncResponse,
+    type UsageChargeUsageParams as UsageChargeUsageParams,
+  };
+}

package/src/resources/v1/usage.ts

@@ -7,7 +7,7 @@ import { path } from '../../internal/utils/path';
 
 export class Usage extends APIResource {
   /**
-   * Get usage history
+   * Retrieves historical usage data for a customer's metered feature over time.
    */
   history(
     featureID: string,
@@ -19,7 +19,8 @@ export class Usage extends APIResource {
   }
 
   /**
-   * Report usage measurements
+   * Reports usage measurements for metered features. The reported usage is used to
+   * track, limit, and bill customer consumption.
    */
   report(body: UsageReportParams, options?: RequestOptions): APIPromise<UsageReportResponse> {
     return this._client.post('/api/v1/usage', { body, ...options });