@finpassai/react-native-sms-sdk

React Native Android SDK for Finpass SMS Analyzer.

This SDK reads SMS messages from the device, compresses them, uploads them to the Finpass service, and sends the final metadata needed to complete the analysis flow.

It supports two Android execution modes:

• startFlow(...): the existing SDK-owned full-screen UI flow
• startHeadlessFlow(...): a silent flow with no SDK UI, dialog, notification, or permission prompt

Current release: 1.0.4

Requirements

• React Native >= 0.73.0
• Android minSdk 28
• iOS is not supported

Installation

npm install @finpassai/[email protected]

React Native autolinking will pick up the Android module.

Before you start

To use this SDK, you need these values in the following order:

1. Get api_key and api_secret from the Finpass Dashboard.
2. Call the Finpass Init API.
3. From the Init API response, get doc_id and access_token.
4. Pass doc_id and access_token to the SDK via startFlow(docId, accessToken) or startHeadlessFlow(docId, accessToken).
5. After the SDK succeeds, call the Finpass Hits API with the same doc_id and your dashboard credentials to get analyze_data.

End-to-end integration flow

Step 1: Get API credentials from Finpass Dashboard

First, get the following credentials from the Finpass Dashboard:

• api_key
• api_secret

You need these only for the Init API call. Do not hardcode them inside the mobile app unless your security model explicitly allows that.

Step 2: Call the Init API

Use your api_key and api_secret to call the Finpass Init API:

curl --location 'https://api.finpass.ai/api/v1/services/sms-analyzer/init' \
--header 'Content-Type: application/json' \
--header 'x-api-key: API_KEY' \
--header 'x-api-secret: API_SECRET' \
--data '{
  "service_type": "on_server",
  "webhook_url": "https://example.com/webhook",
  "unique_id": "123456",
  "incremental_parsing": true
}'

Request fields:

| Field | Type | Description | | ----- | ---- | ----------- | | service_type | string | Service mode for the SMS analyzer flow | | webhook_url | string | Webhook URL where your backend receives status or result callbacks | | unique_id | string | Your unique identifier for this transaction or user | | incremental_parsing | boolean | Enables incremental parsing when supported for your account |

Step 3: Read doc_id and access_token from the Init API response

After calling the Init API, use the doc_id and access_token returned by Finpass.

These two values are required by the mobile SDK:

• doc_id
• access_token

Step 4: Start the SDK flow

For the existing SDK-owned UI flow:

import { startFlow } from '@finpassai/react-native-sms-sdk';

try {
  const result = await startFlow(docId, accessToken);

  if (result.success) {
    console.log('Client ID:', result.clientId);
    console.log('Message:', result.message);
  } else {
    console.log('Flow failed:', result.message);
    console.log('Status code:', result.statusCode);
    console.log('Client ID:', result.clientId);
  }
} catch (error: any) {
  console.log(error.code, error.message);
}

For the new headless flow, request READ_SMS in the host app first, then call startHeadlessFlow(...):

import { PermissionsAndroid, Platform } from 'react-native';
import { startHeadlessFlow } from '@finpassai/react-native-sms-sdk';

async function runHeadlessFlow(docId: string, accessToken: string) {
  if (Platform.OS !== 'android') {
    return;
  }

  const granted = await PermissionsAndroid.request(
    PermissionsAndroid.PERMISSIONS.READ_SMS
  );

  if (granted !== PermissionsAndroid.RESULTS.GRANTED) {
    throw new Error('READ_SMS must be granted before starting the headless flow');
  }

  return startHeadlessFlow(docId, accessToken);
}

Step 5: After SDK success, call the Hits API

After the SDK completes successfully, call this API:

curl --location 'https://api.finpass.ai/api/v1/services/sms-analyzer/hits/?doc_id=SAMPLE_DOC_ID' \
--header 'x-api-key: API_KEY' \
--header 'x-api-secret: API_SECRET'

Important:

• Use the same doc_id you already received from the Init API
• Use the same api_key and api_secret you got from the Finpass Dashboard
• This API returns the analyze_data

Example flow in app code:

import { startFlow } from '@finpassai/react-native-sms-sdk';

async function runSmsAnalyzer(docId: string, accessToken: string) {
  const sdkResult = await startFlow(docId, accessToken);

  if (!sdkResult.success) {
    return sdkResult;
  }

  const hitsResponse = await fetch(
    `https://api.finpass.ai/api/v1/services/sms-analyzer/hits/?doc_id=${encodeURIComponent(docId)}`,
    {
      method: 'GET',
      headers: {
        'x-api-key': 'API_KEY',
        'x-api-secret': 'API_SECRET',
      },
    }
  );

  const analyzeData = await hitsResponse.json();

  return {
    sdkResult,
    analyzeData,
  };
}

