Improve documentation and typings (#293)

* Improve Type documentation

* Improve React Native docs

* Fix type errors

* Add changeset

---------

Co-authored-by: zubairaziz <[email protected]>

.changeset/wet-icons-serve.md

@@ -0,0 +1,7 @@
+---
+"@quiltt/react-native": patch
+"@quiltt/react": patch
+"@quiltt/core": patch
+---
+
+Improve documentation

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

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<string>()
+  const sessionToken = '<TOKEN_OBTAINED_FROM_THE_SERVER>'
   const oAuthRedirectUrl = 'quilttexample://open.reactnative.app'
+
   const handleExitSuccess = (metadata) => {
-    setConnectionId(metadata?.connectionId)
+    console.log('Successfully created connection!', metadata)
   }
 
   return (
-    <QuilttProvider token={token}>
+    <QuilttProvider token={sessionToken}>
       <QuilttConnector
         connectorId="<CONNECTOR_ID>"
         oAuthRedirectUrl={oAuthRedirectUrl}
+
+        // See the JavaScript API docs for the full list of available callbacks
         onExitSuccess={handleExitSuccess}
       />
     </QuilttProvider>

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(),
 })
 

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
 }
 

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
 }