@scell/sdk 1.0.0 → 1.4.0

package/src/types/fiscal.ts

@@ -0,0 +1,251 @@
+/**
+ * Fiscal Compliance Types
+ *
+ * Types for the fiscal compliance API (LF 2026).
+ *
+ * @packageDocumentation
+ */
+
+// ── Compliance Dashboard ────────────────────────────────────
+
+export interface FiscalComplianceData {
+  closing_coverage_percent: number;
+  chain_integrity_percent: number;
+  open_incidents: FiscalIncident[];
+  open_incidents_count: number;
+  overall_status: FiscalComplianceStatus;
+  last_integrity_check_at: string | null;
+  last_closing_at: string | null;
+  last_closing_date: string | null;
+  total_fiscal_entries: number;
+  days_with_activity: number;
+  days_closed: number;
+  attestation_status: FiscalAttestationStatus;
+}
+
+export type FiscalComplianceStatus = 'CONFORME' | 'ALERTE' | 'NON_CONFORME';
+
+export interface FiscalIncident {
+  type: string;
+  severity: 'critical' | 'warning' | 'info';
+  message: string;
+  since?: string;
+  count?: number;
+}
+
+export interface FiscalAttestationStatus {
+  current: boolean;
+  software_version: string;
+  attestation_version: string | null;
+  needs_renewal: boolean;
+  reason: string | null;
+}
+
+// ── Integrity ───────────────────────────────────────────────
+
+export interface FiscalIntegrityReport {
+  is_valid: boolean;
+  entries_checked: number;
+  broken_links: number;
+  details?: Record<string, unknown>;
+}
+
+export interface FiscalIntegrityCheck {
+  id: string;
+  tenant_id: string;
+  result: 'passed' | 'failed';
+  entries_checked: number;
+  broken_links: number;
+  details?: Record<string, unknown>;
+  created_at: string;
+}
+
+export interface FiscalIntegrityOptions {
+  date_from?: string;
+  date_to?: string;
+}
+
+export interface FiscalIntegrityHistoryOptions {
+  per_page?: number;
+}
+
+// ── Closings ────────────────────────────────────────────────
+
+export interface FiscalClosing {
+  id: string;
+  tenant_id: string;
+  closing_date: string;
+  closing_type: string;
+  status: string;
+  entries_count: number;
+  total_debit: number;
+  total_credit: number;
+  chain_hash?: string;
+  environment?: string;
+  created_at?: string;
+}
+
+export interface FiscalClosingsOptions {
+  limit?: number;
+}
+
+export interface FiscalDailyClosingInput {
+  date?: string;
+}
+
+// ── FEC Export ───────────────────────────────────────────────
+
+export interface FiscalFecExportOptions {
+  start_date: string;
+  end_date: string;
+  format?: 'pipe' | 'tab';
+  download?: boolean;
+}
+
+export interface FiscalFecExportResult {
+  period: {
+    start_date: string;
+    end_date: string;
+  };
+  format: string;
+  file_path: string;
+}
+
+// ── Attestation ─────────────────────────────────────────────
+
+export interface FiscalAttestation {
+  year: number;
+  tenant_name: string;
+  software_version: string;
+  compliance: Record<string, unknown>;
+  generated_at?: string;
+  certificate_hash?: string;
+}
+
+// ── Entries (Ledger) ────────────────────────────────────────
+
+export interface FiscalEntry {
+  id: string;
+  tenant_id: string;
+  sequence_number: number;
+  entry_type: string;
+  fiscal_date: string;
+  entity_type?: string | null;
+  entity_id?: string | null;
+  data_snapshot?: Record<string, unknown> | null;
+  data_hash?: string;
+  previous_hash?: string;
+  chain_hash?: string;
+  environment?: string;
+  legal_status?: string;
+  created_at?: string;
+}
+
+export interface FiscalEntriesOptions {
+  date_from?: string;
+  date_to?: string;
+  entry_type?: string;
+  environment?: 'production' | 'sandbox';
+  per_page?: number;
+}
+
+// ── Kill Switch ─────────────────────────────────────────────
+
+export interface FiscalKillSwitchStatus {
+  is_active: boolean;
+  kill_switch: FiscalKillSwitch | null;
+}
+
+export interface FiscalKillSwitch {
+  id: string;
+  tenant_id: string;
+  is_active: boolean;
+  activated_at: string;
+  reason: string;
+  activated_by: string;
+  deactivated_at?: string | null;
+  deactivated_by?: string | null;
+}
+
+export interface FiscalKillSwitchActivateInput {
+  reason: string;
+}
+
+// ── Anchors ─────────────────────────────────────────────────
+
+export interface FiscalAnchor {
+  id: string;
+  tenant_id: string;
+  anchor_type: string;
+  source_hash: string;
+  anchor_reference?: string | null;
+  anchor_provider?: string | null;
+  anchored_at?: string | null;
+  created_at?: string;
+}
+
+export interface FiscalAnchorsOptions {
+  limit?: number;
+}
+
+// ── Rules ───────────────────────────────────────────────────
+
+export type FiscalRuleCategory = 'vat' | 'invoicing' | 'credit_note' | 'closing' | 'export';
+
+export interface FiscalRule {
+  id: string;
+  rule_key: string;
+  name: string;
+  category: FiscalRuleCategory;
+  rule_definition: Record<string, unknown>;
+  version: number;
+  effective_from: string;
+  effective_until?: string | null;
+  legal_reference?: string | null;
+  tenant_id?: string | null;
+  description?: string | null;
+  is_active: boolean;
+  created_at?: string;
+}
+
+export interface FiscalRulesOptions {
+  date?: string;
+  category?: FiscalRuleCategory;
+}
+
+export interface FiscalCreateRuleInput {
+  rule_key: string;
+  name: string;
+  category: FiscalRuleCategory;
+  rule_definition: Record<string, unknown>;
+  effective_from: string;
+  effective_until?: string;
+  legal_reference?: string;
+}
+
+export interface FiscalUpdateRuleInput {
+  rule_definition: Record<string, unknown>;
+  effective_from?: string;
+  effective_until?: string;
+  legal_reference?: string;
+}
+
+export interface FiscalExportRulesOptions {
+  start_date: string;
+  end_date: string;
+}
+
+export interface FiscalReplayRulesInput {
+  start_date: string;
+  end_date: string;
+}
+
+// ── Forensic Export ─────────────────────────────────────────
+
+export type FiscalForensicExportType = 'chronology' | 'graph' | 'report';
+
+export interface FiscalForensicExportOptions {
+  start_date: string;
+  end_date: string;
+  type?: FiscalForensicExportType;
+}

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,
@@ -113,3 +122,106 @@ export type {
   ResetPasswordInput,
   User,
 } from './auth.js';
