expo-icp-frontend-helpers

Helper functions for integrating Expo and ICP frontend. Provides deep linking, iframe detection, and other frontend utilities.

Installation

1npm install expo-icp-frontend-helpers

Dependencies

This package requires the following dependencies:

• canister-manager (>=0.1.7) as peer dependency
• @higayasuo/u8a-utils (>=0.1.0) as dependency

Make sure they are installed in your project:

1npm install canister-manager@^0.1.7

Features

Path Manipulation

normalizePath

1import { normalizePath } from 'expo-icp-frontend-helpers';
2
3// Example usage
4const normalizedPath = normalizePath('aaa/bbb/'); // '/aaa/bbb/'
5const normalizedPath2 = normalizePath('///aaa///bbb///'); // '/aaa/bbb/'
6const normalizedPath3 = normalizePath(''); // '/'

Normalizes a path by:

• Ensuring it starts with a slash
• Preserving trailing slashes
• Handling multiple consecutive slashes
• Handling empty paths (returns '/')

comparePaths

1import { comparePaths } from 'expo-icp-frontend-helpers';
2
3// Example usage
4const isEqual = comparePaths('aaa/bbb/', '/aaa/bbb'); // false
5const isEqual2 = comparePaths('///aaa///bbb', '/aaa/bbb'); // true
6const isEqual3 = comparePaths('aaa/bbb', 'aaa/ccc'); // false

Compares two paths after normalizing them. Returns true if the paths are equal after normalization. Note that paths with different trailing slashes are considered different paths.

concatPaths

1import { concatPaths } from 'expo-icp-frontend-helpers';
2
3// Example usage
4const path = concatPaths('aaa', 'bbb', 'ccc'); // '/aaa/bbb/ccc'
5const path2 = concatPaths('/aaa', 'bbb/', 'ccc'); // '/aaa/bbb/ccc'
6const path3 = concatPaths('aaa', '', 'bbb'); // '/aaa/bbb'
7const path4 = concatPaths(); // '/'

Concatenates multiple paths into a single normalized path. Handles:

• Multiple paths
• Leading and trailing slashes
• Multiple consecutive slashes
• Empty paths
• Root path
• No paths (returns '/')

Identity Management

buildIdentity

Builds a delegation identity from an app key and delegation chain, with security checks.

1import { buildIdentity } from 'expo-icp-frontend-helpers';
2import { Ed25519KeyIdentity, DelegationChain } from '@dfinity/identity';
3
4const identity = await buildIdentity({
5  appKey: Ed25519KeyIdentity.generate(),
6  delegationChain: await DelegationChain.create(
7    delegationKey,
8    appKey.getPublicKey(),
9    expirationDate,
10  ),
11});

The function performs the following security checks:

• Validates the delegation chain is not expired
• Verifies the app key matches the public key in the delegation chain

Throws an error with a clear message if:

• Authentication has expired (please log in again) - AuthenticationExpiredError
• The app key does not match the delegation chain's public key - SessionKeyMismatchError

Example error handling:

1import { isAuthenticationExpiredError, isSessionKeyMismatchError } from 'expo-icp-frontend-helpers';
2
3// Example of handling authentication expiration
4async function handleIdentity() {
5  try {
6    const identity = await buildIdentity({ appKey, delegationChain });
7    // Use the identity for authenticated operations
8    return identity;
9  } catch (error) {
10    if (isAuthenticationExpiredError(error)) {
11      // Clear any stored authentication data
12      await clearStoredAuthData();
13
14      // Show a user-friendly message
15      showToast('Your session has expired. Please log in again.');
16
17      // Redirect to login page
18      navigateToLogin();
19
20      // Optionally, you can return null or throw a different error
21      return null;
22    } else if (isSessionKeyMismatchError(error)) {
23      // Handle session key mismatch
24      // e.g., clear session and redirect to login
25    } else {
26      // Handle other errors
27      throw error;
28    }
29  }
30}
31
32// Example helper functions
33async function clearStoredAuthData() {
34  // Clear local storage or secure storage
35  await AsyncStorage.removeItem('authData');
36  await AsyncStorage.removeItem('delegationChain');
37}
38
39function showToast(message: string) {
40  // Show toast using your preferred toast library
41  Toast.show({
42    type: 'error',
43    text1: 'Authentication Error',
44    text2: message,
45  });
46}
47
48function navigateToLogin() {
49  // Navigate to login screen using your navigation library
50  navigation.navigate('Login');
51}

Deep Link Management

DeepLinkType

1import { DeepLinkType } from 'expo-icp-frontend-helpers';
2
3// Example usage
4const linkType = DeepLinkType.ICP;

