@paygentic/sdk 0.7.1 → 0.7.2

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`,
+  );
+}

package/src/models/purchasegrantresponse.ts

@@ -15,7 +15,7 @@ export type PurchaseGrantResponseObject = ClosedEnum<
   typeof PurchaseGrantResponseObject
 >;
 
-export type PaymentSession = {
+export type PurchaseGrantResponsePaymentSession = {
   /**
    * The Stripe checkout URL for the customer to complete payment.
    */
@@ -55,7 +55,7 @@ export type PurchaseGrantResponse = {
   /**
    * Payment session(s) for the customer to complete the purchase.
    */
-  paymentSessions: Array<PaymentSession>;
+  paymentSessions: Array<PurchaseGrantResponsePaymentSession>;
 };
 
 /** @internal */
@@ -64,8 +64,8 @@ export const PurchaseGrantResponseObject$inboundSchema: z.ZodNativeEnum<
 > = z.nativeEnum(PurchaseGrantResponseObject);
 
 /** @internal */
-export const PaymentSession$inboundSchema: z.ZodType<
-  PaymentSession,
+export const PurchaseGrantResponsePaymentSession$inboundSchema: z.ZodType<
+  PurchaseGrantResponsePaymentSession,
   z.ZodTypeDef,
   unknown
 > = z.object({
@@ -76,13 +76,14 @@ export const PaymentSession$inboundSchema: z.ZodType<
   amount: z.number().optional(),
 });
 
-export function paymentSessionFromJSON(
+export function purchaseGrantResponsePaymentSessionFromJSON(
   jsonString: string,
-): SafeParseResult<PaymentSession, SDKValidationError> {
+): SafeParseResult<PurchaseGrantResponsePaymentSession, SDKValidationError> {
   return safeParse(
     jsonString,
-    (x) => PaymentSession$inboundSchema.parse(JSON.parse(x)),
-    `Failed to parse 'PaymentSession' from JSON`,
+    (x) =>
+      PurchaseGrantResponsePaymentSession$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'PurchaseGrantResponsePaymentSession' from JSON`,
   );
 }
 
@@ -98,7 +99,9 @@ export const PurchaseGrantResponse$inboundSchema: z.ZodType<
   grantAmount: z.number().int(),
   price: z.string(),
   currency: z.string(),
-  paymentSessions: z.array(z.lazy(() => PaymentSession$inboundSchema)),
+  paymentSessions: z.array(
+    z.lazy(() => PurchaseGrantResponsePaymentSession$inboundSchema),
+  ),
 });
 
 export function purchaseGrantResponseFromJSON(

package/src/sdk/paymentsessions.ts

@@ -0,0 +1,27 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { paymentSessionsListPaymentSessions } from "../funcs/paymentSessionsListPaymentSessions.js";
+import { ClientSDK, RequestOptions } from "../lib/sdks.js";
+import * as operations from "../models/operations/index.js";
+import { unwrapAsync } from "../types/fp.js";
+
+export class PaymentSessions extends ClientSDK {
+  /**
+   * List
+   *
+   * @remarks
+   * List payment sessions for the authenticated merchant with optional filters. Supports filtering by subscriptionId, customerId, status, and entityType. When subscriptionId is provided the result includes both the subscription's own activation session (entityType='subscription') and any session attached to invoices for that subscription (entityType='invoice').
+   */
+  async listPaymentSessions(
+    request?: operations.ListPaymentSessionsRequest | undefined,
+    options?: RequestOptions,
+  ): Promise<operations.ListPaymentSessionsResponse> {
+    return unwrapAsync(paymentSessionsListPaymentSessions(
+      this,
+      request,
+      options,
+    ));
+  }
+}

package/src/sdk/profitability.ts

@@ -0,0 +1,28 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { profitabilityGetProfitability } from "../funcs/profitabilityGetProfitability.js";
+import { ClientSDK, RequestOptions } from "../lib/sdks.js";
+import * as models from "../models/index.js";
+import * as operations from "../models/operations/index.js";
+import { unwrapAsync } from "../types/fp.js";
+
+export class Profitability extends ClientSDK {
+  /**
+   * Get profitability summary
+   *
+   * @remarks
+   * Returns a per-customer profitability summary for a merchant over a date range. Each row aggregates revenue (from issued + paid invoices), cost (from metered cost discovery), profit, and margin. Customers are ranked by profit descending and capped at topN; the remainder is rolled into a single self-consistent 'Other' row whose revenue, cost, and profit reflect the same set of customers. Rows are inner-joined against the merchant's customer list, so orphaned meter subjects from deleted or unknown customers are dropped.
+   */
+  async getProfitability(
+    request: operations.GetProfitabilityRequest,
+    options?: RequestOptions,
+  ): Promise<models.ProfitabilitySummaryResponse> {
+    return unwrapAsync(profitabilityGetProfitability(
+      this,
+      request,
+      options,
+    ));
+  }
+}

package/src/sdk/sdk.ts

@@ -12,9 +12,11 @@ import { Features } from "./features.js";
 import { Fees } from "./fees.js";
 import { InvoicesV2 } from "./invoicesv2.js";
 import { Payments } from "./payments.js";
+import { PaymentSessions } from "./paymentsessions.js";
 import { Plans } from "./plans.js";
 import { Prices } from "./prices.js";
 import { Products } from "./products.js";
+import { Profitability } from "./profitability.js";
 import { Revenue } from "./revenue.js";
 import { Sources } from "./sources.js";
 import { Subscriptions } from "./subscriptions.js";
@@ -87,6 +89,11 @@ export class Paygentic extends ClientSDK {
     return (this._payments ??= new Payments(this._options));
   }
 
+  private _paymentSessions?: PaymentSessions;
+  get paymentSessions(): PaymentSessions {
+    return (this._paymentSessions ??= new PaymentSessions(this._options));
+  }
+
   private _events?: Events;
   get events(): Events {
     return (this._events ??= new Events(this._options));
@@ -102,6 +109,11 @@ export class Paygentic extends ClientSDK {
     return (this._revenue ??= new Revenue(this._options));
   }
 
+  private _profitability?: Profitability;
+  get profitability(): Profitability {
+    return (this._profitability ??= new Profitability(this._options));
+  }
+
   private _testClocks?: TestClocks;
   get testClocks(): TestClocks {
     return (this._testClocks ??= new TestClocks(this._options));