@scell/sdk 1.0.0 → 1.2.0

package/src/client.ts

@@ -294,4 +294,80 @@ export class HttpClient {
       ...options,
     });
   }
+
+  /**
+   * 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
+   */
+  async getRaw(
+    path: string,
+    query?: Record<string, string | number | boolean | undefined>,
+    options?: RequestOptions
+  ): Promise<ArrayBuffer> {
+    const url = this.buildUrl(path, query);
+    const requestHeaders = this.buildHeaders(options?.headers);
+    const requestTimeout = options?.timeout ?? this.timeout;
+
+    // Remove JSON content-type for raw requests
+    delete requestHeaders['Content-Type'];
+    requestHeaders['Accept'] = '*/*';
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), requestTimeout);
+
+    if (options?.signal) {
+      options.signal.addEventListener('abort', () => controller.abort());
+    }
+
+    try {
+      const response = await this.fetchFn(url, {
+        method: 'GET',
+        headers: requestHeaders,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        // Try to parse error as JSON
+        const contentType = response.headers.get('Content-Type') ?? '';
+        let responseBody: unknown;
+
+        if (contentType.includes('application/json')) {
+          responseBody = await response.json();
+        } else {
+          responseBody = await response.text();
+        }
+
+        parseApiError(response.status, responseBody, response.headers);
+      }
+
+      return response.arrayBuffer();
+    } catch (error) {
+      clearTimeout(timeoutId);
+
+      if (error instanceof Error) {
+        if (error.name === 'AbortError') {
+          throw new ScellTimeoutError(
+            `Request timed out after ${requestTimeout}ms`
+          );
+        }
+
+        if (
+          error.name === 'TypeError' &&
+          error.message.includes('fetch')
+        ) {
+          throw new ScellNetworkError('Network request failed', error);
+        }
+      }
+
+      throw error;
+    }
+  }
 }

package/src/resources/invoices.ts

@@ -11,13 +11,19 @@ import type {
   SingleResponse,
 } from '../types/common.js';
 import type {
+  AcceptInvoiceInput,
   AuditTrailResponse,
   ConvertInvoiceInput,
   CreateInvoiceInput,
+  DisputeInvoiceInput,
+  IncomingInvoiceParams,
   Invoice,
   InvoiceDownloadResponse,
   InvoiceDownloadType,
+  InvoiceFileFormat,
   InvoiceListOptions,
+  MarkPaidInput,
+  RejectInvoiceInput,
 } from '../types/invoices.js';
 
 /**
@@ -243,4 +249,215 @@ export class InvoicesResource {
       target_format: string;
     }>('/invoices/convert', input, requestOptions);
   }
+
+  /**
+   * 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'
+   * });
+   * ```
+   */
+  async incoming(
+    params: IncomingInvoiceParams = {},
+    requestOptions?: RequestOptions
+  ): Promise<PaginatedResponse<Invoice>> {
+    return this.http.get<PaginatedResponse<Invoice>>(
+      '/invoices/incoming',
+      params as Record<string, string | number | boolean | undefined>,
+      requestOptions
+    );
+  }
+
+  /**
+   * 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');
+   * ```
+   */
+  async accept(
+    id: string,
+    data?: AcceptInvoiceInput,
+    requestOptions?: RequestOptions
+  ): Promise<SingleResponse<Invoice>> {
+    return this.http.post<SingleResponse<Invoice>>(
+      `/invoices/${id}/accept`,
+      data,
+      requestOptions
+    );
+  }
+
+  /**
+   * 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'
+   * });
+   * ```
+   */
+  async reject(
+    id: string,
+    data: RejectInvoiceInput,
+    requestOptions?: RequestOptions
+  ): Promise<SingleResponse<Invoice>> {
+    return this.http.post<SingleResponse<Invoice>>(
+      `/invoices/${id}/reject`,
+      data,
+      requestOptions
+    );
+  }
+
+  /**
+   * 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
+   * });
+   * ```
+   */
+  async dispute(
+    id: string,
+    data: DisputeInvoiceInput,
+    requestOptions?: RequestOptions
+  ): Promise<SingleResponse<Invoice>> {
+    return this.http.post<SingleResponse<Invoice>>(
+      `/invoices/${id}/dispute`,
+      data,
+      requestOptions
+    );
+  }
+
+  /**
+   * 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');
+   * ```
+   */
+  async markPaid(
+    id: string,
+    data?: MarkPaidInput,
+    requestOptions?: RequestOptions
+  ): Promise<SingleResponse<Invoice>> {
+    return this.http.post<SingleResponse<Invoice>>(
+      `/invoices/${id}/mark-paid`,
+      data,
+      requestOptions
+    );
+  }
+
+  /**
+   * 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();
+   * ```
+   */
+  async downloadFile(
+    id: string,
+    format: InvoiceFileFormat = 'pdf',
+    requestOptions?: RequestOptions
+  ): Promise<ArrayBuffer> {
+    return this.http.getRaw(
+      `/invoices/${id}/download`,
+      { format },
+      requestOptions
+    );
+  }
 }