+
+// Tenant Credit Notes types
+export type {
+  CreateTenantCreditNoteInput,
+  RemainingCreditable,
+  RemainingCreditableLine,
+  TenantCreditNote,
+  TenantCreditNoteItem,
+  TenantCreditNoteItemInput,
+  TenantCreditNoteListOptions,
+  TenantCreditNoteStatus,
+  TenantCreditNoteType,
+  UpdateTenantCreditNoteInput,
+} from './tenant-credit-notes.js';
+
+// Tenant Invoices types (multi-tenant)
+export type {
+  CreateIncomingInvoiceParams,
+  CreateTenantDirectCreditNoteParams,
+  CreateTenantDirectInvoiceParams,
+  TenantCreditNoteFilters,
+  TenantInvoice,
+  TenantInvoiceBuyer,
+  TenantInvoiceDirection,
+  TenantInvoiceFilters,
+  TenantInvoiceSeller,
+  UpdateTenantCreditNoteParams,
+  UpdateTenantInvoiceParams,
+} from './tenant-invoices.js';
+
+// Fiscal types
+export type {
+  FiscalAnchor,
+  FiscalAnchorsOptions,
+  FiscalAttestation,
+  FiscalAttestationStatus,
+  FiscalClosing,
+  FiscalClosingsOptions,
+  FiscalComplianceData,
+  FiscalComplianceStatus,
+  FiscalCreateRuleInput,
+  FiscalDailyClosingInput,
+  FiscalEntriesOptions,
+  FiscalEntry,
+  FiscalExportRulesOptions,
+  FiscalFecExportOptions,
+  FiscalFecExportResult,
+  FiscalForensicExportOptions,
+  FiscalForensicExportType,
+  FiscalIncident,
+  FiscalIntegrityCheck,
+  FiscalIntegrityHistoryOptions,
+  FiscalIntegrityOptions,
+  FiscalIntegrityReport,
+  FiscalKillSwitch,
+  FiscalKillSwitchActivateInput,
+  FiscalKillSwitchStatus,
+  FiscalReplayRulesInput,
+  FiscalRule,
+  FiscalRuleCategory,
+  FiscalRulesOptions,
+  FiscalUpdateRuleInput,
+} from './fiscal.js';
+
+// Billing types
+export type {
+  BillingInvoice,
+  BillingInvoiceLine,
+  BillingInvoiceListOptions,
+  BillingTopUpConfirmInput,
+  BillingTopUpInput,
+  BillingTransaction,
+  BillingTransactionListOptions,
+  BillingUsage,
+  BillingUsageOptions,
+} from './billing.js';
+
+// Stats types
+export type {
+  StatsMonthly,
+  StatsMonthlyOptions,
+  StatsOverview,
+  StatsOverviewOptions,
+} from './stats.js';
+
+// Sub-Tenant types
+export type {
+  CreateSubTenantInput,
+  SubTenant,
+  SubTenantAddress,
+  SubTenantListOptions,
+  UpdateSubTenantInput,
+} from './sub-tenants.js';
+
+// Tenant Profile types
+export type {
+  RegenerateKeyResult,
+  TenantBalance,
+  TenantProfile,
+  TenantAddress,
+  TenantQuickStats,
+  UpdateTenantProfileInput,
+} from './tenant-profile.js';

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/stats.ts

