@fast-white-cat/integration-ksef-direct 0.1.0

package/src/modules/integration_ksef_direct/i18n/en.json

@@ -0,0 +1,115 @@
+{
+  "integration_ksef_direct.title": "KSeF Direct",
+  "integration_ksef_direct.nav.documents": "Sent Documents",
+  "integration_ksef_direct.nav.documents_desc": "Outgoing invoices sent to KSeF",
+  "integration_ksef_direct.nav.received_documents": "Received Documents",
+  "integration_ksef_direct.nav.received_documents_desc": "Invoices received from KSeF",
+  "integration_ksef_direct.description": "Direct integration with the Polish KSeF system via official MF API v2 without Exorigo/SmartKSeF middleware.",
+  "integration_ksef_direct.health.connected": "Connected",
+  "integration_ksef_direct.health.error": "Connection error",
+  "integration_ksef_direct.health.unconfigured": "Not configured",
+  "integration_ksef_direct.health.checking": "Checking...",
+  "integration_ksef_direct.health.check_button": "Check connection",
+  "integration_ksef_direct.health.last_checked": "Last check:",
+  "integration_ksef_direct.health.environment": "Environment:",
+  "integration_ksef_direct.health.rate_limits": "Rate limits:",
+  "integration_ksef_direct.health.never": "Never",
+  "integration_ksef_direct.credentials.ksef_token": "KSeF Token",
+  "integration_ksef_direct.credentials.nip": "NIP",
+  "integration_ksef_direct.credentials.environment": "Environment",
+  "integration_ksef_direct.credentials.environment.test": "Test",
+  "integration_ksef_direct.credentials.environment.production": "Production",
+  "integration_ksef_direct.documents.columns.invoiceNumber": "Invoice Number",
+  "integration_ksef_direct.documents.columns.buyer": "Buyer",
+  "integration_ksef_direct.documents.columns.issueDate": "Issue Date",
+  "integration_ksef_direct.documents.columns.grossAmount": "Gross Amount",
+  "integration_ksef_direct.documents.columns.source": "Source",
+  "integration_ksef_direct.documents.columns.status": "Status",
+  "integration_ksef_direct.documents.empty.title": "No KSeF documents yet",
+  "integration_ksef_direct.documents.empty.description": "Add your first document manually or configure KSeF sync.",
+  "integration_ksef_direct.documents.status.draft": "Draft",
+  "integration_ksef_direct.documents.status.queued": "Queued",
+  "integration_ksef_direct.documents.status.sending": "Sending",
+  "integration_ksef_direct.documents.status.sent": "Sent",
+  "integration_ksef_direct.documents.status.failed": "Failed",
+  "integration_ksef_direct.documents.source.manual": "Manual",
+  "integration_ksef_direct.documents.source.ksef_sync": "KSeF sync",
+  "integration_ksef_direct.documents.source.sales_invoice": "Sales invoice",
+  "integration_ksef_direct.documents.form.title_new": "New KSeF Document",
+  "integration_ksef_direct.documents.form.section.buyer": "Buyer",
+  "integration_ksef_direct.documents.form.section.invoice": "Invoice Details",
+  "integration_ksef_direct.documents.form.section.summary": "Summary",
+  "integration_ksef_direct.documents.form.buyer_nip": "Buyer NIP",
+  "integration_ksef_direct.documents.form.buyer_name": "Buyer Name",
+  "integration_ksef_direct.documents.form.invoice_number": "Invoice Number",
+  "integration_ksef_direct.documents.form.issue_date": "Issue Date",
+  "integration_ksef_direct.documents.form.sale_date": "Sale Date",
+  "integration_ksef_direct.documents.form.currency": "Currency",
+  "integration_ksef_direct.documents.form.net_amount": "Net Amount",
+  "integration_ksef_direct.documents.form.vat_amount": "VAT Amount",
+  "integration_ksef_direct.documents.form.gross_amount": "Gross Amount",
+  "integration_ksef_direct.documents.form.notes": "Notes",
+  "integration_ksef_direct.documents.form.section.seller": "Seller",
+  "integration_ksef_direct.documents.form.seller_nip": "Seller NIP",
+  "integration_ksef_direct.documents.form.seller_nip_placeholder": "KSeF not configured",
+  "integration_ksef_direct.documents.form.generate_number": "Generate number",
+  "integration_ksef_direct.documents.form.generating": "Generating...",
+  "integration_ksef_direct.documents.form.generate_number_error": "Failed to generate invoice number",
+  "integration_ksef_direct.documents.form.seller_info_error": "Failed to load seller info",
+  "integration_ksef_direct.documents.form.seller_name": "Seller Name",
+  "integration_ksef_direct.documents.form.section.seller_address": "Seller Address (optional)",
+  "integration_ksef_direct.documents.form.seller_address_l1": "Street and number",
+  "integration_ksef_direct.documents.form.seller_city": "City",
+  "integration_ksef_direct.documents.form.seller_country": "Country",
+  "integration_ksef_direct.documents.form.submit": "Save Document",
+  "integration_ksef_direct.documents.form.error": "Failed to save document",
+  "integration_ksef_direct.documents.form.success": "Document created successfully.",
+  "integration_ksef_direct.documents.form.line_items": "Line Items",
+  "integration_ksef_direct.documents.form.line_items.description": "Description",
+  "integration_ksef_direct.documents.form.line_items.quantity": "Qty",
+  "integration_ksef_direct.documents.form.line_items.unit": "Unit",
+  "integration_ksef_direct.documents.form.line_items.unit_net_price": "Net Price",
+  "integration_ksef_direct.documents.form.line_items.vat_rate": "VAT",
+  "integration_ksef_direct.documents.form.line_items.add": "Add Line",
+  "integration_ksef_direct.documents.form.line_items.remove": "Remove line",
+  "integration_ksef_direct.documents.list.actions.new": "New Document",
+  "integration_ksef_direct.documents.send_button": "Send to KSeF",
+  "integration_ksef_direct.documents.retry_button": "Retry send",
+  "integration_ksef_direct.documents.send_success": "Document queued for sending",
+  "integration_ksef_direct.documents.ksef_reference_number": "KSeF Number",
+  "integration_ksef_direct.documents.ksef_processing_reference": "Processing Reference Number",
+  "integration_ksef_direct.documents.go_to_settings": "Go to settings",
+  "integration_ksef_direct.documents.errors.already_queued": "Document is already queued",
+  "integration_ksef_direct.documents.errors.send_failed": "KSeF send failed",
+  "integration_ksef_direct.documents.errors.xml_failed": "FA_VAT XML generation failed",
+  "integration_ksef_direct.documents.errors.ksef_timeout": "Timeout: KSeF did not confirm the document within 10 minutes",
+  "integration_ksef_direct.documents.errors.missing_seller_name": "Seller name is required to send this document to KSeF",
+
+  "integration_ksef_direct.received_documents.title": "Received Documents",
+  "integration_ksef_direct.received_documents.loading": "Loading...",
+  "integration_ksef_direct.received_documents.empty": "No received documents found.",
+  "integration_ksef_direct.received_documents.cancel": "Cancel",
+  "integration_ksef_direct.received_documents.date_from": "Date From",
+  "integration_ksef_direct.received_documents.date_to": "Date To",
+  "integration_ksef_direct.received_documents.sync_button": "Sync by date range",
+  "integration_ksef_direct.received_documents.fetch_button": "Fetch by reference",
+  "integration_ksef_direct.received_documents.sync_success": "Sync started. Documents will appear shortly.",
+  "integration_ksef_direct.received_documents.fetch_success": "Document fetched successfully.",
+  "integration_ksef_direct.received_documents.copy_xml": "Copy XML",
+  "integration_ksef_direct.received_documents.xml_copied": "Copied",
+  "integration_ksef_direct.received_documents.column.ksef_reference": "KSeF Ref.",
+  "integration_ksef_direct.received_documents.column.invoice_number": "Invoice No.",
+  "integration_ksef_direct.received_documents.column.seller_nip": "Seller NIP",
+  "integration_ksef_direct.received_documents.column.seller_name": "Seller",
+  "integration_ksef_direct.received_documents.column.issue_date": "Issue Date",
+  "integration_ksef_direct.received_documents.column.gross_amount": "Gross Amount",
+  "integration_ksef_direct.received_documents.column.status": "Status",
+  "integration_ksef_direct.received_documents.status.pending_download": "Pending Download",
+  "integration_ksef_direct.received_documents.status.downloaded": "Downloaded",
+  "integration_ksef_direct.received_documents.status.failed": "Failed",
+  "integration_ksef_direct.received_documents.dialog_sync.title": "Sync Received Documents",
+  "integration_ksef_direct.received_documents.dialog_sync.submit": "Start Sync",
+  "integration_ksef_direct.received_documents.dialog_fetch.title": "Fetch Document by KSeF Reference",
+  "integration_ksef_direct.received_documents.dialog_fetch.submit": "Fetch",
+  "integration_ksef_direct.received_documents.error.no_credentials": "KSeF credentials are not configured for this organization."
+}

