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

package/src/modules/integration_ksef_direct/api/post/integration-ksef-direct/documents/[id]/send.ts

@@ -0,0 +1,64 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import {
+  enqueueKsefDirectDocument,
+  KsefDocumentNotFoundError,
+  KsefDocumentNotQueueableError,
+} from '../../../../../commands/enqueue-ksef-direct-document'
+
+export const metadata = {
+  path: '/integration-ksef-direct/documents/[id]/send',
+  POST: { requireAuth: true, requireFeatures: ['integration_ksef_direct.documents.send'] },
+}
+
+export async function POST(req: Request, { params }: { params: { id: string } }) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const container = await createRequestContainer()
+  const em = container.resolve('em') as any
+
+  try {
+    const result = await enqueueKsefDirectDocument(em, auth.tenantId, auth.orgId, params.id)
+    return NextResponse.json(result, { status: 200 })
+  } catch (err) {
+    if (err instanceof KsefDocumentNotFoundError) {
+      return NextResponse.json({ error: 'Document not found' }, { status: 404 })
+    }
+    if (err instanceof KsefDocumentNotQueueableError) {
+      return NextResponse.json({ error: err.message }, { status: 409 })
+    }
+    throw err
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'KSeF Direct',
+  summary: 'Send KSeF Direct document',
+  methods: {
+    POST: {
+      summary: 'Queue a KSeF Direct document for sending',
+      description: 'Transitions a document from draft or failed status to queued and enqueues it for KSeF submission.',
+      responses: [
+        {
+          status: 200,
+          description: 'Document queued',
+          schema: z.object({
+            id: z.string().uuid(),
+            status: z.literal('queued'),
+            invoiceNumber: z.string(),
+          }),
+        },
+      ],
+      errors: [
+        { status: 404, description: 'Document not found', schema: z.object({ error: z.string() }) },
+        { status: 409, description: 'Document cannot be queued in current status', schema: z.object({ error: z.string() }) },
+      ],
+    },
+  },
+}

package/src/modules/integration_ksef_direct/api/post/integration-ksef-direct/documents.ts

@@ -0,0 +1,109 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { validateCrudMutationGuard, runCrudMutationGuardAfterSuccess } from '@open-mercato/shared/lib/crud/mutation-guard'
+import { CreateKsefDirectDocumentSchema } from '../../../data/validators'
+import { createKsefDirectDocument, KsefDirectNotConfiguredError } from '../../../commands/create-ksef-direct-document'
+
+export const metadata = {
+  path: '/integration-ksef-direct/documents',
+  POST: { requireAuth: true, requireFeatures: ['integration_ksef_direct.documents.create'] },
+}
+
+export async function POST(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const body = await readJsonSafe(req, {})
+  const parsed = CreateKsefDirectDocumentSchema.safeParse(body)
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: 'Validation failed', fieldErrors: parsed.error.flatten().fieldErrors },
+      { status: 400 },
+    )
+  }
+
+  const container = await createRequestContainer()
+
+  const guardResult = await validateCrudMutationGuard(container, {
+    tenantId: auth.tenantId,
+    organizationId: auth.orgId,
+    userId: auth.sub ?? '',
+    resourceKind: 'integration_ksef_direct.document',
+    resourceId: 'new',
+    operation: 'create',
+    requestMethod: 'POST',
+    requestHeaders: req.headers,
+  })
+  if (guardResult && !guardResult.ok) {
+    return NextResponse.json(guardResult.body, { status: guardResult.status })
+  }
+
+  const em = container.resolve('em') as any
+  const credentialsService = container.resolve('integrationCredentialsService') as any
+
+  let result: { id: string; status: string; invoiceNumber: string; sellerNip: string }
+  try {
+    result = await createKsefDirectDocument(em, auth.tenantId, auth.orgId, parsed.data, credentialsService)
+  } catch (err) {
+    if (err instanceof KsefDirectNotConfiguredError) {
+      return NextResponse.json(
+        { error: 'KSeF Direct integration is not configured. Set up NIP in integration credentials first.' },
+        { status: 422 },
+      )
+    }
+    throw err
+  }
+
+  if (guardResult?.shouldRunAfterSuccess) {
+    await runCrudMutationGuardAfterSuccess(container, {
+      tenantId: auth.tenantId,
+      organizationId: auth.orgId,
+      userId: auth.sub ?? '',
+      resourceKind: 'integration_ksef_direct.document',
+      resourceId: result.id,
+      operation: 'create',
+      requestMethod: 'POST',
+      requestHeaders: req.headers,
+      metadata: guardResult.metadata,
+    })
+  }
+
+  return NextResponse.json(result, { status: 201 })
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'KSeF Direct',
+  summary: 'Create KSeF Direct document',
+  methods: {
+    POST: {
+      summary: 'Create a manual KSeF Direct document',
+      description: 'Creates a document record in draft status from manually entered invoice data.',
+      requestBody: {
+        contentType: 'application/json',
+        schema: CreateKsefDirectDocumentSchema,
+      },
+      responses: [
+        {
+          status: 201,
+          description: 'Document created',
+          schema: z.object({
+            id: z.string().uuid(),
+            status: z.literal('draft'),
+            invoiceNumber: z.string(),
+            sellerNip: z.string(),
+          }),
+        },
+      ],
+      errors: [
+        { status: 400, description: 'Validation error', schema: z.object({ error: z.string(), fieldErrors: z.record(z.string(), z.array(z.string())).optional() }) },
+        { status: 422, description: 'Integration not configured', schema: z.object({ error: z.string() }) },
+      ],
+    },
+  },
+}

