@paygentic/sdk 0.8.5 → 0.8.7

package/src/models/planversionpriceslot.ts

@@ -0,0 +1,136 @@
+/*
+ * 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";
+import { PriceFeature, PriceFeature$inboundSchema } from "./pricefeature.js";
+
+export const PlanVersionPriceSlotObject = {
+  Price: "price",
+} as const;
+export type PlanVersionPriceSlotObject = ClosedEnum<
+  typeof PlanVersionPriceSlotObject
+>;
+
+export const PlanVersionPriceSlotModel = {
+  Standard: "standard",
+  Dynamic: "dynamic",
+  Volume: "volume",
+  Percentage: "percentage",
+} as const;
+export type PlanVersionPriceSlotModel = ClosedEnum<
+  typeof PlanVersionPriceSlotModel
+>;
+
+export const PlanVersionPriceSlotPaymentTerm = {
+  InArrears: "in_arrears",
+  InAdvance: "in_advance",
+} as const;
+export type PlanVersionPriceSlotPaymentTerm = ClosedEnum<
+  typeof PlanVersionPriceSlotPaymentTerm
+>;
+
+/**
+ * One price slot on a plan version. Every `Price` field is present, plus `priceDeleted` layered on top.
+ */
+export type PlanVersionPriceSlot = {
+  /**
+   * Unique identifier for a price
+   */
+  id: string;
+  object: PlanVersionPriceSlotObject;
+  /**
+   * Unique identifier for an organization
+   */
+  merchantId: string;
+  billableMetricId?: string | undefined;
+  /**
+   * The unique identifier for the fee referred to by this price
+   */
+  feeId?: string | undefined;
+  /**
+   * ISO 8601 duration for billing frequency (e.g., P1M for monthly)
+   */
+  billingCadence?: string | null | undefined;
+  createdAt: Date;
+  currency?: string | undefined;
+  description?: string | undefined;
+  invoiceDisplayName: string;
+  model: PlanVersionPriceSlotModel;
+  paymentTerm: PlanVersionPriceSlotPaymentTerm;
+  properties: { [k: string]: any };
+  unitAmount?: string | undefined;
+  updatedAt: Date;
+  /**
+   * Features associated with this price
+   */
+  features?: Array<PriceFeature> | undefined;
+  /**
+   * When true, grants applied to a subscription will discount usage charged by this price. Only supported for standard metered prices.
+   */
+  grantDiscountEnabled: boolean;
+  /**
+   * Quantity used when generating invoice line items for this price. Total per period = quantity × unitPrice. Only supported for fee prices; metered prices derive quantity from usage. Defaults to 1.
+   */
+  quantity: number;
+  /**
+   * True when the underlying price this slot references has been soft-deleted. The slot can still be removed or replaced to repair the draft; it cannot be published while any slot remains dead.
+   */
+  priceDeleted: boolean;
+};
+
+/** @internal */
+export const PlanVersionPriceSlotObject$inboundSchema: z.ZodNativeEnum<
+  typeof PlanVersionPriceSlotObject
+> = z.nativeEnum(PlanVersionPriceSlotObject);
+
+/** @internal */
+export const PlanVersionPriceSlotModel$inboundSchema: z.ZodNativeEnum<
+  typeof PlanVersionPriceSlotModel
+> = z.nativeEnum(PlanVersionPriceSlotModel);
+
+/** @internal */
+export const PlanVersionPriceSlotPaymentTerm$inboundSchema: z.ZodNativeEnum<
+  typeof PlanVersionPriceSlotPaymentTerm
+> = z.nativeEnum(PlanVersionPriceSlotPaymentTerm);
+
+/** @internal */
+export const PlanVersionPriceSlot$inboundSchema: z.ZodType<
+  PlanVersionPriceSlot,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  id: z.string(),
+  object: PlanVersionPriceSlotObject$inboundSchema.default("price"),
+  merchantId: z.string(),
+  billableMetricId: z.string().optional(),
+  feeId: z.string().optional(),
+  billingCadence: z.nullable(z.string()).optional(),
+  createdAt: z.string().datetime({ offset: true }).transform(v => new Date(v)),
+  currency: z.string().optional(),
+  description: z.string().optional(),
+  invoiceDisplayName: z.string(),
+  model: PlanVersionPriceSlotModel$inboundSchema,
+  paymentTerm: PlanVersionPriceSlotPaymentTerm$inboundSchema,
+  properties: z.record(z.any()),
+  unitAmount: z.string().optional(),
+  updatedAt: z.string().datetime({ offset: true }).transform(v => new Date(v)),
+  features: z.array(PriceFeature$inboundSchema).optional(),
+  grantDiscountEnabled: z.boolean().default(false),
+  quantity: z.number().int().default(1),
+  priceDeleted: z.boolean(),
+});
+
+export function planVersionPriceSlotFromJSON(
+  jsonString: string,
+): SafeParseResult<PlanVersionPriceSlot, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => PlanVersionPriceSlot$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'PlanVersionPriceSlot' from JSON`,
+  );
+}

package/src/models/price.ts

@@ -14,13 +14,13 @@ export const PriceObject = {
 } as const;
 export type PriceObject = ClosedEnum<typeof PriceObject>;
 
-export const Model = {
+export const PriceModel1 = {
   Standard: "standard",
   Dynamic: "dynamic",
   Volume: "volume",
   Percentage: "percentage",
 } as const;
-export type Model = ClosedEnum<typeof Model>;
+export type PriceModel1 = ClosedEnum<typeof PriceModel1>;
 
 export const PricePaymentTerm = {
   InArrears: "in_arrears",
@@ -51,7 +51,7 @@ export type Price = {
   currency?: string | undefined;
   description?: string | undefined;
   invoiceDisplayName: string;
-  model: Model;
+  model: PriceModel1;
   paymentTerm: PricePaymentTerm;
   properties: { [k: string]: any };
   unitAmount?: string | undefined;
@@ -75,9 +75,8 @@ export const PriceObject$inboundSchema: z.ZodNativeEnum<typeof PriceObject> = z
   .nativeEnum(PriceObject);
 
 /** @internal */
-export const Model$inboundSchema: z.ZodNativeEnum<typeof Model> = z.nativeEnum(
-  Model,
-);
+export const PriceModel1$inboundSchema: z.ZodNativeEnum<typeof PriceModel1> = z
+  .nativeEnum(PriceModel1);
 
 /** @internal */
 export const PricePaymentTerm$inboundSchema: z.ZodNativeEnum<
@@ -99,7 +98,7 @@ export const Price$inboundSchema: z.ZodType<Price, z.ZodTypeDef, unknown> = z
     currency: z.string().optional(),
     description: z.string().optional(),
     invoiceDisplayName: z.string(),
-    model: Model$inboundSchema,
+    model: PriceModel1$inboundSchema,
     paymentTerm: PricePaymentTerm$inboundSchema,
     properties: z.record(z.any()),
     unitAmount: z.string().optional(),

package/src/models/pricepropertiesunion.ts

@@ -86,7 +86,7 @@ export type PriceProperties2 = {
  */
 export type PriceProperties1 = {
   /**
-   * Per-unit cost in decimal format for fixed-rate pricing. Sample values: '0.00002' represents $0.00002 per token, '0.15' represents $0.15 per gigabyte stored, '0.05' represents $0.05 per API call. Per unit. Total per period = quantity × unitPrice; see the `quantity` field.
+   * Per-unit cost in decimal format for fixed-rate pricing. Sample values: '0.00002' represents $0.00002 per token, '0.15' represents $0.15 per gigabyte stored, '0.05' represents $0.05 per API call. Per unit. Total per period = quantity × unitPrice; see the `quantity` field. A negative value defines a usage-scaled rebate: the line's subtotal is negative and reduces the invoice. A rebate never drives an invoice total below zero, so set rebate rates below the charges they offset. A negative unitPrice is only valid on a metered price (a billableMetricId is required — there is no usage to scale on a fee price) and cannot be combined with grantDiscountEnabled, a hard-limit feature, or a pricingUnitId. When a rebate and a charge price share a billable metric, they must share feature attachment (both on the same feature, or both featureless) or they will compute against different quantity bases.
    */
   unitPrice: string;
 };

package/src/models/resolveditem.ts

@@ -0,0 +1,63 @@
+/*
+ * 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 {
+  ExternalReference,
+  ExternalReference$inboundSchema,
+} from "./externalreference.js";
+
+/**
+ * An item a line was tagged with, together with its external accounting/tax codes. Deliberately narrower than the /v0/items Item resource: it carries what is needed to translate a line into a GL/SKU code, not the full record.
+ */
+export type ResolvedItem = {
+  /**
+   * Unique identifier for an item
+   */
+  id: string;
+  /**
+   * Human-readable item name
+   */
+  name: string;
+  /**
+   * The product this item belongs to, for grouping lines by product
+   */
+  catalogId: string | null;
+  /**
+   * When this item was retired from the catalog. Archived items still resolve here — invoices that already reference them have to keep resolving — but cannot be tagged onto new pricing. Null while active.
+   */
+  archivedAt: Date | null;
+  /**
+   * The item's external codes, narrowed to the requested provider when one is given. An empty list means the item is not yet mapped for that provider — an actionable state, not an error. More than one may be returned for a single provider, and more than one of those may carry `isPrimary: true`: the uniqueness constraint runs the other way round (an external id is the primary reference of at most one item per merchant), so it does not reduce an item's references to one per provider. Entries are ordered newest first, tie-broken by id, so the order is stable across reads — but a consumer that needs exactly one code must choose deliberately rather than assume there is only one.
+   */
+  externalReferences: Array<ExternalReference>;
+};
+
+/** @internal */
+export const ResolvedItem$inboundSchema: z.ZodType<
+  ResolvedItem,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  id: z.string(),
+  name: z.string(),
+  catalogId: z.nullable(z.string()),
+  archivedAt: z.nullable(
+    z.string().datetime({ offset: true }).transform(v => new Date(v)),
+  ),
+  externalReferences: z.array(ExternalReference$inboundSchema),
+});
+
+export function resolvedItemFromJSON(
+  jsonString: string,
+): SafeParseResult<ResolvedItem, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => ResolvedItem$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'ResolvedItem' from JSON`,
+  );
+}

