@feelflow/ffid-sdk 2.5.2 → 2.7.0

package/dist/server/index.d.cts

@@ -1,5 +1,51 @@
 export { D as DEFAULT_API_BASE_URL } from '../constants-DvTGHPZn.cjs';
 
+/**
+ * Newsletter types exposed by the FFID SDK.
+ *
+ * 2-layer newsletter model (#2078):
+ *   - `inquiry_followup`: 問い合わせフォローアップ (Type A)
+ *   - `general`:          定期ニュースレター (Type B)
+ *
+ * FFID account holders' preferences live in `user_marketing_preferences`;
+ * anonymous subscribers live in `newsletter_subscribers` with double
+ * opt-in required.
+ */
+declare const FFID_NEWSLETTER_TYPES: readonly ["inquiry_followup", "general"];
+type FFIDNewsletterType = (typeof FFID_NEWSLETTER_TYPES)[number];
+interface FFIDNewsletterSubscribeParams {
+    /** Subscriber email address */
+    email: string;
+    /** One or more newsletter types to opt in to */
+    types: FFIDNewsletterType[];
+    /** Origin string recorded on the subscriber row (e.g. your service code) */
+    source: string;
+    /** ISO 639-1 locale (e.g. 'ja', 'en') */
+    locale?: string;
+}
+interface FFIDNewsletterSubscribeResponse {
+    ok: true;
+    /** True when a double opt-in confirmation email was sent */
+    requiresConfirmation: boolean;
+    /** True when the email matched an existing FFID account; the caller
+     *  must sign in to update preferences. Preferences are NOT modified. */
+    requiresSignIn: boolean;
+}
+interface FFIDNewsletterConfirmParams {
+    /** Confirmation token received in the double opt-in email */
+    token: string;
+}
+interface FFIDNewsletterConfirmResponse {
+    ok: true;
+}
+interface FFIDNewsletterUnsubscribeParams {
+    /** Unsubscribe token received in the newsletter footer / List-Unsubscribe header */
+    token: string;
+}
+interface FFIDNewsletterUnsubscribeResponse {
+    ok: true;
+}
+
 /** Cache adapter interface for FFID SDK token verification */
 /**
  * Pluggable cache adapter interface.
@@ -23,6 +69,11 @@ interface FFIDCacheConfig {
 
 /** Billing interval for subscriptions */
 type FFIDBillingInterval = 'monthly' | 'yearly';
