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

# SDK TypeScript para a API do Supercosmos for Platforms

> Instale e use o @mippo/laas-sdk, o cliente TypeScript tipado da API do Supercosmos for Platforms cobrindo KYC, transações e verificação de assinatura de webhooks.

## Instalação

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

## Inicialização

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

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

### Opções do construtor

| Opção | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `apiKey` | `string` | Sim | Sua chave `sk_live_` ou `sk_test_` |
| `environment` | `string` | Não | `'production'` (padrão) ou `'sandbox'` |
| `timeout` | `number` | Não | Timeout da request em ms (padrão: `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
```

## Tratamento de erros

Todos os métodos do SDK lançam um `MippoApiError` em respostas diferentes de 2xx:

```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
  }
}
```

### Classes de erro

| Classe | Quando |
| - | - |
| `MippoApiError` | Qualquer resposta da API diferente de 2xx |
| `MippoAuthError extends MippoApiError` | 401 / 403 — chave inválida, revogada ou conta suspensa |
| `MippoKycError extends MippoApiError` | KYC rejeitado ou expirado |

## Tipos TypeScript

Todos os tipos são exportados a partir da raiz do pacote:

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.