From 9f426927b72e689d104c4d4ce9c25176f3fa4f04 Mon Sep 17 00:00:00 2001
From: Kamala <kamala@gigs.com>
Date: Fri, 10 May 2024 17:04:11 +0200
Subject: [PATCH 1/7] Improve handling of declined portings

---
 docs/porting-embed.md                         | 120 +++++++++---------
 example/app/porting/index.tsx                 |  27 ++--
 src/PortingEmbed/CustomOptionsProvider.tsx    |   8 +-
 src/PortingEmbed/PortingEmbed.tsx             |  11 +-
 src/PortingEmbed/PortingFormContainer.tsx     |  54 +++++---
 .../__tests__/PortingFormContainer.test.tsx   |  45 ++++---
 .../DonorProvider/DonorProviderForm.tsx       |   2 +-
 .../features/GenericPortingDeclined.tsx       |  51 --------
 src/core/ConnectSessionProvider.tsx           |   4 +-
 .../GenericPortingDeclined.stories.tsx        |  38 ------
 10 files changed, 159 insertions(+), 201 deletions(-)
 delete mode 100644 src/PortingEmbed/features/GenericPortingDeclined.tsx
 delete mode 100644 storybook/stories/PortingEmbed/features/GenericPortingDeclined.stories.tsx

diff --git a/docs/porting-embed.md b/docs/porting-embed.md
index 61e199b..a5e805d 100644
--- a/docs/porting-embed.md
+++ b/docs/porting-embed.md
@@ -51,12 +51,16 @@ The ID of your Gigs Project.
 Callback triggered when the number porting is completed.
 `porting` - The whole porting object.
 
-### Optional props
-
 #### `onError`
 
-`(error:  Error)  =>  unknown`
-Callback triggered when there is an error initializing the porting form. The error may stem from an invalid session, in which case recovery can be attempted by generating and passing a new Connect session to the embed. Alternatively, the error may derive from a failed attempt to retrieve a subscription, in which case it is advisable to inform the user to try again later or to contact customer support for assistance.
+`(error?:  Error, porting?: Porting, errorCode?: PortingEmbedError)  =>  unknown`
+
+Callback triggered when: 
+* There is an error initializing the porting form. The error may stem from an invalid session, in which case recovery can be attempted by generating and passing a new Connect session to the embed. The `error` is passed as an argument to the callback.
+* There is a failed attempt to retrieve a subscription. In this case it is advisable to inform the user to try again later or to contact customer support for assistance. The `error` is passed as an argument to the callback.
+* The porting has been declined. The `porting` object and the error code `portingDeclined` are passed as arguments to the callback. 
+
+### Optional props
 
 #### `onInitialized`
 
@@ -210,7 +214,6 @@ Returns a React node representing the customized secondary button component.
 ```jsx
   const titles: Record<string, string> = {
     'protectionDisabling.button': 'Request Porting Again',
-    'portingDeclined.button': 'Contact Customer support',
   }
 
 <PortingEmbed
@@ -235,13 +238,13 @@ renderSecondaryButton={(name, onPress) => (
 
 `(variant: 'error' | 'info', message: string) => React.ReactNode`
 Render prop function that can be used to customize the rendering of alert banners in the embed.
-Alert banners are used either to convey information or to display errors. 
+Alert banners are used either to convey information or to display errors.
 The `'info'` type appears in the `holderDetails` and `address` steps as follows:
 
 <img width="400" src="./holderDetailsInfo.png" alt="Account holder info alert banner">
 <img width="400" src="./addressInfo.png" alt="Address info alert banner">
 
-The `'error'` type appears whenever there is an error after submitting a porting step, or if the porting has been declined (see all the declined messages [here](https://github.com/gigs/embeds-react-native/blob/main/src/PortingEmbed/util/portingUtils.tsx#L96)). 
+The `'error'` type appears whenever there is an error after submitting a porting step, or if the porting has been declined (see all the declined messages [here](https://github.com/gigs/embeds-react-native/blob/main/src/PortingEmbed/util/portingUtils.tsx#L96)).
 
 `variant` - The variant of the alert banner (either 'error' or 'info').
 `message` - The message to be displayed in the alert banner.
@@ -249,24 +252,24 @@ Returns a React node representing the customized alert banner component.
 
 ```jsx
 <PortingEmbed
-//...
-renderAlertBanner={(variant, message) => (
-            <View
-              style={[
-                {
-                  backgroundColor: variant === 'error' ? '#FFE4E6' : 'white',
-                },
-              ]}
-            >
-              <Text
-                style={{
-                  color: variant === 'error' ? '#BE123C' : 'black',
-                }}
-              >
-                {message}
-              </Text>
-            </View>
-          )}
+  //...
+  renderAlertBanner={(variant, message) => (
+    <View
+      style={[
+        {
+          backgroundColor: variant === 'error' ? '#FFE4E6' : 'white',
+        },
+      ]}
+    >
+      <Text
+        style={{
+          color: variant === 'error' ? '#BE123C' : 'black',
+        }}
+      >
+        {message}
+      </Text>
+    </View>
+  )}
 />
 ```
 
@@ -314,29 +317,31 @@ If no `renderPortingProtectionDisabledConfirmation` prop is passed to the compon
 
 ```jsx
 <PortingEmbed
-//...
-renderPortingProtectionDisabledConfirmation={(onConfirm) => (
-            <View>
-              <Text>
-                After you have received confirmation that port protection has
-                been deactivated and your number is prepared for porting, kindly
-                inform us by clicking the button below to confirm.
-              </Text>
-              <Button title={'Confirm'} onPress={onConfirm} color={'blue'} />
-            </View>
-          )}
+  //...
+  renderPortingProtectionDisabledConfirmation={(onConfirm) => (
+    <View>
+      <Text>
+        After you have received confirmation that port protection has been
+        deactivated and your number is prepared for porting, kindly inform us by
+        clicking the button below to confirm.
+      </Text>
+      <Button title={'Confirm'} onPress={onConfirm} color={'blue'} />
+    </View>
+  )}
 />
 ```
+
 #### `defaultTextFont`
 
 The default font that the embed uses for all default components, i.e. all components that are not replaced by a corresponding render prop (for example all inputs will use the `defaultTextFont` if no `renderInput` component was passed to the embed).
 
 ```jsx
 <PortingEmbed
