@factpulse/sdk 2.0.11 → 2.0.49

package/README.md

@@ -2,16 +2,15 @@
 
 Client TypeScript/JavaScript officiel pour l'API FactPulse - Facturation électronique française.
 
-## 🎯 Fonctionnalités
+## Fonctionnalités
 
 - **Factur-X** : Génération et validation de factures électroniques (profils MINIMUM, BASIC, EN16931, EXTENDED)
 - **Chorus Pro** : Intégration avec la plateforme de facturation publique française
 - **AFNOR PDP/PA** : Soumission de flux conformes à la norme XP Z12-013
 - **Signature électronique** : Signature PDF (PAdES-B-B, PAdES-B-T, PAdES-B-LT)
 - **Client simplifié** : Authentification JWT et polling intégrés via `helpers`
-- **TypeScript** : Support complet avec types générés automatiquement
 
-## 🚀 Installation
+## Installation
 
 ```bash
 npm install @factpulse/sdk
@@ -19,174 +18,224 @@ npm install @factpulse/sdk
 yarn add @factpulse/sdk
 ```
 
-## 📖 Démarrage rapide
-
-### Méthode recommandée : Client simplifié avec helpers
+## Démarrage rapide
 
 Le module `helpers` offre une API simplifiée avec authentification et polling automatiques :
 
 ```typescript
-import { FactPulseClient } from '@factpulse/sdk/helpers';
+import {
+  FactPulseClient,
+  montant,
+  montantTotal,
+  ligneDePoste,
+  ligneDeTva,
+  fournisseur,
+  destinataire,
+} from '@factpulse/sdk/helpers';
 import * as fs from 'fs';
 
-// Créer le client (authentification automatique)
+// Créer le client
 const client = new FactPulseClient({
   email: 'votre_email@example.com',
   password: 'votre_mot_de_passe'
 });
 
-// Données de la facture
+// Construire la facture avec les helpers
 const factureData = {
-  numero_facture: 'FAC-2025-001',
-  date_facture: '2025-01-15',
-  fournisseur: {
-    nom: 'Mon Entreprise SAS',
-    siret: '12345678901234',
-    adresse_postale: {
-      ligne_un: '123 Rue Example',
-      code_postal: '75001',
-      nom_ville: 'Paris',
-      pays_code_iso: 'FR'
-    }
-  },
-  destinataire: {
-    nom: 'Client SARL',
-    siret: '98765432109876',
-    adresse_postale: {
-      ligne_un: '456 Avenue Test',
-      code_postal: '69001',
-      nom_ville: 'Lyon',
-      pays_code_iso: 'FR'
-    }
-  },
-  montant_total: {
-    montant_ht_total: '1000.00',
-    montant_tva: '200.00',
-    montant_ttc_total: '1200.00',
-    montant_a_payer: '1200.00'
-  },
-  lignes_de_poste: [{
-    numero: 1,
-    denomination: 'Prestation de conseil',
-    quantite: '10.00',
-    unite: 'PIECE',
-    montant_unitaire_ht: '100.00'
-  }]
+  numeroFacture: 'FAC-2025-001',
+  dateFacture: '2025-01-15',
+  fournisseur: fournisseur(
+    'Mon Entreprise SAS',
+    '12345678901234',
+    '123 Rue Example',
+    '75001',
+    'Paris'
+  ),
+  destinataire: destinataire(
+    'Client SARL',
+    '98765432109876',
+    '456 Avenue Test',
+    '69001',
+    'Lyon'
+  ),
+  montantTotal: montantTotal(1000.00, 200.00, 1200.00, 1200.00),
+  lignesDePoste: [
+    ligneDePoste(1, 'Prestation de conseil', 10, 100.00, 1000.00)
+  ],
+  lignesDeTva: [
+    ligneDeTva(1000.00, 200.00, { tauxManuel: '20.00' })
+  ],
 };
 
-// Lire le PDF source
-const pdfSource = fs.readFileSync('facture_source.pdf');
-
-// Générer le PDF Factur-X (polling automatique)
+// Générer le PDF Factur-X
 const pdfBytes = await client.genererFacturx(
   factureData,
-  pdfSource,
-  'EN16931',  // profil
-  'pdf',      // format
-  true        // sync (attend le résultat)
+  'facture_source.pdf',
+  'EN16931'
 );
 
-// Sauvegarder
 fs.writeFileSync('facture_facturx.pdf', pdfBytes);
 ```
 
