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

package/src/modules/integration_ksef_direct/migrations/Migration20260519210000_integration_ksef_direct.ts

@@ -0,0 +1,15 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260519210000_integration_ksef_direct extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "ksef_direct_connections" ("id" uuid not null default gen_random_uuid(), "organization_id" uuid not null, "tenant_id" uuid not null, "status" text not null default 'unconfigured', "last_checked_at" timestamptz null, "error_message" text null, "error_code" text null, "created_at" timestamptz not null, "updated_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`create index "ksef_direct_connections_status_updated_at_index" on "ksef_direct_connections" ("status", "updated_at");`);
+    this.addSql(`alter table "ksef_direct_connections" add constraint "ksef_direct_connections_organization_id_tenant_id_unique" unique ("organization_id", "tenant_id");`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop table if exists "ksef_direct_connections";`);
+  }
+
+}

package/src/modules/integration_ksef_direct/migrations/Migration20260520120000_ksef_direct_documents.ts

@@ -0,0 +1,17 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260520120000_ksef_direct_documents extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "ksef_direct_documents" ("id" uuid not null default gen_random_uuid(), "organization_id" uuid not null, "tenant_id" uuid not null, "source" text not null default 'manual', "status" text not null default 'draft', "ksef_reference_number" text null, "seller_nip" text not null, "buyer_nip" text not null, "buyer_name" text null, "invoice_number" text not null, "issue_date" timestamptz not null, "sale_date" timestamptz null, "net_amount" numeric(15,2) not null, "vat_amount" numeric(15,2) not null, "gross_amount" numeric(15,2) not null, "currency" text not null default 'PLN', "line_items" jsonb not null default '[]', "notes" text null, "error_message" text null, "created_at" timestamptz not null, "updated_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`create index "ksef_direct_documents_organization_id_tenant_id_index" on "ksef_direct_documents" ("organization_id", "tenant_id");`);
+    this.addSql(`create index "ksef_direct_documents_organization_id_tenant_id_status_index" on "ksef_direct_documents" ("organization_id", "tenant_id", "status");`);
+    this.addSql(`create index "ksef_direct_documents_organization_id_tenant_id_source_index" on "ksef_direct_documents" ("organization_id", "tenant_id", "source");`);
+    this.addSql(`create index "ksef_direct_documents_ksef_reference_number_index" on "ksef_direct_documents" ("ksef_reference_number");`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop table if exists "ksef_direct_documents";`);
+  }
+
+}

package/src/modules/integration_ksef_direct/migrations/Migration20260520220000_ksef_direct_send_queue.ts

@@ -0,0 +1,15 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260520220000_ksef_direct_send_queue extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`alter table "ksef_direct_documents" add column "ksef_processing_reference_number" text null;`);
+    this.addSql(`alter table "ksef_direct_documents" add column "seller_name" text null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`alter table "ksef_direct_documents" drop column "ksef_processing_reference_number";`);
+    this.addSql(`alter table "ksef_direct_documents" drop column "seller_name";`);
+  }
+
+}

package/src/modules/integration_ksef_direct/migrations/Migration20260520230000_ksef_direct_seller_per_document.ts

@@ -0,0 +1,17 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260520230000_ksef_direct_seller_per_document extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`alter table "ksef_direct_documents" add column "seller_address_l1" text null;`);
+    this.addSql(`alter table "ksef_direct_documents" add column "seller_city" text null;`);
+    this.addSql(`alter table "ksef_direct_documents" add column "seller_country" text null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`alter table "ksef_direct_documents" drop column "seller_address_l1";`);
+    this.addSql(`alter table "ksef_direct_documents" drop column "seller_city";`);
+    this.addSql(`alter table "ksef_direct_documents" drop column "seller_country";`);
+  }
+
+}

package/src/modules/integration_ksef_direct/migrations/Migration20260521120000_ksef_direct_received_documents.ts

