@paygentic/sdk 0.9.18 → 0.10.0

package/src/models/linecalculationresult.ts

@@ -0,0 +1,47 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import { safeParse } from "../lib/schemas.js";
+import { Result as SafeParseResult } from "../types/fp.js";
+import { SDKValidationError } from "./errors/sdkvalidationerror.js";
+
+/**
+ * Equal to the line's stored amount, quantity and unit price.
+ */
+export type LineCalculationResult = {
+  /**
+   * The line's amount before tax.
+   */
+  amount: string;
+  /**
+   * The line's quantity.
+   */
+  quantity: string | null;
+  /**
+   * The line's unit price. It can be rounded, so quantity times unit price can differ from the amount.
+   */
+  unitPrice: string | null;
+};
+
+/** @internal */
+export const LineCalculationResult$inboundSchema: z.ZodType<
+  LineCalculationResult,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  amount: z.string(),
+  quantity: z.nullable(z.string()),
+  unitPrice: z.nullable(z.string()),
+});
+
+export function lineCalculationResultFromJSON(
+  jsonString: string,
+): SafeParseResult<LineCalculationResult, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => LineCalculationResult$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'LineCalculationResult' from JSON`,
+  );
+}

package/src/models/linecalculationsource.ts

@@ -0,0 +1,52 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import { safeParse } from "../lib/schemas.js";
+import { Result as SafeParseResult } from "../types/fp.js";
+import { SDKValidationError } from "./errors/sdkvalidationerror.js";
+
+/**
+ * Where a value came from: `ref`, a link that can break after the invoice is issued, and `asUsed`, the values the calculation read, which never change.
+ */
+export type LineCalculationSource = {
+  /**
+   * `interval`: a subscription price interval. `price`: a catalog price. `meter`: a billable metric read directly. `entitlement`: the grant engine's reading of an entitlement. `grant`: a grant. `adjustment`: a subscription adjustment. `line`: another line on the invoice. `storedRow`: a figure the line already stored, with `reason`. `merchant`: an amount a merchant entered. `input` is reserved for a value from a system that is not a meter, with `ref` `name` and `eventId` and `asUsed` `value` and `unit`; nothing produces it yet. An open set, so it is a string rather than an enum: known values are `interval`, `price`, `meter`, `entitlement`, `grant`, `adjustment`, `line`, `storedRow`, `merchant`, and new values may be added.
+   */
+  type: string;
+  /**
+   * The ids that link to the resource.
+   */
+  ref?: { [k: string]: any } | undefined;
+  /**
+   * The values the calculation read from the resource. A `line` source has `amount`, and `unitPrice` where a step read the line's rate.
+   */
+  asUsed?: { [k: string]: any } | undefined;
+  /**
+   * `storedRow` only: why the stored figure stands. An open set, so it is a string rather than an enum: known values are `precedes_timeline`, `no_timeline`, `not_derived`, `no_covering_charge`, and new values may be added.
+   */
+  reason?: string | undefined;
+};
+
+/** @internal */
+export const LineCalculationSource$inboundSchema: z.ZodType<
+  LineCalculationSource,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  type: z.string(),
+  ref: z.record(z.any()).optional(),
+  asUsed: z.record(z.any()).optional(),
+  reason: z.string().optional(),
+});
+
+export function lineCalculationSourceFromJSON(
+  jsonString: string,
+): SafeParseResult<LineCalculationSource, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => LineCalculationSource$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'LineCalculationSource' from JSON`,
+  );
+}

package/src/models/linecalculationstep.ts

