@methodfi/opal-react 0.0.1

package/README.md

@@ -0,0 +1,67 @@
+# @methodfi/opal-react
+
+React SDK for integrating Method Opal into your web applications.
+
+## Installation
+
+```bash
+npm install @methodfi/opal-react
+# or
+yarn add @methodfi/opal-react
+```
+
+## Quick Start
+
+### 1. Provider Setup
+
+Wrap your app with the `OpalProvider`:
+
+```tsx
+import { OpalProvider } from '@methodfi/opal-react';
+
+export default function App() {
+  return (
+    <OpalProvider>
+      <YourAppContent />
+    </OpalProvider>
+  );
+}
+```
+
+### 2. Hook Usage
+
+Use the `useOpal` hook in your components:
+
+```tsx
+import { useOpal } from '@methodfi/opal-react';
+
+function Screen() {
+  const { open } = useOpal({
+    env: 'dev',
+    onOpen: () => {},
+    onExit: () => {},
+    onError: (error) => console.error('Error:', error),
+    onEvent: (event) => {
+      switch (event.type) {
+        case 'opal.session.started': { /* ... */ }
+        case 'opal.session.errored': { /* ... */ }
+        case 'opal.session.exited': { /* ... */ }
+        case 'card_connect.card.verified': { /* ... */ }
+        // See events section
+      }
+    },
+  });
+
+  const onLaunchOpal = async () => {
+    // Resulting token from POST /opal/token (otkn_*)
+    const token = await getOpalToken();
+    open({ token });
+  };
+
+  return (
+    <button onClick={onLaunchOpal}>
+      Launch Opal
+    </button>
+  );
+}
+```

package/dist/components/OpalIframe.d.ts

@@ -0,0 +1,3 @@
+import { OpalIframeProps } from '../types';
+export declare function OpalIframe({ token, opalUrl, onMessage, style, }: OpalIframeProps): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=OpalIframe.d.ts.map

package/dist/components/OpalIframe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpalIframe.d.ts","sourceRoot":"","sources":["../../src/components/OpalIframe.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAE3C,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,OAAO,EACP,SAAS,EACT,KAAK,GACN,EAAE,eAAe,kDAuDjB"}

package/dist/components/OpalProvider.d.ts

@@ -0,0 +1,34 @@
+import { ReactNode } from 'react';
+import { OpalConfig, OpalOpenOptions, OpalError, OpalErrorData } from '../types';
+interface OpalContextType {
+    isOpen: boolean;
+    isReady: boolean;
+    error: OpalError | OpalErrorData | null;
+    open: (options: OpalOpenOptions) => void;
+    close: () => void;
+    updateConfig: (config: OpalConfig) => void;
+}
+interface OpalProviderProps {
+    children: ReactNode;
+}
+/**
+ * Provider component that wraps your app to enable Opal functionality.
+ * This component manages the Opal iframe state and provides context to child components.
+ *
+ * @example
+ * ```tsx
+ * import { OpalProvider } from '@methodfi/opal-react';
+ *
+ * export default function App() {
+ *   return (
+ *     <OpalProvider>
+ *       <YourAppContent />
+ *     </OpalProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function OpalProvider({ children }: OpalProviderProps): JSX.Element;
+export declare function useOpalContext(): OpalContextType;
+export {};
+//# sourceMappingURL=OpalProvider.d.ts.map

package/dist/components/OpalProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpalProvider.d.ts","sourceRoot":"","sources":["../../src/components/OpalProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAuC,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvE,OAAO,EACL,UAAU,EACV,eAAe,EAEf,SAAS,EACT,aAAa,EACd,MAAM,UAAU,CAAC;AAGlB,UAAU,eAAe;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,SAAS,GAAG,aAAa,GAAG,IAAI,CAAC;IACxC,IAAI,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAC;IACzC,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,YAAY,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;CAC5C;AAID,UAAU,iBAAiB;IACzB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,EAAE,QAAQ,EAAE,EAAE,iBAAiB,GAAG,GAAG,CAAC,OAAO,CAyFzE;AAED,wBAAgB,cAAc,IAAI,eAAe,CAMhD"}

package/dist/constants/index.d.ts

@@ -0,0 +1,4 @@
+import { OpalEnvironment } from '../types';
+export declare const OPAL_URLS: Record<OpalEnvironment, string>;
+export declare const IFRAME_SCRIPT = "\n  (function() {\n    // Listen for events from the Opal JS SDK and forward them to the parent window\n    window.addEventListener('message', function(event) {\n      // Only listen to events from Opal origins\n      const allowedOrigins = [\n        'https://opal.production.methodfi.com',\n        'https://opal.sandbox.methodfi.com', \n        'https://opal.dev.methodfi.com',\n        'http://localhost:3000'\n      ];\n\n      if (!allowedOrigins.includes(event.origin)) return;\n\n      // Forward all events from JS SDK to parent window\n      if (event.data?.type) {\n        window.parent.postMessage(event.data, '*');\n      }\n    });\n  })();\n";
+//# sourceMappingURL=index.d.ts.map

package/dist/constants/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/constants/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAE3C,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAKrD,CAAC;AAEF,eAAO,MAAM,aAAa,spBAoBzB,CAAC"}

package/dist/hooks/useOpal.d.ts

@@ -0,0 +1,37 @@
+import { OpalConfig, UseOpalReturn } from '../types';
+/**
+ * Hook for interacting with Opal within an OpalProvider context.
+ * This hook allows you to configure event handlers and open/close Opal sessions.
+ * Supports multiple modes (card_connect, connect, etc.) with flexible event handling.
+ *
+ * @example
+ * ```tsx
+ * const { open, close, isReady, isOpen, error } = useOpal({
+ *   env: 'dev',
+ *   onOpen: () => console.log('Opal opened'),
+ *   onExit: () => console.log('Opal closed'),
+ *   onEvent: (event) => {
+ *     switch (event.type) {
+ *       case 'opal.session.started':
+ *         console.log('Session started');
+ *         break;
+ *       case 'card_connect.card.verified':
+ *         console.log('Card verified:', event.data);
+ *         break;
+ *     }
+ *   },
+ *   onError: (error) => console.error('Opal error:', error),
+ * });
+ *
+ * // Open Opal with a token
+ * const handleOpenOpal = async () => {
+ *   const token = await getOpalToken(); // Your token fetching logic
+ *   open({ token });
+ * };
+ * ```
+ *
+ * @param config Configuration object with event handlers and environment settings
+ * @returns Object with open function and current state
+ */
+export declare function useOpal(config?: OpalConfig): UseOpalReturn;
+//# sourceMappingURL=useOpal.d.ts.map

