@edge-markets/connect 1.0.0 → 1.3.0

package/README.md

@@ -132,3 +132,9 @@ isApiError(error)            // API error
 MIT
 
 
+
+
+
+
+
+

package/dist/index.d.mts

@@ -1,3 +1,139 @@
+type EdgeEnvironment = 'production' | 'staging' | 'sandbox' | 'development';
+interface EdgeEnvironmentConfig {
+    /**
+     * @deprecated cognitoDomain is no longer used. Token exchange now goes through EdgeBoost API.
+     */
+    cognitoDomain: string;
+    apiBaseUrl: string;
+    oauthBaseUrl: string;
+    userClientUrl: string;
+    displayName: string;
+    isProduction: boolean;
+}
+declare const EDGE_ENVIRONMENTS: Readonly<Record<EdgeEnvironment, EdgeEnvironmentConfig>>;
+declare function getEnvironmentConfig(environment: EdgeEnvironment): EdgeEnvironmentConfig;
+declare function isProductionEnvironment(environment: EdgeEnvironment): boolean;
+declare function getAvailableEnvironments(): readonly EdgeEnvironment[];
+
+/**
+ * EDGE Connect OAuth Scopes
+ *
+ * OAuth scopes define what permissions your application requests from users.
+ * Each scope grants access to specific API endpoints.
+ *
+ * @module @edge-markets/connect/config
+ */
+/**
+ * Available OAuth scopes for EDGE Connect.
+ *
+ * Request the minimum scopes your application needs.
+ * Users see these permissions during the consent flow.
+ *
+ * @example
+ * ```typescript
+ * // Request only what you need
+ * link.open({
+ *   scopes: [EDGE_SCOPES.USER_READ, EDGE_SCOPES.BALANCE_READ],
+ * })
+ *
+ * // Or request all scopes
+ * link.open({
+ *   scopes: ALL_EDGE_SCOPES,
+ * })
+ * ```
+ */
+declare const EDGE_SCOPES: {
+    /**
+     * Read user profile information (name, email).
+     * Required for: `GET /v1/user`
+     */
+    readonly USER_READ: "user.read";
+    /**
+     * Read account balance.
+     * Required for: `GET /v1/balance`
+     */
+    readonly BALANCE_READ: "balance.read";
+    /**
+     * Initiate and verify fund transfers.
+     * Required for: `POST /v1/transfer`, `POST /v1/transfer/:id/verify`, `GET /v1/transfers`
+     */
+    readonly TRANSFER_WRITE: "transfer.write";
+};
+/**
+ * Type representing a valid EDGE Connect scope.
+ */
+type EdgeScope = (typeof EDGE_SCOPES)[keyof typeof EDGE_SCOPES];
+/**
+ * All available scopes as an array.
+ * Use when you need full access to all API features.
+ *
+ * @example
+ * ```typescript
+ * const link = new EdgeLink({
+ *   clientId: 'your-client-id',
+ *   environment: 'staging',
+ *   scopes: ALL_EDGE_SCOPES, // Request all permissions
+ *   onSuccess: handleSuccess,
+ * })
+ * ```
+ */
+declare const ALL_EDGE_SCOPES: readonly EdgeScope[];
+/**
+ * Human-readable descriptions for each scope.
+ * Useful for building custom consent UIs or explaining permissions.
+ */
+declare const SCOPE_DESCRIPTIONS: Readonly<Record<EdgeScope, string>>;
+/**
+ * Icons for each scope (for UI display).
+ * Using common icon library names (e.g., Lucide, Heroicons).
+ */
+declare const SCOPE_ICONS: Readonly<Record<EdgeScope, string>>;
+/**
+ * Builds the full scope string for a given environment.
+ *
+ * Different environments may use different scope prefixes in the API Gateway.
+ * This function handles the prefix automatically.
+ *
+ * Note: 'development' environment uses 'staging' scope prefix because it
+ * connects to the staging API Gateway for local testing.
+ *
+ * @param scope - The scope to format
+ * @param environment - The target environment
+ * @returns The full scope string for API Gateway authorization
+ *
+ * @example
+ * ```typescript
+ * formatScopeForEnvironment('user.read', 'staging')
+ * // Returns: 'edge-connect-staging/user.read'
+ *
+ * formatScopeForEnvironment('user.read', 'production')
+ * // Returns: 'edge-connect/user.read'
+ *
+ * formatScopeForEnvironment('user.read', 'development')
+ * // Returns: 'edge-connect-staging/user.read' (maps to staging)
+ * ```
+ */
+declare function formatScopeForEnvironment(scope: EdgeScope, environment: 'production' | 'staging' | 'sandbox' | 'development'): string;
+/**
+ * Formats multiple scopes for an environment.
+ *
+ * @param scopes - Array of scopes to format
+ * @param environment - The target environment
+ * @returns Array of full scope strings
+ */
+declare function formatScopesForEnvironment(scopes: readonly EdgeScope[] | EdgeScope[], environment: 'production' | 'staging' | 'sandbox' | 'development'): string[];
+/**
+ * Parses a full scope string to extract the base scope.
+ *
+ * @param fullScope - The full scope string (e.g., 'edge-connect-staging/user.read')
+ * @returns The base scope (e.g., 'user.read') or null if invalid
+ */
+declare function parseScope(fullScope: string): EdgeScope | null;
+/**
+ * Checks if a scope string is valid.
+ */
+declare function isValidScope(scope: string): scope is EdgeScope;
+
 /**
  * This file was auto-generated by openapi-typescript.
  * Do not make direct changes to the file.
@@ -2308,6 +2444,67 @@ type OtpMethod = 'sms' | 'totp';
  * Parameters for listing transfers.
  */
 type ListTransfersParams = NonNullable<operations['listTransfers']['parameters']['query']>;