package/src/models/revenuesummaryresponse.ts

@@ -44,6 +44,14 @@ export type RevenueSummaryResponse = {
    * Number of non-voided refunds (credit notes) issued in the period. Omitted when groupBy=currency is active.
    */
   refundCount?: number | undefined;
+  /**
+   * Gross total of usage-scaled rebates (negative metered line items) on invoices issued in the period, in dollars. Already netted into issued invoice grandTotals, so surfaced here for visibility. Omitted when groupBy=currency is active.
+   */
+  totalRebates?: string | undefined;
+  /**
+   * Number of rebate line items on invoices issued in the period. Omitted when groupBy=currency is active.
+   */
+  rebateCount?: number | undefined;
   invoices?: InvoiceSummary | undefined;
   payments?: PaymentSummary | undefined;
   /**
@@ -70,6 +78,8 @@ export const RevenueSummaryResponse$inboundSchema: z.ZodType<
   netRevenue: z.string().optional(),
   totalRefunds: z.string().optional(),
   refundCount: z.number().optional(),
+  totalRebates: z.string().optional(),
+  rebateCount: z.number().optional(),
   invoices: InvoiceSummary$inboundSchema.optional(),
   payments: PaymentSummary$inboundSchema.optional(),
   trend: z.array(RevenueTrendBucket$inboundSchema).optional(),

package/src/models/revenuetrendbucket.ts

@@ -28,6 +28,10 @@ export type RevenueTrendBucket = {
    * Revenue from completed payments in dollars for this bucket
    */
   completedPayments: string;
+  /**
+   * Gross magnitude of usage-scaled rebates (negative metered line items) on invoices issued in this bucket, in dollars. Netted into issuedInvoices; surfaced here for visibility.
+   */
+  rebates: string;
   /**
    * Per-group trend entries (present when groupBy=plan or groupBy=customer)
    */
@@ -44,6 +48,7 @@ export const RevenueTrendBucket$inboundSchema: z.ZodType<
   issuedInvoices: z.string(),
   writtenOffInvoices: z.string(),
   completedPayments: z.string(),
+  rebates: z.string(),
   groupBreakdown: z.array(GroupTrendEntry$inboundSchema).optional(),
 });
 

