@dloizides/invoice-core 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.2.0
+
+Open a picked folder (`openDataFolder`), payment status in a separate `status.json`, sync-conflict and duplicate-number detection that blocks issuing, and `StorageExistsError` recognised by name so another package can implement the storage.
+
 ## 0.1.0
 
 First release: storage interface, numbering, validation, VAT rules, JSON layouts, pdfmake rendering, yearly schedules, credit notes, quarter CSV export, legacy folder migration.

package/README.md

@@ -13,7 +13,7 @@ const { number, pdfPath } = await issueInvoice(storage, {
 
 ## Storage
 
-Implement `InvoiceStorage` (`src/storage.ts`) for your platform: `readText`, `readBytes`, `list`, `writeNew` (must refuse an existing file with `StorageExistsError`), `replace`, `remove`, `withLock`. Number claims run inside `withLock(NUMBER_LOCK, ...)`, so a browser implementation should back it with Web Locks.
+`@dloizides/folder-store` implements this in the browser. Otherwise implement `InvoiceStorage` (`src/storage.ts`) for your platform: `readText`, `readBytes`, `list`, `writeNew` (must refuse an existing file with an error named `StorageExistsError`), `replace`, `remove`, `withLock`. Number claims run inside `withLock(NUMBER_LOCK, ...)`, so a browser implementation should back it with Web Locks.
 
 ## Folder format
 
@@ -26,6 +26,7 @@ layouts/<name>.json                       optional; overrides or adds to BUILT_I
 schedules/<clientId>-<year>.json          12 months, each a draft until issued
 invoices/<year>/<number>/invoice.json     immutable record
 invoices/<year>/<number>/<number>.pdf     the PDF; never replaced
+invoices/<year>/<number>/status.json      payment date; the only file here that may change
 ```
 
 `migrateLegacyFolder` moves `<year>/<number>.json` + `.pdf` into `invoices/`, never overwriting. Until then `nextNumber` counts both places.
@@ -41,3 +42,15 @@ A layout is plain data (`InvoiceLayout`): margins, sizes, three colours, title a
 ## Numbers
 
 Invoices number `2030-001`, credit notes `CN-2030-001`, each gap-free per year of their date. `issueDueMonths` dates each invoice on the day it issues; have your accountant confirm that suits your jurisdiction. Built-in VAT rules are not tax advice.
+
+## Opening a folder
+
+`openDataFolder` returns `New` (empty; format written), `Existing`, `Legacy` (ours but no format; call `migrateLegacyFolder`) or `Foreign` (unrelated files; nothing written, ask the user).
+
+## Conflicts
+
+`findFolderConflicts(storage, year)` reports sync-conflict copies, one number written twice and unreadable records, in both layouts. Issuing refuses while the year holds any and names each path; the user removes the copy. Operating system files are ignored.
+
+## Payment status
+
+`markPaid`, `markUnpaid` and `readPaymentStatus` use `status.json` only. `paymentStateOf(record, status, today)` gives paid, unpaid or overdue; overdue starts the day after the due date, and no payment terms means never overdue.

package/dist/index.d.mts

@@ -1,3 +1,9 @@
+declare const enum FolderConflictKind {
+    SyncCopy = "sync copy",
+    DuplicateNumber = "duplicate number",
+    UnreadableRecord = "unreadable record"
+}
+
 /**
  * The data folder as the core sees it. Paths are relative, with forward slashes.
  * Browser and Node implementations live outside this package.
@@ -22,6 +28,17 @@ interface InvoiceStorage {
 declare class StorageExistsError extends Error {
     constructor(path: string);
 }
+/** Whether an error means the file exists; matched by name, so another package's class of this name counts. */
+declare function isStorageExistsError(error: unknown): boolean;
+
+interface FolderConflict {
+    kind: FolderConflictKind;
+    path: string;
+}
+/** Finds sync-conflict copies, duplicate numbers and unreadable records in one year, in both layouts. */
+declare function findFolderConflicts(storage: InvoiceStorage, year: string): Promise<FolderConflict[]>;
+/** Refuses to continue if the year holds a conflict, naming each path. */
+declare function assertNoConflicts(storage: InvoiceStorage, year: string): Promise<void>;
 
 /** Whether an issued record is an invoice or a credit note. */
 declare const enum InvoiceKind {
@@ -232,6 +249,13 @@ interface MigrationResult {
 /** Moves <year>/<number>.json + .pdf to invoices/<year>/<number>/. Never overwrites. */
 declare function migrateLegacyFolder(storage: InvoiceStorage): Promise<MigrationResult>;
 
+declare const enum FolderOpenState {
+    New = "new",
+    Existing = "existing",
+    Legacy = "legacy",
+    Foreign = "foreign"
+}
+
 /** Where a layout places the document title. */
 declare const enum LayoutAlign {
     Left = "left",
@@ -308,11 +332,32 @@ declare function nextNumber(storage: InvoiceStorage, year: string, kind?: Invoic
 /** Writes the record, refusing if that number was already issued. Issued records are never replaced. */
 declare function claimInvoice(storage: InvoiceStorage, record: InvoiceRecord): Promise<string>;
 
+/** Opens a picked folder: an empty one gets the format, anything else unrecognised is left untouched. */
+declare function openDataFolder(storage: InvoiceStorage): Promise<FolderOpenState>;
+
 /** Reads the request's company, client and VAT rule, refusing if any is missing. */
 declare function loadParties(storage: InvoiceStorage, clientId: string): Promise<Parties>;
 /** Checks a request and returns its parties; final mode also refuses blank required fields. */
 declare function checkRequest(storage: InvoiceStorage, request: InvoiceRequest): Promise<Parties>;
 
+declare const enum PaymentState {
+    Paid = "paid",
+    Unpaid = "unpaid",
+    Overdue = "overdue"
+}
+
+interface PaymentStatus {
+    paidOn: string | null;
+}
+/** Reads an invoice's payment status from its status.json; no file means unpaid. */
+declare function readPaymentStatus(storage: InvoiceStorage, number: string): Promise<PaymentStatus>;
+/** Records a payment date in status.json; the issued record is never touched. */
+declare function markPaid(storage: InvoiceStorage, number: string, paidOn: string): Promise<void>;
+/** Removes a recorded payment; the issued record is never touched. */
+declare function markUnpaid(storage: InvoiceStorage, number: string): Promise<void>;
+/** Says whether an invoice is paid, unpaid or overdue today; overdue starts the day after the due date. */
+declare function paymentStateOf(record: InvoiceRecord, status: PaymentStatus, today: string): PaymentState;
+
 /** The logo a PDF shows: an image data URL or SVG text. */
 type PdfLogo = {
     image: string;
@@ -396,4 +441,4 @@ declare function validateRequest(req: InvoiceRequest): FieldError[];
 /** Lists required fields still blank; a final invoice is refused if any are. */
 declare function missingForFinal(company: Company, client: Client, lines?: InvoiceLine[]): FieldError[];
 
-export { BUILT_IN_LAYOUTS, BUILT_IN_RULES, type Client, type Company, type CreditNoteRequest, DEFAULT_LAYOUT, type FieldError, InvoiceError, InvoiceKind, type InvoiceLayout, type InvoiceLine, type InvoiceRecord, type InvoiceRequest, type InvoiceSchedule, type InvoiceStorage, type InvoiceView, type IssueDueOptions, type IssueDueResult, type IssueOptions, type IssuedInvoice, LayoutAlign, type MigrationResult, NUMBER_LOCK, type Parties, type PdfRender, type PrepareScheduleRequest, type RenderInput, type ResolvedLine, type ScheduleMonth, type ScheduleRef, StorageExistsError, type Totals, type VatRule, addDays, centsToAmount, checkRequest, claimInvoice, computeTotals, createMemoryStorage, displayDate, editScheduleMonth, ensureFormat, expandDescription, exportQuarterCsv, formatCents, invoiceDir, isBlank, isRealDate, issueCreditNote, issueDueMonths, issueInvoice, listIssued, loadLogo, loadParties, migrateLegacyFolder, missingForFinal, nextNumber, parseLayout, pdfPath, periodTexts, prepareYearSchedule, readInvoice, readSchedule, recordPath, renderDraftPdf, renderInvoicePdf, reprintInvoice, resolveLayout, resolveLines, selectLayoutName, toCents, validateLines, validateRequest, vatCents };
+export { BUILT_IN_LAYOUTS, BUILT_IN_RULES, type Client, type Company, type CreditNoteRequest, DEFAULT_LAYOUT, type FieldError, type FolderConflict, FolderConflictKind, FolderOpenState, InvoiceError, InvoiceKind, type InvoiceLayout, type InvoiceLine, type InvoiceRecord, type InvoiceRequest, type InvoiceSchedule, type InvoiceStorage, type InvoiceView, type IssueDueOptions, type IssueDueResult, type IssueOptions, type IssuedInvoice, LayoutAlign, type MigrationResult, NUMBER_LOCK, type Parties, PaymentState, type PaymentStatus, type PdfRender, type PrepareScheduleRequest, type RenderInput, type ResolvedLine, type ScheduleMonth, type ScheduleRef, StorageExistsError, type Totals, type VatRule, addDays, assertNoConflicts, centsToAmount, checkRequest, claimInvoice, computeTotals, createMemoryStorage, displayDate, editScheduleMonth, ensureFormat, expandDescription, exportQuarterCsv, findFolderConflicts, formatCents, invoiceDir, isBlank, isRealDate, isStorageExistsError, issueCreditNote, issueDueMonths, issueInvoice, listIssued, loadLogo, loadParties, markPaid, markUnpaid, migrateLegacyFolder, missingForFinal, nextNumber, openDataFolder, parseLayout, paymentStateOf, pdfPath, periodTexts, prepareYearSchedule, readInvoice, readPaymentStatus, readSchedule, recordPath, renderDraftPdf, renderInvoicePdf, reprintInvoice, resolveLayout, resolveLines, selectLayoutName, toCents, validateLines, validateRequest, vatCents };

package/dist/index.d.ts

@@ -1,3 +1,9 @@
+declare const enum FolderConflictKind {
+    SyncCopy = "sync copy",
+    DuplicateNumber = "duplicate number",
+    UnreadableRecord = "unreadable record"
+}
+
 /**
  * The data folder as the core sees it. Paths are relative, with forward slashes.
  * Browser and Node implementations live outside this package.
@@ -22,6 +28,17 @@ interface InvoiceStorage {
 declare class StorageExistsError extends Error {
     constructor(path: string);
 }
+/** Whether an error means the file exists; matched by name, so another package's class of this name counts. */
+declare function isStorageExistsError(error: unknown): boolean;
+
+interface FolderConflict {
+    kind: FolderConflictKind;
+    path: string;
+}
+/** Finds sync-conflict copies, duplicate numbers and unreadable records in one year, in both layouts. */
+declare function findFolderConflicts(storage: InvoiceStorage, year: string): Promise<FolderConflict[]>;
+/** Refuses to continue if the year holds a conflict, naming each path. */
+declare function assertNoConflicts(storage: InvoiceStorage, year: string): Promise<void>;
 
 /** Whether an issued record is an invoice or a credit note. */
 declare const enum InvoiceKind {
@@ -232,6 +249,13 @@ interface MigrationResult {
 /** Moves <year>/<number>.json + .pdf to invoices/<year>/<number>/. Never overwrites. */
 declare function migrateLegacyFolder(storage: InvoiceStorage): Promise<MigrationResult>;
 
+declare const enum FolderOpenState {
+    New = "new",
+    Existing = "existing",
+    Legacy = "legacy",
+    Foreign = "foreign"
+}
+
 /** Where a layout places the document title. */
 declare const enum LayoutAlign {
     Left = "left",
@@ -308,11 +332,32 @@ declare function nextNumber(storage: InvoiceStorage, year: string, kind?: Invoic
 /** Writes the record, refusing if that number was already issued. Issued records are never replaced. */
 declare function claimInvoice(storage: InvoiceStorage, record: InvoiceRecord): Promise<string>;
 
+/** Opens a picked folder: an empty one gets the format, anything else unrecognised is left untouched. */
+declare function openDataFolder(storage: InvoiceStorage): Promise<FolderOpenState>;
+
 /** Reads the request's company, client and VAT rule, refusing if any is missing. */
 declare function loadParties(storage: InvoiceStorage, clientId: string): Promise<Parties>;
 /** Checks a request and returns its parties; final mode also refuses blank required fields. */
 declare function checkRequest(storage: InvoiceStorage, request: InvoiceRequest): Promise<Parties>;
 
+declare const enum PaymentState {
+    Paid = "paid",
+    Unpaid = "unpaid",
+    Overdue = "overdue"
+}
+
+interface PaymentStatus {
+    paidOn: string | null;
+}
+/** Reads an invoice's payment status from its status.json; no file means unpaid. */
+declare function readPaymentStatus(storage: InvoiceStorage, number: string): Promise<PaymentStatus>;
+/** Records a payment date in status.json; the issued record is never touched. */
+declare function markPaid(storage: InvoiceStorage, number: string, paidOn: string): Promise<void>;
+/** Removes a recorded payment; the issued record is never touched. */
+declare function markUnpaid(storage: InvoiceStorage, number: string): Promise<void>;
+/** Says whether an invoice is paid, unpaid or overdue today; overdue starts the day after the due date. */
+declare function paymentStateOf(record: InvoiceRecord, status: PaymentStatus, today: string): PaymentState;
+
 /** The logo a PDF shows: an image data URL or SVG text. */
 type PdfLogo = {
     image: string;
@@ -396,4 +441,4 @@ declare function validateRequest(req: InvoiceRequest): FieldError[];
 /** Lists required fields still blank; a final invoice is refused if any are. */
 declare function missingForFinal(company: Company, client: Client, lines?: InvoiceLine[]): FieldError[];
 
-export { BUILT_IN_LAYOUTS, BUILT_IN_RULES, type Client, type Company, type CreditNoteRequest, DEFAULT_LAYOUT, type FieldError, InvoiceError, InvoiceKind, type InvoiceLayout, type InvoiceLine, type InvoiceRecord, type InvoiceRequest, type InvoiceSchedule, type InvoiceStorage, type InvoiceView, type IssueDueOptions, type IssueDueResult, type IssueOptions, type IssuedInvoice, LayoutAlign, type MigrationResult, NUMBER_LOCK, type Parties, type PdfRender, type PrepareScheduleRequest, type RenderInput, type ResolvedLine, type ScheduleMonth, type ScheduleRef, StorageExistsError, type Totals, type VatRule, addDays, centsToAmount, checkRequest, claimInvoice, computeTotals, createMemoryStorage, displayDate, editScheduleMonth, ensureFormat, expandDescription, exportQuarterCsv, formatCents, invoiceDir, isBlank, isRealDate, issueCreditNote, issueDueMonths, issueInvoice, listIssued, loadLogo, loadParties, migrateLegacyFolder, missingForFinal, nextNumber, parseLayout, pdfPath, periodTexts, prepareYearSchedule, readInvoice, readSchedule, recordPath, renderDraftPdf, renderInvoicePdf, reprintInvoice, resolveLayout, resolveLines, selectLayoutName, toCents, validateLines, validateRequest, vatCents };
+export { BUILT_IN_LAYOUTS, BUILT_IN_RULES, type Client, type Company, type CreditNoteRequest, DEFAULT_LAYOUT, type FieldError, type FolderConflict, FolderConflictKind, FolderOpenState, InvoiceError, InvoiceKind, type InvoiceLayout, type InvoiceLine, type InvoiceRecord, type InvoiceRequest, type InvoiceSchedule, type InvoiceStorage, type InvoiceView, type IssueDueOptions, type IssueDueResult, type IssueOptions, type IssuedInvoice, LayoutAlign, type MigrationResult, NUMBER_LOCK, type Parties, PaymentState, type PaymentStatus, type PdfRender, type PrepareScheduleRequest, type RenderInput, type ResolvedLine, type ScheduleMonth, type ScheduleRef, StorageExistsError, type Totals, type VatRule, addDays, assertNoConflicts, centsToAmount, checkRequest, claimInvoice, computeTotals, createMemoryStorage, displayDate, editScheduleMonth, ensureFormat, expandDescription, exportQuarterCsv, findFolderConflicts, formatCents, invoiceDir, isBlank, isRealDate, isStorageExistsError, issueCreditNote, issueDueMonths, issueInvoice, listIssued, loadLogo, loadParties, markPaid, markUnpaid, migrateLegacyFolder, missingForFinal, nextNumber, openDataFolder, parseLayout, paymentStateOf, pdfPath, periodTexts, prepareYearSchedule, readInvoice, readPaymentStatus, readSchedule, recordPath, renderDraftPdf, renderInvoicePdf, reprintInvoice, resolveLayout, resolveLines, selectLayoutName, toCents, validateLines, validateRequest, vatCents };

package/dist/index.js

@@ -7,6 +7,9 @@ var StorageExistsError = class extends Error {
     this.name = "StorageExistsError";
   }
 };
+function isStorageExistsError(error) {
+  return typeof error === "object" && error !== null && error.name === "StorageExistsError";
+}
 
 // src/types.ts
 var InvoiceError = class extends Error {
@@ -23,6 +26,11 @@ var FORMAT_VERSION = 1;
 var NUMBER_YEAR = /(\d{4})-\d+$/;
 var LEGACY_YEAR = /^\d{4}$/;
 var LEGACY_FILE = /^(\d{4}-\d+)\.(json|pdf)$/;
+var OS_FILES = /* @__PURE__ */ new Set(["desktop.ini", "thumbs.db", ".ds_store"]);
+var NUMBER_SHAPE = /^(CN-)?\d{4}-\d+$/;
+function isOsFile(name) {
+  return OS_FILES.has(name.toLowerCase());
+}
 function toJson(value2) {
   return JSON.stringify(value2, null, 2);
 }
@@ -58,7 +66,7 @@ async function ensureFormat(storage) {
   const text = await storage.readText(FORMAT_PATH);
   if (text === null) {
     await storage.writeNew(FORMAT_PATH, toJson({ version: FORMAT_VERSION })).catch((error) => {
-      if (!(error instanceof StorageExistsError)) {
+      if (!isStorageExistsError(error)) {
         throw error;
       }
     });
@@ -101,6 +109,85 @@ async function migrateLegacyFolder(storage) {
   return result;
 }
 
+// src/FolderConflictKind.ts
+var FolderConflictKind = /* @__PURE__ */ ((FolderConflictKind2) => {
+  FolderConflictKind2["SyncCopy"] = "sync copy";
+  FolderConflictKind2["DuplicateNumber"] = "duplicate number";
+  FolderConflictKind2["UnreadableRecord"] = "unreadable record";
+  return FolderConflictKind2;
+})(FolderConflictKind || {});
+
+// src/conflicts.ts
+var RECORD_FILE = "invoice.json";
+var STATUS_FILE = "status.json";
+var LEGACY_FILE2 = /^(\d{4}-\d+)\.(json|pdf)$/;
+function seriesKey(number) {
+  const separator = number.lastIndexOf("-");
+  return `${number.slice(0, separator)}-${Number(number.slice(separator + 1))}`;
+}
+async function recordConflict(storage, dir, number) {
+  const path = `${dir}/${RECORD_FILE}`;
+  const text = await storage.readText(path);
+  if (text === null) {
+    return [];
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return [{ kind: "unreadable record" /* UnreadableRecord */, path }];
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return [{ kind: "unreadable record" /* UnreadableRecord */, path }];
+  }
+  return parsed.number === number ? [] : [{ kind: "duplicate number" /* DuplicateNumber */, path }];
+}
+async function numberFolderConflicts(storage, dir, number) {
+  const allowed = /* @__PURE__ */ new Set([RECORD_FILE, STATUS_FILE, `${number}.pdf`]);
+  const copies = (await storage.list(dir)).filter((name) => !allowed.has(name) && !isOsFile(name)).map((name) => ({ kind: "sync copy" /* SyncCopy */, path: `${dir}/${name}` }));
+  return [...copies, ...await recordConflict(storage, dir, number)];
+}
+async function currentLayoutConflicts(storage, year) {
+  const conflicts = [];
+  const numbers = /* @__PURE__ */ new Set();
+  const keys = /* @__PURE__ */ new Set();
+  const yearDir = `invoices/${year}`;
+  for (const name of (await storage.list(yearDir)).filter((entry) => !isOsFile(entry))) {
+    const path = `${yearDir}/${name}`;
+    if (!NUMBER_SHAPE.test(name) || numberYear(name) !== year) {
+      conflicts.push({ kind: "sync copy" /* SyncCopy */, path });
+    } else if (keys.has(seriesKey(name))) {
+      conflicts.push({ kind: "duplicate number" /* DuplicateNumber */, path });
+    } else {
+      keys.add(seriesKey(name));
+      numbers.add(name);
+      conflicts.push(...await numberFolderConflicts(storage, path, name));
+    }
+  }
+  return { conflicts, numbers };
+}
+async function legacyLayoutConflicts(storage, year, numbers) {
+  const names = (await storage.list(year)).filter((name) => !isOsFile(name));
+  return names.flatMap((name) => {
+    const number = LEGACY_FILE2.exec(name)?.[1];
+    const path = `${year}/${name}`;
+    if (number === void 0 || numberYear(number) !== year) {
+      return [{ kind: "sync copy" /* SyncCopy */, path }];
+    }
+    return numbers.has(number) ? [{ kind: "duplicate number" /* DuplicateNumber */, path }] : [];
+  });
+}
+async function findFolderConflicts(storage, year) {
+  const { conflicts, numbers } = await currentLayoutConflicts(storage, year);
+  return [...conflicts, ...await legacyLayoutConflicts(storage, year, numbers)];
+}
+async function assertNoConflicts(storage, year) {
+  const conflicts = await findFolderConflicts(storage, year);
+  if (conflicts.length > 0) {
+    throw new InvoiceError(conflicts.map(({ kind, path }) => ({ path: "folder", message: `${kind}: ${path}` })));
+  }
+}
+
 // src/InvoiceKind.ts
 var InvoiceKind = /* @__PURE__ */ ((InvoiceKind2) => {
   InvoiceKind2["Invoice"] = "invoice";
@@ -270,7 +357,7 @@ async function claimInvoice(storage, record) {
   try {
     await storage.writeNew(path, toJson(record));
   } catch (error) {
-    const message = error instanceof StorageExistsError ? `${record.number} is already issued` : `could not save ${record.number}: ${error.message}`;
+    const message = isStorageExistsError(error) ? `${record.number} is already issued` : `could not save ${record.number}: ${error.message}`;
     throw new InvoiceError([{ path: "number", message }]);
   }
   return path;
@@ -656,7 +743,6 @@ async function renderInvoicePdf(storage, input) {
 }
 
 // src/issue.ts
-var NUMBER_SHAPE = /^(CN-)?\d{4}-\d+$/;
 var NUMBER_LOCK = "invoice-number";
 function rendererFor(storage, options) {
   return options.render ?? ((input) => renderInvoicePdf(storage, input));
@@ -678,6 +764,7 @@ async function issueInvoice(storage, request, options = {}) {
   await ensureFormat(storage);
   const render = rendererFor(storage, options);
   return storage.withLock(NUMBER_LOCK, async () => {
+    await assertNoConflicts(storage, final.date.slice(0, 4));
     const number = await nextNumber(storage, final.date.slice(0, 4));
     const lines2 = resolveLines(final, parties.client);
     const pdf = await render({ request: final, number, parties, lines: lines2 });
@@ -764,6 +851,7 @@ async function issueCreditNote(storage, input, options = {}) {
   checkTarget(invoice, input);
   const render = rendererFor(storage, options);
   return storage.withLock(NUMBER_LOCK, async () => {
+    await assertNoConflicts(storage, input.date.slice(0, 4));
     const remaining = invoice.totals.netCents - await creditedSoFar(storage, invoice, input.date);
     const cents = creditCents(input, remaining);
     const number = await nextNumber(storage, input.date.slice(0, 4), "credit-note" /* CreditNote */);
@@ -828,6 +916,15 @@ async function exportQuarterCsv(storage, year, quarter) {
   return `${BOM}${[HEADER.join(","), ...records.map(toRow)].join(NEWLINE)}${NEWLINE}`;
 }
 
+// src/FolderOpenState.ts
+var FolderOpenState = /* @__PURE__ */ ((FolderOpenState2) => {
+  FolderOpenState2["New"] = "new";
+  FolderOpenState2["Existing"] = "existing";
+  FolderOpenState2["Legacy"] = "legacy";
+  FolderOpenState2["Foreign"] = "foreign";
+  return FolderOpenState2;
+})(FolderOpenState || {});
+
 // src/memoryStorage.ts
 function toBytes2(data) {
   return typeof data === "string" ? new TextEncoder().encode(data) : data;
@@ -871,6 +968,69 @@ function createMemoryStorage(initial = {}) {
   };
 }
 
+// src/openFolder.ts
+var DATA_ENTRIES = /* @__PURE__ */ new Set(["company.json", "clients", "invoices", "rules", "layouts", "schedules"]);
+var LEGACY_YEAR2 = /^\d{4}$/;
+async function openDataFolder(storage) {
+  const names = (await storage.list("")).filter((name) => !isOsFile(name));
+  if (names.includes(FORMAT_PATH)) {
+    await ensureFormat(storage);
+    return "existing" /* Existing */;
+  }
+  if (names.length === 0) {
+    await ensureFormat(storage);
+    return "new" /* New */;
+  }
+  return names.some((name) => DATA_ENTRIES.has(name) || LEGACY_YEAR2.test(name)) ? "legacy" /* Legacy */ : "foreign" /* Foreign */;
+}
+
+// src/PaymentState.ts
+var PaymentState = /* @__PURE__ */ ((PaymentState2) => {
+  PaymentState2["Paid"] = "paid";
+  PaymentState2["Unpaid"] = "unpaid";
+  PaymentState2["Overdue"] = "overdue";
+  return PaymentState2;
+})(PaymentState || {});
+
+// src/paymentStatus.ts
+var STATUS_LOCK = "invoice-status";
+function statusPath(number) {
+  return `${invoiceDir(number)}/status.json`;
+}
+async function readPaymentStatus(storage, number) {
+  const path = statusPath(number);
+  if (await storage.readText(path) === null) {
+    return { paidOn: null };
+  }
+  const { paidOn } = await readJsonFile(storage, path, "status");
+  return { paidOn: typeof paidOn === "string" ? paidOn : null };
+}
+async function markPaid(storage, number, paidOn) {
+  if (!isRealDate(paidOn)) {
+    throw new InvoiceError([{ path: "paidOn", message: "must be a real date as YYYY-MM-DD" }]);
+  }
+  const record = await readInvoice(storage, number);
+  if (record.kind !== "invoice" /* Invoice */) {
+    throw new InvoiceError([{ path: "number", message: `${number} is a credit note; only an invoice can be paid` }]);
+  }
+  if (paidOn < record.request.date) {
+    throw new InvoiceError([{ path: "paidOn", message: `must not be before the invoice date ${record.request.date}` }]);
+  }
+  const payment2 = { paidOn };
+  await storage.withLock(STATUS_LOCK, () => storage.replace(statusPath(number), toJson(payment2)));
+}
+async function markUnpaid(storage, number) {
+  await storage.withLock(STATUS_LOCK, () => storage.remove(statusPath(number)));
+}
+function paymentStateOf(record, status, today) {
+  if (status.paidOn !== null) {
+    return "paid" /* Paid */;
+  }
+  const terms = record.client.paymentTermsDays;
+  const overdue = typeof terms === "number" && today > addDays(record.request.date, terms);
+  return overdue ? "overdue" /* Overdue */ : "unpaid" /* Unpaid */;
+}
+
 // src/schedule.ts
 var MONTHS_IN_YEAR = 12;
 var YEAR3 = /^\d{4}$/;
@@ -901,7 +1061,7 @@ async function prepareYearSchedule(storage, request) {
   try {
     await storage.writeNew(schedulePath(schedule.id), toJson(schedule));
   } catch (error) {
-    if (error instanceof StorageExistsError) {
+    if (isStorageExistsError(error)) {
       throw new InvoiceError([{ path: "schedule", message: `${schedule.id} is already prepared` }]);
     }
     throw error;
@@ -982,12 +1142,16 @@ async function issueDueMonths(storage, id, options) {
 exports.BUILT_IN_LAYOUTS = BUILT_IN_LAYOUTS;
 exports.BUILT_IN_RULES = BUILT_IN_RULES;
 exports.DEFAULT_LAYOUT = DEFAULT_LAYOUT;
+exports.FolderConflictKind = FolderConflictKind;
+exports.FolderOpenState = FolderOpenState;
 exports.InvoiceError = InvoiceError;
 exports.InvoiceKind = InvoiceKind;
 exports.LayoutAlign = LayoutAlign;
 exports.NUMBER_LOCK = NUMBER_LOCK;
+exports.PaymentState = PaymentState;
 exports.StorageExistsError = StorageExistsError;
 exports.addDays = addDays;
+exports.assertNoConflicts = assertNoConflicts;
 exports.centsToAmount = centsToAmount;
 exports.checkRequest = checkRequest;
 exports.claimInvoice = claimInvoice;
@@ -998,24 +1162,31 @@ exports.editScheduleMonth = editScheduleMonth;
 exports.ensureFormat = ensureFormat;
 exports.expandDescription = expandDescription;
 exports.exportQuarterCsv = exportQuarterCsv;
+exports.findFolderConflicts = findFolderConflicts;
 exports.formatCents = formatCents;
 exports.invoiceDir = invoiceDir;
 exports.isBlank = isBlank;
 exports.isRealDate = isRealDate;
+exports.isStorageExistsError = isStorageExistsError;
 exports.issueCreditNote = issueCreditNote;
 exports.issueDueMonths = issueDueMonths;
 exports.issueInvoice = issueInvoice;
 exports.listIssued = listIssued;
 exports.loadLogo = loadLogo;
 exports.loadParties = loadParties;
+exports.markPaid = markPaid;
+exports.markUnpaid = markUnpaid;
 exports.migrateLegacyFolder = migrateLegacyFolder;
 exports.missingForFinal = missingForFinal;
 exports.nextNumber = nextNumber;
+exports.openDataFolder = openDataFolder;
 exports.parseLayout = parseLayout;
+exports.paymentStateOf = paymentStateOf;
 exports.pdfPath = pdfPath;
 exports.periodTexts = periodTexts;
 exports.prepareYearSchedule = prepareYearSchedule;
 exports.readInvoice = readInvoice;
+exports.readPaymentStatus = readPaymentStatus;
 exports.readSchedule = readSchedule;
 exports.recordPath = recordPath;
 exports.renderDraftPdf = renderDraftPdf;