@@ -0,0 +1,16 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260521120000_ksef_direct_received_documents extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "ksef_direct_received_documents" ("id" uuid not null default gen_random_uuid(), "organization_id" uuid not null, "tenant_id" uuid not null, "ksef_reference_number" text not null, "raw_xml" text null, "invoice_number" text null, "seller_nip" text null, "seller_name" text null, "issue_date" date null, "currency" text null, "net_amount" numeric(15,2) null, "vat_amount" numeric(15,2) null, "gross_amount" numeric(15,2) null, "status" text not null default 'pending_download', "error_message" text null, "upo_download_url" text null, "invoice_download_url" text null, "synced_at" timestamptz null, "created_at" timestamptz not null, "updated_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`create index "ksef_direct_received_documents_organization_id_tenant_id_index" on "ksef_direct_received_documents" ("organization_id", "tenant_id");`);
+    this.addSql(`create index "ksef_direct_received_documents_organization_id_tenant_id_status_index" on "ksef_direct_received_documents" ("organization_id", "tenant_id", "status");`);
+    this.addSql(`alter table "ksef_direct_received_documents" add constraint "ksef_direct_received_documents_organization_id_ksef_reference_number_unique" unique ("organization_id", "ksef_reference_number");`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop table if exists "ksef_direct_received_documents";`);
+  }
+
+}

package/src/modules/integration_ksef_direct/migrations/Migration20260521130000_ksef_received_download_urls.ts

@@ -0,0 +1,15 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260521130000_ksef_received_download_urls extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`alter table "ksef_direct_received_documents" add column if not exists "upo_download_url" text null;`);
+    this.addSql(`alter table "ksef_direct_received_documents" add column if not exists "invoice_download_url" text null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`alter table "ksef_direct_received_documents" drop column if exists "upo_download_url";`);
+    this.addSql(`alter table "ksef_direct_received_documents" drop column if exists "invoice_download_url";`);
+  }
+
+}

package/src/modules/integration_ksef_direct/setup.ts

@@ -0,0 +1,9 @@
+import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
+
+export const setup: ModuleSetupConfig = {
+  defaultRoleFeatures: {
+    admin: ['integration_ksef_direct.*'],
+  },
+}
+
+export default setup

package/src/modules/integration_ksef_direct/subscribers/auto-enqueue-ksef-document.ts

@@ -0,0 +1,21 @@
+import { enqueueKsefDirectDocument } from '../commands/enqueue-ksef-direct-document'
+
+export const metadata = {
+  event: 'ksef_direct.document.created',
+  persistent: true,
+  id: 'ksef_direct.auto_enqueue_document',
+}
+
+export default async function handler(
+  payload: { documentId: string; organizationId: string; tenantId: string },
+  ctx: { resolve: <T = unknown>(name: string) => T },
+) {
+  const em = ctx.resolve<{ fork: () => unknown }>('em')?.fork() as any
+  if (!em) return
+
+  try {
+    await enqueueKsefDirectDocument(em, payload.tenantId, payload.organizationId, payload.documentId)
+  } catch {
+    // If document is already queued or in a non-draft state, ignore — idempotent
+  }
+}

package/src/modules/integration_ksef_direct/workers/check-ksef-document-status.ts