@@ -0,0 +1,37 @@
+/**
+ * Stats Types
+ *
+ * Types for the tenant statistics API.
+ *
+ * @packageDocumentation
+ */
+
+export interface StatsOverview {
+  total_invoices: number;
+  total_credit_notes: number;
+  total_revenue: number;
+  total_expenses: number;
+  active_sub_tenants: number;
+  currency: string;
+  status_breakdown?: Record<string, number> | null;
+  period_comparison?: Record<string, unknown> | null;
+}
+
+export interface StatsMonthly {
+  month: string;
+  invoices_count: number;
+  credit_notes_count: number;
+  revenue: number;
+  expenses: number;
+  daily_breakdown?: Record<string, unknown>[] | null;
+}
+
+export interface StatsOverviewOptions {
+  period?: string;
+  currency?: string;
+}
+
+export interface StatsMonthlyOptions {
+  year?: number;
+  month?: number;
+}

package/src/types/sub-tenants.ts

@@ -0,0 +1,57 @@
+/**
+ * Sub-Tenant Types
+ *
+ * Types for the sub-tenant management API.
+ *
+ * @packageDocumentation
+ */
+
+export interface SubTenant {
+  id: string;
+  external_id?: string | null;
+  name: string;
+  siret?: string | null;
+  siren?: string | null;
+  email?: string | null;
+  phone?: string | null;
+  address?: SubTenantAddress | null;
+  metadata?: Record<string, unknown> | null;
+  created_at?: string;
+  updated_at?: string;
+}
+
+export interface SubTenantAddress {
+  line1: string;
+  line2?: string;
+  postal_code: string;
+  city: string;
+  country?: string;
+}
+
+export interface SubTenantListOptions {
+  per_page?: number;
+  page?: number;
+  search?: string;
+}
+
+export interface CreateSubTenantInput {
+  external_id?: string;
+  name: string;
+  siret?: string;
+  siren?: string;
+  email?: string;
+  phone?: string;
+  address?: SubTenantAddress;
+  metadata?: Record<string, unknown>;
+}
+
+export interface UpdateSubTenantInput {
+  external_id?: string;
+  name?: string;
+  siret?: string;
+  siren?: string;
+  email?: string;
+  phone?: string;
+  address?: SubTenantAddress;
+  metadata?: Record<string, unknown>;
+}

