@paid-ai/paid-node 1.8.0 → 2.0.0

package/dist/esm/api/resources/signals/types/index.mjs

@@ -0,0 +1,2 @@
+export * from "./GetSignalSummaryRequestGroupBy.mjs";
+export * from "./GetSignalSummaryRequestInterval.mjs";

package/dist/esm/api/resources/valueMetrics/client/Client.d.mts

@@ -25,7 +25,7 @@ export declare class ValueMetrics {
     listValueMetrics(request?: Paid.ListValueMetricsRequest, requestOptions?: ValueMetrics.RequestOptions): core.HttpResponsePromise<Paid.ValueMetricListResponse>;
     private __listValueMetrics;
     /**
-     * Adds one value metric — its unit, formula, signal binding and optional monetary conversion — to the value model. The signal must already exist: an event name your organization has sent, or one referenced by usage pricing on an active product. Publishes a new value model version and recalculates delivered value for historical signals.
+     * Adds one value metric — its unit, formula, signal binding and optional monetary conversion — to the value model. The signal must already exist: an event name your organization has sent, or one referenced by usage pricing on an active product. Publishes a new value model version that values NEW signals going forward; it does NOT recalculate historical delivered value. Re-rating history is a separate, explicit action (POST /api/v2/value-models/backfill).
      *
      * @param {Paid.CreateValueMetricRequest} request
      * @param {ValueMetrics.RequestOptions} requestOptions - Request-specific configuration.

package/dist/esm/api/resources/valueMetrics/client/Client.mjs

@@ -102,7 +102,7 @@ export class ValueMetrics {
         });
     }
     /**
-     * Adds one value metric — its unit, formula, signal binding and optional monetary conversion — to the value model. The signal must already exist: an event name your organization has sent, or one referenced by usage pricing on an active product. Publishes a new value model version and recalculates delivered value for historical signals.
+     * Adds one value metric — its unit, formula, signal binding and optional monetary conversion — to the value model. The signal must already exist: an event name your organization has sent, or one referenced by usage pricing on an active product. Publishes a new value model version that values NEW signals going forward; it does NOT recalculate historical delivered value. Re-rating history is a separate, explicit action (POST /api/v2/value-models/backfill).
      *
      * @param {Paid.CreateValueMetricRequest} request
      * @param {ValueMetrics.RequestOptions} requestOptions - Request-specific configuration.

package/dist/esm/api/resources/valueModels/client/Client.d.mts

@@ -24,12 +24,13 @@ export declare class ValueModels {
     getCurrentValueModel(requestOptions?: ValueModels.RequestOptions): core.HttpResponsePromise<Paid.ValueModelDetail>;
     private __getCurrentValueModel;
     /**
-     * Uploads a new value model version. Validates the content, creates a new version, archives the previous active version, syncs to ClickHouse, and triggers a backfill of all historical signals.
+     * Uploads a new value model version. Validates the content, creates a new version, archives the previous active version, and syncs to ClickHouse. This updates how value is calculated going forward — new signals are valued under the new model. It does NOT re-rate historical signals; run POST /api/v2/value-models/backfill to re-rate history as a separate, explicit action. Any unpublished draft saved in the Paid app is discarded. Send expectedActiveVersion to get a 409 instead of overwriting a version published since you read it.
      *
      * @param {Paid.ValueModelUploadRequest} request
      * @param {ValueModels.RequestOptions} requestOptions - Request-specific configuration.
      *
      * @throws {@link Paid.BadRequestError}
+     * @throws {@link Paid.ConflictError}
      * @throws {@link Paid.InternalServerError}
      *
      * @example
@@ -101,12 +102,13 @@ export declare class ValueModels {
     getValueModelVersion(request: Paid.GetValueModelVersionRequest, requestOptions?: ValueModels.RequestOptions): core.HttpResponsePromise<Paid.ValueModelDetail>;
     private __getValueModelVersion;
     /**
-     * Manually triggers a recalculation of all ClickHouse rows against the current value model.
+     * Manually triggers a recalculation of all ClickHouse rows against the current value model. Returns 422 when the backfill would scan more signals than the ceiling allows — that is deterministic, so retrying without narrowing the scope will not help.
      *
      * @param {Paid.RefreshValueModelBackfillRequest} request
      * @param {ValueModels.RequestOptions} requestOptions - Request-specific configuration.
      *
      * @throws {@link Paid.NotFoundError}
+     * @throws {@link Paid.UnprocessableEntityError}
      * @throws {@link Paid.InternalServerError}
      *
      * @example

package/dist/esm/api/resources/valueModels/client/Client.mjs

@@ -79,12 +79,13 @@ export class ValueModels {
         });
     }
     /**
-     * Uploads a new value model version. Validates the content, creates a new version, archives the previous active version, syncs to ClickHouse, and triggers a backfill of all historical signals.
+     * Uploads a new value model version. Validates the content, creates a new version, archives the previous active version, and syncs to ClickHouse. This updates how value is calculated going forward — new signals are valued under the new model. It does NOT re-rate historical signals; run POST /api/v2/value-models/backfill to re-rate history as a separate, explicit action. Any unpublished draft saved in the Paid app is discarded. Send expectedActiveVersion to get a 409 instead of overwriting a version published since you read it.
      *
      * @param {Paid.ValueModelUploadRequest} request
      * @param {ValueModels.RequestOptions} requestOptions - Request-specific configuration.
      *
      * @throws {@link Paid.BadRequestError}
+     * @throws {@link Paid.ConflictError}
      * @throws {@link Paid.InternalServerError}
      *
      * @example
@@ -150,6 +151,8 @@ export class ValueModels {
                 switch (_response.error.statusCode) {
                     case 400:
                         throw new Paid.BadRequestError(_response.error.body, _response.rawResponse);
+                    case 409:
+                        throw new Paid.ConflictError(_response.error.body, _response.rawResponse);
                     case 500:
                         throw new Paid.InternalServerError(_response.error.body, _response.rawResponse);
                     default:
@@ -310,12 +313,13 @@ export class ValueModels {
         });
     }
     /**
-     * Manually triggers a recalculation of all ClickHouse rows against the current value model.
+     * Manually triggers a recalculation of all ClickHouse rows against the current value model. Returns 422 when the backfill would scan more signals than the ceiling allows — that is deterministic, so retrying without narrowing the scope will not help.
      *
      * @param {Paid.RefreshValueModelBackfillRequest} request
      * @param {ValueModels.RequestOptions} requestOptions - Request-specific configuration.
      *
      * @throws {@link Paid.NotFoundError}
+     * @throws {@link Paid.UnprocessableEntityError}
      * @throws {@link Paid.InternalServerError}
      *
      * @example
@@ -347,6 +351,8 @@ export class ValueModels {
                 switch (_response.error.statusCode) {
                     case 404:
                         throw new Paid.NotFoundError(_response.error.body, _response.rawResponse);
+                    case 422:
+                        throw new Paid.UnprocessableEntityError(_response.error.body, _response.rawResponse);
                     case 500:
                         throw new Paid.InternalServerError(_response.error.body, _response.rawResponse);
                     default:

package/dist/esm/api/resources/valueModels/client/requests/ValueModelUploadRequest.d.mts

@@ -41,4 +41,6 @@ export interface ValueModelUploadRequest {
     content: Paid.ValueModelContent;
     effectiveFrom?: string;
     effectiveTo?: string;
+    /** Optimistic concurrency guard: the active version this upload is based on. When supplied and it does not match the live active version, the upload fails with 409 instead of overwriting a concurrent change. */
+    expectedActiveVersion?: number;
 }