@@ -0,0 +1,129 @@
+import type { QueuedJob, WorkerMeta } from '@open-mercato/queue'
+import { createModuleQueue } from '@open-mercato/queue'
+
+export const metadata: WorkerMeta = {
+  queue: 'ksef_direct_check',
+  id: 'ksef-direct-check',
+  concurrency: 5,
+}
+
+type HandlerContext = { resolve: <T = unknown>(name: string) => T }
+
+type CheckJobPayload = {
+  documentId: string
+  organizationId: string
+  tenantId: string
+  attempt: number
+}
+
+export default async function handler(
+  job: QueuedJob<CheckJobPayload>,
+  ctx: HandlerContext,
+): Promise<void> {
+  const payload = job.payload
+  const em = (ctx.resolve('em') as { fork: () => unknown })?.fork() as any
+  if (!em) return
+
+  const { KsefDirectDocument } = await import('../data/entities')
+  const doc = await em.findOne(KsefDirectDocument, {
+    id: payload.documentId,
+    organizationId: payload.organizationId,
+    tenantId: payload.tenantId,
+  })
+
+  if (!doc || doc.status !== 'sending') {
+    return
+  }
+
+  if (!doc.ksefProcessingReferenceNumber) {
+    doc.status = 'failed'
+    doc.errorMessage = 'Missing KSeF processing reference number'
+    doc.updatedAt = new Date()
+    await em.flush()
+    return
+  }
+
+  const credentialsService = ctx.resolve('integrationCredentialsService') as any
+  const rawCreds = credentialsService
+    ? await credentialsService.resolve('integration_ksef_direct', {
+        tenantId: payload.tenantId,
+        organizationId: payload.organizationId,
+      })
+    : null
+
+  const { KsefDirectCredentialsSchema } = await import('../data/validators')
+  const credsParsed = KsefDirectCredentialsSchema.safeParse(rawCreds)
+  if (!credsParsed.success) {
+    doc.status = 'failed'
+    doc.errorMessage = 'KSeF Direct credentials not configured'
+    doc.updatedAt = new Date()
+    await em.flush()
+    return
+  }
+
+  const credentials = {
+    ksefToken: credsParsed.data.ksef_token,
+    nip: credsParsed.data.nip,
+    environment: credsParsed.data.environment,
+    tenantId: payload.tenantId,
+  }
+
+  const { checkInvoiceStatus } = await import('../lib/ksefClient')
+  const { emitKsefDirectEvent } = await import('../events')
+
+  let result: { processingCode: number; ksefReferenceNumber?: string; errorDescription?: string }
+  try {
+    result = await checkInvoiceStatus(credentials, doc.ksefProcessingReferenceNumber)
+  } catch (err) {
+    // Re-throw transient errors so BullMQ retries; do not permanently fail the document
+    throw err
+  }
+
+  if (result.processingCode === 200) {
+    doc.status = 'sent'
+    doc.updatedAt = new Date()
+    await em.flush()
+
+    await emitKsefDirectEvent('ksef_direct.document.sent', {
+      documentId: doc.id,
+      ksefReferenceNumber: doc.ksefReferenceNumber ?? undefined,
+      organizationId: payload.organizationId,
+      tenantId: payload.tenantId,
+    })
+  } else if (result.processingCode === 100) {
+    if (payload.attempt >= 10) {
+      doc.status = 'failed'
+      doc.errorMessage = 'Timeout: KSeF did not confirm the document within 10 minutes'
+      doc.updatedAt = new Date()
+      await em.flush()
+
+      await emitKsefDirectEvent('ksef_direct.document.failed', {
+        documentId: doc.id,
+        errorMessage: doc.errorMessage,
+        organizationId: payload.organizationId,
+        tenantId: payload.tenantId,
+      })
+    } else {
+      const checkQueue = createModuleQueue<CheckJobPayload>('ksef_direct_check')
+      await checkQueue.enqueue(
+        { ...payload, attempt: payload.attempt + 1 },
+        { delayMs: 60_000 },
+      )
+    }
+  } else {
+    const errorMessage = result.errorDescription
+      ?? `KSeF processing error: code ${result.processingCode}`
+    doc.status = 'failed'
+    doc.errorMessage = errorMessage
+    doc.ksefReferenceNumber = null
+    doc.updatedAt = new Date()
+    await em.flush()
+
+    await emitKsefDirectEvent('ksef_direct.document.failed', {
+      documentId: doc.id,
+      errorMessage,
+      organizationId: payload.organizationId,
+      tenantId: payload.tenantId,
+    })
+  }
+}

package/src/modules/integration_ksef_direct/workers/send-ksef-document.ts