package/src/modules/integration_ksef_direct/api/post/integration-ksef-direct/invoice-numbers.ts

@@ -0,0 +1,40 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { generateKsefInvoiceNumber } from '../../../lib/invoiceNumberFormat'
+
+export const metadata = {
+  path: '/integration-ksef-direct/invoice-numbers',
+  POST: { requireAuth: true, requireFeatures: ['integration_ksef_direct.documents.create'] },
+}
+
+export async function POST(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const number = generateKsefInvoiceNumber()
+  return NextResponse.json({ number }, { status: 201 })
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'KSeF Direct',
+  summary: 'Generate KSeF invoice number',
+  methods: {
+    POST: {
+      summary: 'Generate a unique KSeF invoice number',
+      description: 'Returns a unique invoice number in FV/{yyyy}/{mm}/{id} format using a cryptographically random identifier.',
+      responses: [
+        {
+          status: 201,
+          description: 'Generated invoice number',
+          schema: z.object({
+            number: z.string(),
+          }),
+        },
+      ],
+    },
+  },
+}

package/src/modules/integration_ksef_direct/api/post/integration-ksef-direct/received-documents/fetch.ts

@@ -0,0 +1,185 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { ReceivedDocumentFetchSchema } from '../../../../data/validators'
+import { KsefNetworkError } from '../../../../lib/ksefClient'
+
+export const metadata = {
+  path: '/integration-ksef-direct/received-documents/fetch',
+  POST: { requireAuth: true, requireFeatures: ['integration_ksef_direct.received_documents.sync'] },
+}
+
+const receivedDocumentResponseSchema = z.object({
+  id: z.string().uuid(),
+  ksefReferenceNumber: z.string(),
+  invoiceNumber: z.string().nullable(),
+  sellerNip: z.string().nullable(),
+  sellerName: z.string().nullable(),
+  issueDate: z.string().nullable(),
+  currency: z.string().nullable(),
+  netAmount: z.string().nullable(),
+  vatAmount: z.string().nullable(),
+  grossAmount: z.string().nullable(),
+  rawXml: z.string(),
+  status: z.literal('downloaded'),
+  errorMessage: z.null(),
+  syncedAt: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+})
+
+export async function POST(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const body = await readJsonSafe(req, {})
+  const parsed = ReceivedDocumentFetchSchema.safeParse(body)
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid request' }, { status: 400 })
+  }
+
+  const container = await createRequestContainer()
+  const credentialsService = container.resolve('integrationCredentialsService') as any
+  const rawCreds = credentialsService
+    ? await credentialsService.resolve('integration_ksef_direct', {
+        tenantId: auth.tenantId,
+        organizationId: auth.orgId,
+      })
+    : null
+
+  const { KsefDirectCredentialsSchema } = await import('../../../../data/validators')
+  const credsParsed = KsefDirectCredentialsSchema.safeParse(rawCreds)
+  if (!credsParsed.success) {
+    return NextResponse.json({ error: 'KSeF credentials not configured' }, { status: 409 })
+  }
+
+  const credentials = {
+    ksefToken: credsParsed.data.ksef_token,
+    nip: credsParsed.data.nip,
+    environment: credsParsed.data.environment,
+    tenantId: auth.tenantId,
+  }
+
+  const { downloadInvoice } = await import('../../../../lib/ksefClient')
+  const { parseReceivedInvoiceXml } = await import('../../../../lib/ksefXmlParser')
+  const { KsefDirectReceivedDocument } = await import('../../../../data/entities')
+
+  let rawContent: string
+  let upoDownloadUrl: string | null = null
+  let invoiceDownloadUrl: string | null = null
+
+  try {
+    const result = await downloadInvoice(credentials, parsed.data.ksefReferenceNumber)
+    rawContent = result.rawContent
+    upoDownloadUrl = result.upoDownloadUrl
+    invoiceDownloadUrl = result.invoiceDownloadUrl
+  } catch (err) {
+    if (err instanceof KsefNetworkError) {
+      return NextResponse.json({ error: `KSeF API error: ${err.message}` }, { status: 502 })
+    }
+    if (err instanceof Error && (err.name === 'TimeoutError' || err.name === 'AbortError')) {
+      return NextResponse.json({ error: 'KSeF API request timed out' }, { status: 504 })
+    }
+    throw err
+  }
+
+  const parsedXml = parseReceivedInvoiceXml(rawContent)
+  const em = container.resolve('em') as any
+  const now = new Date()
+
+  let record = await em.findOne(KsefDirectReceivedDocument, {
+    organizationId: auth.orgId,
+    ksefReferenceNumber: parsed.data.ksefReferenceNumber,
+  })
+
+  if (record) {
+    record.rawXml = rawContent
+    if (parsedXml.invoiceNumber) record.invoiceNumber = parsedXml.invoiceNumber
+    if (parsedXml.sellerNip) record.sellerNip = parsedXml.sellerNip
+    if (parsedXml.sellerName) record.sellerName = parsedXml.sellerName
+    if (parsedXml.issueDate) record.issueDate = parsedXml.issueDate
+    if (parsedXml.currency) record.currency = parsedXml.currency
+    if (parsedXml.netAmount) record.netAmount = parsedXml.netAmount
+    if (parsedXml.vatAmount) record.vatAmount = parsedXml.vatAmount
+    if (parsedXml.grossAmount) record.grossAmount = parsedXml.grossAmount
+    if (upoDownloadUrl) record.upoDownloadUrl = upoDownloadUrl
+    if (invoiceDownloadUrl) record.invoiceDownloadUrl = invoiceDownloadUrl
+    record.status = 'downloaded'
+    record.errorMessage = null
+    record.syncedAt = now
+    record.updatedAt = now
+  } else {
+    record = em.create(KsefDirectReceivedDocument, {
+      organizationId: auth.orgId,
+      tenantId: auth.tenantId,
+      ksefReferenceNumber: parsed.data.ksefReferenceNumber,
+      rawXml: rawContent,
+      invoiceNumber: parsedXml.invoiceNumber ?? null,
+      sellerNip: parsedXml.sellerNip ?? null,
+      sellerName: parsedXml.sellerName ?? null,
+      issueDate: parsedXml.issueDate ?? null,
+      currency: parsedXml.currency ?? null,
+      netAmount: parsedXml.netAmount ?? null,
+      vatAmount: parsedXml.vatAmount ?? null,
+      grossAmount: parsedXml.grossAmount ?? null,
+      upoDownloadUrl,
+      invoiceDownloadUrl,
+      status: 'downloaded',
+      syncedAt: now,
+    })
+    em.persist(record)
+  }
+
+  await em.flush()
+
+  return NextResponse.json({
+    id: record.id,
+    ksefReferenceNumber: record.ksefReferenceNumber,
+    invoiceNumber: record.invoiceNumber ?? null,
+    sellerNip: record.sellerNip ?? null,
+    sellerName: record.sellerName ?? null,
+    issueDate: record.issueDate ?? null,
+    currency: record.currency ?? null,
+    netAmount: record.netAmount ?? null,
+    vatAmount: record.vatAmount ?? null,
+    grossAmount: record.grossAmount ?? null,
+    rawXml: record.rawXml,
+    status: 'downloaded',
+    errorMessage: null,
+    syncedAt: record.syncedAt?.toISOString() ?? now.toISOString(),
+    createdAt: record.createdAt.toISOString(),
+    updatedAt: record.updatedAt.toISOString(),
+  })
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'KSeF Direct',
+  summary: 'Fetch received document by KSeF reference',
+  methods: {
+    POST: {
+      summary: 'Fetch and store a single received KSeF document',
+      description: 'Downloads the FA(2) XML for a given KSeF reference number and stores it locally. Synchronous — waits for the download to complete.',
+      requestBody: {
+        contentType: 'application/json',
+        schema: ReceivedDocumentFetchSchema,
+      },
+      responses: [
+        {
+          status: 200,
+          description: 'Document fetched and stored',
+          schema: receivedDocumentResponseSchema,
+        },
+      ],
+      errors: [
+        { status: 400, description: 'Invalid request', schema: z.object({ error: z.string() }) },
+        { status: 409, description: 'KSeF credentials not configured', schema: z.object({ error: z.string() }) },
+        { status: 502, description: 'KSeF API error', schema: z.object({ error: z.string() }) },
+      ],
+    },
+  },
+}

