@paygentic/sdk 0.8.0 → 0.8.1

package/src/models/plan.ts

@@ -8,6 +8,10 @@ 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 {
+  PlanCreditAllocation,
+  PlanCreditAllocation$inboundSchema,
+} from "./plancreditallocation.js";
 import { Price, Price$inboundSchema } from "./price.js";
 
 export const PlanObject = {
@@ -110,6 +114,10 @@ export type Plan = {
    * 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;
+  /**
+   * Credit-pool funding declarations for this plan. Each entry funds a distinct pricing unit's credit pool when a subscription to this plan activates: the allocated amount is minted as a credit grant on the customer's pool for that pricing unit, once at activation, or on a recurring basis only when that allocation explicitly sets recurrencePeriod. A plan may declare zero or more allocations; no two allocations on the same plan target the same pricingUnitId.
+   */
+  creditAllocations?: Array<PlanCreditAllocation> | undefined;
 };
 
 /** @internal */
@@ -182,6 +190,7 @@ export const Plan$inboundSchema: z.ZodType<Plan, z.ZodTypeDef, unknown> = z
     billingAnchor: z.nullable(
       z.string().datetime({ offset: true }).transform(v => new Date(v)),
     ).optional(),
+    creditAllocations: z.array(PlanCreditAllocation$inboundSchema).optional(),
   });
 
 export function planFromJSON(

package/src/models/plancreditallocation.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";
+
+export type PlanCreditAllocation = {
+  /**
+   * Unique identifier for a pricing unit
+   */
+  pricingUnitId: string;
+  /**
+   * Number of credits minted into the customer's pool for this pricing unit each time the allocation is provisioned. Must be a positive number.
+   */
+  amount: number;
+  /**
+   * ISO 8601 duration (e.g. 'P1M') controlling how often the allocation's credits are re-minted on the customer's pool. Recurrence is opt-in: when omitted, the allocation is minted once at subscription activation and never refills — even on a recurring plan. Set this field explicitly for credits that should replenish each period.
+   */
+  recurrencePeriod?: string | undefined;
+};
+
+/** @internal */
+export const PlanCreditAllocation$inboundSchema: z.ZodType<
+  PlanCreditAllocation,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  pricingUnitId: z.string(),
+  amount: z.number(),
+  recurrencePeriod: z.string().optional(),
+});
+/** @internal */
+export type PlanCreditAllocation$Outbound = {
+  pricingUnitId: string;
+  amount: number;
+  recurrencePeriod?: string | undefined;
+};
+
+/** @internal */
+export const PlanCreditAllocation$outboundSchema: z.ZodType<
+  PlanCreditAllocation$Outbound,
+  z.ZodTypeDef,
+  PlanCreditAllocation
+> = z.object({
+  pricingUnitId: z.string(),
+  amount: z.number(),
+  recurrencePeriod: z.string().optional(),
+});
+
+export function planCreditAllocationToJSON(
+  planCreditAllocation: PlanCreditAllocation,
+): string {
+  return JSON.stringify(
+    PlanCreditAllocation$outboundSchema.parse(planCreditAllocation),
+  );
+}
+export function planCreditAllocationFromJSON(
+  jsonString: string,
+): SafeParseResult<PlanCreditAllocation, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => PlanCreditAllocation$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'PlanCreditAllocation' from JSON`,
+  );
+}

package/src/models/reconciledfeatureadded.ts

@@ -0,0 +1,38 @@
+/*
+ * 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 ReconciledFeatureAdded = {
+  featureId: string;
+  featureKey: string;
+  /**
+   * False when this feature's price never produces a recurring line item (an instant price, a credit-denominated price, or an already-elapsed one-time charge) — the feature is entitled but not billed by this reconciliation.
+   */
+  billed: boolean;
+};
+
+/** @internal */
+export const ReconciledFeatureAdded$inboundSchema: z.ZodType<
+  ReconciledFeatureAdded,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  featureId: z.string(),
+  featureKey: z.string(),
+  billed: z.boolean(),
+});
+
+export function reconciledFeatureAddedFromJSON(
+  jsonString: string,
+): SafeParseResult<ReconciledFeatureAdded, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => ReconciledFeatureAdded$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'ReconciledFeatureAdded' from JSON`,
+  );
+}

package/src/models/reconciledfeaturefailed.ts

