npm package: @fiscapi-node/local-sdk
Description: SDK officiel pour connecter une instance locale FiscAPI aux crédits et à la passerelle IA FiscAPI Cloud
Author: FiscAPI Team
Latest version: 0.1.5

# FiscAPI Local SDK

SDK officiel pour connecter une installation locale (**FiscAPI Solution** / **FiscAPI ERP**) à **FiscAPI Cloud** pour:

- la récupération de la clé AI Gateway,
- la synchronisation des actions IA,
- la consommation des crédits IA,
- la demande de recharges par facture.

Package npm: `@fiscapi-node/local-sdk`

## Installation

```bash
npm install @fiscapi-node/local-sdk
```

## Architecture fonctionnelle

1. **Admin Cloud** configure les actions IA et crée un token local (`AI_LOCAL`).
2. **Application locale** initialise le SDK avec ce token.
3. L’application locale:
   - synchronise `getSession()` (clé gateway + état crédits),
   - synchronise `getActions()` (catalogue d’actions IA),
   - débite `consumeCredits()` avant chaque opération IA,
   - déclenche `requestRechargeInvoice()` si crédits insuffisants.

## Où sont stockées et récupérées les actions IA ?

Les actions IA sont récupérées depuis FiscAPI Cloud:

- **source admin principale**: `PlatformSetting` clé `AI_LOCAL_ACTIONS`,
- **fallback stable**: `DEFAULT_LOCAL_AI_ACTIONS` (code serveur),
- **endpoint SDK**: `GET /api/v1/ai/actions`.

Donc elles sont **prévisibles** (liste standard) mais **pilotables par l’admin** (surcharges dans la console).

## Setup Admin (console Cloud)

### Étape 1 — Créer un token local

- Menu: `Admin > IA > Accès IA local`
- Action: créer un token scope `AI_LOCAL`
- Résultat: clé `sk_live_...` (visible une seule fois)

### Étape 2 — Configurer les actions IA locales

- Menu: `Admin > IA > Actions IA locales`
- Action: définir `key`, `instructions`, `costCredits`, `enabled`
- Résultat: ce catalogue sera servi au SDK local

### Étape 3 — Suivre ventes/recharges locales

- Menu: `Admin > Billing`
- Onglet `Recharges (factures)`: validation des demandes (APPROVE/REJECT)
- Onglet `Solutions locales`: vue ventes, solde et consommation IA locale

## Intégration locale (workflow recommandé)

```ts
import { LocalAiClient } from '@fiscapi-node/local-sdk';

const client = new LocalAiClient({
  token: process.env.FISCAPI_LOCAL_TOKEN!,
  baseUrl: 'https://www.fiscapi.com',
});
```

### 1) Synchroniser la session Cloud

```ts
const session = await client.getSession();
// session.gateway.apiKey => à stocker localement en base chiffrée
// session.gateway.baseUrl => URL gateway IA (fallback auto: https://ai-gateway.vercel.sh/v1)
```

### 2) Synchroniser les actions IA

```ts
const { actions } = await client.getActions();
// injecter/mettre à jour la table locale des actions
// chaque action inclut aussi model + modelSource (résolution cloud)
```

### 3) Débiter avant exécution IA

```ts
await client.consumeCredits({ action: 'ocr_invoice', units: 1 });
```

Si l’API renvoie `402 INSUFFICIENT_CREDITS`, bloquer l’action et ouvrir l’écran de recharge.

### 4) Recharger par facture

```ts
await client.requestRechargeInvoice({
  amount: 500,
  message: 'Recharge agence Cotonou',
});
```

Puis suivre:

```ts
const { requests } = await client.listRechargeRequests();
```

## API du SDK

### `new LocalAiClient(config | token)`

```ts
const client = new LocalAiClient({
  token: 'sk_live_xxx',
  baseUrl: 'https://www.fiscapi.com',
  timeout: 30000,
});
```

### `getSession()`

Retourne clé gateway + URL gateway + crédits + policy.
Inclut aussi `models.default` et `models.byAction` (modèle effectif + source).

Le SDK normalise automatiquement l’URL gateway:

- priorité `session.gateway.baseUrl`,
- fallback `session.gatewayBaseUrl`,
- fallback URL si l’ancien backend renvoie `gateway.source = "db"` / `"env"` (non URL).

### `resolveSessionGatewayBaseUrl(session)`

Helper exporté pour récupérer une URL gateway valide à partir d’une session.

### `getActions()`

Retourne les actions IA tenant/local avec:

- `instructions`, `costCredits`, `enabled`
- `model` (modèle effectif)
- `modelSource` (clé/source utilisée: ex `AI_GATEWAY_MODEL_OCR_INVOICE`, `AI_GATEWAY_MODEL`, `env:*`, `fallback`)

### `consumeCredits({ units, action })`

Débite les crédits avant une action IA locale.

### `getCreditsBalance()`

Retourne le solde de crédits global.

### `getCreditPacks()`

Retourne le catalogue des packs (`/api/v1/credits/packs`).

### `requestRechargeInvoice({ amount, message })`

Crée une demande de recharge avec facture (`POST /api/billing/recharges`).

### `listRechargeRequests()`

Liste les demandes de recharge du tenant (`GET /api/billing/recharges`).

## Actions IA standards (référentiel)

Ces actions sont les clés stables à supporter dans FiscAPI local:

- `eliana_chat`
- `invoice`
- `proforma`
- `vigilance`
- `ocr_expense`
- `ocr_invoice`

> Si une action est ajoutée/modifiée côté admin, le SDK/README doit être mis à jour à la release suivante.

## Gestion d’erreurs

Le SDK lève `FiscApiLocalError` avec:

- `status`: HTTP status (ex: `401`, `402`, `403`, `422`)
- `code`: code métier (ex: `INSUFFICIENT_CREDITS`, `UNAUTHORIZED`)
- `details`: payload technique si disponible

## Bonnes pratiques d’exploitation

- Chiffrer localement `session.gateway.apiKey` (jamais en clair côté front).
- Re-synchroniser les actions IA au démarrage + tâche planifiée (ex: toutes les 24h).
- Débiter systématiquement les crédits avant exécution IA.
- Logger localement `action`, `units`, `user`, `timestamp`, `requestId`.
- En cas de `402`, forcer un passage par le flux de recharge.