@scell/sdk 1.0.0

package/src/types/index.ts

@@ -0,0 +1,115 @@
+/**
+ * Scell SDK Type Definitions
+ *
+ * @packageDocumentation
+ */
+
+// Common types
+export type {
+  Address,
+  ApiErrorResponse,
+  CurrencyCode,
+  DateRangeOptions,
+  DateString,
+  DateTimeString,
+  Environment,
+  MessageResponse,
+  MessageWithDataResponse,
+  PaginatedResponse,
+  PaginationMeta,
+  PaginationOptions,
+  SingleResponse,
+  Siren,
+  Siret,
+  UUID,
+} from './common.js';
+
+// Invoice types
+export type {
+  AuditTrailEntry,
+  AuditTrailResponse,
+  ConvertInvoiceInput,
+  CreateInvoiceInput,
+  Invoice,
+  InvoiceDirection,
+  InvoiceDownloadResponse,
+  InvoiceDownloadType,
+  InvoiceFormat,
+  InvoiceLine,
+  InvoiceLineInput,
+  InvoiceListOptions,
+  InvoiceParty,
+  InvoiceStatus,
+} from './invoices.js';
+
+// Signature types
+export type {
+  CreateSignatureInput,
+  Signature,
+  SignatureDownloadResponse,
+  SignatureDownloadType,
+  SignatureListOptions,
+  SignaturePosition,
+  SignatureRemindResponse,
+  SignatureStatus,
+  SignatureUIConfig,
+  Signer,
+  SignerAuthMethod,
+  SignerInput,
+  SignerStatus,
+} from './signatures.js';
+
+// Company types
+export type {
+  Company,
+  CompanyStatus,
+  CreateCompanyInput,
+  KycInitiateResponse,
+  KycStatusResponse,
+  UpdateCompanyInput,
+} from './companies.js';
+
+// Balance types
+export type {
+  Balance,
+  ReloadBalanceInput,
+  ReloadBalanceResponse,
+  Transaction,
+  TransactionListOptions,
+  TransactionService,
+  TransactionType,
+  UpdateBalanceSettingsInput,
+} from './balance.js';
+
+// Webhook types
+export type {
+  BalanceWebhookData,
+  CreateWebhookInput,
+  InvoiceWebhookData,
+  SignatureWebhookData,
+  UpdateWebhookInput,
+  Webhook,
+  WebhookEvent,
+  WebhookListOptions,
+  WebhookLog,
+  WebhookPayload,
+  WebhookTestResponse,
+  WebhookWithSecret,
+} from './webhooks.js';
+
+// API Key types
+export type {
+  ApiKey,
+  ApiKeyWithSecret,
+  CreateApiKeyInput,
+} from './api-keys.js';
+
+// Auth types
+export type {
+  AuthResponse,
+  ForgotPasswordInput,
+  LoginCredentials,
+  RegisterInput,
+  ResetPasswordInput,
+  User,
+} from './auth.js';

package/src/types/invoices.ts

