@feelflow/ffid-sdk 1.18.0 → 1.19.0

package/dist/server/index.d.cts

@@ -21,6 +21,193 @@ interface FFIDCacheConfig {
     ttl: number;
 }
 
+/** Billing interval for subscriptions */
+type FFIDBillingInterval = 'monthly' | 'yearly';
+/** Service information returned by plans endpoint */
+interface FFIDServiceInfo {
+    id: string;
+    code: string;
+    name: string;
+    description: string | null;
+    isActive: boolean;
+    createdAt: string;
+    plans: FFIDPlanInfo[];
+}
+/** Plan information returned by plans endpoint */
+interface FFIDPlanInfo {
+    id: string;
+    serviceId: string;
+    code: string;
+    name: string;
+    description: string | null;
+    minSeats: number;
+    maxSeats: number | null;
+    trialDays: number;
+    priceMonthly: number;
+    priceYearly: number | null;
+    currency: string;
+    isActive: boolean;
+    displayOrder: number;
+    customPricing: boolean;
+    createdAt: string;
+}
+/** Response from list plans endpoint */
+interface FFIDListPlansResponse {
+    services: FFIDServiceInfo[];
+    count: number;
+}
+/** Subscription details returned by ext API (sanitized, no Stripe IDs) */
+interface FFIDSubscriptionDetail {
+    id: string;
+    organizationId: string;
+    organizationName: string;
+    serviceCode: string;
+    serviceName: string;
+    planCode: string;
+    planName: string;
+    status: FFIDSubscriptionStatus;
+    paymentMethod: string | null;
+    billingInterval: FFIDBillingInterval;
+    quantity: number;
+    currentPeriodStart: string | null;
+    currentPeriodEnd: string | null;
+    trialStart: string | null;
+    trialEnd: string | null;
+    canceledAt: string | null;
+    cancelAtPeriodEnd: boolean;
+    createdAt: string;
+}
+/** Parameters for subscribing to a plan */
+interface FFIDSubscribeParams {
+    /** Organization ID (UUID) */
+    organizationId: string;
+    /** Plan code (e.g., 'free', 'basic', 'pro') */
+    planCode: string;
+    /** Billing interval (default: 'monthly') */
+    billingInterval?: FFIDBillingInterval;
+    /** Number of seats (default: plan's minSeats) */
+    quantity?: number;
+    /** User ID for seat auto-assignment (only needed for service-key mode) */
+    userId?: string;
+}
+/** Sanitized subscription fields returned by subscribe/reactivate endpoints (no Stripe IDs) */
+interface FFIDSubscriptionSummary {
+    id: string;
+    organizationId: string;
+    serviceId: string;
+    planId: string;
+    status: FFIDSubscriptionStatus;
+    paymentMethod: string | null;
+    billingInterval: FFIDBillingInterval;
+    quantity: number;
+    currentPeriodStart: string | null;
+    currentPeriodEnd: string | null;
+    trialStart: string | null;
+    trialEnd: string | null;
+    canceledAt: string | null;
+    cancelAtPeriodEnd: boolean;
+    createdAt: string;
+}
+/** Response from subscribe endpoint */
+interface FFIDSubscribeResponse {
+    subscription: FFIDSubscriptionSummary;
+    service: {
+        id: string;
+        code: string;
+        name: string;
+    };
+    plan: {
+        id: string;
+        code: string;
+        name: string;
+        priceMonthly: number;
+        priceYearly: number | null;
+        trialDays: number;
+    };
+    /** True if a canceled subscription was reactivated */
+    reactivated?: boolean;
+    /** True if Stripe checkout is needed (canceled paid plan reactivation) */
+    needsCheckout?: boolean;
+}
+/** Parameters for changing plan */
+interface FFIDChangePlanParams {
+    /** Subscription ID (UUID) */
+    subscriptionId: string;
+    /** New plan code */
+    planCode: string;
+    /** New billing interval (default: keeps current) */
+    billingInterval?: FFIDBillingInterval;
+}
+/** Response from change plan endpoint */
+interface FFIDChangePlanResponse {
+    message: string;
+    subscription: {
+        id: string;
+        organizationId: string;
+        serviceCode: string;
+        planCode: string;
+        planName: string;
+        billingInterval: FFIDBillingInterval;
+        status: FFIDSubscriptionStatus;
+        isUpgrade: boolean;
+    };
+}
+/** Parameters for canceling subscription */
+interface FFIDCancelSubscriptionParams {
+    /** Subscription ID (UUID) */
+    subscriptionId: string;
+    /** Cancellation reason code */
+    reason?: 'too_expensive' | 'missing_features' | 'switched_service' | 'rarely_used' | 'customer_service' | 'other';
+    /** Additional cancellation details */
+    reasonDetails?: string;
+}
+/** Response from cancel subscription endpoint */
+interface FFIDCancelSubscriptionResponse {
+    message: string;
+    subscription: {
+        id: string;
+        organizationId: string;
+        status: FFIDSubscriptionStatus;
+        canceledAt: string | null;
+    };
+}
+/** Parameters for previewing plan change */
+interface FFIDPreviewPlanChangeParams {
+    /** Subscription ID (UUID) */
+    subscriptionId: string;
+    /** New plan code */
+    planCode: string;
+    /** New billing interval (default: keeps current) */
+    billingInterval?: FFIDBillingInterval;
+}
+/** Plan change preview line item */
+interface FFIDPlanChangeLineItem {
+    description: string;
+    amount: number;
+}
+/** Response from plan change preview endpoint */
+interface FFIDPlanChangePreviewResponse {
+    preview: {
+        currentPlan: {
+            name: string;
+            price: number;
+        };
+        newPlan: {
+            name: string;
+            price: number;
+        };
+        billingInterval: FFIDBillingInterval;
+        isUpgrade: boolean;
+        proratedAmount: number;
+        nextInvoiceAmount: number;
+        nextInvoiceDate: string | null;
+        currency: string;
+        isEstimate: boolean;
+        estimateReason?: string;
+        lineItems: FFIDPlanChangeLineItem[];
+    };
+}
+
 /**
  * FFID SDK Type Definitions
  *
@@ -103,7 +290,7 @@ interface FFIDSubscription {
     /** Plan display name */
     planName: string;
     /** Subscription status */
