@paygentic/sdk 0.7.0 → 0.7.2

package/src/models/operations/getprofitability.ts

@@ -0,0 +1,85 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import { ClosedEnum } from "../../types/enums.js";
+
+/**
+ * Time bucket granularity for the per-customer revenue trend. When omitted, the server picks a reasonable bucket from the window length.
+ */
+export const GetProfitabilityBucketWidth = {
+  Hour: "hour",
+  Day: "day",
+  Week: "week",
+} as const;
+/**
+ * Time bucket granularity for the per-customer revenue trend. When omitted, the server picks a reasonable bucket from the window length.
+ */
+export type GetProfitabilityBucketWidth = ClosedEnum<
+  typeof GetProfitabilityBucketWidth
+>;
+
+export type GetProfitabilityRequest = {
+  /**
+   * Merchant whose customers to summarize
+   */
+  merchantId: string;
+  /**
+   * Start of the time range (ISO 8601 format)
+   */
+  from: Date;
+  /**
+   * End of the time range (ISO 8601 format)
+   */
+  to: Date;
+  /**
+   * Number of top customers (by profit) to return individually. The rest are rolled into a single 'Other' row.
+   */
+  topN?: number | undefined;
+  /**
+   * ISO 4217 currency code to scope the summary. Defaults to the merchant's primary currency.
+   */
+  currency?: string | undefined;
+  /**
+   * Time bucket granularity for the per-customer revenue trend. When omitted, the server picks a reasonable bucket from the window length.
+   */
+  bucketWidth?: GetProfitabilityBucketWidth | undefined;
+};
+
+/** @internal */
+export const GetProfitabilityBucketWidth$outboundSchema: z.ZodNativeEnum<
+  typeof GetProfitabilityBucketWidth
+> = z.nativeEnum(GetProfitabilityBucketWidth);
+
+/** @internal */
+export type GetProfitabilityRequest$Outbound = {
+  merchantId: string;
+  from: string;
+  to: string;
+  topN: number;
+  currency?: string | undefined;
+  bucketWidth: string;
+};
+
+/** @internal */
+export const GetProfitabilityRequest$outboundSchema: z.ZodType<
+  GetProfitabilityRequest$Outbound,
+  z.ZodTypeDef,
+  GetProfitabilityRequest
+> = z.object({
+  merchantId: z.string(),
+  from: z.date().transform(v => v.toISOString()),
+  to: z.date().transform(v => v.toISOString()),
+  topN: z.number().int().default(10),
+  currency: z.string().optional(),
+  bucketWidth: GetProfitabilityBucketWidth$outboundSchema.default("day"),
+});
+
+export function getProfitabilityRequestToJSON(
+  getProfitabilityRequest: GetProfitabilityRequest,
+): string {
+  return JSON.stringify(
+    GetProfitabilityRequest$outboundSchema.parse(getProfitabilityRequest),
+  );
+}

package/src/models/operations/getrevenue.ts

@@ -8,7 +8,7 @@ import { ClosedEnum } from "../../types/enums.js";
 /**
  * Time bucket granularity for trend data
  */