@@ -0,0 +1,80 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import { safeParse } from "../lib/schemas.js";
+import { Result as SafeParseResult } from "../types/fp.js";
+import { SDKValidationError } from "./errors/sdkvalidationerror.js";
+import {
+  LineCalculationContribution,
+  LineCalculationContribution$inboundSchema,
+} from "./linecalculationcontribution.js";
+import {
+  LineCalculationValue,
+  LineCalculationValue$inboundSchema,
+} from "./linecalculationvalue.js";
+
+/**
+ * One step: the value it changed (`on`), the value before (`in`) and after (`out`), the rule's parameters, and the source of the rule. A reader that does not know an op shows it as "in → out, because source".
+ */
+export type LineCalculationStep = {
+  /**
+   * `allow`: units a grant covered (`covered`). `clamp`: `min` and `max`, null when open. `scaleToBound`: a minimum or maximum applied to a group of lines by uniform scaling (`bound`, `side`, `measured`, `factor`). `setToBound`: a minimum applied to a group that measured zero (`bound`, `sumOfShares`). `prorate`: `fraction` of the period, with the `billed` and full (`of`) windows and the `basis`. `evaluate`: the one join of quantity and price into an amount (`quantity`, `selector`, `fn`, `applied`); its `in` is null. `cap`: `max` and `scope`; on an `invoice` cap also `total`, what the cap started at, and `usedBefore`, what earlier credits took from it. `replace`: a value set by a rule, with `reason`. `subtract`: `units`. `scale`: ordered `terms`, each `by`, `value` and `label`. A `subtract`, `clamp` or `scale` that did not use the envelope's precision says so in `arithmetic`: `float64` or `decimal120`. `round`: `scale` and `mode`. An open set, so it is a string rather than an enum: known values are `allow`, `clamp`, `scaleToBound`, `setToBound`, `prorate`, `evaluate`, `cap`, `replace`, `subtract`, `scale`, `round`, and new values may be added.
+   */
+  op: string;
+  /**
+   * The value the step changes. `quantity`, `selector` (the quantity a volume band is chosen on), `price` and `amount` are reserved; other names may be added.
+   */
+  on: string;
+  /**
+   * The value before the step. Null only on `evaluate`.
+   */
+  in: LineCalculationValue | null;
+  /**
+   * A decimal string, or a price function.
+   */
+  out: LineCalculationValue;
+  /**
+   * The parameters of the op. See `op`.
+   */
+  params: { [k: string]: any };
+  /**
+   * The key of the source in `sources` whose rule this is.
+   */
+  source: string;
+  /**
+   * The other lines a group rule read, with each one's value and period share.
+   */
+  inputsFrom?: Array<LineCalculationContribution> | undefined;
+  /**
+   * Reserved for an `evaluate` of a custom pricing function: the steps inside it, each of the same shape as a step. Free-form here so the schema does not refer to itself. Nothing produces it yet.
+   */
+  trace?: Array<{ [k: string]: any }> | undefined;
+};
+
+/** @internal */
+export const LineCalculationStep$inboundSchema: z.ZodType<
+  LineCalculationStep,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  op: z.string(),
+  on: z.string(),
+  in: z.nullable(LineCalculationValue$inboundSchema),
+  out: LineCalculationValue$inboundSchema,
+  params: z.record(z.any()),
+  source: z.string(),
+  inputsFrom: z.array(LineCalculationContribution$inboundSchema).optional(),
+  trace: z.array(z.record(z.any())).optional(),
+});
+
+export function lineCalculationStepFromJSON(
+  jsonString: string,
+): SafeParseResult<LineCalculationStep, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => LineCalculationStep$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'LineCalculationStep' from JSON`,
+  );
+}

package/src/models/linecalculationvalue.ts

@@ -0,0 +1,34 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import { safeParse } from "../lib/schemas.js";
+import { Result as SafeParseResult } from "../types/fp.js";
+import { SDKValidationError } from "./errors/sdkvalidationerror.js";
+import {
+  LineCalculationPriceFn,
+  LineCalculationPriceFn$inboundSchema,
+} from "./linecalculationpricefn.js";
+
+/**
+ * A decimal string, or a price function.
+ */
+export type LineCalculationValue = LineCalculationPriceFn | string;
+
+/** @internal */
+export const LineCalculationValue$inboundSchema: z.ZodType<
+  LineCalculationValue,
+  z.ZodTypeDef,
+  unknown
+> = z.union([LineCalculationPriceFn$inboundSchema, z.string()]);
+
+export function lineCalculationValueFromJSON(
+  jsonString: string,
+): SafeParseResult<LineCalculationValue, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => LineCalculationValue$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'LineCalculationValue' from JSON`,
+  );
+}

package/src/models/lineitem.ts