package/dist/hooks/useOpal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOpal.d.ts","sourceRoot":"","sources":["../../src/hooks/useOpal.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,OAAO,CAAC,MAAM,GAAE,UAAe,GAAG,aAAa,CAe9D"}

package/dist/index.d.ts

@@ -0,0 +1,210 @@
+import { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type OpalEnvironment = 'local' | 'dev' | 'sandbox' | 'production';
+type OpalMode = 'opal' | 'card_connect' | 'account_verification' | string;
+type OpalEventObject = 'session' | 'card' | 'account' | 'bank' | string;
+type OpalEventAction = 'started' | 'errored' | 'exited' | 'verified' | 'completed' | string;
+type OpalEventType = 'opal.session.started' | 'opal.session.errored' | 'opal.session.exited' | 'card_connect.session.started' | 'card_connect.session.errored' | 'card_connect.card.verified' | 'account_verification.session.started' | 'account_verification.session.errored' | 'account_verification.account.verified' | string;
+/**
+ * Structured event object matching Method's Opal event format
+ * Events follow the pattern: <mode>.<object>.<action>
+ */
+interface OpalEvent {
+    /** The type of event, formatted as <mode>.<object>.<action> */
+    type: OpalEventType;
+    /** The operational mode associated with the event (e.g., 'card_connect') */
+    mode: OpalMode;
+    /** The object the event is related to (e.g., 'card', 'session') */
+    object: OpalEventObject;
+    /** The action that occurred (e.g., 'started', 'verified', 'errored') */
+    action: OpalEventAction;
+    /** The ISO 8601 timestamp of when the event occurred */
+    timestamp: string;
+    /** Additional context or details related to the event (varies by event type) */
+    data?: OpalEventData | null;
+}
+/**
+ * Error data structure for Opal session errors
+ */
+interface OpalErrorData {
+    /** Error type identifier */
+    type: string;
+    /** Error sub-type for more specific categorization */
+    sub_type?: string;
+    /** Human-readable error message */
+    message: string;
+}
+/**
+ * Card verification event data
+ */
+interface CardVerifiedEventData {
+    /** The account ID of the verified card */
+    account: string;
+    /** Additional metadata about the card verification */
+    metadata?: Record<string, any>;
+}
+/**
+ * Account verification event data
+ */
+interface AccountVerifiedEventData {
+    /** The account ID of the verified account */
+    account: string;
+    /** Account verification details */
+    account_verification?: {
+        account_id: string;
+        type: string;
+        [key: string]: any;
+    };
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * Union type for all possible event data structures
+ */
+type OpalEventData = OpalErrorData | CardVerifiedEventData | AccountVerifiedEventData | Record<string, any>;
+/**
+ * Legacy error interface for backward compatibility
+ */
+interface OpalError {
+    code: string;
+    message: string;
+    type: 'api_error' | 'connection_error' | 'validation_error';
+}
+/**
+ * Configuration object for the useOpal hook
+ */
+interface OpalConfig {
+    /** Environment to connect to (default: 'production') */
+    env?: OpalEnvironment;
+    /** Called when Opal opens */
+    onOpen?: () => void;
+    /** Called when Opal closes */
+    onExit?: (data?: any) => void;
+    /** Called for all Opal events with properly typed event object */
+    onEvent?: (event: OpalEvent) => void;
+    /** Called when an error occurs */
+    onError?: (error: OpalErrorData) => void;
+    /** Called on successful completion */
+    onSuccess?: (data: OpalSuccessData) => void;
+}
+/**
+ * Success data structure for completed Opal sessions
+ */
+interface OpalSuccessData {
+    /** The session ID of the completed session */
+    sessionId: string;
+    /** Additional metadata from the session */
+    metadata?: Record<string, any>;
+}
+/**
+ * Options for opening an Opal session
+ */
+interface OpalOpenOptions {
+    /** The Opal token (otkn_*) obtained from POST /opal/token */
+    token: string;
+}
+/**
+ * Legacy message interface - use OpalEvent instead
+ * @deprecated Use OpalEvent for better type safety
+ */
+interface OpalMessage {
+    type: string;
+    mode: string;
+    object: string;
+    action: string;
+    timestamp: string;
+}
+/**
+ * Return type for the useOpal hook
+ */
+interface UseOpalReturn {
+    /** Opens Opal with the provided token and options */
+    open: (options: OpalOpenOptions) => void;
+    /** Closes the current Opal session */
+    close: () => void;
+    /** Whether Opal is loaded and ready for interaction */
+    isReady: boolean;
+    /** Whether Opal is currently open */
+    isOpen: boolean;
+    /** Current error state, if any */
+    error: OpalError | OpalErrorData | null;
+}
+/**
+ * Props for the OpalIframe component
+ */
+interface OpalIframeProps {
+    /** The Opal token */
+    token: string;
+    /** The full Opal URL with token */
+    opalUrl: string;
+    /** Callback for handling iframe messages */
+    onMessage: (message: OpalEvent) => void;
+    /** Callback for when the iframe should be closed */
+    onClose: () => void;
+    /** Optional styles for the iframe container */
+    style?: React.CSSProperties;
+}
+
+interface OpalProviderProps {
+    children: ReactNode;
+}
+/**
+ * Provider component that wraps your app to enable Opal functionality.
+ * This component manages the Opal iframe state and provides context to child components.
+ *
+ * @example
+ * ```tsx
+ * import { OpalProvider } from '@methodfi/opal-react';
+ *
+ * export default function App() {
+ *   return (
+ *     <OpalProvider>
+ *       <YourAppContent />
+ *     </OpalProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function OpalProvider({ children }: OpalProviderProps): JSX.Element;
+
+/**
+ * Hook for interacting with Opal within an OpalProvider context.
+ * This hook allows you to configure event handlers and open/close Opal sessions.
+ * Supports multiple modes (card_connect, connect, etc.) with flexible event handling.
+ *
+ * @example
+ * ```tsx
+ * const { open, close, isReady, isOpen, error } = useOpal({
+ *   env: 'dev',
+ *   onOpen: () => console.log('Opal opened'),
+ *   onExit: () => console.log('Opal closed'),
+ *   onEvent: (event) => {
+ *     switch (event.type) {
+ *       case 'opal.session.started':
+ *         console.log('Session started');
+ *         break;
+ *       case 'card_connect.card.verified':
+ *         console.log('Card verified:', event.data);
+ *         break;
+ *     }
+ *   },
+ *   onError: (error) => console.error('Opal error:', error),
+ * });
+ *
+ * // Open Opal with a token
+ * const handleOpenOpal = async () => {
+ *   const token = await getOpalToken(); // Your token fetching logic
+ *   open({ token });
+ * };
+ * ```
+ *
+ * @param config Configuration object with event handlers and environment settings
+ * @returns Object with open function and current state
+ */
+declare function useOpal(config?: OpalConfig): UseOpalReturn;
+
+declare function OpalIframe({ token, opalUrl, onMessage, style, }: OpalIframeProps): react_jsx_runtime.JSX.Element | null;
+
+export { OpalIframe, OpalProvider, useOpal };
+export type { AccountVerifiedEventData, CardVerifiedEventData, OpalConfig, OpalEnvironment, OpalError, OpalErrorData, OpalEvent, OpalEventAction, OpalEventData, OpalEventObject, OpalEventType, OpalIframeProps, OpalMessage, OpalMode, OpalOpenOptions, OpalSuccessData, UseOpalReturn };

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,cAAc,SAAS,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC"}