-//...
-defaultTextFont='Custom-font'
+  //...
+  defaultTextFont="Custom-font"
 />
 ```
+
 #### `renderProvidersDropdown`
 
 Render prop function that can be used to customize the rendering of a component to select the current carrier.
@@ -372,25 +377,25 @@ renderProvidersDropdown={(name, providers, onChange) => (
 
 #### Porting Embed props
 
-| Prop                 | Type                   | Required | Description/Signature                                                                                  |
-| -------------------- | ---------------------- | -------- | -------------------------------------------------------------------------------------------- |
-| `connectSession`     | Connect Session object | ✅       | A Connect Session object with an intent of type `completePorting`.                           |
-| `project`            | string                 | ✅       | Your project ID.                                                                             |
-| `onCompleted`        | function               | ✅       | `(porting:  Porting)  =>  unknown`                                                           |
-| `onInitialized`      | function               | ❌       | `()  =>  unknown`                                                                            |
-| `onLoaded`           | function               | ❌       | `()  =>  unknown`                                                                            |
-| `onError`            | function               | ❌       | `(error:  Error)  =>  unknown`                                                               |
-| `onSupportRequested` | function               | ❌       | `() => unknown`                                                                              |
-| `onPortingStep`      | function               | ❌       | `(step: PortingStep) => unknown`                                                             |
-| `renderTitle`        | function               | ❌       | `(step: PortingStep) => unknown`                                                             |
-| `renderCheckbox`        | function               | ❌       | `(name: string, onChange: (value: string) => void, inputMode?: InputModeOptions) => unknown` |
-| `renderPrimaryButton`        | function               | ❌       | `(onPress: () => void, name?: string, isSubmitting?: boolean, disabled?: boolean) => React.ReactNode` |
-| `renderSecondaryButton`        | function               | ❌       | `(name: string, onPress: () => void) => React.ReactNode` |
-| `renderAlertBanner`        | function               | ❌       | `(variant: 'error' | 'info', message: string) => React.ReactNode` |
-| `renderDate`        | function               | ❌       | `(name: string, onChange: (value: string) => void) => React.ReactNode` |
-| `renderPortingProtectionDisabledConfirmation`        | function               | ❌       | `(onConfirm: () => void) => React.ReactNode` |
-| `renderProvidersDropdown`        | function               | ❌       | `(name: string, providers: {id: string; name: string;}[], onChange: (value: string) => void) => React.ReactNode` |
-| `defaultTextFont`        | string               | ❌       | Custom font used in all default components. |
+| Prop                                          | Type                   | Required | Description/Signature                                                                                            |
+| --------------------------------------------- | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `connectSession`                              | Connect Session object | ✅       | A Connect Session object with an intent of type `completePorting`.                                               |
+| `project`                                     | string                 | ✅       | Your project ID.                                                                                                 |
+| `onCompleted`                                 | function               | ✅       | `(porting:  Porting)  =>  unknown`                                                                               |
+| `onError`                                     | function               | ✅       | `(error?:  Error, porting?: Porting, errorCode?: PortingEmbedError)  =>  unknown`                                                                                   |
+| `onInitialized`                               | function               | ❌       | `()  =>  unknown`                                                                                                |
+| `onLoaded`                                    | function               | ❌       | `()  =>  unknown`                                                                                                |
+| `onSupportRequested`                          | function               | ❌       | `() => unknown`                                                                                                  |
+| `onPortingStep`                               | function               | ❌       | `(step: PortingStep) => unknown`                                                                                 |
+| `renderTitle`                                 | function               | ❌       | `(step: PortingStep) => unknown`                                                                                 |
+| `renderCheckbox`                              | function               | ❌       | `(name: string, onChange: (value: string) => void, inputMode?: InputModeOptions) => unknown`                     |
+| `renderPrimaryButton`                         | function               | ❌       | `(onPress: () => void, name?: string, isSubmitting?: boolean, disabled?: boolean) => React.ReactNode`            |
+| `renderSecondaryButton`                       | function               | ❌       | `(name: string, onPress: () => void) => React.ReactNode`                                                         |
+| `renderAlertBanner`                           | function               | ❌       | `(variant: 'error'                                                                                               | 'info', message: string) => React.ReactNode` |
+| `renderDate`                                  | function               | ❌       | `(name: string, onChange: (value: string) => void) => React.ReactNode`                                           |
+| `renderPortingProtectionDisabledConfirmation` | function               | ❌       | `(onConfirm: () => void) => React.ReactNode`                                                                     |
+| `renderProvidersDropdown`                     | function               | ❌       | `(name: string, providers: {id: string; name: string;}[], onChange: (value: string) => void) => React.ReactNode` |
+| `defaultTextFont`                             | string                 | ❌       | Custom font used in all default components.                                                                      |
 
 #### Text
 
@@ -415,6 +420,5 @@ renderProvidersDropdown={(name, providers, onChange) => (
 | `protectionDisabling.cancel`  | Cancel                      |
 | `portingInfoLink`             | See Porting instructions    |
 | `protectionDisabling.button`  | Request Porting Again       |
-| `portingDeclined.button`      | Contact Customer support    |
 | `donorProvider`               | N/A                         |
 | `donorProvider.dropdown`      | Donor providers dropdown    |
diff --git a/example/app/porting/index.tsx b/example/app/porting/index.tsx
index c1425e4..af37f63 100644
--- a/example/app/porting/index.tsx
+++ b/example/app/porting/index.tsx
@@ -14,19 +14,20 @@ import {
 
 import { PortingEmbed } from '../../../src'
 import { PortingStep } from '../../../src/PortingEmbed/nextPortingStep'
+import { Porting } from '../../../types/porting'
 
 export default function PortingEmbedScreen() {
   const [sessionJson, setSessionJson] = useState('')
   const [connectSession, setConnectSession] = useState<any>(null)
   const [isLoaded, setLoaded] = useState(false)
   const [isCompleted, setCompleted] = useState(false)
-  const [clickedCustomerSupport, setClickedCustomerSupport] = useState(false)
   const [portingStep, setPortingStep] = useState<PortingStep>()
   const [isChecked, setChecked] = useState(false)
   const [date, setDate] = useState<Date | undefined>(new Date())
   const [currentProvider, setCurrentProvider] = useState<string | undefined>(
     undefined
   )
+  const [isPortingDeclined, setPortingDeclined] = useState<boolean>(false)
 
   function handleSubmit() {
     setConnectSession(JSON.parse(sessionJson))
@@ -41,11 +42,19 @@ export default function PortingEmbedScreen() {
     setLoaded(true)
   }, [])
 
-  const handleError = useCallback((_error: Error) => {
-    console.log('onError triggered')
-    setLoaded(false)
-    setConnectSession(null)
-  }, [])
+  type PortingEmbedError = 'portingDeclined' | string
+
+  const handleError = useCallback(
+    (_error?: Error, _porting?: Porting, errorCode?: PortingEmbedError) => {
+      console.log('onError triggered')
+      if (errorCode && errorCode === 'portingDeclined') {
+        setPortingDeclined(true)
+      }
+      setLoaded(false)
+      setConnectSession(null)
+    },
+    []
+  )
 
   const handleInitialized = useCallback(() => {
     console.log('onInitialized triggered, embed got a token')
@@ -71,7 +80,6 @@ export default function PortingEmbedScreen() {
     'protectionDisabling.cancel': 'Cancel',
     portingInfoLink: 'See Porting instructions',
     'protectionDisabling.button': 'Request Porting Again',
-    'portingDeclined.button': 'Contact Customer support',
     donorProvider: 'Current provider',
     'donorProvider.dropdown': 'Select your current provider',
   }
@@ -113,10 +121,8 @@ export default function PortingEmbedScreen() {
       <View style={{ width: '100%', height: 1, backgroundColor: 'gray' }} />
       {Boolean(!isLoaded && connectSession) && <Text>Loading...</Text>}
       {isCompleted && <Text>The porting is submitted!</Text>}
-      {clickedCustomerSupport && (
-        <Text>User has requested customer support</Text>
-      )}
       {portingStep && <Text>Current Porting step: {portingStep}</Text>}
+      {isPortingDeclined && <Text>The porting was declined.</Text>}
       {!isCompleted && (
         <PortingEmbed
           project="dev"
@@ -125,7 +131,6 @@ export default function PortingEmbedScreen() {
           onLoaded={handleLoaded}
           onError={handleError}
           onCompleted={() => setCompleted(true)}
-          onSupportRequested={() => setClickedCustomerSupport(true)}
           onPortingStep={(step) => setPortingStep(step)}
           defaultTextFont="Satoshi-Regular"
           renderTitle={(step) =>
diff --git a/src/PortingEmbed/CustomOptionsProvider.tsx b/src/PortingEmbed/CustomOptionsProvider.tsx
index 3364dfc..e64f884 100644
--- a/src/PortingEmbed/CustomOptionsProvider.tsx
+++ b/src/PortingEmbed/CustomOptionsProvider.tsx
@@ -1,10 +1,16 @@
 import { createContext, ReactNode, useContext } from 'react'
 import { InputModeOptions } from 'react-native'
 
+import { Porting } from '../../types/porting'
 import { PortingStep } from './nextPortingStep'
+import { PortingEmbedError } from './PortingEmbed'
 
 type EmbedOptions = {
-  onError?: (error: Error) => unknown
+  onError: (
+    error?: Error,
+    porting?: Porting,
+    errorCode?: PortingEmbedError
+  ) => unknown
   renderTitle?: (step: PortingStep) => React.ReactNode
   renderInput?: (
     name: string,
diff --git a/src/PortingEmbed/PortingEmbed.tsx b/src/PortingEmbed/PortingEmbed.tsx
index b3b9768..c19ac36 100644
--- a/src/PortingEmbed/PortingEmbed.tsx
+++ b/src/PortingEmbed/PortingEmbed.tsx
@@ -7,12 +7,18 @@ import { CustomOptionsProvider } from './CustomOptionsProvider'
 import { PortingStep } from './nextPortingStep'
 import { PortingFormContainer } from './PortingFormContainer'
 
+export type PortingEmbedError = 'portingDeclined' | string
+
 type Props = {
   connectSession?: unknown
   project: string
   onLoaded?: () => unknown
   onInitialized?: () => unknown
-  onError?: (error: Error) => unknown
+  onError: (
+    error?: Error,
+    porting?: Porting,
+    errorCode?: PortingEmbedError
+  ) => unknown
   onCompleted: (porting: Porting) => unknown
   onSupportRequested?: () => unknown
   onPortingStep?: (portingStep: PortingStep) => unknown
@@ -56,7 +62,6 @@ export function PortingEmbed({
   onLoaded,
   onError,
   onCompleted,
-  onSupportRequested,
   onPortingStep,
   renderTitle,
   renderInput,
@@ -90,12 +95,12 @@ export function PortingEmbed({
         }
         defaultTextFont={defaultTextFont}
         renderProvidersDropdown={renderProvidersDropdown}
+        onError={onError}
       >
         <PortingFormContainer
           onLoaded={onLoaded}
           onError={onError}
           onCompleted={onCompleted}
-          onSupportRequested={onSupportRequested}
           onPortingStep={onPortingStep}
         />
       </CustomOptionsProvider>
diff --git a/src/PortingEmbed/PortingFormContainer.tsx b/src/PortingEmbed/PortingFormContainer.tsx
index 67799b2..2c711fe 100644
--- a/src/PortingEmbed/PortingFormContainer.tsx
+++ b/src/PortingEmbed/PortingFormContainer.tsx
@@ -15,16 +15,19 @@ import { AddressForm } from './features/Address/AddressForm'
 import { CarrierInfoForm } from './features/CarrierDetails/CarrierDetailsForm'
 import { DonorApprovalForm } from './features/DonorApproval/DonorApprovalForm'
 import { DonorProviderForm } from './features/DonorProvider/DonorProviderForm'
-import { GenericPortingDeclined } from './features/GenericPortingDeclined'
 import { ProtectionDisabling } from './features/ProtectionDisabling'
 import { nextPortingStep, PortingStep } from './nextPortingStep'
+import { PortingEmbedError } from './PortingEmbed'
 import { hasAllRequiredFieldsCompleted } from './util/portingUtils'
 
 type Props = {
-  onError?: (error: Error) => unknown
+  onError: (
+    error?: Error,
+    porting?: Porting,
+    errorCode?: PortingEmbedError
+  ) => unknown
   onLoaded?: () => unknown
   onCompleted: (porting: Porting) => unknown
-  onSupportRequested?: () => unknown
   onPortingStep?: (portingStep: PortingStep) => unknown
 }
 
@@ -32,7 +35,6 @@ export function PortingFormContainer({
   onError,
   onLoaded,
   onCompleted,
-  onSupportRequested,
   onPortingStep,
 }: Props) {
   const { connectSession } = useSessionContext()
@@ -52,7 +54,7 @@ export function PortingFormContainer({
   useEffect(() => {
     if (!error) return
 
-    onError?.(new Error(error))
+    onError(new Error(error))
     console.error(error)
   }, [error, onError])
 
@@ -73,18 +75,32 @@ export function PortingFormContainer({
     return subscription?.porting ? nextPortingStep(subscription?.porting) : null
   }, [subscription?.porting])
 
+  const portingIsCompleted =
+    subscription?.porting &&
+    hasAllRequiredFieldsCompleted(subscription.porting) &&
+    !subscription.porting.declinedCode
+
+  const portingIsDeclined =
+    subscription?.porting && subscription?.porting.status === 'declined'
+
   useEffect(() => {
-    if (
-      subscription?.porting &&
-      hasAllRequiredFieldsCompleted(subscription.porting) &&
-      !subscription.porting.declinedCode
-    ) {
-      onCompleted(subscription.porting) // handles the case of coming back to a Porting when the required porting fields have been filled out
+    if (portingIsCompleted) {
+      onCompleted(subscription.porting!) // handles the case of coming back to a Porting when the required porting fields have been successfully filled out
       onPortingStep?.(null)
+    } else if (portingIsDeclined) {
+      onError(undefined, subscription.porting!, 'portingDeclined') // handles the case of coming back to a declined Porting
     } else {
       onPortingStep?.(portingStep)
     }
-  }, [subscription?.porting, onCompleted, onPortingStep, portingStep])
+  }, [
+    subscription?.porting,
+    onCompleted,
+    onError,
+    onPortingStep,
+    portingStep,
+    portingIsCompleted,
+    portingIsDeclined,
+  ])
 
   if (!subscription) {
     return null
@@ -101,6 +117,9 @@ export function PortingFormContainer({
       const porting = await updatePorting(subscription.porting!.id, portingData)
 
       if (hasAllRequiredFieldsCompleted(porting)) {
+        if (porting.status === 'declined') {
+          onError(undefined, porting, 'portingDeclined')
+        }
         onCompleted(porting)
         onPortingStep?.(portingStep)
         return
@@ -112,6 +131,11 @@ export function PortingFormContainer({
       setPortingUpdateError(
         e instanceof ApiError ? e.message : 'Something went wrong.'
       )
+      onError(
+        e instanceof ApiError ? e : new Error('Something went wrong.'),
+        undefined,
+        undefined
+      )
     } finally {
       setSubmitting(false)
     }
@@ -170,12 +194,6 @@ export function PortingFormContainer({
             declinedCode={subscription.porting.declinedCode}
           />
         )}
-      {subscription.porting.declinedCode && portingStep === null && (
-        <GenericPortingDeclined
-          declinedCode={subscription.porting.declinedCode}
-          onSupportRequested={onSupportRequested}
-        />
-      )}
     </View>
   )
 }
diff --git a/src/PortingEmbed/__tests__/PortingFormContainer.test.tsx b/src/PortingEmbed/__tests__/PortingFormContainer.test.tsx
index 3852d95..2cc296a 100644
--- a/src/PortingEmbed/__tests__/PortingFormContainer.test.tsx
+++ b/src/PortingEmbed/__tests__/PortingFormContainer.test.tsx
@@ -44,7 +44,7 @@ describe('PortingFormContainer', () => {
             token: '123445',
           }}
         >
-          <PortingFormContainer onCompleted={jest.fn()} />
+          <PortingFormContainer onCompleted={jest.fn()} onError={jest.fn()} />
         </ConnectSessionContext.Provider>
       )
       await waitFor(() => {
@@ -72,6 +72,7 @@ describe('PortingFormContainer', () => {
         >
           <PortingFormContainer
             onCompleted={jest.fn()}
+            onError={jest.fn()}
             onPortingStep={(portingStep) => onPortingStep(portingStep)}
           />
         </ConnectSessionContext.Provider>
@@ -116,7 +117,7 @@ describe('PortingFormContainer', () => {
             token: '1234',
           }}
         >
-          <PortingFormContainer onCompleted={jest.fn()} />
+          <PortingFormContainer onCompleted={jest.fn()} onError={jest.fn()} />
         </ConnectSessionContext.Provider>
       )
       await waitFor(() => {
@@ -150,9 +151,10 @@ describe('PortingFormContainer', () => {
                   <Button title={'Confirm'} onPress={onConfirm} />
                 </View>
               ),
+              onError: () => jest.fn,
             }}
           >
-            <PortingFormContainer onCompleted={jest.fn()} />
+            <PortingFormContainer onCompleted={jest.fn()} onError={jest.fn()} />
           </CustomOptionsContext.Provider>
         </ConnectSessionContext.Provider>
       )
@@ -200,7 +202,7 @@ describe('PortingFormContainer', () => {
             token: '1234',
           }}
         >
-          <PortingFormContainer onCompleted={jest.fn()} />
+          <PortingFormContainer onCompleted={jest.fn()} onError={jest.fn()} />
         </ConnectSessionContext.Provider>
       )
       await waitFor(() => {
@@ -242,7 +244,7 @@ describe('PortingFormContainer', () => {
             token: '1234',
           }}
         >
-          <PortingFormContainer onCompleted={jest.fn()} />
+          <PortingFormContainer onCompleted={jest.fn()} onError={jest.fn()} />
         </ConnectSessionContext.Provider>
       )
 
@@ -285,7 +287,7 @@ describe('PortingFormContainer', () => {
             token: '1234',
           }}
         >
-          <PortingFormContainer onCompleted={jest.fn()} />
+          <PortingFormContainer onCompleted={jest.fn()} onError={jest.fn()} />
         </ConnectSessionContext.Provider>
       )
 
@@ -328,7 +330,7 @@ describe('PortingFormContainer', () => {
             token: '1234',
           }}
         >
-          <PortingFormContainer onCompleted={jest.fn()} />
+          <PortingFormContainer onCompleted={jest.fn()} onError={jest.fn()} />
         </ConnectSessionContext.Provider>
       )
 
@@ -341,12 +343,13 @@ describe('PortingFormContainer', () => {
     beforeEach(() => {
       server.use(
         http.get(
-          'https://api.gigs.com/projects/dev/subscriptions/sub_456',
+          'https://api.gigs.com/projects/dev/subscriptions/sub_555',
           () => {
             return HttpResponse.json({
-              id: 'sub_456',
+              id: 'sub_555',
               porting: {
                 ...porting,
+                status: 'declined',
                 declinedCode: 'portingUserInformationMismatch',
               },
             })
@@ -354,7 +357,8 @@ describe('PortingFormContainer', () => {
         )
       )
     })
-    it('prompts the user to contact customer support', async () => {
+    it('triggers onError', async () => {
+      const onError = jest.fn()
       render(
         <ConnectSessionContext.Provider
           value={{
@@ -362,7 +366,7 @@ describe('PortingFormContainer', () => {
               ...connectSession,
               intent: {
                 completePorting: {
-                  subscription: 'sub_456',
+                  subscription: 'sub_555',
                 },
                 type: 'completePorting',
               },
@@ -371,16 +375,20 @@ describe('PortingFormContainer', () => {
             token: '1234',
           }}
         >
-          <PortingFormContainer onCompleted={jest.fn()} />
+          <PortingFormContainer onCompleted={jest.fn()} onError={onError} />
         </ConnectSessionContext.Provider>
       )
 
       await waitFor(() => {
-        expect(
-          screen.getByText(
-            'The porting was declined. Please reach out to Customer Support.'
-          )
-        ).toBeOnTheScreen()
+        expect(onError).toBeCalledWith(
+          undefined,
+          {
+            ...porting,
+            status: 'declined',
+            declinedCode: 'portingUserInformationMismatch',
+          },
+          'portingDeclined'
+        )
       })
     })
   })
@@ -416,7 +424,7 @@ describe('PortingFormContainer', () => {
             token: '1234',
           }}
         >
-          <PortingFormContainer onCompleted={onCompleted} />
+          <PortingFormContainer onCompleted={onCompleted} onError={jest.fn()} />
         </ConnectSessionContext.Provider>
       )
       await waitFor(() => {
@@ -444,6 +452,7 @@ describe('PortingFormContainer', () => {
         >
           <PortingFormContainer
             onCompleted={jest.fn()}
+            onError={jest.fn()}
             onPortingStep={(portingStep) => onPortingStep(portingStep)}
           />
         </ConnectSessionContext.Provider>
diff --git a/src/PortingEmbed/features/DonorProvider/DonorProviderForm.tsx b/src/PortingEmbed/features/DonorProvider/DonorProviderForm.tsx
index 9ababa8..926cd6a 100644
--- a/src/PortingEmbed/features/DonorProvider/DonorProviderForm.tsx
+++ b/src/PortingEmbed/features/DonorProvider/DonorProviderForm.tsx
@@ -39,7 +39,7 @@ export function DonorProviderForm({
   const options = useOptionsContext()
 
   if (!serviceProviders || !serviceProviders.items.length || fetchError) {
-    options?.onError?.(fetchError || new Error('Service Providers not found.'))
+    options?.onError(fetchError || new Error('Service Providers not found.'))
     return null
   }
 
diff --git a/src/PortingEmbed/features/GenericPortingDeclined.tsx b/src/PortingEmbed/features/GenericPortingDeclined.tsx
deleted file mode 100644
index 4650b42..0000000
--- a/src/PortingEmbed/features/GenericPortingDeclined.tsx
+++ /dev/null
@@ -1,51 +0,0 @@
-import { View } from 'react-native'
-
-import { PortingDeclinedCode } from '../../../types/porting'
-import { AlertBanner } from '../../components/AlertBanner'
-import { EmbedButton } from '../../components/EmbedButton'
-import { useOptionsContext } from '../CustomOptionsProvider'
-import { portingDeclinedMessage } from '../util/portingUtils'
-
-type Props = {
-  onSupportRequested?: () => unknown
-  declinedCode: PortingDeclinedCode
-}
-
-export function GenericPortingDeclined({
-  onSupportRequested,
-  declinedCode,
-}: Props) {
-  const options = useOptionsContext()
-
-  return (
-    <View
-      style={[
-        {
-          marginTop: 12,
-          marginBottom: 42,
-        },
-      ]}
-    >
-      <AlertBanner
-        variant="error"
-        message={portingDeclinedMessage(declinedCode)}
-      />
-      <View
-        style={[
-          {
-            marginTop: 32,
-          },
-        ]}
-      >
-        {onSupportRequested && options?.renderPrimaryButton ? (
-          options.renderPrimaryButton(
-            onSupportRequested,
-            'portingDeclined.button'
-          )
-        ) : (
-          <EmbedButton onPress={onSupportRequested!} name="Customer support" />
-        )}
-      </View>
-    </View>
-  )
-}
diff --git a/src/core/ConnectSessionProvider.tsx b/src/core/ConnectSessionProvider.tsx
index ea2a61b..f62cc12 100644
--- a/src/core/ConnectSessionProvider.tsx
+++ b/src/core/ConnectSessionProvider.tsx
@@ -23,7 +23,7 @@ type Props = {
   connectSession: unknown
   children: React.ReactNode
   onInitialized?: () => unknown
-  onError?: (error: Error) => unknown
+  onError: (error: Error) => unknown
 }
 
 export function ConnectSessionProvider({
@@ -87,7 +87,7 @@ export function ConnectSessionProvider({
       } catch (error) {
         setStatus('error')
         console.error(error)
-        onError?.(
+        onError(
           error instanceof Error
             ? error
             : new Error(error?.toString() || 'Unexpected error')
diff --git a/storybook/stories/PortingEmbed/features/GenericPortingDeclined.stories.tsx b/storybook/stories/PortingEmbed/features/GenericPortingDeclined.stories.tsx
deleted file mode 100644
index 6e43168..0000000
--- a/storybook/stories/PortingEmbed/features/GenericPortingDeclined.stories.tsx
+++ /dev/null
@@ -1,38 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react'
-import React from 'react'
-import { SafeAreaView } from 'react-native'
-
-import { GenericPortingDeclined } from '../../../../src/PortingEmbed/features/GenericPortingDeclined'
-
-const meta = {
-  title: 'GenericPortingDeclined',
-  component: GenericPortingDeclined,
-  args: {
-    declinedCode: 'portingUserInformationMismatch',
-    onSupportRequested: undefined,
-  },
-  decorators: [
-    (Story) => (
-      <SafeAreaView
-        style={{
-          backgroundColor: '#f5f5f5',
-          padding: 16,
-        }}
-      >
-        <Story />
-      </SafeAreaView>
-    ),
-  ],
-} satisfies Meta<typeof GenericPortingDeclined>
-
-export default meta
-
-type Story = StoryObj<typeof meta>
-
-export const Basic: Story = {}
-export const WithCustomerSupportCallback: Story = {
-  args: {
-    declinedCode: 'portingUserInformationMismatch',
-    onSupportRequested: () => console.log('Clicked Customer support'),
-  },
-}

From eb98058a68f2995619d06b82a931089c163d65be Mon Sep 17 00:00:00 2001
From: Kamala <kamala@gigs.com>
Date: Fri, 10 May 2024 17:13:00 +0200
Subject: [PATCH 2/7] Remove unused onSupportRequested

---
 docs/porting-embed.md             | 6 ------
 src/PortingEmbed/PortingEmbed.tsx | 1 -
 2 files changed, 7 deletions(-)

diff --git a/docs/porting-embed.md b/docs/porting-embed.md
index a5e805d..de06de4 100644
--- a/docs/porting-embed.md
+++ b/docs/porting-embed.md
@@ -77,11 +77,6 @@ Callback triggered when the embed form is loaded with a subscription and the rel
 `(step: PortingStep) => unknown`  
 Callback that returns the current porting step. Useful to display custom headlines and information in your app depending on the step.
 
-#### `onSupportRequested`
-
-`() => unknown`  
-Callback triggered when the user has clicked the "Customer support" button. You can use it, for example, to open your own Customer support page.
-
 #### `renderTitle`
 
 `(step: PortingStep) => unknown`  
@@ -385,7 +380,6 @@ renderProvidersDropdown={(name, providers, onChange) => (
 | `onError`                                     | function               | ✅       | `(error?:  Error, porting?: Porting, errorCode?: PortingEmbedError)  =>  unknown`                                                                                   |
 | `onInitialized`                               | function               | ❌       | `()  =>  unknown`                                                                                                |
 | `onLoaded`                                    | function               | ❌       | `()  =>  unknown`                                                                                                |
-| `onSupportRequested`                          | function               | ❌       | `() => unknown`                                                                                                  |
 | `onPortingStep`                               | function               | ❌       | `(step: PortingStep) => unknown`                                                                                 |
 | `renderTitle`                                 | function               | ❌       | `(step: PortingStep) => unknown`                                                                                 |
 | `renderCheckbox`                              | function               | ❌       | `(name: string, onChange: (value: string) => void, inputMode?: InputModeOptions) => unknown`                     |
diff --git a/src/PortingEmbed/PortingEmbed.tsx b/src/PortingEmbed/PortingEmbed.tsx
index c19ac36..1f40bca 100644
--- a/src/PortingEmbed/PortingEmbed.tsx
+++ b/src/PortingEmbed/PortingEmbed.tsx
@@ -20,7 +20,6 @@ type Props = {
     errorCode?: PortingEmbedError
   ) => unknown
   onCompleted: (porting: Porting) => unknown
-  onSupportRequested?: () => unknown
   onPortingStep?: (portingStep: PortingStep) => unknown
   renderTitle?: (step: PortingStep) => React.ReactNode
   renderInput?: (

From 31b305b8a4403c7abf7095f32c9b51f4734f6529 Mon Sep 17 00:00:00 2001
From: Kamala <kamala@gigs.com>
Date: Fri, 10 May 2024 17:17:12 +0200
Subject: [PATCH 3/7] add missing required onError in tests

---
 src/PortingEmbed/__tests__/AccountHolderForm.test.tsx  | 9 +++++++++
 src/PortingEmbed/__tests__/AddressForm.test.tsx        | 8 ++++++++
 src/PortingEmbed/__tests__/CarrierDetailsForm.test.tsx | 7 +++++++
 src/PortingEmbed/__tests__/DonorApprovalForm.test.tsx  | 3 +++
 src/PortingEmbed/__tests__/DonorProviderForm.test.tsx  | 1 +
 5 files changed, 28 insertions(+)

diff --git a/src/PortingEmbed/__tests__/AccountHolderForm.test.tsx b/src/PortingEmbed/__tests__/AccountHolderForm.test.tsx
index 4a6ce02..7de3541 100644
--- a/src/PortingEmbed/__tests__/AccountHolderForm.test.tsx
+++ b/src/PortingEmbed/__tests__/AccountHolderForm.test.tsx
@@ -83,6 +83,7 @@ describe('AccountHolderForm', () => {
               Custom account holder title
             </Text>
           ),
+          onError: () => jest.fn(),
         }}
       >
         <AccountHolderForm
@@ -131,6 +132,7 @@ describe('AccountHolderForm', () => {
               placeholder={placeholders[name]}
             />
           ),
+          onError: () => jest.fn(),
         }}
       >
         <AccountHolderForm
@@ -160,6 +162,7 @@ describe('AccountHolderForm', () => {
               placeholder={placeholders[name]}
             />
           ),
+          onError: () => jest.fn(),
         }}
       >
         <AccountHolderForm
@@ -202,6 +205,7 @@ describe('AccountHolderForm', () => {
                 disabled={disabled}
               />
             ),
+            onError: () => jest.fn(),
           }}
         >
           <AccountHolderForm
@@ -239,6 +243,7 @@ describe('AccountHolderForm', () => {
                 onPress={onPress}
               />
             ),
+            onError: () => jest.fn(),
           }}
         >
           <AccountHolderForm
@@ -275,6 +280,7 @@ describe('AccountHolderForm', () => {
           renderSecondaryButton: (name, _onPress) => (
             <Button onPress={onPressLink} title={placeholders[name]!} />
           ),
+          onError: () => jest.fn(),
         }}
       >
         <AccountHolderForm
@@ -317,6 +323,7 @@ describe('AccountHolderForm', () => {
               </Text>
             </View>
           ),
+          onError: () => jest.fn(),
         }}
       >
         <AccountHolderForm
@@ -356,6 +363,7 @@ describe('AccountHolderForm', () => {
               </Text>
             </View>
           ),
+          onError: () => jest.fn(),
         }}
       >
         <AccountHolderForm
@@ -377,6 +385,7 @@ describe('AccountHolderForm', () => {
       <CustomOptionsContext.Provider
         value={{
           defaultTextFont: 'Custom-font',
+          onError: () => jest.fn(),
         }}
       >
         <AccountHolderForm
diff --git a/src/PortingEmbed/__tests__/AddressForm.test.tsx b/src/PortingEmbed/__tests__/AddressForm.test.tsx
index 353b6f7..fd1bda1 100644
--- a/src/PortingEmbed/__tests__/AddressForm.test.tsx
+++ b/src/PortingEmbed/__tests__/AddressForm.test.tsx
@@ -82,6 +82,7 @@ describe('AddressForm', () => {
               Custom address title
             </Text>
           ),
+          onError: () => jest.fn(),
         }}
       >
         <AddressForm
@@ -120,6 +121,7 @@ describe('AddressForm', () => {
               placeholder={placeholders[name]}
             />
           ),
+          onError: () => jest.fn(),
         }}
       >
         <AddressForm
@@ -155,6 +157,7 @@ describe('AddressForm', () => {
                 disabled={disabled}
               />
             ),
+            onError: () => jest.fn(),
           }}
         >
           <AddressForm
@@ -200,6 +203,7 @@ describe('AddressForm', () => {
                 onPress={onPress}
               />
             ),
+            onError: () => jest.fn(),
           }}
         >
           <AddressForm
@@ -239,6 +243,7 @@ describe('AddressForm', () => {
           renderSecondaryButton: (name, _onPress) => (
             <Button onPress={onPressLink} title={placeholders[name]!} />
           ),
+          onError: () => jest.fn(),
         }}
       >
         <AddressForm
@@ -280,6 +285,7 @@ describe('AddressForm', () => {
               </Text>
             </View>
           ),
+          onError: () => jest.fn(),
         }}
       >
         <AddressForm
@@ -319,6 +325,7 @@ describe('AddressForm', () => {
               </Text>
             </View>
           ),
+          onError: () => jest.fn(),
         }}
       >
         <AddressForm
@@ -339,6 +346,7 @@ describe('AddressForm', () => {
       <CustomOptionsContext.Provider
         value={{
           defaultTextFont: 'Custom-font',
+          onError: () => jest.fn(),
         }}
       >
         <AddressForm
diff --git a/src/PortingEmbed/__tests__/CarrierDetailsForm.test.tsx b/src/PortingEmbed/__tests__/CarrierDetailsForm.test.tsx
index f524d70..3e780bf 100644
--- a/src/PortingEmbed/__tests__/CarrierDetailsForm.test.tsx
+++ b/src/PortingEmbed/__tests__/CarrierDetailsForm.test.tsx
@@ -75,6 +75,7 @@ describe('CarrierInfoForm', () => {
               Custom carrier details title
             </Text>
           ),
+          onError: () => jest.fn(),
         }}
       >
         <CarrierInfoForm
@@ -108,6 +109,7 @@ describe('CarrierInfoForm', () => {
               placeholder={placeholders[name]}
             />
           ),
+          onError: () => jest.fn(),
         }}
       >
         <CarrierInfoForm
@@ -136,6 +138,7 @@ describe('CarrierInfoForm', () => {
                 disabled={disabled}
               />
             ),
+            onError: () => jest.fn(),
           }}
         >
           <CarrierInfoForm
@@ -173,6 +176,7 @@ describe('CarrierInfoForm', () => {
                 onPress={onPress}
               />
             ),
+            onError: () => jest.fn(),
           }}
         >
           <CarrierInfoForm
@@ -211,6 +215,7 @@ describe('CarrierInfoForm', () => {
           renderSecondaryButton: (name, _onPress) => (
             <Button onPress={onPressLink} title={placeholders[name]!} />
           ),
+          onError: () => jest.fn(),
         }}
       >
         <CarrierInfoForm
@@ -251,6 +256,7 @@ describe('CarrierInfoForm', () => {
               </Text>
             </View>
           ),
+          onError: () => jest.fn(),
         }}
       >
         <CarrierInfoForm
@@ -271,6 +277,7 @@ describe('CarrierInfoForm', () => {
       <CustomOptionsContext.Provider
         value={{
           defaultTextFont: 'Custom-font',
+          onError: () => jest.fn(),
         }}
       >
         <CarrierInfoForm
diff --git a/src/PortingEmbed/__tests__/DonorApprovalForm.test.tsx b/src/PortingEmbed/__tests__/DonorApprovalForm.test.tsx
index c7cc247..bd67f33 100644
--- a/src/PortingEmbed/__tests__/DonorApprovalForm.test.tsx
+++ b/src/PortingEmbed/__tests__/DonorApprovalForm.test.tsx
@@ -86,6 +86,7 @@ describe('DonorApprovalForm', () => {
               onChecked={onChecked}
             />
           ),
+          onError: () => jest.fn(),
         }}
       >
         <DonorApprovalForm
@@ -126,6 +127,7 @@ describe('DonorApprovalForm', () => {
               disabled={disabled}
             />
           ),
+          onError: () => jest.fn(),
         }}
       >
         <DonorApprovalForm
@@ -156,6 +158,7 @@ describe('DonorApprovalForm', () => {
       <CustomOptionsContext.Provider
         value={{
           defaultTextFont: 'Custom-font',
+          onError: () => jest.fn(),
         }}
       >
         <DonorApprovalForm
diff --git a/src/PortingEmbed/__tests__/DonorProviderForm.test.tsx b/src/PortingEmbed/__tests__/DonorProviderForm.test.tsx
index 9e289ca..cd1eb8c 100644
--- a/src/PortingEmbed/__tests__/DonorProviderForm.test.tsx
+++ b/src/PortingEmbed/__tests__/DonorProviderForm.test.tsx
@@ -110,6 +110,7 @@ describe('DonorProviderForm', () => {
                 onPress={onPress}
               />
             ),
+            onError: () => jest.fn(),
           }}
         >
           <DonorProviderForm

From 4c98a870e85b52ddea103487af54d619d17f2839 Mon Sep 17 00:00:00 2001
From: Kamala <kamala@gigs.com>
Date: Tue, 28 May 2024 11:20:27 +0200
Subject: [PATCH 4/7] refactor onError

---
 example/app/porting/index.tsx              |  4 +--
 src/PortingEmbed/CustomOptionsProvider.tsx |  9 ++-----
 src/PortingEmbed/PortingEmbed.tsx          | 13 +++++----
 src/PortingEmbed/PortingFormContainer.tsx  | 31 +++++++++++-----------
 src/core/ConnectSessionProvider.tsx        |  6 +++--
 5 files changed, 31 insertions(+), 32 deletions(-)

diff --git a/example/app/porting/index.tsx b/example/app/porting/index.tsx
index af37f63..dc6e8bc 100644
--- a/example/app/porting/index.tsx
+++ b/example/app/porting/index.tsx
@@ -45,9 +45,9 @@ export default function PortingEmbedScreen() {
   type PortingEmbedError = 'portingDeclined' | string
 
   const handleError = useCallback(
-    (_error?: Error, _porting?: Porting, errorCode?: PortingEmbedError) => {
+    (_error: Error, meta: { code: PortingEmbedError; porting?: Porting }) => {
       console.log('onError triggered')
-      if (errorCode && errorCode === 'portingDeclined') {
+      if (meta.code && meta.code === 'portingDeclined') {
         setPortingDeclined(true)
       }
       setLoaded(false)
diff --git a/src/PortingEmbed/CustomOptionsProvider.tsx b/src/PortingEmbed/CustomOptionsProvider.tsx
index e64f884..e2d5782 100644
--- a/src/PortingEmbed/CustomOptionsProvider.tsx
+++ b/src/PortingEmbed/CustomOptionsProvider.tsx
@@ -1,16 +1,11 @@
 import { createContext, ReactNode, useContext } from 'react'
 import { InputModeOptions } from 'react-native'
 
-import { Porting } from '../../types/porting'
 import { PortingStep } from './nextPortingStep'
-import { PortingEmbedError } from './PortingEmbed'
+import { Metadata } from './PortingEmbed'
 
 type EmbedOptions = {
-  onError: (
-    error?: Error,
-    porting?: Porting,
-    errorCode?: PortingEmbedError
-  ) => unknown
+  onError: (error: Error, meta: Metadata) => unknown
   renderTitle?: (step: PortingStep) => React.ReactNode
   renderInput?: (
     name: string,
diff --git a/src/PortingEmbed/PortingEmbed.tsx b/src/PortingEmbed/PortingEmbed.tsx
index 1f40bca..1eb7c5d 100644
--- a/src/PortingEmbed/PortingEmbed.tsx
+++ b/src/PortingEmbed/PortingEmbed.tsx
@@ -9,16 +9,19 @@ import { PortingFormContainer } from './PortingFormContainer'
 
 export type PortingEmbedError = 'portingDeclined' | string
 
+export type Metadata = PortingEmbedErrorMetadata
+
+type PortingEmbedErrorMetadata = {
+  code: PortingEmbedError
+  porting?: Porting
+}
+
 type Props = {
   connectSession?: unknown
   project: string
   onLoaded?: () => unknown
   onInitialized?: () => unknown
-  onError: (
-    error?: Error,
-    porting?: Porting,
-    errorCode?: PortingEmbedError
-  ) => unknown
+  onError: (error: Error, meta: Metadata) => unknown
   onCompleted: (porting: Porting) => unknown
   onPortingStep?: (portingStep: PortingStep) => unknown
   renderTitle?: (step: PortingStep) => React.ReactNode
diff --git a/src/PortingEmbed/PortingFormContainer.tsx b/src/PortingEmbed/PortingFormContainer.tsx
index 2c711fe..b5da24b 100644
--- a/src/PortingEmbed/PortingFormContainer.tsx
+++ b/src/PortingEmbed/PortingFormContainer.tsx
@@ -17,15 +17,11 @@ import { DonorApprovalForm } from './features/DonorApproval/DonorApprovalForm'
 import { DonorProviderForm } from './features/DonorProvider/DonorProviderForm'
 import { ProtectionDisabling } from './features/ProtectionDisabling'
 import { nextPortingStep, PortingStep } from './nextPortingStep'
-import { PortingEmbedError } from './PortingEmbed'
+import { Metadata } from './PortingEmbed'
 import { hasAllRequiredFieldsCompleted } from './util/portingUtils'
 
 type Props = {
-  onError: (
-    error?: Error,
-    porting?: Porting,
-    errorCode?: PortingEmbedError
-  ) => unknown
+  onError: (error: Error, meta: Metadata) => unknown
   onLoaded?: () => unknown
   onCompleted: (porting: Porting) => unknown
   onPortingStep?: (portingStep: PortingStep) => unknown
@@ -54,7 +50,7 @@ export function PortingFormContainer({
   useEffect(() => {
     if (!error) return
 
-    onError(new Error(error))
+    onError(new Error(error), { code: 'initializationError' })
     console.error(error)
   }, [error, onError])
 
@@ -80,15 +76,17 @@ export function PortingFormContainer({
     hasAllRequiredFieldsCompleted(subscription.porting) &&
     !subscription.porting.declinedCode
 
-  const portingIsDeclined =
-    subscription?.porting && subscription?.porting.status === 'declined'
+  const portingIsDeclined = subscription?.porting?.status === 'declined'
 
   useEffect(() => {
     if (portingIsCompleted) {
       onCompleted(subscription.porting!) // handles the case of coming back to a Porting when the required porting fields have been successfully filled out
       onPortingStep?.(null)
     } else if (portingIsDeclined) {
-      onError(undefined, subscription.porting!, 'portingDeclined') // handles the case of coming back to a declined Porting
+      onError(new Error('Porting is declined'), {
+        code: 'portingDeclined',
+        porting: subscription.porting!,
+      }) // handles the case of coming back to a declined Porting
     } else {
       onPortingStep?.(portingStep)
     }
@@ -118,7 +116,10 @@ export function PortingFormContainer({
 
       if (hasAllRequiredFieldsCompleted(porting)) {
         if (porting.status === 'declined') {
-          onError(undefined, porting, 'portingDeclined')
+          onError(new Error('Porting is declined'), {
+            code: 'portingDeclined',
+            porting: subscription.porting!,
+          })
         }
         onCompleted(porting)
         onPortingStep?.(portingStep)
@@ -131,11 +132,9 @@ export function PortingFormContainer({
       setPortingUpdateError(
         e instanceof ApiError ? e.message : 'Something went wrong.'
       )
-      onError(
-        e instanceof ApiError ? e : new Error('Something went wrong.'),
-        undefined,
-        undefined
-      )
+      onError(e instanceof ApiError ? e : new Error('Something went wrong.'), {
+        code: 'unexpectedError',
+      })
     } finally {
       setSubmitting(false)
     }
diff --git a/src/core/ConnectSessionProvider.tsx b/src/core/ConnectSessionProvider.tsx
index f62cc12..70f7476 100644
--- a/src/core/ConnectSessionProvider.tsx
+++ b/src/core/ConnectSessionProvider.tsx
@@ -4,6 +4,7 @@ import {
   ConnectSession,
   ConnectSessionIntent,
 } from '../../types/connectSession'
+import { Metadata } from '../PortingEmbed/PortingEmbed'
 import { assert } from './assert'
 import { exchangeSessionWithToken } from './token'
 
@@ -23,7 +24,7 @@ type Props = {
   connectSession: unknown
   children: React.ReactNode
   onInitialized?: () => unknown
-  onError: (error: Error) => unknown
+  onError: (error: Error, meta: Metadata) => unknown
 }
 
 export function ConnectSessionProvider({
@@ -90,7 +91,8 @@ export function ConnectSessionProvider({
         onError(
           error instanceof Error
             ? error
-            : new Error(error?.toString() || 'Unexpected error')
+            : new Error(error?.toString() || 'Unexpected error'),
+          { code: 'tokenFetchingError' }
         )
       }
     }

From 7b67f8438146d3173cc0c17863349a3408eae00a Mon Sep 17 00:00:00 2001
From: Kamala <kamala@gigs.com>
Date: Tue, 28 May 2024 12:45:59 +0200
Subject: [PATCH 5/7] fix tests and missing refactor

---
 src/PortingEmbed/PortingFormContainer.tsx                | 8 ++++++--
 src/PortingEmbed/__tests__/PortingFormContainer.test.tsx | 9 ++++-----
 .../features/DonorProvider/DonorProviderForm.tsx         | 5 ++++-
 3 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/src/PortingEmbed/PortingFormContainer.tsx b/src/PortingEmbed/PortingFormContainer.tsx
index b5da24b..06d57c0 100644
--- a/src/PortingEmbed/PortingFormContainer.tsx
+++ b/src/PortingEmbed/PortingFormContainer.tsx
@@ -50,9 +50,12 @@ export function PortingFormContainer({
   useEffect(() => {
     if (!error) return
 
-    onError(new Error(error), { code: 'initializationError' })
+    onError(new Error(error), {
+      code: 'initializationError',
+      porting: subscription?.porting || undefined,
+    })
     console.error(error)
-  }, [error, onError])
+  }, [error, onError, subscription?.porting])
 
   // TODO: move onLoaded into the initial data fetching instead of an effect, so
   // it can't trigger multiple times, and will only be triggered for the initial
@@ -134,6 +137,7 @@ export function PortingFormContainer({
       )
       onError(e instanceof ApiError ? e : new Error('Something went wrong.'), {
         code: 'unexpectedError',
+        porting: subscription?.porting || undefined,
       })
     } finally {
       setSubmitting(false)
diff --git a/src/PortingEmbed/__tests__/PortingFormContainer.test.tsx b/src/PortingEmbed/__tests__/PortingFormContainer.test.tsx
index 2cc296a..39ac2de 100644
--- a/src/PortingEmbed/__tests__/PortingFormContainer.test.tsx
+++ b/src/PortingEmbed/__tests__/PortingFormContainer.test.tsx
@@ -380,15 +380,14 @@ describe('PortingFormContainer', () => {
       )
 
       await waitFor(() => {
-        expect(onError).toBeCalledWith(
-          undefined,
-          {
+        expect(onError).toBeCalledWith(new Error('Porting is declined'), {
+          code: 'portingDeclined',
+          porting: {
             ...porting,
             status: 'declined',
             declinedCode: 'portingUserInformationMismatch',
           },
-          'portingDeclined'
-        )
+        })
       })
     })
   })
diff --git a/src/PortingEmbed/features/DonorProvider/DonorProviderForm.tsx b/src/PortingEmbed/features/DonorProvider/DonorProviderForm.tsx
index 926cd6a..8409761 100644
--- a/src/PortingEmbed/features/DonorProvider/DonorProviderForm.tsx
+++ b/src/PortingEmbed/features/DonorProvider/DonorProviderForm.tsx
@@ -39,7 +39,10 @@ export function DonorProviderForm({
   const options = useOptionsContext()
 
   if (!serviceProviders || !serviceProviders.items.length || fetchError) {
-    options?.onError(fetchError || new Error('Service Providers not found.'))
+    options?.onError(fetchError || new Error('Service Providers not found.'), {
+      code: 'providersNotFound',
+      porting,
+    })
     return null
   }
 

From c6b5a04c48433588f2f6554435665c7e6b134fc3 Mon Sep 17 00:00:00 2001
From: Kamala <kamala@gigs.com>
Date: Tue, 28 May 2024 17:43:26 +0200
Subject: [PATCH 6/7] changes after review

---
 docs/porting-embed.md                     | 15 +++++---
 src/PortingEmbed/PortingEmbed.tsx         | 15 +++++---
 src/PortingEmbed/PortingFormContainer.tsx | 33 +++++++++++-----
 src/data/api.ts                           | 47 ++++++++++++++++++++---
 4 files changed, 84 insertions(+), 26 deletions(-)

diff --git a/docs/porting-embed.md b/docs/porting-embed.md
index de06de4..9782fea 100644
--- a/docs/porting-embed.md
+++ b/docs/porting-embed.md
@@ -53,12 +53,15 @@ Callback triggered when the number porting is completed.
 
 #### `onError`
 
-`(error?:  Error, porting?: Porting, errorCode?: PortingEmbedError)  =>  unknown`
+`(error: Error, meta: Metadata)  =>  unknown`
 
-Callback triggered when: 
-* There is an error initializing the porting form. The error may stem from an invalid session, in which case recovery can be attempted by generating and passing a new Connect session to the embed. The `error` is passed as an argument to the callback.
-* There is a failed attempt to retrieve a subscription. In this case it is advisable to inform the user to try again later or to contact customer support for assistance. The `error` is passed as an argument to the callback.
-* The porting has been declined. The `porting` object and the error code `portingDeclined` are passed as arguments to the callback. 
+Callback triggered when the embed is in an error state. The `metadata` object includes a `code` field for the error, which gives more context about the error, and an optional `porting` field. The callback is triggered when:
+
+- There is an error initializing the porting form (code `'initializationError'`). The error may stem from an invalid session, in which case recovery can be attempted by generating and passing a new Connect session to the embed. The `porting` object is passed if present.
+- There is an error retrieving the authorization token (code `'tokenFetchingError'`). 
+- There is a failed attempt to retrieve a subscription (the code is passed from the [Gigs API Error codes](https://developers.gigs.com/docs/concepts/error-codes)). In this case it is advisable to inform the user to try again later or to contact customer support for assistance. The `error` is passed as an argument to the callback.
+- There is an error fetching service providers in the donor providers form (`'providersNotFound'`).
+- The porting has been declined. The `porting` object and the error code `portingDeclined` are passed as arguments to the callback.
 
 ### Optional props
 
@@ -377,7 +380,7 @@ renderProvidersDropdown={(name, providers, onChange) => (
 | `connectSession`                              | Connect Session object | ✅       | A Connect Session object with an intent of type `completePorting`.                                               |
 | `project`                                     | string                 | ✅       | Your project ID.                                                                                                 |
 | `onCompleted`                                 | function               | ✅       | `(porting:  Porting)  =>  unknown`                                                                               |
-| `onError`                                     | function               | ✅       | `(error?:  Error, porting?: Porting, errorCode?: PortingEmbedError)  =>  unknown`                                                                                   |
+| `onError`                                     | function               | ✅       | `(error:  Error, meta: Metadata)  =>  unknown`                                                                   |
 | `onInitialized`                               | function               | ❌       | `()  =>  unknown`                                                                                                |
 | `onLoaded`                                    | function               | ❌       | `()  =>  unknown`                                                                                                |
 | `onPortingStep`                               | function               | ❌       | `(step: PortingStep) => unknown`                                                                                 |
diff --git a/src/PortingEmbed/PortingEmbed.tsx b/src/PortingEmbed/PortingEmbed.tsx
index 1eb7c5d..7b47535 100644
--- a/src/PortingEmbed/PortingEmbed.tsx
+++ b/src/PortingEmbed/PortingEmbed.tsx
@@ -3,16 +3,19 @@ import { InputModeOptions } from 'react-native'
 
 import { Porting } from '../../types/porting'
 import { ConnectSessionProvider } from '../core/ConnectSessionProvider'
+import { ApiErrorType } from '../data/api'
 import { CustomOptionsProvider } from './CustomOptionsProvider'
 import { PortingStep } from './nextPortingStep'
 import { PortingFormContainer } from './PortingFormContainer'
 
-export type PortingEmbedError = 'portingDeclined' | string
-
-export type Metadata = PortingEmbedErrorMetadata
-
-type PortingEmbedErrorMetadata = {
-  code: PortingEmbedError
+export type Metadata = {
+  code:
+    | 'portingDeclined'
+    | 'tokenFetchingError'
+    | 'initializationError'
+    | 'providersNotFound'
+    | 'unexpectedError'
+    | ApiErrorType
   porting?: Porting
 }
 
diff --git a/src/PortingEmbed/PortingFormContainer.tsx b/src/PortingEmbed/PortingFormContainer.tsx
index 06d57c0..fac99ca 100644
--- a/src/PortingEmbed/PortingFormContainer.tsx
+++ b/src/PortingEmbed/PortingFormContainer.tsx
@@ -50,12 +50,20 @@ export function PortingFormContainer({
   useEffect(() => {
     if (!error) return
 
-    onError(new Error(error), {
-      code: 'initializationError',
-      porting: subscription?.porting || undefined,
-    })
+    if (error instanceof ApiError) {
+      onError(error, {
+        code: error instanceof ApiError ? error.code : 'initializationError',
+        porting: subscription?.porting || undefined,
+      })
+    } else {
+      onError(new Error(error), {
+        code: 'initializationError',
+        porting: subscription?.porting || undefined,
+      })
+    }
+
     console.error(error)
-  }, [error, onError, subscription?.porting])
+  }, [error, onError, subscription])
 
   // TODO: move onLoaded into the initial data fetching instead of an effect, so
   // it can't trigger multiple times, and will only be triggered for the initial
@@ -135,10 +143,17 @@ export function PortingFormContainer({
       setPortingUpdateError(
         e instanceof ApiError ? e.message : 'Something went wrong.'
       )
-      onError(e instanceof ApiError ? e : new Error('Something went wrong.'), {
-        code: 'unexpectedError',
-        porting: subscription?.porting || undefined,
-      })
+      if (e instanceof ApiError) {
+        onError(e, {
+          code: e.code,
+          porting: subscription?.porting || undefined,
+        })
+      } else {
+        onError(new Error('Something went wrong.'), {
+          code: 'unexpectedError',
+          porting: subscription?.porting || undefined,
+        })
+      }
     } finally {
       setSubmitting(false)
     }
diff --git a/src/data/api.ts b/src/data/api.ts
index 4cfa7a1..8adbe84 100644
--- a/src/data/api.ts
+++ b/src/data/api.ts
@@ -7,12 +7,49 @@ import { useSessionContext } from '../core/ConnectSessionProvider'
 
 const baseUrlWithProjects = `https://api.gigs.com/projects`
 
