@feelflow/ffid-sdk 2.11.0 → 2.12.1

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;

package/dist/server/index.js

@@ -452,9 +452,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() {
@@ -541,7 +650,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",
@@ -551,6 +660,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,
@@ -559,7 +698,8 @@ function createSubscriptionMethods(deps) {
     changePlan,
     cancelSubscription,
     cancelPendingDowngrade,
-    previewPlanChange
+    previewPlanChange,
+    previewSeatChange
   };
 }
 
@@ -616,7 +756,7 @@ function createMembersMethods(deps) {
 }
 
 // src/client/version-check.ts
-var SDK_VERSION = "2.11.0";
+var SDK_VERSION = "2.12.1";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {
@@ -1226,6 +1366,23 @@ function createRedirectMethods(deps) {
   return { redirectToLogin, redirectToAuthorize, getLoginUrl, getSignupUrl, getLogoutUrl, redirectToLogout };
 }
 
+// src/client/redirect-uri.ts
+var AUTHORITY_BOUNDARY = /^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/?#]+)([/?#]?)/;
+function normalizeRedirectUri(input) {
+  const url = new URL(input);
+  const isRootPath = url.pathname === "" || url.pathname === "/";
+  if (!isRootPath) {
+    return { normalized: input, changed: false };
+  }
+  const match = input.match(AUTHORITY_BOUNDARY);
+  if (match === null || match[2] === "/") {
+    return { normalized: input, changed: false };
+  }
+  const authority = match[1];
+  const rest = input.slice(authority.length);
+  return { normalized: `${authority}/${rest}`, changed: true };
+}
+
 // src/client/password-reset.ts
 var RESET_PASSWORD_BASE = "/api/v1/auth/reset-password";
 function isBlank(value) {
@@ -1736,6 +1893,24 @@ var FFID_ERROR_CODES = {
   TOKEN_VERIFICATION_ERROR: "TOKEN_VERIFICATION_ERROR"
 };
 var EXT_CHECK_ENDPOINT = "/api/v1/subscriptions/ext/check";
+function resolveRedirectUri(raw, logger) {
+  if (raw === null) return null;
+  try {
+    const { normalized, changed } = normalizeRedirectUri(raw);
+    if (changed) {
+      logger.warn(
+        `FFID Client: redirect_uri \u3092\u6B63\u898F\u5316\u3057\u307E\u3057\u305F (${raw} \u2192 ${normalized})\u3002FFID \u7BA1\u7406\u753B\u9762\u3067\u306E\u767B\u9332\u5024\u3068\u4E00\u81F4\u3055\u305B\u3066\u304F\u3060\u3055\u3044\u3002`
+      );
+    }
+    return normalized;
+  } catch (error) {
+    logger.warn(
+      `FFID Client: redirectUri \u306E\u30D1\u30FC\u30B9\u306B\u5931\u6557\u3057\u305F\u305F\u3081\u6B63\u898F\u5316\u3092\u30B9\u30AD\u30C3\u30D7\u3057\u307E\u3057\u305F (${raw})`,
+      error
+    );
+    return raw;
+  }
+}
 function createFFIDClient(config) {
   if (!config.serviceCode || !config.serviceCode.trim()) {
     throw new Error("FFID Client: serviceCode \u304C\u672A\u8A2D\u5B9A\u3067\u3059");
@@ -1743,7 +1918,7 @@ function createFFIDClient(config) {
   const baseUrl = config.apiBaseUrl ?? DEFAULT_API_BASE_URL;
   const authMode = config.authMode ?? "cookie";
   const clientId = config.clientId ?? config.serviceCode;
-  const resolvedRedirectUri = config.redirectUri ?? null;
+  const rawRedirectUri = config.redirectUri ?? null;
   const serviceApiKey = config.serviceApiKey?.trim();
   const verifyStrategy = config.verifyStrategy ?? "jwt";
   const cache = config.cache;
@@ -1758,6 +1933,7 @@ function createFFIDClient(config) {
     throw new Error("FFID Client: timeout \u306F\u6B63\u306E\u6570\u5024\u3092\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044");
   }
   const logger = config.logger ?? (config.debug ? consoleLogger : noopLogger);
+  const resolvedRedirectUri = resolveRedirectUri(rawRedirectUri, logger);
   const tokenStore = authMode === "token" ? createTokenStore() : createTokenStore("memory");
   function createError(code, message) {
     return { code, message };
@@ -1940,7 +2116,8 @@ function createFFIDClient(config) {
     changePlan,
     cancelSubscription,
     cancelPendingDowngrade,
-    previewPlanChange
+    previewPlanChange,
+    previewSeatChange
   } = createSubscriptionMethods({
     fetchWithAuth,
     createError
@@ -2030,6 +2207,7 @@ function createFFIDClient(config) {
     cancelSubscription,
     cancelPendingDowngrade,
     previewPlanChange,
+    previewSeatChange,
     verifyAccessToken,
     getSubscribeUrl,
     redirectToSubscribe,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feelflow/ffid-sdk",
-  "version": "2.11.0",
+  "version": "2.12.1",
   "description": "FeelFlow ID Platform SDK for React/Next.js applications",
   "keywords": [
     "feelflow",