> ## Documentation Index
> Fetch the complete documentation index at: https://laas.mippo.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK for the Mippo LaaS API

> Install and use @mippo/laas-sdk, the typed TypeScript client for the Mippo LaaS API covering KYC, transactions, and webhook signature verification.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @mippo/laas-sdk
  ```

  ```bash yarn theme={null}
  yarn add @mippo/laas-sdk
  ```

  ```bash bun theme={null}
  bun add @mippo/laas-sdk
  ```
</CodeGroup>

## Initialisation

```typescript theme={null}
import { MippoLaas } from '@mippo/laas-sdk';

const mippo = new MippoLaas({
  apiKey: process.env.MIPPO_API_KEY,
  environment: 'sandbox', // 'production' | 'sandbox'
});
```

### Constructor options

| Option        | Type     | Required | Description                              |
| ------------- | -------- | -------- | ---------------------------------------- |
| `apiKey`      | `string` | Yes      | Your `sk_live_` or `sk_test_` key        |
| `environment` | `string` | No       | `'production'` (default) or `'sandbox'`  |
| `timeout`     | `number` | No       | Request timeout in ms (default: `30000`) |

## `mippo.kyc`

### `.submit(request)`

```typescript theme={null}
const client = await mippo.kyc.submit({
  cpf: '123.456.789-09',          // required
  biometricHash: 'sha256:abc',    // required
  personType: 'PF',               // 'PF' | 'PJ', default: 'PF'
  partnerKycToken: 'your_token',  // optional — Model 2 only
});

// Returns: KycToken
// client.token      → string
// client.status     → 'APPROVED' | 'PENDING' | 'REJECTED'
// client.riskTier   → 'STANDARD' | 'HIGH' | 'PEP'
// client.expiresAt  → Date
```

### `.status(kycToken)`

```typescript theme={null}
const status = await mippo.kyc.status('kyc_1719000000_abc123');
// Returns: KycStatusResponse
```

## `mippo.transactions`

### `.initiate(request)`

```typescript theme={null}
const tx = await mippo.transactions.initiate({
  kycToken: client.token,                  // required
  amountBrl: 500,                          // required, min 50
  asset: 'USDT',                           // 'USDT' | 'USDC'
  walletAddress: '0xYourWalletAddress',    // required, EIP-55
});

// Returns: TransactionInitiateResponse
// tx.transactionId              → string
// tx.status                     → 'PENDING_AUTH'
// tx.authChallenge.type         → 'MFA_TOTP' | 'LIVENESS'
// tx.authChallenge.livenessUrl  → string (LIVENESS path only)
```

### `.confirmMfa(request)`

```typescript theme={null}
const confirmed = await mippo.transactions.confirmMfa({
  transactionId: tx.transactionId,  // required
  totpCode: '482910',               // required
});

// Returns: TransactionConfirmMfaResponse
// confirmed.pixPayload  → string (Pix Copia e Cola)
// confirmed.pixExpiry   → Date
```

### `.status(transactionId)`

```typescript theme={null}
const status = await mippo.transactions.status('tx_1719000000_xyz');

// Returns: TransactionStatusResponse
// status.status      → 'PENDING_AUTH' | 'PENDING_PAYMENT' | 'PROCESSING' | 'COMPLETED' | 'FAILED'
// status.txHash      → string | undefined (present when COMPLETED)
// status.completedAt → Date | undefined
```

## Error handling

All SDK methods throw a `MippoApiError` on non-2xx responses:

```typescript theme={null}
import { MippoApiError } from '@mippo/laas-sdk';

try {
  const tx = await mippo.transactions.initiate({ ... });
} catch (err) {
  if (err instanceof MippoApiError) {
    console.error(err.code);     // 'KYC_TOKEN_EXPIRED'
    console.error(err.message);  // Human-readable
    console.error(err.status);   // HTTP status code
  }
}
```

### Error classes

| Class                                  | When                                                   |
| -------------------------------------- | ------------------------------------------------------ |
| `MippoApiError`                        | Any non-2xx API response                               |
| `MippoAuthError extends MippoApiError` | 401 / 403 — key invalid, revoked, or partner suspended |
| `MippoKycError extends MippoApiError`  | KYC rejected or expired                                |

## TypeScript types

All types are exported from the package root:

```typescript theme={null}
import type {
  KycSubmitRequest,
  KycToken,
  KycStatusResponse,
  RiskTier,
  TransactionInitiateRequest,
  TransactionInitiateResponse,
  TransactionConfirmMfaResponse,
  TransactionStatusResponse,
  AuthChallenge,
} from '@mippo/laas-sdk';
```