@@ -0,0 +1,191 @@
+import type {
+  Address,
+  CurrencyCode,
+  DateString,
+  DateTimeString,
+  Environment,
+  Siret,
+  UUID,
+} from './common.js';
+
+/**
+ * Invoice direction
+ */
+export type InvoiceDirection = 'outgoing' | 'incoming';
+
+/**
+ * Invoice output format
+ */
+export type InvoiceFormat = 'facturx' | 'ubl' | 'cii';
+
+/**
+ * Invoice status
+ */
+export type InvoiceStatus =
+  | 'draft'
+  | 'pending'
+  | 'validated'
+  | 'converted'
+  | 'transmitted'
+  | 'accepted'
+  | 'rejected'
+  | 'error';
+
+/**
+ * Invoice download file type
+ */
+export type InvoiceDownloadType = 'original' | 'converted' | 'pdf';
+
+/**
+ * Invoice line item
+ */
+export interface InvoiceLine {
+  line_number: number;
+  description: string;
+  quantity: number;
+  unit_price: number;
+  tax_rate: number;
+  total_ht: number;
+  total_tax: number;
+  total_ttc: number;
+}
+
+/**
+ * Invoice party (seller or buyer)
+ */
+export interface InvoiceParty {
+  siret: Siret;
+  name: string;
+  address: Address;
+}
+
+/**
+ * Invoice entity
+ */
+export interface Invoice {
+  id: UUID;
+  external_id: string | null;
+  invoice_number: string;
+  direction: InvoiceDirection;
+  output_format: InvoiceFormat;
+  issue_date: DateString;
+  due_date: DateString | null;
+  currency: CurrencyCode;
+  total_ht: number;
+  total_tax: number;
+  total_ttc: number;
+  seller: InvoiceParty;
+  buyer: InvoiceParty;
+  lines: InvoiceLine[] | null;
+  status: InvoiceStatus;
+  status_message: string | null;
+  environment: Environment;
+  archive_enabled: boolean;
+  amount_charged: number | null;
+  created_at: DateTimeString;
+  validated_at: DateTimeString | null;
+  transmitted_at: DateTimeString | null;
+  completed_at: DateTimeString | null;
+}
+
+/**
+ * Invoice line input for creation
+ */
+export interface InvoiceLineInput {
+  description: string;
+  quantity: number;
+  unit_price: number;
+  tax_rate: number;
+  total_ht: number;
+  total_tax: number;
+  total_ttc: number;
+}
+
+/**
+ * Invoice creation input
+ */
+export interface CreateInvoiceInput {
+  /** Your external reference ID */
+  external_id?: string | undefined;
+  /** Invoice number (required) */
+  invoice_number: string;
+  /** Direction: outgoing (sale) or incoming (purchase) */
+  direction: InvoiceDirection;
+  /** Output format for electronic invoice */
+  output_format: InvoiceFormat;
+  /** Issue date (YYYY-MM-DD) */
+  issue_date: DateString;
+  /** Due date (YYYY-MM-DD) */
+  due_date?: DateString | undefined;
+  /** Currency code (default: EUR) */
+  currency?: CurrencyCode | undefined;
+  /** Total excluding tax */
+  total_ht: number;
+  /** Total tax amount */
+  total_tax: number;
+  /** Total including tax */
+  total_ttc: number;
+  /** Seller SIRET (14 digits) */
+  seller_siret: Siret;
+  /** Seller company name */
+  seller_name: string;
+  /** Seller address */
+  seller_address: Address;
+  /** Buyer SIRET (14 digits) */
+  buyer_siret: Siret;
+  /** Buyer company name */
+  buyer_name: string;
+  /** Buyer address */
+  buyer_address: Address;
+  /** Invoice line items */
+  lines: InvoiceLineInput[];
+  /** Enable 10-year archiving */
+  archive_enabled?: boolean | undefined;
+}
+
+/**
+ * Invoice list filter options
+ */
+export interface InvoiceListOptions {
+  company_id?: UUID | undefined;
+  direction?: InvoiceDirection | undefined;
+  status?: InvoiceStatus | undefined;
+  environment?: Environment | undefined;
+  from?: DateString | undefined;
+  to?: DateString | undefined;
+  per_page?: number | undefined;
+}
+
+/**
+ * Invoice conversion input
+ */
+export interface ConvertInvoiceInput {
+  invoice_id: UUID;
+  target_format: InvoiceFormat;
+}
+
+/**
+ * Invoice download response
+ */
+export interface InvoiceDownloadResponse {
+  url: string;
+  expires_at: DateTimeString;
+}
+
+/**
+ * Audit trail entry
+ */
+export interface AuditTrailEntry {
+  action: string;
+  details: string;
+  actor_ip: string | null;
+  created_at: DateTimeString;
+}
+
+/**
+ * Audit trail response
+ */
+export interface AuditTrailResponse {
+  data: AuditTrailEntry[];
+  integrity_valid: boolean;
+}

package/src/types/signatures.ts

@@ -0,0 +1,153 @@
+import type { DateTimeString, Environment, UUID } from './common.js';
+
+/**
+ * Signer authentication method
+ */
+export type SignerAuthMethod = 'email' | 'sms' | 'both';
+
+/**
+ * Signer status
+ */
+export type SignerStatus = 'pending' | 'signed' | 'refused';
+
+/**
+ * Signature status
+ */
+export type SignatureStatus =
+  | 'pending'
+  | 'waiting_signers'
+  | 'partially_signed'
+  | 'completed'
+  | 'refused'
+  | 'expired'
+  | 'error';
+
+/**
+ * Signature download file type
+ */
+export type SignatureDownloadType = 'original' | 'signed' | 'audit_trail';
+
+/**
+ * Signature position on document
+ */
+export interface SignaturePosition {
+  page: number;
+  x: number;
+  y: number;
+  width?: number | undefined;
+  height?: number | undefined;
+}
+
+/**
+ * UI customization for signature page (white-label)
+ */
+export interface SignatureUIConfig {
+  logo_url?: string | undefined;
+  primary_color?: string | undefined;
+  company_name?: string | undefined;
+}
+
+/**
+ * Signer entity
+ */
+export interface Signer {
+  id: UUID;
+  first_name: string;
+  last_name: string;
+  full_name: string;
+  email: string | null;
+  phone: string | null;
+  auth_method: SignerAuthMethod;
+  status: SignerStatus;
+  signing_url: string | null;
+  signed_at: DateTimeString | null;
+  refused_at: DateTimeString | null;
+}
+
+/**
+ * Signature entity
+ */
+export interface Signature {
+  id: UUID;
+  external_id: string | null;
+  title: string;
+  description: string | null;
+  document_name: string;
+  document_size: number;
+  signers: Signer[] | null;
+  status: SignatureStatus;
+  status_message: string | null;
+  environment: Environment;
+  archive_enabled: boolean;
+  amount_charged: number | null;
+  expires_at: DateTimeString | null;
+  created_at: DateTimeString;
+  completed_at: DateTimeString | null;
+}
+
+/**
+ * Signer input for creation
+ */
+export interface SignerInput {
+  first_name: string;
+  last_name: string;
+  email?: string | undefined;
+  phone?: string | undefined;
+  auth_method: SignerAuthMethod;
+}
+
+/**
+ * Signature creation input
+ */
+export interface CreateSignatureInput {
+  /** Your external reference ID */
+  external_id?: string | undefined;
+  /** Document title */
+  title: string;
+  /** Document description */
+  description?: string | undefined;
+  /** Base64-encoded document content */
+  document: string;
+  /** Document filename */
+  document_name: string;
+  /** List of signers (1-10) */
+  signers: SignerInput[];
+  /** Signature positions on the document */
+  signature_positions?: SignaturePosition[] | undefined;
+  /** White-label UI customization */
+  ui_config?: SignatureUIConfig | undefined;
+  /** Redirect URL after completion */
+  redirect_complete_url?: string | undefined;
+  /** Redirect URL after cancellation */
+  redirect_cancel_url?: string | undefined;
+  /** Expiration date (default: 30 days) */
+  expires_at?: DateTimeString | undefined;
+  /** Enable 10-year archiving */
+  archive_enabled?: boolean | undefined;
+}
+
+/**
+ * Signature list filter options
+ */
+export interface SignatureListOptions {
+  company_id?: UUID | undefined;
+  status?: SignatureStatus | undefined;
+  environment?: Environment | undefined;
+  per_page?: number | undefined;
+}
+
+/**
+ * Signature download response
+ */
+export interface SignatureDownloadResponse {
+  url: string;
+  expires_at: DateTimeString;
+}
+
+/**
+ * Signature reminder response
+ */
+export interface SignatureRemindResponse {
+  message: string;
+  signers_reminded: number;
+}

