@feelflow/ffid-sdk 1.9.1 → 1.10.0

package/dist/server/index.d.ts

@@ -0,0 +1,416 @@
+export { D as DEFAULT_API_BASE_URL } from '../constants-DvTGHPZn.js';
+
+/** Cache adapter interface for FFID SDK token verification */
+/**
+ * Pluggable cache adapter interface.
+ * Implement this to use custom cache backends (Redis, Memcached, etc.)
+ */
+interface FFIDCacheAdapter {
+    /** Get a cached value by key. Returns null if not found or expired. */
+    get(key: string): Promise<unknown | null>;
+    /** Set a value with TTL in seconds. */
+    set(key: string, value: unknown, ttlSeconds: number): Promise<void>;
+    /** Delete a cached value. */
+    delete(key: string): Promise<void>;
+}
+/** Cache configuration for createFFIDClient */
+interface FFIDCacheConfig {
+    /** Cache adapter instance */
+    adapter: FFIDCacheAdapter;
+    /** Cache TTL in seconds (how long to cache userinfo/introspect results) */
+    ttl: number;
+}
+
+/**
+ * FFID SDK Type Definitions
+ *
+ * Core types for the FeelFlow ID SDK
+ */
+
+/**
+ * User information from FFID
+ */
+type FFIDSeatModel = 'organization';
+/** Userinfo member role for OAuth responses */
+type FFIDOAuthUserInfoMemberRole = 'owner' | 'admin' | 'member' | 'viewer';
+interface FFIDUser {
+    /** User ID (UUID) */
+    id: string;
+    /** Email address */
+    email: string;
+    /** Display name */
+    displayName: string | null;
+    /** Avatar URL */
+    avatarUrl: string | null;
+    /** Locale setting (e.g., 'ja', 'en') */
+    locale: string | null;
+    /** Timezone (e.g., 'Asia/Tokyo') */
+    timezone: string | null;
+    /** Account creation timestamp */
+    createdAt: string;
+}
+/**
+ * Agency branding information for white-label support.
+ * Included in organization when it is linked to an agency.
+ */
+interface FFIDAgencyBranding {
+    /** Agency ID (UUID) */
+    agencyId: string;
+    /** Agency display name */
+    agencyName: string;
+    /** Custom logo URL */
+    logoUrl?: string;
+    /** Custom favicon URL */
+    faviconUrl?: string;
+    /** Primary brand color (hex) */
+    primaryColor?: string;
+    /** Secondary brand color (hex) */
+    secondaryColor?: string;
+    /** White-label company name */
+    companyName?: string;
+}
+/**
+ * Organization membership information
+ */
+interface FFIDOrganization {
+    /** Organization ID (UUID) */
+    id: string;
+    /** Organization name */
+    name: string;
+    /** URL-safe slug */
+    slug: string;
+    /** User's role in this organization */
+    role: 'owner' | 'admin' | 'member';
+    /** Membership status */
+    status: 'active' | 'invited' | 'suspended';
+    /** Agency branding (null if org is not linked to an agency) */
+    agencyBranding: FFIDAgencyBranding | null;
+}
+/**
+ * Subscription/contract information
+ */
+interface FFIDSubscription {
+    /** Subscription ID (UUID) */
+    id: string;
+    /** Service code (e.g., 'chatbot') */
+    serviceCode: string;
+    /** Service display name */
+    serviceName: string;
+    /** Plan code (e.g., 'basic', 'pro') */
+    planCode: string;
+    /** Plan display name */
+    planName: string;
+    /** Subscription status */
+    status: 'trialing' | 'active' | 'past_due' | 'canceled' | 'paused';
+    /** Current billing period end date */
+    currentPeriodEnd: string | null;
+    /** Service seat model (available when sourced from OAuth userinfo) */
+    seatModel?: FFIDSeatModel | undefined;
+    /** Member role in the resolved organization context */
+    memberRole?: FFIDOAuthUserInfoMemberRole | undefined;
+    /** Organization ID used to resolve subscription access */
+    organizationId?: string | null | undefined;
+}
+/** OAuth userinfo subscription summary */
+interface FFIDOAuthUserInfoSubscription {
+    subscriptionId: string | null;
+    status: 'trialing' | 'active' | 'past_due' | 'canceled' | 'paused' | null;
+    planCode: string | null;
+    seatModel: FFIDSeatModel | null;
+    memberRole: FFIDOAuthUserInfoMemberRole | null;
+    organizationId: string | null;
+}
+/** OAuth userinfo response exposed by FFID */
+interface FFIDOAuthUserInfo {
+    sub: string;
+    email: string | null;
+    name: string | null;
+    picture: string | null;
+    organizationId?: string | null | undefined;
+    subscription?: FFIDOAuthUserInfoSubscription | undefined;
+}
+/**
+ * SDK configuration options
+ */
+interface FFIDConfig {
+    /** Service code to identify your application */
+    serviceCode: string;
+    /** FFID API base URL (defaults to production) */
+    apiBaseUrl?: string | undefined;
+    /**
+     * Enable debug logging (deprecated: use logger instead)
+     * When true and no logger provided, uses console for logging
+     * @deprecated Use `logger` option for custom logging
+     */
+    debug?: boolean | undefined;
+    /**
+     * Custom logger for SDK debug output
+     * If not provided: uses no-op logger (silent)
+     * If debug=true and no logger: uses console
+     */
+    logger?: FFIDLogger | undefined;
+    /** Session refresh interval in milliseconds */
+    refreshInterval?: number | undefined;
+    /** Callback when authentication state changes */
+    onAuthStateChange?: ((user: FFIDUser | null) => void) | undefined;
+    /** Callback on authentication error */
+    onError?: ((error: FFIDError) => void) | undefined;
+    /** Authentication mode: 'cookie' (default), 'token' (OAuth Bearer), or 'service-key' (server-to-server) */
+    authMode?: 'cookie' | 'token' | 'service-key' | undefined;
+    /** Client ID for token mode (defaults to serviceCode if not set) */
+    clientId?: string | undefined;
+    /** Custom redirect URI for OAuth flow (defaults to window.location.origin + window.location.pathname) */
+    redirectUri?: string | undefined;
+    /** Service API key for service-key mode (X-Service-Api-Key header) */
+    serviceApiKey?: string | undefined;
+    /**
+     * Token verification strategy for service-key mode.
+     * - 'jwt': Local JWT verification via JWKS (default, lower latency)
+     * - 'introspect': Remote introspection via /api/v1/oauth/introspect
+     *
+     * JWT verification returns limited claims (no email/name/picture/subscription).
+     * Use 'introspect' if you need full user profile data.
+     */
+    verifyStrategy?: 'jwt' | 'introspect' | undefined;
+    /**
+     * Cache configuration for token verification results.
+     * When set, introspect/userinfo responses are cached to reduce API calls.
+     * Only effective in service-key mode with verifyStrategy: 'introspect'.
+     */
+    cache?: FFIDCacheConfig | undefined;
+    /**
+     * Request timeout in milliseconds for FFID API calls.
+     * Applies to token verification and introspection requests.
+     * @default undefined (no timeout, uses fetch default)
+     */
+    timeout?: number | undefined;
+}
+/**
+ * Logger interface for SDK debug output
+ *
+ * Allows injection of custom loggers (e.g., winston, pino)
+ * or use of the built-in console logger when debug is enabled
+ */
+interface FFIDLogger {
+    /** Debug level logging */
+    debug: (...args: unknown[]) => void;
+    /** Info level logging */
+    info: (...args: unknown[]) => void;
+    /** Warning level logging */
+    warn: (...args: unknown[]) => void;
+    /** Error level logging */
+    error: (...args: unknown[]) => void;
+}
+/**
+ * FFID error object
+ */
+interface FFIDError {
+    /** Error code */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Additional error details */
+    details?: Record<string, unknown>;
+}
+/**
+ * Session response from FFID API
+ */
+interface FFIDSessionResponse {
+    user: FFIDUser;
+    organizations: FFIDOrganization[];
+    subscriptions: FFIDSubscription[];
+}
+/**
+ * API response wrapper (discriminated union for type safety)
+ *
+ * Either data is present (success) or error is present (failure), never both.
+ * This pattern ensures callers handle both cases explicitly.
+ */
+type FFIDApiResponse<T> = {
+    data: T;
+    error?: undefined;
+} | {
+    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 {
+    hasActiveSubscription: boolean;
+    organizationId: string | null;
+    subscriptionId: string | null;
+    status: FFIDSubscriptionStatus | null;
+    planCode: string | null;
+    currentPeriodEnd: string | null;
+}
+/**
+ * Checkout session response from billing checkout endpoint
+ */
+interface FFIDCheckoutSessionResponse {
+    /** Stripe Checkout session ID */
+    sessionId: string;
+    /** Stripe Checkout session URL (null if session creation had issues) */
+    url: string | null;
+}
+/**
+ * Portal session response from billing portal endpoint
+ */
+interface FFIDPortalSessionResponse {
+    /** Stripe Billing Portal URL */
+    url: string;
+}
+/**
+ * Parameters for creating a checkout session
+ */
+interface FFIDCreateCheckoutParams {
+    /** Organization ID (UUID) */
+    organizationId: string;
+    /** Subscription ID (UUID) */
+    subscriptionId: string;
+    /** URL to redirect after successful checkout */
+    successUrl: string;
+    /** URL to redirect after cancelled checkout */
+    cancelUrl: string;
+    /** Optional plan ID for upgrade or resubscription */
+    planId?: string;
+}
+/**
+ * Parameters for creating a billing portal session
+ */
+interface FFIDCreatePortalParams {
+    /** Organization ID (UUID) */
+    organizationId: string;
+    /** URL to redirect when user exits the portal */
+    returnUrl: string;
+}
+
+/**
+ * Token Store
+ *
+ * Manages OAuth 2.0 tokens (access + refresh) with dual-storage support.
+ * Falls back to in-memory storage when localStorage is unavailable
+ * (e.g., Safari private browsing mode).
+ */
+/**
+ * Token data stored by the token store
+ */
+interface TokenData {
+    /** OAuth 2.0 access token */
+    accessToken: string;
+    /** OAuth 2.0 refresh token */
+    refreshToken: string;
+    /** Expiration timestamp in milliseconds (Unix epoch) */
+    expiresAt: number;
+}
+/**
+ * Token store interface for managing OAuth tokens
+ */
+interface TokenStore {
+    /** Get stored tokens (null if not stored) */
+    getTokens(): TokenData | null;
+    /** Store new tokens */
+    setTokens(tokens: TokenData): void;
+    /** Clear all stored tokens */
+    clearTokens(): void;
+    /** Check if access token is expired (with 30s buffer) */
+    isAccessTokenExpired(): boolean;
+}
+/**
+ * Create a token store with the specified storage type.
+ *
+ * When storageType is 'localStorage' (default in browser), falls back
+ * to memory if localStorage is not available (e.g., Safari private mode).
+ *
+ * @param storageType - 'localStorage' (default) or 'memory'
+ */
+declare function createTokenStore(storageType?: 'localStorage' | 'memory'): TokenStore;
+
+/** Creates an FFID API client instance */
+declare function createFFIDClient(config: FFIDConfig): {
+    getSession: () => Promise<FFIDApiResponse<FFIDSessionResponse>>;
+    signOut: () => Promise<FFIDApiResponse<void>>;
+    redirectToLogin: () => boolean;
+    getLoginUrl: (redirectUrl?: string) => string;
+    getSignupUrl: (redirectUrl?: string) => string;
+    createError: (code: string, message: string) => FFIDError;
+    exchangeCodeForTokens: (code: string, codeVerifier?: string) => Promise<FFIDApiResponse<void>>;
+    refreshAccessToken: () => Promise<FFIDApiResponse<void>>;
+    checkSubscription: (params: {
+        userId: string;
+        organizationId: string;
+    }) => Promise<FFIDApiResponse<FFIDSubscriptionCheckResponse>>;
+    createCheckoutSession: (params: FFIDCreateCheckoutParams) => Promise<FFIDApiResponse<FFIDCheckoutSessionResponse>>;
+    createPortalSession: (params: FFIDCreatePortalParams) => Promise<FFIDApiResponse<FFIDPortalSessionResponse>>;
+    verifyAccessToken: (accessToken: string) => Promise<FFIDApiResponse<FFIDOAuthUserInfo>>;
+    /** Token store (token mode only) */
+    tokenStore: TokenStore;
+    /** Resolved auth mode */
+    authMode: "cookie" | "token" | "service-key";
+    /** Resolved logger instance */
+    logger: FFIDLogger;
+    baseUrl: string;
+    serviceCode: string;
+    clientId: string;
+    redirectUri: string | null;
+};
+/** Type of the FFID client */
+type FFIDClient = ReturnType<typeof createFFIDClient>;
+
+/** Token verification - verifyAccessToken() implementation */
+
+/** Dependencies required by verifyAccessToken */
+interface VerifyAccessTokenDeps {
+    authMode: string;
+    baseUrl: string;
+    serviceCode: string;
+    serviceApiKey: string | undefined;
+    verifyStrategy: 'jwt' | 'introspect';
+    logger: FFIDLogger;
+    createError: (code: string, message: string) => FFIDError;
+    errorCodes: {
+        NETWORK_ERROR: string;
+        PARSE_ERROR: string;
+        TOKEN_VERIFICATION_ERROR: string;
+    };
+    cache?: {
+        adapter: FFIDCacheAdapter;
+        ttl: number;
+    } | undefined;
+    timeout?: number | undefined;
+}
+/**
+ * Creates a verifyAccessToken function bound to the given client dependencies.
+ *
+ * Supports two strategies:
+ * - 'jwt': Local JWT verification via JWKS (default, lower latency)
+ * - 'introspect': Remote token introspection (full user profile data)
+ */
+declare function createVerifyAccessToken(deps: VerifyAccessTokenDeps): (accessToken: string) => Promise<FFIDApiResponse<FFIDOAuthUserInfo>>;
+
+/**
+ * Create an in-memory cache adapter using a Map.
+ * Suitable for single-process environments (e.g., development, testing).
+ */
+declare function createMemoryCacheAdapter(): FFIDCacheAdapter;
+
+/**
+ * Minimal KVNamespace-compatible interface.
+ * Matches Cloudflare Workers KV without requiring the CF Workers dependency.
+ */
+interface KVNamespaceLike {
+    get(key: string, type: 'json'): Promise<unknown | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * Create a cache adapter backed by a KVNamespace-compatible store.
+ * Suitable for Cloudflare Workers and other KV-based environments.
+ */
+declare function createKVCacheAdapter(kv: KVNamespaceLike): FFIDCacheAdapter;
+
+export { type FFIDCacheAdapter, type FFIDCacheConfig, type FFIDClient, type FFIDConfig, type FFIDOAuthUserInfo, type FFIDOrganization, type FFIDSubscription, type FFIDUser, type KVNamespaceLike, type TokenData, type TokenStore, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createTokenStore, createVerifyAccessToken };