package/src/types/index.ts

@@ -26,20 +26,28 @@ export type {
 
 // Invoice types
 export type {
+  AcceptInvoiceInput,
   AuditTrailEntry,
   AuditTrailResponse,
   ConvertInvoiceInput,
   CreateInvoiceInput,
+  DisputeInvoiceInput,
+  DisputeType,
+  IncomingInvoiceParams,
   Invoice,
   InvoiceDirection,
   InvoiceDownloadResponse,
   InvoiceDownloadType,
+  InvoiceFileFormat,
   InvoiceFormat,
   InvoiceLine,
   InvoiceLineInput,
   InvoiceListOptions,
   InvoiceParty,
   InvoiceStatus,
+  MarkPaidInput,
+  RejectInvoiceInput,
+  RejectionCode,
 } from './invoices.js';
 
 // Signature types
@@ -85,6 +93,7 @@ export type {
 export type {
   BalanceWebhookData,
   CreateWebhookInput,
+  InvoiceIncomingPaidPayload,
   InvoiceWebhookData,
   SignatureWebhookData,
   UpdateWebhookInput,

package/src/types/invoices.ts

@@ -29,6 +29,9 @@ export type InvoiceStatus =
   | 'transmitted'
   | 'accepted'
   | 'rejected'
+  | 'paid'
+  | 'disputed'
+  | 'cancelled'
   | 'error';
 
 /**
@@ -86,6 +89,12 @@ export 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;
 }
 
 /**
@@ -189,3 +198,85 @@ export interface AuditTrailResponse {
   data: AuditTrailEntry[];
   integrity_valid: boolean;
 }
+
+/**
+ * Incoming invoice list filter options
+ */
+export 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
+ */
+export type RejectionCode =
+  | 'incorrect_amount'
+  | 'duplicate'
+  | 'unknown_order'
+  | 'incorrect_vat'
+  | 'other';
+
+/**
+ * Dispute type for incoming invoices
+ */
+export type DisputeType =
+  | 'amount_dispute'
+  | 'quality_dispute'
+  | 'delivery_dispute'
+  | 'other';
+
+/**
+ * Input for accepting an incoming invoice
+ */
+export 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
+ */
+export interface RejectInvoiceInput {
+  /** Reason for rejection */
+  reason: string;
+  /** Standardized rejection code */
+  reason_code: RejectionCode;
+}
+
+/**
+ * Input for disputing an incoming invoice
+ */
+export 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
+ */
+export 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
+ */
+export type InvoiceFileFormat = 'pdf' | 'xml';

package/src/types/webhooks.ts

@@ -4,13 +4,20 @@ import type { DateTimeString, Environment, UUID } from './common.js';
  * Available webhook events
  */
 export type WebhookEvent =
-  // Invoice events
+  // Invoice events (outgoing)
   | 'invoice.created'
   | 'invoice.validated'
   | 'invoice.transmitted'
   | 'invoice.accepted'
   | 'invoice.rejected'
   | 'invoice.error'
+  // Invoice events (incoming)
+  | 'invoice.incoming.received'
+  | 'invoice.incoming.validated'
+  | 'invoice.incoming.accepted'
+  | 'invoice.incoming.rejected'
+  | 'invoice.incoming.disputed'
+  | 'invoice.incoming.paid'
   // Signature events
   | 'signature.created'
   | 'signature.waiting'
@@ -144,3 +151,25 @@ export interface BalanceWebhookData {
   currency: string;
   threshold: number;
 }
+
+/**
+ * Invoice incoming paid webhook payload data
+ */
+export 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;
+}