@dloizides/invoice-core 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 dloizides
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# @dloizides/invoice-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Invoice logic for local-first apps: gap-free numbering, VAT rules, JSON layouts, PDFs with selectable Greek text, yearly schedules, credit notes and a quarter CSV export. Holds no file access: every function takes an `InvoiceStorage`.
+
+```ts
+import { createMemoryStorage, issueInvoice } from '@dloizides/invoice-core';
+
+const storage = createMemoryStorage({ 'company.json': companyText, 'clients/acme.json': clientText });
+const { number, pdfPath } = await issueInvoice(storage, {
+  clientId: 'acme', period: '2030-09', date: '2030-10-08', amounts: ['1234.50'], draft: false,
+});
+```
+
+## 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.
+
+## Folder format
+
+```
+format.json                               {"version": 1}
+company.json                              name, addressLines, regNo, vatNumber, bank, iban, bic, logo?, layout?
+clients/<id>.json                         name, addressLines, taxLines, vatNumber, vatRule, paymentTermsDays, description, layout?
+rules/<id>.json                           optional; overrides or adds to BUILT_IN_RULES
+layouts/<name>.json                       optional; overrides or adds to BUILT_IN_LAYOUTS
+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
+```
+
+`migrateLegacyFolder` moves `<year>/<number>.json` + `.pdf` into `invoices/`, never overwriting. Until then `nextNumber` counts both places.
+
+## Layouts
+
+A layout is plain data (`InvoiceLayout`): margins, sizes, three colours, title alignment. `parseLayout` refuses unknown fields, so a layout cannot carry a script. An unknown name is refused and named.
+
+## Rendering
+
+`renderInvoicePdf` uses pdfmake 0.2.12 and its bundled Roboto, loaded on first use. Pass `render` in the options to replace it.
+
+## 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.

package/dist/index.d.mts