-export const BucketWidth = {
+export const GetRevenueBucketWidth = {
   Hour: "hour",
   Day: "day",
   Week: "week",
@@ -16,7 +16,7 @@ export const BucketWidth = {
 /**
  * Time bucket granularity for trend data
  */
-export type BucketWidth = ClosedEnum<typeof BucketWidth>;
+export type GetRevenueBucketWidth = ClosedEnum<typeof GetRevenueBucketWidth>;
 
 /**
  * Group invoice data by dimension. Allowed values: 'plan' (max 5 groups, top 4 + 'other' when exceeding), 'customer' (max 25 groups, top 24 + 'other' when exceeding, sorted by revenue descending), 'currency' (one entry per currency, primary currency first then alphabetical). Note: groupBy values are mutually exclusive — combining them returns a 400 error. When groupBy=currency is active, top-level netRevenue, invoices, and payments fields are omitted; currencyBreakdown is the sole data source.
@@ -43,7 +43,7 @@ export type GetRevenueRequest = {
   /**
    * Time bucket granularity for trend data
    */
-  bucketWidth?: BucketWidth | undefined;
+  bucketWidth?: GetRevenueBucketWidth | undefined;
   /**
    * Filter by merchant ID. At least one of merchantId, subscriptionIds, or customerId must be provided.
    */
@@ -67,8 +67,9 @@ export type GetRevenueRequest = {
 };
 
 /** @internal */
-export const BucketWidth$outboundSchema: z.ZodNativeEnum<typeof BucketWidth> = z
-  .nativeEnum(BucketWidth);
+export const GetRevenueBucketWidth$outboundSchema: z.ZodNativeEnum<
+  typeof GetRevenueBucketWidth
+> = z.nativeEnum(GetRevenueBucketWidth);
 
 /** @internal */
 export const GroupBy$outboundSchema: z.ZodNativeEnum<typeof GroupBy> = z
@@ -94,7 +95,7 @@ export const GetRevenueRequest$outboundSchema: z.ZodType<
 > = z.object({
   startTime: z.date().transform(v => v.toISOString()),
   endTime: z.date().transform(v => v.toISOString()),
-  bucketWidth: BucketWidth$outboundSchema.default("day"),
+  bucketWidth: GetRevenueBucketWidth$outboundSchema.default("day"),
   merchantId: z.string().optional(),
   customerId: z.string().optional(),
   subscriptionIds: z.array(z.string()).optional(),

package/src/models/operations/index.ts

@@ -45,6 +45,7 @@ export * from "./getpayment.js";
 export * from "./getplan.js";
 export * from "./getprice.js";
 export * from "./getproduct.js";
+export * from "./getprofitability.js";
 export * from "./getrevenue.js";
 export * from "./getsource.js";
 export * from "./getsourcerule.js";
@@ -64,6 +65,7 @@ export * from "./listfees.js";
 export * from "./listinvoices.js";
 export * from "./listlineitems.js";
 export * from "./listpayments.js";
+export * from "./listpaymentsessions.js";
 export * from "./listplans.js";
 export * from "./listprices.js";
 export * from "./listproducts.js";

package/src/models/operations/listbillablemetricevents.ts

@@ -26,6 +26,10 @@ export type ListBillableMetricEventsRequest = {
    * Number of events to skip
    */
   offset?: number | undefined;
+  /**
+   * Filter by external identifier. Alphanumeric characters, hyphens, and underscores only.
+   */
+  externalId?: string | undefined;
 };
 
 /** @internal */
@@ -36,6 +40,7 @@ export type ListBillableMetricEventsRequest$Outbound = {
   subject?: string | undefined;
   limit: number;
   offset: number;
+  externalId?: string | undefined;
 };
 
 /** @internal */
@@ -50,6 +55,7 @@ export const ListBillableMetricEventsRequest$outboundSchema: z.ZodType<
   subject: z.string().optional(),
   limit: z.number().int().default(20),
   offset: z.number().int().default(0),
+  externalId: z.string().optional(),
 });
 
 export function listBillableMetricEventsRequestToJSON(

package/src/models/operations/listinvoices.ts

@@ -46,6 +46,10 @@ export type ListInvoicesRequest = {
    * Maximum number of invoices to return
    */
   limit?: number | undefined;
+  /**
+   * Number of invoices to skip for pagination
+   */
+  offset?: number | undefined;
   /**
    * Filter for invoices ready for processing (platform only)
    */
@@ -75,6 +79,10 @@ export type ListInvoicesObject = ClosedEnum<typeof ListInvoicesObject>;
 export type ListInvoicesResponse = {
   object: ListInvoicesObject;
   data: Array<models.Invoice>;
+  /**
+   * Offset-based pagination response.
+   */
+  pagination?: models.OffsetPagination | undefined;
 };
 
 /** @internal */
@@ -89,6 +97,7 @@ export const ListInvoicesStatus$outboundSchema: z.ZodNativeEnum<
 /** @internal */
 export type ListInvoicesRequest$Outbound = {
   limit: number;
+  offset: number;
   nextActionAt?: string | undefined;
   status?: string | undefined;
   subscriptionId?: string | undefined;
@@ -102,6 +111,7 @@ export const ListInvoicesRequest$outboundSchema: z.ZodType<
   ListInvoicesRequest
 > = z.object({
   limit: z.number().int().default(10),
+  offset: z.number().int().default(0),
   nextActionAt: NextActionAt$outboundSchema.optional(),
   status: ListInvoicesStatus$outboundSchema.optional(),
   subscriptionId: z.string().optional(),
@@ -129,6 +139,7 @@ export const ListInvoicesResponse$inboundSchema: z.ZodType<
 > = z.object({
   object: ListInvoicesObject$inboundSchema,
   data: z.array(models.Invoice$inboundSchema),
+  pagination: models.OffsetPagination$inboundSchema.optional(),
 });
 
 export function listInvoicesResponseFromJSON(

package/src/models/operations/listpaymentsessions.ts

@@ -10,41 +10,64 @@ import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 import * as models from "../index.js";
 
 /**
- * Filter by payment status.
+ * Filter by payment session status.
  */
 export const ListPaymentSessionsStatus = {
   Pending: "pending",
   Processing: "processing",
   Completed: "completed",
+  Failed: "failed",
   Expired: "expired",
   Cancelled: "cancelled",
 } as const;
 /**
- * Filter by payment status.
+ * Filter by payment session status.
  */
 export type ListPaymentSessionsStatus = ClosedEnum<
   typeof ListPaymentSessionsStatus
 >;
 
+/**
+ * Filter by the kind of entity the session pays for.
+ */
+export const EntityType = {
+  Invoice: "invoice",
+  Subscription: "subscription",
+  Payment: "payment",
+  Topup: "topup",
+} as const;
+/**
+ * Filter by the kind of entity the session pays for.
+ */
+export type EntityType = ClosedEnum<typeof EntityType>;
+
 export type ListPaymentSessionsRequest = {
   /**
    * Merchant organization ID. Required when using an API key that is not scoped to a single merchant.
    */
   merchantId?: string | undefined;
   /**
-   * Filter by payment status.
+   * Filter to sessions linked to this subscription (its own activation session plus all of its invoices' sessions).
    */
-  status?: ListPaymentSessionsStatus | undefined;
+  subscriptionId?: string | undefined;
   /**
-   * Filter by customer ID.
+   * Filter to sessions linked to a payment for this customer.
    */
   customerId?: string | undefined;
   /**
-   * Number of payments to return.
+   * Filter by payment session status.
+   */
+  status?: ListPaymentSessionsStatus | undefined;
+  /**
+   * Filter by the kind of entity the session pays for.
+   */
+  entityType?: EntityType | undefined;
+  /**
+   * Number of sessions to return.
    */
   limit?: number | undefined;
   /**
-   * Number of payments to skip.
+   * Number of sessions to skip.
    */
   offset?: number | undefined;
 };
@@ -57,11 +80,11 @@ export type ListPaymentSessionsObject = ClosedEnum<
 >;
 
 /**
- * List of payments
+ * List of payment sessions
  */
 export type ListPaymentSessionsResponse = {
   object: ListPaymentSessionsObject;
-  data: Array<models.Payment>;
+  data: Array<models.PaymentSession>;
   /**
    * Offset-based pagination response.
    */
@@ -73,11 +96,17 @@ export const ListPaymentSessionsStatus$outboundSchema: z.ZodNativeEnum<
   typeof ListPaymentSessionsStatus
 > = z.nativeEnum(ListPaymentSessionsStatus);
 
+/** @internal */
+export const EntityType$outboundSchema: z.ZodNativeEnum<typeof EntityType> = z
+  .nativeEnum(EntityType);
+
 /** @internal */
 export type ListPaymentSessionsRequest$Outbound = {
   merchantId?: string | undefined;
-  status?: string | undefined;
+  subscriptionId?: string | undefined;
   customerId?: string | undefined;
+  status?: string | undefined;
+  entityType?: string | undefined;
   limit: number;
   offset: number;
 };
@@ -89,8 +118,10 @@ export const ListPaymentSessionsRequest$outboundSchema: z.ZodType<
   ListPaymentSessionsRequest
 > = z.object({
   merchantId: z.string().optional(),
-  status: ListPaymentSessionsStatus$outboundSchema.optional(),
+  subscriptionId: z.string().optional(),
   customerId: z.string().optional(),
+  status: ListPaymentSessionsStatus$outboundSchema.optional(),
+  entityType: EntityType$outboundSchema.optional(),
   limit: z.number().int().default(10),
   offset: z.number().int().default(0),
 });
@@ -115,7 +146,7 @@ export const ListPaymentSessionsResponse$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   object: ListPaymentSessionsObject$inboundSchema,
-  data: z.array(models.Payment$inboundSchema),
+  data: z.array(models.PaymentSession$inboundSchema),
   pagination: models.OffsetPagination$inboundSchema,
 });
 

package/src/models/operations/updateplan.ts

@@ -94,6 +94,10 @@ export type UpdatePlanRequestBody = {
    * Number of days before renewal to send the reminder email
    */
   renewalReminderDays?: number | undefined;
+  /**
+   * ISO 8601 datetime reference point for billing period alignment. Must be in the past or present. Set to null to clear the anchor and revert to start-time-based anchoring.
+   */
+  billingAnchor?: Date | null | undefined;
 };
 
 export type UpdatePlanRequest = {
@@ -132,6 +136,7 @@ export type UpdatePlanRequestBody$Outbound = {
   taxBehavior?: string | undefined;
   renewalReminderEnabled?: boolean | undefined;
   renewalReminderDays?: number | undefined;
+  billingAnchor?: string | null | undefined;
 };
 
 /** @internal */
@@ -151,6 +156,8 @@ export const UpdatePlanRequestBody$outboundSchema: z.ZodType<
   taxBehavior: UpdatePlanTaxBehavior$outboundSchema.optional(),
   renewalReminderEnabled: z.boolean().optional(),
   renewalReminderDays: z.number().int().optional(),
+  billingAnchor: z.nullable(z.date().transform(v => v.toISOString()))
+    .optional(),
 });
 
 export function updatePlanRequestBodyToJSON(

package/src/models/paymentsession.ts

@@ -0,0 +1,109 @@
+/*
+ * 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 PaymentSessionObject = {
+  PaymentSession: "payment_session",
+} as const;
+export type PaymentSessionObject = ClosedEnum<typeof PaymentSessionObject>;
+
+/**
+ * Lifecycle status of the session.
+ */
+export const PaymentSessionStatus = {
+  Pending: "pending",
+  Processing: "processing",
+  Completed: "completed",
+  Failed: "failed",
+  Expired: "expired",
+  Cancelled: "cancelled",
+} as const;
+/**
+ * Lifecycle status of the session.
+ */
+export type PaymentSessionStatus = ClosedEnum<typeof PaymentSessionStatus>;
+
+export type PaymentSession = {
+  object: PaymentSessionObject;
+  /**
+   * Payment session ID (ps_*).
+   */
+  id: string;
+  /**
+   * Type of entity the session pays for (invoice, subscription, payment, topup).
+   */
+  entityType: string;
+  /**
+   * ID of the entity the session pays for.
+   */
+  entityId: string;
+  /**
+   * Amount in decimal dollars.
+   */
+  amount: string;
+  /**
+   * ISO 4217 currency code.
+   */
+  currency: string;
+  /**
+   * Lifecycle status of the session.
+   */
+  status: PaymentSessionStatus;
+  /**
+   * Stripe Connect account ID (acct_*) when the session is routed to a connected account.
+   */
+  merchantPaymentAccountId?: string | null | undefined;
+  /**
+   * Timestamp the session reached terminal completion. Null until the session completes.
+   */
+  completedAt?: Date | null | undefined;
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+/** @internal */
+export const PaymentSessionObject$inboundSchema: z.ZodNativeEnum<
+  typeof PaymentSessionObject
+> = z.nativeEnum(PaymentSessionObject);
+
+/** @internal */
+export const PaymentSessionStatus$inboundSchema: z.ZodNativeEnum<
+  typeof PaymentSessionStatus
+> = z.nativeEnum(PaymentSessionStatus);
+
+/** @internal */
+export const PaymentSession$inboundSchema: z.ZodType<
+  PaymentSession,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  object: PaymentSessionObject$inboundSchema,
+  id: z.string(),
+  entityType: z.string(),
+  entityId: z.string(),
+  amount: z.string(),
+  currency: z.string(),
+  status: PaymentSessionStatus$inboundSchema,
+  merchantPaymentAccountId: z.nullable(z.string()).optional(),
+  completedAt: z.nullable(
+    z.string().datetime({ offset: true }).transform(v => new Date(v)),
+  ).optional(),
+  createdAt: z.string().datetime({ offset: true }).transform(v => new Date(v)),
+  updatedAt: z.string().datetime({ offset: true }).transform(v => new Date(v)),
+});
+
+export function paymentSessionFromJSON(
+  jsonString: string,
+): SafeParseResult<PaymentSession, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => PaymentSession$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'PaymentSession' from JSON`,
+  );
+}

package/src/models/plan.ts

@@ -106,6 +106,10 @@ export type Plan = {
    * Billing engine version. Managed by Paygentic support.
    */
   billingVersion?: number | undefined;
+  /**
+   * ISO 8601 datetime reference point for billing period alignment. Must be in the past or present at the time of creation or update. When set, all subscriptions created under this plan align their first billing period to the next recurrence of this anchor. Null means each subscription uses its own start time (hour-rounded) as the anchor.
+   */
+  billingAnchor?: Date | null | undefined;
 };
 
 /** @internal */
@@ -175,6 +179,9 @@ export const Plan$inboundSchema: z.ZodType<Plan, z.ZodTypeDef, unknown> = z
     renewalReminderEnabled: z.boolean().optional(),
     renewalReminderDays: z.number().int().optional(),
     billingVersion: z.number().int().optional(),
+    billingAnchor: z.nullable(
+      z.string().datetime({ offset: true }).transform(v => new Date(v)),
+    ).optional(),
   });
 
 export function planFromJSON(

package/src/models/profitabilityrow.ts

@@ -0,0 +1,68 @@
+/*
+ * 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 {
+  ProfitabilityTrend,
+  ProfitabilityTrend$inboundSchema,
+} from "./profitabilitytrend.js";
+
+export type ProfitabilityRow = {
+  /**
+   * Customer ID, or the literal 'other' for the overflow row.
+   */
+  customerId: string;
+  /**
+   * Display name for the row. 'Other' for the overflow row.
+   */
+  customerName: string;
+  /**
+   * Net revenue (paid + outstanding) in unit currency, with two decimals.
+   */
+  netRevenue: string;
+  /**
+   * Aggregated cost in unit currency, with two decimals.
+   */
+  totalCost: string;
+  /**
+   * Profit (revenue − cost) in unit currency, with two decimals. May be negative.
+   */
+  profit: string;
+  /**
+   * Margin percent (profit / revenue × 100), with two decimals. Null when revenue is zero.
+   */
+  marginPct: string | null;
+  /**
+   * Per-customer revenue trend over the period. Null for the 'Other' row and when there's insufficient data.
+   */
+  trend: ProfitabilityTrend | null;
+};
+
+/** @internal */
+export const ProfitabilityRow$inboundSchema: z.ZodType<
+  ProfitabilityRow,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  customerId: z.string(),
+  customerName: z.string(),
+  netRevenue: z.string(),
+  totalCost: z.string(),
+  profit: z.string(),
+  marginPct: z.nullable(z.string()),
+  trend: z.nullable(ProfitabilityTrend$inboundSchema),
+});
+
+export function profitabilityRowFromJSON(
+  jsonString: string,
+): SafeParseResult<ProfitabilityRow, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => ProfitabilityRow$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'ProfitabilityRow' from JSON`,
+  );
+}

package/src/models/profitabilitysummaryresponse.ts

@@ -0,0 +1,53 @@
+/*
+ * 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 {
+  ProfitabilityRow,
+  ProfitabilityRow$inboundSchema,
+} from "./profitabilityrow.js";
+
+export type ProfitabilitySummaryResponse = {
+  /**
+   * Object type identifier
+   */
+  object: "profitability_summary";
+  /**
+   * ISO 4217 currency code applied to revenue and cost values
+   */
+  currency: string;
+  /**
+   * Top-N customer rows by profit descending, optionally followed by a single 'Other' row when more than topN customers contributed.
+   */
+  rows: Array<ProfitabilityRow>;
+  /**
+   * Non-fatal warnings collected during cost discovery (e.g. an individual cost query failed). Empty array on a clean run.
+   */
+  warnings?: Array<string> | undefined;
+};
+
+/** @internal */
+export const ProfitabilitySummaryResponse$inboundSchema: z.ZodType<
+  ProfitabilitySummaryResponse,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  object: z.literal("profitability_summary"),
+  currency: z.string(),
+  rows: z.array(ProfitabilityRow$inboundSchema),
+  warnings: z.array(z.string()).optional(),
+});
+
+export function profitabilitySummaryResponseFromJSON(
+  jsonString: string,
+): SafeParseResult<ProfitabilitySummaryResponse, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => ProfitabilitySummaryResponse$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'ProfitabilitySummaryResponse' from JSON`,
+  );
+}

package/src/models/profitabilitytrend.ts

@@ -0,0 +1,39 @@
+/*
+ * 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";
+
+export type ProfitabilityTrend = {
+  /**
+   * Revenue values per time bucket, oldest first, in unit currency with two decimals.
+   */
+  values: Array<string>;
+  /**
+   * Period-over-period % change (current half vs prior half). Null when prior is zero.
+   */
+  periodChange: number | null;
+};
+
+/** @internal */
+export const ProfitabilityTrend$inboundSchema: z.ZodType<
+  ProfitabilityTrend,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  values: z.array(z.string()),
+  periodChange: z.nullable(z.number()),
+});
+
+export function profitabilityTrendFromJSON(
+  jsonString: string,
+): SafeParseResult<ProfitabilityTrend, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => ProfitabilityTrend$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'ProfitabilityTrend' from JSON`,
+  );
+}