@capitalos/react 1.1.0-rc.1 → 1.2.1-rc.1

package/README.md

@@ -50,3 +50,7 @@ function MyComponent() {
 ## TypeScript support
 
 TypeScript definitions for `@capitalos/react` are built into the npm package and should be automatically picked up by your editor.
+
+## Error Handling
+
+For details on how errors are managed within the SDK and how to handle them as a consumer or a maintainer, please see our [Error Handling Guidelines](./ERROR_HANDLING.md).

package/dist/_tsup-dts-rollup.d.mts

@@ -1,3 +1,4 @@
+import { Connection } from 'penpal';
 import { IFrameComponent } from 'iframe-resizer';
 import { IFrameMessageData } from 'iframe-resizer';
 import { IFrameOptions } from 'iframe-resizer';
@@ -5,6 +6,7 @@ import { IFrameResizedData } from 'iframe-resizer';
 import { IFrameScrollData } from 'iframe-resizer';
 import { default as React_2 } from 'react';
 import { ReactNode } from 'react';
+import { RefObject } from 'react';
 import { z } from 'zod';
 import * as z_2 from 'zod';
 
@@ -30,6 +32,34 @@ export declare type AccountStatus = z_2.infer<typeof accountStatusSchema>;
 
 declare const accountStatusSchema: z_2.ZodEnum<["eligible", "ineligible", "engaged", "onboarding", "approved", "processing", "pending", "declined", "closed", "waiting"]>;
 
+export declare type ActionResult<T = void> = {
+    success: true;
+    canceled: false;
+    data: T;
+} | {
+    success: false;
+    canceled: true;
+} | {
+    success: false;
+    canceled: false;
+    error: CapitalOSError;
+};
+
+export declare const ActionsIframeContext: React_2.Context<ActionsIframeContextValue | null>;
+
+declare interface ActionsIframeContextValue {
+    childFunctions: ChildFunctions | null;
+    actions: {
+        freezeCard: (cardId: string) => Promise<ActionResult<Card>>;
+        unfreezeCard: (cardId: string) => Promise<ActionResult<Card>>;
+    } | null;
+    isLoading: boolean;
+}
+
+export declare function ActionsIframeProvider({ children }: {
+    children: React_2.ReactNode;
+}): JSX.Element;
+
 declare type AllowedExitPoints = {
     welcome: 'application' | 'activation';
     application: 'application' | 'activation';
@@ -71,6 +101,10 @@ declare type CapitalOsAuthenticationContextType = {
      * The authentication flow will automatically refresh the token after invalidation.
      */
     invalidateToken: () => void;
+    /**
+     * Optional flag indicating whether to log events to the console.
+     */
+    enableLogging: boolean;
 };
 
 declare const CapitalOsAuthenticationProvider: React_2.FC<ProviderProps>;
@@ -90,7 +124,7 @@ export declare class CapitalOSError extends Error {
 
 declare type CapitalOsProps<T extends CapitalOsRenderingContext> = CommonProps & {
     renderingContext: T;
-    methods?: Partial<IframeConnectionMethods>;
+    methods?: Partial<ParentFunctions>;
     sizeWidth?: boolean;
 };
 
@@ -99,6 +133,10 @@ export declare type CapitalOsRenderingContext = {
     referer?: string;
 };
 
+export declare type Card = {
+    status: 'active' | 'inactive' | 'canceled' | 'frozen';
+};
+
 export declare type CardApiDto = z_2.infer<typeof cardApiDtoSchema>;
 
 declare const cardApiDtoSchema: z_2.ZodObject<{
@@ -187,7 +225,7 @@ declare const cardApiDtoSchema: z_2.ZodObject<{
             limit?: number | undefined;
         };
     }>;
-    allowedSpendCategories: z_2.ZodArray<z_2.ZodEnum<["airlines", "carRental", "carService", "education", "electronics", "gasPump", "gasStation", "generalMerchandise", "government", "hardwareAndConstruction", "insurance", "legal", "lodging", "medical", "other", "parking", "phoneAndInternet", "professionalServices", "recreationAndEntertainment", "restaurants", "shipping", "software", "taxisAndRideshare", "transportation", "travelMisc", "utilities"]>, "many">;
+    allowedSpendCategories: z_2.ZodArray<z_2.ZodEnum<["advertisingAndMarketing", "airlines", "carRental", "carService", "education", "electronics", "gasPump", "gasStation", "generalMerchandise", "government", "hardwareAndConstruction", "insurance", "legal", "lodging", "medical", "other", "parking", "phoneAndInternet", "professionalServices", "recreationAndEntertainment", "restaurants", "shipping", "software", "taxisAndRideshare", "transportation", "travelMisc", "utilities"]>, "many">;
     allowedMerchants: z_2.ZodArray<z_2.ZodObject<{
         id: z_2.ZodUnion<[z_2.ZodString, z_2.ZodString]>;
         name: z_2.ZodString;
@@ -206,7 +244,7 @@ declare const cardApiDtoSchema: z_2.ZodObject<{
         shipment: z_2.ZodObject<{
             address: z_2.ZodObject<{
                 addressLine1: z_2.ZodString;
-                addressLine2: z_2.ZodOptional<z_2.ZodNullable<z_2.ZodString>>;
+                addressLine2: z_2.ZodOptional<z_2.ZodNullable<z_2.ZodEffects<z_2.ZodNullable<z_2.ZodString>, string | null, string | null>>>;
                 city: z_2.ZodString;
                 state: z_2.ZodEffects<z_2.ZodString, string, string>;
                 zipcode: z_2.ZodString;
@@ -330,7 +368,7 @@ declare const cardApiDtoSchema: z_2.ZodObject<{
             limit?: number | undefined;
         };
     };
-    allowedSpendCategories: ("airlines" | "carRental" | "carService" | "education" | "electronics" | "gasPump" | "gasStation" | "generalMerchandise" | "government" | "hardwareAndConstruction" | "insurance" | "legal" | "lodging" | "medical" | "other" | "parking" | "phoneAndInternet" | "professionalServices" | "recreationAndEntertainment" | "restaurants" | "shipping" | "software" | "taxisAndRideshare" | "transportation" | "travelMisc" | "utilities")[];
+    allowedSpendCategories: ("advertisingAndMarketing" | "airlines" | "carRental" | "carService" | "education" | "electronics" | "gasPump" | "gasStation" | "generalMerchandise" | "government" | "hardwareAndConstruction" | "insurance" | "legal" | "lodging" | "medical" | "other" | "parking" | "phoneAndInternet" | "professionalServices" | "recreationAndEntertainment" | "restaurants" | "shipping" | "software" | "taxisAndRideshare" | "transportation" | "travelMisc" | "utilities")[];
     allowedMerchants: {
         id: string;
         name: string;
@@ -385,7 +423,7 @@ declare const cardApiDtoSchema: z_2.ZodObject<{
             limit?: number | undefined;
         };
     };
-    allowedSpendCategories: ("airlines" | "carRental" | "carService" | "education" | "electronics" | "gasPump" | "gasStation" | "generalMerchandise" | "government" | "hardwareAndConstruction" | "insurance" | "legal" | "lodging" | "medical" | "other" | "parking" | "phoneAndInternet" | "professionalServices" | "recreationAndEntertainment" | "restaurants" | "shipping" | "software" | "taxisAndRideshare" | "transportation" | "travelMisc" | "utilities")[];
+    allowedSpendCategories: ("advertisingAndMarketing" | "airlines" | "carRental" | "carService" | "education" | "electronics" | "gasPump" | "gasStation" | "generalMerchandise" | "government" | "hardwareAndConstruction" | "insurance" | "legal" | "lodging" | "medical" | "other" | "parking" | "phoneAndInternet" | "professionalServices" | "recreationAndEntertainment" | "restaurants" | "shipping" | "software" | "taxisAndRideshare" | "transportation" | "travelMisc" | "utilities")[];
     allowedMerchants: {
         id: string;
         name: string;
@@ -435,6 +473,24 @@ export declare type CardDetailsProps = CommonProps & {
  */
 export declare function CardsApp(props: CommonProps): JSX.Element;
 
+export declare type ChildFunctions = {
+    freezeCard: (cardId: string) => Promise<ClientActionResult<Card>>;
+    unfreezeCard: (cardId: string) => Promise<ClientActionResult<Card>>;
+};
+
+export declare type ClientActionResult<T> = {
+    success: true;
+    canceled: false;
+    data: T;
+} | {
+    success: false;
+    canceled: true;
+} | {
+    success: false;
+    canceled: false;
+    error: string;
+};
+
 export declare type CommonProps = {
     /**
      * The token provided by initiate-login.
@@ -462,6 +518,13 @@ export declare type CommonProps = {
     theme?: ThemeColorScheme;
 };
 
+export declare function ContactSupport({ onDone, onCancel, ...restOfProps }: ContactSupportProps): JSX.Element;
+
+export declare type ContactSupportProps = CommonProps & {
+    onDone: () => void;
+    onCancel: () => void;
+};
+
 export declare function decodeOneTimeToken(token: string): any;
 
 /**
@@ -517,40 +580,6 @@ export declare const ErrorCode: {
 
 export declare type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 
-export declare type IframeConnectionMethods = {
-    onLoad: () => void;
-    onError: (error: RawErrorDetails) => void;
-    /**
-     * Called when the iframe detects that the JWT token has expired.
-     * This triggers the token refresh flow, which will obtain a new token
-     * and reload the iframe with the fresh token.
-     */
-    onTokenExpired?: () => void;
-    createCard?: {
-        onDone?: () => void;
-        onCancel?: () => void;
-    };
-    createDispute?: {
-        onDone?: () => void;
-        onCancel?: () => void;
-    };
-    onboarding?: {
-        onDone?: (account: Account) => void;
-    };
-    tokenExchange?: {
-        onLongLivedToken?: (jwtToken: string) => void;
-    };
-    makePayment?: {
-        onDone?: () => void;
-    };
-    devTools?: {
-        onClose?: () => void;
-    };
-    cardDetails?: {
-        onCardCanceled?: () => void;
-    };
-};
-
 export declare const IframeResizer: React_2.ForwardRefExoticComponent<Omit<IFrameOptions, "closedCallback" | "scrollCallback" | "resizedCallback" | "messageCallback" | "initCallback"> & {
     onClosed?(iframeId: string): void;
     onInit?(iframe: IFrameComponent): void;
@@ -648,6 +677,22 @@ export declare type IssueCardProps = CommonProps & {
     onCancel: () => void;
 };
 
+export declare function LegalDocuments({ onDone, ...restOfProps }: LegalDocumentsProps): JSX.Element;
+
+export declare type LegalDocumentsProps = CommonProps & {
+    onDone: () => void;
+};
+
+export declare const logger: {
+    log: (message: string, options?: LoggerOptions) => void;
+    warn: (message: string, options?: LoggerOptions) => void;
+    error: (message: string, options?: LoggerOptions) => void;
+};
+
+declare type LoggerOptions = {
+    enableLogging: boolean | undefined;
+};
+
 /**
  * Renders the CapitalOS Make a Payment experience.
  */
@@ -660,6 +705,81 @@ export declare type MakePaymentProps = CommonProps & {
     onDone: () => void;
 };
 
+export declare function Mfa({ onDone, onCancel, mfaId, destination, codeLength, canResendAfter, operationName, ...restOfProps }: MfaProps): JSX.Element;
+
+export declare type MfaActionResult = ActionResult<void>;
+
+export declare type MfaProps = CommonProps & {
+    /**
+     * The ID of the MFA request.
+     */
+    mfaId: string;
+    /**
+     * The destination of the MFA request.
+     */
+    destination: string;
+    /**
+     * The length of the code to be entered.
+     */
+    codeLength: number;
+    /**
+     * ISO string representation of DateTime in UTC
+     */
+    canResendAfter: string;
+    /**
+     * The name of the operation that is being performed.
+     */
+    operationName?: string;
+    /**
+     * Callback to invoke when the MFA was successfully completed.
+     */
+    onDone: () => void;
+    /**
+     * Callback to invoke when the MFA was cancelled by the user.
+     */
+    onCancel: () => void;
+};
+
+export declare interface MfaRequestContext {
+    mfaId: string;
+    destination: string;
+    codeLength: number;
+    canResendAfter: string;
+    operationName?: string;
+}
+
+export declare interface MfaResult {
+    success: boolean;
+    canceled?: boolean;
+    error?: string;
+}
+
+declare interface MfaState {
+    context: MfaRequestContext;
+    resolve: (result: MfaActionResult) => void;
+    reject: (error: Error) => void;
+}
+
+/**
+ * Generic modal component that displays content with backdrop/blur
+ */
+export declare function Modal({ onClose, children, ariaLabel }: ModalProps): JSX.Element;
+
+export declare interface ModalProps {
+    /**
+     * Callback when modal should be closed (backdrop click)
+     */
+    onClose: () => void;
+    /**
+     * Content to render inside the modal
+     */
+    children: ReactNode;
+    /**
+     * Accessible label for screen readers
+     */
+    ariaLabel?: string;
+}
+
 export declare function Onboarding<T extends OnboardingEntryPoint>({ onDone, entryPoint: onboardingEntryPoint, exitPoint: onboardingExitPoint, ...restOfProps }: OnboardingProps<T>): JSX.Element;
 
 declare type OnboardingEntryPoint = keyof AllowedExitPoints;
@@ -670,6 +790,65 @@ declare type OnboardingProps<T extends keyof AllowedExitPoints> = CommonProps &
     onDone: (account: Account) => void;
 };
 
+export declare type ParentFunctions = {
+    onLoad: () => void;
+    onError: (error: RawErrorDetails) => void;
+    /**
+     * Called when the iframe detects that the JWT token has expired.
+     * This triggers the token refresh flow, which will obtain a new token
+     * and reload the iframe with the fresh token.
+     */
+    onTokenExpired?: () => void;
+    cardDetails?: {
+        onCardCanceled?: () => void;
+    };
+    contactSupport?: {
+        onDone?: () => void;
+        onCancel?: () => void;
+    };
+    createCard?: {
+        onDone?: () => void;
+        onCancel?: () => void;
+    };
+    createDispute?: {
+        onDone?: () => void;
+        onCancel?: () => void;
+    };
+    devTools?: {
+        onClose?: () => void;
+    };
+    legalDocuments?: {
+        onDone?: () => void;
+    };
+    makePayment?: {
+        onDone?: () => void;
+    };
+    mfa?: {
+        onDone?: () => void;
+        onCancel?: () => void;
+    };
+    onboarding?: {
+        onDone?: (account: Account) => void;
+    };
+    replaceCard?: {
+        onDone?: () => void;
+        onClose?: () => void;
+    };
+    'system-messages'?: {
+        requestMfa?: (context: MfaRequestContext) => Promise<MfaResult>;
+    };
+    statements?: {
+        onDone?: () => void;
+    };
+    terminateCard?: {
+        onDone?: () => void;
+        onClose?: () => void;
+    };
+    tokenExchange?: {
+        onLongLivedToken?: (jwtToken: string) => void;
+    };
+};
+
 declare type ProviderProps = {
     getToken: () => Promise<string>;
     enableLogging?: boolean | undefined;
@@ -828,6 +1007,69 @@ declare const renderingContextSchema: z.ZodIntersection<z.ZodDiscriminatedUnion<
     entryPoint: "devTools";
 }, {
     entryPoint: "devTools";
+}>, z.ZodObject<{
+    entryPoint: z.ZodLiteral<"contactSupport">;
+}, "strip", z.ZodTypeAny, {
+    entryPoint: "contactSupport";
+}, {
+    entryPoint: "contactSupport";
+}>, z.ZodObject<{
+    entryPoint: z.ZodLiteral<"statements">;
+}, "strip", z.ZodTypeAny, {
+    entryPoint: "statements";
+}, {
+    entryPoint: "statements";
+}>, z.ZodObject<{
+    entryPoint: z.ZodLiteral<"legalDocuments">;
+}, "strip", z.ZodTypeAny, {
+    entryPoint: "legalDocuments";
+}, {
+    entryPoint: "legalDocuments";
+}>, z.ZodObject<{
+    entryPoint: z.ZodLiteral<"replaceCard">;
+    cardId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    cardId: string;
+    entryPoint: "replaceCard";
+}, {
+    cardId: string;
+    entryPoint: "replaceCard";
+}>, z.ZodObject<{
+    entryPoint: z.ZodLiteral<"terminateCard">;
+    cardId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    cardId: string;
+    entryPoint: "terminateCard";
+}, {
+    cardId: string;
+    entryPoint: "terminateCard";
+}>, z.ZodObject<{
+    entryPoint: z.ZodLiteral<"actions">;
+}, "strip", z.ZodTypeAny, {
+    entryPoint: "actions";
+}, {
+    entryPoint: "actions";
+}>, z.ZodObject<{
+    entryPoint: z.ZodLiteral<"mfa">;
+    mfaId: z.ZodString;
+    destination: z.ZodString;
+    codeLength: z.ZodNumber;
+    canResendAfter: z.ZodString;
+    operationName: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    entryPoint: "mfa";
+    mfaId: string;
+    destination: string;
+    codeLength: number;
+    canResendAfter: string;
+    operationName?: string | undefined;
+}, {
+    entryPoint: "mfa";
+    mfaId: string;
+    destination: string;
+    codeLength: number;
+    canResendAfter: string;
+    operationName?: string | undefined;
 }>]>, z.ZodObject<{
     referer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
@@ -836,11 +1078,33 @@ declare const renderingContextSchema: z.ZodIntersection<z.ZodDiscriminatedUnion<
     referer?: string | null | undefined;
 }>>;
 
+export declare function ReplaceCard({ cardId, onDone, onClose, ...restOfProps }: ReplaceCardProps): JSX.Element;
+
+export declare type ReplaceCardProps = CommonProps & {
+    cardId: string;
+    onDone: () => void;
+    onClose: () => void;
+};
+
 /**
  * Safely decodes a URL component, handling potential errors
  */
 export declare function safeDecodeURIComponent(str: string): string;
 
+export declare function Statements({ onDone, ...restOfProps }: StatementsProps): JSX.Element;
+
+export declare type StatementsProps = CommonProps & {
+    onDone: () => void;
+};
+
+export declare function TerminateCard({ cardId, onDone, onClose, ...restOfProps }: TerminateCardProps): JSX.Element;
+
+export declare type TerminateCardProps = CommonProps & {
+    cardId: string;
+    onDone: () => void;
+    onClose: () => void;
+};
+
 export declare type ThemeColorScheme = 'light' | 'dark' | 'system';
 
 export declare type TokenData = {
@@ -892,8 +1156,61 @@ export declare enum TokenType {
     longLived = "longLived"
 }
 
+/**
+ * Hook to access the actions iframe functions.
+ *
+ * @returns An object containing the actions functions and loading state
+ * @throws {CapitalOSError} If the hook is used outside of a CapitalOS component
+ *
+ * @example
+ * ```tsx
+ * const { actions, isLoading } = useActions()
+ *
+ * if (isLoading) {
+ *   return <LoadingSpinner />
+ * }
+ *
+ * // Use the actions
+ * await actions.freezeCard()
+ * ```
+ */
+export declare function useActions(): {
+    actions: ChildFunctions | null;
+    isLoading: boolean;
+};
+
 export declare const useCapitalOsAuthContext: () => CapitalOsAuthenticationContextType;
 
+/**
+ * Hook to resolve logging preference, with direct prop taking precedence over context.
+ * @param enableLoggingProp Direct prop for enableLogging.
+ * @returns Effective logging flag.
+ */
+export declare function useEnableLogging(enableLoggingProp?: boolean): boolean;
+
+/**
+ * A React hook that manages the iframe connection lifecycle, including:
+ * - Establishing and maintaining the iframe connection
+ * - Handling token expiration and refresh flows
+ * - Managing loading states
+ * - Coordinating between one-time tokens and context-based authentication
+ * - Providing error handling and logging capabilities
+ */
+export declare function useIframe(props: {
+    renderingContext: CapitalOsRenderingContext;
+    oneTimeToken?: string | undefined;
+    enableLogging?: boolean | undefined;
+    onError?: ((error: Error) => void) | undefined;
+    theme?: ThemeColorScheme | undefined;
+    methods?: Partial<Omit<ParentFunctions, 'onLoad' | 'onError' | 'onTokenExpired'>> | undefined;
+}): {
+    isLoaded: boolean;
+    url: string | undefined;
+    tokenData: TokenData | undefined;
+    iframeRef: RefObject<HTMLIFrameElement>;
+    connection: Connection<ChildFunctions> | null;
+};
+
 /**
  * connects to child iframe and returns whether the iframe is loaded or not.
  * token was added to the list of dependencies to make sure that the connection is re-established when the token changes.
@@ -902,9 +1219,12 @@ export declare function useIframeConnection({ iframeRef, token, onError, methods
     iframeRef: React.RefObject<HTMLIFrameElement>;
     token: string | undefined;
     onError: ((error: Error) => void) | undefined | null;
-    methods: IframeConnectionMethods;
-}): void;
+    methods: ParentFunctions;
+}): Connection<ChildFunctions> | null;
 
+/**
+ * returns a memoized url of the iframe or undefined if the token is not available yet.
+ */
 export declare function useIframeUrl({ tokenData, renderingContext, theme, onError, }: {
     tokenData: TokenData | undefined;
     renderingContext: CapitalOsRenderingContext;
@@ -912,4 +1232,24 @@ export declare function useIframeUrl({ tokenData, renderingContext, theme, onErr
     onError?: ((error: Error) => void) | undefined;
 }): string | undefined;
 
+/**
+ * Hook that provides stable logging functions (log, warn, error), scoped to the resolved enableLogging flag.
+ * @param enableLoggingProp Optional direct prop to override logging.
+ */
+export declare function useLogger(enableLoggingProp?: boolean): {
+    log: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+};
+
+export declare function useMfaState(): {
+    activeMfaRequest: MfaState | null;
+    isMfaActive: boolean;
+    mfaContext: MfaRequestContext | null;
+    requestMfa: (context: MfaRequestContext) => Promise<MfaActionResult>;
+    handleMfaDone: () => void;
+    handleMfaCancel: () => void;
+    handleMfaError: (error: CapitalOSError) => void;
+};
+
 export { }