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

package/src/modules/integration_ksef_direct/backend/page.tsx

@@ -0,0 +1,183 @@
+"use client"
+
+import * as React from 'react'
+import Link from 'next/link'
+import { FileText, Inbox } from 'lucide-react'
+import { Page, PageBody } from '@open-mercato/ui/backend/Page'
+import { SectionHeader } from '@open-mercato/ui/backend/SectionHeader'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { StatusBadge } from '@open-mercato/ui/primitives/status-badge'
+import { LoadingMessage, ErrorMessage } from '@open-mercato/ui/backend/detail'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
+
+export const pageMetadata = {
+  requireAuth: true,
+  requireFeatures: ['integration_ksef_direct.manage'],
+}
+
+type HealthStatus = 'unconfigured' | 'checking' | 'connected' | 'error'
+
+type ConnectionState = {
+  status: HealthStatus
+  lastCheckedAt: string | null
+  environment?: 'test' | 'production'
+  rateLimits?: { otherPerSecond?: number; otherPerMinute?: number }
+  error?: string
+  errorCode?: string
+}
+
+export default function KsefDirectPage() {
+  const t = useT()
+  const scopeVersion = useOrganizationScopeVersion()
+  const [state, setState] = React.useState<ConnectionState | null>(null)
+  const [isLoading, setLoading] = React.useState(false)
+  const [isChecking, setChecking] = React.useState(false)
+  const [fetchError, setFetchError] = React.useState<string | null>(null)
+
+  const fetchStatus = React.useCallback(async () => {
+    setLoading(true)
+    setFetchError(null)
+    try {
+      const result = await apiCall<ConnectionState>('/api/integration-ksef-direct/health')
+      if (result.ok && result.result) {
+        setState(result.result)
+      } else {
+        setFetchError('Failed to load connection status')
+      }
+    } catch {
+      setFetchError('Failed to load connection status')
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  React.useEffect(() => { fetchStatus() }, [fetchStatus, scopeVersion])
+
+  React.useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        window.history.back()
+      }
+    }
+    window.addEventListener('keydown', handleKeyDown)
+    return () => window.removeEventListener('keydown', handleKeyDown)
+  }, [])
+
+  async function handleCheckConnection() {
+    setChecking(true)
+    try {
+      const result = await apiCall<ConnectionState>('/api/integration-ksef-direct/health')
+      if (result.ok && result.result) {
+        setState(result.result)
+      }
+    } finally {
+      setChecking(false)
+    }
+  }
+
+  function getStatusVariant(status: HealthStatus): 'success' | 'error' | 'neutral' | 'warning' {
+    switch (status) {
+      case 'connected': return 'success'
+      case 'error': return 'error'
+      case 'checking': return 'warning'
+      default: return 'neutral'
+    }
+  }
+
+  function getStatusLabel(status: HealthStatus): string {
+    switch (status) {
+      case 'connected': return t('integration_ksef_direct.health.connected', 'Connected')
+      case 'error': return t('integration_ksef_direct.health.error', 'Connection error')
+      case 'checking': return t('integration_ksef_direct.health.checking', 'Checking...')
+      default: return t('integration_ksef_direct.health.unconfigured', 'Not configured')
+    }
+  }
+
+  return (
+    <Page>
+      <PageBody>
+        <SectionHeader title={t('integration_ksef_direct.title', 'KSeF Direct Integration')} />
+
+        {isLoading && !state && <LoadingMessage label={t('integration_ksef_direct.health.loading', 'Loading...')} />}
+        {fetchError && !isLoading && <ErrorMessage label={fetchError} />}
+
+        <div className="grid grid-cols-2 gap-3 mt-2 mb-6">
+          <Link href="/backend/integration-ksef-direct/documents">
+            <div className="flex items-center gap-3 rounded-lg border border-border p-4 hover:bg-muted/50 transition-colors cursor-pointer">
+              <FileText className="h-5 w-5 text-muted-foreground shrink-0" />
+              <div>
+                <p className="text-sm font-medium">{t('integration_ksef_direct.nav.documents', 'Sent Documents')}</p>
+                <p className="text-xs text-muted-foreground">{t('integration_ksef_direct.nav.documents_desc', 'Outgoing invoices sent to KSeF')}</p>
+              </div>
+            </div>
+          </Link>
+          <Link href="/backend/integration-ksef-direct/received-documents">
+            <div className="flex items-center gap-3 rounded-lg border border-border p-4 hover:bg-muted/50 transition-colors cursor-pointer">
+              <Inbox className="h-5 w-5 text-muted-foreground shrink-0" />
+              <div>
+                <p className="text-sm font-medium">{t('integration_ksef_direct.nav.received_documents', 'Received Documents')}</p>
+                <p className="text-xs text-muted-foreground">{t('integration_ksef_direct.nav.received_documents_desc', 'Invoices received from KSeF')}</p>
+              </div>
+            </div>
+          </Link>
+        </div>
+
+        {state && (
+          <div className="space-y-4">
+            <div className="flex items-center gap-3">
+              <StatusBadge variant={getStatusVariant(state.status)}>
+                {getStatusLabel(state.status)}
+              </StatusBadge>
+              {state.environment && (
+                <span className="text-sm text-muted-foreground">
+                  {t('integration_ksef_direct.health.environment', 'Environment:')} <strong>{state.environment.toUpperCase()}</strong>
+                </span>
+              )}
+            </div>
+
+            {state.lastCheckedAt && (
+              <p className="text-sm text-muted-foreground">
+                {t('integration_ksef_direct.health.last_checked', 'Last check:')}{' '}
+                {new Date(state.lastCheckedAt).toLocaleString()}
+              </p>
+            )}
+
+            {state.status === 'connected' && state.rateLimits && (
+              <p className="text-sm text-muted-foreground">
+                {t('integration_ksef_direct.health.rate_limits', 'Rate limits:')}{' '}
+                {[
+                  state.rateLimits.otherPerSecond != null && `${state.rateLimits.otherPerSecond} req/s`,
+                  state.rateLimits.otherPerMinute != null && `${state.rateLimits.otherPerMinute} req/min`,
+                ]
+                  .filter(Boolean)
+                  .join(' · ')}
+              </p>
+            )}
+
+            {state.status === 'error' && state.error && (
+              <ErrorMessage
+                label={state.error}
+                description={state.errorCode}
+              />
+            )}
+
+            <div className="flex justify-end pt-2">
+              <Button
+                type="button"
+                onClick={handleCheckConnection}
+                disabled={isChecking}
+                variant="outline"
+              >
+                {isChecking
+                  ? t('integration_ksef_direct.health.checking', 'Checking...')
+                  : t('integration_ksef_direct.health.check_button', 'Check connection')}
+              </Button>
+            </div>
+          </div>
+        )}
+      </PageBody>
+    </Page>
+  )
+}

