@feelflow/ffid-sdk 4.1.0 → 4.3.0

package/dist/server/index.js

@@ -704,6 +704,7 @@ function createSubscriptionMethods(deps) {
 var EXT_MEMBERS_ENDPOINT = "/api/v1/organizations/ext/members";
 function createMembersMethods(deps) {
   const { fetchWithAuth, createError, serviceCode } = deps;
+  const assignableRoles = /* @__PURE__ */ new Set(["admin", "member", "viewer"]);
   function buildQuery(organizationId) {
     return new URLSearchParams({ organizationId, serviceCode }).toString();
   }
@@ -717,6 +718,37 @@ function createMembersMethods(deps) {
       `${EXT_MEMBERS_ENDPOINT}?${buildQuery(params.organizationId)}`
     );
   }
+  function normalizeAddMemberArgs(paramsOrOrganizationId, data) {
+    if (typeof paramsOrOrganizationId === "string") {
+      const params = {
+        organizationId: paramsOrOrganizationId,
+        email: data?.email ?? ""
+      };
+      if (data?.role !== void 0) params.role = data.role;
+      return params;
+    }
+    return paramsOrOrganizationId;
+  }
+  async function addMember(paramsOrOrganizationId, data) {
+    const params = normalizeAddMemberArgs(paramsOrOrganizationId, data);
+    if (!params.organizationId || !params.email) {
+      return {
+        error: createError("VALIDATION_ERROR", "organizationId \u3068 email \u306F\u5FC5\u9808\u3067\u3059")
+      };
+    }
+    if (params.role !== void 0 && !assignableRoles.has(params.role)) {
+      return {
+        error: createError("VALIDATION_ERROR", "role \u306F admin\u3001member\u3001viewer \u306E\u3044\u305A\u308C\u304B\u3092\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044")
+      };
+    }
+    return fetchWithAuth(
+      `${EXT_MEMBERS_ENDPOINT}?${buildQuery(params.organizationId)}`,
+      {
+        method: "POST",
+        body: JSON.stringify({ email: params.email, role: params.role })
+      }
+    );
+  }
   async function updateMemberRole(params) {
     if (!params.organizationId || !params.userId) {
       return {
@@ -749,7 +781,7 @@ function createMembersMethods(deps) {
       }
     );
   }
-  return { listMembers, updateMemberRole, removeMember };
+  return { listMembers, addMember, updateMemberRole, removeMember };
 }
 
 // src/client/profile-methods.ts
@@ -802,7 +834,7 @@ function createProfileMethods(deps) {
 }
 
 // src/client/version-check.ts
-var SDK_VERSION = "4.1.0";
+var SDK_VERSION = "4.3.0";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {
@@ -2179,6 +2211,73 @@ var FFID_ERROR_CODES = {
   TOKEN_VERIFICATION_ERROR: "TOKEN_VERIFICATION_ERROR"
 };
 var EXT_CHECK_ENDPOINT = "/api/v1/subscriptions/ext/check";
+var DEFAULT_ALLOW_GRACE = true;
+var DEFAULT_SERVICE_ACCESS_FAIL_POLICY = "failClosed";
+var SERVICE_ACCESS_DENIED_CODE = "SERVICE_ACCESS_DENIED";
+var ACCESS_GRANTING_EFFECTIVE_STATUSES = ["active", "past_due_grace"];
+var BLOCKING_EFFECTIVE_STATUSES = [
+  "blocked",
+  "canceled",
+  "expired",
+  "trial_expired"
+];
+function resolveServiceAccessDenialReason(params, allowGrace) {
+  if (params.hasAccess) {
+    return null;
+  }
+  if (params.effectiveStatus === null) {
+    return "no_subscription";
+  }
+  if (params.isGrace && !allowGrace) {
+    return "grace_disallowed";
+  }
+  if (params.effectiveStatus === "active" || params.effectiveStatus === "past_due_grace") {
+    return "blocked";
+  }
+  return params.effectiveStatus;
+}
+function toServiceAccessDecision(response, allowGrace) {
+  const effectiveStatus = response.effectiveStatus ?? null;
+  const serverHasAccess = response.hasAccess ?? (effectiveStatus !== null && ACCESS_GRANTING_EFFECTIVE_STATUSES.includes(effectiveStatus));
+  const isGrace = response.isGrace ?? effectiveStatus === "past_due_grace";
+  const hasAccess = serverHasAccess && (allowGrace || !isGrace);
+  const isBlocked = response.isBlocked ?? (effectiveStatus === null || effectiveStatus !== null && BLOCKING_EFFECTIVE_STATUSES.includes(effectiveStatus));
+  return {
+    hasAccess,
+    effectiveStatus,
+    isGrace,
+    isBlocked: isBlocked || !hasAccess,
+    allowGrace,
+    failPolicy: DEFAULT_SERVICE_ACCESS_FAIL_POLICY,
+    denialReason: resolveServiceAccessDenialReason({ effectiveStatus, hasAccess, isGrace }, allowGrace),
+    organizationId: response.organizationId,
+    subscriptionId: response.subscriptionId,
+    status: response.status,
+    planCode: response.planCode,
+    currentPeriodEnd: response.currentPeriodEnd,
+    gracePeriodEndsAt: response.gracePeriodEndsAt ?? null,
+    reactivatable: response.reactivatable ?? false
+  };
+}
+function failClosedServiceAccessDecision(params, error) {
+  return {
+    hasAccess: false,
+    effectiveStatus: null,
+    isGrace: false,
+    isBlocked: true,
+    allowGrace: params.allowGrace ?? DEFAULT_ALLOW_GRACE,
+    failPolicy: DEFAULT_SERVICE_ACCESS_FAIL_POLICY,
+    denialReason: "ffid_unreachable",
+    organizationId: params.organizationId || null,
+    subscriptionId: null,
+    status: null,
+    planCode: null,
+    currentPeriodEnd: null,
+    gracePeriodEndsAt: null,
+    reactivatable: false,
+    error
+  };
+}
 function resolveRedirectUri(raw, logger) {
   if (raw === null) return null;
   try {
@@ -2417,6 +2516,57 @@ function createFFIDClient(config) {
       `${EXT_CHECK_ENDPOINT}?${query.toString()}`
     );
   }
+  async function checkServiceAccess(params) {
+    const failPolicy = params.failPolicy ?? DEFAULT_SERVICE_ACCESS_FAIL_POLICY;
+    if (failPolicy !== DEFAULT_SERVICE_ACCESS_FAIL_POLICY) {
+      return {
+        error: createError(
+          "VALIDATION_ERROR",
+          `failPolicy \u306F ${DEFAULT_SERVICE_ACCESS_FAIL_POLICY} \u306E\u307F\u6307\u5B9A\u3067\u304D\u307E\u3059`
+        )
+      };
+    }
+    const subscriptionParams = {
+      organizationId: params.organizationId
+    };
+    if (params.userId !== void 0) {
+      subscriptionParams.userId = params.userId;
+    }
+    const subscriptionResult = await checkSubscription(subscriptionParams);
+    if (subscriptionResult.error) {
+      if (subscriptionResult.error.code === "VALIDATION_ERROR") {
+        return { error: subscriptionResult.error };
+      }
+      return {
+        data: failClosedServiceAccessDecision(params, subscriptionResult.error)
+      };
+    }
+    return {
+      data: toServiceAccessDecision(
+        subscriptionResult.data,
+        params.allowGrace ?? DEFAULT_ALLOW_GRACE
+      )
+    };
+  }
+  async function requireServiceAccess(params) {
+    const result = await checkServiceAccess(params);
+    if (result.error) {
+      return result;
+    }
+    if (!result.data.hasAccess) {
+      const error = createError(
+        SERVICE_ACCESS_DENIED_CODE,
+        `FFID service access denied: ${result.data.denialReason ?? "unknown"}`
+      );
+      if (result.data.error) {
+        error.details = { cause: result.data.error };
+      }
+      return {
+        error
+      };
+    }
+    return result;
+  }
   const { createCheckoutSession, createPortalSession } = createBillingMethods({
     fetchWithAuth,
     createError
@@ -2434,7 +2584,7 @@ function createFFIDClient(config) {
     fetchWithAuth,
     createError
   });
-  const { listMembers, updateMemberRole, removeMember } = createMembersMethods({
+  const { listMembers, addMember, updateMemberRole, removeMember } = createMembersMethods({
     fetchWithAuth,
     createError,
     serviceCode: config.serviceCode
@@ -2515,7 +2665,10 @@ function createFFIDClient(config) {
     exchangeCodeForTokens,
     refreshAccessToken,
     checkSubscription,
+    checkServiceAccess,
+    requireServiceAccess,
     listMembers,
+    addMember,
     updateMemberRole,
     removeMember,
     getProfile,

package/dist/server/test/index.d.cts

@@ -1,4 +1,5 @@
-import { g as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-ZcJhRbD6.cjs';
+import { k as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-DgprK2ec.cjs';
+import '../../types-5g_Bg6Ey.cjs';
 
 /**
  * FFID SDK - Test mode client (E2E / integration test bypass)

package/dist/server/test/index.d.ts

@@ -1,4 +1,5 @@
-import { g as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-ZcJhRbD6.js';
+import { k as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-BaStAONh.js';
+import '../../types-5g_Bg6Ey.js';
 
 /**
  * FFID SDK - Test mode client (E2E / integration test bypass)

package/dist/types-5g_Bg6Ey.d.cts

@@ -0,0 +1,37 @@
+/**
+ * Subscription access-control types (Chain of Pacts / Issue #2443).
+ *
+ * Defines `EffectiveSubscriptionStatus` — the semantic status surfaced by
+ * `/api/v1/subscriptions/ext/check` for external services that need a single
+ * value to drive access-control decisions. Mirrors the server-side type in
+ * `src/lib/common/subscription-helpers.ts` so the FFID backend, SDK, and
+ * consuming services agree on the same vocabulary.
+ */
+/**
+ * Semantic subscription status used for access-control decisions by external
+ * services.
+ *
+ * Unlike the raw DB `FFIDSubscriptionStatus` (which keeps the Stripe-aligned
+ * status machine, e.g. `past_due` / `incomplete` / `incomplete_expired`), this
+ * narrowed union flattens dunning-window vs. hard-block cases so callers can
+ * branch on a single value:
+ *
+ * - `active` — normal paying subscription; grant full access.
+ * - `past_due_grace` — payment failed but FFID is still retrying. Service
+ *   SHOULD keep access and surface a recovery banner.
+ * - `blocked` — payment dunning exhausted (`past_due` over grace,
+ *   `unpaid`, `incomplete_expired`, `paused`, `incomplete`). Deny access.
+ * - `canceled` — contract ended (voluntary or auto-cancel). Deny access;
+ *   check the accompanying `reactivatable` flag before showing a restart CTA.
+ * - `trial_expired` — `status = 'trialing'` but the trial end is in the past.
+ *   DB row is still `trialing`; deny access and prompt for a paid plan.
+ * - `expired` — `status = 'active'` but `current_period_end` is in the past.
+ *   This is the FFID-internal runtime-expired case (see
+ *   `getEffectiveSubscriptionStatus` on the server). Deny access.
+ *
+ * @see /api/v1/subscriptions/ext/check
+ * @see docs/03-implementation/EXPIRED_CONTRACT_HANDLING.md
+ */
+type EffectiveSubscriptionStatus = 'active' | 'past_due_grace' | 'blocked' | 'canceled' | 'trial_expired' | 'expired';
+
+export type { EffectiveSubscriptionStatus as E };

package/dist/types-5g_Bg6Ey.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Subscription access-control types (Chain of Pacts / Issue #2443).
+ *
+ * Defines `EffectiveSubscriptionStatus` — the semantic status surfaced by
+ * `/api/v1/subscriptions/ext/check` for external services that need a single
+ * value to drive access-control decisions. Mirrors the server-side type in
+ * `src/lib/common/subscription-helpers.ts` so the FFID backend, SDK, and
+ * consuming services agree on the same vocabulary.
+ */
+/**
+ * Semantic subscription status used for access-control decisions by external
+ * services.
+ *
+ * Unlike the raw DB `FFIDSubscriptionStatus` (which keeps the Stripe-aligned
+ * status machine, e.g. `past_due` / `incomplete` / `incomplete_expired`), this
+ * narrowed union flattens dunning-window vs. hard-block cases so callers can
+ * branch on a single value:
+ *
+ * - `active` — normal paying subscription; grant full access.
+ * - `past_due_grace` — payment failed but FFID is still retrying. Service
+ *   SHOULD keep access and surface a recovery banner.
+ * - `blocked` — payment dunning exhausted (`past_due` over grace,
+ *   `unpaid`, `incomplete_expired`, `paused`, `incomplete`). Deny access.
+ * - `canceled` — contract ended (voluntary or auto-cancel). Deny access;
+ *   check the accompanying `reactivatable` flag before showing a restart CTA.
+ * - `trial_expired` — `status = 'trialing'` but the trial end is in the past.
+ *   DB row is still `trialing`; deny access and prompt for a paid plan.
+ * - `expired` — `status = 'active'` but `current_period_end` is in the past.
+ *   This is the FFID-internal runtime-expired case (see
+ *   `getEffectiveSubscriptionStatus` on the server). Deny access.
+ *
+ * @see /api/v1/subscriptions/ext/check
+ * @see docs/03-implementation/EXPIRED_CONTRACT_HANDLING.md
+ */
+type EffectiveSubscriptionStatus = 'active' | 'past_due_grace' | 'blocked' | 'canceled' | 'trial_expired' | 'expired';
+
+export type { EffectiveSubscriptionStatus as E };

package/dist/webhooks/index.d.cts

@@ -1,3 +1,5 @@
+import { E as EffectiveSubscriptionStatus } from '../types-5g_Bg6Ey.cjs';
+
 /**
  * FFID Webhook SDK Constants
  *
@@ -43,6 +45,7 @@ declare class FFIDWebhookPayloadError extends FFIDWebhookError {
  * Types for receiving and verifying FeelFlow ID webhook events.
  * Used by external services to handle real-time event notifications.
  */
+
 /** All supported webhook event types */
 type FFIDWebhookEventType = 'subscription.created' | 'subscription.updated' | 'subscription.canceled' | 'subscription.downgrade_scheduled' | 'subscription.downgrade_applied' | 'subscription.downgrade_canceled' | 'subscription.trial_ending' | 'subscription.payment_failed' | 'user.created' | 'user.updated' | 'user.deleted' | 'user.deletion_requested' | 'organization.created' | 'organization.updated' | 'organization.member.added' | 'organization.member.removed' | 'organization.member.role_changed' | 'legal.document.updated' | 'legal.agreement.required' | 'system.maintenance.scheduled' | 'system.maintenance.started' | 'system.maintenance.completed' | 'announcement.published' | 'test.ping';
 interface FFIDSubscriptionCreatedPayload {
@@ -50,6 +53,8 @@ interface FFIDSubscriptionCreatedPayload {
     organizationId?: string;
     plan?: string;
     status?: string;
+    effectiveStatus?: EffectiveSubscriptionStatus;
+    gracePeriodEndsAt?: string | null;
 }
 interface FFIDSubscriptionUpdatedPayload {
     subscriptionId: string;
@@ -57,6 +62,8 @@ interface FFIDSubscriptionUpdatedPayload {
     plan?: string;
     previousPlan?: string;
     status?: string;
+    effectiveStatus?: EffectiveSubscriptionStatus;
+    gracePeriodEndsAt?: string | null;
 }
 interface FFIDSubscriptionCanceledPayload {
     /** FFID subscription UUID. */
@@ -86,6 +93,10 @@ interface FFIDSubscriptionCanceledPayload {
      * when Stripe runs out the paid period before emitting the deletion event.
      */
     expiredAt?: string;
+    /** Cancellation always leaves the canonical access-control status as `canceled`. */
+    effectiveStatus?: EffectiveSubscriptionStatus;
+    /** Always null for cancellation events because no grace window remains. */
+    gracePeriodEndsAt?: string | null;
 }
 interface FFIDSubscriptionDowngradeScheduledPayload {
     /** FFID subscription UUID. */
@@ -172,6 +183,13 @@ interface FFIDSubscriptionPaymentFailedPayload {
      * `null` means already blocking.
      */
     graceUntil?: string | null;
+    /** Canonical FFID access-control status derived from payment-failure severity. */
+    effectiveStatus?: EffectiveSubscriptionStatus;
+    /**
+     * Alias of `graceUntil` for canonical access payloads; services should prefer
+     * this field when sharing code with `/subscriptions/ext/check`.
+     */
+    gracePeriodEndsAt?: string | null;
     /**
      * `true` when the FFID server could not resolve `stripeSubscriptionId` to an
      * FFID subscription row (e.g. race with a not-yet-synced sub, or invoice

package/dist/webhooks/index.d.ts

@@ -1,3 +1,5 @@
+import { E as EffectiveSubscriptionStatus } from '../types-5g_Bg6Ey.js';
+
 /**
  * FFID Webhook SDK Constants
  *
@@ -43,6 +45,7 @@ declare class FFIDWebhookPayloadError extends FFIDWebhookError {
  * Types for receiving and verifying FeelFlow ID webhook events.
  * Used by external services to handle real-time event notifications.
  */
+
 /** All supported webhook event types */
 type FFIDWebhookEventType = 'subscription.created' | 'subscription.updated' | 'subscription.canceled' | 'subscription.downgrade_scheduled' | 'subscription.downgrade_applied' | 'subscription.downgrade_canceled' | 'subscription.trial_ending' | 'subscription.payment_failed' | 'user.created' | 'user.updated' | 'user.deleted' | 'user.deletion_requested' | 'organization.created' | 'organization.updated' | 'organization.member.added' | 'organization.member.removed' | 'organization.member.role_changed' | 'legal.document.updated' | 'legal.agreement.required' | 'system.maintenance.scheduled' | 'system.maintenance.started' | 'system.maintenance.completed' | 'announcement.published' | 'test.ping';
 interface FFIDSubscriptionCreatedPayload {
@@ -50,6 +53,8 @@ interface FFIDSubscriptionCreatedPayload {
     organizationId?: string;
     plan?: string;
     status?: string;
+    effectiveStatus?: EffectiveSubscriptionStatus;
+    gracePeriodEndsAt?: string | null;
 }
 interface FFIDSubscriptionUpdatedPayload {
     subscriptionId: string;
@@ -57,6 +62,8 @@ interface FFIDSubscriptionUpdatedPayload {
     plan?: string;
     previousPlan?: string;
     status?: string;
+    effectiveStatus?: EffectiveSubscriptionStatus;
+    gracePeriodEndsAt?: string | null;
 }
 interface FFIDSubscriptionCanceledPayload {
     /** FFID subscription UUID. */
@@ -86,6 +93,10 @@ interface FFIDSubscriptionCanceledPayload {
      * when Stripe runs out the paid period before emitting the deletion event.
      */
     expiredAt?: string;
+    /** Cancellation always leaves the canonical access-control status as `canceled`. */
+    effectiveStatus?: EffectiveSubscriptionStatus;
+    /** Always null for cancellation events because no grace window remains. */
+    gracePeriodEndsAt?: string | null;
 }
 interface FFIDSubscriptionDowngradeScheduledPayload {
     /** FFID subscription UUID. */
@@ -172,6 +183,13 @@ interface FFIDSubscriptionPaymentFailedPayload {
      * `null` means already blocking.
      */
     graceUntil?: string | null;
+    /** Canonical FFID access-control status derived from payment-failure severity. */
+    effectiveStatus?: EffectiveSubscriptionStatus;
+    /**
+     * Alias of `graceUntil` for canonical access payloads; services should prefer
+     * this field when sharing code with `/subscriptions/ext/check`.
+     */
+    gracePeriodEndsAt?: string | null;
     /**
      * `true` when the FFID server could not resolve `stripeSubscriptionId` to an
      * FFID subscription row (e.g. race with a not-yet-synced sub, or invoice

package/package.json

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