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.

Current release: 1.0.3

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).
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

Pass the doc_id and access_token from the Init API into the SDK:

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);
}

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) {
  const sdkResult = await startFlow(docId);

  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.

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 |

What the SDK does

Once startFlow(docId, accessToken) is called, the SDK performs this Android flow:

1. Requests 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

The SDK shows its own full-screen native activity with progress updates during the flow.

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 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 | No current Android activity is available | | E_CANCELLED | The native activity returns a cancelled result |

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(...) returns:

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

Examples include:

• SMS permission denied by the user
• 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(...) throws a PlatformError with the message:

This feature is not available on iOS