npm package: @finpassai/react-native-sms-sdk
Description: React Native SMS SDK for Android - Analyse SMS data
Latest version: 1.0.3

# 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

```bash
npm install @finpassai/react-native-sms-sdk@1.0.3
```

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:

```bash
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:

```ts
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:

```bash
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:

```ts
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:

```ts
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:

```ts
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:

```ts
{
  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:

```ts
This feature is not available on iOS
```