@@ -0,0 +1,137 @@
+import type { QueuedJob, WorkerMeta } from '@open-mercato/queue'
+import { createModuleQueue } from '@open-mercato/queue'
+
+export const metadata: WorkerMeta = {
+  queue: 'ksef_direct_send',
+  id: 'ksef-direct-send',
+  concurrency: 5,
+}
+
+type HandlerContext = { resolve: <T = unknown>(name: string) => T }
+
+type SendJobPayload = {
+  documentId: string
+  organizationId: string
+  tenantId: string
+}
+
+type CheckJobPayload = {
+  documentId: string
+  organizationId: string
+  tenantId: string
+  attempt: number
+}
+
+export default async function handler(
+  job: QueuedJob<SendJobPayload>,
+  ctx: HandlerContext,
+): Promise<void> {
+  const payload = job.payload
+  const em = (ctx.resolve('em') as { fork: () => unknown })?.fork() as any
+  if (!em) return
+
+  const { KsefDirectDocument } = await import('../data/entities')
+  const doc = await em.findOne(KsefDirectDocument, {
+    id: payload.documentId,
+    organizationId: payload.organizationId,
+    tenantId: payload.tenantId,
+  })
+
+  if (!doc || doc.status !== 'queued') {
+    return
+  }
+
+  if (!doc.sellerName?.trim()) {
+    doc.status = 'failed'
+    doc.errorMessage = 'Seller name is required to send the document to KSeF'
+    doc.updatedAt = new Date()
+    await em.flush()
+
+    const { emitKsefDirectEvent } = await import('../events')
+    await emitKsefDirectEvent('ksef_direct.document.failed', {
+      documentId: doc.id,
+      errorMessage: doc.errorMessage,
+      organizationId: payload.organizationId,
+      tenantId: payload.tenantId,
+    })
+    return
+  }
+
+  const credentialsService = ctx.resolve('integrationCredentialsService') as any
+  const rawCreds = credentialsService
+    ? await credentialsService.resolve('integration_ksef_direct', {
+        tenantId: payload.tenantId,
+        organizationId: payload.organizationId,
+      })
+    : null
+
+  const { KsefDirectCredentialsSchema } = await import('../data/validators')
+  const credsParsed = KsefDirectCredentialsSchema.safeParse(rawCreds)
+
+  if (!credsParsed.success) {
+    doc.status = 'failed'
+    doc.errorMessage = 'KSeF Direct credentials not configured'
+    doc.updatedAt = new Date()
+    await em.flush()
+
+    const { emitKsefDirectEvent } = await import('../events')
+    await emitKsefDirectEvent('ksef_direct.document.failed', {
+      documentId: doc.id,
+      errorMessage: doc.errorMessage,
+      organizationId: payload.organizationId,
+      tenantId: payload.tenantId,
+    })
+    return
+  }
+
+  const creds = credsParsed.data
+  const credentials = {
+    ksefToken: creds.ksef_token,
+    nip: creds.nip,
+    environment: creds.environment,
+    tenantId: payload.tenantId,
+  }
+
+  try {
+    const { fetchInvoicePublicKey, prepareInvoicePayload } = await import('../lib/ksefCrypto')
+    const { generateFa2Xml } = await import('../lib/ksefFa2Xml')
+    const { sendInvoice } = await import('../lib/ksefClient')
+
+    const xml = generateFa2Xml(doc, {
+      sellerName: doc.sellerName,
+      sellerAddressL1: doc.sellerAddressL1 ?? undefined,
+      sellerCity: doc.sellerCity ?? undefined,
+      sellerCountry: doc.sellerCountry ?? undefined,
+    })
+
+    const { publicKeyPem, publicKeyId } = await fetchInvoicePublicKey(credentials.environment)
+    const invoicePayload = prepareInvoicePayload(xml, publicKeyPem)
+    const { sessionReferenceNumber, invoiceReferenceNumber } = await sendInvoice(credentials, { ...invoicePayload, publicKeyId })
+
+    doc.status = 'sending'
+    doc.ksefProcessingReferenceNumber = sessionReferenceNumber
+    doc.ksefReferenceNumber = invoiceReferenceNumber
+    doc.updatedAt = new Date()
+    await em.flush()
+
+    const checkQueue = createModuleQueue<CheckJobPayload>('ksef_direct_check')
+    await checkQueue.enqueue(
+      { documentId: doc.id, organizationId: payload.organizationId, tenantId: payload.tenantId, attempt: 1 },
+      { delayMs: 30_000 },
+    )
+  } catch (err) {
+    const errorMessage = err instanceof Error ? err.message : 'Unknown error during KSeF document send'
+    doc.status = 'failed'
+    doc.errorMessage = errorMessage
+    doc.updatedAt = new Date()
+    await em.flush()
+
+    const { emitKsefDirectEvent } = await import('../events')
+    await emitKsefDirectEvent('ksef_direct.document.failed', {
+      documentId: doc.id,
+      errorMessage,
+      organizationId: payload.organizationId,
+      tenantId: payload.tenantId,
+    })
+  }
+}