package/src/types/webhooks.ts

@@ -0,0 +1,146 @@
+import type { DateTimeString, Environment, UUID } from './common.js';
+
+/**
+ * Available webhook events
+ */
+export type WebhookEvent =
+  // Invoice events
+  | 'invoice.created'
+  | 'invoice.validated'
+  | 'invoice.transmitted'
+  | 'invoice.accepted'
+  | 'invoice.rejected'
+  | 'invoice.error'
+  // Signature events
+  | 'signature.created'
+  | 'signature.waiting'
+  | 'signature.signed'
+  | 'signature.completed'
+  | 'signature.refused'
+  | 'signature.expired'
+  | 'signature.error'
+  // Balance events
+  | 'balance.low'
+  | 'balance.critical';
+
+/**
+ * Webhook entity
+ */
+export interface Webhook {
+  id: UUID;
+  company_id: UUID | null;
+  url: string;
+  events: WebhookEvent[];
+  is_active: boolean;
+  environment: Environment;
+  retry_count: number;
+  timeout_seconds: number;
+  failure_count: number;
+  last_triggered_at: DateTimeString | null;
+  last_success_at: DateTimeString | null;
+  last_failure_at: DateTimeString | null;
+  created_at: DateTimeString;
+}
+
+/**
+ * Webhook with secret (returned on creation)
+ */
+export interface WebhookWithSecret extends Webhook {
+  secret: string;
+}
+
+/**
+ * Webhook creation input
+ */
+export interface CreateWebhookInput {
+  url: string;
+  events: WebhookEvent[];
+  environment: Environment;
+  headers?: Record<string, string> | undefined;
+  retry_count?: number | undefined;
+  timeout_seconds?: number | undefined;
+}
+
+/**
+ * Webhook update input
+ */
+export interface UpdateWebhookInput {
+  url?: string | undefined;
+  events?: WebhookEvent[] | undefined;
+  is_active?: boolean | undefined;
+  headers?: Record<string, string> | undefined;
+  retry_count?: number | undefined;
+  timeout_seconds?: number | undefined;
+}
+
+/**
+ * Webhook list filter options
+ */
+export interface WebhookListOptions {
+  company_id?: UUID | undefined;
+}
+
+/**
+ * Webhook test response
+ */
+export interface WebhookTestResponse {
+  success: boolean;
+  status_code?: number | undefined;
+  response_time_ms?: number | undefined;
+  error?: string | undefined;
+}
+
+/**
+ * Webhook log entry
+ */
+export interface WebhookLog {
+  id: UUID;
+  event: string;
+  payload: Record<string, unknown>;
+  response_status: number | null;
+  response_body: string | null;
+  response_time_ms: number | null;
+  success: boolean;
+  error_message: string | null;
+  created_at: DateTimeString;
+}
+
+/**
+ * Webhook payload structure (received by your endpoint)
+ */
+export interface WebhookPayload<T = unknown> {
+  event: WebhookEvent;
+  timestamp: DateTimeString;
+  data: T;
+}
+
+/**
+ * Invoice webhook payload data
+ */
+export interface InvoiceWebhookData {
+  id: UUID;
+  invoice_number: string;
+  status: string;
+  environment: Environment;
+}
+
+/**
+ * Signature webhook payload data
+ */
+export interface SignatureWebhookData {
+  id: UUID;
+  title: string;
+  status: string;
+  environment: Environment;
+  signer_id?: UUID | undefined;
+  signer_email?: string | undefined;
+}
+
+/**
+ * Balance webhook payload data
+ */
+export interface BalanceWebhookData {
+  amount: number;
+  currency: string;
+  threshold: number;
+}