@scell/sdk 1.0.0 → 1.2.0

package/README.md

@@ -259,6 +259,57 @@ const { data: trail, integrity_valid } = await apiClient.invoices.auditTrail(inv
 await apiClient.invoices.convert({ invoice_id: invoiceId, target_format: 'ubl' });
 ```
 
+### Incoming Invoices (Supplier Invoices)
+
+```typescript
+// List incoming invoices
+const { data: incoming, meta } = await apiClient.invoices.incoming({
+  status: 'pending',
+  seller_siret: '12345678901234',
+  from: '2024-01-01',
+  min_amount: 100,
+  per_page: 50,
+});
+
+console.log(`Found ${meta.total} incoming invoices`);
+
+// Accept an incoming invoice
+const { data: accepted } = await apiClient.invoices.accept(invoiceId, {
+  payment_date: '2024-02-15',
+  note: 'Approved by accounting department',
+});
+
+// Reject an incoming invoice
+const { data: rejected } = await apiClient.invoices.reject(invoiceId, {
+  reason: 'Invoice amount does not match purchase order #PO-2024-001',
+  reason_code: 'incorrect_amount',
+});
+
+// Dispute an incoming invoice
+const { data: disputed } = await apiClient.invoices.dispute(invoiceId, {
+  reason: 'Billed amount exceeds agreed price by 50 EUR',
+  dispute_type: 'amount_dispute',
+  expected_amount: 950.00,
+});
+
+// Mark an invoice as paid (mandatory in French e-invoicing lifecycle)
+const { data: paidInvoice } = await apiClient.invoices.markPaid(invoiceId, {
+  payment_reference: 'VIR-2026-0124',
+  paid_at: '2026-01-24T10:30:00Z',
+  note: 'Payment received via bank transfer',
+});
+
+// Download invoice file as PDF (Factur-X with embedded XML)
+const pdfBuffer = await apiClient.invoices.downloadFile(invoiceId);
+// In Node.js:
+import { writeFileSync } from 'fs';
+writeFileSync('invoice.pdf', Buffer.from(pdfBuffer));
+
+// Download XML version (UBL/CII standalone)
+const xmlBuffer = await apiClient.invoices.downloadFile(invoiceId, 'xml');
+writeFileSync('invoice.xml', Buffer.from(xmlBuffer));
+```
+
 ### Signatures
 
 ```typescript
@@ -412,6 +463,12 @@ const result = await withRetry(
 | `invoice.accepted` | Invoice accepted |
 | `invoice.rejected` | Invoice rejected |
 | `invoice.error` | Invoice processing error |
+| `invoice.incoming.received` | Incoming invoice received from supplier |
+| `invoice.incoming.validated` | Incoming invoice validated |
+| `invoice.incoming.accepted` | Incoming invoice accepted |
+| `invoice.incoming.rejected` | Incoming invoice rejected |
+| `invoice.incoming.disputed` | Incoming invoice disputed |
+| `invoice.incoming.paid` | Incoming invoice marked as paid |
 | `signature.created` | Signature request created |
 | `signature.waiting` | Waiting for signers |
 | `signature.signed` | A signer has signed |
@@ -431,17 +488,30 @@ import type {
   Invoice,
   InvoiceStatus,
   InvoiceDirection,
+  InvoiceFileFormat,
   CreateInvoiceInput,
+  // Incoming invoices
+  IncomingInvoiceParams,
+  AcceptInvoiceInput,
+  RejectInvoiceInput,
+  DisputeInvoiceInput,
+  MarkPaidInput,
+  RejectionCode,
+  DisputeType,
+  // Signatures
   Signature,
   SignatureStatus,
   CreateSignatureInput,
   Signer,
-  Company,
-  Balance,
-  Transaction,
+  // Webhooks
   Webhook,
   WebhookEvent,
   WebhookPayload,
+  InvoiceIncomingPaidPayload,
+  // Other
+  Company,
+  Balance,
+  Transaction,
 } from '@scell/sdk';
 ```
 

package/dist/index.d.mts

@@ -131,6 +131,17 @@ declare class HttpClient {
      * DELETE request
      */
     delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * GET request that returns raw binary data as ArrayBuffer
+     *
+     * Use this for downloading files (PDF, XML, etc.)
+     *
+     * @param path - API endpoint path
+     * @param query - Query parameters
+     * @param options - Request options
+     * @returns ArrayBuffer containing the file content
+     */
+    getRaw(path: string, query?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<ArrayBuffer>;
 }
 
 /**
@@ -996,7 +1007,7 @@ type InvoiceFormat = 'facturx' | 'ubl' | 'cii';
 /**
  * Invoice status
  */
-type InvoiceStatus = 'draft' | 'pending' | 'validated' | 'converted' | 'transmitted' | 'accepted' | 'rejected' | 'error';
+type InvoiceStatus = 'draft' | 'pending' | 'validated' | 'converted' | 'transmitted' | 'accepted' | 'rejected' | 'paid' | 'disputed' | 'cancelled' | 'error';
 /**
  * Invoice download file type
  */
@@ -1049,6 +1060,12 @@ interface Invoice {
     validated_at: DateTimeString | null;
     transmitted_at: DateTimeString | null;
     completed_at: DateTimeString | null;
+    /** Date when the invoice was marked as paid (ISO 8601) */
+    paid_at: DateTimeString | null;
+    /** Payment reference (bank transfer ID, check number, etc.) */
+    payment_reference: string | null;
+    /** Optional note about the payment */
+    payment_note: string | null;
 }
 /**
  * Invoice line input for creation
@@ -1145,6 +1162,71 @@ interface AuditTrailResponse {
     data: AuditTrailEntry[];
     integrity_valid: boolean;
 }
+/**
+ * Incoming invoice list filter options
+ */
+interface IncomingInvoiceParams {
+    status?: InvoiceStatus | undefined;
+    seller_siret?: Siret | undefined;
+    from?: DateString | undefined;
+    to?: DateString | undefined;
+    min_amount?: number | undefined;
+    max_amount?: number | undefined;
+    page?: number | undefined;
+    per_page?: number | undefined;
+}
+/**
+ * Rejection reason code for incoming invoices
+ */
+type RejectionCode = 'incorrect_amount' | 'duplicate' | 'unknown_order' | 'incorrect_vat' | 'other';
+/**
+ * Dispute type for incoming invoices
+ */
+type DisputeType = 'amount_dispute' | 'quality_dispute' | 'delivery_dispute' | 'other';
+/**
+ * Input for accepting an incoming invoice
+ */
+interface AcceptInvoiceInput {
+    /** Expected payment date (YYYY-MM-DD) */
+    payment_date?: DateString | undefined;
+    /** Optional note about the acceptance */
+    note?: string | undefined;
+}
+/**
+ * Input for rejecting an incoming invoice
+ */
+interface RejectInvoiceInput {
+    /** Reason for rejection */
+    reason: string;
+    /** Standardized rejection code */
+    reason_code: RejectionCode;
+}
+/**
+ * Input for disputing an incoming invoice
+ */
+interface DisputeInvoiceInput {
+    /** Reason for the dispute */
+    reason: string;
+    /** Type of dispute */
+    dispute_type: DisputeType;
+    /** Expected correct amount (if amount dispute) */
+    expected_amount?: number | undefined;
+}
+/**
+ * Input for marking an incoming invoice as paid
+ */
+interface MarkPaidInput {
+    /** Payment reference (bank transfer ID, check number, etc.) */
+    payment_reference?: string | undefined;
+    /** Payment date (ISO 8601) - defaults to current date/time if not provided */
+    paid_at?: DateTimeString | undefined;
+    /** Optional note about the payment */
+    note?: string | undefined;
+}
+/**
+ * Invoice file download format
+ */
+type InvoiceFileFormat = 'pdf' | 'xml';
 
 /**
  * Invoices Resource
@@ -1319,6 +1401,152 @@ declare class InvoicesResource {
         invoice_id: string;
         target_format: string;
     }>;
+    /**
+     * List incoming invoices (from suppliers)
+     *
+     * Returns invoices where your company is the buyer.
+     *
+     * @param params - Filter and pagination options
+     * @param requestOptions - Request options
+     * @returns Paginated list of incoming invoices
+     *
+     * @example
+     * ```typescript
+     * // List all incoming invoices
+     * const { data, meta } = await client.invoices.incoming({
+     *   status: 'pending',
+     *   per_page: 50
+     * });
+     * console.log(`Found ${meta.total} incoming invoices`);
+     *
+     * // Filter by seller
+     * const fromSupplier = await client.invoices.incoming({
+     *   seller_siret: '12345678901234'
+     * });
+     * ```
+     */
+    incoming(params?: IncomingInvoiceParams, requestOptions?: RequestOptions): Promise<PaginatedResponse<Invoice>>;
+    /**
+     * Accept an incoming invoice
+     *
+     * Mark an incoming invoice as accepted, optionally specifying a payment date.
+     *
+     * @param id - Invoice UUID
+     * @param data - Optional acceptance data
+     * @param requestOptions - Request options
+     * @returns Updated invoice
+     *
+     * @example
+     * ```typescript
+     * // Accept with payment date
+     * const { data: invoice } = await client.invoices.accept('invoice-uuid', {
+     *   payment_date: '2024-02-15',
+     *   note: 'Approved by accounting'
+     * });
+     *
+     * // Simple acceptance
+     * await client.invoices.accept('invoice-uuid');
+     * ```
+     */
+    accept(id: string, data?: AcceptInvoiceInput, requestOptions?: RequestOptions): Promise<SingleResponse<Invoice>>;
+    /**
+     * Reject an incoming invoice
+     *
+     * Mark an incoming invoice as rejected with a reason.
+     *
+     * @param id - Invoice UUID
+     * @param data - Rejection details
+     * @param requestOptions - Request options
+     * @returns Updated invoice
+     *
+     * @example
+     * ```typescript
+     * const { data: invoice } = await client.invoices.reject('invoice-uuid', {
+     *   reason: 'Invoice amount does not match purchase order',
+     *   reason_code: 'incorrect_amount'
+     * });
+     * ```
+     */
+    reject(id: string, data: RejectInvoiceInput, requestOptions?: RequestOptions): Promise<SingleResponse<Invoice>>;
+    /**
+     * Dispute an incoming invoice
+     *
+     * Open a dispute on an incoming invoice for resolution.
+     *
+     * @param id - Invoice UUID
+     * @param data - Dispute details
+     * @param requestOptions - Request options
+     * @returns Updated invoice
+     *
+     * @example
+     * ```typescript
+     * const { data: invoice } = await client.invoices.dispute('invoice-uuid', {
+     *   reason: 'Billed amount exceeds agreed price',
+     *   dispute_type: 'amount_dispute',
+     *   expected_amount: 950.00
+     * });
+     * ```
+     */
+    dispute(id: string, data: DisputeInvoiceInput, requestOptions?: RequestOptions): Promise<SingleResponse<Invoice>>;
+    /**
+     * Mark an incoming invoice as paid
+     *
+     * This is a mandatory step in the French e-invoicing lifecycle for incoming invoices.
+     * Once marked as paid, the invoice status changes to 'paid' and payment details are recorded.
+     *
+     * @param id - Invoice UUID
+     * @param data - Optional payment details (reference, date, note)
+     * @param requestOptions - Request options
+     * @returns Updated invoice with payment information
+     *
+     * @example
+     * ```typescript
+     * // Mark as paid with payment details
+     * const { data: invoice } = await client.invoices.markPaid('invoice-uuid', {
+     *   payment_reference: 'VIR-2026-0124',
+     *   paid_at: '2026-01-24T10:30:00Z',
+     *   note: 'Payment received via bank transfer'
+     * });
+     *
+     * // Simple mark as paid (uses current date/time)
+     * await client.invoices.markPaid('invoice-uuid');
+     * ```
+     */
+    markPaid(id: string, data?: MarkPaidInput, requestOptions?: RequestOptions): Promise<SingleResponse<Invoice>>;
+    /**
+     * Download invoice source file as binary content
+     *
+     * Downloads the original invoice file (PDF with embedded XML for Factur-X,
+     * or standalone XML for UBL/CII formats).
+     *
+     * @param id - Invoice UUID
+     * @param format - File format to download: 'pdf' (default) or 'xml'
+     * @param requestOptions - Request options
+     * @returns ArrayBuffer containing the file content
+     *
+     * @example
+     * ```typescript
+     * // Download invoice as PDF (Factur-X)
+     * const pdfBuffer = await client.invoices.downloadFile('invoice-uuid');
+     *
+     * // In Node.js, save to file:
+     * import { writeFileSync } from 'fs';
+     * writeFileSync('invoice.pdf', Buffer.from(pdfBuffer));
+     *
+     * // Download XML version (UBL/CII)
+     * const xmlBuffer = await client.invoices.downloadFile('invoice-uuid', 'xml');
+     * writeFileSync('invoice.xml', Buffer.from(xmlBuffer));
+     *
+     * // In browser, trigger download:
+     * const blob = new Blob([pdfBuffer], { type: 'application/pdf' });
+     * const url = URL.createObjectURL(blob);
+     * const a = document.createElement('a');
+     * a.href = url;
+     * a.download = 'invoice.pdf';
+     * a.click();
+     * ```
+     */
+    downloadFile(id: string, format?: InvoiceFileFormat, requestOptions?: RequestOptions): Promise<ArrayBuffer>;
 }
 
 /**
@@ -1627,7 +1855,7 @@ declare class SignaturesResource {
 /**
  * Available webhook events
  */
-type WebhookEvent = 'invoice.created' | 'invoice.validated' | 'invoice.transmitted' | 'invoice.accepted' | 'invoice.rejected' | 'invoice.error' | 'signature.created' | 'signature.waiting' | 'signature.signed' | 'signature.completed' | 'signature.refused' | 'signature.expired' | 'signature.error' | 'balance.low' | 'balance.critical';
+type WebhookEvent = 'invoice.created' | 'invoice.validated' | 'invoice.transmitted' | 'invoice.accepted' | 'invoice.rejected' | 'invoice.error' | 'invoice.incoming.received' | 'invoice.incoming.validated' | 'invoice.incoming.accepted' | 'invoice.incoming.rejected' | 'invoice.incoming.disputed' | 'invoice.incoming.paid' | 'signature.created' | 'signature.waiting' | 'signature.signed' | 'signature.completed' | 'signature.refused' | 'signature.expired' | 'signature.error' | 'balance.low' | 'balance.critical';
 /**
  * Webhook entity
  */
@@ -1739,6 +1967,27 @@ interface BalanceWebhookData {
     currency: string;
     threshold: number;
 }
+/**
+ * Invoice incoming paid webhook payload data
+ */
+interface InvoiceIncomingPaidPayload {
+    /** Invoice UUID */
+    invoice_id: string;
+    /** Invoice number */
+    invoice_number: string;
+    /** Seller company name */
+    seller_name: string;
+    /** Seller SIRET (14 digits) */
+    seller_siret: string;
+    /** Total amount including tax */
+    total_amount: number;
+    /** Currency code (ISO 4217) */
+    currency: string;
+    /** Date when the invoice was marked as paid (ISO 8601) */
+    paid_at: string;
+    /** Payment reference (if provided) */
+    payment_reference?: string | undefined;
+}
 
 /**
  * Webhooks Resource
@@ -2289,4 +2538,4 @@ declare class ScellApiClient {
     constructor(apiKey: string, config?: ClientConfig);
 }
 
-export { type Address, type ApiErrorResponse, type ApiKey, type ApiKeyWithSecret, type AuditTrailEntry, type AuditTrailResponse, type AuthResponse, type Balance, type BalanceWebhookData, type ClientConfig, type Company, type CompanyStatus, type ConvertInvoiceInput, type CreateApiKeyInput, type CreateCompanyInput, type CreateInvoiceInput, type CreateSignatureInput, type CreateWebhookInput, type CurrencyCode, type DateRangeOptions, type DateString, type DateTimeString, type Environment, type ForgotPasswordInput, type Invoice, type InvoiceDirection, type InvoiceDownloadResponse, type InvoiceDownloadType, type InvoiceFormat, type InvoiceLine, type InvoiceLineInput, type InvoiceListOptions, type InvoiceParty, type InvoiceStatus, type InvoiceWebhookData, type KycInitiateResponse, type KycStatusResponse, type LoginCredentials, type MessageResponse, type MessageWithDataResponse, type PaginatedResponse, type PaginationMeta, type PaginationOptions, type RegisterInput, type ReloadBalanceInput, type ReloadBalanceResponse, type ResetPasswordInput, type RetryOptions, ScellApiClient, ScellAuth, ScellAuthenticationError, ScellAuthorizationError, ScellClient, ScellError, ScellInsufficientBalanceError, ScellNetworkError, ScellNotFoundError, ScellRateLimitError, ScellServerError, ScellTimeoutError, ScellValidationError, ScellWebhooks, type Signature, type SignatureDownloadResponse, type SignatureDownloadType, type SignatureListOptions, type SignaturePosition, type SignatureRemindResponse, type SignatureStatus, type SignatureUIConfig, type SignatureWebhookData, type Signer, type SignerAuthMethod, type SignerInput, type SignerStatus, type SingleResponse, type Siren, type Siret, type Transaction, type TransactionListOptions, type TransactionService, type TransactionType, type UUID, type UpdateBalanceSettingsInput, type UpdateCompanyInput, type UpdateWebhookInput, type User, type VerifySignatureOptions, type Webhook, type WebhookEvent, type WebhookListOptions, type WebhookLog, type WebhookPayload, type WebhookTestResponse, type WebhookWithSecret, createRetryWrapper, withRetry };
+export { type AcceptInvoiceInput, type Address, type ApiErrorResponse, type ApiKey, type ApiKeyWithSecret, type AuditTrailEntry, type AuditTrailResponse, type AuthResponse, type Balance, type BalanceWebhookData, type ClientConfig, type Company, type CompanyStatus, type ConvertInvoiceInput, type CreateApiKeyInput, type CreateCompanyInput, type CreateInvoiceInput, type CreateSignatureInput, type CreateWebhookInput, type CurrencyCode, type DateRangeOptions, type DateString, type DateTimeString, type DisputeInvoiceInput, type DisputeType, type Environment, type ForgotPasswordInput, type IncomingInvoiceParams, type Invoice, type InvoiceDirection, type InvoiceDownloadResponse, type InvoiceDownloadType, type InvoiceFileFormat, type InvoiceFormat, type InvoiceIncomingPaidPayload, type InvoiceLine, type InvoiceLineInput, type InvoiceListOptions, type InvoiceParty, type InvoiceStatus, type InvoiceWebhookData, type KycInitiateResponse, type KycStatusResponse, type LoginCredentials, type MarkPaidInput, type MessageResponse, type MessageWithDataResponse, type PaginatedResponse, type PaginationMeta, type PaginationOptions, type RegisterInput, type RejectInvoiceInput, type RejectionCode, type ReloadBalanceInput, type ReloadBalanceResponse, type ResetPasswordInput, type RetryOptions, ScellApiClient, ScellAuth, ScellAuthenticationError, ScellAuthorizationError, ScellClient, ScellError, ScellInsufficientBalanceError, ScellNetworkError, ScellNotFoundError, ScellRateLimitError, ScellServerError, ScellTimeoutError, ScellValidationError, ScellWebhooks, type Signature, type SignatureDownloadResponse, type SignatureDownloadType, type SignatureListOptions, type SignaturePosition, type SignatureRemindResponse, type SignatureStatus, type SignatureUIConfig, type SignatureWebhookData, type Signer, type SignerAuthMethod, type SignerInput, type SignerStatus, type SingleResponse, type Siren, type Siret, type Transaction, type TransactionListOptions, type TransactionService, type TransactionType, type UUID, type UpdateBalanceSettingsInput, type UpdateCompanyInput, type UpdateWebhookInput, type User, type VerifySignatureOptions, type Webhook, type WebhookEvent, type WebhookListOptions, type WebhookLog, type WebhookPayload, type WebhookTestResponse, type WebhookWithSecret, createRetryWrapper, withRetry };