@scell/sdk 1.0.0

package/src/resources/invoices.ts

@@ -0,0 +1,246 @@
+/**
+ * Invoices Resource
+ *
+ * @packageDocumentation
+ */
+
+import type { HttpClient, RequestOptions } from '../client.js';
+import type {
+  MessageWithDataResponse,
+  PaginatedResponse,
+  SingleResponse,
+} from '../types/common.js';
+import type {
+  AuditTrailResponse,
+  ConvertInvoiceInput,
+  CreateInvoiceInput,
+  Invoice,
+  InvoiceDownloadResponse,
+  InvoiceDownloadType,
+  InvoiceListOptions,
+} from '../types/invoices.js';
+
+/**
+ * Invoices API resource
+ *
+ * @example
+ * ```typescript
+ * // List invoices
+ * const invoices = await client.invoices.list({
+ *   direction: 'outgoing',
+ *   status: 'validated'
+ * });
+ *
+ * // Create an invoice
+ * const invoice = await client.invoices.create({
+ *   invoice_number: 'FACT-2024-001',
+ *   direction: 'outgoing',
+ *   output_format: 'facturx',
+ *   // ...
+ * });
+ *
+ * // Download invoice
+ * const download = await client.invoices.download(invoice.id, 'pdf');
+ * console.log('Download URL:', download.url);
+ * ```
+ */
+export class InvoicesResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * List invoices with optional filtering
+   *
+   * @param options - Filter and pagination options
+   * @param requestOptions - Request options
+   * @returns Paginated list of invoices
+   *
+   * @example
+   * ```typescript
+   * // List all outgoing invoices
+   * const { data, meta } = await client.invoices.list({
+   *   direction: 'outgoing',
+   *   per_page: 50
+   * });
+   * console.log(`Found ${meta.total} invoices`);
+   * ```
+   */
+  async list(
+    options: InvoiceListOptions = {},
+    requestOptions?: RequestOptions
+  ): Promise<PaginatedResponse<Invoice>> {
+    return this.http.get<PaginatedResponse<Invoice>>(
+      '/invoices',
+      options as Record<string, string | number | boolean | undefined>,
+      requestOptions
+    );
+  }
+
+  /**
+   * Get a specific invoice by ID
+   *
+   * @param id - Invoice UUID
+   * @param requestOptions - Request options
+   * @returns Invoice details
+   *
+   * @example
+   * ```typescript
+   * const { data: invoice } = await client.invoices.get('uuid-here');
+   * console.log('Invoice number:', invoice.invoice_number);
+   * ```
+   */
+  async get(
+    id: string,
+    requestOptions?: RequestOptions
+  ): Promise<SingleResponse<Invoice>> {
+    return this.http.get<SingleResponse<Invoice>>(
+      `/invoices/${id}`,
+      undefined,
+      requestOptions
+    );
+  }
+
+  /**
+   * Create a new invoice
+   *
+   * Note: This endpoint requires API key authentication.
+   * Creating an invoice in production mode will debit your balance.
+   *
+   * @param input - Invoice creation data
+   * @param requestOptions - Request options
+   * @returns Created invoice
+   *
+   * @example
+   * ```typescript
+   * const { data: invoice } = await client.invoices.create({
+   *   invoice_number: 'FACT-2024-001',
+   *   direction: 'outgoing',
+   *   output_format: 'facturx',
+   *   issue_date: '2024-01-15',
+   *   total_ht: 100.00,
+   *   total_tax: 20.00,
+   *   total_ttc: 120.00,
+   *   seller_siret: '12345678901234',
+   *   seller_name: 'My Company',
+   *   seller_address: {
+   *     line1: '1 Rue Example',
+   *     postal_code: '75001',
+   *     city: 'Paris',
+   *     country: 'FR'
+   *   },
+   *   buyer_siret: '98765432109876',
+   *   buyer_name: 'Client Company',
+   *   buyer_address: {
+   *     line1: '2 Avenue Test',
+   *     postal_code: '75002',
+   *     city: 'Paris',
+   *     country: 'FR'
+   *   },
+   *   lines: [{
+   *     description: 'Service prestation',
+   *     quantity: 1,
+   *     unit_price: 100.00,
+   *     tax_rate: 20.00,
+   *     total_ht: 100.00,
+   *     total_tax: 20.00,
+   *     total_ttc: 120.00
+   *   }]
+   * });
+   * ```
+   */
+  async create(
+    input: CreateInvoiceInput,
+    requestOptions?: RequestOptions
+  ): Promise<MessageWithDataResponse<Invoice>> {
+    return this.http.post<MessageWithDataResponse<Invoice>>(
+      '/invoices',
+      input,
+      requestOptions
+    );
+  }
+
+  /**
+   * Download invoice file
+   *
+   * @param id - Invoice UUID
+   * @param type - File type to download
+   * @param requestOptions - Request options
+   * @returns Temporary download URL
+   *
+   * @example
+   * ```typescript
+   * // Download PDF version
+   * const { url, expires_at } = await client.invoices.download(
+   *   'invoice-uuid',
+   *   'pdf'
+   * );
+   * console.log('Download before:', expires_at);
+   * ```
+   */
+  async download(
+    id: string,
+    type: InvoiceDownloadType,
+    requestOptions?: RequestOptions
+  ): Promise<InvoiceDownloadResponse> {
+    return this.http.get<InvoiceDownloadResponse>(
+      `/invoices/${id}/download/${type}`,
+      undefined,
+      requestOptions
+    );
+  }
+
+  /**
+   * Get invoice audit trail (Piste d'Audit Fiable)
+   *
+   * @param id - Invoice UUID
+   * @param requestOptions - Request options
+   * @returns Audit trail entries with integrity validation
+   *
+   * @example
+   * ```typescript
+   * const { data: entries, integrity_valid } = await client.invoices.auditTrail(
+   *   'invoice-uuid'
+   * );
+   *
+   * if (integrity_valid) {
+   *   console.log('Audit trail is valid');
+   *   entries.forEach(e => console.log(e.action, e.created_at));
+   * }
+   * ```
+   */
+  async auditTrail(
+    id: string,
+    requestOptions?: RequestOptions
+  ): Promise<AuditTrailResponse> {
+    return this.http.get<AuditTrailResponse>(
+      `/invoices/${id}/audit-trail`,
+      undefined,
+      requestOptions
+    );
+  }
+
+  /**
+   * Convert invoice to another format
+   *
+   * @param input - Conversion parameters
+   * @param requestOptions - Request options
+   * @returns Conversion status
+   *
+   * @example
+   * ```typescript
+   * await client.invoices.convert({
+   *   invoice_id: 'invoice-uuid',
+   *   target_format: 'ubl'
+   * });
+   * ```
+   */
+  async convert(
+    input: ConvertInvoiceInput,
+    requestOptions?: RequestOptions
+  ): Promise<{ message: string; invoice_id: string; target_format: string }> {
+    return this.http.post<{
+      message: string;
+      invoice_id: string;
+      target_format: string;
+    }>('/invoices/convert', input, requestOptions);
+  }
+}

