@stigg/typescript 0.1.0-beta.61 → 0.1.0-beta.62

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

@@ -33,6 +33,8 @@ import {
   GrantVoidParams,
   Grants,
 } from './grants';
+import * as ReservationsAPI from './reservations';
+import { ReservationReleaseParams, ReservationReleaseResponse, Reservations } from './reservations';
 import { APIPromise } from '../../../core/api-promise';
 import { MyCursorIDPage, type MyCursorIDPageParams, PagePromise } from '../../../core/pagination';
 import { buildHeaders } from '../../../internal/headers';
@@ -44,6 +46,7 @@ export class Credits extends APIResource {
     this._client,
   );
   consumption: ConsumptionAPI.Consumption = new ConsumptionAPI.Consumption(this._client);
+  reservations: ReservationsAPI.Reservations = new ReservationsAPI.Reservations(this._client);
 
   /**
    * Retrieves the automatic recharge configuration for a customer and currency.
@@ -347,10 +350,17 @@ export namespace CreditGetUsageResponse {
  */
 export interface CreditListLedgerResponse {
   /**
-   * The credit amount for this event
+   * The amount of the ledger event. Reservation events carry their net effect on the
+   * balance: a reserve is negative, and so is a release that consumed more than was
+   * held
    */
   amount: number;
 
+  /**
+   * On a released reservation, the credits consumed from each grant
+   */
+  breakdown: Array<CreditListLedgerResponse.Breakdown> | null;
+
   /**
    * The credit currency ID
    */
@@ -381,13 +391,32 @@ export interface CreditListLedgerResponse {
     | 'CREDITS_VOIDED'
     | 'CREDITS_UPDATED'
     | 'CREDITS_CONSUMPTION_TRANSFER_SOURCE'
-    | 'CREDITS_CONSUMPTION_TRANSFER_TARGET';
+    | 'CREDITS_CONSUMPTION_TRANSFER_TARGET'
+    | 'CREDITS_RESERVED'
+    | 'CREDITS_RESERVATION_RELEASED'
+    | 'CREDITS_RESERVATION_EXPIRED';
 
   /**
    * The feature ID associated with this event
    */
   featureId: string | null;
 
+  /**
+   * On a released reservation, the held amount returned to the balance before
+   * consumed credits are deducted
+   */
+  holdReturnedAmount: number | null;
+
+  /**
+   * The metadata sent with the credit reservation
+   */
+  metadata: { [key: string]: string } | null;
+
+  /**
+   * The credit reservation this event belongs to
+   */
+  reservationId: string | null;
+
   /**
    * The resource ID this event is scoped to
    */
@@ -399,6 +428,72 @@ export interface CreditListLedgerResponse {
   timestamp: string;
 }
 
+export namespace CreditListLedgerResponse {
+  export interface Breakdown {
+    /**
+     * The amount of the ledger event. Reservation events carry their net effect on the
+     * balance: a reserve is negative, and so is a release that consumed more than was
+     * held
+     */
+    amount: number;
+
+    /**
+     * The credit currency ID
+     */
+    creditCurrencyId: string;
+
+    /**
+     * The credit grant ID associated with this event
+     */
+    creditGrantId: string;
+
+    /**
+     * The customer ID this event belongs to
+     */
+    customerId: string;
+
+    /**
+     * The unique event identifier
+     */
+    eventId: string | null;
+
+    /**
+     * The type of credit event
+     */
+    eventType:
+      | 'CREDITS_GRANTED'
+      | 'CREDITS_EXPIRED'
+      | 'CREDITS_CONSUMED'
+      | 'CREDITS_VOIDED'
+      | 'CREDITS_UPDATED'
+      | 'CREDITS_CONSUMPTION_TRANSFER_SOURCE'
+      | 'CREDITS_CONSUMPTION_TRANSFER_TARGET'
+      | 'CREDITS_RESERVED'
+      | 'CREDITS_RESERVATION_RELEASED'
+      | 'CREDITS_RESERVATION_EXPIRED';
+
+    /**
+     * The feature ID associated with this event
+     */
+    featureId: string | null;
+
+    /**
+     * The credit reservation this event belongs to
+     */
+    reservationId: string | null;
+
+    /**
+     * The resource ID this event is scoped to
+     */
+    resourceId: string | null;
+
+    /**
+     * The timestamp when the event occurred
+     */
+    timestamp: string;
+  }
+}
+
 export interface CreditGetAutoRechargeParams {
   /**
    * Query param: Filter by currency ID (required)
@@ -511,6 +606,11 @@ export interface CreditListLedgerParams extends MyCursorIDPageParams {
    */
   eventType?: string;
 
+  /**
+   * Query param: Filter by credit reservation ID
+   */
+  reservationId?: string;
+
   /**
    * Query param: Filter by resource ID
    */
@@ -533,6 +633,7 @@ export interface CreditListLedgerParams extends MyCursorIDPageParams {
 Credits.Grants = Grants;
 Credits.CustomCurrencies = CustomCurrencies;
 Credits.Consumption = Consumption;
+Credits.Reservations = Reservations;
 
 export declare namespace Credits {
   export {
@@ -576,4 +677,10 @@ export declare namespace Credits {
     type ConsumptionConsumeParams as ConsumptionConsumeParams,
     type ConsumptionConsumeAsyncParams as ConsumptionConsumeAsyncParams,
   };
+
+  export {
+    Reservations as Reservations,
+    type ReservationReleaseResponse as ReservationReleaseResponse,
+    type ReservationReleaseParams as ReservationReleaseParams,
+  };
 }

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

@@ -39,3 +39,4 @@ export {
   type GrantVoidParams,
   type GrantListResponsesMyCursorIDPage,
 } from './grants';
+export { Reservations, type ReservationReleaseResponse, type ReservationReleaseParams } from './reservations';

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

@@ -0,0 +1,172 @@
+// 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';
+import { path } from '../../../internal/utils/path';
+
+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.
+   */
+  release(
+    reservationID: string,
+    params: ReservationReleaseParams,
+    options?: RequestOptions,
+  ): APIPromise<ReservationReleaseResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
+    return this._client.post(path`/api/v1/credits/reservations/${reservationID}/release`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+/**
+ * Response object
+ */
+export interface ReservationReleaseResponse {
+  /**
+   * Result of releasing a credit reservation
+   */
+  data: ReservationReleaseResponse.Data;
+}
+
+export namespace ReservationReleaseResponse {
+  /**
+   * Result of releasing a credit reservation
+   */
+  export interface Data {
+    /**
+     * The optimistic credit balance after the release
+     */
+    credit: Data.Credit | null;
+
+    /**
+     * The released reservation
+     */
+    reservation: Data.Reservation;
+  }
+
+  export namespace Data {
+    /**
+     * The optimistic credit balance after the release
+     */
+    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;
+    }
+
+    /**
+     * The released reservation
+     */
+    export interface Reservation {
+      /**
+       * The client-provided reservation ID.
+       */
+      id: string;
+
+      /**
+       * The amount of credits held.
+       */
+      amount: number;
+
+      /**
+       * The amount consumed at release
+       */
+      consumedAmount: number | null;
+
+      /**
+       * When the reservation expires. Unreleased credits return to the balance at this
+       * time.
+       */
+      expiresAt: string;
+
+      /**
+       * The status of the reservation.
+       */
+      status: 'ACTIVE' | 'RELEASED';
+    }
+  }
+}
+
+export interface ReservationReleaseParams {
+  /**
+   * Body param: The amount of credits to consume at release. Up to the reserved
+   * amount is charged to the credits that backed the reservation; the rest returns
+   * to the balance, and any amount above the reservation is consumed normally.
+   */
+  consumedAmount: number;
+
+  /**
+   * Body param: The credit currency of the reservation
+   */
+  currencyId: string;
+
+  /**
+   * Body param: The customer the reservation was made for
+   */
+  customerId: string;
+
+  /**
+   * Body param: The resource the reservation was made for, if any
+   */
+  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 declare namespace Reservations {
+  export {
+    type ReservationReleaseResponse as ReservationReleaseResponse,
+    type ReservationReleaseParams as ReservationReleaseParams,
+  };
+}

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

@@ -3294,6 +3294,36 @@ export interface CustomerCheckEntitlementParams {
    */
   requestedValues?: Array<string>;
 
+  /**
+   * Query param: When the reservation expires (ISO 8601, at most 24 hours ahead).
+   * Mutually exclusive with `reservationTtlSeconds`.
+   */
+  reservationExpiresAt?: string;
+
+  /**
+   * Query param: Client-provided reservation ID, required with `reserveAmount`.
+   * Retry with the same ID to get the same result; reuse with different parameters
+   * is a conflict.
+   */
+  reservationId?: string;
+
+  /**
+   * Query param: JSON-encoded object of string values to attach to the reservation.
+   */
+  reservationMetadata?: string;
+
+  /**
+   * Query param: How long the reservation holds the credits, in seconds (1–86400,
+   * default 3600). Mutually exclusive with `reservationExpiresAt`.
+   */
+  reservationTtlSeconds?: number;
+
+  /**
+   * Query param: Credits to reserve (credit entitlements only). The check is decided
+   * and the credits held atomically; `requestedUsage` is ignored.
+   */
+  reserveAmount?: number;
+
   /**
    * Query param: Resource ID to scope the entitlement check to a specific resource
    */

package/src/resources/v1/plans/plans.ts

@@ -2692,7 +2692,7 @@ export namespace PlanUpdateParams {
       featureId?: string;
 
       /**
-       * Maximum number of units (max 999999)
+       * Maximum number of units
        */
       maxUnitQuantity?: number;
 

package/src/resources/v1/usage.ts

@@ -391,10 +391,10 @@ export interface UsageEstimateParams {
   featureId: string;
 
   /**
-   * Body param: The value to report for usage. Must be a whole number — the REST API
-   * does not accept fractional (float) usage values; scale up (e.g. report cents
-   * instead of dollars, or milliseconds instead of seconds) if you need sub-unit
-   * precision.
+   * Body param: The value to report for usage. Fractional values are accepted and
+   * rounded half away from zero to 5 decimal places. A value with a fractional part
+   * must have an absolute value below 34,359,738,368 (2^35); whole numbers are
+   * accepted up to ±9,007,199,254,740,991.
    */
   value: number;
 
@@ -511,9 +511,10 @@ export namespace UsageReportParams {
     featureId: string;
 
     /**
-     * The value to report for usage. Must be a whole number — the REST API does not
-     * accept fractional (float) usage values; scale up (e.g. report cents instead of
-     * dollars, or milliseconds instead of seconds) if you need sub-unit precision.
+     * The value to report for usage. Fractional values are accepted and rounded half
+     * away from zero to 5 decimal places. A value with a fractional part must have an
+     * absolute value below 34,359,738,368 (2^35); whole numbers are accepted up to
+     * ±9,007,199,254,740,991.
      */
     value: number;
 

package/src/resources/v2/usage.ts

@@ -299,9 +299,10 @@ export namespace UsageReportParams {
     featureId: string;
 
     /**
-     * The value to report for usage. Must be a whole number — the REST API does not
-     * accept fractional (float) usage values; scale up (e.g. report cents instead of
-     * dollars, or milliseconds instead of seconds) if you need sub-unit precision.
+     * The value to report for usage. Fractional values are accepted and rounded half
+     * away from zero to 5 decimal places. A value with a fractional part must have an
+     * absolute value below 34,359,738,368 (2^35); whole numbers are accepted up to
+     * ±9,007,199,254,740,991.
      */
     value: number;
 

package/src/version.ts

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

package/version.d.mts

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

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.0-beta.61";
+export declare const VERSION = "0.1.0-beta.62";
 //# 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.61'; // x-release-please-version
+exports.VERSION = '0.1.0-beta.62'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

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