package/src/modules/integration_ksef_direct/i18n/pl.json

@@ -0,0 +1,115 @@
+{
+  "integration_ksef_direct.title": "KSeF Direct",
+  "integration_ksef_direct.nav.documents": "Wysłane dokumenty",
+  "integration_ksef_direct.nav.documents_desc": "Faktury wychodzące wysłane do KSeF",
+  "integration_ksef_direct.nav.received_documents": "Odebrane dokumenty",
+  "integration_ksef_direct.nav.received_documents_desc": "Faktury odebrane z KSeF",
+  "integration_ksef_direct.description": "Bezpośrednia integracja z KSeF przez oficjalne API MF v2 bez pośrednika Exorigo/SmartKSeF.",
+  "integration_ksef_direct.health.connected": "Połączono",
+  "integration_ksef_direct.health.error": "Błąd połączenia",
+  "integration_ksef_direct.health.unconfigured": "Nieskonfigurowano",
+  "integration_ksef_direct.health.checking": "Sprawdzanie...",
+  "integration_ksef_direct.health.check_button": "Sprawdź połączenie",
+  "integration_ksef_direct.health.last_checked": "Ostatni check:",
+  "integration_ksef_direct.health.environment": "Środowisko:",
+  "integration_ksef_direct.health.rate_limits": "Rate limity:",
+  "integration_ksef_direct.health.never": "Nigdy",
+  "integration_ksef_direct.credentials.ksef_token": "Token KSeF",
+  "integration_ksef_direct.credentials.nip": "NIP",
+  "integration_ksef_direct.credentials.environment": "Środowisko",
+  "integration_ksef_direct.credentials.environment.test": "Test",
+  "integration_ksef_direct.credentials.environment.production": "Produkcja",
+  "integration_ksef_direct.documents.columns.invoiceNumber": "Nr faktury",
+  "integration_ksef_direct.documents.columns.buyer": "Nabywca",
+  "integration_ksef_direct.documents.columns.issueDate": "Data wystawienia",
+  "integration_ksef_direct.documents.columns.grossAmount": "Kwota brutto",
+  "integration_ksef_direct.documents.columns.source": "Źródło",
+  "integration_ksef_direct.documents.columns.status": "Status",
+  "integration_ksef_direct.documents.empty.title": "Brak dokumentów KSeF",
+  "integration_ksef_direct.documents.empty.description": "Dodaj pierwszy dokument ręcznie lub skonfiguruj synchronizację z KSeF.",
+  "integration_ksef_direct.documents.status.draft": "Szkic",
+  "integration_ksef_direct.documents.status.queued": "W kolejce",
+  "integration_ksef_direct.documents.status.sending": "Wysyłanie",
+  "integration_ksef_direct.documents.status.sent": "Wysłane",
+  "integration_ksef_direct.documents.status.failed": "Błąd",
+  "integration_ksef_direct.documents.source.manual": "Ręcznie",
+  "integration_ksef_direct.documents.source.ksef_sync": "Synchronizacja KSeF",
+  "integration_ksef_direct.documents.source.sales_invoice": "Faktura sprzedaży",
+  "integration_ksef_direct.documents.form.title_new": "Nowy dokument KSeF",
+  "integration_ksef_direct.documents.form.section.buyer": "Nabywca",
+  "integration_ksef_direct.documents.form.section.invoice": "Szczegóły faktury",
+  "integration_ksef_direct.documents.form.section.summary": "Podsumowanie",
+  "integration_ksef_direct.documents.form.buyer_nip": "NIP nabywcy",
+  "integration_ksef_direct.documents.form.buyer_name": "Nazwa nabywcy",
+  "integration_ksef_direct.documents.form.invoice_number": "Numer faktury",
+  "integration_ksef_direct.documents.form.issue_date": "Data wystawienia",
+  "integration_ksef_direct.documents.form.sale_date": "Data sprzedaży",
+  "integration_ksef_direct.documents.form.currency": "Waluta",
+  "integration_ksef_direct.documents.form.net_amount": "Kwota netto",
+  "integration_ksef_direct.documents.form.vat_amount": "Kwota VAT",
+  "integration_ksef_direct.documents.form.gross_amount": "Kwota brutto",
+  "integration_ksef_direct.documents.form.notes": "Uwagi",
+  "integration_ksef_direct.documents.form.section.seller": "Sprzedawca",
+  "integration_ksef_direct.documents.form.seller_nip": "NIP sprzedawcy",
+  "integration_ksef_direct.documents.form.seller_nip_placeholder": "Brak konfiguracji KSeF",
+  "integration_ksef_direct.documents.form.generate_number": "Generuj numer",
+  "integration_ksef_direct.documents.form.generating": "Generowanie...",
+  "integration_ksef_direct.documents.form.generate_number_error": "Nie udało się wygenerować numeru",
+  "integration_ksef_direct.documents.form.seller_info_error": "Nie udało się pobrać danych sprzedawcy",
+  "integration_ksef_direct.documents.form.seller_name": "Nazwa sprzedawcy",
+  "integration_ksef_direct.documents.form.section.seller_address": "Adres sprzedawcy (opcjonalny)",
+  "integration_ksef_direct.documents.form.seller_address_l1": "Ulica i numer",
+  "integration_ksef_direct.documents.form.seller_city": "Miasto",
+  "integration_ksef_direct.documents.form.seller_country": "Kraj",
+  "integration_ksef_direct.documents.form.submit": "Zapisz dokument",
+  "integration_ksef_direct.documents.form.error": "Nie udało się zapisać dokumentu",
+  "integration_ksef_direct.documents.form.success": "Dokument został dodany.",
+  "integration_ksef_direct.documents.form.line_items": "Pozycje",
+  "integration_ksef_direct.documents.form.line_items.description": "Opis",
+  "integration_ksef_direct.documents.form.line_items.quantity": "Ilość",
+  "integration_ksef_direct.documents.form.line_items.unit": "Jedn.",
+  "integration_ksef_direct.documents.form.line_items.unit_net_price": "Cena netto",
+  "integration_ksef_direct.documents.form.line_items.vat_rate": "VAT",
+  "integration_ksef_direct.documents.form.line_items.add": "Dodaj pozycję",
+  "integration_ksef_direct.documents.form.line_items.remove": "Usuń pozycję",
+  "integration_ksef_direct.documents.list.actions.new": "Nowy dokument",
+  "integration_ksef_direct.documents.send_button": "Wyślij do KSeF",
+  "integration_ksef_direct.documents.retry_button": "Ponów wysyłkę",
+  "integration_ksef_direct.documents.send_success": "Dokument dodany do kolejki wysyłki",
+  "integration_ksef_direct.documents.ksef_reference_number": "Numer KSeF",
+  "integration_ksef_direct.documents.ksef_processing_reference": "Numer referencyjny przetwarzania",
+  "integration_ksef_direct.documents.go_to_settings": "Przejdź do ustawień",
+  "integration_ksef_direct.documents.errors.already_queued": "Dokument jest już w kolejce",
+  "integration_ksef_direct.documents.errors.send_failed": "Błąd wysyłki do KSeF",
+  "integration_ksef_direct.documents.errors.xml_failed": "Błąd generowania XML FA_VAT",
+  "integration_ksef_direct.documents.errors.ksef_timeout": "Timeout: KSeF nie potwierdził dokumentu w ciągu 10 minut",
+  "integration_ksef_direct.documents.errors.missing_seller_name": "Nazwa sprzedawcy jest wymagana do wysłania dokumentu do KSeF",
+
+  "integration_ksef_direct.received_documents.title": "Odebrane dokumenty",
+  "integration_ksef_direct.received_documents.loading": "Ładowanie...",
+  "integration_ksef_direct.received_documents.empty": "Brak odebranych dokumentów.",
+  "integration_ksef_direct.received_documents.cancel": "Anuluj",
+  "integration_ksef_direct.received_documents.date_from": "Data od",
+  "integration_ksef_direct.received_documents.date_to": "Data do",
+  "integration_ksef_direct.received_documents.sync_button": "Synchronizuj zakres dat",
+  "integration_ksef_direct.received_documents.fetch_button": "Pobierz po numerze ref.",
+  "integration_ksef_direct.received_documents.sync_success": "Synchronizacja rozpoczęta. Dokumenty pojawią się wkrótce.",
+  "integration_ksef_direct.received_documents.fetch_success": "Dokument pobrany pomyślnie.",
+  "integration_ksef_direct.received_documents.copy_xml": "Kopiuj XML",
+  "integration_ksef_direct.received_documents.xml_copied": "Skopiowano",
+  "integration_ksef_direct.received_documents.column.ksef_reference": "Numer KSeF",
+  "integration_ksef_direct.received_documents.column.invoice_number": "Nr faktury",
+  "integration_ksef_direct.received_documents.column.seller_nip": "NIP sprzedawcy",
+  "integration_ksef_direct.received_documents.column.seller_name": "Sprzedawca",
+  "integration_ksef_direct.received_documents.column.issue_date": "Data wystawienia",
+  "integration_ksef_direct.received_documents.column.gross_amount": "Kwota brutto",
+  "integration_ksef_direct.received_documents.column.status": "Status",
+  "integration_ksef_direct.received_documents.status.pending_download": "Oczekuje na pobranie",
+  "integration_ksef_direct.received_documents.status.downloaded": "Pobrano",
+  "integration_ksef_direct.received_documents.status.failed": "Błąd",
+  "integration_ksef_direct.received_documents.dialog_sync.title": "Synchronizuj odebrane dokumenty",
+  "integration_ksef_direct.received_documents.dialog_sync.submit": "Rozpocznij synchronizację",
+  "integration_ksef_direct.received_documents.dialog_fetch.title": "Pobierz dokument po numerze KSeF",
+  "integration_ksef_direct.received_documents.dialog_fetch.submit": "Pobierz",
+  "integration_ksef_direct.received_documents.error.no_credentials": "Dane dostępowe KSeF nie są skonfigurowane dla tej organizacji."
+}

