@duffel/components 3.4.3 → 3.5.0--canary-2

package/components/DuffelCardForm/lib/getIFrameEventListener.d.ts

@@ -2,6 +2,6 @@ import { DuffelCardFormProps } from "./types";
 type Inputs = {
     setIFrameHeight: (height: string) => void;
     postMessageWithStyles: () => void;
-} & Pick<DuffelCardFormProps, "onValidateSuccess" | "onValidateFailure" | "onCreateCardForTemporaryUseSuccess" | "onCreateCardForTemporaryUseFailure">;
-export declare function getIFrameEventListener(baseUrl: string, { postMessageWithStyles, setIFrameHeight, onValidateSuccess, onValidateFailure, onCreateCardForTemporaryUseSuccess, onCreateCardForTemporaryUseFailure, }: Inputs): (event: MessageEvent) => void;
+} & Pick<DuffelCardFormProps, "onValidateSuccess" | "onValidateFailure" | "onCreateCardForTemporaryUseSuccess" | "onCreateCardForTemporaryUseFailure" | "onSaveCardSuccess" | "onSaveCardFailure">;
+export declare function getIFrameEventListener(iFrameURL: URL, { postMessageWithStyles, setIFrameHeight, onValidateSuccess, onValidateFailure, onCreateCardForTemporaryUseSuccess, onCreateCardForTemporaryUseFailure, onSaveCardSuccess, onSaveCardFailure, }: Inputs): (event: MessageEvent) => void;
 export {};

package/components/DuffelCardForm/lib/getIFrameOriginForEnvironment.d.ts

@@ -0,0 +1,2 @@
+import { DuffelCardFormProps } from "./types";
+export declare function getIFrameOriginForEnvironment(tokenProxyEnvironment: DuffelCardFormProps["tokenProxyEnvironment"]): string;

package/components/DuffelCardForm/lib/getIframeURL.d.ts

@@ -0,0 +1,2 @@
+import { DuffelCardFormProps } from "./types";
+export declare function getIframeURL(tokenProxyEnvironment: DuffelCardFormProps["tokenProxyEnvironment"], intent: DuffelCardFormProps["intent"], clientKey: DuffelCardFormProps["clientKey"], cardId: DuffelCardFormProps["cardId"]): URL;

package/components/DuffelCardForm/lib/getPathnameForIntent.d.ts

@@ -0,0 +1,2 @@
+import { DuffelCardFormIntent } from "./types";
+export declare function getPathnameForIntent(intent: DuffelCardFormIntent): string;

package/components/DuffelCardForm/lib/postMessageToCreateCardForTemporaryUse.d.ts

@@ -0,0 +1 @@
+export declare function postMessageToCreateCardForTemporaryUse(iFrameReference: React.RefObject<HTMLIFrameElement>, baseUrl: URL): void;

package/components/DuffelCardForm/lib/postMessageToSaveCard.d.ts

@@ -0,0 +1 @@
+export declare function postMessageToSaveCard(iFrameReference: React.RefObject<HTMLIFrameElement>, baseUrl: URL): void;

package/components/DuffelCardForm/lib/postMessageWithStyles.d.ts

@@ -0,0 +1,2 @@
+import { DuffelCardFormStyles } from "./types";
+export declare function postMessageWithStyles(iFrameReference: React.RefObject<HTMLIFrameElement>, baseUrl: URL, styles: DuffelCardFormStyles | undefined): void;

package/components/DuffelCardForm/lib/types.d.ts

@@ -2,9 +2,27 @@ export interface CreateCardForTemporaryUseData {
     id: string;
     live_mode: false;
 }
