@paygentic/sdk 0.9.7 → 0.9.9

package/src/models/pricetax.ts

@@ -0,0 +1,100 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+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";
+
+/**
+ * Whether this price's money is consideration for a supply — the one tax fact only you can state, because it is settled when you agree the deal rather than derived from what was sold. `IN_SCOPE` (the default) is consideration: it enters the taxable amount, positive as a charge or negative as a reduction in the price of the supply it applies to. `OUTSIDE_SCOPE` money is not consideration for anything, so it does not change the taxable amount, carries no tax, does not appear on the tax document, and nets into the amount payable after tax. This means "not consideration for a supply" — it does NOT mean "a supply outside this jurisdiction": exports and place-of-supply answers are worked out from the addresses on the sale by the tax provider, and are never declared on a price. How a supply is then classified — standard, zero-rated, exempt — is the tax provider's determination and is not set here either. Omit the whole `tax` object to leave a price in scope; there is deliberately no schema default on this property, so that a misspelt key is refused rather than silently defaulted.
+ */
+export const SupplyScope = {
+  InScope: "IN_SCOPE",
+  OutsideScope: "OUTSIDE_SCOPE",
+} as const;
+/**
+ * Whether this price's money is consideration for a supply — the one tax fact only you can state, because it is settled when you agree the deal rather than derived from what was sold. `IN_SCOPE` (the default) is consideration: it enters the taxable amount, positive as a charge or negative as a reduction in the price of the supply it applies to. `OUTSIDE_SCOPE` money is not consideration for anything, so it does not change the taxable amount, carries no tax, does not appear on the tax document, and nets into the amount payable after tax. This means "not consideration for a supply" — it does NOT mean "a supply outside this jurisdiction": exports and place-of-supply answers are worked out from the addresses on the sale by the tax provider, and are never declared on a price. How a supply is then classified — standard, zero-rated, exempt — is the tax provider's determination and is not set here either. Omit the whole `tax` object to leave a price in scope; there is deliberately no schema default on this property, so that a misspelt key is refused rather than silently defaulted.
+ */
+export type SupplyScope = ClosedEnum<typeof SupplyScope>;
+
+/**
+ * What an `OUTSIDE_SCOPE` amount is called in the invoice totals, so the wording follows the declaration rather than being retyped per price. Required when `supplyScope` is `OUTSIDE_SCOPE`, and rejected otherwise. `CASHBACK` is the only value today, and a price declaring it must use the `standard` model and must not carry a positive `unitPrice` — a cashback is money paid back, not charged.
+ */
+export const OutsideScopeLabel = {
+  Cashback: "CASHBACK",
+} as const;
+/**
+ * What an `OUTSIDE_SCOPE` amount is called in the invoice totals, so the wording follows the declaration rather than being retyped per price. Required when `supplyScope` is `OUTSIDE_SCOPE`, and rejected otherwise. `CASHBACK` is the only value today, and a price declaring it must use the `standard` model and must not carry a positive `unitPrice` — a cashback is money paid back, not charged.
+ */
+export type OutsideScopeLabel = ClosedEnum<typeof OutsideScopeLabel>;
+
+/**
+ * A price's tax declaration. Optional on write — a price that declares nothing is `IN_SCOPE`, and is billed and taxed exactly as it was before this object existed. Always present on read. Replaced as a whole on update: send the object to change it, omit it to leave it alone.
+ */
+export type PriceTax = {
+  /**
+   * Whether this price's money is consideration for a supply — the one tax fact only you can state, because it is settled when you agree the deal rather than derived from what was sold. `IN_SCOPE` (the default) is consideration: it enters the taxable amount, positive as a charge or negative as a reduction in the price of the supply it applies to. `OUTSIDE_SCOPE` money is not consideration for anything, so it does not change the taxable amount, carries no tax, does not appear on the tax document, and nets into the amount payable after tax. This means "not consideration for a supply" — it does NOT mean "a supply outside this jurisdiction": exports and place-of-supply answers are worked out from the addresses on the sale by the tax provider, and are never declared on a price. How a supply is then classified — standard, zero-rated, exempt — is the tax provider's determination and is not set here either. Omit the whole `tax` object to leave a price in scope; there is deliberately no schema default on this property, so that a misspelt key is refused rather than silently defaulted.
+   */
+  supplyScope: SupplyScope;
+  /**
+   * What an `OUTSIDE_SCOPE` amount is called in the invoice totals, so the wording follows the declaration rather than being retyped per price. Required when `supplyScope` is `OUTSIDE_SCOPE`, and rejected otherwise. `CASHBACK` is the only value today, and a price declaring it must use the `standard` model and must not carry a positive `unitPrice` — a cashback is money paid back, not charged.
+   */
+  outsideScopeLabel?: OutsideScopeLabel | null | undefined;
+};
+
+/** @internal */
+export const SupplyScope$inboundSchema: z.ZodNativeEnum<typeof SupplyScope> = z
+  .nativeEnum(SupplyScope);
+/** @internal */
+export const SupplyScope$outboundSchema: z.ZodNativeEnum<typeof SupplyScope> =
+  SupplyScope$inboundSchema;
+
+/** @internal */
+export const OutsideScopeLabel$inboundSchema: z.ZodNativeEnum<
+  typeof OutsideScopeLabel
+> = z.nativeEnum(OutsideScopeLabel);
+/** @internal */
+export const OutsideScopeLabel$outboundSchema: z.ZodNativeEnum<
+  typeof OutsideScopeLabel
+> = OutsideScopeLabel$inboundSchema;
+
+/** @internal */
+export const PriceTax$inboundSchema: z.ZodType<
+  PriceTax,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  supplyScope: SupplyScope$inboundSchema,
+  outsideScopeLabel: z.nullable(OutsideScopeLabel$inboundSchema).optional(),
+});
+/** @internal */
+export type PriceTax$Outbound = {
+  supplyScope: string;
+  outsideScopeLabel?: string | null | undefined;
+};
+
+/** @internal */
+export const PriceTax$outboundSchema: z.ZodType<
+  PriceTax$Outbound,
+  z.ZodTypeDef,
+  PriceTax
+> = z.object({
+  supplyScope: SupplyScope$outboundSchema,
+  outsideScopeLabel: z.nullable(OutsideScopeLabel$outboundSchema).optional(),
+});
+
+export function priceTaxToJSON(priceTax: PriceTax): string {
+  return JSON.stringify(PriceTax$outboundSchema.parse(priceTax));
+}
+export function priceTaxFromJSON(
+  jsonString: string,
+): SafeParseResult<PriceTax, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => PriceTax$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'PriceTax' from JSON`,
+  );
+}

package/src/models/ratetype.ts

@@ -0,0 +1,25 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import { ClosedEnum } from "../types/enums.js";
+
+/**
+ * What properties.unitPrice is denominated in. 'amount' (the default) is an amount of the invoice currency for each unit metered, so the quantity is the multiplier. 'proportion' is the reverse: a dimensionless share of a currency-denominated quantity, so '0.02' is 2% and the invoice prints '2.00%'. Presentation only. Requires a standard metered price in real currency.
+ */
+export const RateType = {
+  Amount: "amount",
+  Proportion: "proportion",
+} as const;
+/**
+ * What properties.unitPrice is denominated in. 'amount' (the default) is an amount of the invoice currency for each unit metered, so the quantity is the multiplier. 'proportion' is the reverse: a dimensionless share of a currency-denominated quantity, so '0.02' is 2% and the invoice prints '2.00%'. Presentation only. Requires a standard metered price in real currency.
+ */
+export type RateType = ClosedEnum<typeof RateType>;
+
+/** @internal */
+export const RateType$inboundSchema: z.ZodNativeEnum<typeof RateType> = z
+  .nativeEnum(RateType);
+/** @internal */
+export const RateType$outboundSchema: z.ZodNativeEnum<typeof RateType> =
+  RateType$inboundSchema;

package/src/models/schemasprice.ts

@@ -13,6 +13,8 @@ import {
   PriceProperties,
   PriceProperties$inboundSchema,
 } from "./priceproperties.js";
+import { PriceTax, PriceTax$inboundSchema } from "./pricetax.js";
+import { RateType, RateType$inboundSchema } from "./ratetype.js";
 
 export const SchemasPriceObject = {
   Price: "price",
@@ -55,6 +57,10 @@ export type SchemasPrice = {
   billingCadence?: string | null | undefined;
   createdAt: Date;
   invoiceDisplayName: string;
+  /**
+   * Presentation only. Prices sharing this value, within one billing period, print as a single row on the rendered invoice PDF and are described by this string. Every member still bills its own line item on the ledger, this API and the compliance document. The combined row's rate is derived from the members' own rates. Requires the 'standard' pricing model. Sample values: 'Cross Border Fees', 'FX Fees'
+   */
+  invoiceDisplayGroup?: string | null | undefined;
   /**
    * Pricing model of a price as returned by the API. Includes the legacy models ('dynamic', 'percentage') retained for existing prices; 'standard' and 'volume' can be created (see PriceModelInput).
    */
@@ -74,6 +80,14 @@ export type SchemasPrice = {
    * A fixed amount owed whole rather than a per-period rate. An obligation is not prorated over a partial first period: when a subscription starts before its billing anchor, no truncated stub is billed and the first charge is the full amount at the next anchor. An obligation also refuses an interval boundary that falls strictly inside one of its own billing periods, since part of an amount owed whole is not a thing to bill. Defaults to false, which is a rate and is today's behaviour for every price. Not supported on a metered price, whose amount resolves from usage at close.
    */
   isObligation: boolean;
+  /**
+   * What properties.unitPrice is denominated in. 'amount' (the default) is an amount of the invoice currency for each unit metered, so the quantity is the multiplier. 'proportion' is the reverse: a dimensionless share of a currency-denominated quantity, so '0.02' is 2% and the invoice prints '2.00%'. Presentation only. Requires a standard metered price in real currency.
+   */
+  rateType?: RateType | undefined;
+  /**
+   * A price's tax declaration. Optional on write — a price that declares nothing is `IN_SCOPE`, and is billed and taxed exactly as it was before this object existed. Always present on read. Replaced as a whole on update: send the object to change it, omit it to leave it alone.
+   */
+  tax: PriceTax;
   /**
    * Quantity for invoice line items. Total per period = quantity × unitPrice. Only supported for fee prices; metered prices derive quantity from usage. Defaults to 1.
    */
@@ -105,6 +119,7 @@ export const SchemasPrice$inboundSchema: z.ZodType<
   billingCadence: z.nullable(z.string()).optional(),
   createdAt: z.string().datetime({ offset: true }).transform(v => new Date(v)),
   invoiceDisplayName: z.string(),
+  invoiceDisplayGroup: z.nullable(z.string()).optional(),
   model: PriceModel$inboundSchema.optional(),
   paymentTerm: SchemasPricePaymentTerm$inboundSchema,
   properties: PriceProperties$inboundSchema,
@@ -112,6 +127,8 @@ export const SchemasPrice$inboundSchema: z.ZodType<
   features: z.array(PriceFeature$inboundSchema).optional(),
   grantDiscountEnabled: z.boolean().default(false),
   isObligation: z.boolean().default(false),
+  rateType: RateType$inboundSchema.optional(),
+  tax: PriceTax$inboundSchema,
   quantity: z.number().int(),
 });
 

package/src/models/subscriptionadjustment.ts

@@ -17,6 +17,7 @@ export type SubscriptionAdjustmentObject = ClosedEnum<
 
 export const SubscriptionAdjustmentType = {
   PercentageDiscount: "percentageDiscount",
+  UsageDiscount: "usageDiscount",
 } as const;
 export type SubscriptionAdjustmentType = ClosedEnum<
   typeof SubscriptionAdjustmentType
@@ -34,19 +35,27 @@ export type SubscriptionAdjustment = {
   subscriptionId: string;
   type: SubscriptionAdjustmentType;
   /**
-   * The discount rate as a decimal fraction between 0 and 1. "0.35" means 35 percent.
+   * The discount rate as a decimal fraction between 0 and 1. "0.35" means 35 percent. Null on a usageDiscount, which carries a unit count instead.
    */
-  percentageDiscount: string;
+  percentageDiscount: string | null;
   /**
-   * The first instant the discount applies. Inclusive.
+   * The number of usage units taken off the targeted line's billable quantity. Null on a percentageDiscount, which carries a rate instead.
+   */
+  usageDiscount: string | null;
+  /**
+   * The prices this adjustment reduces. Exactly one metered price on a usageDiscount; empty on a percentageDiscount, which reduces every discountable charge.
+   */
+  targetPriceIds: Array<string>;
+  /**
+   * Opens the window. Read per type: INCLUSIVE on a percentageDiscount, whose window is prorated by day overlap; EXCLUSIVE on a usageDiscount, which corrects a line whose period END falls strictly after this instant.
    */
   effectiveFrom: Date;
   /**
-   * The instant the discount stops applying. Exclusive. Null means the discount never stops.
+   * Closes the window, or null for never. Read per type: EXCLUSIVE on a percentageDiscount; INCLUSIVE on a usageDiscount, which corrects a line whose period END falls on or before this instant.
    */
   effectiveTo: Date | null;
   /**
-   * The deal's own name, shown on each discount line of the invoice.
+   * The deal's own name. Shown on each discount line a percentageDiscount emits; a usageDiscount emits no line, so its description is carried here only.
    */
   description: string | null;
   createdAt: Date;
@@ -72,7 +81,9 @@ export const SubscriptionAdjustment$inboundSchema: z.ZodType<
   id: z.string(),
   subscriptionId: z.string(),
   type: SubscriptionAdjustmentType$inboundSchema,
-  percentageDiscount: z.string(),
+  percentageDiscount: z.nullable(z.string()),
+  usageDiscount: z.nullable(z.string()),
+  targetPriceIds: z.array(z.string()),
   effectiveFrom: z.string().datetime({ offset: true }).transform(v =>
     new Date(v)
   ),

package/src/sdk/subscriptions.ts

@@ -149,7 +149,7 @@ export class Subscriptions extends ClientSDK {
    * Create Adjustment
    *
    * @remarks
-   * Attaches a percentage discount to the subscription for a dated window. Every invoice calculated while the window is open carries one discount line for each discounted charge, and tax is assessed on the reduced amount. An invoice that already exists is not changed, including one still in draft — the discount reaches the periods that close after it is created. There is no update operation, and a window cannot be changed after it is created. To change a rate before any invoice has issued under the discount, delete the adjustment and create a replacement. Once an invoice has issued the adjustment is permanent, so set effectiveTo at creation time whenever the deal has a known end date.
+   * Attaches an adjustment to the subscription for a dated window. A percentageDiscount reduces every discountable charge by a rate and carries one discount line per charge on the invoice. A usageDiscount takes a number of usage units off one metered price's billable quantity before that line is priced, so the line re-slots on a volume ladder and shows the corrected quantity; it emits no line of its own. Tax is assessed on the reduced amount either way. An invoice that already exists is not changed, including one still in draft — the adjustment reaches the periods that close after it is created. There is no update operation, and a window cannot be changed after it is created. To change an adjustment before any invoice has issued under it, delete it and create a replacement. Once an invoice has issued the adjustment is permanent, so set effectiveTo at creation time whenever the deal has a known end date.
    */
   async createSubscriptionAdjustment(
     request: operations.CreateSubscriptionAdjustmentRequest,