package/src/modules/integration_ksef_direct/commands/create-ksef-direct-document.ts

@@ -0,0 +1,93 @@
+import type { CreateKsefDirectDocumentInput, KsefDirectLineItemInput } from '../data/validators'
+import { KsefDirectDocument, type KsefDirectStoredLineItem } from '../data/entities'
+import { emitKsefDirectEvent } from '../events'
+
+export class KsefDirectNotConfiguredError extends Error {
+  constructor() {
+    super('KSEF_DIRECT_NOT_CONFIGURED')
+    this.name = 'KsefDirectNotConfiguredError'
+  }
+}
+
+const VAT_RATE_MAP: Record<string, number> = { '0': 0, '5': 5, '8': 8, '23': 23, ZW: 0, NP: 0 }
+
+function round2(value: number): number {
+  return Math.round(value * 100) / 100
+}
+
+function computeLineItem(item: KsefDirectLineItemInput): KsefDirectStoredLineItem {
+  const netAmount = round2(item.quantity * item.unitNetPrice)
+  const rate = VAT_RATE_MAP[item.vatRate] ?? 0
+  const vatAmount = round2(netAmount * rate / 100)
+  return {
+    description: item.description,
+    quantity: item.quantity,
+    unit: item.unit,
+    unitNetPrice: item.unitNetPrice,
+    vatRate: item.vatRate,
+    netAmount,
+    vatAmount,
+    grossAmount: round2(netAmount + vatAmount),
+  }
+}
+
+export async function createKsefDirectDocument(
+  em: any,
+  tenantId: string,
+  organizationId: string,
+  input: CreateKsefDirectDocumentInput,
+  credentialsService: any,
+): Promise<{ id: string; status: string; invoiceNumber: string; sellerNip: string }> {
+  const credentials = await credentialsService?.resolve('integration_ksef_direct', { tenantId, organizationId })
+  if (!credentials?.nip) {
+    throw new KsefDirectNotConfiguredError()
+  }
+
+  let sellerName = input.sellerName ?? null
+  if (!sellerName) {
+    const { Organization } = await import('@open-mercato/core/modules/directory/data/entities')
+    const org = await em.findOne(Organization, { id: organizationId })
+    sellerName = org?.name ?? null
+  }
+
+  const storedLineItems = input.lineItems.map(computeLineItem)
+  const netAmount = round2(storedLineItems.reduce((sum, l) => sum + l.netAmount, 0))
+  const vatAmount = round2(storedLineItems.reduce((sum, l) => sum + l.vatAmount, 0))
+  const grossAmount = round2(netAmount + vatAmount)
+  const now = new Date()
+
+  const doc = em.create(KsefDirectDocument, {
+    organizationId,
+    tenantId,
+    source: 'manual' as const,
+    status: 'draft' as const,
+    sellerNip: credentials.nip,
+    sellerName,
+    sellerAddressL1: input.sellerAddressL1 ?? null,
+    sellerCity: input.sellerCity ?? null,
+    sellerCountry: input.sellerCountry ?? null,
+    buyerNip: input.buyerNip,
+    buyerName: input.buyerName ?? null,
+    invoiceNumber: input.invoiceNumber,
+    issueDate: new Date(input.issueDate),
+    saleDate: input.saleDate ? new Date(input.saleDate) : null,
+    netAmount: String(netAmount),
+    vatAmount: String(vatAmount),
+    grossAmount: String(grossAmount),
+    currency: input.currency ?? 'PLN',
+    lineItems: storedLineItems,
+    notes: input.notes ?? null,
+    createdAt: now,
+    updatedAt: now,
+  })
+
+  await em.persist(doc).flush()
+
+  await emitKsefDirectEvent('ksef_direct.document.created', {
+    documentId: doc.id,
+    organizationId,
+    tenantId,
+  })
+
+  return { id: doc.id, status: doc.status, invoiceNumber: doc.invoiceNumber, sellerNip: doc.sellerNip }
+}