-    status: 'trialing' | 'active' | 'past_due' | 'canceled' | 'paused';
+    status: FFIDSubscriptionStatus;
     /** Current billing period end date */
     currentPeriodEnd: string | null;
     /** Trial end date (null if not a trial or no trial_end set) */
@@ -118,7 +305,7 @@ interface FFIDSubscription {
 /** OAuth userinfo subscription summary */
 interface FFIDOAuthUserInfoSubscription {
     subscriptionId: string | null;
-    status: 'trialing' | 'active' | 'past_due' | 'canceled' | 'paused' | null;
+    status: FFIDSubscriptionStatus | null;
     planCode: string | null;
     seatModel: FFIDSeatModel | null;
     memberRole: FFIDOAuthUserInfoMemberRole | null;
@@ -255,9 +442,6 @@ type FFIDApiResponse<T> = {
     data?: undefined;
     error: FFIDError;
 };
-/**
- * Subscription check response from ext/check endpoint
- */
 /** Subscription status values matching the FFID platform's SubscriptionStatus type */
 type FFIDSubscriptionStatus = 'trialing' | 'active' | 'past_due' | 'canceled' | 'pending_invoice' | 'paused' | 'incomplete' | 'incomplete_expired' | 'unpaid';
 interface FFIDSubscriptionCheckResponse {
@@ -308,6 +492,7 @@ interface FFIDCreatePortalParams {
     /** URL to redirect when user exits the portal */
     returnUrl: string;
 }
+
 /** Member role in an organization */
 type FFIDMemberRole = 'owner' | 'admin' | 'member' | 'viewer';
 /** Member status in an organization */
@@ -476,6 +661,12 @@ declare function createFFIDClient(config: FFIDConfig): {
     }) => Promise<FFIDApiResponse<FFIDRemoveMemberResponse>>;
     createCheckoutSession: (params: FFIDCreateCheckoutParams) => Promise<FFIDApiResponse<FFIDCheckoutSessionResponse>>;
     createPortalSession: (params: FFIDCreatePortalParams) => Promise<FFIDApiResponse<FFIDPortalSessionResponse>>;
+    listPlans: () => Promise<FFIDApiResponse<FFIDListPlansResponse>>;
+    getSubscription: (subscriptionId: string) => Promise<FFIDApiResponse<FFIDSubscriptionDetail>>;
+    subscribe: (params: FFIDSubscribeParams) => Promise<FFIDApiResponse<FFIDSubscribeResponse>>;
+    changePlan: (params: FFIDChangePlanParams) => Promise<FFIDApiResponse<FFIDChangePlanResponse>>;
+    cancelSubscription: (params: FFIDCancelSubscriptionParams) => Promise<FFIDApiResponse<FFIDCancelSubscriptionResponse>>;
+    previewPlanChange: (params: FFIDPreviewPlanChangeParams) => Promise<FFIDApiResponse<FFIDPlanChangePreviewResponse>>;
     verifyAccessToken: (accessToken: string, options?: FFIDVerifyAccessTokenOptions) => Promise<FFIDApiResponse<FFIDOAuthUserInfo>>;
     requestPasswordReset: (email: string) => Promise<FFIDApiResponse<FFIDPasswordResetResponse>>;
     verifyPasswordResetToken: (accessToken: string) => Promise<FFIDApiResponse<FFIDPasswordResetVerifyResponse>>;

package/dist/server/index.d.ts

@@ -21,6 +21,193 @@ interface FFIDCacheConfig {
     ttl: number;
 }
 
+/** Billing interval for subscriptions */
+type FFIDBillingInterval = 'monthly' | 'yearly';
+/** Service information returned by plans endpoint */
+interface FFIDServiceInfo {
+    id: string;
+    code: string;
+    name: string;
+    description: string | null;
+    isActive: boolean;
+    createdAt: string;
+    plans: FFIDPlanInfo[];
+}
+/** Plan information returned by plans endpoint */
+interface FFIDPlanInfo {
+    id: string;
+    serviceId: string;
+    code: string;
+    name: string;
+    description: string | null;
+    minSeats: number;
+    maxSeats: number | null;
+    trialDays: number;
+    priceMonthly: number;
+    priceYearly: number | null;
+    currency: string;
+    isActive: boolean;
+    displayOrder: number;
+    customPricing: boolean;
+    createdAt: string;
+}
+/** Response from list plans endpoint */
+interface FFIDListPlansResponse {
+    services: FFIDServiceInfo[];
+    count: number;
+}
+/** Subscription details returned by ext API (sanitized, no Stripe IDs) */
+interface FFIDSubscriptionDetail {
+    id: string;
+    organizationId: string;
+    organizationName: string;
+    serviceCode: string;
+    serviceName: string;
+    planCode: string;
+    planName: string;
+    status: FFIDSubscriptionStatus;
+    paymentMethod: string | null;
+    billingInterval: FFIDBillingInterval;
+    quantity: number;
+    currentPeriodStart: string | null;
+    currentPeriodEnd: string | null;
+    trialStart: string | null;
+    trialEnd: string | null;
+    canceledAt: string | null;
+    cancelAtPeriodEnd: boolean;
+    createdAt: string;
+}
+/** Parameters for subscribing to a plan */
+interface FFIDSubscribeParams {
+    /** Organization ID (UUID) */
+    organizationId: string;
+    /** Plan code (e.g., 'free', 'basic', 'pro') */
+    planCode: string;
+    /** Billing interval (default: 'monthly') */
+    billingInterval?: FFIDBillingInterval;
+    /** Number of seats (default: plan's minSeats) */
+    quantity?: number;
+    /** User ID for seat auto-assignment (only needed for service-key mode) */
+    userId?: string;
+}
+/** Sanitized subscription fields returned by subscribe/reactivate endpoints (no Stripe IDs) */
+interface FFIDSubscriptionSummary {
+    id: string;
+    organizationId: string;
+    serviceId: string;
+    planId: string;
+    status: FFIDSubscriptionStatus;
+    paymentMethod: string | null;
+    billingInterval: FFIDBillingInterval;
+    quantity: number;
+    currentPeriodStart: string | null;
+    currentPeriodEnd: string | null;
+    trialStart: string | null;
+    trialEnd: string | null;
+    canceledAt: string | null;
+    cancelAtPeriodEnd: boolean;
+    createdAt: string;
+}
+/** Response from subscribe endpoint */
+interface FFIDSubscribeResponse {
+    subscription: FFIDSubscriptionSummary;
+    service: {
+        id: string;
+        code: string;
+        name: string;
+    };
+    plan: {
+        id: string;
+        code: string;
+        name: string;
+        priceMonthly: number;
+        priceYearly: number | null;
+        trialDays: number;
+    };
+    /** True if a canceled subscription was reactivated */
+    reactivated?: boolean;
+    /** True if Stripe checkout is needed (canceled paid plan reactivation) */
+    needsCheckout?: boolean;
+}
+/** Parameters for changing plan */
+interface FFIDChangePlanParams {
+    /** Subscription ID (UUID) */
+    subscriptionId: string;
+    /** New plan code */
+    planCode: string;
+    /** New billing interval (default: keeps current) */
+    billingInterval?: FFIDBillingInterval;
+}
+/** Response from change plan endpoint */
+interface FFIDChangePlanResponse {
+    message: string;
+    subscription: {
+        id: string;
+        organizationId: string;
+        serviceCode: string;
+        planCode: string;
+        planName: string;
+        billingInterval: FFIDBillingInterval;
+        status: FFIDSubscriptionStatus;
+        isUpgrade: boolean;
+    };
+}
+/** Parameters for canceling subscription */
+interface FFIDCancelSubscriptionParams {
+    /** Subscription ID (UUID) */
+    subscriptionId: string;
+    /** Cancellation reason code */
+    reason?: 'too_expensive' | 'missing_features' | 'switched_service' | 'rarely_used' | 'customer_service' | 'other';
+    /** Additional cancellation details */
+    reasonDetails?: string;
+}
+/** Response from cancel subscription endpoint */
+interface FFIDCancelSubscriptionResponse {
+    message: string;
+    subscription: {
+        id: string;
+        organizationId: string;
+        status: FFIDSubscriptionStatus;
+        canceledAt: string | null;
+    };
+}
+/** Parameters for previewing plan change */
+interface FFIDPreviewPlanChangeParams {
+    /** Subscription ID (UUID) */
+    subscriptionId: string;
+    /** New plan code */
+    planCode: string;
+    /** New billing interval (default: keeps current) */
+    billingInterval?: FFIDBillingInterval;
+}
+/** Plan change preview line item */
+interface FFIDPlanChangeLineItem {
+    description: string;
+    amount: number;
+}
+/** Response from plan change preview endpoint */
+interface FFIDPlanChangePreviewResponse {
+    preview: {
+        currentPlan: {
+            name: string;
+            price: number;
+        };
+        newPlan: {
+            name: string;
+            price: number;
+        };
+        billingInterval: FFIDBillingInterval;
+        isUpgrade: boolean;
+        proratedAmount: number;
+        nextInvoiceAmount: number;
+        nextInvoiceDate: string | null;
+        currency: string;
+        isEstimate: boolean;
+        estimateReason?: string;
+        lineItems: FFIDPlanChangeLineItem[];
+    };
+}
+
 /**
  * FFID SDK Type Definitions
  *
@@ -103,7 +290,7 @@ interface FFIDSubscription {
     /** Plan display name */
     planName: string;
     /** Subscription status */
-    status: 'trialing' | 'active' | 'past_due' | 'canceled' | 'paused';
+    status: FFIDSubscriptionStatus;
     /** Current billing period end date */
     currentPeriodEnd: string | null;
     /** Trial end date (null if not a trial or no trial_end set) */
@@ -118,7 +305,7 @@ interface FFIDSubscription {
 /** OAuth userinfo subscription summary */
 interface FFIDOAuthUserInfoSubscription {
     subscriptionId: string | null;
-    status: 'trialing' | 'active' | 'past_due' | 'canceled' | 'paused' | null;
+    status: FFIDSubscriptionStatus | null;
     planCode: string | null;
     seatModel: FFIDSeatModel | null;
     memberRole: FFIDOAuthUserInfoMemberRole | null;
@@ -255,9 +442,6 @@ type FFIDApiResponse<T> = {
     data?: undefined;
     error: FFIDError;
 };
-/**
- * Subscription check response from ext/check endpoint
- */
 /** Subscription status values matching the FFID platform's SubscriptionStatus type */
 type FFIDSubscriptionStatus = 'trialing' | 'active' | 'past_due' | 'canceled' | 'pending_invoice' | 'paused' | 'incomplete' | 'incomplete_expired' | 'unpaid';
 interface FFIDSubscriptionCheckResponse {
@@ -308,6 +492,7 @@ interface FFIDCreatePortalParams {
     /** URL to redirect when user exits the portal */
     returnUrl: string;
 }
+
 /** Member role in an organization */
 type FFIDMemberRole = 'owner' | 'admin' | 'member' | 'viewer';
 /** Member status in an organization */
@@ -476,6 +661,12 @@ declare function createFFIDClient(config: FFIDConfig): {
     }) => Promise<FFIDApiResponse<FFIDRemoveMemberResponse>>;
     createCheckoutSession: (params: FFIDCreateCheckoutParams) => Promise<FFIDApiResponse<FFIDCheckoutSessionResponse>>;
     createPortalSession: (params: FFIDCreatePortalParams) => Promise<FFIDApiResponse<FFIDPortalSessionResponse>>;
+    listPlans: () => Promise<FFIDApiResponse<FFIDListPlansResponse>>;
+    getSubscription: (subscriptionId: string) => Promise<FFIDApiResponse<FFIDSubscriptionDetail>>;
+    subscribe: (params: FFIDSubscribeParams) => Promise<FFIDApiResponse<FFIDSubscribeResponse>>;
+    changePlan: (params: FFIDChangePlanParams) => Promise<FFIDApiResponse<FFIDChangePlanResponse>>;
+    cancelSubscription: (params: FFIDCancelSubscriptionParams) => Promise<FFIDApiResponse<FFIDCancelSubscriptionResponse>>;
+    previewPlanChange: (params: FFIDPreviewPlanChangeParams) => Promise<FFIDApiResponse<FFIDPlanChangePreviewResponse>>;
     verifyAccessToken: (accessToken: string, options?: FFIDVerifyAccessTokenOptions) => Promise<FFIDApiResponse<FFIDOAuthUserInfo>>;
     requestPasswordReset: (email: string) => Promise<FFIDApiResponse<FFIDPasswordResetResponse>>;
     verifyPasswordResetToken: (accessToken: string) => Promise<FFIDApiResponse<FFIDPasswordResetVerifyResponse>>;

package/dist/server/index.js

@@ -442,6 +442,106 @@ function createBillingMethods(deps) {
   return { createCheckoutSession, createPortalSession };
 }
 
+// src/client/subscription-methods.ts
+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";
+function createSubscriptionMethods(deps) {
+  const { fetchWithAuth, createError } = deps;
+  async function listPlans() {
+    return fetchWithAuth(EXT_PLANS_ENDPOINT);
+  }
+  async function getSubscription(subscriptionId) {
+    if (!subscriptionId) {
+      return {
+        error: createError("VALIDATION_ERROR", "subscriptionId \u306F\u5FC5\u9808\u3067\u3059")
+      };
+    }
+    return fetchWithAuth(
+      `${EXT_SUBSCRIPTION_ENDPOINT}/${encodeURIComponent(subscriptionId)}`
+    );
+  }
+  async function subscribe(params) {
+    if (!params.organizationId || !params.planCode) {
+      return {
+        error: createError("VALIDATION_ERROR", "organizationId \u3068 planCode \u306F\u5FC5\u9808\u3067\u3059")
+      };
+    }
+    return fetchWithAuth(
+      EXT_SUBSCRIBE_ENDPOINT,
+      {
+        method: "POST",
+        body: JSON.stringify({
+          organizationId: params.organizationId,
+          planCode: params.planCode,
+          ...params.billingInterval ? { billingInterval: params.billingInterval } : {},
+          ...params.quantity !== void 0 ? { quantity: params.quantity } : {},
+          ...params.userId ? { userId: params.userId } : {}
+        })
+      }
+    );
+  }
+  async function changePlan(params) {
+    if (!params.subscriptionId || !params.planCode) {
+      return {
+        error: createError("VALIDATION_ERROR", "subscriptionId \u3068 planCode \u306F\u5FC5\u9808\u3067\u3059")
+      };
+    }
+    return fetchWithAuth(
+      `${EXT_SUBSCRIPTION_ENDPOINT}/${encodeURIComponent(params.subscriptionId)}/plan`,
+      {
+        method: "PUT",
+        body: JSON.stringify({
+          planCode: params.planCode,
+          ...params.billingInterval ? { billingInterval: params.billingInterval } : {}
+        })
+      }
+    );
+  }
+  async function cancelSubscription(params) {
+    if (!params.subscriptionId) {
+      return {
+        error: createError("VALIDATION_ERROR", "subscriptionId \u306F\u5FC5\u9808\u3067\u3059")
+      };
+    }
+    const body = {};
+    if (params.reason) body.reason = params.reason;
+    if (params.reasonDetails) body.reasonDetails = params.reasonDetails;
+    return fetchWithAuth(
+      `${EXT_SUBSCRIPTION_ENDPOINT}/${encodeURIComponent(params.subscriptionId)}`,
+      {
+        method: "DELETE",
+        ...Object.keys(body).length > 0 ? { body: JSON.stringify(body) } : {}
+      }
+    );
+  }
+  async function previewPlanChange(params) {
+    if (!params.subscriptionId || !params.planCode) {
+      return {
+        error: createError("VALIDATION_ERROR", "subscriptionId \u3068 planCode \u306F\u5FC5\u9808\u3067\u3059")
+      };
+    }
+    return fetchWithAuth(
+      `${EXT_SUBSCRIPTION_ENDPOINT}/${encodeURIComponent(params.subscriptionId)}/plan/preview`,
+      {
+        method: "POST",
+        body: JSON.stringify({
+          planCode: params.planCode,
+          ...params.billingInterval ? { billingInterval: params.billingInterval } : {}
+        })
+      }
+    );
+  }
+  return {
+    listPlans,
+    getSubscription,
+    subscribe,
+    changePlan,
+    cancelSubscription,
+    previewPlanChange
+  };
+}
+
 // src/client/members-methods.ts
 var EXT_MEMBERS_ENDPOINT = "/api/v1/organizations/ext/members";
 function createMembersMethods(deps) {
@@ -495,7 +595,7 @@ function createMembersMethods(deps) {
 }
 
 // src/client/version-check.ts
-var SDK_VERSION = "1.18.0";
+var SDK_VERSION = "1.19.0";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {
@@ -1555,6 +1655,17 @@ function createFFIDClient(config) {
     fetchWithAuth,
     createError
   });
+  const {
+    listPlans,
+    getSubscription,
+    subscribe,
+    changePlan,
+    cancelSubscription,
+    previewPlanChange
+  } = createSubscriptionMethods({
+    fetchWithAuth,
+    createError
+  });
   const { listMembers, updateMemberRole, removeMember } = createMembersMethods({
     fetchWithAuth,
     createError,
@@ -1608,6 +1719,12 @@ function createFFIDClient(config) {
     removeMember,
     createCheckoutSession,
     createPortalSession,
+    listPlans,
+    getSubscription,
+    subscribe,
+    changePlan,
+    cancelSubscription,
+    previewPlanChange,
     verifyAccessToken,
     requestPasswordReset,
     verifyPasswordResetToken,

package/package.json

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