@@ -0,0 +1,399 @@
+/**
+ * The data folder as the core sees it. Paths are relative, with forward slashes.
+ * Browser and Node implementations live outside this package.
+ */
+interface InvoiceStorage {
+    /** Returns the file as text, or null if it does not exist. */
+    readText(path: string): Promise<string | null>;
+    /** Returns the file as bytes, or null if it does not exist. */
+    readBytes(path: string): Promise<Uint8Array | null>;
+    /** Returns the names of a folder's direct children; empty if it does not exist. */
+    list(dir: string): Promise<string[]>;
+    /** Creates a file and its parents; throws StorageExistsError if the file exists. */
+    writeNew(path: string, data: string | Uint8Array): Promise<void>;
+    /** Creates or overwrites a file; never used on an issued record. */
+    replace(path: string, data: string | Uint8Array): Promise<void>;
+    /** Deletes a file; does nothing if it does not exist. */
+    remove(path: string): Promise<void>;
+    /** Runs work while holding the named lock; other holders of that name wait. */
+    withLock<T>(name: string, work: () => Promise<T>): Promise<T>;
+}
+/** Thrown by writeNew when the file already exists. */
+declare class StorageExistsError extends Error {
+    constructor(path: string);
+}
+
+/** Whether an issued record is an invoice or a credit note. */
+declare const enum InvoiceKind {
+    Invoice = "invoice",
+    CreditNote = "credit-note"
+}
+
+/** One validation problem: a field path and what is wrong with it. */
+interface FieldError {
+    path: string;
+    message: string;
+}
+/** The issuing company, read from company.json in the data folder. */
+interface Company {
+    name: string;
+    addressLines: string[];
+    regNo: string;
+    vatNumber: string;
+    bank: string;
+    iban: string;
+    bic: string;
+    logo?: string;
+    template?: string;
+    layout?: string;
+}
+/** A client, read from clients/<id>.json in the data folder. */
+interface Client {
+    name: string;
+    addressLines: string[];
+    taxLines: string[];
+    vatNumber: string;
+    vatRule: string;
+    paymentTermsDays: number | null;
+    description: string;
+    template?: string;
+    layout?: string;
+}
+/** A VAT treatment, built in or read from a rule file. */
+interface VatRule {
+    id: string;
+    ratePercent: number;
+    labelEn: string;
+    labelEl: string;
+    rateTextEn: string;
+    rateTextEl: string;
+    noteEn: string;
+    noteEl: string;
+    source: string;
+    reviewedByAccountant?: boolean;
+}
+/** A line as entered: its own description and an amount such as 2952.50. */
+interface InvoiceLine {
+    description: string;
+    amount: string;
+}
+/** A line ready to print and total. */
+interface ResolvedLine {
+    description: string;
+    cents: number;
+}
+/** Totals in whole cents. */
+interface Totals {
+    netCents: number;
+    vatCents: number;
+    totalCents: number;
+}
+/** The per-invoice request. Lines win over amounts, which use the client description. */
+interface InvoiceRequest {
+    clientId: string;
+    period: string;
+    date: string;
+    amounts: string[];
+    lines?: InvoiceLine[];
+    template?: string;
+    layout?: string;
+    draft: boolean;
+}
+/** The three files an invoice is built from. */
+interface Parties {
+    company: Company;
+    client: Client;
+    rule: VatRule;
+}
+/** Which schedule month an issued record came from. */
+interface ScheduleRef {
+    id: string;
+    period: string;
+}
+/** The immutable record of an issued invoice or credit note. */
+interface InvoiceRecord extends Parties {
+    kind: InvoiceKind;
+    number: string;
+    request: InvoiceRequest;
+    lines: ResolvedLine[];
+    totals: Totals;
+    schedule?: ScheduleRef;
+    creditFor?: string;
+    reason?: string;
+}
+/** Where an issued record and its PDF were saved. */
+interface IssuedInvoice {
+    number: string;
+    pdfPath: string;
+    recordPath: string;
+}
+/** Thrown for any refusal; errors name each field. */
+declare class InvoiceError extends Error {
+    readonly errors: FieldError[];
+    constructor(errors: FieldError[]);
+}
+
+/** What a renderer receives. A null number means a draft. */
+interface RenderInput {
+    request: InvoiceRequest;
+    number: string | null;
+    parties: Parties;
+    lines?: ResolvedLine[];
+    kind?: InvoiceKind;
+    creditFor?: string;
+    reason?: string;
+}
+/** Everything a PDF prints, already formatted. */
+interface InvoiceView {
+    draft: boolean;
+    creditNote: boolean;
+    number: string;
+    date: string;
+    dueDate: string;
+    periodEn: string;
+    periodEl: string;
+    company: {
+        name: string;
+        addressLines: string[];
+        regNo: string;
+        vatNumber: string;
+        bank: string;
+        iban: string;
+        bic: string;
+    };
+    client: {
+        name: string;
+        addressLines: string[];
+        taxLines: string[];
+    };
+    rows: {
+        description: string;
+        amount: string;
+    }[];
+    net: string;
+    vat: string;
+    total: string;
+    vatLabel: string;
+    noteEn: string;
+    noteEl: string;
+    creditFor?: string;
+    reason?: string;
+}
+
+/** The lock every number claim holds, so two tabs never take one number. */
+declare const NUMBER_LOCK = "invoice-number";
+/** Renders PDF bytes; the default is renderInvoicePdf. */
+type PdfRender = (input: RenderInput) => Promise<Uint8Array>;
+/** Options for issuing; schedule marks which schedule month this came from. */
+interface IssueOptions {
+    render?: PdfRender;
+    schedule?: ScheduleRef;
+}
+/** Issues a final invoice: renders first, then claims the number, so a failed render uses none. */
+declare function issueInvoice(storage: InvoiceStorage, request: InvoiceRequest, options?: IssueOptions): Promise<IssuedInvoice>;
+/** Renders a draft PDF that takes no number. */
+declare function renderDraftPdf(storage: InvoiceStorage, request: InvoiceRequest, options?: IssueOptions): Promise<Uint8Array>;
+/** Reads an issued record; a record from the old layout's shape gets its kind, lines and totals. */
+declare function readInvoice(storage: InvoiceStorage, number: string): Promise<InvoiceRecord>;
+/** Lists a year's issued invoices and credit notes; folders with no record are skipped. */
+declare function listIssued(storage: InvoiceStorage, year: string): Promise<InvoiceRecord[]>;
+/** Recreates the missing PDF of an issued record; never replaces an existing PDF. */
+declare function reprintInvoice(storage: InvoiceStorage, number: string, options?: IssueOptions): Promise<{
+    number: string;
+    pdfPath: string;
+}>;
+
+/** What to credit. Without an amount the credit note covers all the invoice has left. */
+interface CreditNoteRequest {
+    invoiceNumber: string;
+    date: string;
+    reason: string;
+    amount?: string;
+}
+/** Issues a credit note that references its invoice and takes its own gap-free CN- number. */
+declare function issueCreditNote(storage: InvoiceStorage, input: CreditNoteRequest, options?: IssueOptions): Promise<IssuedInvoice>;
+
+/** The accountant's CSV of one quarter's invoices and credit notes, by date; credit notes are negative. */
+declare function exportQuarterCsv(storage: InvoiceStorage, year: string, quarter: number): Promise<string>;
+
+/** The folder of an issued invoice or credit note. */
+declare function invoiceDir(number: string): string;
+/** The path of an issued record. */
+declare function recordPath(number: string): string;
+/** The path of an issued PDF. */
+declare function pdfPath(number: string): string;
+/** Creates format.json in a new folder and refuses a folder newer than this code. */
+declare function ensureFormat(storage: InvoiceStorage): Promise<void>;
+/** What a migration moved, and the numbers left in place because the target exists. */
+interface MigrationResult {
+    moved: string[];
+    conflicts: string[];
+}
+/** Moves <year>/<number>.json + .pdf to invoices/<year>/<number>/. Never overwrites. */
+declare function migrateLegacyFolder(storage: InvoiceStorage): Promise<MigrationResult>;
+
+/** Where a layout places the document title. */
+declare const enum LayoutAlign {
+    Left = "left",
+    Right = "right"
+}
+
+/** The name a request uses when neither it, the client nor the company picks a layout. */
+declare const DEFAULT_LAYOUT = "classic";
+/** The look of a PDF: plain data only, so a layout cannot run anything. */
+interface InvoiceLayout {
+    name: string;
+    pageMargin: number;
+    bodySize: number;
+    titleSize: number;
+    logoWidth: number;
+    accent: string;
+    muted: string;
+    band: string;
+    titleAlign: LayoutAlign;
+}
+/** The layouts every folder can use; a file in layouts/ overrides them by name. */
+declare const BUILT_IN_LAYOUTS: {
+    readonly classic: {
+        readonly name: "classic";
+        readonly pageMargin: 40;
+        readonly bodySize: 9.5;
+        readonly titleSize: 22;
+        readonly logoWidth: 90;
+        readonly accent: "#1F3A5F";
+        readonly muted: "#666666";
+        readonly band: "#E4ECF5";
+        readonly titleAlign: LayoutAlign.Right;
+    };
+    readonly compact: {
+        readonly name: "compact";
+        readonly pageMargin: 28;
+        readonly bodySize: 8.5;
+        readonly titleSize: 16;
+        readonly logoWidth: 60;
+        readonly accent: "#2F4F4F";
+        readonly muted: "#5F5F5F";
+        readonly band: "#E8EFEE";
+        readonly titleAlign: LayoutAlign.Left;
+    };
+};
+/** Checks a parsed layout file; refuses unknown fields and anything but plain values. */
+declare function parseLayout(raw: unknown): InvoiceLayout;
+/** Finds a layout in the data folder, then the built-in set; an unknown name is refused and named. */
+declare function resolveLayout(storage: InvoiceStorage, name: string): Promise<InvoiceLayout>;
+/** The layout name in force: request, then client, then company, then the default. */
+declare function selectLayoutName(request: InvoiceRequest, parties: Parties): string;
+
+/** Fills {periodElAccusative} and {periodEn} in a client description. */
+declare function expandDescription(description: string, period: string): string;
+/** Turns a request into printable lines: its own lines, else amounts with the client description. */
+declare function resolveLines(request: InvoiceRequest, client: Client): ResolvedLine[];
+/** Sums lines in whole cents and adds VAT at the given rate. */
+declare function computeTotals(lines: ResolvedLine[], ratePercent: number): Totals;
+
+/** Creates an in-memory storage, for tests and previews. */
+declare function createMemoryStorage(initial?: Record<string, string | Uint8Array>): InvoiceStorage;
+
+/** Parses "2952" or "2952.50" into integer cents; returns null if malformed. */
+declare function toCents(amount: string): number | null;
+/** Formats cents in Greek style: 295200 becomes "2.952,00". */
+declare function formatCents(cents: number): string;
+/** Formats cents as a plain amount: -4000 becomes "-40.00". */
+declare function centsToAmount(cents: number): string;
+/** Computes VAT in whole cents, rounded half up. */
+declare function vatCents(netCents: number, ratePercent: number): number;
+
+/** Returns the next gap-free number for a year, such as 2030-002 or CN-2030-001. */
+declare function nextNumber(storage: InvoiceStorage, year: string, kind?: InvoiceKind): Promise<string>;
+/** Writes the record, refusing if that number was already issued. Issued records are never replaced. */
+declare function claimInvoice(storage: InvoiceStorage, record: InvoiceRecord): Promise<string>;
+
+/** 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>;
+
+/** The logo a PDF shows: an image data URL or SVG text. */
+type PdfLogo = {
+    image: string;
+} | {
+    svg: string;
+};
+
+/** Reads the company logo for a PDF; PNG, JPG or SVG, refusing anything else or a missing file. */
+declare function loadLogo(storage: InvoiceStorage, logo?: string): Promise<PdfLogo | undefined>;
+/** Renders an invoice or credit note to PDF bytes with selectable Greek text. Works in browsers and Node. */
+declare function renderInvoicePdf(storage: InvoiceStorage, input: RenderInput): Promise<Uint8Array>;
+
+/** Period texts for a YYYY-MM period. */
+declare function periodTexts(period: string): {
+    en: string;
+    el: string;
+    elAccusative: string;
+};
+/** Formats YYYY-MM-DD as DD/MM/YYYY. */
+declare function displayDate(iso: string): string;
+/** Adds days to a YYYY-MM-DD date. */
+declare function addDays(iso: string, days: number): string;
+
+/** The built-in VAT rules by id; a rule file in the data folder overrides them. Not tax advice. */
+declare const BUILT_IN_RULES: ReadonlyMap<string, VatRule>;
+
+/** One month of a schedule: a draft until number is set. */
+interface ScheduleMonth {
+    period: string;
+    lines: InvoiceLine[];
+    number: string | null;
+    issuedOn: string | null;
+}
+/** A client's yearly schedule, stored in schedules/<id>.json. */
+interface InvoiceSchedule {
+    id: string;
+    clientId: string;
+    year: string;
+    months: ScheduleMonth[];
+}
+/** What to prepare: a client and the amount each month starts with. */
+interface PrepareScheduleRequest {
+    clientId: string;
+    year: string;
+    monthlyAmount: string;
+}
+/** The clock and renderer for issuing due months. */
+interface IssueDueOptions {
+    today: string;
+    render?: PdfRender;
+}
+/** What issuing due months did; a failure stops the run and leaves the rest as drafts. */
+interface IssueDueResult {
+    issued: {
+        period: string;
+        number: string;
+    }[];
+    failed: {
+        period: string;
+        errors: FieldError[];
+    } | null;
+    remaining: string[];
+}
+/** Prepares 12 drafts with no numbers from a client and a monthly amount; a second call for that year is refused. */
+declare function prepareYearSchedule(storage: InvoiceStorage, request: PrepareScheduleRequest): Promise<InvoiceSchedule>;
+/** Reads a schedule by id. */
+declare function readSchedule(storage: InvoiceStorage, id: string): Promise<InvoiceSchedule>;
+/** Changes a draft month's lines; an issued month is refused and named. */
+declare function editScheduleMonth(storage: InvoiceStorage, id: string, period: string, lines: InvoiceLine[]): Promise<InvoiceSchedule>;
+/** Issues finished months in order, each with its own number, dated today; stops at the first failure. */
+declare function issueDueMonths(storage: InvoiceStorage, id: string, options: IssueDueOptions): Promise<IssueDueResult>;
+
+/** True for an empty value or a placeholder such as CY[____]. */
+declare function isBlank(value: unknown): boolean;
+/** True for a real calendar date written as YYYY-MM-DD. */
+declare function isRealDate(date: string): boolean;
+/** Checks each line's amount; a description may stay blank until final. */
+declare function validateLines(lines: InvoiceLine[]): FieldError[];
+/** Checks the request shape; these errors apply to drafts too. */
+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 };