@paygentic/sdk 0.8.4 → 0.8.6

package/src/models/planversionsummary.ts

@@ -0,0 +1,95 @@
+/*
+ * 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";
+
+export const PlanVersionSummaryObject = {
+  PlanVersion: "plan_version",
+} as const;
+export type PlanVersionSummaryObject = ClosedEnum<
+  typeof PlanVersionSummaryObject
+>;
+
+/**
+ * Lifecycle status of the version.
+ */
+export const PlanVersionSummaryStatus = {
+  Draft: "draft",
+  Published: "published",
+  Archived: "archived",
+} as const;
+/**
+ * Lifecycle status of the version.
+ */
+export type PlanVersionSummaryStatus = ClosedEnum<
+  typeof PlanVersionSummaryStatus
+>;
+
+export type PlanVersionSummary = {
+  /**
+   * Unique identifier for a plan version
+   */
+  id: string;
+  object: PlanVersionSummaryObject;
+  /**
+   * Monotonic version number within the plan, starting at 1.
+   */
+  versionNumber: number;
+  /**
+   * Lifecycle status of the version.
+   */
+  status: PlanVersionSummaryStatus;
+  /**
+   * When this version was published. Absent for draft versions.
+   */
+  publishedAt?: Date | undefined;
+  /**
+   * Whether this version is the plan's current default (live) version.
+   */
+  isDefault: boolean;
+  /**
+   * Number of committed-status subscriptions (active or pending payment) pinned to this version at creation time. This is a count of pins recorded when each subscription was created, not a live-billing cohort: for billing, subscriptions follow the plan's current default version regardless of the version they were pinned to.
+   */
+  subscriptionCount: number;
+};
+
+/** @internal */
+export const PlanVersionSummaryObject$inboundSchema: z.ZodNativeEnum<
+  typeof PlanVersionSummaryObject
+> = z.nativeEnum(PlanVersionSummaryObject);
+
+/** @internal */
+export const PlanVersionSummaryStatus$inboundSchema: z.ZodNativeEnum<
+  typeof PlanVersionSummaryStatus
+> = z.nativeEnum(PlanVersionSummaryStatus);
+
+/** @internal */
+export const PlanVersionSummary$inboundSchema: z.ZodType<
+  PlanVersionSummary,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  id: z.string(),
+  object: PlanVersionSummaryObject$inboundSchema,
+  versionNumber: z.number().int(),
+  status: PlanVersionSummaryStatus$inboundSchema,
+  publishedAt: z.string().datetime({ offset: true }).transform(v => new Date(v))
+    .optional(),
+  isDefault: z.boolean(),
+  subscriptionCount: z.number().int(),
+});
+
+export function planVersionSummaryFromJSON(
+  jsonString: string,
+): SafeParseResult<PlanVersionSummary, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => PlanVersionSummary$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'PlanVersionSummary' 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/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

@@ -165,6 +165,14 @@ export type Subscription = {
    */
   payment?: PaymentPending | PaymentPaid | PaymentAwaitingApproval | undefined;
   planId: string;
+  /**
+   * The plan version pinned to this subscription at creation.
+   */
+  planVersionId?: string | undefined;
+  /**
+   * The version number of the plan version referenced by planVersionId, as of subscription creation.
+   */
+  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
    */
@@ -423,6 +431,8 @@ export const Subscription$inboundSchema: z.ZodType<
     z.lazy(() => PaymentAwaitingApproval$inboundSchema),
   ]).optional(),
   planId: z.string(),
+  planVersionId: z.string().optional(),
+  versionNumber: z.number().int().optional(),
   prefundAmount: z.string().optional(),
   minimumAccountBalance: z.string().optional(),
   startedAt: z.string().datetime({ offset: true }).transform(v => new Date(v)),

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,8 +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";
@@ -85,4 +89,72 @@ export class Plans extends ClientSDK {
       options,
     ));
   }
+
+  /**
+   * List versions
+   *
+   * @remarks
+   * List the versions of a plan, newest first. Only accounts that can manage this plan may list its versions; versions can expose in-progress pricing, so read-only access is not sufficient.
+   */
+  async listPlanVersions(
+    request: operations.ListPlanVersionsRequest,
+    options?: RequestOptions,
+  ): Promise<operations.ListPlanVersionsResponse> {
+    return unwrapAsync(plansListPlanVersions(
+      this,
+      request,
+      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,
+    ));
+  }
 }