From f4b48e6db199cae4e880202c28974b481890b7c6 Mon Sep 17 00:00:00 2001 From: Ruben Izmailyan Date: Thu, 14 Nov 2024 08:30:46 -0600 Subject: [PATCH] Improve documentation and typings (#293) * Improve Type documentation * Improve React Native docs * Fix type errors * Add changeset --------- Co-authored-by: zubairaziz --- .changeset/wet-icons-serve.md | 7 +++ packages/core/src/api/browser.ts | 55 +++++++++++++++++-- packages/react-native/README.md | 18 +++--- .../src/providers/QuilttAuthProvider.tsx | 3 +- .../react/src/providers/QuilttProvider.tsx | 2 + .../src/providers/QuilttSettingsProvider.tsx | 1 + 6 files changed, 73 insertions(+), 13 deletions(-) create mode 100644 .changeset/wet-icons-serve.md diff --git a/.changeset/wet-icons-serve.md b/.changeset/wet-icons-serve.md new file mode 100644 index 00000000..1dc84879 --- /dev/null +++ b/.changeset/wet-icons-serve.md @@ -0,0 +1,7 @@ +--- +"@quiltt/react-native": patch +"@quiltt/react": patch +"@quiltt/core": patch +--- + +Improve documentation diff --git a/packages/core/src/api/browser.ts b/packages/core/src/api/browser.ts index 63e46819..fa327268 100644 --- a/packages/core/src/api/browser.ts +++ b/packages/core/src/api/browser.ts @@ -45,46 +45,93 @@ export type ConnectorSDKCallbacks = { onExitError?: ConnectorSDKOnExitErrorCallback } +/** + * Callback function to handle all events from the Connector. + * @param type The type of event that was emitted + * @param metadata Metadata about the event that was emitted + */ export type ConnectorSDKOnEventCallback = ( + /** The type of event that was emitted */ type: ConnectorSDKEventType, + /** The metadata from the event */ metadata: ConnectorSDKCallbackMetadata ) => void +/** Callback function to handle the Open event */ export type ConnectorSDKOnOpenCallback = (metadata: ConnectorSDKCallbackMetadata) => void + +/** Callback function to handle the Load event */ export type ConnectorSDKOnLoadCallback = (metadata: ConnectorSDKCallbackMetadata) => void +/** Callback function to handle all Exit events */ export type ConnectorSDKOnEventExitCallback = ( type: ConnectorSDKEventType, metadata: ConnectorSDKCallbackMetadata ) => void +/** Callback function to handle the ExitSuccess event */ export type ConnectorSDKOnExitSuccessCallback = (metadata: ConnectorSDKCallbackMetadata) => void + +/** Callback function to handle the ExitAbort event */ export type ConnectorSDKOnExitAbortCallback = (metadata: ConnectorSDKCallbackMetadata) => void + +/** Callback function to handle the ExitError event */ export type ConnectorSDKOnExitErrorCallback = (metadata: ConnectorSDKCallbackMetadata) => void +/** + * Enum representing the different types of events emitted by the Connector. + */ export enum ConnectorSDKEventType { + /** The Connector modal has been opened */ Open = 'opened', + + /** The Connector has loaded successfully */ Load = 'loaded', + + /** The end-user successfully completed the flow */ ExitSuccess = 'exited.successful', + + /** The end-user exited the Connector before completing the flow */ ExitAbort = 'exited.aborted', + + /** The end-user experienced an error during the flow */ ExitError = 'exited.errored', } +/** + * Metadata about a Connector event + * @param connectorId The ID of the Connector that emitted the event + * @param profileId The ID of the authenticated Profile + * @param connectionId The ID of the Connection that was created or reconnected + */ export type ConnectorSDKCallbackMetadata = { + /** The ID of the Connector that emitted the event */ connectorId: string + /** The ID of the authenticated Profile */ profileId?: string + /** The ID of the Connection that was created or reconnected */ connectionId?: string } +/** + Options for the standard Connect flow + @param institution The Institution search term or ID to preload +*/ export type ConnectorSDKConnectOptions = ConnectorSDKCallbacks & { + /** The Institution search term or ID to preload */ institution?: string + /** The ID of the Connection to reconnect */ + connectionId?: string } +/** + * Options for the Reconnect flow + * @param connectionId The ID of the Connection to reconnect + */ export type ConnectorSDKReconnectOptions = ConnectorSDKCallbacks & { + /** The ID of the Connection to reconnect */ connectionId: string } -export type ConnectorSDKConnectorOptions = ConnectorSDKCallbacks & { - institution?: string - connectionId?: string -} +/** Options to initialize Connector */ +export type ConnectorSDKConnectorOptions = ConnectorSDKConnectOptions | ConnectorSDKConnectOptions diff --git a/packages/react-native/README.md b/packages/react-native/README.md index 9d81416e..1f98309c 100644 --- a/packages/react-native/README.md +++ b/packages/react-native/README.md @@ -21,35 +21,37 @@ $ pnpm add base-64 react-native-webview react-native-url-polyfill $ pnpm add @quiltt/react-native ``` +## Documentation +For SDK documentation and more code examples, see the [React Native guide](https://www.quiltt.dev/connector/sdk/react-native). + ### QuilttConnector Launch the [Quiltt Connector](https://www.quiltt.dev/connector) in a webview. -`@quiltt/react-native` does not include any navigation library, you might want to navigate to a new "page" when using QuilttConnector to get the best result. - -For simple usage of `react-navigation`, please see [App.tsx](../../examples/react-native-expo/App.tsx) and [ConnectorScreen.tsx](../../examples/react-native-expo/screens/ConnectorScreen.tsx). +`@quiltt/react-native` does not ship with a navigation library, so you might want to navigate to a new "page" when using QuilttConnector. #### Example ```tsx -import { useState } from 'react' import { QuilttProvider } from '@quiltt/react' import { QuilttConnector } from '@quiltt/react-native' export const App = () => { // See: https://www.quiltt.dev/authentication/issuing-session-tokens - const token = 'GET_THIS_TOKEN_FROM_YOUR_SERVER' - const [connectionId, setConnectionId] = useState() + const sessionToken = '' const oAuthRedirectUrl = 'quilttexample://open.reactnative.app' + const handleExitSuccess = (metadata) => { - setConnectionId(metadata?.connectionId) + console.log('Successfully created connection!', metadata) } return ( - + diff --git a/packages/react/src/providers/QuilttAuthProvider.tsx b/packages/react/src/providers/QuilttAuthProvider.tsx index 2c0c0d4b..a765fe84 100644 --- a/packages/react/src/providers/QuilttAuthProvider.tsx +++ b/packages/react/src/providers/QuilttAuthProvider.tsx @@ -8,10 +8,11 @@ import { InMemoryCache, QuilttClient } from '@quiltt/core' import { useQuilttSession } from '../hooks' type QuilttAuthProviderProps = PropsWithChildren & { + /** The Session token obtained from the server */ token?: string } -const GraphQLClient = new QuilttClient({ +export const GraphQLClient = new QuilttClient({ cache: new InMemoryCache(), }) diff --git a/packages/react/src/providers/QuilttProvider.tsx b/packages/react/src/providers/QuilttProvider.tsx index 1bbf56b2..94a7616a 100644 --- a/packages/react/src/providers/QuilttProvider.tsx +++ b/packages/react/src/providers/QuilttProvider.tsx @@ -4,7 +4,9 @@ import { QuilttAuthProvider } from './QuilttAuthProvider' import { QuilttSettingsProvider } from './QuilttSettingsProvider' type QuilttProviderProps = PropsWithChildren & { + /** The client ID for the client-side Auth API */ clientId?: string + /** The Session token obtained from the server */ token?: string } diff --git a/packages/react/src/providers/QuilttSettingsProvider.tsx b/packages/react/src/providers/QuilttSettingsProvider.tsx index 43358de8..d28490aa 100644 --- a/packages/react/src/providers/QuilttSettingsProvider.tsx +++ b/packages/react/src/providers/QuilttSettingsProvider.tsx @@ -6,6 +6,7 @@ import { useState } from 'react' import { QuilttSettings } from '../hooks' type QuilttSettingsProviderProps = PropsWithChildren & { + /** The Client ID to use for the client-side Auth API */ clientId?: string }