@stigg/typescript 0.1.0-beta.65 → 0.1.0-beta.66

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

@@ -14,6 +14,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(params: GrantCreateParams, options?: RequestOptions): APIPromise<CreditGrantResponse> {
     const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
@@ -32,6 +44,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(
     params: GrantListParams,
@@ -54,6 +76,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,

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

@@ -11,6 +11,16 @@ export class Reservations extends APIResource {
    * Releases a credit reservation, consuming the given amount and returning the rest
    * of the held credits to the balance. Retry a failed release with the same
    * reservation ID; it is applied once.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.v1.credits.reservations.release('x', {
+   *     consumedAmount: 0,
+   *     currencyId: 'currencyId',
+   *     customerId: 'customerId',
+   *   });
+   * ```
    */
   release(
     reservationID: string,

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

@@ -25,6 +25,19 @@ import {
   PromotionalEntitlementRevokeResponse,
   PromotionalEntitlements,
 } from './promotional-entitlements';
+import * as EntitiesAPI from './entities/entities';
+import {
+  Entities,
+  EntityArchiveParams,
+  EntityArchiveResponse,
+  EntityListParams,
+  EntityListResponse,
+  EntityListResponsesMyCursorIDPage,
+  EntityRetrieveParams,
+  EntityRetrieveResponse,
+  EntityUpsertParams,
+  EntityUpsertResponse,
+} from './entities/entities';
 import { APIPromise } from '../../../core/api-promise';
 import { MyCursorIDPage, type MyCursorIDPageParams, PagePromise } from '../../../core/pagination';
 import { buildHeaders } from '../../../internal/headers';
@@ -36,10 +49,18 @@ export class Customers extends APIResource {
   promotionalEntitlements: PromotionalEntitlementsAPI.PromotionalEntitlements =
     new PromotionalEntitlementsAPI.PromotionalEntitlements(this._client);
   integrations: IntegrationsAPI.Integrations = new IntegrationsAPI.Integrations(this._client);
+  entities: EntitiesAPI.Entities = new EntitiesAPI.Entities(this._client);
 
   /**
    * 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,
@@ -62,6 +83,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, params: CustomerUpdateParams, options?: RequestOptions): APIPromise<CustomerResponse> {
     const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
@@ -80,6 +108,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(
     params: CustomerListParams | null | undefined = {},
@@ -102,6 +138,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,
@@ -124,12 +167,21 @@ 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. 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.
+   * enum values. Pass `dimensions` to also check the governance budgets of the
+   * entities the usage is attributed to; the response then includes `chains`. 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.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.customers.checkEntitlement(
+   *   'x',
+   * );
+   * ```
    */
   checkEntitlement(
     id: string,
@@ -153,6 +205,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(params: CustomerImportParams, options?: RequestOptions): APIPromise<CustomerImportResponse> {
     const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
@@ -173,6 +238,13 @@ export class Customers extends APIResource {
    * 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.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.customers.listContracts(
+   *   'id',
+   * );
+   * ```
    */
   listContracts(
     id: string,
@@ -199,6 +271,16 @@ export class Customers extends APIResource {
    * Optionally narrowed to one contract, an issue-date range, and/or a set of
    * invoice states. Returns an empty list when no billing provider is connected or
    * the customer is not synced.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const customerListInvoicesResponse of client.v1.customers.listInvoices(
+   *   'id',
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   listInvoices(
     id: string,
@@ -225,6 +307,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,
@@ -251,6 +343,12 @@ export class Customers extends APIResource {
 
   /**
    * Creates a new customer.
+   *
+   * @example
+   * ```ts
+   * const customerResponse =
+   *   await client.v1.customers.provision({ id: 'id' });
+   * ```
    */
   provision(params: CustomerProvisionParams, options?: RequestOptions): APIPromise<CustomerResponse> {
     const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
@@ -275,6 +373,12 @@ export class Customers extends APIResource {
    * 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.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.v1.customers.retrieveEntitlements('x');
+   * ```
    */
   retrieveEntitlements(
     id: string,
@@ -297,6 +401,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,
@@ -1689,6 +1799,12 @@ export namespace CustomerCheckEntitlementResponse {
 
     type: 'FEATURE';
 
+    /**
+     * Per-entity rollups, one chain per resolved dimension. Omitted when dimensions
+     * was not provided.
+     */
+    chains?: Array<Array<Feature.Chain>>;
+
     currentUsage?: number;
 
     /**
@@ -1729,6 +1845,39 @@ export namespace CustomerCheckEntitlementResponse {
   }
 
   export namespace Feature {
+    /**
+     * Per-entity governance node — limit and current usage for a single resolved
+     * entity.
+     */
+    export interface Chain {
+      /**
+       * Amount consumed by this entity in the current cadence period.
+       */
+      currentUsage: number;
+
+      /**
+       * External id of the entity within the customer.
+       */
+      entityId: string;
+
+      /**
+       * Whether this node alone permits the requested usage.
+       */
+      isGranted: boolean;
+
+      /**
+       * External ids of the entities this budget is scoped to. Empty (`[]`) is the
+       * node-wide budget; a non-empty set is the dimension-scoped budget that matched
+       * this request — use it to tell apart multiple budgets on the same entity.
+       */
+      scopeEntityIds: Array<string>;
+
+      /**
+       * Hard usage limit for this node; null when the entity has no entity entitlement.
+       */
+      usageLimit: number | null;
+    }
+
     export interface Feature {
       /**
        * The unique reference ID of the entitlement.
@@ -1788,6 +1937,12 @@ export namespace CustomerCheckEntitlementResponse {
      */
     usageUpdatedAt: string;
 
+    /**
+     * Per-entity rollups, one chain per resolved dimension. Omitted when dimensions
+     * was not provided.
+     */
+    chains?: Array<Array<Credit.Chain>>;
+
     /**
      * Timestamp of the last update to the entitlement grant or configuration.
      */
@@ -1859,6 +2014,39 @@ export namespace CustomerCheckEntitlementResponse {
       unitSingular?: string | null;
     }
 
+    /**
+     * Per-entity governance node — limit and current usage for a single resolved
+     * entity.
+     */
+    export interface Chain {
+      /**
+       * Amount consumed by this entity in the current cadence period.
+       */
+      currentUsage: number;
+
+      /**
+       * External id of the entity within the customer.
+       */
+      entityId: string;
+
+      /**
+       * Whether this node alone permits the requested usage.
+       */
+      isGranted: boolean;
+
+      /**
+       * External ids of the entities this budget is scoped to. Empty (`[]`) is the
+       * node-wide budget; a non-empty set is the dimension-scoped budget that matched
+       * this request — use it to tell apart multiple budgets on the same entity.
+       */
+      scopeEntityIds: Array<string>;
+
+      /**
+       * Hard usage limit for this node; null when the entity has no entity entitlement.
+       */
+      usageLimit: number | null;
+    }
+
     /**
      * The reservation created by this request, when it asked to reserve credits and
      * was granted.
@@ -3292,6 +3480,13 @@ export interface CustomerCheckEntitlementParams {
    */
   currencyId?: string;
 
+  /**
+   * Query param: Attribution map of the entities the usage is attributed to (e.g.
+   * `dimensions[userId]=u1`). When provided, their governance budgets are checked
+   * too and the response includes `chains`.
+   */
+  dimensions?: { [key: string]: string };
+
   /**
    * Query param: Feature ID (refId) to check. Mutually exclusive with `currencyId`.
    */
@@ -3335,7 +3530,8 @@ export interface CustomerCheckEntitlementParams {
 
   /**
    * Query param: Credits to reserve (credit entitlements only). The check is decided
-   * and the credits held atomically; `requestedUsage` is ignored.
+   * and the credits held atomically; `requestedUsage` is ignored. Not supported with
+   * `dimensions`.
    */
   reserveAmount?: number;
 
@@ -4148,6 +4344,7 @@ export interface CustomerUnarchiveParams {
 Customers.PaymentMethod = PaymentMethod;
 Customers.PromotionalEntitlements = PromotionalEntitlements;
 Customers.Integrations = Integrations;
+Customers.Entities = Entities;
 
 export declare namespace Customers {
   export {
@@ -4204,4 +4401,17 @@ export declare namespace Customers {
     type IntegrationLinkParams as IntegrationLinkParams,
     type IntegrationUnlinkParams as IntegrationUnlinkParams,
   };
+
+  export {
+    Entities as Entities,
+    type EntityRetrieveResponse as EntityRetrieveResponse,
+    type EntityListResponse as EntityListResponse,
+    type EntityArchiveResponse as EntityArchiveResponse,
+    type EntityUpsertResponse as EntityUpsertResponse,
+    type EntityListResponsesMyCursorIDPage as EntityListResponsesMyCursorIDPage,
+    type EntityRetrieveParams as EntityRetrieveParams,
+    type EntityListParams as EntityListParams,
+    type EntityArchiveParams as EntityArchiveParams,
+    type EntityUpsertParams as EntityUpsertParams,
+  };
 }