@paid-ai/paid-node 1.8.0 → 2.0.0

package/dist/cjs/api/types/CustomerUnitCapSchedule.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Monthly UTC boundaries: an anchored day, or the first of each calendar month.
+ */
+export type CustomerUnitCapSchedule = {
+    type: "ANCHORED";
+    anchorDay: number;
+} | {
+    type: "CALENDAR";
+};

package/dist/cjs/api/types/CustomerUnitCapSchedule.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/types/CustomerUnitCapScheduleInput.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Omit to inherit the schedule in force at effectiveFrom. If none applies, use the creation-time UTC day. An explicit change counts spend from the new schedule’s ordinary period start, including earlier spend.
+ */
+export type CustomerUnitCapScheduleInput = {
+    type: "ANCHORED";
+    anchorDay: number;
+} | {
+    type: "CALENDAR";
+};

package/dist/cjs/api/types/CustomerUnitCapScheduleInput.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/types/CustomerUnitCapSet.d.ts

@@ -1,15 +1,17 @@
+import type * as Paid from "../index.js";
 export interface CustomerUnitCapSet {
     /** The cap, in credits of the currency, per period. Must be positive. */
     amount: number;
-    /** Period length. Periods start on the day-of-month of `effectiveFrom` (UTC), clamped in shorter months. */
+    /** Monthly UTC periods, with boundaries defined by `schedule`. */
     frequency?: CustomerUnitCapSet.Frequency;
+    schedule?: Paid.CustomerUnitCapScheduleInput;
     /** The credits currency to cap. Omit it only when the organization has exactly one credits currency, which is then used; otherwise it is required. */
     creditsCurrencyId?: string;
-    /** ISO 8601 timestamp. When the cap starts applying and the anchor day for its periods (UTC). Defaults to now when omitted. Spend earlier in the period that contains it still counts toward the cap. */
+    /** ISO 8601 timestamp. When the cap starts applying, independently of its schedule. Defaults to now. Spend earlier in the schedule’s current period still counts. */
     effectiveFrom?: string;
 }
 export declare namespace CustomerUnitCapSet {
-    /** Period length. Periods start on the day-of-month of `effectiveFrom` (UTC), clamped in shorter months. */
+    /** Monthly UTC periods, with boundaries defined by `schedule`. */
     const Frequency: {
         readonly Monthly: "MONTHLY";
     };

package/dist/cjs/api/types/CustomerUnitCapSet.js

@@ -4,7 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CustomerUnitCapSet = void 0;
 var CustomerUnitCapSet;
 (function (CustomerUnitCapSet) {
-    /** Period length. Periods start on the day-of-month of `effectiveFrom` (UTC), clamped in shorter months. */
+    /** Monthly UTC periods, with boundaries defined by `schedule`. */
     CustomerUnitCapSet.Frequency = {
         Monthly: "MONTHLY",
     };

package/dist/cjs/api/types/CustomerUnitCapSetResponse.d.ts

@@ -6,6 +6,8 @@ export interface CustomerUnitCapSetResponse {
     customerId: string;
     /** The credits currency the cap was set on: the requested `creditsCurrencyId`, or the organization's only credits currency when it was omitted. */
     creditsCurrencyId: string;
-    policy: Paid.CustomerUnitCapOpenPolicy;
+    /** Whether this save created a policy version. False when the effective timeline was already identical. */
+    changed: boolean;
+    policy: Paid.CustomerUnitCapSavedPolicy;
     currentPeriod: Paid.CustomerUnitCapCurrentPeriod | null;
 }

package/dist/cjs/api/types/CustomerUnitCreate.d.ts

@@ -1,5 +1,5 @@
 export interface CustomerUnitCreate {
-    /** Your own id for the unit: required, unique within the customer, immutable, at most 255 characters. Every unit route addresses the unit by it (percent-encode it in the path), and so do signals (`customerUnit.externalCustomerUnitId`). Cannot be `.` or `..`. */
+    /** Your own id for the unit: required, immutable, at most 255 characters, and unique within the organization: no other customer's unit id, external id or alias may be the same, ignoring letter case. Every unit route addresses the unit by it (percent-encode it in the path), and so do signals (`customerUnit.externalCustomerUnitId`). Cannot be `.` or `..`. */
     externalId: string;
     /** Display name (defaults to the external ID). */
     name?: string;
@@ -9,4 +9,6 @@ export interface CustomerUnitCreate {
     parentExternalId?: string;
     /** Freeform JSON for your own use. */
     metadata?: Record<string, unknown> | null;
+    /** `false` makes the unit non-billable, together with every unit under it (a dev or QA environment, say). Defaults to `true`. The root unit is always billable (`409 ROOT_UNIT_ALWAYS_BILLABLE`): a customer that should never be billed simply has no order. Sending `false` needs non-billable units enabled for your organization (`403 FEATURE_NOT_ENABLED` otherwise). Usage on a non-billable unit is still recorded but not billed: it burns no credits, adds nothing to invoices or overage, and counts toward no cap, on a price whose usage comes from a meter (read from your events when the invoice closes) too. A meter's derived signal, and a correlation-window meter's window, follow the source event they take their unit from (the window's closing event, else its opening event): they are not billed when that event was not. Usage is still billed when it is sent with a customer API key, and on cost-plus pricing, which bills from costs that carry no unit. Only signals sent to `/api/v2/signals` that resolve to an active unit, by its key or through an alias on it, can be non-billable, and a change applies to signals received afterwards. */
+    billable?: boolean;
 }

package/dist/cjs/api/types/CustomerUnitCreatedUnderParent.d.ts

@@ -0,0 +1,34 @@
+export interface CustomerUnitCreatedUnderParent {
+    /** Your own id for the unit, unique within the customer; the identifier every unit route takes. */
+    externalId: string;
+    /** Paid's id of the customer the unit belongs to (`cus_…`). `null` only for a legacy customer that has no Paid id; `customerExternalId` still names it. */
+    customerId: string | null;
+    /** Your external id of that customer, when it has one. */
+    customerExternalId: string | null;
+    /** Display name. Never used to address the unit. */
+    name: string;
+    /** Your structural vocabulary for the unit. */
+    externalType: string | null;
+    /** ACTIVE; DELETED after a soft delete (one-way); or DRAFT, a placeholder that holds the key for this customer until you create the unit with that key (which promotes it) or delete it (soft, the key stays reserved, as for any unit). A draft is never a parent and never carries a cap. */
+    status: CustomerUnitCreatedUnderParent.Status;
+    /** `externalId` of the parent unit; `null` only on the customer's root unit. */
+    parentExternalId: string | null;
+    /** Whether this unit is the customer's root: the one unit without a parent. Derived from the missing parent, not stored. At most one active root per customer; the root cannot be moved, and once deleted a new root can be created. */
+    isRoot: boolean;
+    /** The unit's own setting, as last created or updated: `false` marks it, and every unit under it, non-billable. Always `true` on the root. `effectiveBillable` says whether the unit is billable once its ancestors are counted. Usage on a non-billable unit is still recorded but not billed: it burns no credits, adds nothing to invoices or overage, and counts toward no cap, on a price whose usage comes from a meter (read from your events when the invoice closes) too. A meter's derived signal, and a correlation-window meter's window, follow the source event they take their unit from (the window's closing event, else its opening event): they are not billed when that event was not. Usage is still billed when it is sent with a customer API key, and on cost-plus pricing, which bills from costs that carry no unit. Only signals sent to `/api/v2/signals` that resolve to an active unit, by its key or through an alias on it, can be non-billable, and a change applies to signals received afterwards. */
+    billable: boolean;
+    /** Read-only. Whether the unit is billable in effect: `false` when the unit or any unit above it has `billable: false`. A unit cannot make itself billable under a non-billable ancestor, and moving a unit under one makes it non-billable. */
+    effectiveBillable: boolean;
+    metadata: Record<string, unknown> | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare namespace CustomerUnitCreatedUnderParent {
+    /** ACTIVE; DELETED after a soft delete (one-way); or DRAFT, a placeholder that holds the key for this customer until you create the unit with that key (which promotes it) or delete it (soft, the key stays reserved, as for any unit). A draft is never a parent and never carries a cap. */
+    const Status: {
+        readonly Active: "ACTIVE";
+        readonly Deleted: "DELETED";
+        readonly Draft: "DRAFT";
+    };
+    type Status = (typeof Status)[keyof typeof Status];
+}

package/dist/cjs/api/types/CustomerUnitCreatedUnderParent.js

@@ -0,0 +1,13 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CustomerUnitCreatedUnderParent = void 0;
+var CustomerUnitCreatedUnderParent;
+(function (CustomerUnitCreatedUnderParent) {
+    /** ACTIVE; DELETED after a soft delete (one-way); or DRAFT, a placeholder that holds the key for this customer until you create the unit with that key (which promotes it) or delete it (soft, the key stays reserved, as for any unit). A draft is never a parent and never carries a cap. */
+    CustomerUnitCreatedUnderParent.Status = {
+        Active: "ACTIVE",
+        Deleted: "DELETED",
+        Draft: "DRAFT",
+    };
+})(CustomerUnitCreatedUnderParent || (exports.CustomerUnitCreatedUnderParent = CustomerUnitCreatedUnderParent = {}));

package/dist/cjs/api/types/CustomerUnitSpendResponse.d.ts

@@ -0,0 +1,12 @@
+import type * as Paid from "../index.js";
+export interface CustomerUnitSpendResponse {
+    /** Your own id for the unit (its `externalId`), the identifier the unit and cap routes take. */
+    externalCustomerUnitId: string;
+    /** The Paid display id of the customer the unit belongs to. */
+    customerId: string;
+    /** The credits currency this response is about: the requested `creditsCurrencyId`, or the organization's only credits currency when it was omitted. */
+    creditsCurrencyId: string;
+    window: Paid.CustomerUnitSpendWindow;
+    /** Credits of this currency spent by this unit and every unit beneath it during the window, net of reversals. Counted whether or not the unit has a cap. JSON number; exact within ±2^53. */
+    spent: number;
+}

package/dist/cjs/api/types/CustomerUnitSpendResponse.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/types/CustomerUnitSpendWindow.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The window `spent` covers: the one requested, or the current calendar month (UTC) when none was given.
+ */
+export interface CustomerUnitSpendWindow {
+    /** Inclusive start of the window, UTC. */
+    start: string;
+    /** Exclusive end of the window, UTC. */
+    end: string;
+}

package/dist/cjs/api/types/CustomerUnitSpendWindow.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/types/CustomerUnitUpdate.d.ts

@@ -7,4 +7,6 @@ export interface CustomerUnitUpdate {
     parentExternalId?: string;
     /** Freeform JSON for your own use. */
     metadata?: Record<string, unknown> | null;
+    /** Flips the unit's own setting either way. Under a non-billable ancestor the unit stays non-billable in effect (`effectiveBillable`) whatever its own value. Refused on the root unit, which is always billable (`409 ROOT_UNIT_ALWAYS_BILLABLE`). Sending `false` needs non-billable units enabled for your organization (`403 FEATURE_NOT_ENABLED` otherwise). Usage on a non-billable unit is still recorded but not billed: it burns no credits, adds nothing to invoices or overage, and counts toward no cap, on a price whose usage comes from a meter (read from your events when the invoice closes) too. A meter's derived signal, and a correlation-window meter's window, follow the source event they take their unit from (the window's closing event, else its opening event): they are not billed when that event was not. Usage is still billed when it is sent with a customer API key, and on cost-plus pricing, which bills from costs that carry no unit. Only signals sent to `/api/v2/signals` that resolve to an active unit, by its key or through an alias on it, can be non-billable, and a change applies to signals received afterwards. */
+    billable?: boolean;
 }

package/dist/cjs/api/types/DeliveredValueCalculation.d.ts

@@ -0,0 +1,11 @@
+import type * as Paid from "../index.js";
+export interface DeliveredValueCalculation {
+    /** First signal this configuration priced, within the requested period. */
+    startDate: string;
+    /** Last signal this configuration priced, within the requested period. */
+    endDate: string;
+    /** Folds left to right into unitTotal, e.g. 40 tickets × 45 minutes ÷ 60 = 30 hours. */
+    terms: Paid.DeliveredValueCalculationTerm[];
+    /** What the terms fold to, in the metric's own unit. */
+    unitTotal: number;
+}

package/dist/cjs/api/types/DeliveredValueCalculation.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/types/DeliveredValueCalculationTerm.d.ts

@@ -0,0 +1,34 @@
+export interface DeliveredValueCalculationTerm {
+    /** How this term applies to the running total. Absent on the leading occurrence-count term. */
+    operator?: DeliveredValueCalculationTerm.Operator;
+    /** Customer-facing name of this term, e.g. 'minutes saved'. */
+    label: string;
+    /** The term's raw value. When format is 'percent' this is the stored ratio (0.02 = 2%). */
+    value: number;
+    /** Display-only formatting hint for the value. */
+    format?: DeliveredValueCalculationTerm.Format;
+    /** The unit a 'duration' format is expressed in. */
+    formatUnit?: DeliveredValueCalculationTerm.FormatUnit;
+}
+export declare namespace DeliveredValueCalculationTerm {
+    /** How this term applies to the running total. Absent on the leading occurrence-count term. */
+    const Operator: {
+        readonly Multiply: "×";
+        readonly Divide: "÷";
+    };
+    type Operator = (typeof Operator)[keyof typeof Operator];
+    /** Display-only formatting hint for the value. */
+    const Format: {
+        readonly Percent: "percent";
+        readonly Duration: "duration";
+    };
+    type Format = (typeof Format)[keyof typeof Format];
+    /** The unit a 'duration' format is expressed in. */
+    const FormatUnit: {
+        readonly Seconds: "seconds";
+        readonly Minutes: "minutes";
+        readonly Hours: "hours";
+        readonly Days: "days";
+    };
+    type FormatUnit = (typeof FormatUnit)[keyof typeof FormatUnit];
+}

package/dist/cjs/api/types/DeliveredValueCalculationTerm.js

@@ -0,0 +1,24 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeliveredValueCalculationTerm = void 0;
+var DeliveredValueCalculationTerm;
+(function (DeliveredValueCalculationTerm) {
+    /** How this term applies to the running total. Absent on the leading occurrence-count term. */
+    DeliveredValueCalculationTerm.Operator = {
+        Multiply: "\u00D7",
+        Divide: "\u00F7",
+    };
+    /** Display-only formatting hint for the value. */
+    DeliveredValueCalculationTerm.Format = {
+        Percent: "percent",
+        Duration: "duration",
+    };
+    /** The unit a 'duration' format is expressed in. */
+    DeliveredValueCalculationTerm.FormatUnit = {
+        Seconds: "seconds",
+        Minutes: "minutes",
+        Hours: "hours",
+        Days: "days",
+    };
+})(DeliveredValueCalculationTerm || (exports.DeliveredValueCalculationTerm = DeliveredValueCalculationTerm = {}));

package/dist/cjs/api/types/DeliveredValueMetric.d.ts

@@ -0,0 +1,54 @@
+import type * as Paid from "../index.js";
+export interface DeliveredValueMetric {
+    slug: string;
+    name: string;
+    category: string | null;
+    unit: Paid.ValueMetricUnit;
+    description: string | null;
+    longDescription: string | null;
+    sources: DeliveredValueMetric.Sources.Item[] | null;
+    archivedAt: string | null;
+    monetaryConversion: DeliveredValueMetric.MonetaryConversion | null;
+    formula: DeliveredValueMetric.Formula | null;
+    /** Display-ready calculations, oldest first, each one the strip a value receipt renders. Normally a single entry. If the value model changed during the period there is one entry per configuration, each folding the figures that configuration actually priced. Each strip is in the unit that configuration measured, so they sum to unitTotal unless the unit itself changed during the period. Absent when the metric's formula cannot be represented faithfully as a flat strip (e.g. conditions, or signals with differing values), or when nothing was delivered in the period. */
+    calculations?: Paid.DeliveredValueCalculation[];
+    /** Total measured value delivered over the period, in the metric's own unit (see unit). Durations are in the authored durationUnit (e.g. hours), never normalized to seconds. If the unit changed during the period, durations are restated in the current durationUnit. Absent where no total can be stated in one unit: a change of unit type, a renamed custom unit, or a figure mixing rows measured in a known unit with rows whose configuration can no longer be identified. The per-configuration calculations carry the figures instead. */
+    unitTotal?: number;
+    /** Monetary value delivered over the period, in decimal units of the response currency (12.5 = $12.50), not cents. Null when the metric delivered no money and converts none — never reported as 0. A metric priced under a conversion the value model has since dropped still reports what it delivered. */
+    monetaryTotal: number | null;
+    /** Signals that contributed to this metric in the period, counted by quantity — one signal reporting a batch of 100 counts as 100. Fractional where the signals reported fractional quantities. */
+    signalCount: number;
+}
+export declare namespace DeliveredValueMetric {
+    type Sources = Sources.Item[];
+    namespace Sources {
+        interface Item {
+            name: string;
+            url: string;
+        }
+    }
+    interface MonetaryConversion {
+        /** The flat rate, when this conversion is the 'unit_value * rate' shape this API and Value Studio produce. Null for a conversion authored through the whole-manifest upload that this API cannot express — read `expression` and `variables` for those, and edit them with PUT /api/v2/value-models. */
+        valuePerUnit: number | null;
+        /** The rate variable's customer-facing label. Null when valuePerUnit is null. */
+        label: string | null;
+        expression: string;
+        variables: MonetaryConversion.Variables.Item[];
+    }
+    namespace MonetaryConversion {
+        type Variables = Variables.Item[];
+        namespace Variables {
+            interface Item {
+                id: string;
+                label: string;
+                default: number;
+            }
+        }
+    }
+    interface Formula {
+        id: string;
+        label: string;
+        expression: string;
+        variables: Paid.ValueMetricFormulaVariable[];
+    }
+}

package/dist/cjs/api/types/DeliveredValueMetric.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/types/DeliveredValueResponse.d.ts

@@ -0,0 +1,34 @@
+import type * as Paid from "../index.js";
+export interface DeliveredValueResponse {
+    /** Currency for every monetary field in this response — the customer's override when one exists, else the value model's currency. */
+    currency: string;
+    /** The resolved period, echoing date-only inputs expanded to full UTC date-times. */
+    period: DeliveredValueResponse.Period;
+    customer: DeliveredValueResponse.Customer;
+    /** One entry per value metric, ordered by the value model's display order. Archived metrics appear only when they delivered value in the period. */
+    valueMetrics: Paid.DeliveredValueMetric[];
+    /** Per-event activity behind the metric totals, one entry per event. An event that feeds several value metrics appears once, and states its occurrences and its values once. */
+    signals: Paid.DeliveredValueSignal[];
+    totals: DeliveredValueResponse.Totals;
+}
+export declare namespace DeliveredValueResponse {
+    /**
+     * The resolved period, echoing date-only inputs expanded to full UTC date-times.
+     */
+    interface Period {
+        startDate: string;
+        endDate: string;
+    }
+    interface Customer {
+        /** The Paid customer ID. */
+        id: string;
+        externalId: string | null;
+        name: string;
+    }
+    interface Totals {
+        /** Money delivered over the period, in decimal units of the response currency, not cents. Adds up the signals array exactly, so the breakdown always reconciles with this figure. That includes value whose metric the value model no longer defines, which is why this can exceed the sum of valueMetrics. Signals the value model no longer lists are outside the report altogether and appear in neither. */
+        monetaryTotal: number;
+        /** Total signal occurrences, counted the way a value receipt's footer counts them: events that delivered value, plus display-only events that fired. Quantity-weighted, so fractional where the signals reported fractional quantities. */
+        signalCount: number;
+    }
+}

package/dist/cjs/api/types/DeliveredValueResponse.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/types/DeliveredValueSignal.d.ts

@@ -0,0 +1,14 @@
+import type * as Paid from "../index.js";
+export interface DeliveredValueSignal {
+    eventName: string;
+    label: string;
+    /** Customer-facing description of this signal. The value model's own description for the event wins. Without one, this is the description of the first metric the signal feeds. */
+    description: string | null;
+    /** Every value metric this signal feeds, in the order the value model binds them. A signal may feed more than one. Empty for a display-only signal. This list comes from the value model, so it does not change with the period. Read values for what each metric actually delivered. */
+    valueTypeSlugs: string[];
+    tags: string[];
+    /** Quantity-weighted occurrences of this event in the period. Fractional where the signals reported fractional quantities. */
+    count: number;
+    /** Delivered value per metric this event contributed to. Empty when the event fired but delivered no value. */
+    values: Paid.DeliveredValueSignalValue[];
+}

package/dist/cjs/api/types/DeliveredValueSignal.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/types/DeliveredValueSignalValue.d.ts

@@ -0,0 +1,8 @@
+export interface DeliveredValueSignalValue {
+    /** The value metric this value counted toward. */
+    valueTypeSlug: string;
+    /** Value delivered by this event, in the metric's own unit. Absent for the same reason the metric's unitTotal can be: the period mixes units that do not convert. */
+    unitValue?: number;
+    /** Monetary value delivered by this event, in decimal units of the response currency, not cents. */
+    monetaryValue: number;
+}

package/dist/cjs/api/types/DeliveredValueSignalValue.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/types/DeliveredValueSummaryBucket.d.ts

@@ -0,0 +1,20 @@
+export interface DeliveredValueSummaryBucket {
+    /** Start of the bucket (inclusive), UTC. Clipped to the requested startDate when the window starts mid-period. */
+    periodStart: string;
+    /** Last instant of the bucket (inclusive), UTC. Clipped to the requested endDate when the window ends mid-period. */
+    periodEnd: string;
+    /** The group this bucket belongs to. For valueMetric grouping, the metric's slug; an archived metric still appears when it delivered value in the window. For dimension grouping, the payload value of dimensionKey; a signal whose payload lacks the key, or holds it empty, groups under the empty string. For formulaCondition grouping, the metric's slug, a colon, and the band: the zero-based index of the condition that priced the rows, "default" where every condition missed, or "none" where the metric priced them through a formula that has no conditions. Read valueMetric and conditionIndex rather than parsing this. For signal grouping, the name of the source event, as the signals array of GET /delivered-value names it. */
+    groupKey: string;
+    /** Slug of the metric this band belongs to. Present only under formulaCondition grouping. */
+    valueMetric?: string;
+    /** Zero-based index of the formula condition that priced this band's rows, in the order the value model authors them. Present only under formulaCondition grouping, and only for a band that is a condition — absent for the "default" and "none" groups. */
+    conditionIndex?: number;
+    /** The condition that priced this band, as field, operator and value — a stable descriptor, not display copy. A metric priced through several formulas states the label they agree on; where they band differently at this index, no one condition describes the group and the label is absent. */
+    conditionLabel?: string;
+    /** Value delivered in this bucket in the metric's own unit — minutes saved, tickets resolved — as GET /delivered-value states it. Present under valueMetric and formulaCondition grouping, where every row in a group belongs to one metric and so shares its unit. Under dimension and signal grouping it is present only when the request names a valueMetric, which narrows the rows to that one metric; without it the groups sum across metrics that need not measure the same thing (a signal may feed more than one), and no unit describes the sum. */
+    unitTotal?: number;
+    /** Money delivered in this bucket, in decimal units of the response currency (12.5 = $12.50), not cents. */
+    monetaryTotal: number;
+    /** Signals that contributed to this group in this bucket, counted by quantity — one signal reporting a batch of 100 counts as 100. For valueMetric grouping, a signal feeding two metrics counts under both groups. For dimension and signal grouping, it counts once in its group. */
+    signalCount: number;
+}

package/dist/cjs/api/types/DeliveredValueSummaryBucket.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/types/DeliveredValueSummaryResponse.d.ts

@@ -0,0 +1,41 @@
+import type * as Paid from "../index.js";
+export interface DeliveredValueSummaryResponse {
+    /** Currency for every monetary field here, resolved as GET /delivered-value resolves it. */
+    currency: string;
+    customer: DeliveredValueSummaryResponse.Customer;
+    /** How the buckets are grouped. */
+    groupBy: DeliveredValueSummaryResponse.GroupBy;
+    /** The signal-payload key the buckets are grouped by, echoed from the query. Present only when groupBy is dimension. */
+    dimensionKey?: string;
+    /** The value metric the buckets are narrowed to, echoed from the query. Present only when the request named one. Every unitTotal in the response is then in this metric's unit. */
+    valueMetric?: string;
+    /** Period bucket size. */
+    interval: DeliveredValueSummaryResponse.Interval;
+    /** Buckets ordered by period, then by group key. Every period in the window appears, and every group appears in every period, so a chart never has to fill gaps itself. For valueMetric grouping the groups are the model's metrics, plus any archived metric that delivered value in the window. For dimension grouping the groups are the payload values observed in the window, so a window that delivered nothing has no rows. For signal grouping the groups are the signals the value model binds to a metric, plus any signal that delivered value in the window under a binding the model has since dropped. A row is one period of one group; a request producing more than 5000 rows is rejected rather than answered in part. */
+    data: Paid.DeliveredValueSummaryBucket[];
+}
+export declare namespace DeliveredValueSummaryResponse {
+    interface Customer {
+        /** The Paid customer ID. */
+        id: string;
+        externalId: string | null;
+        name: string;
+    }
+    /** How the buckets are grouped. */
+    const GroupBy: {
+        readonly ValueMetric: "valueMetric";
+        readonly Dimension: "dimension";
+        readonly FormulaCondition: "formulaCondition";
+        readonly Signal: "signal";
+    };
+    type GroupBy = (typeof GroupBy)[keyof typeof GroupBy];
+    /** Period bucket size. */
+    const Interval: {
+        readonly Hour: "hour";
+        readonly Day: "day";
+        readonly Week: "week";
+        readonly Month: "month";
+        readonly Quarter: "quarter";
+    };
+    type Interval = (typeof Interval)[keyof typeof Interval];
+}

package/dist/cjs/api/types/DeliveredValueSummaryResponse.js

@@ -0,0 +1,22 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeliveredValueSummaryResponse = void 0;
+var DeliveredValueSummaryResponse;
+(function (DeliveredValueSummaryResponse) {
+    /** How the buckets are grouped. */
+    DeliveredValueSummaryResponse.GroupBy = {
+        ValueMetric: "valueMetric",
+        Dimension: "dimension",
+        FormulaCondition: "formulaCondition",
+        Signal: "signal",
+    };
+    /** Period bucket size. */
+    DeliveredValueSummaryResponse.Interval = {
+        Hour: "hour",
+        Day: "day",
+        Week: "week",
+        Month: "month",
+        Quarter: "quarter",
+    };
+})(DeliveredValueSummaryResponse || (exports.DeliveredValueSummaryResponse = DeliveredValueSummaryResponse = {}));

package/dist/cjs/api/types/GrantCustomerCreditsResponse.d.ts

@@ -1,6 +1,6 @@
 import type * as Paid from "../index.js";
 export interface GrantCustomerCreditsResponse {
-    /** True when this request created a new grant. */
+    /** True when this request created a new grant. False when an earlier request with the same idempotencyKey already created it. */
     created: boolean;
     customer: Paid.CreditGrantCustomer;
     creditCurrency: Paid.CreditGrantCurrency;

package/dist/cjs/api/types/PlanCreditBenefit.d.ts

@@ -6,9 +6,12 @@ export interface PlanCreditBenefit {
     rolloverAmount?: number | null;
     rolloverDuration?: number | null;
     rolloverDurationUnit?: PlanCreditBenefit.RolloverDurationUnit | null;
-    allocationCadence?: PlanCreditBenefit.AllocationCadence;
+    allocationCadence?: string;
     creditGrantTiming?: PlanCreditBenefit.CreditGrantTiming | null;
     isInfiniteTotal?: boolean;
+    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;
     /** Accepts any additional properties */
     [key: string]: any;
 }
@@ -23,11 +26,6 @@ export declare namespace PlanCreditBenefit {
         readonly Months: "months";
     };
     type RolloverDurationUnit = (typeof RolloverDurationUnit)[keyof typeof RolloverDurationUnit];
-    const AllocationCadence: {
-        readonly Upfront: "upfront";
-        readonly Monthly: "monthly";
-    };
-    type AllocationCadence = (typeof AllocationCadence)[keyof typeof AllocationCadence];
     const CreditGrantTiming: {
         readonly OnPayment: "on_payment";
         readonly OnInvoicePosted: "on_invoice_posted";

package/dist/cjs/api/types/PlanCreditBenefit.js

@@ -12,10 +12,6 @@ var PlanCreditBenefit;
         Days: "days",
         Months: "months",
     };
-    PlanCreditBenefit.AllocationCadence = {
-        Upfront: "upfront",
-        Monthly: "monthly",
-    };
     PlanCreditBenefit.CreditGrantTiming = {
         OnPayment: "on_payment",
         OnInvoicePosted: "on_invoice_posted",

package/dist/cjs/api/types/PricingOutput.d.ts

@@ -10,6 +10,9 @@ export interface PricingOutput {
     creditsCurrencyId?: string;
     creditCost?: number;
     unitValue?: 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;
     percentageValue?: number;
     costPlusMultiplier?: number;
     pricePoints: Paid.PricingPricePointOutput[];

package/dist/cjs/api/types/ProductCreditBenefitInput.d.ts

@@ -1,4 +1,5 @@
 export interface ProductCreditBenefitInput {
+    id?: string;
     creditsCurrencyId: string;
     /** Credit amount, exact to at most 6 decimal places. */
     amount: number;
@@ -7,6 +8,8 @@ export interface ProductCreditBenefitInput {
     allocationCadence?: ProductCreditBenefitInput.AllocationCadence;
     creditGrantTiming?: ProductCreditBenefitInput.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 ProductCreditBenefitInput {
     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/cjs/api/types/ProductCreditBenefitInput.js

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

package/dist/cjs/api/types/ProductCreditBenefitOutput.d.ts

@@ -7,6 +7,8 @@ export interface ProductCreditBenefitOutput {
     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/cjs/api/types/ProductPricingOutput.d.ts

@@ -10,6 +10,9 @@ export interface ProductPricingOutput {
     creditsCurrencyId?: string;
     creditCost?: number;
     unitValue?: 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;
     percentageValue?: number;
     costPlusMultiplier?: number;
     pricePoints: Paid.ProductPricePointOutput[];