package/src/modules/integration_ksef_direct/commands/enqueue-ksef-direct-document.ts

@@ -0,0 +1,57 @@
+import { createModuleQueue } from '@open-mercato/queue'
+import { KsefDirectDocument } from '../data/entities'
+import { emitKsefDirectEvent } from '../events'
+
+export class KsefDocumentNotFoundError extends Error {
+  readonly status = 404
+  constructor() {
+    super('Document not found')
+    this.name = 'KsefDocumentNotFoundError'
+  }
+}
+
+export class KsefDocumentNotQueueableError extends Error {
+  readonly status = 409
+  constructor(currentStatus: string) {
+    super(`Document cannot be queued: current status is '${currentStatus}'`)
+    this.name = 'KsefDocumentNotQueueableError'
+  }
+}
+
+export type SendKsefDocumentJobPayload = {
+  documentId: string
+  organizationId: string
+  tenantId: string
+}
+
+export async function enqueueKsefDirectDocument(
+  em: any,
+  tenantId: string,
+  organizationId: string,
+  documentId: string,
+): Promise<{ id: string; status: string; invoiceNumber: string }> {
+  const doc = await em.findOne(KsefDirectDocument, { id: documentId, organizationId, tenantId })
+
+  if (!doc) {
+    throw new KsefDocumentNotFoundError()
+  }
+
+  if (!['draft', 'failed'].includes(doc.status)) {
+    throw new KsefDocumentNotQueueableError(doc.status)
+  }
+
+  doc.status = 'queued'
+  doc.updatedAt = new Date()
+  await em.flush()
+
+  await emitKsefDirectEvent('ksef_direct.document.queued', {
+    documentId: doc.id,
+    organizationId,
+    tenantId,
+  })
+
+  const queue = createModuleQueue<SendKsefDocumentJobPayload>('ksef_direct_send')
+  await queue.enqueue({ documentId: doc.id, organizationId, tenantId })
+
+  return { id: doc.id, status: doc.status, invoiceNumber: doc.invoiceNumber }
+}

package/src/modules/integration_ksef_direct/data/entities.ts