Android integration

The library manifest already includes:

• android.permission.INTERNET
• android.permission.READ_SMS
• com.reactnativesmssdk.ui.SdkActivity

You do not need to manually add the SDK activity or permissions in the host app unless your app has custom manifest merge rules.

Runtime permission handling depends on which API you use:

• startFlow(...) can request READ_SMS inside the SDK UI flow.
• startHeadlessFlow(...) never shows a permission prompt. The host app must request READ_SMS before calling it.

Public API

startFlow(docId: string, accessToken: string): Promise<SdkResult>

Starts the Android SDK flow using the doc_id and access_token obtained from the Init API.

Parameters:

| Parameter | Type | Description | | --------- | ---- | ----------- | | docId | string | Value received from Finpass Init API as doc_id | | accessToken | string | Value received from Finpass Init API as access_token |

Returns:

interface SdkResult {
  success: boolean;
  statusCode: number;
  message: string;
  clientId: string;
}

Field meanings:

| Field | Type | Description | | ----- | ---- | ----------- | | success | boolean | Whether the overall SDK flow completed successfully | | statusCode | number | Backend status code when available, otherwise 0 | | message | string | Final success or failure message | | clientId | string | Registered client identifier, if one was created |

startHeadlessFlow(docId: string, accessToken: string): Promise<SdkResult>

Starts the Android SDK flow without launching SdkActivity or showing any SDK-owned UI.

Use this only after the host app has already been granted READ_SMS.

Behavior:

• uses the existing register/config/upload/analyze/metadata backend pipeline
• verifies READ_SMS internally before any SMS read
• rejects immediately with E_PERMISSION_DENIED if READ_SMS is missing
• does not require currentActivity
• runs only while the host app process remains active

What the SDK does

Both startFlow(...) and startHeadlessFlow(...) run the same backend pipeline:

1. Verifies SMS permission
2. Registers device details with Finpass
3. Fetches configuration
4. Fetches upload URL and upload fields
5. Reads SMS messages from the device
6. Compresses the SMS payload
7. Uploads the ZIP file
8. Calls the analyze API
9. Sends metadata using message_count from the analyze response

Flow-specific behavior:

• startFlow(...) launches the SDK full-screen native activity with progress updates and can request permission inside the SDK.
• startHeadlessFlow(...) does not launch SdkActivity, does not show any SDK screen, dialog, progress UI, notification, or permission prompt, and uses application/react context instead of currentActivity.

Headless flow caveats:

• The host app must request READ_SMS before calling startHeadlessFlow(...).
• The SDK still checks READ_SMS internally and fails fast if it is missing.
• The headless flow is in-process only. If the app is backgrounded, suspended, or killed mid-run, the SDK does not continue in a background service.

Error behavior

There are two kinds of failures:

1. Immediate API or platform errors reject the promise.
2. Backend or flow failures resolve with SdkResult.success === false.

Rejected promise errors

These come from the JavaScript wrapper or native module rejection path.

| Code | When it happens | | ---- | --------------- | | E_PLATFORM_NOT_SUPPORTED | startFlow or startHeadlessFlow is called on iOS | | E_INVALID_DOC_ID | docId is missing or empty | | E_INVALID_ACCESS_TOKEN | accessToken is missing or empty | | E_IN_PROGRESS | Another SDK flow is already running | | E_NO_ACTIVITY | startFlow is called with no current Android activity available | | E_CANCELLED | The native activity returns a cancelled result | | E_PERMISSION_DENIED | startHeadlessFlow is called before READ_SMS has been granted |

Example:

import { PlatformError, SdkError, startFlow } from '@finpassai/react-native-sms-sdk';

try {
  await startFlow(docId, accessToken);
} catch (error) {
  if (error instanceof PlatformError) {
    console.log(error.message); // "This feature is not available on iOS"
  }

  if (error instanceof SdkError) {
    console.log(error.code);
    console.log(error.message);
  }
}

Resolved flow failures

These do not reject the promise. Instead, startFlow(...) and startHeadlessFlow(...) return:

{
  success: false,
  statusCode: number,
  message: string,
  clientId: string
}

Examples include:

• SMS permission denied by the user in the UI flow
• registration failure
• config fetch failure
• upload URL failure
• no SMS found on device
• upload failure
• analyze API failure
• metadata submission failure
• missing SDK configuration inside the native activity

iOS behavior

The package can be imported in a React Native app on iOS, but calling startFlow(...) or startHeadlessFlow(...) throws a PlatformError with the message:

This feature is not available on iOS