@@ -0,0 +1,55 @@
+/*
+ * 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";
+
+/**
+ * Coded failure reason. `grant_mint_failed` means the entitlement was created but its initial metered grant could not be minted; re-running this reconciliation retries the mint.
+ */
+export const Reason = {
+  EntitlementFailed: "entitlement_failed",
+  GrantMintFailed: "grant_mint_failed",
+} as const;
+/**
+ * Coded failure reason. `grant_mint_failed` means the entitlement was created but its initial metered grant could not be minted; re-running this reconciliation retries the mint.
+ */
+export type Reason = ClosedEnum<typeof Reason>;
+
+export type ReconciledFeatureFailed = {
+  featureId: string;
+  featureKey: string;
+  /**
+   * Coded failure reason. `grant_mint_failed` means the entitlement was created but its initial metered grant could not be minted; re-running this reconciliation retries the mint.
+   */
+  reason: Reason;
+};
+
+/** @internal */
+export const Reason$inboundSchema: z.ZodNativeEnum<typeof Reason> = z
+  .nativeEnum(Reason);
+
+/** @internal */
+export const ReconciledFeatureFailed$inboundSchema: z.ZodType<
+  ReconciledFeatureFailed,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  featureId: z.string(),
+  featureKey: z.string(),
+  reason: Reason$inboundSchema,
+});
+
+export function reconciledFeatureFailedFromJSON(
+  jsonString: string,
+): SafeParseResult<ReconciledFeatureFailed, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => ReconciledFeatureFailed$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'ReconciledFeatureFailed' from JSON`,
+  );
+}

package/src/models/reconciledfeatureremoved.ts

@@ -0,0 +1,33 @@
+/*
+ * 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 ReconciledFeatureRemoved = {
+  featureId: string;
+  featureKey: string;
+};
+
+/** @internal */
+export const ReconciledFeatureRemoved$inboundSchema: z.ZodType<
+  ReconciledFeatureRemoved,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  featureId: z.string(),
+  featureKey: z.string(),
+});
+
+export function reconciledFeatureRemovedFromJSON(
+  jsonString: string,
+): SafeParseResult<ReconciledFeatureRemoved, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => ReconciledFeatureRemoved$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'ReconciledFeatureRemoved' from JSON`,
+  );
+}

package/src/models/reconciledfeatureskipped.ts

