@treeviz/familysearch-sdk 1.0.24 → 2.0.1

package/dist/index-D-O_e-PM.d.cts

@@ -0,0 +1,359 @@
+/**
+ * Core SDK Types
+ *
+ * Environment configuration, SDK initialization, and base API types
+ */
+/**
+ * FamilySearch API environment
+ */
+type FamilySearchEnvironment = "production" | "beta" | "integration";
+/**
+ * Environment-specific endpoint configuration
+ */
+interface EnvironmentConfig {
+    /** Identity server host for OAuth */
+    identHost: string;
+    /** Platform API host for data operations */
+    platformHost: string;
+}
+/**
+ * Rate limiter configuration
+ */
+interface RateLimiterConfig {
+    /** Maximum requests per second (default: 10) */
+    requestsPerSecond?: number;
+    /** Maximum burst size (default: 20) */
+    maxBurst?: number;
+    /** Maximum retry attempts for 429 errors (default: 3) */
+    maxRetries?: number;
+    /** Initial backoff delay in ms (default: 1000) */
+    initialBackoffMs?: number;
+    /** Maximum backoff delay in ms (default: 30000) */
+    maxBackoffMs?: number;
+    /** Jitter factor (0-1) to add randomness to backoff delays (default: 0.3 = 30%) */
+    jitterFactor?: number;
+}
+/**
+ * SDK initialization options
+ */
+interface FamilySearchSDKConfig {
+    /** API environment (default: "integration") */
+    environment?: FamilySearchEnvironment;
+    /** OAuth access token */
+    accessToken?: string;
+    /** Application key for API requests */
+    appKey?: string;
+    /** OAuth redirect URI (required for OAuth flows) */
+    redirectUri?: string;
+    /** Optional logger for debugging */
+    logger?: SDKLogger;
+    /** Optional rate limiter configuration */
+    rateLimiter?: RateLimiterConfig;
+}
+/**
+ * Logger interface for SDK debugging
+ */
+interface SDKLogger {
+    log: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+}
+/**
+ * Generic API response wrapper
+ */
+interface FamilySearchApiResponse<T> {
+    /** Response data */
+    data?: T;
+    /** HTTP status code */
+    statusCode: number;
+    /** HTTP status text */
+    statusText: string;
+    /** Response headers */
+    headers: Record<string, string>;
+}
+/**
+ * API error with additional context
+ */
+interface FamilySearchApiError extends Error {
+    /** HTTP status code if available */
+    statusCode?: number;
+    /** Full response object */
+    response?: FamilySearchApiResponse<unknown>;
+}
+/**
+ * Progress callback for long operations
+ */
+type ProgressCallback = (progress: {
+    stage: string;
+    current: number;
+    total: number;
+    percent: number;
+}) => void;
+
+/**
+ * OAuth API Types
+ *
+ * Types for OAuth authentication flow
+ */
+
+/**
+ * OAuth token response
+ */
+interface OAuthTokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in?: number;
+    refresh_token?: string;
+    id_token?: string;
+}
+/**
+ * OAuth endpoints for an environment
+ */
+interface OAuthEndpoints {
+    authorization: string;
+    token: string;
+    currentUser: string;
+}
+/**
+ * OAuth configuration
+ */
+interface OAuthConfig {
+    clientId: string;
+    redirectUri: string;
+    environment?: FamilySearchEnvironment;
+}
+/**
+ * OAuth state validation result
+ */
+interface OAuthStateValidation {
+    valid: boolean;
+    isLinkMode: boolean;
+    lang?: string;
+    parentUid?: string;
+}
+
+/**
+ * FamilySearch OAuth Authentication Module
+ *
+ * Provides OAuth 2.0 authentication utilities for FamilySearch API v3.
+ * This module is designed to be framework-agnostic and can be used
+ * in any JavaScript/TypeScript environment.
+ */
+
+declare const OAUTH_ENDPOINTS: Record<FamilySearchEnvironment, OAuthEndpoints>;
+/**
+ * Get OAuth endpoints for a specific environment
+ */
+declare function getOAuthEndpoints(environment?: FamilySearchEnvironment): OAuthEndpoints;
+/**
+ * Generate a cryptographically secure random state for CSRF protection
+ */
+declare function generateOAuthState(): string;
+/**
+ * Build the authorization URL for OAuth flow
+ */
+declare function buildAuthorizationUrl(config: OAuthConfig, state: string, options?: {
+    scopes?: string[];
+    prompt?: string;
+}): string;
+/**
+ * Exchange authorization code for access token
+ */
+declare function exchangeCodeForToken(code: string, config: OAuthConfig): Promise<OAuthTokenResponse>;
+/**
+ * Refresh an access token using a refresh token
+ */
+declare function refreshAccessToken(refreshToken: string, config: OAuthConfig): Promise<OAuthTokenResponse>;
+/**
+ * Validate an access token by making a test API call
+ */
+declare function validateAccessToken(accessToken: string, environment?: FamilySearchEnvironment): Promise<boolean>;
+/**
+ * Get user info from access token
+ */
+declare function getUserInfo(accessToken: string, environment?: FamilySearchEnvironment): Promise<{
+    sub: string;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    email?: string;
+    email_verified?: boolean;
+} | null>;
+/**
+ * Storage keys for OAuth state management
+ */
+declare const OAUTH_STORAGE_KEYS: {
+    readonly state: "fs_oauth_state";
+    readonly linkMode: "fs_oauth_link_mode";
+    readonly lang: "fs_oauth_lang";
+    readonly parentUid: "fs_oauth_parent_uid";
+};
+/**
+ * Store OAuth state in localStorage for popup flow
+ * Uses localStorage instead of sessionStorage because popup windows
+ * don't share sessionStorage with the parent window
+ */
+declare function storeOAuthState(state: string, options?: {
+    isLinkMode?: boolean;
+    lang?: string;
+    parentUid?: string;
+}): void;
+/**
+ * Validate OAuth state from callback and extract metadata
+ * Returns invalid state if localStorage is not available (SSR/Node.js environments)
+ */
+declare function validateOAuthState(state: string): OAuthStateValidation;
+/**
+ * Open OAuth authorization in a popup window
+ */
+declare function openOAuthPopup(authUrl: string, options?: {
+    width?: number;
+    height?: number;
+    windowName?: string;
+}): Window | null;
+/**
+ * Parse OAuth callback parameters from URL
+ */
+declare function parseCallbackParams(url?: string): {
+    code?: string;
+    state?: string;
+    error?: string;
+    error_description?: string;
+};
+/**
+ * Generate a storage key scoped to a user ID
+ */
+declare function getTokenStorageKey(userId: string, type: "access" | "expires" | "refresh" | "environment"): string;
+/**
+ * Store access token with expiration
+ * Per FamilySearch compatibility requirements:
+ * - Access tokens stored in sessionStorage (cleared on browser close)
+ * - Refresh tokens stored in localStorage (for re-authentication)
+ */
+declare function storeTokens(userId: string, tokens: {
+    accessToken: string;
+    expiresAt?: number;
+    refreshToken?: string;
+    environment?: string;
+}): void;
+/**
+ * Get stored access token
+ */
+declare function getStoredAccessToken(userId: string): string | null;
+/**
+ * Get stored refresh token
+ */
+declare function getStoredRefreshToken(userId: string): string | null;
+/**
+ * Clear all stored tokens for a user
+ */
+declare function clearStoredTokens(userId: string): void;
+/**
+ * Clear all FamilySearch tokens from storage
+ */
+declare function clearAllTokens(): void;
+/**
+ * OAuthAPI class provides convenient OAuth methods.
+ *
+ * Note: Most OAuth operations don't require SDK instance as they are stateless
+ * utility functions, but having them in a class provides consistency with other
+ * API modules and allows future extension.
+ */
+declare class OAuthAPI {
+    private config;
+    constructor(config: OAuthConfig);
+    /**
+     * Get OAuth endpoints for current environment
+     */
+    getEndpoints(): OAuthEndpoints;
+    /**
+     * Generate a cryptographically secure random state
+     */
+    generateState(): string;
+    /**
+     * Build authorization URL
+     */
+    buildAuthorizationUrl(state: string, options?: {
+        scopes?: string[];
+        prompt?: string;
+    }): string;
+    /**
+     * Exchange authorization code for access token
+     */
+    exchangeCodeForToken(code: string): Promise<OAuthTokenResponse>;
+    /**
+     * Refresh an access token
+     */
+    refreshAccessToken(refreshToken: string): Promise<OAuthTokenResponse>;
+    /**
+     * Validate an access token
+     */
+    validateAccessToken(accessToken: string): Promise<boolean>;
+    /**
+     * Get user info from access token
+     */
+    getUserInfo(accessToken: string): Promise<{
+        sub: string;
+        name?: string;
+        given_name?: string;
+        family_name?: string;
+        email?: string;
+        email_verified?: boolean;
+    } | null>;
+    /**
+     * Store OAuth state in localStorage
+     */
+    storeState(state: string, options?: {
+        isLinkMode?: boolean;
+        lang?: string;
+        parentUid?: string;
+    }): void;
+    /**
+     * Validate OAuth state from callback
+     */
+    validateState(state: string): OAuthStateValidation;
+    /**
+     * Open OAuth authorization in popup
+     */
+    openPopup(authUrl: string, options?: {
+        width?: number;
+        height?: number;
+        windowName?: string;
+    }): Window | null;
+    /**
+     * Parse OAuth callback parameters from URL
+     */
+    parseCallbackParams(url?: string): {
+        code?: string;
+        state?: string;
+        error?: string;
+        error_description?: string;
+    };
+    /**
+     * Store tokens for a user
+     */
+    storeTokens(userId: string, tokens: {
+        accessToken: string;
+        expiresAt?: number;
+        refreshToken?: string;
+        environment?: string;
+    }): void;
+    /**
+     * Get stored access token for a user
+     */
+    getStoredAccessToken(userId: string): string | null;
+    /**
+     * Get stored refresh token for a user
+     */
+    getStoredRefreshToken(userId: string): string | null;
+    /**
+     * Clear all stored tokens for a user
+     */
+    clearStoredTokens(userId: string): void;
+    /**
+     * Clear all FamilySearch tokens from storage
+     */
+    clearAllTokens(): void;
+}
+
+export { type EnvironmentConfig as E, type FamilySearchApiResponse as F, type OAuthTokenResponse as O, type ProgressCallback as P, type RateLimiterConfig as R, type SDKLogger as S, type FamilySearchEnvironment as a, type FamilySearchSDKConfig as b, type FamilySearchApiError as c, type OAuthEndpoints as d, type OAuthConfig as e, type OAuthStateValidation as f, getOAuthEndpoints as g, generateOAuthState as h, buildAuthorizationUrl as i, exchangeCodeForToken as j, getUserInfo as k, OAUTH_STORAGE_KEYS as l, validateOAuthState as m, getTokenStorageKey as n, openOAuthPopup as o, parseCallbackParams as p, storeTokens as q, refreshAccessToken as r, storeOAuthState as s, getStoredAccessToken as t, getStoredRefreshToken as u, validateAccessToken as v, clearStoredTokens as w, clearAllTokens as x, OAUTH_ENDPOINTS as y, OAuthAPI as z };