-### Méthode alternative : SDK brut
+## Helpers disponibles
+
+### montant(value)
 
-Pour un contrôle total, utilisez le SDK généré directement :
+Convertit une valeur en string formaté pour les montants monétaires.
 
 ```typescript
-import { Configuration, TraitementFactureApi } from '@factpulse/sdk';
-import axios from 'axios';
+import { montant } from '@factpulse/sdk/helpers';
 
-// 1. Obtenir le token JWT
-const tokenResponse = await axios.post('https://factpulse.fr/api/token/', {
-  username: 'votre_email@example.com',
-  password: 'votre_mot_de_passe'
-});
-const token = tokenResponse.data.access;
+montant(1234.5);      // "1234.50"
+montant("1234.56");   // "1234.56"
+montant(null);        // "0.00"
+```
 
-// 2. Configurer le client
-const config = new Configuration({
-  basePath: 'https://factpulse.fr/api/facturation',
-  accessToken: token
-});
+### montantTotal(ht, tva, ttc, aPayer, options?)
 
-// 3. Appeler l'API
-const api = new TraitementFactureApi(config);
-const response = await api.genererFactureApiV1TraitementGenererFacturePost(
-  JSON.stringify(factureData),
-  'EN16931',
-  'pdf',
-  new Blob([pdfSource])
-);
+Crée un objet MontantTotal complet.
+
+```typescript
+import { montantTotal } from '@factpulse/sdk/helpers';
 
-// 4. Polling manuel pour récupérer le résultat
-const taskId = response.data.id_tache;
-// ... (implémenter le polling)
+const total = montantTotal(1000.00, 200.00, 1200.00, 1200.00, {
+  remiseTtc: 50.00,          // Optionnel
+  motifRemise: 'Fidélité',   // Optionnel
+  acompte: 100.00,           // Optionnel
+});
 ```
 
-## 🔧 Avantages des helpers
+### ligneDePoste(numero, denomination, quantite, montantUnitaireHt, montantTotalLigneHt, options?)
 
-| Fonctionnalité | SDK brut | helpers |
-|----------------|----------|---------|
-| Authentification | Manuelle | Automatique |
-| Refresh token | Manuel | Automatique |
-| Polling tâches async | Manuel | Automatique (backoff) |
-| Retry sur 401 | Manuel | Automatique |
-| Types TypeScript | ✓ | ✓ |
+Crée une ligne de facturation.
 
-## 🔑 Options d'authentification
+```typescript
+import { ligneDePoste } from '@factpulse/sdk/helpers';
+
+const ligne = ligneDePoste(
+  1,
+  'Prestation de conseil',
+  5,
+  200.00,
+  1000.00,  // montantTotalLigneHt requis
+  {
+    tauxTva: 'TVA20',        // Ou tauxTvaManuel: '20.00'
+    categorieTva: 'S',       // S, Z, E, AE, K
+    unite: 'HEURE',          // FORFAIT, PIECE, HEURE, JOUR...
+    reference: 'REF-001',    // Optionnel
+  }
+);
+```
 
-### Client UID (multi-clients)
+### ligneDeTva(montantBaseHt, montantTva, options?)
 
-Si vous gérez plusieurs clients :
+Crée une ligne de ventilation TVA.
 
 ```typescript
-const client = new FactPulseClient({
-  email: 'votre_email@example.com',
-  password: 'votre_mot_de_passe',
-  clientUid: 'identifiant_client'  // UID du client cible
+import { ligneDeTva } from '@factpulse/sdk/helpers';
+
+const tva = ligneDeTva(1000.00, 200.00, {
+  taux: 'TVA20',       // Ou tauxManuel: '20.00'
+  categorie: 'S',      // S, Z, E, AE, K
 });
 ```
 