Available types:

• 'icp': For ICP canister URLs
• 'dev-server': For local development server (http://localhost:8081)
• 'expo-go': For Expo Go app (exp://)
• 'legacy': For legacy Expo deep links
• 'modern': For modern Expo deep links (HTTPS only)

isDeepLinkType

1import { isDeepLinkType } from 'expo-icp-frontend-helpers';
2
3// Example usage
4const isValid = isDeepLinkType('icp'); // true
5const isInvalid = isDeepLinkType('unknown'); // false

Validates if a given string is a valid DeepLinkType.

getDeepLinkType

1import { getDeepLinkType } from 'expo-icp-frontend-helpers';
2
3// Example usage
4const linkType = await getDeepLinkType({
5  easDeepLinkType: 'modern',
6  deepLink: 'https://example.com',
7  frontendCanisterId: 'abc123',
8});

Determines the deep link type based on:

• URL scheme (exp://, http://localhost:8081)
• Frontend canister ID presence
• EAS deep link type (legacy or modern)

buildDeepLink

1import { buildDeepLink } from 'expo-icp-frontend-helpers';
2
3// Example usage
4const url = buildDeepLink({
5  deepLinkType: 'icp',
6  localIPAddress: '192.168.1.1',
7  dfxNetwork: 'local',
8  frontendCanisterId: 'abc123',
9  expoScheme: 'myapp',
10  pathname: '/home'
11});
12console.log(url.toString()); // 'https://abc123.ic0.app/home'
13console.log(url.pathname); // '/home'
14
15// With expo-go deep link
16const expoUrl = buildDeepLink({
17  deepLinkType: 'expo-go',
18  localIPAddress: '192.168.1.1',
19  dfxNetwork: 'local',
20  frontendCanisterId: 'abc123',
21  expoScheme: 'myapp',
22  pathname: '/users/profile'
23});
24console.log(expoUrl.toString()); // 'exp://192.168.1.1:8081/--/users/profile'
25console.log(expoUrl.pathname); // '/--/users/profile'

Builds a deep link URL based on the provided configuration. Features:

• Returns a URL object for flexible URL manipulation
• Handles different deep link types (icp, dev-server, expo-go, legacy, modern)
• Supports custom pathnames
• Special handling for expo-go deep links (adds /--/ prefix)
• Type-safe parameters using TypeScript generics
• Throws clear errors for unsupported types or invalid configurations

buildDeepLinkBaseURL

1import { buildDeepLinkBaseURL } from 'expo-icp-frontend-helpers';
2
3// Example usage
4const baseUrl = buildDeepLinkBaseURL({
5  deepLinkType: 'icp',
6  localIPAddress: '192.168.1.1',
7  frontendCanisterURL: 'https://abc123.ic0.app',
8  expoScheme: 'myapp'
9});
10console.log(baseUrl.toString()); // 'https://abc123.ic0.app'

Builds the base URL for a deep link based on its type. Features:

• Returns a URL object for flexible URL manipulation
• Handles different deep link types
• Special handling for expo-go deep links (includes /--/ in base URL)
• Type-safe parameters using TypeScript generics
• Throws clear errors for unsupported types or invalid configurations

URL Parsing

updateParams

1import { updateParams } from 'expo-icp-frontend-helpers';
2
3// Example usage
4const params = new URLSearchParams();
5updateParams(params, { userId: '123', userName: 'john' });
6console.log(params.toString()); // 'user-id=123&user-name=john'
7
8// With undefined values
9const params2 = new URLSearchParams();
10updateParams(params2, { id: '123', name: undefined });
11console.log(params2.toString()); // 'id=123'
12
13// With numbers
14const params3 = new URLSearchParams();
15updateParams(params3, { userId: 123 });
16console.log(params3.toString()); // 'user-id=123'
17
18// With boolean values
19const params4 = new URLSearchParams();
20updateParams(params4, { isActive: true });
21console.log(params4.toString()); // 'is-active=true'
22
23// With special characters
24const params5 = new URLSearchParams();
25updateParams(params5, { query: 'hello world' });
26console.log(params5.toString()); // 'query=hello+world'
27
28// With multiple words in camelCase
29const params6 = new URLSearchParams();
30updateParams(params6, { userProfileId: '123' });
31console.log(params6.toString()); // 'user-profile-id=123'

Updates a URLSearchParams object with values from the given object. Features:

• Converts camelCase keys to kebab-case
• Handles undefined values (skips them)
• Converts numbers and booleans to strings
• Handles special characters in values
• Supports multiple words in camelCase keys
• Type-safe parameters using TypeScript generics

parseParams