@factpulse/sdk 2.0.49 → 3.0.2

package/dist/src/helpers/client.d.ts

@@ -1,4 +1,4 @@
-/** Credentials Chorus Pro pour le mode Zero-Trust. */
+/** Chorus Pro credentials for Zero-Trust mode. */
 export interface ChorusProCredentials {
     pisteClientId: string;
     pisteClientSecret: string;
@@ -6,7 +6,7 @@ export interface ChorusProCredentials {
     chorusProPassword: string;
     sandbox?: boolean;
 }
-/** Credentials AFNOR PDP pour le mode Zero-Trust. L'API FactPulse utilise ces credentials pour s'authentifier auprès de la PDP AFNOR. */
+/** AFNOR PDP credentials for Zero-Trust mode. The FactPulse API uses these credentials to authenticate with the AFNOR PDP. */
 export interface AFNORCredentials {
     flowServiceUrl: string;
     tokenUrl: string;
@@ -25,85 +25,85 @@ export interface FactPulseClientConfig {
     pollingTimeout?: number;
     maxRetries?: number;
 }
-type MontantValue = string | number | null | undefined;
-/** Convertit une valeur en string de montant pour l'API. */
-export declare function montant(value: MontantValue): string;
-/** Crée un objet MontantTotal simplifié. */
-export declare function montantTotal(ht: MontantValue, tva: MontantValue, ttc: MontantValue, aPayer: MontantValue, options?: {
-    remiseTtc?: MontantValue;
-    motifRemise?: string;
-    acompte?: MontantValue;
+type AmountValue = string | number | null | undefined;
+/** Converts a value to an amount string for the API. */
+export declare function amount(value: AmountValue): string;
+/** Creates a simplified InvoiceTotals object. */
+export declare function invoiceTotals(exclTax: AmountValue, vat: AmountValue, inclTax: AmountValue, amountDue: AmountValue, options?: {
+    globalAllowanceAmount?: AmountValue;
+    globalAllowanceReason?: string;
+    prepayment?: AmountValue;
 }): Record<string, unknown>;
-/** Crée une ligne de poste (aligné sur LigneDePoste de models.py).
- * Pour le taux TVA: soit tauxTva (code ex: "TVA20") soit tauxTvaManuel (valeur ex: 20.00) */
-export declare function ligneDePoste(numero: number, denomination: string, quantite: MontantValue, montantUnitaireHt: MontantValue, montantTotalLigneHt: MontantValue, options?: {
-    tauxTva?: string;
-    tauxTvaManuel?: MontantValue;
-    categorieTva?: string;
-    unite?: string;
+/** Creates an invoice line (aligned with InvoiceLine in models.py).
+ * For VAT rate: either vatRate (code e.g.: "VAT20") or manualVatRate (value e.g.: 20.00) */
+export declare function invoiceLine(lineNumber: number, itemName: string, quantity: AmountValue, unitNetPrice: AmountValue, lineNetAmount: AmountValue, options?: {
+    vatRate?: string;
+    manualVatRate?: AmountValue;
+    vatCategory?: string;
+    unit?: string;
     reference?: string;
-    montantRemiseHt?: MontantValue;
-    codeRaisonReduction?: string;
-    raisonReduction?: string;
-    dateDebutPeriode?: string;
-    dateFinPeriode?: string;
+    lineAllowanceAmount?: AmountValue;
+    allowanceReasonCode?: string;
+    allowanceReason?: string;
+    periodStartDate?: string;
+    periodEndDate?: string;
 }): Record<string, unknown>;
-/** Crée une ligne de TVA (aligné sur LigneDeTVA de models.py).
- * Pour le taux: soit taux (code ex: "TVA20") soit tauxManuel (valeur ex: 20.00) */
-export declare function ligneDeTva(montantBaseHt: MontantValue, montantTva: MontantValue, options?: {
-    taux?: string;
-    tauxManuel?: MontantValue;
-    categorie?: string;
+/** Creates a VAT line (aligned with VATLine in models.py).
+ * For rate: either rate (code e.g.: "VAT20") or manualRate (value e.g.: 20.00) */
+export declare function vatLine(taxableAmount: AmountValue, vatAmount: AmountValue, options?: {
+    rate?: string;
+    manualRate?: AmountValue;
+    category?: string;
 }): Record<string, unknown>;
-/** Crée une adresse postale pour l'API FactPulse. */
-export declare function adressePostale(ligne1: string, codePostal: string, ville: string, options?: {
-    pays?: string;
-    ligne2?: string;
-    ligne3?: string;
+/** Creates a postal address for the FactPulse API. */
+export declare function postalAddress(lineOne: string, postalCode: string, city: string, options?: {
+    countryCode?: string;
+    lineTwo?: string;
+    lineThree?: string;
 }): Record<string, unknown>;
-/** Crée une adresse électronique pour l'API FactPulse. schemeId: "0009"=SIREN, "0225"=SIRET */
-export declare function adresseElectronique(identifiant: string, schemeId?: string): Record<string, unknown>;
-/** Crée un fournisseur (émetteur) avec auto-calcul SIREN, TVA intracommunautaire et adresses. */
-export declare function fournisseur(nom: string, siret: string, adresseLigne1: string, codePostal: string, ville: string, options?: {
-    idFournisseur?: number;
+/** Creates an electronic address for the FactPulse API. schemeId: "0009"=SIREN, "0225"=SIRET */
+export declare function electronicAddress(identifier: string, schemeId?: string): Record<string, unknown>;
+/** Creates a supplier (issuer) with auto-computed SIREN, intra-EU VAT number and addresses. */
+export declare function supplier(name: string, siret: string, addressLine1: string, postalCode: string, city: string, options?: {
+    supplierId?: number;
     siren?: string;
-    numeroTvaIntra?: string;
+    vatNumber?: string;
     iban?: string;
-    pays?: string;
-    adresseLigne2?: string;
-    codeService?: number;
-    codeCoordonnesBancaires?: number;
+    countryCode?: string;
+    addressLine2?: string;
+    supplierServiceId?: number;
+    supplierBankDetailsCode?: number;
 }): Record<string, unknown>;
-/** Crée un destinataire (client) avec auto-calcul SIREN et adresses. */
-export declare function destinataire(nom: string, siret: string, adresseLigne1: string, codePostal: string, ville: string, options?: {
+/** Creates a recipient (customer) with auto-computed SIREN and addresses. */
+export declare function recipient(name: string, siret: string, addressLine1: string, postalCode: string, city: string, options?: {
     siren?: string;
-    pays?: string;
-    adresseLigne2?: string;
-    codeServiceExecutant?: string;
+    countryCode?: string;
+    addressLine2?: string;
+    executingServiceCode?: string;
 }): Record<string, unknown>;
 /**
- * Crée un bénéficiaire (factor) pour l'affacturage.
+ * Creates a beneficiary (factor) for factoring.
  *
- * Le bénéficiaire (BG-10 / PayeeTradeParty) est utilisé lorsque le paiement
- * doit être effectué à un tiers différent du fournisseur, typiquement un
- * factor (société d'affacturage).
+ * The beneficiary (BG-10 / PayeeTradeParty) is used when payment
+ * must be made to a third party different from the supplier, typically
+ * a factor (factoring company).
  *
- * Pour les factures affacturées, il faut aussi:
- * - Utiliser un type de document affacturé (393, 396, 501, 502, 472, 473)
- * - Ajouter une note ACC avec la mention de subrogation
- * - L'IBAN du bénéficiaire sera utilisé pour le paiement
+ * For factored invoices, you also need to:
+ * - Use a factored document type (393, 396, 501, 502, 472, 473)
+ * - Add an ACC note with the subrogation mention
+ * - The beneficiary's IBAN will be used for payment
  *
- * @param nom Raison sociale du factor (BT-59)
+ * @param name Factor's business name (BT-59)
  * @param options Options: siret (BT-60), siren (BT-61), iban, bic
- * @returns Dict prêt à être utilisé dans une facture affacturée
+ * @returns Dict ready to be used in a factored invoice
  *
  * @example
- * const factor = beneficiaire('FACTOR SAS', {
+ * const factor = beneficiary('FACTOR SAS', {
  *   siret: '30000000700033',
  *   iban: 'FR76 3000 4000 0500 0012 3456 789',
  * });
  */
-export declare function beneficiaire(nom: string, options?: {
+export declare function beneficiary(name: string, options?: {
     siret?: string;
     siren?: string;
     iban?: string;
@@ -126,130 +126,130 @@ export declare class FactPulseClient {
     ensureAuthenticated(forceRefresh?: boolean): Promise<void>;
     resetAuth(): void;
     pollTask(taskId: string, timeout?: number, interval?: number): Promise<Record<string, unknown>>;
-    genererFacturx(factureData: Record<string, unknown> | string, pdfPath: string, profil?: string, formatSortie?: string, sync?: boolean, timeout?: number): Promise<Buffer | string>;
-    static formatMontant(m: unknown): string;
+    generateFacturx(invoiceData: Record<string, unknown> | string, pdfPath: string, profile?: string, outputFormat?: string, sync?: boolean, timeout?: number): Promise<Buffer | string>;
+    static formatAmount(m: unknown): string;
     /**
-     * Recupere les credentials AFNOR (mode stored ou zero-trust).
-     * Mode zero-trust: Retourne les afnorCredentials fournis au constructeur.
-     * Mode stored: Recupere les credentials via GET /api/v1/afnor/credentials.
+     * Retrieves AFNOR credentials (stored or zero-trust mode).
+     * Zero-trust mode: Returns the afnorCredentials provided to the constructor.
+     * Stored mode: Retrieves credentials via GET /api/v1/afnor/credentials.
      */
     private getAfnorCredentialsInternal;
     /**
-     * Obtient le token OAuth2 AFNOR et l'URL de la PDP.
-     * Cette methode:
-     * 1. Recupere les credentials AFNOR (mode stored ou zero-trust)
-     * 2. Fait l'OAuth AFNOR pour obtenir un token
-     * 3. Retourne le token et l'URL de la PDP
+     * Obtains the AFNOR OAuth2 token and the PDP URL.
+     * This method:
+     * 1. Retrieves AFNOR credentials (stored or zero-trust mode)
+     * 2. Performs AFNOR OAuth to obtain a token
+     * 3. Returns the token and the PDP URL
      */
     private getAfnorTokenAndUrl;
     /**
-     * Effectue une requete vers l'API AFNOR avec gestion d'auth et d'erreurs.
-     * IMPORTANT: Cette methode utilise le token OAuth AFNOR, PAS le JWT FactPulse!
+     * Performs a request to the AFNOR API with auth and error handling.
+     * IMPORTANT: This method uses the AFNOR OAuth token, NOT the FactPulse JWT!
      */
     private makeAfnorRequest;
     rechercherSiretAfnor(siret: string): Promise<Record<string, unknown>>;
     rechercherSirenAfnor(siren: string): Promise<Record<string, unknown>>;
     listerCodesRoutageAfnor(siren: string): Promise<unknown[]>;
     /**
-     * Soumet une facture a une PDP via l'API AFNOR.
-     * L'authentification utilise le token OAuth AFNOR (obtenu automatiquement),
-     * soit via les credentials stockes (mode stored), soit via les afnorCredentials
-     * fournis au constructeur (mode zero-trust).
+     * Submits an invoice to a PDP via the AFNOR API.
+     * Authentication uses the AFNOR OAuth token (obtained automatically),
+     * either via stored credentials (stored mode), or via the afnorCredentials
+     * provided to the constructor (zero-trust mode).
      *
-     * @param pdfBuffer Buffer du PDF Factur-X a soumettre
-     * @param flowName Nom du flux (ex: "Facture FAC-2025-001")
+     * @param pdfBuffer Buffer of the Factur-X PDF to submit
+     * @param flowName Flow name (e.g.: "Invoice INV-2025-001")
      * @param options Options: trackingId, flowSyntax (CII/UBL), flowProfile
      */
-    soumettreFactureAfnor(pdfBuffer: Buffer, flowName: string, options?: {
+    submitInvoiceAfnor(pdfBuffer: Buffer, flowName: string, options?: {
         trackingId?: string;
         flowSyntax?: string;
         flowProfile?: string;
     }): Promise<Record<string, unknown>>;
-    rechercherFluxAfnor(criteria?: {
+    searchFlowsAfnor(criteria?: {
         trackingId?: string;
         status?: string;
         offset?: number;
         limit?: number;
     }): Promise<Record<string, unknown>>;
-    telechargerFluxAfnor(flowId: string): Promise<Buffer>;
+    downloadFlowAfnor(flowId: string): Promise<Buffer>;
     /**
-     * Récupère les métadonnées JSON d'un flux entrant (facture fournisseur).
-     * 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 Factur-X, CII et UBL.
+     * Retrieves JSON metadata of an incoming flow (supplier invoice).
+     * Downloads an incoming flow from the AFNOR PDP and extracts invoice
+     * metadata into a unified JSON format. Supports Factur-X, CII and UBL.
      *
-     * Note: Cet endpoint utilise l'authentification JWT FactPulse (pas OAuth AFNOR).
-     * Le serveur FactPulse se charge d'appeler la PDP avec les credentials stockés.
+     * Note: This endpoint uses FactPulse JWT authentication (not AFNOR OAuth).
+     * The FactPulse server handles calling the PDP with stored credentials.
      *
-     * @param flowId Identifiant du flux (UUID)
-     * @param includeDocument Si true, inclut le document original encodé en base64
-     * @returns Métadonnées de la facture (fournisseur, montants, dates, etc.)
+     * @param flowId Flow identifier (UUID)
+     * @param includeDocument If true, includes the original document encoded in base64
+     * @returns Invoice metadata (supplier, amounts, dates, etc.)
      *
      * @example
-     * const facture = await client.obtenirFactureEntranteAfnor("550e8400-...");
-     * console.log(`Fournisseur: ${facture.fournisseur.nom}`);
-     * console.log(`Montant TTC: ${facture.montant_ttc} ${facture.devise}`);
+     * const invoice = await client.getIncomingInvoiceAfnor("550e8400-...");
+     * console.log(`Supplier: ${invoice.supplier.name}`);
+     * console.log(`Total incl. tax: ${invoice.total_incl_tax} ${invoice.currency}`);
      */
-    obtenirFactureEntranteAfnor(flowId: string, includeDocument?: boolean): Promise<Record<string, unknown>>;
+    getIncomingInvoiceAfnor(flowId: string, includeDocument?: boolean): Promise<Record<string, unknown>>;
     healthcheckAfnor(): Promise<Record<string, unknown>>;
     rechercherStructureChorus(criteria: Record<string, unknown>): Promise<unknown[]>;
     consulterStructureChorus(idStructureCpp: number): Promise<Record<string, unknown>>;
     /**
-     * Liste les services d'une structure Chorus Pro.
-     * @param idStructureCpp ID Chorus Pro de la structure
-     * @returns Objet avec listeServices, total, codeRetour, libelle
+     * Lists the services of a Chorus Pro structure.
+     * @param idStructureCpp Chorus Pro ID of the structure
+     * @returns Object with listeServices, total, codeRetour, libelle
      */
     listerServicesStructureChorus(idStructureCpp: number): Promise<Record<string, unknown>>;
     obtenirIdChorusDepuisSiret(siret: string): Promise<number | null>;
-    soumettreFactureChorus(factureData: Record<string, unknown>): Promise<Record<string, unknown>>;
-    consulterFactureChorus(identifiantFactureCpp: number): Promise<Record<string, unknown>>;
+    submitInvoiceChorus(invoiceData: Record<string, unknown>): Promise<Record<string, unknown>>;
+    lookupInvoiceChorus(invoiceIdCpp: number): Promise<Record<string, unknown>>;
     /**
-     * Valide un PDF Factur-X.
-     * @param pdfBuffer - Contenu du PDF en Buffer
-     * @param options - Options de validation
-     * @param options.profil - Profil Factur-X (MINIMUM, BASIC, EN16931, EXTENDED). Si non spécifié, auto-détecté.
-     * @param options.useVerapdf - Active la validation stricte PDF/A avec VeraPDF (défaut: false)
+     * Validates a Factur-X PDF.
+     * @param pdfBuffer - PDF content as Buffer
+     * @param options - Validation options
+     * @param options.profile - Factur-X profile (MINIMUM, BASIC, EN16931, EXTENDED). If not specified, auto-detected.
+     * @param options.useVerapdf - Enable strict PDF/A validation with VeraPDF (default: false)
      */
-    validerPdfFacturx(pdfBuffer: Buffer, options?: {
-        profil?: string;
+    validateFacturxPdf(pdfBuffer: Buffer, options?: {
+        profile?: string;
         useVerapdf?: boolean;
     }): Promise<Record<string, unknown>>;
-    validerXmlFacturx(xmlContent: string, profil?: string): Promise<Record<string, unknown>>;
-    validerSignaturePdf(pdfBuffer: Buffer): Promise<Record<string, unknown>>;
+    validateFacturxXml(xmlContent: string, profile?: string): Promise<Record<string, unknown>>;
+    validatePdfSignature(pdfBuffer: Buffer): Promise<Record<string, unknown>>;
     /**
-     * Signe un PDF avec le certificat configuré côté serveur (via client_uid du JWT).
-     * Le certificat doit être préalablement configuré dans Django Admin.
+     * Signs a PDF with the server-configured certificate (via JWT client_uid).
+     * The certificate must be previously configured in Django Admin.
      */
-    signerPdf(pdfBuffer: Buffer, options?: {
-        raison?: string;
-        localisation?: string;
+    signPdf(pdfBuffer: Buffer, options?: {
+        reason?: string;
+        location?: string;
         contact?: string;
         usePadesLt?: boolean;
         useTimestamp?: boolean;
     }): Promise<Buffer>;
     /**
-     * Génère un certificat de test (NON PRODUCTION).
-     * Le certificat doit ensuite être configuré dans Django Admin.
+     * Generates a test certificate (NOT FOR PRODUCTION).
+     * The certificate must then be configured in Django Admin.
      */
-    genererCertificatTest(options?: {
+    generateTestCertificate(options?: {
         cn?: string;
         organisation?: string;
         email?: string;
-        dureeJours?: number;
-        tailleClé?: number;
+        validityDays?: number;
+        keySize?: number;
     }): Promise<Record<string, unknown>>;
     /**
-     * Workflow complet : génération + validation + signature + soumission AFNOR.
-     * Note: La signature utilise le certificat configuré côté serveur (via client_uid du JWT).
-     * @param factureData Données de la facture
-     * @param pdfPath Chemin vers le PDF source
-     * @param options Options du workflow
-     * @returns Résultat avec pdfBuffer, validation, signature et afnor
+     * Complete workflow: generation + validation + signature + AFNOR submission.
+     * Note: Signature uses the server-configured certificate (via JWT client_uid).
+     * @param invoiceData Invoice data
+     * @param pdfPath Path to the source PDF
+     * @param options Workflow options
+     * @returns Result with pdfBuffer, validation, signature and afnor
      */
-    genererFacturxComplet(factureData: Record<string, unknown>, pdfPath: string, options?: {
-        profil?: string;
-        valider?: boolean;
-        signer?: boolean;
-        soumettreAfnor?: boolean;
+    generateCompleteFacturx(invoiceData: Record<string, unknown>, pdfPath: string, options?: {
+        profile?: string;
+        validate?: boolean;
+        sign?: boolean;
+        submitAfnor?: boolean;
         afnorFlowName?: string;
         afnorTrackingId?: string;
         timeout?: number;
@@ -257,7 +257,7 @@ export declare class FactPulseClient {
         pdfBuffer: Buffer;
         validation?: Record<string, unknown>;
         signature?: {
-            signe: boolean;
+            signed: boolean;
         };
         afnor?: Record<string, unknown>;
     }>;