expo-linking 2.4.2 → 3.2.0

package/src/Linking.ts

@@ -3,10 +3,17 @@ import { Platform, UnavailabilityError } from 'expo-modules-core';
 import invariant from 'invariant';
 import qs from 'qs';
 import { useEffect, useState } from 'react';
+import { EmitterSubscription } from 'react-native';
 import URL from 'url-parse';
 
 import NativeLinking from './ExpoLinking';
-import { CreateURLOptions, ParsedURL, QueryParams, URLListener } from './Linking.types';
+import {
+  CreateURLOptions,
+  ParsedURL,
+  QueryParams,
+  SendIntentExtras,
+  URLListener,
+} from './Linking.types';
 import { hasCustomScheme, resolveScheme } from './Schemes';
 
 function validateURL(url: string): void {
@@ -17,7 +24,11 @@ function validateURL(url: string): void {
 function getHostUri(): string | null {
   if (Constants.manifest?.hostUri) {
     return Constants.manifest.hostUri;
+    // @ts-ignore: hostUri isn't defined on the expoClient type, because
+    // Constants.manifest is of type AppManifest while
+    // Constants.manifest2.extra.expoClient is of type ExpoConfig
   } else if (Constants.manifest2?.extra?.expoClient?.hostUri) {
+    // @ts-ignore
     return Constants.manifest2.extra.expoClient.hostUri;
   } else if (!hasCustomScheme()) {
     // we're probably not using up-to-date xdl, so just fake it for now
@@ -33,7 +44,8 @@ function isExpoHosted(): boolean {
   return !!(
     hostUri &&
     (/^(.*\.)?(expo\.io|exp\.host|exp\.direct|expo\.test)(:.*)?(\/.*)?$/.test(hostUri) ||
-      Constants.manifest?.developer)
+      Constants.manifest?.developer ||
+      Constants.manifest2?.extra?.expoGo?.developer)
   );
 }
 
@@ -73,12 +85,12 @@ function ensureLeadingSlash(input: string, shouldAppend: boolean): string {
   return input;
 }
 
+// @needsAudit
 /**
  * Create a URL that works for the environment the app is currently running in.
  * The scheme in bare and standalone must be defined in the app.json under `expo.scheme`.
  *
- * **Examples**
- *
+ * # Examples
  * - Bare: empty string
  * - Standalone, Custom: `yourscheme:///path`
  * - Web (dev): `https://localhost:19006/path`
@@ -87,28 +99,38 @@ function ensureLeadingSlash(input: string, shouldAppend: boolean): string {
  * - Expo Client (prod): `exp://exp.host/@yourname/your-app/--/path`
  *
  * @param path addition path components to append to the base URL.
- * @param queryParams An object of parameters that will be converted into a query string.
+ * @param queryParams An object with a set of query parameters. These will be merged with any
+ * Expo-specific parameters that are needed (e.g. release channel) and then appended to the URL
+ * as a query string.
+ * @param scheme Optional URI protocol to use in the URL `<scheme>:///`, when `undefined` the scheme
+ * will be chosen from the Expo config (`app.config.js` or `app.json`).
+ * @return A URL string which points to your app with the given deep link information.
+ * @deprecated An alias for [`createURL()`](#linkingcreateurlpath-namedparameters). This method is
+ * deprecated and will be removed in a future SDK version.
  */
 export function makeUrl(path: string = '', queryParams?: QueryParams, scheme?: string): string {
   return createURL(path, { queryParams, scheme, isTripleSlashed: true });
 }
 
+// @needsAudit
 /**
- * Create a URL that works for the environment the app is currently running in.
- * The scheme in bare and standalone must be defined in the Expo config (app.config.js or app.json) under `expo.scheme`.
+ * Helper method for constructing a deep link into your app, given an optional path and set of query
+ * parameters. Creates a URI scheme with two slashes by default.
  *
- * **Examples**
+ * The scheme in bare and standalone must be defined in the Expo config (`app.config.js` or `app.json`)
+ * under `expo.scheme`.
  *
- * - Bare: `<scheme>://path` -- uses provided scheme or scheme from Expo config `scheme`.
+ * # Examples
+ * - Bare: `<scheme>://path` - uses provided scheme or scheme from Expo config `scheme`.
  * - Standalone, Custom: `yourscheme://path`
  * - Web (dev): `https://localhost:19006/path`
  * - Web (prod): `https://myapp.com/path`
  * - Expo Client (dev): `exp://128.0.0.1:19000/--/path`
  * - Expo Client (prod): `exp://exp.host/@yourname/your-app/--/path`
  *
- * @param path addition path components to append to the base URL.
- * @param scheme URI protocol `<scheme>://` that must be built into your native app.
- * @param queryParams An object of parameters that will be converted into a query string.
+ * @param path Addition path components to append to the base URL.
+ * @param namedParameters Additional options object.
+ * @return A URL string which points to your app with the given deep link information.
  */
 export function createURL(
   path: string,
@@ -161,7 +183,7 @@ export function createURL(
       if (typeof parsedParams === 'object') {
         paramsFromHostUri = parsedParams;
       }
-    } catch (e) {}
+    } catch {}
     queryParams = {
       ...queryParams,
       ...paramsFromHostUri,
@@ -179,10 +201,11 @@ export function createURL(
   );
 }
 
+// @needsAudit
 /**
- * Returns the components and query parameters for a given URL.
- *
- * @param url Input URL to parse
+ * Helper method for parsing out deep link information from a URL.
+ * @param url A URL that points to the currently running experience (e.g. an output of `Linking.createURL()`).
+ * @return A `ParsedURL` object.
  */
 export function parse(url: string): ParsedURL {
   validateURL(url);
@@ -231,28 +254,40 @@ export function parse(url: string): ParsedURL {
   };
 }
 
+// @needsAudit
 /**
- * Add a handler to Linking changes by listening to the `url` event type
- * and providing the handler
- *
- * See https://reactnative.dev/docs/linking.html#addeventlistener
+ * Add a handler to `Linking` changes by listening to the `url` event type and providing the handler.
+ * It is recommended to use the [`useURL()`](#useurl) hook instead.
+ * @param type The only valid type is `'url'`.
+ * @param handler An [`URLListener`](#urllistener) function that takes an `event` object of the type
+ * [`EventType`](#eventype).
+ * @return An EmitterSubscription that has the remove method from EventSubscription
+ * @see [React Native Docs Linking page](https://reactnative.dev/docs/linking#addeventlistener).
  */
-export function addEventListener(type: string, handler: URLListener) {
-  NativeLinking.addEventListener(type, handler);
+export function addEventListener(type: 'url', handler: URLListener): EmitterSubscription {
+  return NativeLinking.addEventListener(type, handler);
 }
 
 /**
  * Remove a handler by passing the `url` event type and the handler.
+ * @param type The only valid type is `'url'`.
+ * @param handler An [`URLListener`](#urllistener) function that takes an `event` object of the type
+ * [`EventType`](#eventype).
+ * @see [React Native Docs Linking page](https://reactnative.dev/docs/linking#removeeventlistener).
  *
- * See https://reactnative.dev/docs/linking.html#removeeventlistener
+ * @deprecated Call `remove()` on the return value of `addEventListener()` instead.
  */
-export function removeEventListener(type: string, handler: URLListener) {
+export function removeEventListener(type: 'url', handler: URLListener): void {
   NativeLinking.removeEventListener(type, handler);
 }
 
+// @needsAudit
 /**
- * **Native:** Parses the link that opened the app. If no link opened the app, all the fields will be \`null\`.
- * **Web:** Parses the current window URL.
+ * Helper method which wraps React Native's `Linking.getInitialURL()` in `Linking.parse()`.
+ * Parses the deep link information out of the URL used to open the experience initially.
+ * If no link opened the app, all the fields will be `null`.
+ * > On the web it parses the current window URL.
+ * @return A promise that resolves with `ParsedURL` object.
  */
 export async function parseInitialURLAsync(): Promise<ParsedURL> {
   const initialUrl = await NativeLinking.getInitialURL();
@@ -268,25 +303,23 @@ export async function parseInitialURLAsync(): Promise<ParsedURL> {
   return parse(initialUrl);
 }
 
+// @needsAudit
 /**
- * Launch an Android intent with optional extras
- *
+ * Launch an Android intent with extras.
+ * > Use [IntentLauncher](./intent-launcher) instead, `sendIntent` is only included in
+ * > `Linking` for API compatibility with React Native's Linking API.
  * @platform android
  */
-export async function sendIntent(
-  action: string,
-  extras?: { key: string; value: string | number | boolean }[]
-): Promise<void> {
+export async function sendIntent(action: string, extras?: SendIntentExtras[]): Promise<void> {
   if (Platform.OS === 'android') {
     return await NativeLinking.sendIntent(action, extras);
   }
   throw new UnavailabilityError('Linking', 'sendIntent');
 }
 
+// @needsAudit
 /**
- * Attempt to open the system settings for an the app.
- *
- * @platform ios
+ * Open the operating system settings app and displays the app’s custom settings, if it has any.
  */
 export async function openSettings(): Promise<void> {
   if (Platform.OS === 'web') {
@@ -298,33 +331,49 @@ export async function openSettings(): Promise<void> {
   await openURL('app-settings:');
 }
 
+// @needsAudit
 /**
- * If the app launch was triggered by an app link,
- * it will give the link url, otherwise it will give `null`
+ * Get the URL that was used to launch the app if it was launched by a link.
+ * @return The URL string that launched your app, or `null`.
  */
 export async function getInitialURL(): Promise<string | null> {
   return (await NativeLinking.getInitialURL()) ?? null;
 }
 
+// @needsAudit
 /**
- * Try to open the given `url` with any of the installed apps.
+ * Attempt to open the given URL with an installed app. See the [Linking guide](/guides/linking)
+ * for more information.
+ * @param url A URL for the operating system to open, eg: `tel:5555555`, `exp://`.
+ * @return A `Promise` that is fulfilled with `true` if the link is opened operating system
+ * automatically or the user confirms the prompt to open the link. The `Promise` rejects if there
+ * are no applications registered for the URL or the user cancels the dialog.
  */
 export async function openURL(url: string): Promise<true> {
   validateURL(url);
   return await NativeLinking.openURL(url);
 }
 
+// @needsAudit
 /**
  * Determine whether or not an installed app can handle a given URL.
- * On web this always returns true because there is no API for detecting what URLs can be opened.
+ * On web this always returns `true` because there is no API for detecting what URLs can be opened.
+ * @param url The URL that you want to test can be opened.
+ * @return A `Promise` object that is fulfilled with `true` if the URL can be handled, otherwise it
+ * `false` if not.
+ *
+ * The `Promise` will reject on Android if it was impossible to check if the URL can be opened, and
+ * on iOS if you didn't [add the specific scheme in the `LSApplicationQueriesSchemes` key inside **Info.plist**](/guides/linking#opening-links-to-other-apps).
  */
 export async function canOpenURL(url: string): Promise<boolean> {
   validateURL(url);
   return await NativeLinking.canOpenURL(url);
 }
 
+// @needsAudit
 /**
  * Returns the initial URL followed by any subsequent changes to the URL.
+ * @return Returns the initial URL or `null`.
  */
 export function useURL(): string | null {
   const [url, setLink] = useState<string | null>(null);
@@ -335,22 +384,12 @@ export function useURL(): string | null {
 
   useEffect(() => {
     getInitialURL().then((url) => setLink(url));
-    addEventListener('url', onChange);
-    return () => removeEventListener('url', onChange);
+    const subscription = addEventListener('url', onChange);
+    return () => subscription.remove();
   }, []);
 
   return url;
 }
 
-/**
- * Returns the initial URL followed by any subsequent changes to the URL.
- * @deprecated Use `useURL` instead.
- */
-export function useUrl(): string | null {
-  console.warn(
-    `Linking.useUrl has been deprecated in favor of Linking.useURL. This API will be removed in SDK 44.`
-  );
-  return useURL();
-}
-
 export * from './Linking.types';
+export * from './Schemes';

package/src/Linking.types.ts

@@ -1,14 +1,23 @@
 import { ParsedQs } from 'qs';
 
+// @docsMissing
 export type QueryParams = ParsedQs;
 
+// @needsAudit @docsMissing
 export type ParsedURL = {
   scheme: string | null;
   hostname: string | null;
+  /**
+   * The path into the app specified by the URL.
+   */
   path: string | null;
+  /**
+   * The set of query parameters specified by the query string of the url used to open the app.
+   */
   queryParams: QueryParams | null;
 };
 
+// @needsAudit
 export type CreateURLOptions = {
   /**
    * URI protocol `<scheme>://` that must be built into your native app.
@@ -24,8 +33,17 @@ export type CreateURLOptions = {
   isTripleSlashed?: boolean;
 };
 
-export type EventType = { url: string; nativeEvent?: MessageEvent };
+// @docsMissing
+export type EventType = {
+  url: string;
+  nativeEvent?: MessageEvent;
+};
 
+// @docsMissing
 export type URLListener = (event: EventType) => void;
 
+// @docsMissing
 export type NativeURLListener = (nativeEvent: MessageEvent) => void;
+
+// @docsMissing
+export type SendIntentExtras = { key: string; value: string | number | boolean };

package/src/Schemes.ts

@@ -1,8 +1,9 @@
 import Constants, { ExecutionEnvironment } from 'expo-constants';
 import { Platform } from 'expo-modules-core';
 
-const LINKING_GUIDE_URL = `https://docs.expo.io/guides/linking/`;
+const LINKING_GUIDE_URL = `https://docs.expo.dev/guides/linking/`;
 
+// @docsMissing
 export function hasCustomScheme(): boolean {
   if (Constants.executionEnvironment === ExecutionEnvironment.Bare) {
     // Bare always uses a custom scheme.
@@ -101,21 +102,25 @@ function getNativeAppIdScheme(): string | null {
   );
 }
 
+// @needsAudit
+/**
+ * Ensure the user has linked the expo-constants manifest in bare workflow.
+ */
 export function hasConstantsManifest(): boolean {
-  // Ensure the user has linked the expo-constants manifest in bare workflow.
   return (
     !!Object.keys(Constants.manifest ?? {}).length ||
     !!Object.keys(Constants.manifest2 ?? {}).length
   );
 }
 
-export function resolveScheme(props: { scheme?: string; isSilent?: boolean }): string {
+// @docsMissing
+export function resolveScheme(options: { scheme?: string; isSilent?: boolean }): string {
   if (
     Constants.executionEnvironment !== ExecutionEnvironment.StoreClient &&
     !hasConstantsManifest()
   ) {
     throw new Error(
-      `expo-linking needs access to the expo-constants manifest (app.json or app.config.js) to determine what URI scheme to use. Setup the manifest and rebuild: https://github.com/expo/expo/blob/master/packages/expo-constants/README.md`
+      `expo-linking needs access to the expo-constants manifest (app.json or app.config.js) to determine what URI scheme to use. Setup the manifest and rebuild: https://github.com/expo/expo/blob/main/packages/expo-constants/README.md`
     );
   }
 
@@ -123,7 +128,7 @@ export function resolveScheme(props: { scheme?: string; isSilent?: boolean }): s
   const nativeAppId = getNativeAppIdScheme();
 
   if (!manifestSchemes.length) {
-    if (__DEV__ && !props.isSilent) {
+    if (__DEV__ && !options.isSilent) {
       // Assert a config warning if no scheme is setup yet. `isSilent` is used for warnings, but we'll ignore it for exceptions.
       console.warn(
         `Linking requires a build-time setting \`scheme\` in the project's Expo config (app.config.js or app.json) for production apps, if it's left blank, your app may crash. The scheme does not apply to development in the Expo client but you should add it as soon as you start working with Linking to avoid creating a broken build. Learn more: ${LINKING_GUIDE_URL}`
@@ -138,10 +143,10 @@ export function resolveScheme(props: { scheme?: string; isSilent?: boolean }): s
 
   // In the Expo client...
   if (Constants.executionEnvironment === ExecutionEnvironment.StoreClient) {
-    if (props.scheme) {
+    if (options.scheme) {
       // This enables users to use the fb or google redirects on iOS in the Expo client.
-      if (EXPO_CLIENT_SCHEMES.includes(props.scheme)) {
-        return props.scheme;
+      if (EXPO_CLIENT_SCHEMES.includes(options.scheme)) {
+        return options.scheme;
       }
       // Silently ignore to make bare workflow development easier.
     }
@@ -151,15 +156,15 @@ export function resolveScheme(props: { scheme?: string; isSilent?: boolean }): s
 
   const schemes = [...manifestSchemes, nativeAppId].filter(Boolean);
 
-  if (props.scheme) {
+  if (options.scheme) {
     if (__DEV__) {
       // Bare workflow development assertion about the provided scheme matching the Expo config.
-      if (!schemes.includes(props.scheme) && !props.isSilent) {
+      if (!schemes.includes(options.scheme) && !options.isSilent) {
         // TODO: Will this cause issues for things like Facebook or Google that use `reversed-client-id://` or `fb<FBID>:/`?
         // Traditionally these APIs don't use the Linking API directly.
         console.warn(
           `The provided Linking scheme '${
-            props.scheme
+            options.scheme
           }' does not appear in the list of possible URI schemes in your Expo config. Expected one of: ${schemes
             .map((scheme) => `'${scheme}'`)
             .join(', ')}`
@@ -167,7 +172,7 @@ export function resolveScheme(props: { scheme?: string; isSilent?: boolean }): s
       }
     }
     // Return the user provided value.
-    return props.scheme;
+    return options.scheme;
   }
   // If no scheme is provided, we'll guess what the scheme is based on the manifest.
   // This is to attempt to keep managed apps working across expo build and EAS build.
@@ -175,7 +180,7 @@ export function resolveScheme(props: { scheme?: string; isSilent?: boolean }): s
   // be using one of defined schemes.
 
   // If the native app id is the only scheme,
-  if (!!nativeAppId && !manifestSchemes.length && !props.isSilent) {
+  if (!!nativeAppId && !manifestSchemes.length && !options.isSilent) {
     // Assert a config warning if no scheme is setup yet.
     // This warning only applies to managed workflow EAS apps, as bare workflow
     console.warn(
@@ -195,7 +200,7 @@ export function resolveScheme(props: { scheme?: string; isSilent?: boolean }): s
     // Throw in production, use the __DEV__ flag so users can test this functionality with `expo start --no-dev`
     throw new Error(errorMessage);
   }
-  if (extraSchemes.length && !props.isSilent) {
+  if (extraSchemes.length && !options.isSilent) {
     console.warn(
       `Linking found multiple possible URI schemes in your Expo config.\nUsing '${scheme}'. Ignoring: ${[
         ...extraSchemes,