package/src/modules/integration_ksef_direct/workers/sync-received-documents.ts

@@ -0,0 +1,171 @@
+import type { QueuedJob, WorkerMeta } from '@open-mercato/queue'
+
+export const metadata: WorkerMeta = {
+  queue: 'ksef_direct_receive',
+  id: 'ksef-direct-receive',
+  concurrency: 3,
+}
+
+type HandlerContext = { resolve: <T = unknown>(name: string) => T }
+
+export type SyncReceivedDocumentsPayload = {
+  organizationId: string
+  tenantId: string
+  dateFrom: string
+  dateTo: string
+}
+
+export default async function handler(
+  job: QueuedJob<SyncReceivedDocumentsPayload>,
+  ctx: HandlerContext,
+): Promise<void> {
+  const payload = job.payload
+
+  const em = (ctx.resolve('em') as { fork: () => unknown })?.fork() as any
+  if (!em) return
+
+  const credentialsService = ctx.resolve('integrationCredentialsService') as any
+  const rawCreds = credentialsService
+    ? await credentialsService.resolve('integration_ksef_direct', {
+        tenantId: payload.tenantId,
+        organizationId: payload.organizationId,
+      })
+    : null
+  const { KsefDirectCredentialsSchema } = await import('../data/validators')
+  const credsParsed = KsefDirectCredentialsSchema.safeParse(rawCreds)
+  if (!credsParsed.success) return
+
+  const credentials = {
+    ksefToken: credsParsed.data.ksef_token,
+    nip: credsParsed.data.nip,
+    environment: credsParsed.data.environment,
+    tenantId: payload.tenantId,
+  }
+
+  const { queryReceivedInvoices, downloadInvoiceFromUrl } = await import('../lib/ksefClient')
+  const { KsefDirectReceivedDocument } = await import('../data/entities')
+  const { parseReceivedInvoiceXml } = await import('../lib/ksefXmlParser')
+  const { emitKsefDirectEvent } = await import('../events')
+
+  // Phase 1: enumerate all received invoices for the date range and upsert summaries
+  const result = await queryReceivedInvoices(credentials, {
+    dateFrom: payload.dateFrom,
+    dateTo: payload.dateTo,
+  })
+
+  const collectedRefs: string[] = []
+
+  for (const summary of result.items) {
+    collectedRefs.push(summary.ksefReferenceNumber)
+
+    const existing = await em.findOne(KsefDirectReceivedDocument, {
+      organizationId: payload.organizationId,
+      ksefReferenceNumber: summary.ksefReferenceNumber,
+    })
+
+    if (!existing) {
+      const record = em.create(KsefDirectReceivedDocument, {
+        organizationId: payload.organizationId,
+        tenantId: payload.tenantId,
+        ksefReferenceNumber: summary.ksefReferenceNumber,
+        sellerNip: summary.sellerNip,
+        sellerName: summary.sellerName,
+        issueDate: summary.issueDate,
+        grossAmount: summary.grossAmount,
+        netAmount: summary.netAmount,
+        vatAmount: summary.vatAmount,
+        currency: summary.currency,
+        invoiceNumber: summary.invoiceNumber,
+        upoDownloadUrl: summary.upoDownloadUrl,
+        invoiceDownloadUrl: summary.invoiceDownloadUrl,
+        status: 'pending_download',
+      })
+      em.persist(record)
+    } else {
+      // Keep URL fields fresh in case they changed (pre-signed URLs rotate)
+      if (summary.upoDownloadUrl) existing.upoDownloadUrl = summary.upoDownloadUrl
+      if (summary.invoiceDownloadUrl) existing.invoiceDownloadUrl = summary.invoiceDownloadUrl
+      if (existing.status === 'failed') {
+        existing.status = 'pending_download'
+        existing.errorMessage = null
+        existing.updatedAt = new Date()
+      }
+    }
+  }
+
+  await em.flush()
+
+  if (collectedRefs.length === 0) {
+    await emitKsefDirectEvent('ksef_direct.received_document.synced', {
+      organizationId: payload.organizationId,
+      tenantId: payload.tenantId,
+      syncedCount: 0,
+      failedCount: 0,
+      dateFrom: payload.dateFrom,
+      dateTo: payload.dateTo,
+    })
+    return
+  }
+
+  // Phase 2: download XML content for all pending records using stored URLs
+  const pendingRecords = await em.find(KsefDirectReceivedDocument, {
+    organizationId: payload.organizationId,
+    tenantId: payload.tenantId,
+    status: 'pending_download',
+    ksefReferenceNumber: { $in: collectedRefs },
+  })
+
+  let syncedCount = 0
+  let failedCount = 0
+
+  for (const record of pendingRecords) {
+    try {
+      const downloadUrl = record.invoiceDownloadUrl ?? record.upoDownloadUrl
+      if (!downloadUrl) {
+        throw new Error('No download URL available for this invoice')
+      }
+
+      const rawXml = await downloadInvoiceFromUrl(downloadUrl)
+      const parsed = parseReceivedInvoiceXml(rawXml)
+
+      record.rawXml = rawXml
+      // Only override metadata fields with parsed values when non-null (prefer KSeF API metadata)
+      if (parsed.invoiceNumber) record.invoiceNumber = parsed.invoiceNumber
+      if (parsed.sellerNip) record.sellerNip = parsed.sellerNip
+      if (parsed.sellerName) record.sellerName = parsed.sellerName
+      if (parsed.issueDate) record.issueDate = parsed.issueDate
+      if (parsed.currency) record.currency = parsed.currency
+      if (parsed.netAmount) record.netAmount = parsed.netAmount
+      if (parsed.vatAmount) record.vatAmount = parsed.vatAmount
+      if (parsed.grossAmount) record.grossAmount = parsed.grossAmount
+      record.status = 'downloaded'
+      record.syncedAt = new Date()
+      record.updatedAt = new Date()
+      await em.flush()
+      syncedCount++
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : 'Unknown error during XML download'
+      record.status = 'failed'
+      record.errorMessage = errorMessage
+      record.updatedAt = new Date()
+      await em.flush()
+      failedCount++
+
+      await emitKsefDirectEvent('ksef_direct.received_document.failed', {
+        organizationId: payload.organizationId,
+        tenantId: payload.tenantId,
+        ksefReferenceNumber: record.ksefReferenceNumber,
+        errorMessage,
+      })
+    }
+  }
+
+  await emitKsefDirectEvent('ksef_direct.received_document.synced', {
+    organizationId: payload.organizationId,
+    tenantId: payload.tenantId,
+    syncedCount,
+    failedCount,
+    dateFrom: payload.dateFrom,
+    dateTo: payload.dateTo,
+  })
+}

package/src/types/declarations.d.ts

@@ -0,0 +1 @@
+declare module '@open-mercato/core/*'