chore: add comments

Author: gao-sun

packages/rn-sample/App.tsx

@@ -6,6 +6,7 @@ import { StatusBar } from 'expo-status-bar';
 import { useEffect, useState } from 'react';
 import { Button, StyleSheet, Text, View } from 'react-native';
 
+// Replace with your own redirect URI
 const redirectUri = 'io.logto://callback';
 
 const Content = () => {
@@ -49,8 +50,8 @@ const App = () => {
   return (
     <LogtoProvider
       config={{
-        endpoint: 'http://localhost:3002/',
-        appId: 's5sc0ktp6fs0a8rwqod6h',
+        endpoint: 'https://<your-logto-endpoint>',
+        appId: '<your-app-id>',
       }}
     >
       <Content />

packages/rn-sample/babel.config.js

@@ -1,4 +1,4 @@
-module.exports = function(api) {
+module.exports = function (api) {
   api.cache(true);
   return {
     presets: ['babel-preset-expo'],

packages/rn-sample/index.js

@@ -6,7 +6,7 @@ import { registerRootComponent } from 'expo';
 
 import App from './App';
 
-// registerRootComponent calls AppRegistry.registerComponent('main', () => App);
+// `registerRootComponent` calls `AppRegistry.registerComponent('main', () => App);`
 // It also ensures that whether you load the app in Expo Go or in a native build,
 // the environment is set up appropriately
 registerRootComponent(App);

packages/rn-sample/metro.config.js

@@ -2,8 +2,9 @@
  * @fileoverview https://docs.expo.dev/guides/monorepos/#modify-the-metro-config
  */
 
+const path = require('node:path');
+
 const { getDefaultConfig } = require('expo/metro-config');
-const path = require('path');
 
 // Find the project and workspace directories
 const projectRoot = __dirname;

packages/rn/package.json

@@ -1,5 +1,8 @@
 {
   "name": "@logto/rn",
+  "publishConfig": {
+    "access": "public"
+  },
   "version": "0.1.0",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -45,9 +48,6 @@
     "extends": "@silverhand/react"
   },
   "prettier": "@silverhand/eslint-config/.prettierrc",
-  "publishConfig": {
-    "access": "public"
-  },
   "dependencies": {
     "@logto/client": "3.0.0-alpha.2",
     "@logto/js": "4.0.0-alpha.2",

packages/rn/src/client.ts

@@ -62,7 +62,7 @@ export class LogtoClient extends StandardLogtoClient {
               break;
             }
             default: {
-              throw new LogtoNativeClientError('auth_session_failed');
+              throw new LogtoNativeClientError('navigation_purpose_not_supported');
             }
           }
         },
@@ -97,6 +97,20 @@ export class LogtoClient extends StandardLogtoClient {
     this.storage = storage;
   }
 
+  /**
+   * Start the sign-in flow with the specified redirect URI. The URI must be registered in the
+   * Logto Console. It uses `WebBrowser.openAuthSessionAsync` to open the browser and start the
+   * sign-in flow.
+   *
+   * The user will be redirected to that URI after the sign-in flow is completed, and the client
+   * will handle the callback to exchange the authorization code for the tokens.
+   *
+   * @param redirectUri The redirect URI that the user will be redirected to after the sign-in flow is completed.
+   * @param interactionMode The interaction mode to be used for the authorization request. Note it's not
+   * a part of the OIDC standard, but a Logto-specific extension. Defaults to `signIn`.
+   *
+   * @see {@link InteractionMode}
+   */
   override async signIn(redirectUri: string, interactionMode?: InteractionMode): Promise<void> {
     await super.signIn(redirectUri, interactionMode);
 
@@ -106,4 +120,13 @@ export class LogtoClient extends StandardLogtoClient {
 
     await this.handleSignInCallback(this.authSessionResult.url);
   }
+
+  /**
+   * Revokes all the tokens and cleans up the storage. By default, it will NOT open the browser
+   * to start the sign-out flow for better user experience, and the `postLogoutRedirectUri` will
+   * be ignored.
+   */
+  override async signOut(postLogoutRedirectUri?: string | undefined): Promise<void> {
+    return super.signOut(postLogoutRedirectUri);
+  }
 }

packages/rn/src/errors.ts

@@ -1,5 +1,6 @@
 const logtoNativeClientErrorCodes = Object.freeze({
   auth_session_failed: 'User failed to finish the authentication session.',
+  navigation_purpose_not_supported: 'The navigation purpose is not supported.',
 });
 
 export type LogtoNativeClientErrorCode = keyof typeof logtoNativeClientErrorCodes;

packages/rn/src/hooks.ts

@@ -1,7 +1,14 @@
 import { useCallback, useContext, useMemo } from 'react';
 
+// eslint-disable-next-line unused-imports/no-unused-imports -- use for JSDoc
+import type { LogtoClient } from './client';
 import { LogtoContext } from './context';
 
+/**
+ * A hook to use the Logto client instance, methods, and the authentication state. The
+ * `LogtoContext` must be provided to make this hook work. It's recommended to use the
+ * `LogtoProvider` component to wrap the root component of the app.
+ */
 export const useLogto = () => {
   const { client, isAuthenticated, setIsAuthenticated } = useContext(LogtoContext);
 
@@ -22,17 +29,34 @@ export const useLogto = () => {
 
   const memorized = useMemo(
     () => ({
+      /** The Logto client instance. */
       client,
+      /**
+       * If the user is authenticated.
+       *
+       * NOTE: It only checks the existence of ID token in the storage, so it's not guaranteed that the
+       * tokens are valid.
+       */
       isAuthenticated,
+      /** @see {@link LogtoClient.getRefreshToken} */
       getRefreshToken: client.getRefreshToken.bind(client),
+      /** @see {@link LogtoClient.getAccessToken} */
       getAccessToken: client.getAccessToken.bind(client),
+      /** @see {@link LogtoClient.getAccessTokenClaims} */
       getAccessTokenClaims: client.getAccessTokenClaims.bind(client),
+      /** @see {@link LogtoClient.getOrganizationToken} */
       getOrganizationToken: client.getOrganizationToken.bind(client),
+      /** @see {@link LogtoClient.getOrganizationTokenClaims} */
       getOrganizationTokenClaims: client.getOrganizationTokenClaims.bind(client),
+      /** @see {@link LogtoClient.getIdToken} */
       getIdToken: client.getIdToken.bind(client),
+      /** @see {@link LogtoClient.getIdTokenClaims} */
       getIdTokenClaims: client.getIdTokenClaims.bind(client),
+      /** @see {@link LogtoClient.signIn} */
       signIn,
+      /** @see {@link LogtoClient.signOut} */
       signOut,
+      /** @see {@link LogtoClient.fetchUserInfo} */
       fetchUserInfo: client.fetchUserInfo.bind(client),
     }),
     [client, isAuthenticated, signIn, signOut]

packages/rn/src/polyfill.ts

@@ -1,3 +1,9 @@
+/**
+ * @fileoverview
+ * This file is a polyfill for the `atob` and `btoa` functions. It is required for Logto to work in
+ * Expo managed workflow (also React Native).
+ */
+
 /* eslint-disable @silverhand/fp/no-mutation, @typescript-eslint/no-unnecessary-condition */
 import { btoaPolyfill, atobPolyfill } from 'js-base64';
 

packages/rn/src/provider.tsx

@@ -4,14 +4,15 @@ import { LogtoClient, type LogtoNativeConfig } from './client.js';
 import { LogtoContext } from './context.js';
 
 export type LogtoProviderProps = {
+  /** The configuration for the `LogtoClient`. */
   readonly config: LogtoNativeConfig;
-  /**
-   * Whether to enable cache for well-known data. Use sessionStorage by default.
-   * @default false
-   */
   readonly children?: ReactNode;
 };
 
+/**
+ * A provider component to provide the `LogtoContext` which includes the `LogtoClient` instance
+ * with the given configuration.
+ */
 export const LogtoProvider = ({ config, children }: LogtoProviderProps) => {
   const memorizedLogtoClient = useMemo(() => new LogtoClient(config), [config]);
   const [isAuthenticated, setIsAuthenticated] = useState(false);