@ksefgpt/shared-types

Shared TypeScript type definitions for KSeFGPT projects — invoices, corrections, common enums. Types only; no runtime code.

Layout

src/
├── common.ts        AuthMethod, InvoiceType, ExportJobStatus, BulkImportJobStatus, sort enums
├── invoice.ts       Invoice, InvoiceMetadata, InvoiceLineItem, FA(3) nested structures
├── correction.ts    CorrectionSource, LineItemPatch/Override, parsed-invoice types
└── index.ts         re-exports from all of the above

Usage

In a sibling Next.js / TS project (/Users/.../ksef-ai-web-app):

// package.json
{
  "dependencies": {
    "@ksefgpt/shared-types": "file:../ksef-shared-types-js"
  }
}

Then:

import type { Invoice, InvoiceMetadata } from "@ksefgpt/shared-types";
import type { CorrectionLineItemsRequest } from "@ksefgpt/shared-types/correction";
import type { AuthMethod } from "@ksefgpt/shared-types/common";

Since the package is type-only, import type is sufficient; nothing runs at runtime.

Conventions

• Field names mirror the API's wire format (mostly camelCase, some snake_case for legacy import endpoints).
• FA(3) Polish field names (p_13_x, p_14_x, przyczynaKorekty, etc.) stay in Polish — they map 1:1 to the KSeF XSD.
• Types here must remain portable — no React, RTK Query, Redux, or framework-specific symbols.

Releasing

Publishing runs via the Publish to npm GitHub Action.

Prerequisites (one-time)

• Repository secret NPM_TOKEN set to an npm Automation token with publish rights to the @ksefgpt scope (npm → Profile → Access Tokens → Generate New Token → "Automation").
• The npm organisation @ksefgpt exists and the publishing user is a member with Developer role or higher.

Cutting a release

Two equivalent paths:

A. Tag-driven (recommended)

1. Bump version in package.json locally.
2. Commit and tag: git commit -am "chore(release): v0.2.0" && git tag v0.2.0.
3. Push: git push --follow-tags.
4. The Action triggers on v* tag push, runs npm run type-check, then npm publish --access public --provenance.

B. Manual (workflow_dispatch)

1. GitHub → Actions → "Publish to npm" → Run workflow.
2. Optionally pass a version (e.g. 0.2.0) — the workflow runs npm version, commits, tags, pushes, then publishes.
3. Optionally pass tag (default latest) to publish under a dist-tag like next or beta.

Provenance

--provenance is currently disabled in the workflow. npm rejects provenance attestation for source repos with internal or private visibility — only public repos are accepted.

To turn provenance on later:

1. Make this repo's GitHub visibility public.
2. Restore id-token: write under permissions: in .github/workflows/publish.yml.
3. Add --provenance back to the npm publish step.

With provenance enabled, the npm registry records a signed attestation linking each artifact to the workflow run, repo, and commit SHA — visible on the package page under "Provenance".