@@ -0,0 +1,195 @@
+import { Entity, PrimaryKey, Property, Index, Unique } from '@mikro-orm/decorators/legacy'
+
+export interface KsefDirectStoredLineItem {
+  description: string
+  quantity: number
+  unit: string
+  unitNetPrice: number
+  vatRate: string
+  netAmount: number
+  vatAmount: number
+  grossAmount: number
+}
+
+@Entity({ tableName: 'ksef_direct_documents' })
+@Index({ properties: ['organizationId', 'tenantId'] })
+@Index({ properties: ['organizationId', 'tenantId', 'status'] })
+@Index({ properties: ['organizationId', 'tenantId', 'source'] })
+@Index({ properties: ['ksefReferenceNumber'] })
+export class KsefDirectDocument {
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'source', type: 'text', default: 'manual' })
+  source: 'manual' | 'ksef_sync' | 'sales_invoice' = 'manual'
+
+  @Property({ name: 'status', type: 'text', default: 'draft' })
+  status: 'draft' | 'queued' | 'sending' | 'sent' | 'failed' = 'draft'
+
+  @Property({ name: 'ksef_reference_number', type: 'text', nullable: true })
+  ksefReferenceNumber?: string | null
+
+  @Property({ name: 'seller_nip', type: 'text' })
+  sellerNip!: string
+
+  @Property({ name: 'buyer_nip', type: 'text' })
+  buyerNip!: string
+
+  @Property({ name: 'buyer_name', type: 'text', nullable: true })
+  buyerName?: string | null
+
+  @Property({ name: 'invoice_number', type: 'text' })
+  invoiceNumber!: string
+
+  @Property({ name: 'issue_date', type: Date })
+  issueDate!: Date
+
+  @Property({ name: 'sale_date', type: Date, nullable: true })
+  saleDate?: Date | null
+
+  @Property({ name: 'net_amount', type: 'string', columnType: 'numeric(15,2)' })
+  netAmount!: string
+
+  @Property({ name: 'vat_amount', type: 'string', columnType: 'numeric(15,2)' })
+  vatAmount!: string
+
+  @Property({ name: 'gross_amount', type: 'string', columnType: 'numeric(15,2)' })
+  grossAmount!: string
+
+  @Property({ name: 'currency', type: 'text', default: 'PLN' })
+  currency: string = 'PLN'
+
+  @Property({ name: 'line_items', type: 'json', columnType: 'jsonb' })
+  lineItems: KsefDirectStoredLineItem[] = []
+
+  @Property({ name: 'notes', type: 'text', nullable: true })
+  notes?: string | null
+
+  @Property({ name: 'ksef_processing_reference_number', type: 'text', nullable: true })
+  ksefProcessingReferenceNumber?: string | null
+
+  @Property({ name: 'seller_name', type: 'text', nullable: true })
+  sellerName?: string | null
+
+  @Property({ name: 'seller_address_l1', type: 'text', nullable: true })
+  sellerAddressL1?: string | null
+
+  @Property({ name: 'seller_city', type: 'text', nullable: true })
+  sellerCity?: string | null
+
+  @Property({ name: 'seller_country', type: 'text', nullable: true })
+  sellerCountry?: string | null
+
+  @Property({ name: 'error_message', type: 'text', nullable: true })
+  errorMessage?: string | null
+
+  @Property({ name: 'created_at', type: Date })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+}
+
+@Entity({ tableName: 'ksef_direct_received_documents' })
+@Index({ properties: ['organizationId', 'tenantId'] })
+@Index({ properties: ['organizationId', 'tenantId', 'status'] })
+@Unique({ properties: ['organizationId', 'ksefReferenceNumber'] })
+export class KsefDirectReceivedDocument {
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'ksef_reference_number', type: 'text' })
+  ksefReferenceNumber!: string
+
+  @Property({ name: 'raw_xml', type: 'text', nullable: true })
+  rawXml?: string | null
+
+  @Property({ name: 'invoice_number', type: 'text', nullable: true })
+  invoiceNumber?: string | null
+
+  @Property({ name: 'seller_nip', type: 'text', nullable: true })
+  sellerNip?: string | null
+
+  @Property({ name: 'seller_name', type: 'text', nullable: true })
+  sellerName?: string | null
+
+  @Property({ name: 'issue_date', type: 'string', columnType: 'date', nullable: true })
+  issueDate?: string | null
+
+  @Property({ name: 'currency', type: 'text', nullable: true })
+  currency?: string | null
+
+  @Property({ name: 'net_amount', type: 'string', columnType: 'numeric(15,2)', nullable: true })
+  netAmount?: string | null
+
+  @Property({ name: 'vat_amount', type: 'string', columnType: 'numeric(15,2)', nullable: true })
+  vatAmount?: string | null
+
+  @Property({ name: 'gross_amount', type: 'string', columnType: 'numeric(15,2)', nullable: true })
+  grossAmount?: string | null
+
+  @Property({ name: 'status', type: 'text', default: 'pending_download' })
+  status: 'pending_download' | 'downloaded' | 'failed' = 'pending_download'
+
+  @Property({ name: 'error_message', type: 'text', nullable: true })
+  errorMessage?: string | null
+
+  @Property({ name: 'upo_download_url', type: 'text', nullable: true })
+  upoDownloadUrl?: string | null
+
+  @Property({ name: 'invoice_download_url', type: 'text', nullable: true })
+  invoiceDownloadUrl?: string | null
+
+  @Property({ name: 'synced_at', type: Date, nullable: true })
+  syncedAt?: Date | null
+
+  @Property({ name: 'created_at', type: Date })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+}
+
+@Entity({ tableName: 'ksef_direct_connections' })
+@Index({ properties: ['status', 'updatedAt'] })
+@Unique({ properties: ['organizationId', 'tenantId'] })
+export class KsefDirectConnection {
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'status', type: 'text', default: 'unconfigured' })
+  status: 'unconfigured' | 'checking' | 'connected' | 'error' = 'unconfigured'
+
+  @Property({ name: 'last_checked_at', type: Date, nullable: true })
+  lastCheckedAt?: Date | null
+
+  @Property({ name: 'error_message', type: 'text', nullable: true })
+  errorMessage?: string | null
+
+  @Property({ name: 'error_code', type: 'text', nullable: true })
+  errorCode?: string | null
+
+  @Property({ name: 'created_at', type: Date })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+}