-export class ApiError extends Error {}
+export type ApiErrorType =
+  | 'malformed'
+  | 'unauthenticated'
+  | 'permissionDenied'
+  | 'notFound'
+  | 'conflict'
+  | 'invalid'
+  | 'tooManyRequests'
+  | 'internal'
+  | 'notImplemented'
+  | 'networkError'
+
+interface ApiErrorOptions {
+  type: string
+  code: ApiErrorType
+  message: string
+  hint: string
+  documentation: string[]
+}
+
+export class ApiError extends Error {
+  object: string
+  type: string
+  code: ApiErrorType
+  hint: string
+  documentation: string[]
+
+  constructor({ type, code, message, hint, documentation }: ApiErrorOptions) {
+    super(message)
+    this.object = 'error'
+    this.type = type
+    this.code = code
+    this.hint = hint
+    this.documentation = documentation
+
+    Object.setPrototypeOf(this, ApiError.prototype)
+  }
+}
 
 export function useGetSubscription(subscription: string) {
   const { project, token } = useSessionContext()
   const [loading, setLoading] = useState(false)
-  const [error, setError] = useState<string | null>(null)
+  const [error, setError] = useState<ApiError | string | null>(null)
   const [data, setData] = useState<null | Subscription>(null)
 
   const getSubscription = useCallback(async () => {
@@ -35,7 +72,7 @@ export function useGetSubscription(subscription: string) {
       }
     } catch (e) {
       if (e instanceof ApiError) {
-        setError(e.message)
+        setError(e)
       } else {
         setError('Something went wrong')
       }
@@ -94,8 +131,8 @@ export function useUpdatePorting() {
         const body = await res
           .json()
           .catch(async () => ({ message: await res.text() }))
-          .catch((error) => ({ message: error.message }))
-        throw new ApiError('Failed: ' + body.message)
+          .catch((error) => error)
+        throw new ApiError(body.error)
       }
 
       const body = (await res.json()) as Porting

From 0849f8895b013d1ab8177afcf2e06de92403b713 Mon Sep 17 00:00:00 2001
From: Kamala <kamala@gigs.com>
Date: Tue, 28 May 2024 21:58:36 +0200
Subject: [PATCH 7/7] remove redundant ternary

---
 src/PortingEmbed/PortingFormContainer.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/PortingEmbed/PortingFormContainer.tsx b/src/PortingEmbed/PortingFormContainer.tsx
index fac99ca..1aad2da 100644
--- a/src/PortingEmbed/PortingFormContainer.tsx
+++ b/src/PortingEmbed/PortingFormContainer.tsx
@@ -52,7 +52,7 @@ export function PortingFormContainer({
 
     if (error instanceof ApiError) {
       onError(error, {
-        code: error instanceof ApiError ? error.code : 'initializationError',
+        code: error.code,
         porting: subscription?.porting || undefined,
       })
     } else {