npm package: @quipuscore/capacitor-sms
Description: Capacitor plugin for reading and syncing SMS messages on Android devices.
Author: quipu
Latest version: 0.0.1

# Capacitor SMS Plugin

A Capacitor plugin to read and sync SMS messages on Android devices.

> **Note:** This plugin is **Android-only**. SMS reading is not supported on iOS.

## Installation

```bash
npm install @quipuscore/capacitor-sms
npx cap sync
```



## Requirements

- Capacitor 7+
- Android API level 22+ (Android 5.1+)

## Configuration

### Android

Add the following permissions to your AndroidManifest.xml:

```xml
<uses-permission android:name="android.permission.READ_SMS" />
<uses-permission android:name="android.permission.INTERNET" />
```

## Usage

### Initialize the plugin

```typescript
import { SmsPlugin } from '@quipuscore/capacitor-sms';

// Initialize with your API token
await SmsPlugin.initialize({ token: 'YOUR_API_TOKEN' });
```

### Read and sync SMS messages

```typescript
// Read SMS messages and sync with your backend in a single operation
try {
  const result = await SmsPlugin.collectAndSync({
    userId: 'user123',
    deviceId: 'device456'
  });
  console.log(`Successfully processed ${result.messages.length} messages`);
} catch (error) {
  console.error('Error reading or syncing SMS:', error);
}
```

## API

<docgen-index>

* [`initialize(...)`](#initialize)
* [`collectAndSync(...)`](#collectandsync)
* [`linkUserIdWithDevice(...)`](#linkuseridwithdevice)
* [Interfaces](#interfaces)

</docgen-index>

<docgen-api>
<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->

Public interface for the SMS plugin - exposing initialize, collectAndSync, and linkUserIdWithDevice methods

### initialize(...)

```typescript
initialize(options: InitializeOptions) => Promise<InitializeResult>
```

Initialize the SMS plugin with a token

| Param         | Type                                                            | Description                                 |
| ------------- | --------------------------------------------------------------- | ------------------------------------------- |
| **`options`** | <code><a href="#initializeoptions">InitializeOptions</a></code> | Options containing the authentication token |

**Returns:** <code>Promise&lt;<a href="#initializeresult">InitializeResult</a>&gt;</code>

--------------------


### collectAndSync(...)

```typescript
collectAndSync(options: CollectAndSyncOptions) => Promise<SyncSmsResult>
```

Collect SMS messages and sync them to the server in one operation

| Param         | Type                                                                    | Description                            |
| ------------- | ----------------------------------------------------------------------- | -------------------------------------- |
| **`options`** | <code><a href="#collectandsyncoptions">CollectAndSyncOptions</a></code> | Options containing userId and deviceId |

**Returns:** <code>Promise&lt;<a href="#syncsmsresult">SyncSmsResult</a>&gt;</code>

--------------------


### linkUserIdWithDevice(...)

```typescript
linkUserIdWithDevice(options: LinkUserIdWithDeviceOptions) => Promise<LinkUserIdWithDeviceResult>
```

Link a user ID with a device ID

| Param         | Type                                                                                | Description                            |
| ------------- | ----------------------------------------------------------------------------------- | -------------------------------------- |
| **`options`** | <code><a href="#linkuseridwithdeviceoptions">LinkUserIdWithDeviceOptions</a></code> | Options containing userId and deviceId |

**Returns:** <code>Promise&lt;<a href="#linkuseridwithdeviceresult">LinkUserIdWithDeviceResult</a>&gt;</code>

--------------------


### Interfaces


#### InitializeResult

| Prop          | Type                 |
| ------------- | -------------------- |
| **`success`** | <code>boolean</code> |
| **`message`** | <code>string</code>  |


#### InitializeOptions

| Prop           | Type                | Description                                                                              |
| -------------- | ------------------- | ---------------------------------------------------------------------------------------- |
| **`clientId`** | <code>string</code> | Client ID for identification                                                             |
| **`token`**    | <code>string</code> | API token for authentication - this also determines the environment (sandbox/production) |


#### SyncSmsResult

| Prop          | Type                 |
| ------------- | -------------------- |
| **`success`** | <code>boolean</code> |
| **`message`** | <code>string</code>  |


#### CollectAndSyncOptions

| Prop                 | Type                | Description              |
| -------------------- | ------------------- | ------------------------ |
| **`deviceId`**       | <code>string</code> |                          |
| **`userId`**         | <code>string</code> | Optional user ID         |
| **`identityNumber`** | <code>string</code> | Optional identity number |
| **`identityType`**   | <code>string</code> | Optional identity type   |


#### LinkUserIdWithDeviceResult

| Prop          | Type                 |
| ------------- | -------------------- |
| **`success`** | <code>boolean</code> |
| **`message`** | <code>string</code>  |


#### LinkUserIdWithDeviceOptions

| Prop           | Type                | Description                     |
| -------------- | ------------------- | ------------------------------- |
| **`userId`**   | <code>string</code> | User ID to link with the device |
| **`deviceId`** | <code>string</code> | Device ID to link with the user |

</docgen-api>

## License

MIT