@@ -7,6 +7,10 @@ import { safeParse } from "../lib/schemas.js";
 import { ClosedEnum } from "../types/enums.js";
 import { Result as SafeParseResult } from "../types/fp.js";
 import { SDKValidationError } from "./errors/sdkvalidationerror.js";
+import {
+  LineProvenance,
+  LineProvenance$inboundSchema,
+} from "./lineprovenance.js";
 
 /**
  * The type of line item. 'discount' and 'adjustment' line items have negative subtotal/total amounts: 'discount' is a grant discount, 'adjustment' is a discount agreed on the subscription.
@@ -156,6 +160,10 @@ export type LineItem = {
    * Real-time estimated subtotal for a line whose amount is not final yet: current usage for a metered item, the rate the subscription is on for a fee. Null for manual items, and for any line whose amount is already final or cannot be estimated.
    */
   estimatedSubtotal?: string | null | undefined;
+  /**
+   * How the line's amount before tax was calculated: a trace of one evaluation, saved when the invoice was calculated and fixed once it is issued. Returned only with `expand=lineProvenance`. Every field but `status` is present when `status` is `recorded`. Every number is a plain decimal string.
+   */
+  provenance?: LineProvenance | undefined;
 };
 
 /** @internal */
@@ -209,6 +217,7 @@ export const LineItem$inboundSchema: z.ZodType<
   updatedAt: z.string().datetime({ offset: true }).transform(v => new Date(v)),
   estimatedMeteredQuantity: z.nullable(z.string()).optional(),
   estimatedSubtotal: z.nullable(z.string()).optional(),
