@stigg/typescript 0.1.0-beta.4 → 0.1.0-beta.41

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

@@ -0,0 +1,269 @@
+// 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 { buildHeaders } from '../../../internal/headers';
+import { RequestOptions } from '../../../internal/request-options';
+
+export class Consumption extends APIResource {
+  /**
+   * Consumes a specified amount of credits directly from a customer wallet, with no
+   * feature mapping. Returns the optimistic balance.
+   */
+  consume(
+    params: ConsumptionConsumeParams,
+    options?: RequestOptions,
+  ): APIPromise<ConsumptionConsumeResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
+    return this._client.post('/api/v1/credits/consumption', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Consumes credits directly from customer wallets asynchronously. Consumptions are
+   * reconciled asynchronously into the credit balances.
+   */
+  consumeAsync(
+    params: ConsumptionConsumeAsyncParams,
+    options?: RequestOptions,
+  ): APIPromise<ConsumptionConsumeAsyncResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
+    return this._client.post('/api/v1/credits/consumption/async', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+/**
+ * Response object
+ */
+export interface ConsumptionConsumeResponse {
+  /**
+   * Result of a synchronous direct credit consumption
+   */
+  data: ConsumptionConsumeResponse.Data;
+}
+
+export namespace ConsumptionConsumeResponse {
+  /**
+   * Result of a synchronous direct credit consumption
+   */
+  export interface Data {
+    /**
+     * The amount of credits consumed
+     */
+    amount: number;
+
+    /**
+     * The credit currency the credits were consumed from
+     */
+    currencyId: string;
+
+    /**
+     * The customer the credits were consumed from
+     */
+    customerId: string;
+
+    /**
+     * The timestamp the consumption was attributed to
+     */
+    timestamp: string;
+
+    /**
+     * The optimistic credit balance after consumption (when sync credit consumption is
+     * enabled)
+     */
+    credit?: Data.Credit | null;
+
+    /**
+     * The resource the consumption was attributed to
+     */
+    resourceId?: string | null;
+  }
+
+  export namespace Data {
+    /**
+     * The optimistic credit balance after consumption (when sync credit consumption is
+     * enabled)
+     */
+    export interface Credit {
+      /**
+       * The credit currency identifier
+       */
+      currencyId: string;
+
+      /**
+       * The wallet's total consumed credits for this currency (optimistic — includes
+       * not-yet-reconciled usage), shared across every feature that draws on the
+       * currency. This is the running balance, not this call's deduction — see
+       * `consumed` for that.
+       */
+      currentUsage: number;
+
+      /**
+       * The grant-version timestamp of this balance, used by the SDK for last-write-wins
+       * reconciliation
+       */
+      timestamp: string;
+
+      /**
+       * The total credits granted
+       */
+      usageLimit: number;
+
+      /**
+       * End of the current credit grant period (when recurring credits reset), if
+       * applicable
+       */
+      usagePeriodEnd?: string | null;
+    }
+  }
+}
+
+/**
+ * Response object
+ */
+export interface ConsumptionConsumeAsyncResponse {
+  /**
+   * Confirmation that the credit consumptions were accepted for processing
+   */
+  data: unknown;
+}
+
+export interface ConsumptionConsumeParams {
+  /**
+   * Body param: The amount of credits to consume
+   */
+  amount: number;
+
+  /**
+   * Body param: The credit currency to consume from (required)
+   */
+  currencyId: string;
+
+  /**
+   * Body param: The customer to consume credits from (required)
+   */
+  customerId: string;
+
+  /**
+   * Body param: A unique key used to deduplicate the consumption (required)
+   */
+  idempotencyKey: string;
+
+  /**
+   * Body param: Optional timestamp the consumption is attributed to
+   */
+  createdAt?: string;
+
+  /**
+   * Body param: Optional dimensions describing the consumption
+   */
+  dimensions?: { [key: string]: string | number | boolean };
+
+  /**
+   * Body param: Optional resource the consumption is attributed to
+   */
+  resourceId?: string;
+
+  /**
+   * Header param: Account ID — optional when authenticating with a user JWT (Bearer
+   * token); falls back to the user's first membership. Ignored for API-key auth.
+   */
+  'X-ACCOUNT-ID'?: string;
+
+  /**
+   * Header param: Environment ID — required when authenticating with a user JWT
+   * (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is
+   * intrinsic to the key).
+   */
+  'X-ENVIRONMENT-ID'?: string;
+}
+
+export interface ConsumptionConsumeAsyncParams {
+  /**
+   * Body param: The credit consumptions to report (up to 1000)
+   */
+  consumptions: Array<ConsumptionConsumeAsyncParams.Consumption>;
+
+  /**
+   * Header param: Account ID — optional when authenticating with a user JWT (Bearer
+   * token); falls back to the user's first membership. Ignored for API-key auth.
+   */
+  'X-ACCOUNT-ID'?: string;
+
+  /**
+   * Header param: Environment ID — required when authenticating with a user JWT
+   * (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is
+   * intrinsic to the key).
+   */
+  'X-ENVIRONMENT-ID'?: string;
+}
+
+export namespace ConsumptionConsumeAsyncParams {
+  /**
+   * Request body for consuming credits directly from a wallet
+   */
+  export interface Consumption {
+    /**
+     * The amount of credits to consume
+     */
+    amount: number;
+
+    /**
+     * The credit currency to consume from (required)
+     */
+    currencyId: string;
+
+    /**
+     * The customer to consume credits from (required)
+     */
+    customerId: string;
+
+    /**
+     * A unique key used to deduplicate the consumption (required)
+     */
+    idempotencyKey: string;
+
+    /**
+     * Optional timestamp the consumption is attributed to
+     */
+    createdAt?: string;
+
+    /**
+     * Optional dimensions describing the consumption
+     */
+    dimensions?: { [key: string]: string | number | boolean };
+
+    /**
+     * Optional resource the consumption is attributed to
+     */
+    resourceId?: string;
+  }
+}
+
+export declare namespace Consumption {
+  export {
+    type ConsumptionConsumeResponse as ConsumptionConsumeResponse,
+    type ConsumptionConsumeAsyncResponse as ConsumptionConsumeAsyncResponse,
+    type ConsumptionConsumeParams as ConsumptionConsumeParams,
+    type ConsumptionConsumeAsyncParams as ConsumptionConsumeAsyncParams,
+  };
+}

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

@@ -1,15 +1,26 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../../core/resource';
+import * as ConsumptionAPI from './consumption';
+import {
+  Consumption,
+  ConsumptionConsumeAsyncParams,
+  ConsumptionConsumeAsyncResponse,
+  ConsumptionConsumeParams,
+  ConsumptionConsumeResponse,
+} from './consumption';
 import * as CustomCurrenciesAPI from './custom-currencies';
 import {
   CustomCurrencies,
+  CustomCurrencyArchiveParams,
   CustomCurrencyCreateParams,
+  CustomCurrencyListAssociatedEntitiesParams,
   CustomCurrencyListAssociatedEntitiesResponse,
   CustomCurrencyListParams,
   CustomCurrencyListResponse,
   CustomCurrencyListResponsesMyCursorIDPage,
   CustomCurrencyResponse,
+  CustomCurrencyUnarchiveParams,
   CustomCurrencyUpdateParams,
 } from './custom-currencies';
 import * as GrantsAPI from './grants';
@@ -19,10 +30,12 @@ import {
   GrantListParams,
   GrantListResponse,
   GrantListResponsesMyCursorIDPage,
+  GrantVoidParams,
   Grants,
 } from './grants';
 import { APIPromise } from '../../../core/api-promise';
 import { MyCursorIDPage, type MyCursorIDPageParams, PagePromise } from '../../../core/pagination';
+import { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
 
 export class Credits extends APIResource {
@@ -30,36 +43,67 @@ export class Credits extends APIResource {
   customCurrencies: CustomCurrenciesAPI.CustomCurrencies = new CustomCurrenciesAPI.CustomCurrencies(
     this._client,
   );
+  consumption: ConsumptionAPI.Consumption = new ConsumptionAPI.Consumption(this._client);
 
   /**
    * Retrieves the automatic recharge configuration for a customer and currency.
    * Returns default settings if no configuration exists.
    */
   getAutoRecharge(
-    query: CreditGetAutoRechargeParams,
+    params: CreditGetAutoRechargeParams,
     options?: RequestOptions,
   ): APIPromise<CreditGetAutoRechargeResponse> {
-    return this._client.get('/api/v1/credits/auto-recharge', { query, ...options });
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...query } = params;
+    return this._client.get('/api/v1/credits/auto-recharge', {
+      query,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
    * Retrieves credit usage time-series data for a customer, grouped by feature, over
    * a specified time range.
    */
-  getUsage(query: CreditGetUsageParams, options?: RequestOptions): APIPromise<CreditGetUsageResponse> {
-    return this._client.get('/api/v1/credits/usage', { query, ...options });
+  getUsage(params: CreditGetUsageParams, options?: RequestOptions): APIPromise<CreditGetUsageResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...query } = params;
+    return this._client.get('/api/v1/credits/usage', {
+      query,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
    * Retrieves a paginated list of credit ledger events for a customer.
    */
   listLedger(
-    query: CreditListLedgerParams,
+    params: CreditListLedgerParams,
     options?: RequestOptions,
   ): PagePromise<CreditListLedgerResponsesMyCursorIDPage, CreditListLedgerResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...query } = params;
     return this._client.getAPIList('/api/v1/credits/ledger', MyCursorIDPage<CreditListLedgerResponse>, {
       query,
       ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
     });
   }
 }
@@ -158,6 +202,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,19 +246,37 @@ 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
      */
     export interface Series {
       /**
-       * The feature ID
+       * The feature ID; null when grouping by dimensions only
        */
-      featureId: string;
+      featureId: string | null;
 
       /**
-       * The display name of the feature
+       * The display name of the feature; null when grouping by dimensions only
        */
-      featureName: string;
+      featureName: string | null;
 
       /**
        * Time-series data points for this feature
@@ -218,6 +287,11 @@ export namespace CreditGetUsageResponse {
        * Total credits consumed by this feature in the time range
        */
       totalCredits: number;
+
+      /**
+       * Dimension key/value pairs identifying this series when groupBy is applied
+       */
+      tags?: Array<Series.Tag>;
     }
 
     export namespace Series {
@@ -235,6 +309,21 @@ export namespace CreditGetUsageResponse {
          */
         value: number;
       }
+
+      /**
+       * Dimension key/value pair identifying a credit usage series
+       */
+      export interface Tag {
+        /**
+         * The dimension key
+         */
+        key: string;
+
+        /**
+         * The dimension value for this series
+         */
+        value: string;
+      }
     }
   }
 }
@@ -298,70 +387,131 @@ export interface CreditListLedgerResponse {
 
 export interface CreditGetAutoRechargeParams {
   /**
-   * Filter by currency ID (required)
+   * Query param: Filter by currency ID (required)
    */
   currencyId: string;
 
   /**
-   * Filter by customer ID (required)
+   * Query param: Filter by customer ID (required)
    */
   customerId: string;
+
+  /**
+   * Header param: Account ID — optional when authenticating with a user JWT (Bearer
+   * token); falls back to the user's first membership. Ignored for API-key auth.
+   */
+  'X-ACCOUNT-ID'?: string;
+
+  /**
+   * Header param: Environment ID — required when authenticating with a user JWT
+   * (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is
+   * intrinsic to the key).
+   */
+  'X-ENVIRONMENT-ID'?: string;
 }
 
 export interface CreditGetUsageParams {
   /**
-   * Filter by customer ID (required)
+   * Query param: Filter by customer ID (required)
    */
   customerId: string;
 
   /**
-   * Filter by currency ID
+   * Query param: Return items that come after this cursor
+   */
+  after?: string;
+
+  /**
+   * Query param: Return items that come before this cursor
+   */
+  before?: string;
+
+  /**
+   * Query param: Filter by currency ID
    */
   currencyId?: string;
 
   /**
-   * End date for the credit usage time range (ISO 8601). Defaults to now when
-   * startDate is provided
+   * Query param: End date for the credit usage time range (ISO 8601). Defaults to
+   * now when startDate is provided
    */
   endDate?: string;
 
   /**
-   * Filter by resource ID
+   * Query param: Comma-separated list of feature dimension keys to group usage
+   * series by (up to 3). Each key matches /^[a-zA-Z0-9_$-]+$/
+   */
+  groupBy?: string;
+
+  /**
+   * Query param: Maximum number of items to return
+   */
+  limit?: number;
+
+  /**
+   * Query param: Filter by resource ID
    */
   resourceId?: string;
 
   /**
-   * Start date for the credit usage time range (ISO 8601). Takes precedence over
-   * timeRange when provided
+   * Query param: Start date for the credit usage time range (ISO 8601). Takes
+   * precedence over timeRange when provided
    */
   startDate?: string;
 
   /**
-   * Time range for usage data (LAST_DAY, LAST_WEEK, LAST_MONTH, LAST_YEAR). Defaults
-   * to LAST_MONTH
+   * Query param: Time range for usage data (LAST_DAY, LAST_WEEK, LAST_MONTH,
+   * LAST_YEAR). Defaults to LAST_MONTH
    */
   timeRange?: 'LAST_DAY' | 'LAST_WEEK' | 'LAST_MONTH' | 'LAST_YEAR';
+
+  /**
+   * Header param: Account ID — optional when authenticating with a user JWT (Bearer
+   * token); falls back to the user's first membership. Ignored for API-key auth.
+   */
+  'X-ACCOUNT-ID'?: string;
+
+  /**
+   * Header param: Environment ID — required when authenticating with a user JWT
+   * (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is
+   * intrinsic to the key).
+   */
+  'X-ENVIRONMENT-ID'?: string;
 }
 
 export interface CreditListLedgerParams extends MyCursorIDPageParams {
   /**
-   * Filter by customer ID (required)
+   * Query param: Filter by customer ID (required)
    */
   customerId: string;
 
   /**
-   * Filter by currency ID
+   * Query param: Filter by currency ID
    */
   currencyId?: string;
 
   /**
-   * Filter by resource ID
+   * Query param: Filter by resource ID
    */
   resourceId?: string;
+
+  /**
+   * Header param: Account ID — optional when authenticating with a user JWT (Bearer
+   * token); falls back to the user's first membership. Ignored for API-key auth.
+   */
+  'X-ACCOUNT-ID'?: string;
+
+  /**
+   * Header param: Environment ID — required when authenticating with a user JWT
+   * (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is
+   * intrinsic to the key).
+   */
+  'X-ENVIRONMENT-ID'?: string;
 }
 
 Credits.Grants = Grants;
 Credits.CustomCurrencies = CustomCurrencies;
+Credits.Consumption = Consumption;
 
 export declare namespace Credits {
   export {
@@ -381,6 +531,7 @@ export declare namespace Credits {
     type GrantListResponsesMyCursorIDPage as GrantListResponsesMyCursorIDPage,
     type GrantCreateParams as GrantCreateParams,
     type GrantListParams as GrantListParams,
+    type GrantVoidParams as GrantVoidParams,
   };
 
   export {
@@ -392,5 +543,16 @@ export declare namespace Credits {
     type CustomCurrencyCreateParams as CustomCurrencyCreateParams,
     type CustomCurrencyUpdateParams as CustomCurrencyUpdateParams,
     type CustomCurrencyListParams as CustomCurrencyListParams,
+    type CustomCurrencyArchiveParams as CustomCurrencyArchiveParams,
+    type CustomCurrencyListAssociatedEntitiesParams as CustomCurrencyListAssociatedEntitiesParams,
+    type CustomCurrencyUnarchiveParams as CustomCurrencyUnarchiveParams,
+  };
+
+  export {
+    Consumption as Consumption,
+    type ConsumptionConsumeResponse as ConsumptionConsumeResponse,
+    type ConsumptionConsumeAsyncResponse as ConsumptionConsumeAsyncResponse,
+    type ConsumptionConsumeParams as ConsumptionConsumeParams,
+    type ConsumptionConsumeAsyncParams as ConsumptionConsumeAsyncParams,
   };
 }