package/src/modules/integration_ksef_direct/index.ts

@@ -0,0 +1,6 @@
+export const metadata = {
+  id: 'integration_ksef_direct',
+  title: 'KSeF Integration',
+  description: 'Direct integration with the Polish KSeF system via official MF API v2',
+  requires: ['integrations'],
+}

package/src/modules/integration_ksef_direct/integration.ts

@@ -0,0 +1,54 @@
+import type { IntegrationDefinition } from '@open-mercato/shared/modules/integrations/types'
+
+export const integration: IntegrationDefinition = {
+  id: 'integration_ksef_direct',
+  title: 'KSeF Direct',
+  description: 'Direct integration with the Polish National e-Invoice System (KSeF) via official MF REST API v2 — no Exorigo/SmartKSeF middleware required.',
+  category: 'fiscal',
+  providerKey: 'ksef_direct',
+  icon: 'file-text',
+  package: '@fast-white-cat/integration-ksef-direct',
+  version: '0.1.0',
+  author: 'FastWhiteCat',
+  company: 'FastWhiteCat',
+  license: 'PROPRIETARY',
+  tags: ['ksef', 'e-invoicing', 'poland', 'fiscal', 'tax-compliance', 'direct'],
+  credentials: {
+    fields: [
+      {
+        key: 'ksef_token',
+        label: 'KSeF Token',
+        type: 'secret',
+        required: true,
+      },
+      {
+        key: 'nip',
+        label: 'NIP (Tax Identification Number)',
+        type: 'text',
+        required: true,
+      },
+      {
+        key: 'environment',
+        label: 'Environment',
+        type: 'select',
+        required: true,
+        options: [
+          { value: 'test', label: 'Test (api-test.ksef.mf.gov.pl)' },
+          { value: 'production', label: 'Production (api.ksef.mf.gov.pl)' },
+        ],
+      },
+    ],
+  },
+  healthCheck: {
+    service: 'ksefDirectHealthChecker',
+  },
+  apiVersions: [
+    {
+      id: 'ksef-api-v2',
+      label: 'KSeF MF API v2',
+      status: 'stable',
+      default: true,
+      changelog: 'Direct MF KSeF API v2 — challenge/token auth flow',
+    },
+  ],
+}