package/src/modules/integration_ksef_direct/data/validators.ts

@@ -0,0 +1,115 @@
+import { z } from 'zod'
+
+const dateString = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Must be YYYY-MM-DD')
+const vatRates = ['0', '5', '8', '23', 'ZW', 'NP'] as const
+
+export const KsefDirectLineItemSchema = z.object({
+  description: z.string().min(1),
+  quantity: z.number().positive(),
+  unit: z.string().min(1).default('szt'),
+  unitNetPrice: z.number().min(0),
+  vatRate: z.enum(vatRates),
+})
+
+export const CreateKsefDirectDocumentSchema = z.object({
+  buyerNip: z.string().regex(/^\d{10}$/, 'NIP must be 10 digits'),
+  buyerName: z.string().max(256).optional(),
+  invoiceNumber: z.string().min(1).max(256),
+  issueDate: dateString,
+  saleDate: dateString.optional(),
+  currency: z.string().length(3).default('PLN'),
+  lineItems: z.array(KsefDirectLineItemSchema).min(1),
+  notes: z.string().optional(),
+  sellerName: z.string().min(1).max(512).optional(),
+  sellerAddressL1: z.string().min(1).max(512),
+  sellerCity: z.string().min(1).max(256),
+  sellerCountry: z.string().length(2).optional(),
+})
+
+export type CreateKsefDirectDocumentInput = z.infer<typeof CreateKsefDirectDocumentSchema>
+export type KsefDirectLineItemInput = z.infer<typeof KsefDirectLineItemSchema>
+
+export const KsefDirectConnectionStatusSchema = z.enum(['unconfigured', 'checking', 'connected', 'error'])
+
+export const KsefDirectCredentialsSchema = z.object({
+  ksef_token: z.string().min(1),
+  nip: z.string().min(1),
+  environment: z.enum(['test', 'production']),
+})
+
+export const KsefDirectRateLimitsSchema = z.object({
+  otherPerSecond: z.number().optional(),
+  otherPerMinute: z.number().optional(),
+})
+
+export const KsefDirectHealthResponseSchema = z.discriminatedUnion('status', [
+  z.object({
+    status: z.literal('connected'),
+    lastCheckedAt: z.string(),
+    environment: z.enum(['test', 'production']),
+    rateLimits: KsefDirectRateLimitsSchema.optional(),
+  }),
+  z.object({
+    status: z.literal('error'),
+    lastCheckedAt: z.string(),
+    error: z.string(),
+    errorCode: z.string(),
+  }),
+  z.object({
+    status: z.literal('unconfigured'),
+    lastCheckedAt: z.null(),
+  }),
+  z.object({
+    status: z.literal('checking'),
+    lastCheckedAt: z.string().nullable(),
+  }),
+])
+
+export type KsefDirectCredentials = z.infer<typeof KsefDirectCredentialsSchema>
+export type KsefDirectHealthResponse = z.infer<typeof KsefDirectHealthResponseSchema>
+export type KsefDirectRateLimits = z.infer<typeof KsefDirectRateLimitsSchema>
+
+export const KsefSendInvoiceResponseSchema = z.object({
+  referenceNumber: z.string(),
+  processingCode: z.number().optional(),
+  processingDescription: z.string().optional(),
+  timestamp: z.string().optional(),
+}).passthrough()
+
+export const KsefInvoiceStatusResponseSchema = z.object({
+  referenceNumber: z.string(),
+  processingCode: z.number(),
+  processingDescription: z.string().optional(),
+  invoiceStatus: z.object({
+    ksefReferenceNumber: z.string().optional(),
+    invoiceNumber: z.string().optional(),
+  }).optional(),
+}).passthrough()
+
+export type KsefSendInvoiceResponse = z.infer<typeof KsefSendInvoiceResponseSchema>
+export type KsefInvoiceStatusResponse = z.infer<typeof KsefInvoiceStatusResponseSchema>
+
+const isoDate = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Must be YYYY-MM-DD')
+
+export const ReceivedDocumentSyncSchema = z.object({
+  dateFrom: isoDate,
+  dateTo: isoDate,
+}).refine(
+  (data) => data.dateTo >= data.dateFrom,
+  { message: 'dateTo must be >= dateFrom', path: ['dateTo'] },
+).refine(
+  (data) => {
+    const from = new Date(data.dateFrom)
+    const to = new Date(data.dateTo)
+    const diffDays = (to.getTime() - from.getTime()) / (1000 * 60 * 60 * 24)
+    return diffDays <= 366
+  },
+  { message: 'Date range must not exceed 366 days', path: ['dateTo'] },
+)
+
+export const ReceivedDocumentFetchSchema = z.object({
+  ksefReferenceNumber: z.string().min(1),
+})
+
+export type ReceivedDocumentSyncInput = z.infer<typeof ReceivedDocumentSyncSchema>
+export type ReceivedDocumentFetchInput = z.infer<typeof ReceivedDocumentFetchSchema>