@@ -0,0 +1,33 @@
+/*
+ * 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 ReconciledFeatureSkipped = {
+  featureId: string;
+  featureKey: string;
+};
+
+/** @internal */
+export const ReconciledFeatureSkipped$inboundSchema: z.ZodType<
+  ReconciledFeatureSkipped,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  featureId: z.string(),
+  featureKey: z.string(),
+});
+
+export function reconciledFeatureSkippedFromJSON(
+  jsonString: string,
+): SafeParseResult<ReconciledFeatureSkipped, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => ReconciledFeatureSkipped$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'ReconciledFeatureSkipped' from JSON`,
+  );
+}

package/src/models/subscriptionreconciliation.ts

@@ -0,0 +1,144 @@
+/*
+ * 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 {
+  ReconciledFeatureAdded,
+  ReconciledFeatureAdded$inboundSchema,
+} from "./reconciledfeatureadded.js";
+import {
+  ReconciledFeatureFailed,
+  ReconciledFeatureFailed$inboundSchema,
+} from "./reconciledfeaturefailed.js";
+import {
+  ReconciledFeatureRemoved,
+  ReconciledFeatureRemoved$inboundSchema,
+} from "./reconciledfeatureremoved.js";
+import {
+  ReconciledFeatureSkipped,
+  ReconciledFeatureSkipped$inboundSchema,
+} from "./reconciledfeatureskipped.js";
+
+export const SubscriptionReconciliationObject = {
+  SubscriptionReconciliation: "subscriptionReconciliation",
+} as const;
+export type SubscriptionReconciliationObject = ClosedEnum<
+  typeof SubscriptionReconciliationObject
+>;
+
+export type Features = {
+  added: Array<ReconciledFeatureAdded>;
+  /**
+   * Features the subscription already had an active entitlement for — left unchanged.
+   */
+  skipped: Array<ReconciledFeatureSkipped>;
+  /**
+   * Features no longer on the plan: their entitlement was canceled and grants voided so the subscription matches the plan's current features.
+   */
+  removed: Array<ReconciledFeatureRemoved>;
+  /**
+   * Features that could not be fully provisioned. Never billed by this call.
+   */
+  failed: Array<ReconciledFeatureFailed>;
+};
+
+export type SubscriptionReconciliationLineItems = {
+  /**
+   * Number of features newly billed on the subscription by this reconciliation. A dry-run preview returns the same count as the applied run.
+   */
+  created: number;
+  /**
+   * Number of features whose billing was removed from the subscription's upcoming (not-yet-invoiced) invoice because their price is no longer on the plan.
+   */
+  removed: number;
+  /**
+   * True when entitlements were provisioned successfully but the line-item synchronization step failed. Safe to retry.
+   */
+  syncFailed?: boolean | undefined;
+};
+
+export type SubscriptionReconciliation = {
+  object: SubscriptionReconciliationObject;
+  /**
+   * True when this reconciliation was a preview — no entitlement, grant, or line item was created.
+   */
+  dryRun: boolean;
+  features: Features;
+  lineItems: SubscriptionReconciliationLineItems;
+};
+
+/** @internal */
+export const SubscriptionReconciliationObject$inboundSchema: z.ZodNativeEnum<
+  typeof SubscriptionReconciliationObject
+> = z.nativeEnum(SubscriptionReconciliationObject);
+
+/** @internal */
+export const Features$inboundSchema: z.ZodType<
+  Features,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  added: z.array(ReconciledFeatureAdded$inboundSchema),
+  skipped: z.array(ReconciledFeatureSkipped$inboundSchema),
+  removed: z.array(ReconciledFeatureRemoved$inboundSchema),
+  failed: z.array(ReconciledFeatureFailed$inboundSchema),
+});
+
+export function featuresFromJSON(
+  jsonString: string,
+): SafeParseResult<Features, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => Features$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'Features' from JSON`,
+  );
+}
+
+/** @internal */
+export const SubscriptionReconciliationLineItems$inboundSchema: z.ZodType<
+  SubscriptionReconciliationLineItems,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  created: z.number().int(),
+  removed: z.number().int(),
+  syncFailed: z.boolean().optional(),
+});
+
+export function subscriptionReconciliationLineItemsFromJSON(
+  jsonString: string,
+): SafeParseResult<SubscriptionReconciliationLineItems, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) =>
+      SubscriptionReconciliationLineItems$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'SubscriptionReconciliationLineItems' from JSON`,
+  );
+}
+
+/** @internal */
+export const SubscriptionReconciliation$inboundSchema: z.ZodType<
+  SubscriptionReconciliation,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  object: SubscriptionReconciliationObject$inboundSchema,
+  dryRun: z.boolean(),
+  features: z.lazy(() => Features$inboundSchema),
+  lineItems: z.lazy(() => SubscriptionReconciliationLineItems$inboundSchema),
+});
+
+export function subscriptionReconciliationFromJSON(
+  jsonString: string,
+): SafeParseResult<SubscriptionReconciliation, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => SubscriptionReconciliation$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'SubscriptionReconciliation' from JSON`,
+  );
+}

package/src/sdk/subscriptions.ts

@@ -6,6 +6,7 @@ import { subscriptionsCreate } from "../funcs/subscriptionsCreate.js";
 import { subscriptionsGeneratePortalLink } from "../funcs/subscriptionsGeneratePortalLink.js";
 import { subscriptionsGet } from "../funcs/subscriptionsGet.js";
 import { subscriptionsList } from "../funcs/subscriptionsList.js";
+import { subscriptionsReconcileSubscriptionFeatures } from "../funcs/subscriptionsReconcileSubscriptionFeatures.js";
 import { subscriptionsTerminate } from "../funcs/subscriptionsTerminate.js";
 import { subscriptionsUpdateSubscription } from "../funcs/subscriptionsUpdateSubscription.js";
 import { ClientSDK, RequestOptions } from "../lib/sdks.js";
@@ -106,4 +107,21 @@ export class Subscriptions extends ClientSDK {
       options,
     ));
   }
+
+  /**
+   * Reconcile Features
+   *
+   * @remarks
+   * Creates a reconciliation that converges a subscription's feature entitlements to its current plan. Provisions a missing entitlement (and, for metered features, its initial grant) for every plan feature the subscription does not already have; cancels the entitlement and voids the grants of any feature no longer on the plan; then synchronizes the corresponding prices' billing. An already-present feature is left unchanged. Restricted to active subscriptions billed on their plan's line-item schedule.
+   */
+  async reconcileSubscriptionFeatures(
+    request: operations.ReconcileSubscriptionFeaturesRequest,
+    options?: RequestOptions,
+  ): Promise<models.SubscriptionReconciliation> {
+    return unwrapAsync(subscriptionsReconcileSubscriptionFeatures(
+      this,
+      request,
+      options,
+    ));
+  }
 }