package/dist/index-D-O_e-PM.d.ts

@@ -0,0 +1,359 @@
+/**
+ * Core SDK Types
+ *
+ * Environment configuration, SDK initialization, and base API types
+ */
+/**
+ * FamilySearch API environment
+ */
+type FamilySearchEnvironment = "production" | "beta" | "integration";
+/**
+ * Environment-specific endpoint configuration
+ */
+interface EnvironmentConfig {
+    /** Identity server host for OAuth */
+    identHost: string;
+    /** Platform API host for data operations */
+    platformHost: string;
+}
+/**
+ * Rate limiter configuration
+ */
+interface RateLimiterConfig {
+    /** Maximum requests per second (default: 10) */
+    requestsPerSecond?: number;
+    /** Maximum burst size (default: 20) */
+    maxBurst?: number;
+    /** Maximum retry attempts for 429 errors (default: 3) */
+    maxRetries?: number;
+    /** Initial backoff delay in ms (default: 1000) */
+    initialBackoffMs?: number;
+    /** Maximum backoff delay in ms (default: 30000) */
+    maxBackoffMs?: number;
+    /** Jitter factor (0-1) to add randomness to backoff delays (default: 0.3 = 30%) */
+    jitterFactor?: number;
+}
+/**
+ * SDK initialization options
+ */
+interface FamilySearchSDKConfig {
+    /** API environment (default: "integration") */
+    environment?: FamilySearchEnvironment;
+    /** OAuth access token */
+    accessToken?: string;
+    /** Application key for API requests */
+    appKey?: string;
+    /** OAuth redirect URI (required for OAuth flows) */
+    redirectUri?: string;
+    /** Optional logger for debugging */
+    logger?: SDKLogger;
+    /** Optional rate limiter configuration */
+    rateLimiter?: RateLimiterConfig;
+}
+/**
+ * Logger interface for SDK debugging
+ */
+interface SDKLogger {
+    log: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+}
+/**
+ * Generic API response wrapper
+ */
+interface FamilySearchApiResponse<T> {
+    /** Response data */
+    data?: T;
+    /** HTTP status code */
+    statusCode: number;
+    /** HTTP status text */
+    statusText: string;
+    /** Response headers */
+    headers: Record<string, string>;
+}
+/**
+ * API error with additional context
+ */
+interface FamilySearchApiError extends Error {
+    /** HTTP status code if available */
+    statusCode?: number;
+    /** Full response object */
+    response?: FamilySearchApiResponse<unknown>;
+}
+/**
+ * Progress callback for long operations
+ */
+type ProgressCallback = (progress: {
+    stage: string;
+    current: number;
+    total: number;
+    percent: number;
+}) => void;
+
+/**
+ * OAuth API Types
+ *
+ * Types for OAuth authentication flow
+ */
+
+/**
+ * OAuth token response
+ */
+interface OAuthTokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in?: number;
+    refresh_token?: string;
+    id_token?: string;
+}
+/**
+ * OAuth endpoints for an environment
+ */
+interface OAuthEndpoints {
+    authorization: string;
+    token: string;
+    currentUser: string;
+}
+/**
+ * OAuth configuration
+ */
+interface OAuthConfig {
+    clientId: string;
+    redirectUri: string;
+    environment?: FamilySearchEnvironment;
+}
+/**
+ * OAuth state validation result
+ */
+interface OAuthStateValidation {
+    valid: boolean;
+    isLinkMode: boolean;
+    lang?: string;
+    parentUid?: string;
+}
+
+/**
+ * FamilySearch OAuth Authentication Module
+ *
+ * Provides OAuth 2.0 authentication utilities for FamilySearch API v3.
+ * This module is designed to be framework-agnostic and can be used
+ * in any JavaScript/TypeScript environment.
+ */
+
+declare const OAUTH_ENDPOINTS: Record<FamilySearchEnvironment, OAuthEndpoints>;
+/**
+ * Get OAuth endpoints for a specific environment
+ */
+declare function getOAuthEndpoints(environment?: FamilySearchEnvironment): OAuthEndpoints;
+/**
+ * Generate a cryptographically secure random state for CSRF protection
+ */
+declare function generateOAuthState(): string;
+/**
+ * Build the authorization URL for OAuth flow
+ */
+declare function buildAuthorizationUrl(config: OAuthConfig, state: string, options?: {
+    scopes?: string[];
+    prompt?: string;
+}): string;
+/**
+ * Exchange authorization code for access token
+ */
+declare function exchangeCodeForToken(code: string, config: OAuthConfig): Promise<OAuthTokenResponse>;
+/**
+ * Refresh an access token using a refresh token
+ */
+declare function refreshAccessToken(refreshToken: string, config: OAuthConfig): Promise<OAuthTokenResponse>;
+/**
+ * Validate an access token by making a test API call
+ */
+declare function validateAccessToken(accessToken: string, environment?: FamilySearchEnvironment): Promise<boolean>;
+/**
+ * Get user info from access token
+ */
+declare function getUserInfo(accessToken: string, environment?: FamilySearchEnvironment): Promise<{
+    sub: string;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    email?: string;
+    email_verified?: boolean;
+} | null>;
+/**
+ * Storage keys for OAuth state management
+ */
+declare const OAUTH_STORAGE_KEYS: {
+    readonly state: "fs_oauth_state";
+    readonly linkMode: "fs_oauth_link_mode";
+    readonly lang: "fs_oauth_lang";
+    readonly parentUid: "fs_oauth_parent_uid";
+};
+/**
+ * Store OAuth state in localStorage for popup flow
+ * Uses localStorage instead of sessionStorage because popup windows
+ * don't share sessionStorage with the parent window
+ */
+declare function storeOAuthState(state: string, options?: {
+    isLinkMode?: boolean;
+    lang?: string;
+    parentUid?: string;
+}): void;
+/**
+ * Validate OAuth state from callback and extract metadata
+ * Returns invalid state if localStorage is not available (SSR/Node.js environments)
+ */
+declare function validateOAuthState(state: string): OAuthStateValidation;
+/**
+ * Open OAuth authorization in a popup window
+ */
+declare function openOAuthPopup(authUrl: string, options?: {
+    width?: number;
+    height?: number;
+    windowName?: string;
+}): Window | null;
+/**
+ * Parse OAuth callback parameters from URL
+ */
+declare function parseCallbackParams(url?: string): {
+    code?: string;
+    state?: string;
+    error?: string;
+    error_description?: string;
+};
+/**
+ * Generate a storage key scoped to a user ID
+ */
+declare function getTokenStorageKey(userId: string, type: "access" | "expires" | "refresh" | "environment"): string;
+/**
+ * Store access token with expiration
+ * Per FamilySearch compatibility requirements:
+ * - Access tokens stored in sessionStorage (cleared on browser close)
+ * - Refresh tokens stored in localStorage (for re-authentication)
+ */
+declare function storeTokens(userId: string, tokens: {
+    accessToken: string;
+    expiresAt?: number;
+    refreshToken?: string;
+    environment?: string;
+}): void;
+/**
+ * Get stored access token
+ */
+declare function getStoredAccessToken(userId: string): string | null;
+/**
+ * Get stored refresh token
+ */
+declare function getStoredRefreshToken(userId: string): string | null;
+/**
+ * Clear all stored tokens for a user
+ */
+declare function clearStoredTokens(userId: string): void;
+/**
+ * Clear all FamilySearch tokens from storage
+ */
+declare function clearAllTokens(): void;
+/**
+ * OAuthAPI class provides convenient OAuth methods.
+ *
+ * Note: Most OAuth operations don't require SDK instance as they are stateless
+ * utility functions, but having them in a class provides consistency with other
+ * API modules and allows future extension.
+ */
+declare class OAuthAPI {
+    private config;
+    constructor(config: OAuthConfig);
+    /**
+     * Get OAuth endpoints for current environment
+     */
+    getEndpoints(): OAuthEndpoints;
+    /**
+     * Generate a cryptographically secure random state
+     */
+    generateState(): string;
+    /**
+     * Build authorization URL
+     */
+    buildAuthorizationUrl(state: string, options?: {
+        scopes?: string[];
+        prompt?: string;
+    }): string;
+    /**
+     * Exchange authorization code for access token
+     */
+    exchangeCodeForToken(code: string): Promise<OAuthTokenResponse>;
+    /**
+     * Refresh an access token
+     */
+    refreshAccessToken(refreshToken: string): Promise<OAuthTokenResponse>;
+    /**
+     * Validate an access token
+     */
+    validateAccessToken(accessToken: string): Promise<boolean>;
+    /**
+     * Get user info from access token
+     */
+    getUserInfo(accessToken: string): Promise<{
+        sub: string;
+        name?: string;
+        given_name?: string;
+        family_name?: string;
+        email?: string;
+        email_verified?: boolean;
+    } | null>;
+    /**
+     * Store OAuth state in localStorage
+     */
+    storeState(state: string, options?: {
+        isLinkMode?: boolean;
+        lang?: string;
+        parentUid?: string;
+    }): void;
+    /**
+     * Validate OAuth state from callback
+     */
+    validateState(state: string): OAuthStateValidation;
+    /**
+     * Open OAuth authorization in popup
+     */
+    openPopup(authUrl: string, options?: {
+        width?: number;
+        height?: number;
+        windowName?: string;
+    }): Window | null;
+    /**
+     * Parse OAuth callback parameters from URL
+     */
+    parseCallbackParams(url?: string): {
+        code?: string;
+        state?: string;
+        error?: string;
+        error_description?: string;
+    };
+    /**
+     * Store tokens for a user
+     */
+    storeTokens(userId: string, tokens: {
+        accessToken: string;
+        expiresAt?: number;
+        refreshToken?: string;
+        environment?: string;
+    }): void;
+    /**
+     * Get stored access token for a user
+     */
+    getStoredAccessToken(userId: string): string | null;
+    /**
+     * Get stored refresh token for a user
+     */
+    getStoredRefreshToken(userId: string): string | null;
+    /**
+     * Clear all stored tokens for a user
+     */
+    clearStoredTokens(userId: string): void;
+    /**
+     * Clear all FamilySearch tokens from storage
+     */
+    clearAllTokens(): void;
+}
+
+export { type EnvironmentConfig as E, type FamilySearchApiResponse as F, type OAuthTokenResponse as O, type ProgressCallback as P, type RateLimiterConfig as R, type SDKLogger as S, type FamilySearchEnvironment as a, type FamilySearchSDKConfig as b, type FamilySearchApiError as c, type OAuthEndpoints as d, type OAuthConfig as e, type OAuthStateValidation as f, getOAuthEndpoints as g, generateOAuthState as h, buildAuthorizationUrl as i, exchangeCodeForToken as j, getUserInfo as k, OAUTH_STORAGE_KEYS as l, validateOAuthState as m, getTokenStorageKey as n, openOAuthPopup as o, parseCallbackParams as p, storeTokens as q, refreshAccessToken as r, storeOAuthState as s, getStoredAccessToken as t, getStoredRefreshToken as u, validateAccessToken as v, clearStoredTokens as w, clearAllTokens as x, OAUTH_ENDPOINTS as y, OAuthAPI as z };