package/src/models/scheduleinterval.ts

@@ -50,7 +50,10 @@ export type ScheduleInterval = {
   billingMode: ScheduleIntervalBillingMode;
   billDate?: Date | null | undefined;
   startDate: Date;
-  endDate: Date;
+  /**
+   * Null for an open-ended subscription-owned interval; order-owned intervals always have a concrete end.
+   */
+  endDate: Date | null;
   usageFilter?: { [k: string]: any } | null | undefined;
   metadata: { [k: string]: any };
   createdAt: Date;
@@ -114,7 +117,9 @@ export const ScheduleInterval$inboundSchema: z.ZodType<
     z.string().datetime({ offset: true }).transform(v => new Date(v)),
   ).optional(),
   startDate: z.string().datetime({ offset: true }).transform(v => new Date(v)),
-  endDate: z.string().datetime({ offset: true }).transform(v => new Date(v)),
+  endDate: z.nullable(
+    z.string().datetime({ offset: true }).transform(v => new Date(v)),
+  ),
   usageFilter: z.nullable(z.record(z.any())).optional(),
   metadata: z.record(z.any()),
   createdAt: z.string().datetime({ offset: true }).transform(v => new Date(v)),

package/src/models/schemasbillingschedule.ts

@@ -62,7 +62,10 @@ export type SchemasBillingSchedule = {
   merchantId: string;
   status: SchemasBillingScheduleStatus;
   startDate: Date;
-  endDate: Date;
+  /**
+   * Null for an open-ended subscription-owned schedule; order-owned schedules always have a concrete end.
+   */
+  endDate: Date | null;
   billingAnchor: Date;
   alignmentPolicy: SchemasBillingScheduleAlignmentPolicy;
   prorationPolicy: SchemasBillingScheduleProrationPolicy;
@@ -115,7 +118,9 @@ export const SchemasBillingSchedule$inboundSchema: z.ZodType<
   merchantId: z.string(),
   status: SchemasBillingScheduleStatus$inboundSchema,
   startDate: z.string().datetime({ offset: true }).transform(v => new Date(v)),
-  endDate: z.string().datetime({ offset: true }).transform(v => new Date(v)),
+  endDate: z.nullable(
+    z.string().datetime({ offset: true }).transform(v => new Date(v)),
+  ),
   billingAnchor: z.string().datetime({ offset: true }).transform(v =>
     new Date(v)
   ),

package/src/models/subscription.ts

@@ -174,11 +174,15 @@ export type Subscription = {
    */
   versionNumber?: number | undefined;
   /**
-   * @deprecated Use minimumAccountBalance instead. Minimum required wallet balance in atomic units. Sample values: '200000000000' equals $200.00 minimum, '1000000000000' equals $1000.00 minimum
+   * Deprecated. Legacy-only, not populated for new subscriptions.
+   *
+   * @deprecated field: This will be removed in a future release, please migrate away from it as soon as possible.
    */
   prefundAmount?: string | undefined;
   /**
-   * Minimum wallet balance requirement in nanodollars. Can be '0' to disable. The system calculates the difference between this minimum and the customer's current balance, charging only what's needed to reach the minimum. Note: If the calculated charge amount is below payment processor minimums (typically $1.00), the actual charged amount may be automatically adjusted upward to meet the minimum requirement. Sample values: '200000000000' equals $200.00 minimum, '1000000000000' equals $1000.00 minimum
+   * Deprecated. Legacy-only, not populated for new subscriptions.
+   *
+   * @deprecated field: This will be removed in a future release, please migrate away from it as soon as possible.
    */
   minimumAccountBalance?: string | undefined;
   startedAt: Date;
@@ -198,7 +202,9 @@ export type Subscription = {
   testClockId?: string | undefined;
   updatedAt: Date;
   /**
-   * Optional (virtual) wallet ID for the subscription
+   * Deprecated. Legacy-only, not populated for new subscriptions.
+   *
+   * @deprecated field: This will be removed in a future release, please migrate away from it as soon as possible.
    */
   walletId?: string | undefined;
   /**

package/src/models/transitionplanversionrequest.ts

@@ -0,0 +1,39 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+
+/**
+ * Sets this version as the plan's default.
+ */
+export type TransitionPlanVersionRequest = {
+  /**
+   * Set to true to point the plan's default at this version. Idempotent on the already-default version.
+   */
+  default?: boolean | undefined;
+};
+
+/** @internal */
+export type TransitionPlanVersionRequest$Outbound = {
+  default?: boolean | undefined;
+};
+
+/** @internal */
+export const TransitionPlanVersionRequest$outboundSchema: z.ZodType<
+  TransitionPlanVersionRequest$Outbound,
+  z.ZodTypeDef,
+  TransitionPlanVersionRequest
+> = z.object({
+  default: z.boolean().optional(),
+});
+
+export function transitionPlanVersionRequestToJSON(
+  transitionPlanVersionRequest: TransitionPlanVersionRequest,
+): string {
+  return JSON.stringify(
+    TransitionPlanVersionRequest$outboundSchema.parse(
+      transitionPlanVersionRequest,
+    ),
+  );
+}

package/src/sdk/plans.ts

@@ -4,9 +4,12 @@
 
 import { plansCreate } from "../funcs/plansCreate.js";
 import { plansGet } from "../funcs/plansGet.js";
+import { plansGetPlanVersion } from "../funcs/plansGetPlanVersion.js";
 import { plansList } from "../funcs/plansList.js";
 import { plansListAvailable } from "../funcs/plansListAvailable.js";
 import { plansListPlanVersions } from "../funcs/plansListPlanVersions.js";
+import { plansMintPlanVersion } from "../funcs/plansMintPlanVersion.js";
+import { plansTransitionPlanVersion } from "../funcs/plansTransitionPlanVersion.js";
 import { plansUpdate } from "../funcs/plansUpdate.js";
 import { ClientSDK, RequestOptions } from "../lib/sdks.js";
 import * as models from "../models/index.js";
@@ -103,4 +106,55 @@ export class Plans extends ClientSDK {
       options,
     ));
   }
+
+  /**
+   * Mint a plan version
+   *
+   * @remarks
+   * Mint a new plan version from a price diff and make it the version the plan bills from, in one step. The diff references existing prices by id: create prices beforehand with POST /prices, then add, remove, or replace them here. To return to an earlier price set, make that version the default with a PATCH on the version.
+   */
+  async mintPlanVersion(
+    request: operations.MintPlanVersionRequest,
+    options?: RequestOptions,
+  ): Promise<models.PlanVersion> {
+    return unwrapAsync(plansMintPlanVersion(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Get a version
+   *
+   * @remarks
+   * Get a single plan version, including its price slots. Only accounts that can manage this plan may read its versions; versions can expose in-progress pricing, so read-only access is not sufficient.
+   */
+  async getPlanVersion(
+    request: operations.GetPlanVersionRequest,
+    options?: RequestOptions,
+  ): Promise<models.PlanVersion> {
+    return unwrapAsync(plansGetPlanVersion(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Set the default version
+   *
+   * @remarks
+   * Point the plan's default at this version, so its floating subscriptions bill from it. Any version may become default, in either direction — this is how you roll a plan back to (or forward to) an earlier price set. Idempotent when the version is already the default.
+   */
+  async transitionPlanVersion(
+    request: operations.TransitionPlanVersionRequest,
+    options?: RequestOptions,
+  ): Promise<models.PlanVersion> {
+    return unwrapAsync(plansTransitionPlanVersion(
+      this,
+      request,
+      options,
+    ));
+  }
 }