Type Definitions

interface InvoiceInput {
  number: string;
  to: BuyerParty;
  lines: InvoiceLine[];

  // Optional
  date?: string;                // ISO 8601 (default: today)
  dueDate?: string;             // ISO 8601
  currency?: string;            // ISO 4217 (default: "EUR")
  taxCurrency?: string;         // BT-6
  taxCurrencyRate?: number;
  note?: string;
  from?: Party;                 // deprecated: seller comes from API key
  payeeParty?: Party;           // BG-10
  buyerReference?: string;      // BT-10
  orderReference?: string;      // PO number
  salesOrderReference?: string; // BT-14
  contractReference?: string;   // BT-12
  projectReference?: string;    // BT-11
  invoiceReference?: string;    // required for credit notes
  isCreditNote?: boolean;

  // Payment
  paymentTerms?: string;
  paymentReference?: string;
  paymentMeans?: number;        // UNCL 4461: 10, 30, 31, 48, 49, 57, 58, 59
  paymentIban?: string;
  paymentBic?: string;

  // Extended
  delivery?: Delivery;
  invoicePeriod?: InvoicePeriod;
  attachments?: Attachment[];
  allowances?: AllowanceCharge[];
  charges?: AllowanceCharge[];
}

interface Party {
  name: string;
  peppolId: string;          // e.g. "0208:0685660237"
  country: string;           // ISO 3166-1 alpha-2

  // Optional
  vatNumber?: string;
  street?: string;
  city?: string;
  postalCode?: string;
  companyId?: string;        // BT-30 / BT-47
  companyIdScheme?: string;  // e.g. "0208"
  contactName?: string;
  phone?: string;
  email?: string;
}

type BuyerParty = Party & {
  street: string;
  city: string;
  postalCode: string;
}

interface InvoiceLine {
  description: string;
  quantity: number;
  unitPrice: number;
  vatRate: number;            // percentage (e.g. 21)

  // Optional
  unit?: string;              // UN/ECE code or "hour", "day", "kg"...
  vatCategory?: string;       // "S" | "Z" | "E" | "AE" | ...
  itemId?: string;            // seller's item ID
  standardItemId?: string;    // GTIN/EAN
  standardItemScheme?: string;
  baseQuantity?: number;
  accountingCost?: string;    // BT-133
  allowances?: LineAllowanceCharge[];
  charges?: LineAllowanceCharge[];
}

interface SendResult {
  id: string;                 // deprecated — see submissionId / providerDocumentId
  submissionId?: string;      // the getpeppr record of this document (SDK 4.0.0)
  providerDocumentId?: string;// the provider document GUID (SDK 4.0.0)
  status: DocumentStatus;
  rawStatus: string;          // raw pre-coercion gateway status (required, SDK 4.0.0)
  detail?: StatusDetail;      // structured national detail, per axis (SDK 2.2.0)
  peppolMessageId?: string;   // Peppol AS4 message ID — only with ?include=evidence
  ublXml?: string;            // generated UBL (debug)
  warnings?: ValidationWarning[];
  createdAt?: string;         // ISO 8601, when the gateway measured one
}

type DocumentStatus =
  | "submitted" | "delivered" | "accepted"
  | "rejected" | "paid" | "failed"
  | "cleared" | "acknowledged" | "in_process"
  | "under_query" | "conditionally_accepted"
  | "partially_paid" | "no_action" | "unknown";

interface StatusDetail {
  platformFiscal?: StatusDetailEntry;
  delivery?: StatusDetailEntry;
  businessDisposition?: StatusDetailEntry;
  settlement?: StatusDetailEntry;
}

interface StatusDetailEntry {
  axis: "platformFiscal" | "delivery" | "businessDisposition" | "settlement" | "unmapped";
  jurisdiction: string;       // e.g. "FR", or "*" for network-wide
  code: string;               // native code (e.g. "213") — not the label
  label: string;              // human label (e.g. "Rejetée")
  codeSystem: string;         // e.g. "fr-ctc-lifecycle"
  codeVersion: string;
  standardCode?: { system: string; code: string };
  reason?: string;
  warnings?: string[];
  failureCategory?: "transport" | "routing" | "syntax" | "semantic" | "authority";
  payment?: { amount: number; currency: string; date: string };
  paymentSemantics?: "received" | "initiated";
  actor?: "seller" | "buyer";
}

interface ServerValidationResult {
  valid: boolean;
  errors: ValidationError[];
  warnings: ValidationWarning[];
  ubl: {
    valid: boolean;
    errors: ServerValidationMessage[];
  };
  /** @deprecated Mirrors ubl.valid; no standalone XSD validator runs. */
  xsd: {
    valid: boolean;
    errors: ServerValidationMessage[];
    note?: string;
  };
  schematron: {
    /** No problem among the rules checked — NOT a statement of Peppol conformance. */
    valid: boolean;
    /** What valid is worth: this pass never covers the whole network rulebook. */
    coverage: { rulesChecked: number; ofNetworkFatalRules: "partial" };
    errors: ServerValidationMessage[];
    warnings: ServerValidationMessage[];
  };
}

interface ServerValidationMessage {
  severity: "error" | "warning";
  message: string;
  location?: string;
  ruleId?: string;
}

interface PeppolConfig {
  apiKey: string;
  environment?: "sandbox" | "production";
  baseUrl?: string;           // custom endpoint
  timeout?: number;           // ms (default: 30000)
}

interface Attachment {
  id: string;                 // document reference
  description?: string;
  filename?: string;          // e.g. "invoice.pdf"
  mimeType?: string;          // e.g. "application/pdf"
  content?: string;           // raw base64, no data URI prefix; 2 MB decoded cap on server validation
  url?: string;               // external URL alternative
}

// Document-level (BG-20 / BG-21)
interface AllowanceCharge {
  reason: string;
  amount: number;
  vatRate: number;
  vatCategory?: string;
}

// Line-level (BG-27 / BG-28)
interface LineAllowanceCharge {
  reason: string;
  amount: number;
}

interface WebhookEvent<T = unknown> {
  id: string;
  type: WebhookEventType;
  data: T;
  createdAt: string;
}

type WebhookEventType =
  | "invoice.sent"
  | "invoice.accepted"
  | "invoice.refused"
  | "invoice.error"
  | "invoice.registered"
  | "invoice.paid"
  | "invoice.received"
  | "invoice.undeliverable"
  | "invoice.delivery_unconfirmed"   // no evidence yet, not a failure
  | "invoice.partially_paid"
  | "invoice.under_query"
  | "invoice.conditionally_accepted"
  | "invoice.status_changed"   // opt-in: never matched by "*"
  | "legal_entity.registered"
  | "legal_entity.verification_failed"
  | "legal_entity.awaiting_authz"
  | "legal_entity.registration_failed"
  | "peppol_identifier.verified"
  | "peppol_identifier.verification_failed"
  | "inbound.invoice.received"
  | "inbound.creditnote.received"
  | "test.ping";

// Also exported as a runtime constant:
// const WEBHOOK_EVENT_TYPES: readonly WebhookEventType[]