package/src/modules/integration_ksef_direct/api/post/integration-ksef-direct/received-documents/sync.ts

@@ -0,0 +1,86 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { createModuleQueue } from '@open-mercato/queue'
+import { ReceivedDocumentSyncSchema } from '../../../../data/validators'
+import type { SyncReceivedDocumentsPayload } from '../../../../workers/sync-received-documents'
+
+export const metadata = {
+  path: '/integration-ksef-direct/received-documents/sync',
+  POST: { requireAuth: true, requireFeatures: ['integration_ksef_direct.received_documents.sync'] },
+}
+
+export async function POST(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth?.tenantId || !auth.orgId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const body = await readJsonSafe(req, {})
+  const parsed = ReceivedDocumentSyncSchema.safeParse(body)
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: 'Invalid date range', fieldErrors: parsed.error.flatten().fieldErrors },
+      { status: 400 },
+    )
+  }
+
+  const container = await createRequestContainer()
+  const credentialsService = container.resolve('integrationCredentialsService') as any
+  const rawCreds = credentialsService
+    ? await credentialsService.resolve('integration_ksef_direct', {
+        tenantId: auth.tenantId,
+        organizationId: auth.orgId,
+      })
+    : null
+
+  const { KsefDirectCredentialsSchema } = await import('../../../../data/validators')
+  if (!KsefDirectCredentialsSchema.safeParse(rawCreds).success) {
+    return NextResponse.json(
+      { error: 'KSeF credentials not configured' },
+      { status: 409 },
+    )
+  }
+
+  const queue = createModuleQueue<SyncReceivedDocumentsPayload>('ksef_direct_receive')
+  const jobId = await queue.enqueue({
+    organizationId: auth.orgId,
+    tenantId: auth.tenantId,
+    dateFrom: parsed.data.dateFrom,
+    dateTo: parsed.data.dateTo,
+  })
+
+  return NextResponse.json({ jobId, message: 'Sync job queued' }, { status: 202 })
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'KSeF Direct',
+  summary: 'Sync received documents',
+  methods: {
+    POST: {
+      summary: 'Trigger date-range sync of received KSeF documents',
+      description: 'Enqueues a background worker that fetches all invoices received from KSeF for the given date range.',
+      requestBody: {
+        contentType: 'application/json',
+        schema: ReceivedDocumentSyncSchema,
+      },
+      responses: [
+        {
+          status: 202,
+          description: 'Sync job queued',
+          schema: z.object({
+            jobId: z.string(),
+            message: z.string(),
+          }),
+        },
+      ],
+      errors: [
+        { status: 400, description: 'Invalid date range', schema: z.object({ error: z.string() }) },
+        { status: 409, description: 'KSeF credentials not configured', schema: z.object({ error: z.string() }) },
+      ],
+    },
+  },
+}

package/src/modules/integration_ksef_direct/backend/integration-ksef-direct/documents/new/page.meta.ts

@@ -0,0 +1,4 @@
+export const metadata = {
+  navHidden: true,
+  requireFeatures: ['integration_ksef_direct.documents.create'],
+}