package/src/types/tenant-credit-notes.ts

@@ -0,0 +1,128 @@
+/**
+ * Tenant Credit Notes types
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  CurrencyCode,
+  DateString,
+  DateTimeString,
+  PaginationOptions,
+  Siret,
+  UUID,
+} from './common.js';
+
+/**
+ * Credit note status
+ */
+export type TenantCreditNoteStatus = 'draft' | 'sent' | 'cancelled';
+
+/**
+ * Credit note type
+ */
+export type TenantCreditNoteType = 'partial' | 'total';
+
+/**
+ * Credit note item
+ */
+export interface TenantCreditNoteItem {
+  id: UUID;
+  invoice_line_id?: UUID | undefined;
+  description: string;
+  quantity: number;
+  unit_price: number;
+  tax_rate: number;
+  total: number;
+}
+
+/**
+ * Tenant Credit Note
+ */
+export interface TenantCreditNote {
+  id: UUID;
+  credit_note_number: string;
+  invoice_id: UUID;
+  tenant_id: UUID;
+  sub_tenant_id: UUID;
+  status: TenantCreditNoteStatus;
+  type: TenantCreditNoteType;
+  reason: string;
+  subtotal: number;
+  tax_amount: number;
+  total: number;
+  currency: CurrencyCode;
+  buyer_name?: string | undefined;
+  buyer_siret?: Siret | undefined;
+  seller_name?: string | undefined;
+  seller_siret?: Siret | undefined;
+  issue_date: DateString;
+  created_at: DateTimeString;
+  updated_at: DateTimeString;
+  items?: TenantCreditNoteItem[] | undefined;
+}
+
+/**
+ * Credit note item input for creation
+ */
+export interface TenantCreditNoteItemInput {
+  invoice_line_id: UUID;
+  quantity?: number | undefined;
+}
+
+/**
+ * Input for creating a tenant credit note
+ */
+export interface CreateTenantCreditNoteInput {
+  invoice_id: UUID;
+  reason: string;
+  type: TenantCreditNoteType;
+  items?: TenantCreditNoteItemInput[] | undefined;
+  metadata?: Record<string, unknown> | undefined;
+}
+
+/**
+ * Line item remaining creditable information
+ */
+export interface RemainingCreditableLine {
+  invoice_line_id: UUID;
+  description: string;
+  original_quantity: number;
+  credited_quantity: number;
+  remaining_quantity: number;
+  unit_price: number;
+}
+
+/**
+ * Remaining creditable information for an invoice
+ */
+export interface RemainingCreditable {
+  invoice_id: UUID;
+  invoice_total: number;
+  credited_total: number;
+  remaining_total: number;
+  lines: RemainingCreditableLine[];
+}
+
+/**
+ * List options for tenant credit notes
+ */
+export interface TenantCreditNoteListOptions extends PaginationOptions {
+  status?: TenantCreditNoteStatus | undefined;
+  date_from?: DateString | undefined;
+  date_to?: DateString | undefined;
+}
+
+/**
+ * Input for updating a tenant credit note
+ *
+ * Only credit notes in 'draft' status can be updated.
+ */
+export interface UpdateTenantCreditNoteInput {
+  /** Updated reason for the credit note */
+  reason?: string | undefined;
+  /** Updated items (for partial credit notes) */
+  items?: TenantCreditNoteItemInput[] | undefined;
+  /** Updated metadata */
+  metadata?: Record<string, unknown> | undefined;
+}