+/**
+ * Supported currencies for billing responses.
+ * Mirrors the platform's `SupportedCurrency` enum (`jpy` = zero-decimal Japanese Yen, `usd` = US Dollar).
+ */
+type FFIDSupportedCurrency = 'jpy' | 'usd';
 /** Service information returned by plans endpoint */
 interface FFIDServiceInfo {
     id: string;
@@ -214,27 +265,56 @@ interface FFIDPlanChangeLineItem {
     description: string;
     amount: number;
 }
+/** Fields shared by every plan-change preview variant (internal; consumers use `FFIDPlanChangePreview`) */
+interface FFIDPlanChangePreviewBase {
+    /** Discriminant for preview response variants (reserved for future unions with e.g. seat-change previews) */
+    type: 'plan-change';
+    /** Current plan display info. `price` is the total for the current quantity (unitPrice × quantity), not per-seat. */
+    currentPlan: {
+        name: string;
+        price: number;
+    };
+    /** New plan display info. `price` is the total for the effective quantity (unitPrice × quantity), not per-seat. */
+    newPlan: {
+        name: string;
+        price: number;
+    };
+    billingInterval: FFIDBillingInterval;
+    isUpgrade: boolean;
+    /** Full amount of the next billing cycle at the new plan's standard price. Never overwritten by Stripe proration data. */
+    nextInvoiceAmount: number;
+    nextInvoiceDate: string | null;
+    currency: FFIDSupportedCurrency;
+    /** true when amounts are estimated from local prices (no Stripe proration data) */
+    isEstimate: boolean;
+    /** Reason why `isEstimate` is true. Only meaningful when `isEstimate === true`. */
+    estimateReason?: 'no_stripe_data' | 'custom_pricing' | 'stripe_error';
+    lineItems: FFIDPlanChangeLineItem[];
+}
+/**
+ * Plan change proration preview.
+ *
+ * `willApplyAtPeriodEnd` is a discriminant that constrains related fields at the type level:
+ * - `true`: period-end-deferred downgrade. `proratedAmount` is always 0; `effectiveDate` mirrors
+ *   the subscription's `currentPeriodEnd` (may be `null` when the subscription has no active
+ *   billing cycle yet — e.g. a pre-Stripe trial or a subscription whose billing cycle is unset).
+ * - `false`: immediate change. `effectiveDate` is always `null`; `proratedAmount` is the live
+ *   (possibly Stripe-refined) day-basis difference.
+ */
+type FFIDPlanChangePreview = FFIDPlanChangePreviewBase & ({
+    willApplyAtPeriodEnd: true;
+    effectiveDate: string | null;
+    /** 0 on period-end-deferred changes; charge happens at the next invoice */
+    proratedAmount: 0;
+} | {
+    willApplyAtPeriodEnd: false;
+    effectiveDate: null;
+    /** Prorated difference charged within the current billing period */
+    proratedAmount: 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[];
-    };
+    preview: FFIDPlanChangePreview;
 }
 
 /**
@@ -745,6 +825,12 @@ declare function createFFIDClient(config: FFIDConfig): {
         accessToken: string;
         refreshToken: string;
     }) => Promise<FFIDApiResponse<FFIDOtpVerifyResponse>>;
+    /** Newsletter methods (subscribe / confirm / unsubscribe) */
+    newsletter: {
+        subscribe: (params: FFIDNewsletterSubscribeParams) => Promise<FFIDApiResponse<FFIDNewsletterSubscribeResponse>>;
+        confirm: (params: FFIDNewsletterConfirmParams) => Promise<FFIDApiResponse<FFIDNewsletterConfirmResponse>>;
+        unsubscribe: (params: FFIDNewsletterUnsubscribeParams) => Promise<FFIDApiResponse<FFIDNewsletterUnsubscribeResponse>>;
+    };
     /** Token store (token mode only) */
     tokenStore: TokenStore;
     /** Resolved auth mode */

package/dist/server/index.d.ts

@@ -1,5 +1,51 @@
 export { D as DEFAULT_API_BASE_URL } from '../constants-DvTGHPZn.js';
 
+/**
+ * Newsletter types exposed by the FFID SDK.
+ *
+ * 2-layer newsletter model (#2078):
+ *   - `inquiry_followup`: 問い合わせフォローアップ (Type A)
+ *   - `general`:          定期ニュースレター (Type B)
+ *
+ * FFID account holders' preferences live in `user_marketing_preferences`;
+ * anonymous subscribers live in `newsletter_subscribers` with double
+ * opt-in required.
+ */
+declare const FFID_NEWSLETTER_TYPES: readonly ["inquiry_followup", "general"];
+type FFIDNewsletterType = (typeof FFID_NEWSLETTER_TYPES)[number];
+interface FFIDNewsletterSubscribeParams {
+    /** Subscriber email address */
+    email: string;
+    /** One or more newsletter types to opt in to */
+    types: FFIDNewsletterType[];
+    /** Origin string recorded on the subscriber row (e.g. your service code) */
+    source: string;
+    /** ISO 639-1 locale (e.g. 'ja', 'en') */
+    locale?: string;
+}
+interface FFIDNewsletterSubscribeResponse {
+    ok: true;
+    /** True when a double opt-in confirmation email was sent */
+    requiresConfirmation: boolean;
+    /** True when the email matched an existing FFID account; the caller
+     *  must sign in to update preferences. Preferences are NOT modified. */
+    requiresSignIn: boolean;
+}
+interface FFIDNewsletterConfirmParams {
+    /** Confirmation token received in the double opt-in email */
+    token: string;
+}
+interface FFIDNewsletterConfirmResponse {
+    ok: true;
+}
+interface FFIDNewsletterUnsubscribeParams {
+    /** Unsubscribe token received in the newsletter footer / List-Unsubscribe header */
+    token: string;
+}
+interface FFIDNewsletterUnsubscribeResponse {
+    ok: true;
+}
+
 /** Cache adapter interface for FFID SDK token verification */
 /**
  * Pluggable cache adapter interface.
@@ -23,6 +69,11 @@ interface FFIDCacheConfig {
 
 /** Billing interval for subscriptions */
 type FFIDBillingInterval = 'monthly' | 'yearly';
+/**
+ * Supported currencies for billing responses.
+ * Mirrors the platform's `SupportedCurrency` enum (`jpy` = zero-decimal Japanese Yen, `usd` = US Dollar).
+ */
+type FFIDSupportedCurrency = 'jpy' | 'usd';
 /** Service information returned by plans endpoint */
 interface FFIDServiceInfo {
     id: string;
@@ -214,27 +265,56 @@ interface FFIDPlanChangeLineItem {
     description: string;
     amount: number;
 }
+/** Fields shared by every plan-change preview variant (internal; consumers use `FFIDPlanChangePreview`) */
+interface FFIDPlanChangePreviewBase {
+    /** Discriminant for preview response variants (reserved for future unions with e.g. seat-change previews) */
+    type: 'plan-change';
+    /** Current plan display info. `price` is the total for the current quantity (unitPrice × quantity), not per-seat. */
+    currentPlan: {
+        name: string;
+        price: number;
+    };
+    /** New plan display info. `price` is the total for the effective quantity (unitPrice × quantity), not per-seat. */
+    newPlan: {
+        name: string;
+        price: number;
+    };
+    billingInterval: FFIDBillingInterval;
+    isUpgrade: boolean;
+    /** Full amount of the next billing cycle at the new plan's standard price. Never overwritten by Stripe proration data. */
+    nextInvoiceAmount: number;
+    nextInvoiceDate: string | null;
+    currency: FFIDSupportedCurrency;
+    /** true when amounts are estimated from local prices (no Stripe proration data) */
+    isEstimate: boolean;
+    /** Reason why `isEstimate` is true. Only meaningful when `isEstimate === true`. */
+    estimateReason?: 'no_stripe_data' | 'custom_pricing' | 'stripe_error';
+    lineItems: FFIDPlanChangeLineItem[];
+}
+/**
+ * Plan change proration preview.
+ *
+ * `willApplyAtPeriodEnd` is a discriminant that constrains related fields at the type level:
+ * - `true`: period-end-deferred downgrade. `proratedAmount` is always 0; `effectiveDate` mirrors
+ *   the subscription's `currentPeriodEnd` (may be `null` when the subscription has no active
+ *   billing cycle yet — e.g. a pre-Stripe trial or a subscription whose billing cycle is unset).
+ * - `false`: immediate change. `effectiveDate` is always `null`; `proratedAmount` is the live
+ *   (possibly Stripe-refined) day-basis difference.
+ */
+type FFIDPlanChangePreview = FFIDPlanChangePreviewBase & ({
+    willApplyAtPeriodEnd: true;
+    effectiveDate: string | null;
+    /** 0 on period-end-deferred changes; charge happens at the next invoice */
+    proratedAmount: 0;
+} | {
+    willApplyAtPeriodEnd: false;
+    effectiveDate: null;
+    /** Prorated difference charged within the current billing period */
+    proratedAmount: 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[];
-    };
+    preview: FFIDPlanChangePreview;
 }
 
 /**
@@ -745,6 +825,12 @@ declare function createFFIDClient(config: FFIDConfig): {
         accessToken: string;
         refreshToken: string;
     }) => Promise<FFIDApiResponse<FFIDOtpVerifyResponse>>;
+    /** Newsletter methods (subscribe / confirm / unsubscribe) */
+    newsletter: {
+        subscribe: (params: FFIDNewsletterSubscribeParams) => Promise<FFIDApiResponse<FFIDNewsletterSubscribeResponse>>;
+        confirm: (params: FFIDNewsletterConfirmParams) => Promise<FFIDApiResponse<FFIDNewsletterConfirmResponse>>;
+        unsubscribe: (params: FFIDNewsletterUnsubscribeParams) => Promise<FFIDApiResponse<FFIDNewsletterUnsubscribeResponse>>;
+    };
     /** Token store (token mode only) */
     tokenStore: TokenStore;
     /** Resolved auth mode */

package/dist/server/index.js

@@ -98,9 +98,15 @@ function createTokenStore(storageType) {
 }
 
 // src/client/oauth-userinfo.ts
-var VALID_SUBSCRIPTION_STATUSES = ["trialing", "active", "past_due", "canceled", "paused"];
-function isValidSubscriptionStatus(value) {
-  return VALID_SUBSCRIPTION_STATUSES.includes(value);
+var SESSION_ELIGIBLE_SUBSCRIPTION_STATUSES = [
+  "trialing",
+  "active",
+  "past_due",
+  "canceled",
+  "paused"
+];
+function isSessionEligibleSubscriptionStatus(value) {
+  return typeof value === "string" && SESSION_ELIGIBLE_SUBSCRIPTION_STATUSES.includes(value);
 }
 function normalizeUserinfo(raw) {
   return {
@@ -126,7 +132,7 @@ function normalizeUserinfo(raw) {
 }
 function mapUserinfoSubscriptionToSession(userinfo, serviceCode) {
   const subscription = userinfo.subscription;
-  if (!subscription || !subscription.planCode || !isValidSubscriptionStatus(subscription.status)) {
+  if (!subscription || !subscription.planCode || !isSessionEligibleSubscriptionStatus(subscription.status)) {
     return [];
   }
   return [
@@ -610,7 +616,7 @@ function createMembersMethods(deps) {
 }
 
 // src/client/version-check.ts
-var SDK_VERSION = "2.5.2";
+var SDK_VERSION = "2.7.0";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {
@@ -1541,6 +1547,118 @@ function createContractWizardMethods(deps) {
   };
 }
 
+// src/newsletter/ffid-newsletter-client.ts
+var EXT_SUBSCRIBE_ENDPOINT2 = "/api/v1/ext/newsletter/subscribe";
+var CONFIRM_ENDPOINT = "/api/newsletter/confirm";
+var UNSUBSCRIBE_ENDPOINT = "/api/newsletter/unsubscribe";
+function trimOrEmpty(s) {
+  return typeof s === "string" ? s.trim() : "";
+}
+async function postPublic(url, init, opts) {
+  let response;
+  try {
+    response = await fetch(url, init);
+  } catch (err) {
+    return {
+      error: opts.createError(
+        "NETWORK_ERROR",
+        err instanceof Error ? err.message : "\u30CD\u30C3\u30C8\u30EF\u30FC\u30AF\u30A8\u30E9\u30FC\u304C\u767A\u751F\u3057\u307E\u3057\u305F"
+      )
+    };
+  }
+  if (!response.ok) {
+    try {
+      const body = await response.json();
+      if (body?.error?.code || body?.error?.message) {
+        return {
+          error: opts.createError(
+            body.error.code ?? "UNKNOWN_ERROR",
+            body.error.message ?? `${opts.fallbackMessage} (status: ${response.status})`
+          )
+        };
+      }
+    } catch {
+    }
+    return {
+      error: opts.createError(
+        "NETWORK_ERROR",
+        `${opts.fallbackMessage} (status: ${response.status})`
+      )
+    };
+  }
+  return { data: opts.success };
+}
+function createNewsletterMethods(deps) {
+  const { fetchWithAuth, baseUrl, createError } = deps;
+  async function subscribe(params) {
+    const email = trimOrEmpty(params.email);
+    const source = trimOrEmpty(params.source);
+    if (!email) {
+      return { error: createError("VALIDATION_ERROR", "email \u306F\u5FC5\u9808\u3067\u3059") };
+    }
+    if (!source) {
+      return { error: createError("VALIDATION_ERROR", "source \u306F\u5FC5\u9808\u3067\u3059") };
+    }
+    if (!Array.isArray(params.types) || params.types.length === 0) {
+      return {
+        error: createError(
+          "VALIDATION_ERROR",
+          "types \u306B\u306F1\u3064\u4EE5\u4E0A\u306E newsletter \u7A2E\u5225\u3092\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044"
+        )
+      };
+    }
+    return fetchWithAuth(
+      EXT_SUBSCRIBE_ENDPOINT2,
+      {
+        method: "POST",
+        body: JSON.stringify({
+          email,
+          types: params.types,
+          source,
+          locale: params.locale
+        })
+      }
+    );
+  }
+  async function confirm(params) {
+    const token = trimOrEmpty(params.token);
+    if (!token) {
+      return { error: createError("VALIDATION_ERROR", "token \u306F\u5FC5\u9808\u3067\u3059") };
+    }
+    return postPublic(
+      `${baseUrl}${CONFIRM_ENDPOINT}`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ token })
+      },
+      {
+        success: { ok: true },
+        createError,
+        fallbackMessage: "\u78BA\u8A8D\u30EA\u30AF\u30A8\u30B9\u30C8\u304C\u5931\u6557\u3057\u307E\u3057\u305F"
+      }
+    );
+  }
+  async function unsubscribe(params) {
+    const token = trimOrEmpty(params.token);
+    if (!token) {
+      return { error: createError("VALIDATION_ERROR", "token \u306F\u5FC5\u9808\u3067\u3059") };
+    }
+    const url = new URL(`${baseUrl}${UNSUBSCRIBE_ENDPOINT}`);
+    url.searchParams.set("token", token);
+    return postPublic(
+      url.toString(),
+      { method: "POST" },
+      {
+        success: { ok: true },
+        createError,
+        fallbackMessage: "\u89E3\u9664\u30EA\u30AF\u30A8\u30B9\u30C8\u304C\u5931\u6557\u3057\u307E\u3057\u305F"
+      }
+    );
+  }
+  return { subscribe, confirm, unsubscribe };
+}
+
 // src/client/ffid-client.ts
 var UNAUTHORIZED_STATUS2 = 401;
 var SDK_LOG_PREFIX = "[FFID SDK]";
@@ -1816,6 +1934,11 @@ function createFFIDClient(config) {
     createError,
     errorCodes: FFID_ERROR_CODES
   });
+  const newsletter = createNewsletterMethods({
+    fetchWithAuth,
+    baseUrl,
+    createError
+  });
   const verifyAccessToken = createVerifyAccessToken({
     authMode,
     baseUrl,
@@ -1870,6 +1993,8 @@ function createFFIDClient(config) {
     confirmPasswordReset,
     sendOtp,
     verifyOtp,
+    /** Newsletter methods (subscribe / confirm / unsubscribe) */
+    newsletter,
     /** Token store (token mode only) */
     tokenStore,
     /** Resolved auth mode */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feelflow/ffid-sdk",
-  "version": "2.5.2",
+  "version": "2.7.0",
   "description": "FeelFlow ID Platform SDK for React/Next.js applications",
   "keywords": [
     "feelflow",
@@ -97,6 +97,7 @@
   "devDependencies": {
     "@testing-library/jest-dom": "^6.0.0",
     "@testing-library/react": "^16.0.0",
+    "@types/node": "^22.19.17",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@typescript-eslint/eslint-plugin": "^8.58.0",