package/dist/esm/api/resources/valueReceipts/client/Client.d.mts

@@ -44,7 +44,7 @@ export declare class ValueReceipts {
     createValueReceipt(request: Paid.SyncValueReceiptRequest, requestOptions?: ValueReceipts.RequestOptions): core.HttpResponsePromise<Paid.ValueReceiptSyncResponse>;
     private __createValueReceipt;
     /**
-     * Deprecated — use POST /value-receipts. Returns the receipt this customer already has for the date range (200), refreshed with current data, and creates one only if there is none (201), so calling twice does not give the customer two receipts.
+     * Deprecated — use POST /value-receipts. Returns the receipt this customer already has for the date range (200), and creates one only if there is none (201), so calling twice does not give the customer two receipts. A receipt does not change after it is created, so a repeated call reports the same figures. Create a new receipt to report the period again with newer data.
      *
      * @param {Paid.SyncValueReceiptRequest} request
      * @param {ValueReceipts.RequestOptions} requestOptions - Request-specific configuration.
@@ -81,7 +81,7 @@ export declare class ValueReceipts {
     getValueReceiptById(request: Paid.GetValueReceiptByIdRequest, requestOptions?: ValueReceipts.RequestOptions): core.HttpResponsePromise<Paid.ValueReceiptDetail>;
     private __getValueReceiptById;
     /**
-     * Re-populate an existing draft value receipt with current data inline. Returns the slim sync response. Sealed VRs cannot be refreshed.
+     * Deprecated. A value receipt is immutable from creation, so it cannot be re-populated. A receipt you own answers 409, and one that does not exist or belongs to another organization answers 404. To get current data, create a new receipt for the period with `POST /value-receipts`.
      *
      * @param {Paid.RefreshValueReceiptRequest} request
      * @param {ValueReceipts.RequestOptions} requestOptions - Request-specific configuration.
@@ -100,7 +100,7 @@ export declare class ValueReceipts {
     refreshValueReceipt(request: Paid.RefreshValueReceiptRequest, requestOptions?: ValueReceipts.RequestOptions): core.HttpResponsePromise<Paid.ValueReceiptSyncResponse>;
     private __refreshValueReceipt;
     /**
-     * Transition a draft value receipt to sealed (posted) status. Sealed VRs are immutable — they cannot be updated or re-populated.
+     * Deprecated. A value receipt is immutable from creation, so it is already sealed and this call has nothing to do. It answers 200 for any receipt the organization owns.
      *
      * @param {Paid.SealValueReceiptRequest} request
      * @param {ValueReceipts.RequestOptions} requestOptions - Request-specific configuration.
@@ -135,7 +135,7 @@ export declare class ValueReceipts {
     archiveValueReceipt(request: Paid.ArchiveValueReceiptRequest, requestOptions?: ValueReceipts.RequestOptions): core.HttpResponsePromise<Paid.SuccessResponse>;
     private __archiveValueReceipt;
     /**
-     * Restore an archived value receipt.
+     * Restore an archived value receipt. A receipt with no content, or one that failed to build, stays archived and answers 409. So does one whose period another value receipt now covers.
      *
      * @param {Paid.UnarchiveValueReceiptRequest} request
      * @param {ValueReceipts.RequestOptions} requestOptions - Request-specific configuration.
@@ -153,7 +153,7 @@ export declare class ValueReceipts {
     unarchiveValueReceipt(request: Paid.UnarchiveValueReceiptRequest, requestOptions?: ValueReceipts.RequestOptions): core.HttpResponsePromise<Paid.SuccessResponse>;
     private __unarchiveValueReceipt;
     /**
-     * Make a value receipt publicly accessible via URL. An archived receipt is rejected with 409 — unarchive it first.
+     * Make a value receipt publicly accessible via URL. An archived receipt is rejected with 409 — unarchive it first. So is one with no content, which has nothing to show.
      *
      * @param {Paid.PublishValueReceiptBody} request
      * @param {ValueReceipts.RequestOptions} requestOptions - Request-specific configuration.

package/dist/esm/api/resources/valueReceipts/client/Client.mjs

@@ -188,7 +188,7 @@ export class ValueReceipts {
         });
     }
     /**
-     * Deprecated — use POST /value-receipts. Returns the receipt this customer already has for the date range (200), refreshed with current data, and creates one only if there is none (201), so calling twice does not give the customer two receipts.
+     * Deprecated — use POST /value-receipts. Returns the receipt this customer already has for the date range (200), and creates one only if there is none (201), so calling twice does not give the customer two receipts. A receipt does not change after it is created, so a repeated call reports the same figures. Create a new receipt to report the period again with newer data.
      *
      * @param {Paid.SyncValueReceiptRequest} request
      * @param {ValueReceipts.RequestOptions} requestOptions - Request-specific configuration.
@@ -333,7 +333,7 @@ export class ValueReceipts {
         });
     }
     /**
-     * Re-populate an existing draft value receipt with current data inline. Returns the slim sync response. Sealed VRs cannot be refreshed.
+     * Deprecated. A value receipt is immutable from creation, so it cannot be re-populated. A receipt you own answers 409, and one that does not exist or belongs to another organization answers 404. To get current data, create a new receipt for the period with `POST /value-receipts`.
      *
      * @param {Paid.RefreshValueReceiptRequest} request
      * @param {ValueReceipts.RequestOptions} requestOptions - Request-specific configuration.
@@ -410,7 +410,7 @@ export class ValueReceipts {
         });
     }
     /**
-     * Transition a draft value receipt to sealed (posted) status. Sealed VRs are immutable — they cannot be updated or re-populated.
+     * Deprecated. A value receipt is immutable from creation, so it is already sealed and this call has nothing to do. It answers 200 for any receipt the organization owns.
      *
      * @param {Paid.SealValueReceiptRequest} request
      * @param {ValueReceipts.RequestOptions} requestOptions - Request-specific configuration.
@@ -555,7 +555,7 @@ export class ValueReceipts {
         });
     }
     /**
-     * Restore an archived value receipt.
+     * Restore an archived value receipt. A receipt with no content, or one that failed to build, stays archived and answers 409. So does one whose period another value receipt now covers.
      *
      * @param {Paid.UnarchiveValueReceiptRequest} request
      * @param {ValueReceipts.RequestOptions} requestOptions - Request-specific configuration.
@@ -629,7 +629,7 @@ export class ValueReceipts {
         });
     }
     /**
-     * Make a value receipt publicly accessible via URL. An archived receipt is rejected with 409 — unarchive it first.
+     * Make a value receipt publicly accessible via URL. An archived receipt is rejected with 409 — unarchive it first. So is one with no content, which has nothing to show.
      *
      * @param {Paid.PublishValueReceiptBody} request
      * @param {ValueReceipts.RequestOptions} requestOptions - Request-specific configuration.

package/dist/esm/api/resources/valueReceipts/client/requests/PublishValueReceiptBody.d.mts

@@ -6,5 +6,6 @@
  */
 export interface PublishValueReceiptBody {
     id: string;
+    /** When the public link stops working. Must be in the future, or the request fails with 409. Omit or set null for a link that does not expire. */
     publishExpiresAt?: string | null;
 }

package/dist/esm/api/resources/webhooks/client/Client.d.mts

@@ -36,7 +36,7 @@ export declare class Webhooks {
      *
      * @example
      *     await client.webhooks.updateWebhook({
-     *         webhookName: "billing-invoice-created"
+     *         webhookName: "billing-invoice-paid"
      *     })
      */
     updateWebhook(request: Paid.UpdateWebhookRequest, requestOptions?: Webhooks.RequestOptions): core.HttpResponsePromise<Paid.WebhookUpdateResponse>;
@@ -54,7 +54,7 @@ export declare class Webhooks {
      *
      * @example
      *     await client.webhooks.testWebhook({
-     *         webhookName: "billing-invoice-created"
+     *         webhookName: "billing-invoice-paid"
      *     })
      */
     testWebhook(request: Paid.TestWebhookRequest, requestOptions?: Webhooks.RequestOptions): core.HttpResponsePromise<Paid.WebhookTestResponse>;

package/dist/esm/api/resources/webhooks/client/Client.mjs

@@ -102,7 +102,7 @@ export class Webhooks {
      *
      * @example
      *     await client.webhooks.updateWebhook({
-     *         webhookName: "billing-invoice-created"
+     *         webhookName: "billing-invoice-paid"
      *     })
      */
     updateWebhook(request, requestOptions) {
@@ -176,7 +176,7 @@ export class Webhooks {
      *
      * @example
      *     await client.webhooks.testWebhook({
-     *         webhookName: "billing-invoice-created"
+     *         webhookName: "billing-invoice-paid"
      *     })
      */
     testWebhook(request, requestOptions) {

package/dist/esm/api/resources/webhooks/client/requests/TestWebhookRequest.d.mts

@@ -2,7 +2,7 @@ import type * as Paid from "../../../../index.mjs";
 /**
  * @example
  *     {
- *         webhookName: "billing-invoice-created"
+ *         webhookName: "billing-invoice-paid"
  *     }
  */
 export interface TestWebhookRequest {

package/dist/esm/api/resources/webhooks/client/requests/UpdateWebhookRequest.d.mts

@@ -2,13 +2,13 @@ import type * as Paid from "../../../../index.mjs";
 /**
  * @example
  *     {
- *         webhookName: "billing-invoice-created"
+ *         webhookName: "billing-invoice-paid"
  *     }
  */
 export interface UpdateWebhookRequest {
     webhookName: Paid.UpdateWebhookRequestWebhookName;
     /** Whether the webhook is enabled for delivery. */
     enabled?: boolean;
-    /** The HTTPS endpoint Paid should deliver this webhook to. Set to null to clear it while disabled. */
+    /** The HTTPS endpoint Paid should deliver this webhook to. It must use HTTPS and a public host: localhost, private networks (10.x, 172.16-31.x, 192.168.x), link-local addresses and .local names are rejected. Set to null to clear it while disabled. */
     url?: string | null;
 }

package/dist/esm/api/resources/webhooks/types/TestWebhookRequestWebhookName.d.mts

@@ -1,5 +1,4 @@
 export declare const TestWebhookRequestWebhookName: {
-    readonly BillingInvoiceCreated: "billing-invoice-created";
     readonly BillingInvoicePaid: "billing-invoice-paid";
     readonly BillingInvoicePosted: "billing-invoice-posted";
     readonly BillingCheckoutCreated: "billing-checkout-created";

package/dist/esm/api/resources/webhooks/types/TestWebhookRequestWebhookName.mjs

@@ -1,6 +1,5 @@
 // This file was auto-generated by Fern from our API Definition.
 export const TestWebhookRequestWebhookName = {
-    BillingInvoiceCreated: "billing-invoice-created",
     BillingInvoicePaid: "billing-invoice-paid",
     BillingInvoicePosted: "billing-invoice-posted",
     BillingCheckoutCreated: "billing-checkout-created",

package/dist/esm/api/resources/webhooks/types/UpdateWebhookRequestWebhookName.d.mts

@@ -1,5 +1,4 @@
 export declare const UpdateWebhookRequestWebhookName: {
-    readonly BillingInvoiceCreated: "billing-invoice-created";
     readonly BillingInvoicePaid: "billing-invoice-paid";
     readonly BillingInvoicePosted: "billing-invoice-posted";
     readonly BillingCheckoutCreated: "billing-checkout-created";

package/dist/esm/api/resources/webhooks/types/UpdateWebhookRequestWebhookName.mjs

@@ -1,6 +1,5 @@
 // This file was auto-generated by Fern from our API Definition.
 export const UpdateWebhookRequestWebhookName = {
-    BillingInvoiceCreated: "billing-invoice-created",
     BillingInvoicePaid: "billing-invoice-paid",
     BillingInvoicePosted: "billing-invoice-posted",
     BillingCheckoutCreated: "billing-checkout-created",

package/dist/esm/api/types/Attribution.d.mts

@@ -1,2 +1,5 @@
 import type * as Paid from "../index.mjs";
+/**
+ * The product this usage is for, by Paid ID or by your external ID. Optional.
+ */
 export type Attribution = Paid.ProductById | Paid.ProductByExternalId;

package/dist/esm/api/types/Checkout.d.mts

@@ -12,6 +12,10 @@ export interface Checkout {
     metadata: Record<string, unknown> | null;
     collectAddress: boolean;
     collectPhone: boolean;
+    /** Heading on the confirmation screen after checkout. Null when the checkout shows the default, "Payment successful". */
+    successTitle: string | null;
+    /** Text under the heading on the confirmation screen. Null when the checkout shows the default, "Thank you for your purchase!". */
+    successMessage: string | null;
     singleUse: boolean;
     allowedCurrencies: string[];
     /** Additional informational pricing cards rendered alongside the plans. */

package/dist/esm/api/types/CheckoutDetails.d.mts

@@ -12,6 +12,10 @@ export interface CheckoutDetails {
     metadata: Record<string, unknown> | null;
     collectAddress: boolean;
     collectPhone: boolean;
+    /** Heading on the confirmation screen after checkout. Null when the checkout shows the default, "Payment successful". */
+    successTitle: string | null;
+    /** Text under the heading on the confirmation screen. Null when the checkout shows the default, "Thank you for your purchase!". */
+    successMessage: string | null;
     singleUse: boolean;
     allowedCurrencies: string[];
     /** Additional informational pricing cards rendered alongside the plans. */

package/dist/esm/api/types/CreateOrderLineAttributeRequest.d.mts

@@ -12,12 +12,15 @@ export declare namespace CreateOrderLineAttributeRequest {
         pricingModel: Pricing.PricingModel;
         billingFrequency?: Pricing.BillingFrequency;
         billingFrequencyCustomMonths?: number;
+        /** When the charge is billed. A usage charge must use arrears, prepaid credits included; to sell credits up front, add a credit benefit to a recurring, seat or one-time charge. */
         billingType?: Pricing.BillingType;
         signalType?: Pricing.SignalType;
         creditsCurrencyId?: string;
         /** Credit amount, exact to at most 6 decimal places. */
         creditCost?: number;
         overageUnitPrice?: number;
+        /** Overage price per credit in the currency's minor units (40 is $0.40 for USD, ¥40 for JPY, 0.040 KWD for KWD), keyed by uppercase ISO 4217 currency code. On an invoice, an entry for the invoice currency on any of the order's pricing or credit benefits beats every overageUnitPrice; overageUnitPrice applies only when no holder has an entry for that currency. Writes keep the two consistent for the primary currency (the organization's default when the product is priced in it, else the product's only pricing currency; an order line's own currency): a map entry for it sets overageUnitPrice, winning when a write sends both, and an overageUnitPrice sent without the map updates an existing entry for it. A write that sends only overageUnitPrice never creates a map. */
+        overageUnitPrices?: Record<string, number | null> | null;
         /** Credit amount, exact to at most 6 decimal places. */
         creditRolloverAmount?: number;
         creditBenefits?: Pricing.CreditBenefits.Item[];
@@ -80,6 +83,7 @@ export declare namespace CreateOrderLineAttributeRequest {
             readonly Custom: "custom";
         };
         type BillingFrequency = (typeof BillingFrequency)[keyof typeof BillingFrequency];
+        /** When the charge is billed. A usage charge must use arrears, prepaid credits included; to sell credits up front, add a credit benefit to a recurring, seat or one-time charge. */
         const BillingType: {
             readonly Advance: "advance";
             readonly Arrears: "arrears";
@@ -98,6 +102,9 @@ export declare namespace CreateOrderLineAttributeRequest {
                 recipient?: Item.Recipient;
                 /** Credit amount, exact to at most 6 decimal places. */
                 amount: number;
+                overageUnitPrice?: number | null;
+                /** Overage price per credit in the currency's minor units (40 is $0.40 for USD, ¥40 for JPY, 0.040 KWD for KWD), keyed by uppercase ISO 4217 currency code. On an invoice, an entry for the invoice currency on any of the order's pricing or credit benefits beats every overageUnitPrice; overageUnitPrice applies only when no holder has an entry for that currency. Writes keep the two consistent for the primary currency (the organization's default when the product is priced in it, else the product's only pricing currency; an order line's own currency): a map entry for it sets overageUnitPrice, winning when a write sends both, and an overageUnitPrice sent without the map updates an existing entry for it. A write that sends only overageUnitPrice never creates a map. */
+                overageUnitPrices?: Record<string, number | null> | null;
                 /** Credit amount, exact to at most 6 decimal places. */
                 rolloverAmount?: number | null;
                 rolloverDuration?: number | null;
@@ -119,6 +126,8 @@ export declare namespace CreateOrderLineAttributeRequest {
                 const AllocationCadence: {
                     readonly Upfront: "upfront";
                     readonly Monthly: "monthly";
+                    readonly Quarterly: "quarterly";
+                    readonly SemiAnnually: "semi_annually";
                 };
                 type AllocationCadence = (typeof AllocationCadence)[keyof typeof AllocationCadence];
                 const CreditGrantTiming: {

package/dist/esm/api/types/CreateOrderLineAttributeRequest.mjs

@@ -37,6 +37,7 @@ export var CreateOrderLineAttributeRequest;
             Annual: "annual",
             Custom: "custom",
         };
+        /** When the charge is billed. A usage charge must use arrears, prepaid credits included; to sell credits up front, add a credit benefit to a recurring, seat or one-time charge. */
         Pricing.BillingType = {
             Advance: "advance",
             Arrears: "arrears",
@@ -60,6 +61,8 @@ export var CreateOrderLineAttributeRequest;
                 Item.AllocationCadence = {
                     Upfront: "upfront",
                     Monthly: "monthly",
+                    Quarterly: "quarterly",
+                    SemiAnnually: "semi_annually",
                 };
                 Item.CreditGrantTiming = {
                     OnPayment: "on_payment",

package/dist/esm/api/types/CreditBenefitInput.d.mts

@@ -1,4 +1,5 @@
 export interface CreditBenefitInput {
+    id?: string;
     creditsCurrencyId: string;
     /** Credit amount, exact to at most 6 decimal places. */
     amount: number;
@@ -7,6 +8,8 @@ export interface CreditBenefitInput {
     allocationCadence?: CreditBenefitInput.AllocationCadence;
     creditGrantTiming?: CreditBenefitInput.CreditGrantTiming | null;
     overageUnitPrice?: number | null;
+    /** Overage price per credit in the currency's minor units (40 is $0.40 for USD, ¥40 for JPY, 0.040 KWD for KWD), keyed by uppercase ISO 4217 currency code. On an invoice, an entry for the invoice currency on any of the order's pricing or credit benefits beats every overageUnitPrice; overageUnitPrice applies only when no holder has an entry for that currency. Writes keep the two consistent for the primary currency (the organization's default when the product is priced in it, else the product's only pricing currency; an order line's own currency): a map entry for it sets overageUnitPrice, winning when a write sends both, and an overageUnitPrice sent without the map updates an existing entry for it. A write that sends only overageUnitPrice never creates a map. */
+    overageUnitPrices?: Record<string, number | null> | null;
     /** Credit amount, exact to at most 6 decimal places. */
     rolloverAmount?: number | null;
     rolloverDuration?: number | null;
@@ -21,6 +24,8 @@ export declare namespace CreditBenefitInput {
     const AllocationCadence: {
         readonly Upfront: "upfront";
         readonly Monthly: "monthly";
+        readonly Quarterly: "quarterly";
+        readonly SemiAnnually: "semi_annually";
     };
     type AllocationCadence = (typeof AllocationCadence)[keyof typeof AllocationCadence];
     const CreditGrantTiming: {

package/dist/esm/api/types/CreditBenefitInput.mjs

@@ -8,6 +8,8 @@ export var CreditBenefitInput;
     CreditBenefitInput.AllocationCadence = {
         Upfront: "upfront",
         Monthly: "monthly",
+        Quarterly: "quarterly",
+        SemiAnnually: "semi_annually",
     };
     CreditBenefitInput.CreditGrantTiming = {
         OnOrderActivation: "on_order_activation",

package/dist/esm/api/types/CreditBenefitOutput.d.mts

@@ -7,6 +7,8 @@ export interface CreditBenefitOutput {
     allocationCadence: string;
     creditGrantTiming?: string | null;
     overageUnitPrice?: number | null;
+    /** Overage price per credit in the currency's minor units (40 is $0.40 for USD, ¥40 for JPY, 0.040 KWD for KWD), keyed by uppercase ISO 4217 currency code. On an invoice, an entry for the invoice currency on any of the order's pricing or credit benefits beats every overageUnitPrice; overageUnitPrice applies only when no holder has an entry for that currency. Writes keep the two consistent for the primary currency (the organization's default when the product is priced in it, else the product's only pricing currency; an order line's own currency): a map entry for it sets overageUnitPrice, winning when a write sends both, and an overageUnitPrice sent without the map updates an existing entry for it. A write that sends only overageUnitPrice never creates a map. */
+    overageUnitPrices?: Record<string, number | null> | null;
     rolloverAmount?: number | null;
     rolloverDuration?: number | null;
     rolloverDurationUnit?: string | null;

package/dist/esm/api/types/CreditGrantCreateRequest.d.mts

@@ -7,4 +7,6 @@ export interface CreditGrantCreateRequest {
     startsAt?: string;
     /** When these credits expire, as an RFC3339 datetime with timezone. Omit or set null for credits that do not expire. */
     expiresAt?: string | null;
+    /** Unique key for this grant within your organization. A retry with the same key and request body returns the original grant with `created: false` instead of granting again. Reusing a key for a different customer or request body returns 409. */
+    idempotencyKey?: string;
 }

package/dist/esm/api/types/CreditTransaction.d.mts

@@ -12,7 +12,7 @@ export interface CreditTransaction {
     originCode: string;
     /** Usage event that produced this spend. Null for grants and non-signal spends. */
     eventName: string | null;
-    /** ID of the usage signal that produced this spend, resolvable via `GET /api/v2/signals/{id}` (including the signal's data payload). Null for grants and non-signal spends. */
+    /** ID of the usage signal that produced this spend, resolvable via `GET /api/v2/signals/{id}`, or in bulk for a whole page via `POST /api/v2/signals/lookup` (both include the signal's data payload). Null for grants and non-signal spends. */
     signalId: string | null;
     /** Paid order display ID this transaction is linked to, if any. */
     orderId: string | null;

package/dist/esm/api/types/CreditTransactionSummaryBucket.d.mts

@@ -0,0 +1,25 @@
+export interface CreditTransactionSummaryBucket {
+    /** Start of the period bucket (inclusive), UTC. For the first bucket this is `createdAtFrom` when the window starts inside the period. */
+    periodStart: string;
+    /** Last instant of the period bucket (inclusive), UTC; for the last bucket this is `createdAtTo` (or the request time) when the window ends inside the period. To fetch exactly this bucket's transactions, call the transaction list with `createdAtFrom`/`createdAtTo` set to `periodStart`/`periodEnd`, `creditCurrencyKey` set to this bucket's currency key, `eventName` set to `groupKey`, and the same `type` and other filters. A null `groupKey` has no event to filter on; select those rows client-side by their null `eventName`. */
+    periodEnd: string;
+    /** Value of the `groupBy` dimension. For `eventName`, the usage event that produced the spends; null for transactions with no event (grants, invoice-void clawbacks, manual adjustments). */
+    groupKey: string | null;
+    /** Credits are counted per currency and never summed across currencies. */
+    creditCurrency: CreditTransactionSummaryBucket.CreditCurrency;
+    /** Net credits in this bucket as an exact decimal string, in the type's natural direction: for `spend`, the credits consumed (positive; negative only when the bucket holds solely reversals); for `grant` and `pendingGrant`, the credits granted. Exact at any magnitude and at the full 6 decimal places. Summing the transaction list's `amount` over the same filters and period gives the same value (negated for `spend`). */
+    credits: string;
+    /** Number of ledger transactions in this bucket. */
+    transactionCount: number;
+}
+export declare namespace CreditTransactionSummaryBucket {
+    /**
+     * Credits are counted per currency and never summed across currencies.
+     */
+    interface CreditCurrency {
+        /** Stable machine-readable key for this credit currency. */
+        key: string;
+        /** Human-readable name for this credit currency. */
+        name: string;
+    }
+}

package/dist/esm/api/types/CreditTransactionSummaryBucket.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/types/CreditTransactionSummaryResponse.d.mts

@@ -0,0 +1,32 @@
+import type * as Paid from "../index.mjs";
+export interface CreditTransactionSummaryResponse {
+    /** Ledger type these buckets summarize. */
+    type: CreditTransactionSummaryResponse.Type;
+    /** Dimension the buckets are grouped by. */
+    groupBy: CreditTransactionSummaryResponse.GroupBy;
+    /** Period bucket size. */
+    interval: CreditTransactionSummaryResponse.Interval;
+    /** Buckets ordered by period, then credit currency key, then group key (null last). Periods with no transactions are omitted. */
+    data: Paid.CreditTransactionSummaryBucket[];
+}
+export declare namespace CreditTransactionSummaryResponse {
+    /** Ledger type these buckets summarize. */
+    const Type: {
+        readonly Grant: "grant";
+        readonly Spend: "spend";
+        readonly PendingGrant: "pendingGrant";
+    };
+    type Type = (typeof Type)[keyof typeof Type];
+    /** Dimension the buckets are grouped by. */
+    const GroupBy: {
+        readonly EventName: "eventName";
+    };
+    type GroupBy = (typeof GroupBy)[keyof typeof GroupBy];
+    /** Period bucket size. */
+    const Interval: {
+        readonly Day: "day";
+        readonly Week: "week";
+        readonly Month: "month";
+    };
+    type Interval = (typeof Interval)[keyof typeof Interval];
+}

package/dist/esm/api/types/CreditTransactionSummaryResponse.mjs

@@ -0,0 +1,20 @@
+// This file was auto-generated by Fern from our API Definition.
+export var CreditTransactionSummaryResponse;
+(function (CreditTransactionSummaryResponse) {
+    /** Ledger type these buckets summarize. */
+    CreditTransactionSummaryResponse.Type = {
+        Grant: "grant",
+        Spend: "spend",
+        PendingGrant: "pendingGrant",
+    };
+    /** Dimension the buckets are grouped by. */
+    CreditTransactionSummaryResponse.GroupBy = {
+        EventName: "eventName",
+    };
+    /** Period bucket size. */
+    CreditTransactionSummaryResponse.Interval = {
+        Day: "day",
+        Week: "week",
+        Month: "month",
+    };
+})(CreditTransactionSummaryResponse || (CreditTransactionSummaryResponse = {}));

package/dist/esm/api/types/CustomView.d.mts

@@ -1,4 +1,8 @@
 export interface CustomView {
+    /** Enable customer unit navigation for a customer-scoped view. Setting true requires customer hierarchies to be enabled for your organization, and every query must support unit selection. Existing views default to false. */
+    hierarchyEnabled?: boolean;
+    /** Send the customer's unit caps to the render bundle as `context.caps`. Needs `hierarchyEnabled` on a customer-scoped view. Turn it on only for views that draw cap usage: each load then reads cap usage from billing. Caps are spend policy, so an API key also needs `read:billing` to receive them in the data (they are left out otherwise) or to mint this view's embed token. Defaults to false. */
+    capsEnabled?: boolean;
     /** Stable public identifier used in preview/embed URLs. */
     displayId: string;
     name: string;

package/dist/esm/api/types/CustomViewAuthoringDetail.d.mts

@@ -1,5 +1,9 @@
 import type * as Paid from "../index.mjs";
 export interface CustomViewAuthoringDetail {
+    /** Enable customer unit navigation for a customer-scoped view. Setting true requires customer hierarchies to be enabled for your organization, and every query must support unit selection. Existing views default to false. */
+    hierarchyEnabled?: boolean;
+    /** Send the customer's unit caps to the render bundle as `context.caps`. Needs `hierarchyEnabled` on a customer-scoped view. Turn it on only for views that draw cap usage: each load then reads cap usage from billing. Caps are spend policy, so an API key also needs `read:billing` to receive them in the data (they are left out otherwise) or to mint this view's embed token. Defaults to false. */
+    capsEnabled?: boolean;
     displayId: string;
     name: string;
     description: string | null;

package/dist/esm/api/types/CustomViewContextCap.d.mts

@@ -0,0 +1,27 @@
+import type * as Paid from "../index.mjs";
+/**
+ * A cap in force on one of the customer's units, as the customer unit cap read returns it. `used` covers the unit and every unit under it.
+ */
+export interface CustomViewContextCap {
+    /** The cap, in credits of the currency. JSON number; exact within ±2^53. */
+    amount: number;
+    /** Monthly UTC periods, with boundaries defined by `schedule`. */
+    frequency: CustomViewContextCap.Frequency;
+    schedule: Paid.CustomerUnitCapSchedule;
+    /** The capped unit's externalId, as in `units`. */
+    externalId: string;
+    /** The credits currency this cap limits. */
+    creditsCurrencyId: string;
+    /** That currency's key, such as `agent_credits`. */
+    creditsCurrencyKey: string;
+    /** That currency's display name. */
+    creditsCurrencyName: string;
+    currentPeriod: Paid.CustomerUnitCapCurrentPeriod | null;
+}
+export declare namespace CustomViewContextCap {
+    /** Monthly UTC periods, with boundaries defined by `schedule`. */
+    const Frequency: {
+        readonly Monthly: "MONTHLY";
+    };
+    type Frequency = (typeof Frequency)[keyof typeof Frequency];
+}

package/dist/esm/api/types/CustomViewContextCap.mjs

@@ -0,0 +1,8 @@
+// This file was auto-generated by Fern from our API Definition.
+export var CustomViewContextCap;
+(function (CustomViewContextCap) {
+    /** Monthly UTC periods, with boundaries defined by `schedule`. */
+    CustomViewContextCap.Frequency = {
+        Monthly: "MONTHLY",
+    };
+})(CustomViewContextCap || (CustomViewContextCap = {}));