package/src/modules/integration_ksef_direct/lib/health.ts

@@ -0,0 +1,43 @@
+import { verifyAccess, KsefAuthError, KsefNetworkError } from './ksefClient'
+import type { KsefCredentials } from './ksefClient'
+
+export interface HealthCheckResult {
+  status: 'healthy' | 'unhealthy'
+  message: string
+  details: Record<string, unknown>
+  checkedAt: Date
+}
+
+export const ksefDirectHealthChecker = {
+  async check(credentials: Record<string, unknown>): Promise<HealthCheckResult> {
+    const typed: KsefCredentials = {
+      ksefToken: credentials.ksef_token as string,
+      nip: credentials.nip as string,
+      environment: credentials.environment as 'test' | 'production',
+    }
+
+    try {
+      const rateLimits = await verifyAccess(typed)
+      return {
+        status: 'healthy',
+        message: `Connected to KSeF ${typed.environment} (NIP: ${typed.nip})`,
+        details: { environment: typed.environment, nip: typed.nip, rateLimits },
+        checkedAt: new Date(),
+      }
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : 'Unknown error'
+      const errorCode =
+        err instanceof KsefAuthError
+          ? err.errorCode
+          : err instanceof KsefNetworkError
+            ? err.errorCode
+            : 'UNKNOWN_ERROR'
+      return {
+        status: 'unhealthy',
+        message: `KSeF connection failed: ${message}`,
+        details: { error: message, errorCode },
+        checkedAt: new Date(),
+      }
+    }
+  },
+}

package/src/modules/integration_ksef_direct/lib/invoiceNumberFormat.ts

@@ -0,0 +1,23 @@
+import { randomBytes } from 'crypto'
+
+// Format: FV/{yyyy}/{mm}/{nanoid:8} — extensible to per-tenant configurable format in the future
+const ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+const MAX_VALID = 256 - (256 % ALPHABET.length)
+
+function createAlphanumericId(size: number): string {
+  let id = ''
+  while (id.length < size) {
+    const byte = randomBytes(1)[0]
+    if (byte >= MAX_VALID) continue
+    id += ALPHABET[byte % ALPHABET.length]
+  }
+  return id
+}
+
+export function generateKsefInvoiceNumber(): string {
+  const now = new Date()
+  const yyyy = String(now.getFullYear())
+  const mm = String(now.getMonth() + 1).padStart(2, '0')
+  const unique = createAlphanumericId(8)
+  return `FV/${yyyy}/${mm}/${unique}`
+}