package/src/resources/signatures.ts

@@ -0,0 +1,245 @@
+/**
+ * Signatures Resource
+ *
+ * @packageDocumentation
+ */
+
+import type { HttpClient, RequestOptions } from '../client.js';
+import type {
+  MessageResponse,
+  MessageWithDataResponse,
+  PaginatedResponse,
+  SingleResponse,
+} from '../types/common.js';
+import type {
+  CreateSignatureInput,
+  Signature,
+  SignatureDownloadResponse,
+  SignatureDownloadType,
+  SignatureListOptions,
+  SignatureRemindResponse,
+} from '../types/signatures.js';
+
+/**
+ * Signatures API resource
+ *
+ * @example
+ * ```typescript
+ * // Create a signature request
+ * const signature = await client.signatures.create({
+ *   title: 'Employment Contract',
+ *   document: btoa(pdfContent), // Base64 encoded
+ *   document_name: 'contract.pdf',
+ *   signers: [{
+ *     first_name: 'John',
+ *     last_name: 'Doe',
+ *     email: 'john@example.com',
+ *     auth_method: 'email'
+ *   }]
+ * });
+ *
+ * // Send reminder
+ * await client.signatures.remind(signature.id);
+ * ```
+ */
+export class SignaturesResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * List signature requests with optional filtering
+   *
+   * @param options - Filter and pagination options
+   * @param requestOptions - Request options
+   * @returns Paginated list of signatures
+   *
+   * @example
+   * ```typescript
+   * const { data, meta } = await client.signatures.list({
+   *   status: 'pending',
+   *   per_page: 25
+   * });
+   * console.log(`${meta.total} pending signatures`);
+   * ```
+   */
+  async list(
+    options: SignatureListOptions = {},
+    requestOptions?: RequestOptions
+  ): Promise<PaginatedResponse<Signature>> {
+    return this.http.get<PaginatedResponse<Signature>>(
+      '/signatures',
+      options as Record<string, string | number | boolean | undefined>,
+      requestOptions
+    );
+  }
+
+  /**
+   * Get a specific signature by ID
+   *
+   * @param id - Signature UUID
+   * @param requestOptions - Request options
+   * @returns Signature details with signers
+   *
+   * @example
+   * ```typescript
+   * const { data: signature } = await client.signatures.get('uuid-here');
+   * signature.signers?.forEach(signer => {
+   *   console.log(`${signer.full_name}: ${signer.status}`);
+   * });
+   * ```
+   */
+  async get(
+    id: string,
+    requestOptions?: RequestOptions
+  ): Promise<SingleResponse<Signature>> {
+    return this.http.get<SingleResponse<Signature>>(
+      `/signatures/${id}`,
+      undefined,
+      requestOptions
+    );
+  }
+
+  /**
+   * Create a new signature request
+   *
+   * Note: This endpoint requires API key authentication.
+   * Creating a signature in production mode will debit your balance.
+   *
+   * @param input - Signature creation data
+   * @param requestOptions - Request options
+   * @returns Created signature
+   *
+   * @example
+   * ```typescript
+   * import { readFileSync } from 'fs';
+   *
+   * const pdfContent = readFileSync('contract.pdf');
+   * const { data: signature } = await client.signatures.create({
+   *   title: 'Service Agreement',
+   *   description: 'Annual service contract',
+   *   document: pdfContent.toString('base64'),
+   *   document_name: 'contract.pdf',
+   *   signers: [
+   *     {
+   *       first_name: 'Alice',
+   *       last_name: 'Smith',
+   *       email: 'alice@example.com',
+   *       auth_method: 'email'
+   *     },
+   *     {
+   *       first_name: 'Bob',
+   *       last_name: 'Jones',
+   *       phone: '+33612345678',
+   *       auth_method: 'sms'
+   *     }
+   *   ],
+   *   ui_config: {
+   *     logo_url: 'https://mycompany.com/logo.png',
+   *     primary_color: '#3b82f6',
+   *     company_name: 'My Company'
+   *   },
+   *   redirect_complete_url: 'https://myapp.com/signed',
+   *   redirect_cancel_url: 'https://myapp.com/cancelled'
+   * });
+   *
+   * // Send signing URLs to signers
+   * signature.signers?.forEach(signer => {
+   *   console.log(`${signer.email}: ${signer.signing_url}`);
+   * });
+   * ```
+   */
+  async create(
+    input: CreateSignatureInput,
+    requestOptions?: RequestOptions
+  ): Promise<MessageWithDataResponse<Signature>> {
+    return this.http.post<MessageWithDataResponse<Signature>>(
+      '/signatures',
+      input,
+      requestOptions
+    );
+  }
+
+  /**
+   * Download signature files
+   *
+   * @param id - Signature UUID
+   * @param type - File type to download
+   * @param requestOptions - Request options
+   * @returns Temporary download URL
+   *
+   * @example
+   * ```typescript
+   * // Download signed document
+   * const { url } = await client.signatures.download(
+   *   'signature-uuid',
+   *   'signed'
+   * );
+   *
+   * // Download audit trail (proof file)
+   * const { url: auditUrl } = await client.signatures.download(
+   *   'signature-uuid',
+   *   'audit_trail'
+   * );
+   * ```
+   */
+  async download(
+    id: string,
+    type: SignatureDownloadType,
+    requestOptions?: RequestOptions
+  ): Promise<SignatureDownloadResponse> {
+    return this.http.get<SignatureDownloadResponse>(
+      `/signatures/${id}/download/${type}`,
+      undefined,
+      requestOptions
+    );
+  }
+
+  /**
+   * Send reminder to pending signers
+   *
+   * @param id - Signature UUID
+   * @param requestOptions - Request options
+   * @returns Number of signers reminded
+   *
+   * @example
+   * ```typescript
+   * const { signers_reminded } = await client.signatures.remind('uuid');
+   * console.log(`Reminded ${signers_reminded} signers`);
+   * ```
+   */
+  async remind(
+    id: string,
+    requestOptions?: RequestOptions
+  ): Promise<SignatureRemindResponse> {
+    return this.http.post<SignatureRemindResponse>(
+      `/signatures/${id}/remind`,
+      undefined,
+      requestOptions
+    );
+  }
+
+  /**
+   * Cancel a signature request
+   *
+   * Note: Cannot cancel completed signatures.
+   *
+   * @param id - Signature UUID
+   * @param requestOptions - Request options
+   * @returns Cancellation confirmation
+   *
+   * @example
+   * ```typescript
+   * await client.signatures.cancel('signature-uuid');
+   * console.log('Signature cancelled');
+   * ```
+   */
+  async cancel(
+    id: string,
+    requestOptions?: RequestOptions
+  ): Promise<MessageResponse> {
+    return this.http.post<MessageResponse>(
+      `/signatures/${id}/cancel`,
+      undefined,
+      requestOptions
+    );
+  }
+}