+  provenance: LineProvenance$inboundSchema.optional(),
 });
 
 export function lineItemFromJSON(

package/src/models/lineprovenance.ts

@@ -0,0 +1,122 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import { safeParse } from "../lib/schemas.js";
+import { Result as SafeParseResult } from "../types/fp.js";
+import { SDKValidationError } from "./errors/sdkvalidationerror.js";
+import {
+  LineCalculationInputs,
+  LineCalculationInputs$inboundSchema,
+} from "./linecalculationinputs.js";
+import {
+  LineCalculationNotApplied,
+  LineCalculationNotApplied$inboundSchema,
+} from "./linecalculationnotapplied.js";
+import {
+  LineCalculationPeriod,
+  LineCalculationPeriod$inboundSchema,
+} from "./linecalculationperiod.js";
+import {
+  LineCalculationPrecision,
+  LineCalculationPrecision$inboundSchema,
+} from "./linecalculationprecision.js";
+import {
+  LineCalculationResult,
+  LineCalculationResult$inboundSchema,
+} from "./linecalculationresult.js";
+import {
+  LineCalculationSource,
+  LineCalculationSource$inboundSchema,
+} from "./linecalculationsource.js";
+import {
+  LineCalculationStep,
+  LineCalculationStep$inboundSchema,
+} from "./linecalculationstep.js";
+
+/**
+ * How the line's amount before tax was calculated: a trace of one evaluation, saved when the invoice was calculated and fixed once it is issued. Returned only with `expand=lineProvenance`. Every field but `status` is present when `status` is `recorded`. Every number is a plain decimal string.
+ */
+export type LineProvenance = {
+  /**
+   * `recorded`: the trace is present. `notRecorded`: the line was calculated but has no saved trace, for example a line calculated before traces were saved (show "Calculation not recorded"). `pending`: the line's invoice has not been calculated yet. An open set, so it is a string rather than an enum: known values are `recorded`, `notRecorded`, `pending`, and new values may be added.
+   */
+  status: string;
+  /**
+   * The format version. It changes only when a field is removed or renamed, or a field changes meaning. A new op, source type, price model, reason or label is not a new version.
+   */
+  version?: number | undefined;
+  /**
+   * The currency of every amount in the trace.
+   */
+  currency?: string | undefined;
+  /**
+   * The default arithmetic of every step. Any other rounding is an explicit `round` step.
+   */
+  precision?: LineCalculationPrecision | undefined;
+  /**
+   * The period the line bills.
+   */
+  period?: LineCalculationPeriod | undefined;
+  /**
+   * When the calculation ran.
+   */
+  calculatedAt?: Date | undefined;
+  /**
+   * The subscription the line belongs to.
+   */
+  subscriptionId?: string | undefined;
+  /**
+   * The values the evaluation started from.
+   */
+  inputs?: LineCalculationInputs | undefined;
+  /**
+   * Every source a step or an input names, by key.
+   */
+  sources?: { [k: string]: LineCalculationSource } | undefined;
+  /**
+   * The steps in the order they were applied. Each starts where the last step on the same value ended.
+   */
+  steps?: Array<LineCalculationStep> | undefined;
+  /**
+   * Rules in force for the line that did not change it, and why.
+   */
+  notApplied?: Array<LineCalculationNotApplied> | undefined;
+  /**
+   * Equal to the line's stored amount, quantity and unit price.
+   */
+  result?: LineCalculationResult | undefined;
+};
+
+/** @internal */
+export const LineProvenance$inboundSchema: z.ZodType<
+  LineProvenance,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  status: z.string(),
+  version: z.number().int().optional(),
+  currency: z.string().optional(),
+  precision: LineCalculationPrecision$inboundSchema.optional(),
+  period: LineCalculationPeriod$inboundSchema.optional(),
+  calculatedAt: z.string().datetime({ offset: true }).transform(v =>
+    new Date(v)
+  ).optional(),
+  subscriptionId: z.string().optional(),
+  inputs: LineCalculationInputs$inboundSchema.optional(),
+  sources: z.record(LineCalculationSource$inboundSchema).optional(),
+  steps: z.array(LineCalculationStep$inboundSchema).optional(),
+  notApplied: z.array(LineCalculationNotApplied$inboundSchema).optional(),
+  result: LineCalculationResult$inboundSchema.optional(),
+});
+
+export function lineProvenanceFromJSON(
+  jsonString: string,
+): SafeParseResult<LineProvenance, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => LineProvenance$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'LineProvenance' from JSON`,
+  );
+}

package/src/models/operations/getinvoice.ts

@@ -10,7 +10,7 @@ export type GetInvoiceRequest = {
    */
   id: string;
   /**
-   * Comma-separated list of fields to expand. Supports: lineItems, items. `items` resolves each returned line's item and its external accounting codes into an `items` collection inside the lineItems block; because those ids come from the lines, requesting `items` also expands `lineItems` on its default paging.
+   * Comma-separated list of fields to expand. Supports: lineItems, items, lineProvenance. `items` resolves each returned line's item and its external accounting codes into an `items` collection inside the lineItems block; because those ids come from the lines, requesting `items` also expands `lineItems` on its default paging. `lineProvenance` adds `provenance` to each returned line: how its amount before tax was calculated. It also expands `lineItems`.
    */
   expand?: string | undefined;
   /**

package/src/models/operations/getinvoicelineitems.ts

@@ -18,7 +18,7 @@ export type GetInvoiceLineItemsRequest = {
    */
   pageToken?: string | undefined;
   /**
-   * Comma-separated list of fields to expand. Supports: items — resolves each returned line's item and that item's external accounting codes into an `items` collection, so a line can be translated to a GL/SKU code without a second call.
+   * Comma-separated list of fields to expand. Supports: items, lineProvenance. `items` resolves each returned line's item and that item's external accounting codes into an `items` collection, so a line can be translated to a GL/SKU code without a second call. `lineProvenance` adds `provenance` to each returned line: how its amount before tax was calculated.
    */
   expand?: string | undefined;
   /**

package/src/models/operations/listlineitems.ts

@@ -31,7 +31,7 @@ export type ListLineItemsRequest = {
    */
   invoiceId?: string | undefined;
   /**
-   * Comma-separated list of fields to expand. Supports: items — resolves each returned line's item and that item's external accounting codes into an `items` collection, so a line can be translated to a GL/SKU code without a second call.
+   * Comma-separated list of fields to expand. Supports: items, lineProvenance. `items` resolves each returned line's item and that item's external accounting codes into an `items` collection, so a line can be translated to a GL/SKU code without a second call. `lineProvenance` adds `provenance` to each returned line: how its amount before tax was calculated.
    */
   expand?: string | undefined;
   /**