@stigg/typescript 0.1.0-beta.14 → 0.1.0-beta.15

package/src/resources/v1/addons/addons.ts

@@ -24,6 +24,15 @@ export class Addons extends APIResource {
 
   /**
    * Creates a new addon in draft status, associated with a specific product.
+   *
+   * @example
+   * ```ts
+   * const addon = await client.v1.addons.create({
+   *   id: 'id',
+   *   displayName: 'displayName',
+   *   productId: 'productId',
+   * });
+   * ```
    */
   create(body: AddonCreateParams, options?: RequestOptions): APIPromise<Addon> {
     return this._client.post('/api/v1/addons', { body, ...options });
@@ -32,6 +41,11 @@ export class Addons extends APIResource {
   /**
    * Retrieves an addon by its unique identifier, including entitlements and pricing
    * details.
+   *
+   * @example
+   * ```ts
+   * const addon = await client.v1.addons.retrieve('x');
+   * ```
    */
   retrieve(id: string, options?: RequestOptions): APIPromise<Addon> {
     return this._client.get(path`/api/v1/addons/${id}`, options);
@@ -40,6 +54,11 @@ export class Addons extends APIResource {
   /**
    * Updates an existing addon's properties such as display name, description, and
    * metadata.
+   *
+   * @example
+   * ```ts
+   * const addon = await client.v1.addons.update('x');
+   * ```
    */
   update(id: string, body: AddonUpdateParams, options?: RequestOptions): APIPromise<Addon> {
     return this._client.patch(path`/api/v1/addons/${id}`, { body, ...options });
@@ -47,6 +66,14 @@ export class Addons extends APIResource {
 
   /**
    * Retrieves a paginated list of addons in the environment.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const addonListResponse of client.v1.addons.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query: AddonListParams | null | undefined = {},
@@ -60,6 +87,11 @@ export class Addons extends APIResource {
 
   /**
    * Archives an addon, preventing it from being used in new subscriptions.
+   *
+   * @example
+   * ```ts
+   * const addon = await client.v1.addons.archive('x');
+   * ```
    */
   archive(id: string, options?: RequestOptions): APIPromise<Addon> {
     return this._client.post(path`/api/v1/addons/${id}/archive`, options);
@@ -67,6 +99,11 @@ export class Addons extends APIResource {
 
   /**
    * Creates a draft version of an existing addon for modification before publishing.
+   *
+   * @example
+   * ```ts
+   * const addon = await client.v1.addons.createDraft('x');
+   * ```
    */
   createDraft(id: string, options?: RequestOptions): APIPromise<Addon> {
     return this._client.post(path`/api/v1/addons/${id}/draft`, options);
@@ -74,6 +111,16 @@ export class Addons extends APIResource {
 
   /**
    * Retrieves the list of charges configured on an addon.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const addonListChargesResponse of client.v1.addons.listCharges(
+   *   'x',
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listCharges(
     id: string,
@@ -89,6 +136,13 @@ export class Addons extends APIResource {
 
   /**
    * Publishes a draft addon, making it available for use in subscriptions.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.addons.publish('x', {
+   *   migrationType: 'NEW_CUSTOMERS',
+   * });
+   * ```
    */
   publish(id: string, body: AddonPublishParams, options?: RequestOptions): APIPromise<AddonPublishResponse> {
     return this._client.post(path`/api/v1/addons/${id}/publish`, { body, ...options });
@@ -96,6 +150,11 @@ export class Addons extends APIResource {
 
   /**
    * Removes a draft version of an addon.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.addons.removeDraft('x');
+   * ```
    */
   removeDraft(id: string, options?: RequestOptions): APIPromise<AddonRemoveDraftResponse> {
     return this._client.delete(path`/api/v1/addons/${id}/draft`, options);

package/src/resources/v1/addons/entitlements.ts

@@ -8,6 +8,14 @@ import { path } from '../../../internal/utils/path';
 export class Entitlements extends APIResource {
   /**
    * Creates one or more entitlements (feature or credit) on a draft addon.
+   *
+   * @example
+   * ```ts
+   * const entitlement =
+   *   await client.v1.addons.entitlements.create('addonId', {
+   *     entitlements: [{ id: 'id', type: 'FEATURE' }],
+   *   });
+   * ```
    */
   create(
     addonID: string,
@@ -19,6 +27,15 @@ export class Entitlements extends APIResource {
 
   /**
    * Updates an existing entitlement on a draft addon.
+   *
+   * @example
+   * ```ts
+   * const addonPackageEntitlement =
+   *   await client.v1.addons.entitlements.update('id', {
+   *     addonId: 'addonId',
+   *     type: 'FEATURE',
+   *   });
+   * ```
    */
   update(
     id: string,
@@ -31,6 +48,12 @@ export class Entitlements extends APIResource {
 
   /**
    * Retrieves a list of entitlements for an addon.
+   *
+   * @example
+   * ```ts
+   * const entitlements =
+   *   await client.v1.addons.entitlements.list('addonId');
+   * ```
    */
   list(addonID: string, options?: RequestOptions): APIPromise<EntitlementListResponse> {
     return this._client.get(path`/api/v1/addons/${addonID}/entitlements`, options);
@@ -38,6 +61,14 @@ export class Entitlements extends APIResource {
 
   /**
    * Deletes an entitlement from a draft addon.
+   *
+   * @example
+   * ```ts
+   * const addonPackageEntitlement =
+   *   await client.v1.addons.entitlements.delete('id', {
+   *     addonId: 'addonId',
+   *   });
+   * ```
    */
   delete(
     id: string,

package/src/resources/v1/coupons.ts

@@ -13,6 +13,19 @@ export class Coupons extends APIResource {
   /**
    * Creates a new discount coupon with percentage or fixed amount off, applicable to
    * customer subscriptions.
+   *
+   * @example
+   * ```ts
+   * const coupon = await client.v1.coupons.create({
+   *   id: 'id',
+   *   amountsOff: [{ amount: 0, currency: 'usd' }],
+   *   description: 'description',
+   *   durationInMonths: 1,
+   *   metadata: { foo: 'string' },
+   *   name: 'name',
+   *   percentOff: 1,
+   * });
+   * ```
    */
   create(body: CouponCreateParams, options?: RequestOptions): APIPromise<Coupon> {
     return this._client.post('/api/v1/coupons', { body, ...options });
@@ -20,6 +33,11 @@ export class Coupons extends APIResource {
 
   /**
    * Retrieves a coupon by its unique identifier.
+   *
+   * @example
+   * ```ts
+   * const coupon = await client.v1.coupons.retrieve('x');
+   * ```
    */
   retrieve(id: string, options?: RequestOptions): APIPromise<Coupon> {
     return this._client.get(path`/api/v1/coupons/${id}`, options);
@@ -27,6 +45,14 @@ export class Coupons extends APIResource {
 
   /**
    * Retrieves a paginated list of coupons in the environment.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const couponListResponse of client.v1.coupons.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query: CouponListParams | null | undefined = {},
@@ -40,6 +66,11 @@ export class Coupons extends APIResource {
 
   /**
    * Archives a coupon, preventing it from being applied to new subscriptions.
+   *
+   * @example
+   * ```ts
+   * const coupon = await client.v1.coupons.archiveCoupon('x');
+   * ```
    */
   archiveCoupon(id: string, options?: RequestOptions): APIPromise<Coupon> {
     return this._client.post(path`/api/v1/coupons/${id}/archive`, options);
@@ -47,6 +78,11 @@ export class Coupons extends APIResource {
 
   /**
    * Updates an existing coupon's properties such as name, description, and metadata.
+   *
+   * @example
+   * ```ts
+   * const coupon = await client.v1.coupons.updateCoupon('x');
+   * ```
    */
   updateCoupon(id: string, body: CouponUpdateCouponParams, options?: RequestOptions): APIPromise<Coupon> {
     return this._client.patch(path`/api/v1/coupons/${id}`, { body, ...options });

package/src/resources/v1/credits/credits.ts

@@ -34,6 +34,14 @@ export class Credits extends APIResource {
   /**
    * Retrieves the automatic recharge configuration for a customer and currency.
    * Returns default settings if no configuration exists.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.credits.getAutoRecharge({
+   *   currencyId: 'currencyId',
+   *   customerId: 'customerId',
+   * });
+   * ```
    */
   getAutoRecharge(
     query: CreditGetAutoRechargeParams,
@@ -45,6 +53,13 @@ export class Credits extends APIResource {
   /**
    * Retrieves credit usage time-series data for a customer, grouped by feature, over
    * a specified time range.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.credits.getUsage({
+   *   customerId: 'customerId',
+   * });
+   * ```
    */
   getUsage(query: CreditGetUsageParams, options?: RequestOptions): APIPromise<CreditGetUsageResponse> {
     return this._client.get('/api/v1/credits/usage', { query, ...options });
@@ -52,6 +67,16 @@ export class Credits extends APIResource {
 
   /**
    * Retrieves a paginated list of credit ledger events for a customer.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const creditListLedgerResponse of client.v1.credits.listLedger(
+   *   { customerId: 'customerId' },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listLedger(
     query: CreditListLedgerParams,
@@ -158,6 +183,13 @@ export namespace CreditGetUsageResponse {
      */
     currency: Data.Currency | null;
 
+    /**
+     * Cursor-based pagination for the returned series. `next`/`prev` are opaque
+     * cursors; pass them back as `after`/`before` to traverse pages. The series axis
+     * is `groupBy` when provided, otherwise `featureId`
+     */
+    pagination: Data.Pagination;
+
     /**
      * Credit usage series grouped by feature
      */
@@ -195,6 +227,24 @@ export namespace CreditGetUsageResponse {
       symbol: string | null;
     }
 
+    /**
+     * Cursor-based pagination for the returned series. `next`/`prev` are opaque
+     * cursors; pass them back as `after`/`before` to traverse pages. The series axis
+     * is `groupBy` when provided, otherwise `featureId`
+     */
+    export interface Pagination {
+      /**
+       * Cursor for fetching the next page of results, or null if no additional pages
+       * exist
+       */
+      next: string | null;
+
+      /**
+       * Cursor for fetching the previous page of results, or null if at the beginning
+       */
+      prev: string | null;
+    }
+
     /**
      * Credit usage data for a single feature
      */
@@ -334,6 +384,16 @@ export interface CreditGetUsageParams {
    */
   customerId: string;
 
+  /**
+   * Return items that come after this cursor
+   */
+  after?: string;
+
+  /**
+   * Return items that come before this cursor
+   */
+  before?: string;
+
   /**
    * Filter by currency ID
    */
@@ -351,6 +411,11 @@ export interface CreditGetUsageParams {
    */
   groupBy?: string;
 
+  /**
+   * Maximum number of items to return
+   */
+  limit?: number;
+
   /**
    * Filter by resource ID
    */

package/src/resources/v1/credits/custom-currencies.ts

@@ -12,6 +12,15 @@ import { path } from '../../../internal/utils/path';
 export class CustomCurrencies extends APIResource {
   /**
    * Creates a new custom currency in the environment.
+   *
+   * @example
+   * ```ts
+   * const customCurrencyResponse =
+   *   await client.v1.credits.customCurrencies.create({
+   *     id: 'id',
+   *     displayName: 'displayName',
+   *   });
+   * ```
    */
   create(body: CustomCurrencyCreateParams, options?: RequestOptions): APIPromise<CustomCurrencyResponse> {
     return this._client.post('/api/v1/credits/custom-currencies', { body, ...options });
@@ -19,6 +28,14 @@ export class CustomCurrencies extends APIResource {
 
   /**
    * Updates an existing custom currency. Only the supplied fields are modified.
+   *
+   * @example
+   * ```ts
+   * const customCurrencyResponse =
+   *   await client.v1.credits.customCurrencies.update(
+   *     'currencyId',
+   *   );
+   * ```
    */
   update(
     currencyID: string,
@@ -32,6 +49,14 @@ export class CustomCurrencies extends APIResource {
    * Retrieves a paginated list of custom currencies in the environment. Archived
    * currencies are excluded by default; pass `status=ARCHIVED` (or
    * `status=ACTIVE,ARCHIVED`) to include them.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const customCurrencyListResponse of client.v1.credits.customCurrencies.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query: CustomCurrencyListParams | null | undefined = {},
@@ -48,6 +73,14 @@ export class CustomCurrencies extends APIResource {
    * Archives a custom currency. Fails if the currency is still associated with any
    * active plan or addon — use the associated-entities endpoint first to inspect
    * dependencies.
+   *
+   * @example
+   * ```ts
+   * const customCurrencyResponse =
+   *   await client.v1.credits.customCurrencies.archive(
+   *     'currencyId',
+   *   );
+   * ```
    */
   archive(currencyID: string, options?: RequestOptions): APIPromise<CustomCurrencyResponse> {
     return this._client.post(path`/api/v1/credits/custom-currencies/${currencyID}/archive`, options);
@@ -56,6 +89,14 @@ export class CustomCurrencies extends APIResource {
   /**
    * Lists the active plans and addons that reference a custom currency. Useful
    * before archiving to inspect dependencies.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.v1.credits.customCurrencies.listAssociatedEntities(
+   *     'currencyId',
+   *   );
+   * ```
    */
   listAssociatedEntities(
     currencyID: string,
@@ -70,6 +111,14 @@ export class CustomCurrencies extends APIResource {
   /**
    * Restores a previously archived custom currency. Fails if another active currency
    * with the same ID already exists.
+   *
+   * @example
+   * ```ts
+   * const customCurrencyResponse =
+   *   await client.v1.credits.customCurrencies.unarchive(
+   *     'currencyId',
+   *   );
+   * ```
    */
   unarchive(currencyID: string, options?: RequestOptions): APIPromise<CustomCurrencyResponse> {
     return this._client.post(path`/api/v1/credits/custom-currencies/${currencyID}/unarchive`, options);

package/src/resources/v1/credits/grants.ts

@@ -13,6 +13,18 @@ export class Grants extends APIResource {
   /**
    * Creates a new credit grant for a customer with specified amount, type, and
    * optional billing configuration.
+   *
+   * @example
+   * ```ts
+   * const creditGrantResponse =
+   *   await client.v1.credits.grants.create({
+   *     amount: 0,
+   *     currencyId: 'currencyId',
+   *     customerId: 'customerId',
+   *     displayName: 'displayName',
+   *     grantType: 'PAID',
+   *   });
+   * ```
    */
   create(body: GrantCreateParams, options?: RequestOptions): APIPromise<CreditGrantResponse> {
     return this._client.post('/api/v1/credits/grants', { body, ...options });
@@ -20,6 +32,16 @@ export class Grants extends APIResource {
 
   /**
    * Retrieves a paginated list of credit grants for a customer.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const grantListResponse of client.v1.credits.grants.list(
+   *   { customerId: 'customerId' },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query: GrantListParams,
@@ -34,6 +56,12 @@ export class Grants extends APIResource {
   /**
    * Voids an existing credit grant, preventing further consumption of the remaining
    * credits.
+   *
+   * @example
+   * ```ts
+   * const creditGrantResponse =
+   *   await client.v1.credits.grants.void('x');
+   * ```
    */
   void(id: string, options?: RequestOptions): APIPromise<CreditGrantResponse> {
     return this._client.post(path`/api/v1/credits/grants/${id}/void`, options);

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

@@ -39,6 +39,13 @@ export class Customers extends APIResource {
   /**
    * Retrieves a customer by their unique identifier, including billing information
    * and subscription status.
+   *
+   * @example
+   * ```ts
+   * const customerResponse = await client.v1.customers.retrieve(
+   *   'x',
+   * );
+   * ```
    */
   retrieve(id: string, options?: RequestOptions): APIPromise<CustomerResponse> {
     return this._client.get(path`/api/v1/customers/${id}`, options);
@@ -47,6 +54,13 @@ export class Customers extends APIResource {
   /**
    * Updates an existing customer's properties such as name, email, and billing
    * information.
+   *
+   * @example
+   * ```ts
+   * const customerResponse = await client.v1.customers.update(
+   *   'x',
+   * );
+   * ```
    */
   update(id: string, body: CustomerUpdateParams, options?: RequestOptions): APIPromise<CustomerResponse> {
     return this._client.patch(path`/api/v1/customers/${id}`, { body, ...options });
@@ -54,6 +68,14 @@ export class Customers extends APIResource {
 
   /**
    * Retrieves a paginated list of customers in the environment.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const customerListResponse of client.v1.customers.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query: CustomerListParams | null | undefined = {},
@@ -68,6 +90,13 @@ export class Customers extends APIResource {
   /**
    * Archives a customer, preventing new subscriptions. Optionally cancels existing
    * subscriptions.
+   *
+   * @example
+   * ```ts
+   * const customerResponse = await client.v1.customers.archive(
+   *   'x',
+   * );
+   * ```
    */
   archive(id: string, options?: RequestOptions): APIPromise<CustomerResponse> {
     return this._client.post(path`/api/v1/customers/${id}/archive`, options);
@@ -82,6 +111,13 @@ export class Customers extends APIResource {
    * 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.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.customers.checkEntitlement(
+   *   'x',
+   * );
+   * ```
    */
   checkEntitlement(
     id: string,
@@ -94,6 +130,19 @@ export class Customers extends APIResource {
   /**
    * Imports multiple customers in bulk. Used for migrating customer data from
    * external systems.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.customers.import({
+   *   customers: [
+   *     {
+   *       id: 'id',
+   *       email: 'dev@stainless.com',
+   *       name: 'name',
+   *     },
+   *   ],
+   * });
+   * ```
    */
   import(body: CustomerImportParams, options?: RequestOptions): APIPromise<CustomerImportResponse> {
     return this._client.post('/api/v1/customers/import', { body, ...options });
@@ -101,6 +150,16 @@ export class Customers extends APIResource {
 
   /**
    * Retrieves a paginated list of resources within the same customer.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const customerListResourcesResponse of client.v1.customers.listResources(
+   *   'x',
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listResources(
     id: string,
@@ -117,6 +176,12 @@ export class Customers extends APIResource {
   /**
    * Creates a new customer and optionally provisions an initial subscription in a
    * single operation.
+   *
+   * @example
+   * ```ts
+   * const customerResponse =
+   *   await client.v1.customers.provision({ id: 'id' });
+   * ```
    */
   provision(body: CustomerProvisionParams, options?: RequestOptions): APIPromise<CustomerResponse> {
     return this._client.post('/api/v1/customers', { body, ...options });
@@ -130,6 +195,12 @@ export class Customers extends APIResource {
    * 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.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.v1.customers.retrieveEntitlements('x');
+   * ```
    */
   retrieveEntitlements(
     id: string,
@@ -141,6 +212,12 @@ export class Customers extends APIResource {
 
   /**
    * Restores an archived customer, allowing them to create new subscriptions again.
+   *
+   * @example
+   * ```ts
+   * const customerResponse =
+   *   await client.v1.customers.unarchive('x');
+   * ```
    */
   unarchive(id: string, options?: RequestOptions): APIPromise<CustomerResponse> {
     return this._client.post(path`/api/v1/customers/${id}/unarchive`, options);