package/src/modules/integration_ksef_direct/di.ts

@@ -0,0 +1,9 @@
+import { asValue } from 'awilix'
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import { ksefDirectHealthChecker } from './lib/health'
+
+export function register(container: AppContainer) {
+  container.register({
+    ksefDirectHealthChecker: asValue(ksefDirectHealthChecker),
+  })
+}

package/src/modules/integration_ksef_direct/events.ts

@@ -0,0 +1,18 @@
+import { createModuleEvents } from '@open-mercato/shared/modules/events'
+
+const events = [
+  { id: 'ksef_direct.connection.connected', label: 'KSeF Direct Connection Established', entity: 'ksef_direct_connection', category: 'lifecycle' },
+  { id: 'ksef_direct.connection.failed', label: 'KSeF Direct Connection Failed', entity: 'ksef_direct_connection', category: 'lifecycle' },
+  { id: 'ksef_direct.connection.checked', label: 'KSeF Direct Connection Checked', entity: 'ksef_direct_connection', category: 'lifecycle' },
+  { id: 'ksef_direct.document.created', label: 'KSeF Direct Document Created', entity: 'ksef_direct_document', category: 'lifecycle' },
+  { id: 'ksef_direct.document.queued', label: 'KSeF Direct Document Queued', entity: 'ksef_direct_document', category: 'lifecycle', clientBroadcast: true },
+  { id: 'ksef_direct.document.sent', label: 'KSeF Direct Document Sent', entity: 'ksef_direct_document', category: 'lifecycle', clientBroadcast: true },
+  { id: 'ksef_direct.document.failed', label: 'KSeF Direct Document Failed', entity: 'ksef_direct_document', category: 'lifecycle', clientBroadcast: true },
+  { id: 'ksef_direct.received_document.synced', label: 'KSeF Direct Received Documents Synced', entity: 'ksef_direct_received_document', category: 'lifecycle' },
+  { id: 'ksef_direct.received_document.failed', label: 'KSeF Direct Received Document Failed', entity: 'ksef_direct_received_document', category: 'lifecycle' },
+] as const
+
+export const eventsConfig = createModuleEvents({ moduleId: 'integration_ksef_direct', events })
+export const emitKsefDirectEvent = eventsConfig.emit
+export type KsefDirectEventId = typeof events[number]['id']
+export default eventsConfig