@feelflow/ffid-sdk 2.11.0 → 2.12.0

package/dist/index.d.cts

@@ -341,6 +341,62 @@ type FFIDPlanChangePreview = FFIDPlanChangePreviewBase & ({
 interface FFIDPlanChangePreviewResponse {
     preview: FFIDPlanChangePreview;
 }
+/** Parameters for previewing a seat count change */
+interface FFIDPreviewSeatChangeParams {
+    /** Subscription ID (UUID) */
+    subscriptionId: string;
+    /** New seat quantity. Must be an integer within the plan's allowed range. */
+    quantity: number;
+}
+/** Seat change preview line item */
+interface FFIDSeatChangeLineItem {
+    description: string;
+    amount: number;
+}
+/**
+ * Seat change proration preview.
+ *
+ * Sister type to `FFIDPlanChangePreview`. The shared `type` discriminant lets
+ * consumers narrow a preview payload without inspecting unrelated fields.
+ *
+ * - `isEstimate=true` (default when Stripe is not configured or data is unavailable):
+ *   `proratedAmount` is computed locally as `(newQuantity - currentQuantity) * unitPrice`.
+ * - `isEstimate=false`: `proratedAmount` reflects Stripe's live proration calculation.
+ *
+ * `nextInvoiceAmount` is always a local estimate (`unitPrice * newQuantity`).
+ *
+ * `pricingUnavailable=true` indicates the plan uses custom pricing with a zero unit
+ * price (Enterprise). Consumers should hide monetary amounts in this case.
+ */
+interface FFIDSeatChangePreview {
+    /** Discriminant for preview response variants (pairs with `FFIDPlanChangePreview.type`) */
+    type: 'seat-change';
+    currentQuantity: number;
+    newQuantity: number;
+    /** Per-seat price for the current billing interval */
+    unitPrice: number;
+    billingInterval: FFIDBillingInterval;
+    /**
+     * Prorated cost for the current billing period. Negative when seats are decreased
+     * (credit). `0` when `pricingUnavailable === true` (Enterprise custom pricing).
+     */
+    proratedAmount: number;
+    /** Next invoice full amount — always a local estimate (`unitPrice * newQuantity`) */
+    nextInvoiceAmount: number;
+    nextInvoiceDate: string | null;
+    currency: FFIDSupportedCurrency;
+    /** true when proratedAmount is estimated from local prices rather than Stripe proration data */
+    isEstimate: boolean;
+    /** true when unit price is 0 due to custom pricing (Enterprise) — hide monetary amounts */
+    pricingUnavailable?: boolean;
+    /** Reason why `isEstimate` is true. Only meaningful when `isEstimate === true`. */
+    estimateReason?: 'no_stripe_data' | 'custom_pricing' | 'stripe_error';
+    lineItems: FFIDSeatChangeLineItem[];
+}
+/** Response from seat change preview endpoint */
+interface FFIDSeatChangePreviewResponse {
+    preview: FFIDSeatChangePreview;
+}
 
 /** OTP / magic link methods - sendOtp / verifyOtp */
 
@@ -453,6 +509,7 @@ declare function createFFIDClient(config: FFIDConfig): {
     cancelSubscription: (params: FFIDCancelSubscriptionParams) => Promise<FFIDApiResponse<FFIDCancelSubscriptionResponse>>;
     cancelPendingDowngrade: (subscriptionId: string) => Promise<FFIDApiResponse<FFIDCancelPendingDowngradeResponse>>;
     previewPlanChange: (params: FFIDPreviewPlanChangeParams) => Promise<FFIDApiResponse<FFIDPlanChangePreviewResponse>>;
+    previewSeatChange: (params: FFIDPreviewSeatChangeParams) => Promise<FFIDApiResponse<FFIDSeatChangePreviewResponse>>;
     verifyAccessToken: (accessToken: string, options?: FFIDVerifyAccessTokenOptions) => Promise<FFIDApiResponse<FFIDOAuthUserInfo>>;
     getSubscribeUrl: (options?: ContractWizardSubscribeOptions) => string;
     redirectToSubscribe: (options?: ContractWizardSubscribeOptions) => FFIDRedirectResult;
@@ -499,6 +556,18 @@ declare function createFFIDClient(config: FFIDConfig): {
 /** Type of the FFID client */
 type FFIDClient = ReturnType<typeof createFFIDClient>;
 
+/** Subscription management methods - plan listing, subscribe, change, cancel, preview */
+
+/**
+ * Thrown by the SDK when the server returns a payload that violates a type-level
+ * invariant the SDK relies on for consumer narrowing. Always indicates a server
+ * regression (or a client/server version mismatch); never caused by user input.
+ */
+declare class FFIDSDKError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+
 /**
  * Create an in-memory cache adapter using a Map.
  * Suitable for single-process environments (e.g., development, testing).
@@ -844,4 +913,4 @@ declare function createInquiryMethods(deps: InquiryMethodsDeps): {
 };
 type FFIDInquiryClient = ReturnType<typeof createInquiryMethods>;
 
-export { AnnouncementListResponse, type ContractWizardFlowType, type ContractWizardResubscribeOptions, type ContractWizardSubscribeOptions, type ContractWizardSubscriptionOptions, DEFAULT_API_BASE_URL, FFIDAnnouncementsApiResponse, type FFIDAnnouncementsClient, FFIDAnnouncementsClientConfig, FFIDAnnouncementsLogger, FFIDApiResponse, type FFIDBillingInterval, FFIDCacheAdapter, type FFIDCancelPendingDowngradeResponse, type FFIDCancelSubscriptionParams, type FFIDCancelSubscriptionResponse, type FFIDChangePlanParams, type FFIDChangePlanResponse, FFIDCheckoutSessionResponse, type FFIDClient, FFIDConfig, FFIDCreateCheckoutParams, FFIDCreatePortalParams, FFIDError, type FFIDInquiryClient, FFIDInquiryCreateParams, FFIDInquiryCreateResponse, FFIDListMembersResponse, type FFIDListPlansResponse, FFIDLogger, FFIDMemberRole, type FFIDNewsletterClient, type FFIDNewsletterConfirmParams, type FFIDNewsletterConfirmResponse, type FFIDNewsletterSubscribeParams, type FFIDNewsletterSubscribeResponse, type FFIDNewsletterType, type FFIDNewsletterUnsubscribeParams, type FFIDNewsletterUnsubscribeResponse, FFIDOAuthUserInfo, FFIDOrganization, type FFIDOtpSendResponse, type FFIDOtpVerifyResponse, type FFIDPasswordResetConfirmResponse, type FFIDPasswordResetResponse, type FFIDPasswordResetVerifyResponse, type FFIDPlanChangeLineItem, type FFIDPlanChangePreview, type FFIDPlanChangePreviewResponse, type FFIDPlanInfo, FFIDPortalSessionResponse, type FFIDPreviewPlanChangeParams, FFIDProvider, type FFIDProviderProps, FFIDRedirectResult, FFIDRemoveMemberResponse, type FFIDResetSessionResponse, type FFIDServiceInfo, FFIDSessionResponse, type FFIDSubscribeParams, type FFIDSubscribeResponse, FFIDSubscription, FFIDSubscriptionCheckResponse, FFIDSubscriptionContextValue, type FFIDSubscriptionDetail, FFIDSubscriptionStatus, type FFIDSubscriptionSummary, type FFIDSupportedCurrency, FFIDUpdateMemberRoleResponse, FFIDUser, FFIDVerifyAccessTokenOptions, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_NEWSLETTER_TYPES, type KVNamespaceLike, ListAnnouncementsOptions, type RedirectToAuthorizeOptions, type TokenData, type TokenStore, type UseFFIDReturn, type WithFFIDAuthOptions, type WithSubscriptionOptions, createFFIDAnnouncementsClient, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createTokenStore, generateCodeChallenge, generateCodeVerifier, retrieveCodeVerifier, storeCodeVerifier, useFFID, useSubscription, withFFIDAuth, withSubscription };
+export { AnnouncementListResponse, type ContractWizardFlowType, type ContractWizardResubscribeOptions, type ContractWizardSubscribeOptions, type ContractWizardSubscriptionOptions, DEFAULT_API_BASE_URL, FFIDAnnouncementsApiResponse, type FFIDAnnouncementsClient, FFIDAnnouncementsClientConfig, FFIDAnnouncementsLogger, FFIDApiResponse, type FFIDBillingInterval, FFIDCacheAdapter, type FFIDCancelPendingDowngradeResponse, type FFIDCancelSubscriptionParams, type FFIDCancelSubscriptionResponse, type FFIDChangePlanParams, type FFIDChangePlanResponse, FFIDCheckoutSessionResponse, type FFIDClient, FFIDConfig, FFIDCreateCheckoutParams, FFIDCreatePortalParams, FFIDError, type FFIDInquiryClient, FFIDInquiryCreateParams, FFIDInquiryCreateResponse, FFIDListMembersResponse, type FFIDListPlansResponse, FFIDLogger, FFIDMemberRole, type FFIDNewsletterClient, type FFIDNewsletterConfirmParams, type FFIDNewsletterConfirmResponse, type FFIDNewsletterSubscribeParams, type FFIDNewsletterSubscribeResponse, type FFIDNewsletterType, type FFIDNewsletterUnsubscribeParams, type FFIDNewsletterUnsubscribeResponse, FFIDOAuthUserInfo, FFIDOrganization, type FFIDOtpSendResponse, type FFIDOtpVerifyResponse, type FFIDPasswordResetConfirmResponse, type FFIDPasswordResetResponse, type FFIDPasswordResetVerifyResponse, type FFIDPlanChangeLineItem, type FFIDPlanChangePreview, type FFIDPlanChangePreviewResponse, type FFIDPlanInfo, FFIDPortalSessionResponse, type FFIDPreviewPlanChangeParams, type FFIDPreviewSeatChangeParams, FFIDProvider, type FFIDProviderProps, FFIDRedirectResult, FFIDRemoveMemberResponse, type FFIDResetSessionResponse, FFIDSDKError, type FFIDSeatChangeLineItem, type FFIDSeatChangePreview, type FFIDSeatChangePreviewResponse, type FFIDServiceInfo, FFIDSessionResponse, type FFIDSubscribeParams, type FFIDSubscribeResponse, FFIDSubscription, FFIDSubscriptionCheckResponse, FFIDSubscriptionContextValue, type FFIDSubscriptionDetail, FFIDSubscriptionStatus, type FFIDSubscriptionSummary, type FFIDSupportedCurrency, FFIDUpdateMemberRoleResponse, FFIDUser, FFIDVerifyAccessTokenOptions, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_NEWSLETTER_TYPES, type KVNamespaceLike, ListAnnouncementsOptions, type RedirectToAuthorizeOptions, type TokenData, type TokenStore, type UseFFIDReturn, type WithFFIDAuthOptions, type WithSubscriptionOptions, createFFIDAnnouncementsClient, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createTokenStore, generateCodeChallenge, generateCodeVerifier, retrieveCodeVerifier, storeCodeVerifier, useFFID, useSubscription, withFFIDAuth, withSubscription };

package/dist/index.d.ts

@@ -341,6 +341,62 @@ type FFIDPlanChangePreview = FFIDPlanChangePreviewBase & ({
 interface FFIDPlanChangePreviewResponse {
     preview: FFIDPlanChangePreview;
 }
+/** Parameters for previewing a seat count change */
+interface FFIDPreviewSeatChangeParams {
+    /** Subscription ID (UUID) */
+    subscriptionId: string;
+    /** New seat quantity. Must be an integer within the plan's allowed range. */
+    quantity: number;
+}
+/** Seat change preview line item */
+interface FFIDSeatChangeLineItem {
+    description: string;
+    amount: number;
+}
+/**
+ * Seat change proration preview.
+ *
+ * Sister type to `FFIDPlanChangePreview`. The shared `type` discriminant lets
+ * consumers narrow a preview payload without inspecting unrelated fields.
+ *
+ * - `isEstimate=true` (default when Stripe is not configured or data is unavailable):
+ *   `proratedAmount` is computed locally as `(newQuantity - currentQuantity) * unitPrice`.
+ * - `isEstimate=false`: `proratedAmount` reflects Stripe's live proration calculation.
+ *
+ * `nextInvoiceAmount` is always a local estimate (`unitPrice * newQuantity`).
+ *
+ * `pricingUnavailable=true` indicates the plan uses custom pricing with a zero unit
+ * price (Enterprise). Consumers should hide monetary amounts in this case.
+ */
+interface FFIDSeatChangePreview {
+    /** Discriminant for preview response variants (pairs with `FFIDPlanChangePreview.type`) */
+    type: 'seat-change';
+    currentQuantity: number;
+    newQuantity: number;
+    /** Per-seat price for the current billing interval */
+    unitPrice: number;
+    billingInterval: FFIDBillingInterval;
+    /**
+     * Prorated cost for the current billing period. Negative when seats are decreased
+     * (credit). `0` when `pricingUnavailable === true` (Enterprise custom pricing).
+     */
+    proratedAmount: number;
+    /** Next invoice full amount — always a local estimate (`unitPrice * newQuantity`) */
+    nextInvoiceAmount: number;
+    nextInvoiceDate: string | null;
+    currency: FFIDSupportedCurrency;
+    /** true when proratedAmount is estimated from local prices rather than Stripe proration data */
+    isEstimate: boolean;
+    /** true when unit price is 0 due to custom pricing (Enterprise) — hide monetary amounts */
+    pricingUnavailable?: boolean;
+    /** Reason why `isEstimate` is true. Only meaningful when `isEstimate === true`. */
+    estimateReason?: 'no_stripe_data' | 'custom_pricing' | 'stripe_error';
+    lineItems: FFIDSeatChangeLineItem[];
+}
+/** Response from seat change preview endpoint */
+interface FFIDSeatChangePreviewResponse {
+    preview: FFIDSeatChangePreview;
+}
 
 /** OTP / magic link methods - sendOtp / verifyOtp */
 
@@ -453,6 +509,7 @@ declare function createFFIDClient(config: FFIDConfig): {
     cancelSubscription: (params: FFIDCancelSubscriptionParams) => Promise<FFIDApiResponse<FFIDCancelSubscriptionResponse>>;
     cancelPendingDowngrade: (subscriptionId: string) => Promise<FFIDApiResponse<FFIDCancelPendingDowngradeResponse>>;
     previewPlanChange: (params: FFIDPreviewPlanChangeParams) => Promise<FFIDApiResponse<FFIDPlanChangePreviewResponse>>;
+    previewSeatChange: (params: FFIDPreviewSeatChangeParams) => Promise<FFIDApiResponse<FFIDSeatChangePreviewResponse>>;
     verifyAccessToken: (accessToken: string, options?: FFIDVerifyAccessTokenOptions) => Promise<FFIDApiResponse<FFIDOAuthUserInfo>>;
     getSubscribeUrl: (options?: ContractWizardSubscribeOptions) => string;
     redirectToSubscribe: (options?: ContractWizardSubscribeOptions) => FFIDRedirectResult;
@@ -499,6 +556,18 @@ declare function createFFIDClient(config: FFIDConfig): {
 /** Type of the FFID client */
 type FFIDClient = ReturnType<typeof createFFIDClient>;
 
+/** Subscription management methods - plan listing, subscribe, change, cancel, preview */
+
+/**
+ * Thrown by the SDK when the server returns a payload that violates a type-level
+ * invariant the SDK relies on for consumer narrowing. Always indicates a server
+ * regression (or a client/server version mismatch); never caused by user input.
+ */
+declare class FFIDSDKError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+
 /**
  * Create an in-memory cache adapter using a Map.
  * Suitable for single-process environments (e.g., development, testing).
@@ -844,4 +913,4 @@ declare function createInquiryMethods(deps: InquiryMethodsDeps): {
 };
 type FFIDInquiryClient = ReturnType<typeof createInquiryMethods>;
 
-export { AnnouncementListResponse, type ContractWizardFlowType, type ContractWizardResubscribeOptions, type ContractWizardSubscribeOptions, type ContractWizardSubscriptionOptions, DEFAULT_API_BASE_URL, FFIDAnnouncementsApiResponse, type FFIDAnnouncementsClient, FFIDAnnouncementsClientConfig, FFIDAnnouncementsLogger, FFIDApiResponse, type FFIDBillingInterval, FFIDCacheAdapter, type FFIDCancelPendingDowngradeResponse, type FFIDCancelSubscriptionParams, type FFIDCancelSubscriptionResponse, type FFIDChangePlanParams, type FFIDChangePlanResponse, FFIDCheckoutSessionResponse, type FFIDClient, FFIDConfig, FFIDCreateCheckoutParams, FFIDCreatePortalParams, FFIDError, type FFIDInquiryClient, FFIDInquiryCreateParams, FFIDInquiryCreateResponse, FFIDListMembersResponse, type FFIDListPlansResponse, FFIDLogger, FFIDMemberRole, type FFIDNewsletterClient, type FFIDNewsletterConfirmParams, type FFIDNewsletterConfirmResponse, type FFIDNewsletterSubscribeParams, type FFIDNewsletterSubscribeResponse, type FFIDNewsletterType, type FFIDNewsletterUnsubscribeParams, type FFIDNewsletterUnsubscribeResponse, FFIDOAuthUserInfo, FFIDOrganization, type FFIDOtpSendResponse, type FFIDOtpVerifyResponse, type FFIDPasswordResetConfirmResponse, type FFIDPasswordResetResponse, type FFIDPasswordResetVerifyResponse, type FFIDPlanChangeLineItem, type FFIDPlanChangePreview, type FFIDPlanChangePreviewResponse, type FFIDPlanInfo, FFIDPortalSessionResponse, type FFIDPreviewPlanChangeParams, FFIDProvider, type FFIDProviderProps, FFIDRedirectResult, FFIDRemoveMemberResponse, type FFIDResetSessionResponse, type FFIDServiceInfo, FFIDSessionResponse, type FFIDSubscribeParams, type FFIDSubscribeResponse, FFIDSubscription, FFIDSubscriptionCheckResponse, FFIDSubscriptionContextValue, type FFIDSubscriptionDetail, FFIDSubscriptionStatus, type FFIDSubscriptionSummary, type FFIDSupportedCurrency, FFIDUpdateMemberRoleResponse, FFIDUser, FFIDVerifyAccessTokenOptions, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_NEWSLETTER_TYPES, type KVNamespaceLike, ListAnnouncementsOptions, type RedirectToAuthorizeOptions, type TokenData, type TokenStore, type UseFFIDReturn, type WithFFIDAuthOptions, type WithSubscriptionOptions, createFFIDAnnouncementsClient, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createTokenStore, generateCodeChallenge, generateCodeVerifier, retrieveCodeVerifier, storeCodeVerifier, useFFID, useSubscription, withFFIDAuth, withSubscription };
+export { AnnouncementListResponse, type ContractWizardFlowType, type ContractWizardResubscribeOptions, type ContractWizardSubscribeOptions, type ContractWizardSubscriptionOptions, DEFAULT_API_BASE_URL, FFIDAnnouncementsApiResponse, type FFIDAnnouncementsClient, FFIDAnnouncementsClientConfig, FFIDAnnouncementsLogger, FFIDApiResponse, type FFIDBillingInterval, FFIDCacheAdapter, type FFIDCancelPendingDowngradeResponse, type FFIDCancelSubscriptionParams, type FFIDCancelSubscriptionResponse, type FFIDChangePlanParams, type FFIDChangePlanResponse, FFIDCheckoutSessionResponse, type FFIDClient, FFIDConfig, FFIDCreateCheckoutParams, FFIDCreatePortalParams, FFIDError, type FFIDInquiryClient, FFIDInquiryCreateParams, FFIDInquiryCreateResponse, FFIDListMembersResponse, type FFIDListPlansResponse, FFIDLogger, FFIDMemberRole, type FFIDNewsletterClient, type FFIDNewsletterConfirmParams, type FFIDNewsletterConfirmResponse, type FFIDNewsletterSubscribeParams, type FFIDNewsletterSubscribeResponse, type FFIDNewsletterType, type FFIDNewsletterUnsubscribeParams, type FFIDNewsletterUnsubscribeResponse, FFIDOAuthUserInfo, FFIDOrganization, type FFIDOtpSendResponse, type FFIDOtpVerifyResponse, type FFIDPasswordResetConfirmResponse, type FFIDPasswordResetResponse, type FFIDPasswordResetVerifyResponse, type FFIDPlanChangeLineItem, type FFIDPlanChangePreview, type FFIDPlanChangePreviewResponse, type FFIDPlanInfo, FFIDPortalSessionResponse, type FFIDPreviewPlanChangeParams, type FFIDPreviewSeatChangeParams, FFIDProvider, type FFIDProviderProps, FFIDRedirectResult, FFIDRemoveMemberResponse, type FFIDResetSessionResponse, FFIDSDKError, type FFIDSeatChangeLineItem, type FFIDSeatChangePreview, type FFIDSeatChangePreviewResponse, type FFIDServiceInfo, FFIDSessionResponse, type FFIDSubscribeParams, type FFIDSubscribeResponse, FFIDSubscription, FFIDSubscriptionCheckResponse, FFIDSubscriptionContextValue, type FFIDSubscriptionDetail, FFIDSubscriptionStatus, type FFIDSubscriptionSummary, type FFIDSupportedCurrency, FFIDUpdateMemberRoleResponse, FFIDUser, FFIDVerifyAccessTokenOptions, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_NEWSLETTER_TYPES, type KVNamespaceLike, ListAnnouncementsOptions, type RedirectToAuthorizeOptions, type TokenData, type TokenStore, type UseFFIDReturn, type WithFFIDAuthOptions, type WithSubscriptionOptions, createFFIDAnnouncementsClient, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createTokenStore, generateCodeChallenge, generateCodeVerifier, retrieveCodeVerifier, storeCodeVerifier, useFFID, useSubscription, withFFIDAuth, withSubscription };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { useFFIDContext } from './chunk-2OAFWUEL.js';
-export { DEFAULT_API_BASE_URL, FFIDAnnouncementBadge, FFIDAnnouncementList, FFIDInquiryForm, FFIDLoginButton, FFIDOrganizationSwitcher, FFIDProvider, FFIDSubscriptionBadge, FFIDUserMenu, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_INQUIRY_CATEGORIES, createFFIDAnnouncementsClient, createFFIDClient, createTokenStore, generateCodeChallenge, generateCodeVerifier, retrieveCodeVerifier, storeCodeVerifier, useFFID, useFFIDAnnouncements, useSubscription, withSubscription } from './chunk-2OAFWUEL.js';
+import { useFFIDContext } from './chunk-KJUA77BM.js';
+export { DEFAULT_API_BASE_URL, FFIDAnnouncementBadge, FFIDAnnouncementList, FFIDInquiryForm, FFIDLoginButton, FFIDOrganizationSwitcher, FFIDProvider, FFIDSDKError, FFIDSubscriptionBadge, FFIDUserMenu, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_INQUIRY_CATEGORIES, createFFIDAnnouncementsClient, createFFIDClient, createTokenStore, generateCodeChallenge, generateCodeVerifier, retrieveCodeVerifier, storeCodeVerifier, useFFID, useFFIDAnnouncements, useSubscription, withSubscription } from './chunk-KJUA77BM.js';
 import { useRef, useEffect } from 'react';
 import { jsx, Fragment } from 'react/jsx-runtime';
 

package/dist/server/index.cjs

@@ -453,9 +453,118 @@ function createBillingMethods(deps) {
 var EXT_PLANS_ENDPOINT = "/api/v1/subscriptions/ext/plans";
 var EXT_SUBSCRIPTION_ENDPOINT = "/api/v1/subscriptions/ext";
 var EXT_SUBSCRIBE_ENDPOINT = "/api/v1/subscriptions/ext/subscribe";
+var FFIDSDKError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "FFIDSDKError";
+    this.code = code;
+  }
+};
 function isBlankString(value) {
   return typeof value !== "string" || value.trim() === "";
 }
+var MALFORMED_PREVIEW_CODE = "MALFORMED_PLAN_CHANGE_PREVIEW";
+var MALFORMED_SEAT_PREVIEW_CODE = "MALFORMED_SEAT_CHANGE_PREVIEW";
+var SEAT_ESTIMATE_REASONS = /* @__PURE__ */ new Set(["no_stripe_data", "custom_pricing", "stripe_error"]);
+function validatePlanChangePreview(preview) {
+  if (preview === null || typeof preview !== "object") {
+    throw new FFIDSDKError(
+      MALFORMED_PREVIEW_CODE,
+      "SDK: server returned malformed PlanChangePreview \u2014 expected object, got " + (preview === null ? "null" : typeof preview)
+    );
+  }
+  const p = preview;
+  const flag = p.willApplyAtPeriodEnd;
+  if (typeof flag !== "boolean") {
+    throw new FFIDSDKError(
+      MALFORMED_PREVIEW_CODE,
+      `SDK: server returned malformed PlanChangePreview \u2014 willApplyAtPeriodEnd must be boolean (got ${typeof flag})`
+    );
+  }
+  const { proratedAmount, effectiveDate } = p;
+  if (flag === true) {
+    if (proratedAmount !== 0) {
+      throw new FFIDSDKError(
+        MALFORMED_PREVIEW_CODE,
+        `SDK: server returned malformed PlanChangePreview \u2014 willApplyAtPeriodEnd=true requires proratedAmount=0 (got ${JSON.stringify(proratedAmount)})`
+      );
+    }
+    if (effectiveDate !== null && typeof effectiveDate !== "string") {
+      throw new FFIDSDKError(
+        MALFORMED_PREVIEW_CODE,
+        `SDK: server returned malformed PlanChangePreview \u2014 willApplyAtPeriodEnd=true requires effectiveDate to be string or null (got ${typeof effectiveDate})`
+      );
+    }
+    return;
+  }
+  if (effectiveDate !== null) {
+    throw new FFIDSDKError(
+      MALFORMED_PREVIEW_CODE,
+      `SDK: server returned malformed PlanChangePreview \u2014 willApplyAtPeriodEnd=false requires effectiveDate=null (got ${JSON.stringify(effectiveDate)})`
+    );
+  }
+  if (typeof proratedAmount !== "number") {
+    throw new FFIDSDKError(
+      MALFORMED_PREVIEW_CODE,
+      `SDK: server returned malformed PlanChangePreview \u2014 willApplyAtPeriodEnd=false requires proratedAmount to be a number (got ${typeof proratedAmount})`
+    );
+  }
+}
+function validateSeatChangePreview(preview) {
+  if (preview === null || typeof preview !== "object") {
+    throw new FFIDSDKError(
+      MALFORMED_SEAT_PREVIEW_CODE,
+      "SDK: server returned malformed SeatChangePreview \u2014 expected object, got " + (preview === null ? "null" : typeof preview)
+    );
+  }
+  const p = preview;
+  if (p.type !== "seat-change") {
+    throw new FFIDSDKError(
+      MALFORMED_SEAT_PREVIEW_CODE,
+      `SDK: server returned malformed SeatChangePreview \u2014 type must be 'seat-change' (got ${JSON.stringify(p.type)})`
+    );
+  }
+  const numericFields = [
+    "currentQuantity",
+    "newQuantity",
+    "unitPrice",
+    "proratedAmount",
+    "nextInvoiceAmount"
+  ];
+  for (const key of numericFields) {
+    if (typeof p[key] !== "number") {
+      throw new FFIDSDKError(
+        MALFORMED_SEAT_PREVIEW_CODE,
+        `SDK: server returned malformed SeatChangePreview \u2014 ${key} must be a number (got ${typeof p[key]})`
+      );
+    }
+  }
+  if (p.nextInvoiceDate !== null && typeof p.nextInvoiceDate !== "string") {
+    throw new FFIDSDKError(
+      MALFORMED_SEAT_PREVIEW_CODE,
+      `SDK: server returned malformed SeatChangePreview \u2014 nextInvoiceDate must be string or null (got ${typeof p.nextInvoiceDate})`
+    );
+  }
+  if (typeof p.isEstimate !== "boolean") {
+    throw new FFIDSDKError(
+      MALFORMED_SEAT_PREVIEW_CODE,
+      `SDK: server returned malformed SeatChangePreview \u2014 isEstimate must be boolean (got ${typeof p.isEstimate})`
+    );
+  }
+  if (p.estimateReason !== void 0 && !SEAT_ESTIMATE_REASONS.has(p.estimateReason)) {
+    throw new FFIDSDKError(
+      MALFORMED_SEAT_PREVIEW_CODE,
+      `SDK: server returned malformed SeatChangePreview \u2014 estimateReason must be one of 'no_stripe_data' | 'custom_pricing' | 'stripe_error' (got ${JSON.stringify(p.estimateReason)})`
+    );
+  }
+  if (!Array.isArray(p.lineItems)) {
+    throw new FFIDSDKError(
+      MALFORMED_SEAT_PREVIEW_CODE,
+      `SDK: server returned malformed SeatChangePreview \u2014 lineItems must be an array (got ${typeof p.lineItems})`
+    );
+  }
+}
 function createSubscriptionMethods(deps) {
   const { fetchWithAuth, createError } = deps;
   async function listPlans() {
@@ -542,7 +651,7 @@ function createSubscriptionMethods(deps) {
         error: createError("VALIDATION_ERROR", "subscriptionId \u3068 planCode \u306F\u5FC5\u9808\u3067\u3059")
       };
     }
-    return fetchWithAuth(
+    const response = await fetchWithAuth(
       `${EXT_SUBSCRIPTION_ENDPOINT}/${encodeURIComponent(params.subscriptionId)}/plan/preview`,
       {
         method: "POST",
@@ -552,6 +661,36 @@ function createSubscriptionMethods(deps) {
         })
       }
     );
+    if (response.data !== void 0) {
+      validatePlanChangePreview(response.data.preview);
+    }
+    return response;
+  }
+  async function previewSeatChange(params) {
+    if (isBlankString(params.subscriptionId)) {
+      return {
+        error: createError("VALIDATION_ERROR", "subscriptionId \u306F\u5FC5\u9808\u3067\u3059")
+      };
+    }
+    if (typeof params.quantity !== "number" || !Number.isInteger(params.quantity) || params.quantity < 1) {
+      return {
+        error: createError(
+          "VALIDATION_ERROR",
+          `quantity \u306F 1 \u4EE5\u4E0A\u306E\u6574\u6570\u3067\u3042\u308B\u5FC5\u8981\u304C\u3042\u308A\u307E\u3059 (received: ${String(params.quantity)})`
+        )
+      };
+    }
+    const response = await fetchWithAuth(
+      `${EXT_SUBSCRIPTION_ENDPOINT}/${encodeURIComponent(params.subscriptionId)}/seats/preview`,
+      {
+        method: "POST",
+        body: JSON.stringify({ quantity: params.quantity })
+      }
+    );
+    if (response.data !== void 0) {
+      validateSeatChangePreview(response.data.preview);
+    }
+    return response;
   }
   return {
     listPlans,
@@ -560,7 +699,8 @@ function createSubscriptionMethods(deps) {
     changePlan,
     cancelSubscription,
     cancelPendingDowngrade,
-    previewPlanChange
+    previewPlanChange,
+    previewSeatChange
   };
 }
 
@@ -617,7 +757,7 @@ function createMembersMethods(deps) {
 }
 
 // src/client/version-check.ts
-var SDK_VERSION = "2.11.0";
+var SDK_VERSION = "2.12.0";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {
@@ -1941,7 +2081,8 @@ function createFFIDClient(config) {
     changePlan,
     cancelSubscription,
     cancelPendingDowngrade,
-    previewPlanChange
+    previewPlanChange,
+    previewSeatChange
   } = createSubscriptionMethods({
     fetchWithAuth,
     createError
@@ -2031,6 +2172,7 @@ function createFFIDClient(config) {
     cancelSubscription,
     cancelPendingDowngrade,
     previewPlanChange,
+    previewSeatChange,
     verifyAccessToken,
     getSubscribeUrl,
     redirectToSubscribe,

package/dist/server/index.d.cts

@@ -358,6 +358,62 @@ type FFIDPlanChangePreview = FFIDPlanChangePreviewBase & ({
 interface FFIDPlanChangePreviewResponse {
     preview: FFIDPlanChangePreview;
 }
+/** Parameters for previewing a seat count change */
+interface FFIDPreviewSeatChangeParams {
+    /** Subscription ID (UUID) */
+    subscriptionId: string;
+    /** New seat quantity. Must be an integer within the plan's allowed range. */
+    quantity: number;
+}
+/** Seat change preview line item */
+interface FFIDSeatChangeLineItem {
+    description: string;
+    amount: number;
+}
+/**
+ * Seat change proration preview.
+ *
+ * Sister type to `FFIDPlanChangePreview`. The shared `type` discriminant lets
+ * consumers narrow a preview payload without inspecting unrelated fields.
+ *
+ * - `isEstimate=true` (default when Stripe is not configured or data is unavailable):
+ *   `proratedAmount` is computed locally as `(newQuantity - currentQuantity) * unitPrice`.
+ * - `isEstimate=false`: `proratedAmount` reflects Stripe's live proration calculation.
+ *
+ * `nextInvoiceAmount` is always a local estimate (`unitPrice * newQuantity`).
+ *
+ * `pricingUnavailable=true` indicates the plan uses custom pricing with a zero unit
+ * price (Enterprise). Consumers should hide monetary amounts in this case.
+ */
+interface FFIDSeatChangePreview {
+    /** Discriminant for preview response variants (pairs with `FFIDPlanChangePreview.type`) */
+    type: 'seat-change';
+    currentQuantity: number;
+    newQuantity: number;
+    /** Per-seat price for the current billing interval */
+    unitPrice: number;
+    billingInterval: FFIDBillingInterval;
+    /**
+     * Prorated cost for the current billing period. Negative when seats are decreased
+     * (credit). `0` when `pricingUnavailable === true` (Enterprise custom pricing).
+     */
+    proratedAmount: number;
+    /** Next invoice full amount — always a local estimate (`unitPrice * newQuantity`) */
+    nextInvoiceAmount: number;
+    nextInvoiceDate: string | null;
+    currency: FFIDSupportedCurrency;
+    /** true when proratedAmount is estimated from local prices rather than Stripe proration data */
+    isEstimate: boolean;
+    /** true when unit price is 0 due to custom pricing (Enterprise) — hide monetary amounts */
+    pricingUnavailable?: boolean;
+    /** Reason why `isEstimate` is true. Only meaningful when `isEstimate === true`. */
+    estimateReason?: 'no_stripe_data' | 'custom_pricing' | 'stripe_error';
+    lineItems: FFIDSeatChangeLineItem[];
+}
+/** Response from seat change preview endpoint */
+interface FFIDSeatChangePreviewResponse {
+    preview: FFIDSeatChangePreview;
+}
 
 /**
  * FFID SDK Type Definitions
@@ -845,6 +901,7 @@ declare function createFFIDClient(config: FFIDConfig): {
     cancelSubscription: (params: FFIDCancelSubscriptionParams) => Promise<FFIDApiResponse<FFIDCancelSubscriptionResponse>>;
     cancelPendingDowngrade: (subscriptionId: string) => Promise<FFIDApiResponse<FFIDCancelPendingDowngradeResponse>>;
     previewPlanChange: (params: FFIDPreviewPlanChangeParams) => Promise<FFIDApiResponse<FFIDPlanChangePreviewResponse>>;
+    previewSeatChange: (params: FFIDPreviewSeatChangeParams) => Promise<FFIDApiResponse<FFIDSeatChangePreviewResponse>>;
     verifyAccessToken: (accessToken: string, options?: FFIDVerifyAccessTokenOptions) => Promise<FFIDApiResponse<FFIDOAuthUserInfo>>;
     getSubscribeUrl: (options?: ContractWizardSubscribeOptions) => string;
     redirectToSubscribe: (options?: ContractWizardSubscribeOptions) => FFIDRedirectResult;

package/dist/server/index.d.ts

@@ -358,6 +358,62 @@ type FFIDPlanChangePreview = FFIDPlanChangePreviewBase & ({
 interface FFIDPlanChangePreviewResponse {
     preview: FFIDPlanChangePreview;
 }
+/** Parameters for previewing a seat count change */
+interface FFIDPreviewSeatChangeParams {
+    /** Subscription ID (UUID) */
+    subscriptionId: string;
+    /** New seat quantity. Must be an integer within the plan's allowed range. */
+    quantity: number;
+}
+/** Seat change preview line item */
+interface FFIDSeatChangeLineItem {
+    description: string;
+    amount: number;
+}
+/**
+ * Seat change proration preview.
+ *
+ * Sister type to `FFIDPlanChangePreview`. The shared `type` discriminant lets
+ * consumers narrow a preview payload without inspecting unrelated fields.
+ *
+ * - `isEstimate=true` (default when Stripe is not configured or data is unavailable):
+ *   `proratedAmount` is computed locally as `(newQuantity - currentQuantity) * unitPrice`.
+ * - `isEstimate=false`: `proratedAmount` reflects Stripe's live proration calculation.
+ *
+ * `nextInvoiceAmount` is always a local estimate (`unitPrice * newQuantity`).
+ *
+ * `pricingUnavailable=true` indicates the plan uses custom pricing with a zero unit
+ * price (Enterprise). Consumers should hide monetary amounts in this case.
+ */
+interface FFIDSeatChangePreview {
+    /** Discriminant for preview response variants (pairs with `FFIDPlanChangePreview.type`) */
+    type: 'seat-change';
+    currentQuantity: number;
+    newQuantity: number;
+    /** Per-seat price for the current billing interval */
+    unitPrice: number;
+    billingInterval: FFIDBillingInterval;
+    /**
+     * Prorated cost for the current billing period. Negative when seats are decreased
+     * (credit). `0` when `pricingUnavailable === true` (Enterprise custom pricing).
+     */
+    proratedAmount: number;
+    /** Next invoice full amount — always a local estimate (`unitPrice * newQuantity`) */
+    nextInvoiceAmount: number;
+    nextInvoiceDate: string | null;
+    currency: FFIDSupportedCurrency;
+    /** true when proratedAmount is estimated from local prices rather than Stripe proration data */
+    isEstimate: boolean;
+    /** true when unit price is 0 due to custom pricing (Enterprise) — hide monetary amounts */
+    pricingUnavailable?: boolean;
+    /** Reason why `isEstimate` is true. Only meaningful when `isEstimate === true`. */
+    estimateReason?: 'no_stripe_data' | 'custom_pricing' | 'stripe_error';
+    lineItems: FFIDSeatChangeLineItem[];
+}
+/** Response from seat change preview endpoint */
+interface FFIDSeatChangePreviewResponse {
+    preview: FFIDSeatChangePreview;
+}
 
 /**
  * FFID SDK Type Definitions
@@ -845,6 +901,7 @@ declare function createFFIDClient(config: FFIDConfig): {
     cancelSubscription: (params: FFIDCancelSubscriptionParams) => Promise<FFIDApiResponse<FFIDCancelSubscriptionResponse>>;
     cancelPendingDowngrade: (subscriptionId: string) => Promise<FFIDApiResponse<FFIDCancelPendingDowngradeResponse>>;
     previewPlanChange: (params: FFIDPreviewPlanChangeParams) => Promise<FFIDApiResponse<FFIDPlanChangePreviewResponse>>;
+    previewSeatChange: (params: FFIDPreviewSeatChangeParams) => Promise<FFIDApiResponse<FFIDSeatChangePreviewResponse>>;
     verifyAccessToken: (accessToken: string, options?: FFIDVerifyAccessTokenOptions) => Promise<FFIDApiResponse<FFIDOAuthUserInfo>>;
     getSubscribeUrl: (options?: ContractWizardSubscribeOptions) => string;
     redirectToSubscribe: (options?: ContractWizardSubscribeOptions) => FFIDRedirectResult;