-### Configuration avancée
+### adressePostale(ligne1, codePostal, ville, options?)
+
+Crée une adresse postale structurée.
 
 ```typescript
-const client = new FactPulseClient({
-  email: 'votre_email@example.com',
-  password: 'votre_mot_de_passe',
-  apiUrl: 'https://factpulse.fr',  // URL personnalisée
-  pollingInterval: 2000,  // Intervalle de polling initial (ms)
-  pollingTimeout: 120000,  // Timeout de polling (ms)
-  maxRetries: 2  // Tentatives en cas de 401
+import { adressePostale } from '@factpulse/sdk/helpers';
+
+const adresse = adressePostale('123 Rue de la République', '75001', 'Paris', {
+  pays: 'FR',          // Défaut: 'FR'
+  ligne2: 'Bâtiment A' // Optionnel
 });
 ```
 
-## 💡 Formats de montants acceptés
+### adresseElectronique(identifiant, schemeId?)
+
+Crée une adresse électronique (identifiant numérique).
+
+```typescript
+import { adresseElectronique } from '@factpulse/sdk/helpers';
+
+// SIRET (schemeId="0225")
+const adresse = adresseElectronique('12345678901234', '0225');
+
+// SIREN (schemeId="0009", défaut)
+const adresse = adresseElectronique('123456789');
+```
+
+### fournisseur(nom, siret, adresseLigne1, codePostal, ville, options?)
+
+Crée un fournisseur complet avec calcul automatique du SIREN et TVA intra.
+
+```typescript
+import { fournisseur } from '@factpulse/sdk/helpers';
+
+const f = fournisseur(
+  'Ma Société SAS',
+  '12345678901234',
+  '123 Rue Example',
+  '75001',
+  'Paris',
+  { iban: 'FR7630006000011234567890189' }
+);
+// SIREN et TVA intracommunautaire calculés automatiquement
+```
+
+### destinataire(nom, siret, adresseLigne1, codePostal, ville, options?)
 
-L'API accepte plusieurs formats pour les montants :
+Crée un destinataire (client) avec calcul automatique du SIREN.
 
 ```typescript
-// String (recommandé pour la précision)
-const montant = "1234.56";
+import { destinataire } from '@factpulse/sdk/helpers';
+
+const d = destinataire(
+  'Client SARL',
+  '98765432109876',
+  '456 Avenue Test',
+  '69001',
+  'Lyon'
+);
+```
+
+## Mode Zero-Trust (Chorus Pro / AFNOR)
 
-// Number
-const montant = 1234.56;
+Pour passer vos propres credentials sans stockage côté serveur :
 
-// Integer
-const montant = 1234;
+```typescript
+import {
+  FactPulseClient,
+  ChorusProCredentials,
+  AFNORCredentials,
+} from '@factpulse/sdk/helpers';
 
-// Helper de formatage
-const montantFormate = FactPulseClient.formatMontant(1234.5);  // "1234.50"
+const client = new FactPulseClient({
+  email: 'votre_email@example.com',
+  password: 'votre_mot_de_passe',
+  chorusCredentials: {
+    pisteClientId: 'votre_client_id',
+    pisteClientSecret: 'votre_client_secret',
+    chorusProLogin: 'votre_login',
+    chorusProPassword: 'votre_password',
+    sandbox: true,
+  },
+  afnorCredentials: {
+    flowServiceUrl: 'https://api.pdp.fr/flow/v1',
+    tokenUrl: 'https://auth.pdp.fr/oauth/token',
+    clientId: 'votre_client_id',
+    clientSecret: 'votre_client_secret',
+  },
+});
 ```
 
-## 📚 Ressources
+## Ressources
 
 - **Documentation API** : https://factpulse.fr/api/facturation/documentation
-- **Code source** : https://github.com/factpulse/sdk-typescript
-- **Issues** : https://github.com/factpulse/sdk-typescript/issues
 - **Support** : contact@factpulse.fr
 
-## 📄 Licence
+## Licence
 
 MIT License - Copyright (c) 2025 FactPulse

package/api/afnorpdppaapi.ts