+/**
+ * Address block for identity verification.
+ * The block itself is required; all sub-fields are optional — supply as many
+ * as the partner holds for a higher-confidence match.
+ */
+interface VerifyIdentityAddress {
+    /** Street address line (e.g. "123 Main St") */
+    street?: string;
+    city?: string;
+    /** US state code (e.g. "TX") */
+    state?: string;
+    zip?: string;
+}
+/**
+ * Options for `EdgeConnectServer.verifyIdentity()`.
+ *
+ * @example
+ * ```typescript
+ * const options: VerifyIdentityOptions = {
+ *   firstName: 'John',
+ *   lastName: 'Doe',
+ *   address: { street: '123 Main St', city: 'Austin', state: 'TX', zip: '78701' },
+ * }
+ * ```
+ */
+interface VerifyIdentityOptions {
+    firstName: string;
+    lastName: string;
+    /**
+     * Address details are required per the verification contract.
+     * All sub-fields within the block are individually optional — supply as many
+     * as the partner holds for a higher-confidence match.
+     * Address threshold enforcement is skipped if the EdgeBoost user has no address on file.
+     */
+    address: VerifyIdentityAddress;
+}
+/**
+ * Similarity scores returned when identity verification passes.
+ * Partners should log these for their own audit trail.
+ */
+interface VerifyIdentityScores {
+    /** Levenshtein-based full-name similarity score (0–100). Threshold: 70. */
+    name: number;
+    /** Levenshtein-based combined address similarity score (0–100). Threshold: 65. */
+    address: number;
+    /** Whether the ZIP code is an exact digit match. */
+    zipMatch: boolean;
+}
+/**
+ * Response from a successful `verifyIdentity()` call.
+ *
+ * @example
+ * ```typescript
+ * const result: VerifyIdentityResult = await edge.verifyIdentity(accessToken, options)
+ * console.log(`Name score: ${result.scores.name}`) // e.g. 95
+ * ```
+ */
+interface VerifyIdentityResult {
+    verified: true;
+    scores: VerifyIdentityScores;
+}
 /**
  * All possible transfer types.
  * Use for validation or building UI select options.
@@ -2429,201 +2626,29 @@ interface EdgeLinkExit {
         message: string;
     };
 }
-
-/**
- * EDGE Connect Environment Configuration
- *
- * Defines the URLs and settings for each deployment environment.
- * Partners select an environment when initializing the SDK.
- *
- * @module @edge-markets/connect/config
- */
-/**
- * Available EDGE Connect environments.
- *
- * - `production`: Live environment with real money
- * - `staging`: Test environment with test accounts (use during development)
- * - `sandbox`: Isolated environment with mock data (coming soon)
- *
- * @example
- * ```typescript
- * const edge = new EdgeConnectServer({
- *   clientId: process.env.EDGE_CLIENT_ID,
- *   clientSecret: process.env.EDGE_CLIENT_SECRET,
- *   environment: 'staging', // <-- autocomplete shows all options
- * })
- * ```
- */
-type EdgeEnvironment = 'production' | 'staging' | 'sandbox';
-/**
- * Configuration for a specific environment.
- */
-interface EdgeEnvironmentConfig {
-    /** Legacy: Cognito domain for OAuth token endpoints. */
-    authDomain: string;
-    /** Base URL for the Connect API endpoints (without trailing slash). */
-    apiBaseUrl: string;
-    /** Base URL for OAuth token operations (without trailing slash). */
-    oauthBaseUrl: string;
-    /** URL for the EdgeBoost user client (for Link popup). */
-    userClientUrl: string;
-    /** Human-readable name for debugging/logging. */
-    displayName: string;
-    /** Whether this environment uses real money. */
-    isProduction: boolean;
+/** PKCE code verifier and challenge pair */
+interface PKCEPair {
+    verifier: string;
+    challenge: string;
+}
+/** Event emitted during the Link flow */
+interface EdgeLinkEvent {
+    eventName: EdgeLinkEventName;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+/** All possible Link event names (superset of browser + mobile events) */
+type EdgeLinkEventName = 'OPEN' | 'CLOSE' | 'HANDOFF' | 'TRANSITION' | 'REDIRECT' | 'ERROR' | 'SUCCESS';
+/** Base configuration shared by all EdgeLink implementations */
+interface EdgeLinkConfigBase {
+    clientId: string;
+    environment: EdgeEnvironment;
+    onSuccess: (result: EdgeLinkSuccess) => void;
+    onExit?: (metadata: EdgeLinkExit) => void;
+    onEvent?: (event: EdgeLinkEvent) => void;
+    scopes?: EdgeScope[];
+    linkUrl?: string;
 }
-/**
- * Environment configurations.
- *
- * These URLs are updated when infrastructure changes.
- * Partners shouldn't need to modify these directly.
- */
-declare const EDGE_ENVIRONMENTS: Readonly<Record<EdgeEnvironment, EdgeEnvironmentConfig>>;
-/**
- * Gets the configuration for a specific environment.
- *
- * @param environment - The environment to get config for
- * @returns The environment configuration
- *
- * @example
- * ```typescript
- * const config = getEnvironmentConfig('staging')
- * console.log(`Using ${config.displayName} at ${config.apiBaseUrl}`)
- * ```
- */
-declare function getEnvironmentConfig(environment: EdgeEnvironment): EdgeEnvironmentConfig;
-/**
- * Checks if an environment is the production environment.
- *
- * @param environment - The environment to check
- * @returns true if this is the production environment
- *
- * @example
- * ```typescript
- * if (isProductionEnvironment('staging')) {
- *   // false - staging is not production
- * }
- * ```
- */
-declare function isProductionEnvironment(environment: EdgeEnvironment): boolean;
-/**
- * Gets all available environment names.
- * Useful for building environment selectors in admin UIs.
- */
-declare function getAvailableEnvironments(): readonly EdgeEnvironment[];
-
-/**
- * EDGE Connect OAuth Scopes
- *
- * OAuth scopes define what permissions your application requests from users.
- * Each scope grants access to specific API endpoints.
- *
- * @module @edge-markets/connect/config
- */
-/**
- * Available OAuth scopes for EDGE Connect.
- *
- * Request the minimum scopes your application needs.
- * Users see these permissions during the consent flow.
- *
- * @example
- * ```typescript
- * // Request only what you need
- * link.open({
- *   scopes: [EDGE_SCOPES.USER_READ, EDGE_SCOPES.BALANCE_READ],
- * })
- *
- * // Or request all scopes
- * link.open({
- *   scopes: ALL_EDGE_SCOPES,
- * })
- * ```
- */
-declare const EDGE_SCOPES: {
-    /**
-     * Read user profile information (name, email).
-     * Required for: `GET /v1/user`
-     */
-    readonly USER_READ: "user.read";
-    /**
-     * Read account balance.
-     * Required for: `GET /v1/balance`
-     */
-    readonly BALANCE_READ: "balance.read";
-    /**
-     * Initiate and verify fund transfers.
-     * Required for: `POST /v1/transfer`, `POST /v1/transfer/:id/verify`, `GET /v1/transfers`
-     */
-    readonly TRANSFER_WRITE: "transfer.write";
-};
-/**
- * Type representing a valid EDGE Connect scope.
- */
-type EdgeScope = (typeof EDGE_SCOPES)[keyof typeof EDGE_SCOPES];
-/**
- * All available scopes as an array.
- * Use when you need full access to all API features.
- *
- * @example
- * ```typescript
- * const link = new EdgeLink({
- *   clientId: 'your-client-id',
- *   environment: 'staging',
- *   scopes: ALL_EDGE_SCOPES, // Request all permissions
- *   onSuccess: handleSuccess,
- * })
- * ```
- */
-declare const ALL_EDGE_SCOPES: readonly EdgeScope[];
-/**
- * Human-readable descriptions for each scope.
- * Useful for building custom consent UIs or explaining permissions.
- */
-declare const SCOPE_DESCRIPTIONS: Readonly<Record<EdgeScope, string>>;
-/**
- * Icons for each scope (for UI display).
- * Using common icon library names (e.g., Lucide, Heroicons).
- */
-declare const SCOPE_ICONS: Readonly<Record<EdgeScope, string>>;
-/**
- * Builds the full scope string for a given environment.
- *
- * Different environments may use different scope prefixes in Cognito.
- * This function handles the prefix automatically.
- *
- * @param scope - The scope to format
- * @param environment - The target environment
- * @returns The full scope string for Cognito
- *
- * @example
- * ```typescript
- * formatScopeForEnvironment('user.read', 'staging')
- * // Returns: 'edge-connect-staging/user.read'
- *
- * formatScopeForEnvironment('user.read', 'production')
- * // Returns: 'edge-connect/user.read'
- * ```
- */
-declare function formatScopeForEnvironment(scope: EdgeScope, environment: 'production' | 'staging' | 'sandbox'): string;
-/**
- * Formats multiple scopes for an environment.
- *
- * @param scopes - Array of scopes to format
- * @param environment - The target environment
- * @returns Array of full scope strings
- */
-declare function formatScopesForEnvironment(scopes: readonly EdgeScope[] | EdgeScope[], environment: 'production' | 'staging' | 'sandbox'): string[];
-/**
- * Parses a full scope string to extract the base scope.
- *
- * @param fullScope - The full scope string (e.g., 'edge-connect-staging/user.read')
- * @returns The base scope (e.g., 'user.read') or null if invalid
- */
-declare function parseScope(fullScope: string): EdgeScope | null;
-/**
- * Checks if a scope string is valid.
- */
-declare function isValidScope(scope: string): scope is EdgeScope;
 
 /**
  * EDGE Connect SDK Error Classes
@@ -2838,6 +2863,32 @@ declare class EdgeValidationError extends EdgeError {
     readonly validationErrors: Record<string, string[]>;
     constructor(message: string, validationErrors: Record<string, string[]>);
 }
+/**
+ * Thrown when identity verification fails because one or more fields do not meet
+ * the similarity threshold when compared against the user's stored EdgeBoost profile.
+ *
+ * The `fieldErrors` map contains only the fields that failed verification.
+ * Each value is a human-readable message safe to display directly to the user.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await edge.verifyIdentity(accessToken, { firstName: 'John', lastName: 'Doe', address: {} })
+ * } catch (error) {
+ *   if (error instanceof EdgeIdentityVerificationError) {
+ *     if (error.fieldErrors.name) {
+ *       showMessage(error.fieldErrors.name)
+ *       // "Name doesn't match what is on file, please contact support"
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class EdgeIdentityVerificationError extends EdgeError {
+    /** Field-level messages for each failing field. Keys match the request fields (e.g. `name`, `address`). */
+    readonly fieldErrors: Record<string, string>;
+    constructor(fieldErrors: Record<string, string>, message?: string);
+}
 /**
  * Thrown when a popup is blocked by the browser.
  *
@@ -2916,6 +2967,10 @@ declare function isConsentRequiredError(error: unknown): error is EdgeConsentReq
  * Type guard for API errors.
  */
 declare function isApiError(error: unknown): error is EdgeApiError;
+/**
+ * Type guard for identity verification errors.
+ */
+declare function isIdentityVerificationError(error: unknown): error is EdgeIdentityVerificationError;
 /**
  * Type guard for network errors.
  */
@@ -2968,4 +3023,4 @@ declare const SDK_VERSION = "1.0.0";
  */
 declare const SDK_NAME = "@edge-markets/connect";
 
-export { ALL_EDGE_SCOPES, type ApiError, type Balance, type ConsentRequiredError, EDGE_ENVIRONMENTS, EDGE_SCOPES, EdgeApiError, EdgeAuthenticationError, EdgeConsentRequiredError, type EdgeEnvironment, type EdgeEnvironmentConfig, EdgeError, EdgeInsufficientScopeError, type EdgeLinkExit, type EdgeLinkSuccess, EdgeNetworkError, EdgeNotFoundError, EdgePopupBlockedError, EdgePopupClosedError, type EdgeScope, EdgeStateMismatchError, EdgeTokenExchangeError, type EdgeTokens, EdgeValidationError, type InitiateTransferRequest, type ListTransfersParams, OTP_METHODS, type OtpMethod, type RevokeConsentResponse, SCOPE_DESCRIPTIONS, SCOPE_ICONS, SDK_NAME, SDK_VERSION, TRANSFER_STATUSES, TRANSFER_TYPES, type Transfer, type TransferList, type TransferListItem, type TransferStatus, type TransferType, type User, type VerifyTransferRequest, type components, formatScopeForEnvironment, formatScopesForEnvironment, getAvailableEnvironments, getEnvironmentConfig, isApiError, isAuthenticationError, isConsentRequiredError, isEdgeError, isNetworkError, isProductionEnvironment, isValidScope, type operations, parseScope, type paths };
+export { ALL_EDGE_SCOPES, type ApiError, type Balance, type ConsentRequiredError, EDGE_ENVIRONMENTS, EDGE_SCOPES, EdgeApiError, EdgeAuthenticationError, EdgeConsentRequiredError, type EdgeEnvironment, type EdgeEnvironmentConfig, EdgeError, EdgeIdentityVerificationError, EdgeInsufficientScopeError, type EdgeLinkConfigBase, type EdgeLinkEvent, type EdgeLinkEventName, type EdgeLinkExit, type EdgeLinkSuccess, EdgeNetworkError, EdgeNotFoundError, EdgePopupBlockedError, EdgePopupClosedError, type EdgeScope, EdgeStateMismatchError, EdgeTokenExchangeError, type EdgeTokens, EdgeValidationError, type InitiateTransferRequest, type ListTransfersParams, OTP_METHODS, type OtpMethod, type PKCEPair, type RevokeConsentResponse, SCOPE_DESCRIPTIONS, SCOPE_ICONS, SDK_NAME, SDK_VERSION, TRANSFER_STATUSES, TRANSFER_TYPES, type Transfer, type TransferList, type TransferListItem, type TransferStatus, type TransferType, type User, type VerifyIdentityAddress, type VerifyIdentityOptions, type VerifyIdentityResult, type VerifyIdentityScores, type VerifyTransferRequest, type components, formatScopeForEnvironment, formatScopesForEnvironment, getAvailableEnvironments, getEnvironmentConfig, isApiError, isAuthenticationError, isConsentRequiredError, isEdgeError, isIdentityVerificationError, isNetworkError, isProductionEnvironment, isValidScope, type operations, parseScope, type paths };