@stigg/typescript 0.1.0-beta.40 → 0.1.0-beta.42

package/src/resources/v1/events/events.ts

@@ -24,6 +24,29 @@ export class Events extends APIResource {
   dataExport: DataExportAPI.DataExport = new DataExportAPI.DataExport(this._client);
   beta: BetaAPI.Beta = new BetaAPI.Beta(this._client);
 
+  /**
+   * Estimates the credit cost of a usage event without ingesting it. Returns the
+   * estimated cost per credit currency, the current balance, and the balance after
+   * the estimated consumption.
+   */
+  estimateCost(
+    params: EventEstimateCostParams,
+    options?: RequestOptions,
+  ): APIPromise<EventEstimateCostResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
+    return this._client.post('/api/v1/events/estimate', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
   /**
    * Reports raw usage events for event-based metering. Events are ingested
    * asynchronously and aggregated into usage totals.
@@ -44,6 +67,86 @@ export class Events extends APIResource {
   }
 }
 
+/**
+ * Response object
+ */
+export interface EventEstimateCostResponse {
+  /**
+   * Estimated credit cost, current balance and balance after
+   */
+  data: EventEstimateCostResponse.Data;
+}
+
+export namespace EventEstimateCostResponse {
+  /**
+   * Estimated credit cost, current balance and balance after
+   */
+  export interface Data {
+    /**
+     * Per-currency cost estimates
+     */
+    estimates: Array<Data.Estimate>;
+
+    /**
+     * Request-level warnings about the estimation context
+     */
+    warnings: Array<'RESOURCE_SCOPED_SUBSCRIPTION_EXISTS' | 'FEATURE_NOT_FOUND' | 'FEATURE_NOT_CREDIT_BASED'>;
+  }
+
+  export namespace Data {
+    export interface Estimate {
+      /**
+       * The credit balance after subtracting the estimated cost
+       */
+      balanceAfterEstimate: number;
+
+      /**
+       * Estimated cost contribution per feature
+       */
+      breakdown: Array<Estimate.Breakdown>;
+
+      /**
+       * The credit currency identifier
+       */
+      currencyId: string;
+
+      /**
+       * The current credit balance, including not-yet-reconciled consumption
+       */
+      currentBalance: number;
+
+      /**
+       * The estimated credit cost of the reported event or usage
+       */
+      estimatedCost: number;
+
+      /**
+       * Whether the estimated consumption would bring the balance below zero
+       */
+      wouldOverdraft: boolean;
+    }
+
+    export namespace Estimate {
+      export interface Breakdown {
+        /**
+         * The estimated credit cost contributed by this feature
+         */
+        cost: number;
+
+        /**
+         * The feature whose meter contributed this cost
+         */
+        featureId: string;
+
+        /**
+         * Warning explaining why this cost may be inaccurate, if any
+         */
+        warningCode: 'UNSUPPORTED_AGGREGATION' | null;
+      }
+    }
+  }
+}
+
 /**
  * Response object
  */
@@ -55,6 +158,41 @@ export interface EventReportResponse {
   data: unknown;
 }
 
+export interface EventEstimateCostParams {
+  /**
+   * Body param: Customer id
+   */
+  customerId: string;
+
+  /**
+   * Body param: The name of the usage event
+   */
+  eventName: string;
+
+  /**
+   * Body param: Dimensions associated with the usage event
+   */
+  dimensions?: { [key: string]: string | number | boolean };
+
+  /**
+   * Body param: Resource id
+   */
+  resourceId?: string | null;
+
+  /**
+   * 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 EventReportParams {
   /**
    * Body param: A list of usage events to report
@@ -116,7 +254,12 @@ Events.DataExport = DataExport;
 Events.Beta = Beta;
 
 export declare namespace Events {
-  export { type EventReportResponse as EventReportResponse, type EventReportParams as EventReportParams };
+  export {
+    type EventEstimateCostResponse as EventEstimateCostResponse,
+    type EventReportResponse as EventReportResponse,
+    type EventEstimateCostParams as EventEstimateCostParams,
+    type EventReportParams as EventReportParams,
+  };
 
   export {
     DataExport as DataExport,

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

@@ -10,4 +10,10 @@ export {
   type DataExportMintScopedTokenParams,
   type DataExportTriggerSyncParams,
 } from './data-export/index';
-export { Events, type EventReportResponse, type EventReportParams } from './events';
+export {
+  Events,
+  type EventEstimateCostResponse,
+  type EventReportResponse,
+  type EventEstimateCostParams,
+  type EventReportParams,
+} from './events';

package/src/resources/v1/index.ts

@@ -62,7 +62,13 @@ export {
   type CustomerListResponsesMyCursorIDPage,
   type CustomerListResourcesResponsesMyCursorIDPage,
 } from './customers/index';
-export { Events, type EventReportResponse, type EventReportParams } from './events/index';
+export {
+  Events,
+  type EventEstimateCostResponse,
+  type EventReportResponse,
+  type EventEstimateCostParams,
+  type EventReportParams,
+} from './events/index';
 export {
   Features,
   type Feature,
@@ -130,8 +136,10 @@ export {
 } from './subscriptions/index';
 export {
   Usage,
+  type UsageEstimateCostResponse,
   type UsageHistoryResponse,
   type UsageReportResponse,
+  type UsageEstimateCostParams,
   type UsageHistoryParams,
   type UsageReportParams,
 } from './usage';

package/src/resources/v1/usage.ts

@@ -10,6 +10,29 @@ import { path } from '../../internal/utils/path';
  * Operations related to usage & metering
  */
 export class Usage extends APIResource {
+  /**
+   * Estimates the credit cost of a usage report without recording it. Returns the
+   * estimated cost per credit currency, the current balance, and the balance after
+   * the estimated consumption.
+   */
+  estimateCost(
+    params: UsageEstimateCostParams,
+    options?: RequestOptions,
+  ): APIPromise<UsageEstimateCostResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
+    return this._client.post('/api/v1/usage/estimate', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
   /**
    * Retrieves historical usage data for a customer's metered feature over time.
    */
@@ -52,6 +75,86 @@ export class Usage extends APIResource {
   }
 }
 
+/**
+ * Response object
+ */
+export interface UsageEstimateCostResponse {
+  /**
+   * Estimated credit cost, current balance and balance after
+   */
+  data: UsageEstimateCostResponse.Data;
+}
+
+export namespace UsageEstimateCostResponse {
+  /**
+   * Estimated credit cost, current balance and balance after
+   */
+  export interface Data {
+    /**
+     * Per-currency cost estimates
+     */
+    estimates: Array<Data.Estimate>;
+
+    /**
+     * Request-level warnings about the estimation context
+     */
+    warnings: Array<'RESOURCE_SCOPED_SUBSCRIPTION_EXISTS' | 'FEATURE_NOT_FOUND' | 'FEATURE_NOT_CREDIT_BASED'>;
+  }
+
+  export namespace Data {
+    export interface Estimate {
+      /**
+       * The credit balance after subtracting the estimated cost
+       */
+      balanceAfterEstimate: number;
+
+      /**
+       * Estimated cost contribution per feature
+       */
+      breakdown: Array<Estimate.Breakdown>;
+
+      /**
+       * The credit currency identifier
+       */
+      currencyId: string;
+
+      /**
+       * The current credit balance, including not-yet-reconciled consumption
+       */
+      currentBalance: number;
+
+      /**
+       * The estimated credit cost of the reported event or usage
+       */
+      estimatedCost: number;
+
+      /**
+       * Whether the estimated consumption would bring the balance below zero
+       */
+      wouldOverdraft: boolean;
+    }
+
+    export namespace Estimate {
+      export interface Breakdown {
+        /**
+         * The estimated credit cost contributed by this feature
+         */
+        cost: number;
+
+        /**
+         * The feature whose meter contributed this cost
+         */
+        featureId: string;
+
+        /**
+         * Warning explaining why this cost may be inaccurate, if any
+         */
+        warningCode: 'UNSUPPORTED_AGGREGATION' | null;
+      }
+    }
+  }
+}
+
 /**
  * Response object
  */
@@ -232,13 +335,24 @@ export namespace UsageReportResponse {
      * Optimistic credit balance for a credit-backed feature
      */
     export interface Credit {
+      /**
+       * The credits this single reportUsage call deducted, in credit units — scoped to
+       * this one measurement (0 for idempotency duplicates). Contrast `currentUsage`,
+       * which is the wallet-wide running total shared across all features on this
+       * currency. Use it to reconcile expected per-call deductions.
+       */
+      consumed: number;
+
       /**
        * The credit currency identifier
        */
       currencyId: string;
 
       /**
-       * The credits consumed (optimistic — includes not-yet-reconciled usage)
+       * 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;
 
@@ -262,6 +376,51 @@ export namespace UsageReportResponse {
   }
 }
 
+export interface UsageEstimateCostParams {
+  /**
+   * Body param: Customer id
+   */
+  customerId: string;
+
+  /**
+   * Body param: Feature id
+   */
+  featureId: string;
+
+  /**
+   * Body param: The value to report for usage
+   */
+  value: number;
+
+  /**
+   * Body param: Additional dimensions for the usage report
+   */
+  dimensions?: { [key: string]: string | number | boolean };
+
+  /**
+   * Body param: Resource id
+   */
+  resourceId?: string | null;
+
+  /**
+   * Body param: The method by which the usage value should be updated
+   */
+  updateBehavior?: 'DELTA' | 'SET';
+
+  /**
+   * 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 UsageHistoryParams {
   /**
    * Path param: Customer id
@@ -371,8 +530,10 @@ export namespace UsageReportParams {
 
 export declare namespace Usage {
   export {
+    type UsageEstimateCostResponse as UsageEstimateCostResponse,
     type UsageHistoryResponse as UsageHistoryResponse,
     type UsageReportResponse as UsageReportResponse,
+    type UsageEstimateCostParams as UsageEstimateCostParams,
     type UsageHistoryParams as UsageHistoryParams,
     type UsageReportParams as UsageReportParams,
   };

package/src/resources/v1/v1.ts

@@ -42,6 +42,8 @@ import {
 import * as UsageAPI from './usage';
 import {
   Usage,
+  UsageEstimateCostParams,
+  UsageEstimateCostResponse,
   UsageHistoryParams,
   UsageHistoryResponse,
   UsageReportParams,
@@ -102,7 +104,13 @@ import {
   Customers,
 } from './customers/customers';
 import * as EventsAPI from './events/events';
-import { EventReportParams, EventReportResponse, Events } from './events/events';
+import {
+  EventEstimateCostParams,
+  EventEstimateCostResponse,
+  EventReportParams,
+  EventReportResponse,
+  Events,
+} from './events/events';
 import * as PlansAPI from './plans/plans';
 import {
   Plan,
@@ -229,7 +237,9 @@ export declare namespace V1 {
 
   export {
     Events as Events,
+    type EventEstimateCostResponse as EventEstimateCostResponse,
     type EventReportResponse as EventReportResponse,
+    type EventEstimateCostParams as EventEstimateCostParams,
     type EventReportParams as EventReportParams,
   };
 
@@ -302,8 +312,10 @@ export declare namespace V1 {
 
   export {
     Usage as Usage,
+    type UsageEstimateCostResponse as UsageEstimateCostResponse,
     type UsageHistoryResponse as UsageHistoryResponse,
     type UsageReportResponse as UsageReportResponse,
+    type UsageEstimateCostParams as UsageEstimateCostParams,
     type UsageHistoryParams as UsageHistoryParams,
     type UsageReportParams as UsageReportParams,
   };

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.1.0-beta.40'; // x-release-please-version
+export const VERSION = '0.1.0-beta.42'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.0-beta.40";
+export declare const VERSION = "0.1.0-beta.42";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.0-beta.40";
+export declare const VERSION = "0.1.0-beta.42";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.1.0-beta.40'; // x-release-please-version
+exports.VERSION = '0.1.0-beta.42'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.1.0-beta.40'; // x-release-please-version
+export const VERSION = '0.1.0-beta.42'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map