@@ -21,11 +21,92 @@ import globalAxios from 'axios';
 import { DUMMY_BASE_URL, assertParamExists, setApiKeyToObject, setBasicAuthToObject, setBearerAuthToObject, setOAuthToObject, setSearchParams, serializeDataIfNeeded, toPathString, createRequestFunction } from '../common';
 // @ts-ignore
 import { BASE_PATH, COLLECTION_FORMATS, type RequestArgs, BaseAPI, RequiredError, operationServerMap } from '../base';
+// @ts-ignore
+import type { FactureEntrante } from '../models';
+// @ts-ignore
+import type { HTTPValidationError } from '../models';
 /**
  * AFNORPDPPAApi - axios parameter creator
  */
 export const AFNORPDPPAApiAxiosParamCreator = function (configuration?: Configuration) {
     return {
+        /**
+         * Récupère les credentials AFNOR/PDP stockés pour le client_uid du JWT. Cet endpoint est utilisé par le SDK en mode \'stored\' pour récupérer les credentials avant de faire l\'OAuth AFNOR lui-même.
+         * @summary Récupérer les credentials AFNOR stockés
+         * @param {*} [options] Override http request option.
+         * @throws {RequiredError}
+         */
+        getAfnorCredentialsApiV1AfnorCredentialsGet: async (options: RawAxiosRequestConfig = {}): Promise<RequestArgs> => {
+            const localVarPath = `/api/v1/afnor/credentials`;
+            // use dummy base URL string because the URL constructor only accepts absolute URLs.
+            const localVarUrlObj = new URL(localVarPath, DUMMY_BASE_URL);
+            let baseOptions;
+            if (configuration) {
+                baseOptions = configuration.baseOptions;
+            }
+
+            const localVarRequestOptions = { method: 'GET', ...baseOptions, ...options};
+            const localVarHeaderParameter = {} as any;
+            const localVarQueryParameter = {} as any;
+
+            // authentication HTTPBearer required
+            // http bearer authentication required
+            await setBearerAuthToObject(localVarHeaderParameter, configuration)
+
+            localVarHeaderParameter['Accept'] = 'application/json';
+
+            setSearchParams(localVarUrlObj, localVarQueryParameter);
+            let headersFromBaseOptions = baseOptions && baseOptions.headers ? baseOptions.headers : {};
+            localVarRequestOptions.headers = {...localVarHeaderParameter, ...headersFromBaseOptions, ...options.headers};
+
+            return {
+                url: toPathString(localVarUrlObj),
+                options: localVarRequestOptions,
+            };
+        },
+        /**
+         * Télécharge un flux entrant depuis la PDP AFNOR et extrait les métadonnées de la facture vers un format JSON unifié. Supporte les formats Factur-X, CII et UBL.
+         * @summary Récupérer et extraire une facture entrante
+         * @param {string} flowId 
+         * @param {boolean} [includeDocument] 
+         * @param {*} [options] Override http request option.
+         * @throws {RequiredError}
+         */
+        getFluxEntrantApiV1AfnorFluxEntrantsFlowIdGet: async (flowId: string, includeDocument?: boolean, options: RawAxiosRequestConfig = {}): Promise<RequestArgs> => {
+            // verify required parameter 'flowId' is not null or undefined
+            assertParamExists('getFluxEntrantApiV1AfnorFluxEntrantsFlowIdGet', 'flowId', flowId)
+            const localVarPath = `/api/v1/afnor/flux-entrants/{flow_id}`
+                .replace(`{${"flow_id"}}`, encodeURIComponent(String(flowId)));
+            // use dummy base URL string because the URL constructor only accepts absolute URLs.
+            const localVarUrlObj = new URL(localVarPath, DUMMY_BASE_URL);
+            let baseOptions;
+            if (configuration) {
+                baseOptions = configuration.baseOptions;
+            }
+
+            const localVarRequestOptions = { method: 'GET', ...baseOptions, ...options};
+            const localVarHeaderParameter = {} as any;
+            const localVarQueryParameter = {} as any;
+
+            // authentication HTTPBearer required
+            // http bearer authentication required
+            await setBearerAuthToObject(localVarHeaderParameter, configuration)
+
+            if (includeDocument !== undefined) {
+                localVarQueryParameter['include_document'] = includeDocument;
+            }
+
+            localVarHeaderParameter['Accept'] = 'application/json';
+
+            setSearchParams(localVarUrlObj, localVarQueryParameter);
+            let headersFromBaseOptions = baseOptions && baseOptions.headers ? baseOptions.headers : {};
+            localVarRequestOptions.headers = {...localVarHeaderParameter, ...headersFromBaseOptions, ...options.headers};
+
+            return {
+                url: toPathString(localVarUrlObj),
+                options: localVarRequestOptions,
+            };
+        },
         /**
          * Endpoint proxy OAuth2 pour obtenir un token d\'accès AFNOR. Fait proxy vers le mock AFNOR (sandbox) ou la vraie PDP selon MOCK_AFNOR_BASE_URL. Cet endpoint est public (pas d\'auth Django requise) car il est appelé par le SDK AFNOR.
          * @summary Endpoint OAuth2 pour authentification AFNOR
@@ -65,6 +146,32 @@ export const AFNORPDPPAApiAxiosParamCreator = function (configuration?: Configur
 export const AFNORPDPPAApiFp = function(configuration?: Configuration) {
     const localVarAxiosParamCreator = AFNORPDPPAApiAxiosParamCreator(configuration)
     return {
+        /**
+         * Récupère les credentials AFNOR/PDP stockés pour le client_uid du JWT. Cet endpoint est utilisé par le SDK en mode \'stored\' pour récupérer les credentials avant de faire l\'OAuth AFNOR lui-même.
+         * @summary Récupérer les credentials AFNOR stockés
+         * @param {*} [options] Override http request option.
+         * @throws {RequiredError}
+         */
+        async getAfnorCredentialsApiV1AfnorCredentialsGet(options?: RawAxiosRequestConfig): Promise<(axios?: AxiosInstance, basePath?: string) => AxiosPromise<any>> {
+            const localVarAxiosArgs = await localVarAxiosParamCreator.getAfnorCredentialsApiV1AfnorCredentialsGet(options);
+            const localVarOperationServerIndex = configuration?.serverIndex ?? 0;
+            const localVarOperationServerBasePath = operationServerMap['AFNORPDPPAApi.getAfnorCredentialsApiV1AfnorCredentialsGet']?.[localVarOperationServerIndex]?.url;
+            return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath);
+        },
+        /**
+         * Télécharge un flux entrant depuis la PDP AFNOR et extrait les métadonnées de la facture vers un format JSON unifié. Supporte les formats Factur-X, CII et UBL.
+         * @summary Récupérer et extraire une facture entrante
+         * @param {string} flowId 
+         * @param {boolean} [includeDocument] 
+         * @param {*} [options] Override http request option.
+         * @throws {RequiredError}
+         */
+        async getFluxEntrantApiV1AfnorFluxEntrantsFlowIdGet(flowId: string, includeDocument?: boolean, options?: RawAxiosRequestConfig): Promise<(axios?: AxiosInstance, basePath?: string) => AxiosPromise<FactureEntrante>> {
+            const localVarAxiosArgs = await localVarAxiosParamCreator.getFluxEntrantApiV1AfnorFluxEntrantsFlowIdGet(flowId, includeDocument, options);
+            const localVarOperationServerIndex = configuration?.serverIndex ?? 0;
+            const localVarOperationServerBasePath = operationServerMap['AFNORPDPPAApi.getFluxEntrantApiV1AfnorFluxEntrantsFlowIdGet']?.[localVarOperationServerIndex]?.url;
+            return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath);
+        },
         /**
          * Endpoint proxy OAuth2 pour obtenir un token d\'accès AFNOR. Fait proxy vers le mock AFNOR (sandbox) ou la vraie PDP selon MOCK_AFNOR_BASE_URL. Cet endpoint est public (pas d\'auth Django requise) car il est appelé par le SDK AFNOR.
          * @summary Endpoint OAuth2 pour authentification AFNOR
@@ -86,6 +193,26 @@ export const AFNORPDPPAApiFp = function(configuration?: Configuration) {
 export const AFNORPDPPAApiFactory = function (configuration?: Configuration, basePath?: string, axios?: AxiosInstance) {
     const localVarFp = AFNORPDPPAApiFp(configuration)
     return {
+        /**
+         * Récupère les credentials AFNOR/PDP stockés pour le client_uid du JWT. Cet endpoint est utilisé par le SDK en mode \'stored\' pour récupérer les credentials avant de faire l\'OAuth AFNOR lui-même.
+         * @summary Récupérer les credentials AFNOR stockés
+         * @param {*} [options] Override http request option.
+         * @throws {RequiredError}
+         */
+        getAfnorCredentialsApiV1AfnorCredentialsGet(options?: RawAxiosRequestConfig): AxiosPromise<any> {
+            return localVarFp.getAfnorCredentialsApiV1AfnorCredentialsGet(options).then((request) => request(axios, basePath));
+        },
+        /**
+         * Télécharge un flux entrant depuis la PDP AFNOR et extrait les métadonnées de la facture vers un format JSON unifié. Supporte les formats Factur-X, CII et UBL.
+         * @summary Récupérer et extraire une facture entrante
+         * @param {string} flowId 
+         * @param {boolean} [includeDocument] 
+         * @param {*} [options] Override http request option.
+         * @throws {RequiredError}
+         */
+        getFluxEntrantApiV1AfnorFluxEntrantsFlowIdGet(flowId: string, includeDocument?: boolean, options?: RawAxiosRequestConfig): AxiosPromise<FactureEntrante> {
+            return localVarFp.getFluxEntrantApiV1AfnorFluxEntrantsFlowIdGet(flowId, includeDocument, options).then((request) => request(axios, basePath));
+        },
         /**
          * Endpoint proxy OAuth2 pour obtenir un token d\'accès AFNOR. Fait proxy vers le mock AFNOR (sandbox) ou la vraie PDP selon MOCK_AFNOR_BASE_URL. Cet endpoint est public (pas d\'auth Django requise) car il est appelé par le SDK AFNOR.
          * @summary Endpoint OAuth2 pour authentification AFNOR
@@ -102,6 +229,28 @@ export const AFNORPDPPAApiFactory = function (configuration?: Configuration, bas
  * AFNORPDPPAApi - object-oriented interface
  */
 export class AFNORPDPPAApi extends BaseAPI {
+    /**
+     * Récupère les credentials AFNOR/PDP stockés pour le client_uid du JWT. Cet endpoint est utilisé par le SDK en mode \'stored\' pour récupérer les credentials avant de faire l\'OAuth AFNOR lui-même.
+     * @summary Récupérer les credentials AFNOR stockés
+     * @param {*} [options] Override http request option.
+     * @throws {RequiredError}
+     */
+    public getAfnorCredentialsApiV1AfnorCredentialsGet(options?: RawAxiosRequestConfig) {
+        return AFNORPDPPAApiFp(this.configuration).getAfnorCredentialsApiV1AfnorCredentialsGet(options).then((request) => request(this.axios, this.basePath));
+    }
+
+    /**
+     * Télécharge un flux entrant depuis la PDP AFNOR et extrait les métadonnées de la facture vers un format JSON unifié. Supporte les formats Factur-X, CII et UBL.
+     * @summary Récupérer et extraire une facture entrante
+     * @param {string} flowId 
+     * @param {boolean} [includeDocument] 
+     * @param {*} [options] Override http request option.
+     * @throws {RequiredError}
+     */
+    public getFluxEntrantApiV1AfnorFluxEntrantsFlowIdGet(flowId: string, includeDocument?: boolean, options?: RawAxiosRequestConfig) {
+        return AFNORPDPPAApiFp(this.configuration).getFluxEntrantApiV1AfnorFluxEntrantsFlowIdGet(flowId, includeDocument, options).then((request) => request(this.axios, this.basePath));
+    }
+
     /**
      * Endpoint proxy OAuth2 pour obtenir un token d\'accès AFNOR. Fait proxy vers le mock AFNOR (sandbox) ou la vraie PDP selon MOCK_AFNOR_BASE_URL. Cet endpoint est public (pas d\'auth Django requise) car il est appelé par le SDK AFNOR.
      * @summary Endpoint OAuth2 pour authentification AFNOR