-export interface CreateCardForTemporaryUseError {
+export type CreateCardForTemporaryUseError = {
     status: number;
     message: string;
+};
+export type SaveCardError = {
+    status: number;
+    message: string;
+};
+export interface SaveCardData {
+    id: string;
+    live_mode: boolean;
+    last_4_digits: string;
+    bin: string;
+    expiry_month: number;
+    expiry_year: number;
+    brand: string;
+    cardholder_name: string;
+    /**
+     * The card will no longer be available for use after this time.
+     */
+    unavailable_at: string;
 }
 /**
  * An object where each key value pair is a style to be applied.
@@ -28,10 +46,11 @@ export interface DuffelCardFormStyles {
     sectionTitle?: StylesMap;
     layoutGrid?: StylesMap;
 }
-export type DuffelCardFormActions = "validate" | "create-card-for-temporary-use";
+export type DuffelCardFormActions = "validate" | "save-card" | "create-card-for-temporary-use";
+export type DuffelCardFormIntent = "to-create-card-for-temporary-use" | "to-use-saved-card" | "to-save-card";
 export interface DuffelCardFormProps {
     /**
-     * The client key present in the Quote object.
+     * The client key retrieved from the Duffel API.
      */
     clientKey: string;
     /**
@@ -44,38 +63,77 @@ export interface DuffelCardFormProps {
      * @default: `production`
      */
     tokenProxyEnvironment?: "development" | "staging" | "production";
+    /**
+     * The card intent defines what the form is meant to look like.
+     * It can be one of:
+     *
+     * - `to-create-card-for-temporary-use`: The full form will be shown. You may also use this intent for the use case of using and saving the card.
+     * - `to-use-saved-card`: When using this intent also provide the saved card ID. Only a cvv field will be rendered.
+     * - `to-save-card`: The form will be shown without the cvv field. This only allows you to save a card for future use,
+     *    but not create an id for immediate, temporary use. For the use case of saving during checkout or save + use, use the `to-create-card-for-temporary-use` intent.
+     */
+    intent: DuffelCardFormIntent;
     /**
      * The actions you'd like the component to perform.
      *
      * This prop is a dependecy of a useEffect hook in the component
      * and so when it's changed it will perform the action you specify.
      *
-     * The action `create-card-for-temporary-use` will only happen once `validate` has been successful.
+     * The `create-card-for-temporary-use` and `save-card` actions will only happen once `validate` has been successful.
+     *
+     * We recommend using the `useDuffelCardFormActions` hook for a simpler, more readable interface to manage the actions array.
      *
      */
     actions: DuffelCardFormActions[];
+    /**
+     * Once a card is saved, in order to use it, travellers need to enter its cvv.
+     * When using the `use-saved-card` intent, you must provide the card ID.
+     */
+    cardId?: string;
     /**
      * This function will be called when the card form validation has been successful.
      */
-    onValidateSuccess: () => void;
+    onValidateSuccess?: () => void;
     /**
      * If the card form validation is successful but data is changed afterwards,
      * making it invalid, this function will be called.
      */
-    onValidateFailure: () => void;
+    onValidateFailure?: () => void;
     /**
      * This function will be called when the card has been created for temporary use.
      *
      * This callback will only be triggered if the `create-card-for-temporary-use`
-     * action is present in the `actions` prop.
+     * action is present in the `actions` prop. Alternatively,
+     * you may use the `triggerCreateCardForTemporaryUse` function from the
+     * `useDuffelCardFormActions` hook.
      */
-    onCreateCardForTemporaryUseSuccess: (data: CreateCardForTemporaryUseData) => void;
+    onCreateCardForTemporaryUseSuccess?: (data: CreateCardForTemporaryUseData) => void;
     /**
      * This function will be called when the component has failed to create the card for temporary use.
      *
      * This callback will only be triggered if the `create-card-for-temporary-use`
-     * action is present in the `actions` prop.
+     * action is present in the `actions` prop. Alternatively,
+     * you may use the `triggerCreateCardForTemporaryUse` function from the
+     * `useDuffelCardFormActions` hook.
+     */
+    onCreateCardForTemporaryUseFailure?: (error: CreateCardForTemporaryUseError) => void;
+    /**
+     * This function will be called when the card has been saved.
+     *
+     * This callback will only be triggered if the `save-card`
+     * action is present in the `actions` prop. Alternatively,
+     * you may use the `triggerSaveCard` function from the
+     * `useDuffelCardFormActions` hook.
+     */
+    onSaveCardSuccess?: (data: SaveCardData) => void;
+    /**
+     * This function will be called when saving the card has failed.
+     *
+     * This callback will only be triggered if the `save-card`
+     * action is present in the `actions` prop. Alternatively,
+     * you may use the `triggerSaveCard` function from the
+     * `useDuffelCardFormActions` hook.
      */
-    onCreateCardForTemporaryUseFailure: (error: CreateCardForTemporaryUseError) => void;
+    onSaveCardFailure?: (error: SaveCardError) => void;
 }
 export {};

package/components/DuffelCardForm/lib/useDuffelCardFormActions.d.ts

@@ -0,0 +1,23 @@
+import { DuffelCardFormProps } from "./types";
+export interface UseDuffelCardFormActionsHook {
+    /**
+     * The actions array that should be passed to the `actions` prop of the `DuffelCardForm` component.
+     * You do not have have to modify this array directly, instead rely on `triggerSaveCard` and `triggerCreateCardForTemporaryUse` to update the array.
+     */
+    actions: DuffelCardFormProps["actions"];
+    /**
+     *  Call this function to tell the component to save the card.
+     */
+    triggerSaveCard: () => void;
+    /**
+     *  Call this function to tell the component to create a card for temporary use.
+     */
+    triggerCreateCardForTemporaryUse: () => void;
+}
+/**
+ * This hook gives you convinient helpers to read and reason through the DuffelCardForm integration.
+ * Add `actions` to the `DuffelCardForm` actions prop and call the functions to trigger the actions you'd like.
+ *
+ * In the background, this hook is setting the state on actions prop and the component's useEffect hook will trigger the action.
+ */
+export declare function useDuffelCardFormActions(): UseDuffelCardFormActionsHook;