@substrat-run/connector-fortnox 0.5.8 → 0.7.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { addDecimal, connectionActivity, connectionId as connectionIdSchema, instant, money, mulDecimal, scopeId as scopeIdSchema, tenantId as tenantIdSchema, } from '@substrat-run/contracts';
-import { deadlineFetch, settleConnectionUse } from '@substrat-run/kernel';
+import { addDecimal, CONNECTOR_ATTACHMENT_BUFFERED_MAX_BYTES, connectionActivity, connectionId as connectionIdSchema, entityRef, instant, money, mulDecimal, scopeId as scopeIdSchema, tenantId as tenantIdSchema, } from '@substrat-run/contracts';
+import { deadlineFetch, settleConnectionUse, ulid } from '@substrat-run/kernel';
 import { FortnoxApi, FortnoxApiError, FORTNOX_API_BASE, FORTNOX_OAUTH_BASE, fortnoxSecret, } from './api.js';
 import { financialYearFor, summarizeLedger } from './aggregate.js';
 import { parseSie4 } from './sie4.js';
@@ -60,6 +60,8 @@ export const FORTNOX_CONNECTION_GRANTS = [];
 /** The connector-state key prefix every binding lives under — what the sweep enumerates. */
 const BINDING_PREFIX = 'fortnox:binding:';
 const bindingKey = (scope) => `${BINDING_PREFIX}${scope}`;
+const FILES_LANDED_PREFIX = 'fortnox:files-landed:';
+const filesLandedKey = (scope, givenNumber) => `${FILES_LANDED_PREFIX}${scope}:${givenNumber}`;
 /**
  * One page of parsed bookkeeping, as it crosses into a scope.
  *
@@ -104,6 +106,33 @@ export const fortnoxLedgerPage = z.object({
 });
 /** How many balance rows ride one `invoke`. */
 const PAGE_SIZE = 500;
+/**
+ * One financial year's whole SIE4 file, as a `form: 'sie'` binding lands it, in one `invoke`.
+ *
+ * The file itself, because it already is the neutral statement of the books, and everything a
+ * reader could want is in it: the opening and closing balances the sums skip, every voucher, every
+ * account name. A vertical that takes uploaded SIE files has a reader for it already, and this way
+ * a file from Fortnox and a file from a person go through the same door.
+ *
+ * Decoded from PC8, so `sie` is text. Parsed on the way out like {@link fortnoxLedgerPage}.
+ */
+export const fortnoxSieFile = z.object({
+    /** The content hash: unchanged books present the same id, so a landing can answer it once. */
+    syncId: z.string().min(1),
+    connectionId: z.string().min(1),
+    company: z.object({
+        name: z.string(),
+        organizationNumber: z.string(),
+    }),
+    financialYear: z.object({
+        id: z.number(),
+        from: z.string(),
+        to: z.string(),
+    }),
+    sie: z.string().min(1),
+});
+/** How long a `form: 'sie'` binding leaves an older year before reading it again. */
+const OLDER_YEAR_REFRESH_MS = 24 * 3_600_000;
 /**
  * The supplier invoices an invoice binding lands (#2422) — one page per pass that found changes.
  *
@@ -132,17 +161,83 @@ export const fortnoxSupplierInvoicePage = z.object({
         dueDate: z.string(),
         /** In the invoice's own currency. */
         total: money,
+        /** What is left to pay, in the invoice's currency. Absent when Fortnox states none. */
+        balance: money.optional(),
+        /** In the invoice's currency. Absent when Fortnox states none. */
+        vat: money.optional(),
+        ocr: z.string().nullable().optional(),
         booked: z.boolean(),
         cancelled: z.boolean(),
+        /** A credit note. */
+        credit: z.boolean().optional(),
+        /** A payment of the invoice is on its way. */
+        paymentPending: z.boolean().optional(),
+        /** The old single comment, while an invoice still has one. New comments are in `commentLog`. */
+        comments: z.string().nullable().optional(),
+        /** Fortnox's comment log, oldest first as Fortnox lists it. Its web UI writes only here. */
+        commentLog: z
+            .array(z.object({ comment: z.string(), createdAt: z.string().nullable(), userName: z.string().nullable() }))
+            .optional(),
+        /** The voucher the invoice was booked on. `year` is Fortnox's number for the financial year. */
+        voucher: z.object({ series: z.string().nullable(), number: z.number().int(), year: z.number().int().nullable() }).nullable().optional(),
+        project: z.string().nullable().optional(),
+        costCentre: z.string().nullable().optional(),
         /** The invoice's accounting rows: debit-positive, in SEK, as the ledger page states them. */
         rows: z.array(z.object({
             account: z.string(),
+            /** The account's name, as Fortnox writes it on the row. */
+            accountDescription: z.string().nullable().optional(),
             costCentre: z.string().nullable(),
+            project: z.string().nullable().optional(),
+            transactionInformation: z.string().nullable().optional(),
             amount: money,
         })),
     }))
         .min(1),
 });
+/**
+ * What a landing operation may answer. `files` names the invoices whose file the vertical wants
+ * and the entity each one lands on, which must be a declared attachment target the connection
+ * can write. An answer without it, or that does not parse, asks for no file.
+ */
+export const fortnoxSupplierInvoiceLandingAnswer = z
+    .object({ files: z.array(z.object({ givenNumber: z.string().min(1), entity: entityRef })).optional() })
+    .passthrough();
+/**
+ * What a binding's `writeback.read` answers when the sweep asks what to write for one company.
+ *
+ * The sweep asks rather than listens. Asking is what makes a lost pass harmless: what the vertical
+ * still answers is what is still to do, and nothing about a decision has to ride an event or sit
+ * in a ledger of its own. It reads `{ connectionId, company }`, and a vertical holding several
+ * companies answers for that company alone, because `GivenNumber` repeats between companies.
+ *
+ * The answer is instructions, not vocabulary: what a decision means is the vertical's, and all the
+ * connector knows is what to do in Fortnox.
+ */
+export const fortnoxInvoiceWriteback = z.object({
+    /** Invoices to keep from being paid until they are decided: `DisablePaymentFile`, set once. */
+    hold: z.array(z.object({ givenNumber: z.string().min(1) })).default([]),
+    decisions: z
+        .array(z.object({
+        /** Handed back in the receipt. A retry of the same decision carries the same key. */
+        key: z.string().min(1),
+        givenNumber: z.string().min(1),
+        /** Book the invoice, unless it already is. */
+        book: z.boolean(),
+        /** Clear a hold this binding set. A block anyone else set is never touched. */
+        release: z.boolean(),
+        /** One entry for Fortnox's comment log, added once. It is written last. */
+        comment: z.string().min(1).nullable(),
+    }))
+        .default([]),
+});
+/** What a binding's `writeback.record` receives, once for each decision that is settled. */
+export const fortnoxInvoiceWritebackReceipt = z.object({
+    key: z.string().min(1),
+    status: z.enum(['done', 'failed']),
+    /** Fortnox's reason, for a `failed` one. */
+    error: z.string().nullable(),
+});
 /**
  * Invoice details read per connection per pass. The client paces every read to Fortnox's limit,
  * so this bounds how long one pass runs (about 40 seconds at the limit) rather than the rate. A
@@ -155,8 +250,39 @@ const INVOICE_DETAILS_PER_PASS = 200;
  * it runs. Past this, what was read lands and the next pass resumes after it.
  */
 const INVOICE_PASS_DEADLINE_MS = 90_000;
-/** How far back a binding's first pass reads. */
-const INVOICE_FIRST_LOOKBACK_MS = 90 * 86_400_000;
+/** What one held invoice can cost a pass: its read and the write. */
+const INVOICE_HOLD_CALLS = 2;
+/** What one decision can cost a pass: its read, booking, the block, the log's read and its write. */
+const INVOICE_DECISION_CALLS = 5;
+/** Tries at a write that keeps failing for no stated reason, before the vertical is told. */
+const INVOICE_WRITE_ATTEMPTS = 8;
+/** Passes a queued file may fail before it is skipped, so a file that never reads cannot hold the budget. */
+const INVOICE_FILE_ATTEMPTS = 8;
+const invoiceHoldKey = (givenNumber) => `fortnox:invoice-hold:${givenNumber}`;
+const invoiceWriteKey = (key) => `fortnox:invoice-write:${key}`;
+/** How far back a binding's first pass reads when its declaration does not say. */
+export const INVOICE_FIRST_LOOKBACK_DAYS = 90;
+/** What one queued invoice costs from a pass's budget at the least: its connections, one file. */
+const INVOICE_FILE_READS = 2;
+/** The largest file a pass will hold. A larger one is skipped by name, never truncated. */
+const INVOICE_FILE_MAX_BYTES = CONNECTOR_ATTACHMENT_BUFFERED_MAX_BYTES;
+/** A file's type by its name, for an archive read that does not say or says only "bytes". */
+const FILE_TYPES = {
+    pdf: 'application/pdf',
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    tif: 'image/tiff',
+    tiff: 'image/tiff',
+};
+const fileType = (name, stated) => {
+    const type = stated?.split(';')[0]?.trim().toLowerCase();
+    if (type && type !== 'application/octet-stream')
+        return type;
+    const ext = name.split('.').pop()?.toLowerCase() ?? '';
+    return Object.hasOwn(FILE_TYPES, ext) ? FILE_TYPES[ext] : 'application/octet-stream';
+};
 /**
  * Read back from each cursor. Fortnox's filter is to the minute in Swedish local time, and the
  * landing upserts, so re-reading a few minutes costs a resend and missing them costs an invoice.
@@ -208,6 +334,18 @@ const apiOptions = (options) => ({
 export async function bindFortnoxScope(host, input) {
     const tenant = tenantIdSchema.parse(input.tenantId);
     const scope = scopeIdSchema.parse(input.scopeId);
+    if (input.form !== undefined && (input.kind ?? 'ledger') !== 'ledger') {
+        throw new Error(`form applies to a ledger binding, not to '${String(input.kind)}'`);
+    }
+    if (input.years !== undefined && input.form !== 'sie') {
+        throw new Error("years applies to a binding with form 'sie': the summary form lands the current year");
+    }
+    if (input.years !== undefined && input.years !== 'all' && !(Number.isInteger(input.years) && input.years >= 0)) {
+        throw new Error(`years is 'all' or a whole number of years, not ${String(input.years)}`);
+    }
+    if ((input.firstPass !== undefined || input.writeback !== undefined) && input.kind !== 'supplier-invoice') {
+        throw new Error(`firstPass and writeback apply to a supplier-invoice binding, not to '${input.kind ?? 'ledger'}'`);
+    }
     const current = (await listFortnoxBindings(host, input.connectionId)).find((b) => b.scopeId === input.scopeId);
     if (current && (current.kind ?? 'ledger') !== (input.kind ?? 'ledger')) {
         throw new Error(`one Fortnox landing kind per scope; use a separate scope for the other kind (${current.kind ?? 'ledger'} to ${input.kind ?? 'ledger'} on scope ${input.scopeId})`);
@@ -229,7 +367,27 @@ export async function bindFortnoxScope(host, input) {
         operation: input.operation,
         permission: input.permission,
         ...(input.kind ? { kind: input.kind } : {}),
+        ...(input.form !== undefined ? { form: input.form } : {}),
+        ...(input.years !== undefined ? { years: input.years } : {}),
+        ...(input.firstPass !== undefined ? { firstPass: input.firstPass } : {}),
+        ...(input.writeback !== undefined ? { writeback: input.writeback } : {}),
         ...(input.externalAccountRef ? { externalAccountRef: input.externalAccountRef } : {}),
+        // A re-bind that changes nothing keeps the years already landed: an operator re-PUT or a scope
+        // asking again must not re-download a whole history. Any change starts over, a newly recorded
+        // company included, since the years held may be another company's.
+        ...(current?.yearSync && input.form === 'sie' && current.form === 'sie' && current.years === input.years &&
+            current.operation === input.operation && (current.externalAccountRef ?? null) === (input.externalAccountRef ?? null)
+            ? { yearSync: current.yearSync }
+            : {}),
+        // A re-bind starts the cursor over but keeps the files already asked for: an invoice outside a
+        // narrowed first pass would otherwise never be asked about again.
+        ...(current?.files?.length ? { files: current.files } : {}),
+        // A re-bind that changes what is written back keeps the invoice cursor and its queued files, so
+        // turning writeback on does not re-land the company's history. A different operation or first
+        // pass reads from the start again, since what was landed was landed for the old one.
+        ...(current?.invoiceSync && current.operation === input.operation && current.firstPass === input.firstPass
+            ? { invoiceSync: current.invoiceSync }
+            : {}),
         boundAt: new Date(input.now?.() ?? Date.now()).toISOString(),
     };
     await host.admin.putConnectorState(input.connectionId, bindingKey(input.scopeId), binding);
@@ -377,12 +535,131 @@ export async function syncFortnoxScope(host, connectionId, binding, options) {
     };
 }
 /**
- * Sync ONE invoice binding (#2422): list the supplier invoices changed since its cursor, read
- * each one's rows, and land them in one page through the binding's operation as the connection.
+ * Sync ONE `form: 'sie'` binding: land the current year's SIE4 file if it changed, and bring one
+ * older year up to date.
+ *
+ * One older year per pass, because a year is one large download and a pass runs on a timer. A
+ * company's history therefore lands newest year first, a year a quarter of an hour, and after that
+ * each older year is read once a day: a closed year rarely moves, but nothing stops it moving. A
+ * year whose file has not changed lands nothing.
+ *
+ * Each year is written to the binding right after it lands, so a failure on one costs only that one,
+ * and the years that did land are answered beside the ones that failed.
+ */
+export async function syncFortnoxSieFiles(host, connectionId, binding, options) {
+    const conn = await openFortnoxConnection(host.admin, options.fetch, binding.tenantId, binding.vertical, options.timeoutMs ?? 30_000, { externalAccountRef: binding.externalAccountRef ?? null, expected: connectionId });
+    const api = new FortnoxApi(conn, apiOptions(options));
+    const nowMs = options.now?.() ?? Date.now();
+    const year = new Date(nowMs).toISOString().slice(0, 4);
+    const years = await api.financialYears();
+    const current = financialYearFor(years, options.period ?? { from: `${year}-01-01`, to: `${year}-12-31` });
+    if (!current)
+        return { synced: [], failed: [] };
+    const held = (y) => binding.yearSync?.[String(y.Id)];
+    // The last time a year was tried, landed or failed: a failed year waits its turn like a read one.
+    const tried = (y) => {
+        const read = held(y)?.syncedAt;
+        const failed = binding.yearFailedAt?.[String(y.Id)];
+        return read === undefined || (failed !== undefined && failed > read) ? failed : read;
+    };
+    const kept = binding.years === 'all' ? Infinity : (binding.years ?? 0);
+    // Never tried comes first, newest first (the sort is stable), because the recent years are the
+    // ones a reader wants. After that, the one tried longest ago.
+    const due = years
+        .filter((y) => y.FromDate < current.FromDate)
+        .sort((a, b) => (a.FromDate < b.FromDate ? 1 : -1))
+        .slice(0, kept)
+        .filter((y) => {
+        const last = tried(y);
+        return last === undefined || nowMs - Date.parse(last) >= OLDER_YEAR_REFRESH_MS;
+    })
+        .sort((a, b) => (tried(a) ?? '').localeCompare(tried(b) ?? ''));
+    const key = bindingKey(binding.scopeId);
+    const synced = [];
+    const failed = [];
+    for (const financialYear of [current, ...due.slice(0, 1)]) {
+        try {
+            const sie = await api.sieFile(financialYear.Id);
+            const contentHash = await sha256Hex(`sie\n${financialYear.Id}\n${sie}`);
+            const changed = held(financialYear)?.contentHash !== contentHash;
+            if (changed) {
+                // The file names its company (#FNAMN, #ORGNR), as the summary form reads it.
+                const ledger = parseSie4(sie);
+                // The connection acting as itself (#97), gated on the grant the binding was seated with.
+                const scope = await host.getConnectorScope(connectionId, scopeIdSchema.parse(binding.scopeId));
+                await scope.invoke(binding.operation, fortnoxSieFile.parse({
+                    syncId: contentHash,
+                    connectionId,
+                    company: { name: ledger.company, organizationNumber: ledger.organizationNumber },
+                    financialYear: { id: financialYear.Id, from: financialYear.FromDate, to: financialYear.ToDate },
+                    sie,
+                }));
+            }
+            // A year is a long download, so the binding read at the start of the pass may be stale by now:
+            // the cursor goes onto the binding as it stands, and one unbound or re-bound meanwhile is left
+            // as the person left it rather than brought back from this pass's copy.
+            const now = (await host.admin.getConnectorState(connectionId, key));
+            if (!now || typeof now !== 'object' || now.boundAt !== binding.boundAt)
+                break;
+            const syncedAt = new Date(nowMs).toISOString();
+            const { [String(financialYear.Id)]: _landed, ...stillFailed } = now.yearFailedAt ?? {};
+            await host.admin.putConnectorState(connectionId, key, {
+                ...now,
+                yearSync: { ...now.yearSync, [String(financialYear.Id)]: { syncedAt, contentHash } },
+                yearFailedAt: Object.keys(stillFailed).length > 0 ? stillFailed : undefined,
+                ...(financialYear === current ? { lastSync: { financialYearId: current.Id, syncedAt, contentHash, balances: 0 } } : {}),
+            });
+            synced.push({
+                scopeId: binding.scopeId,
+                changed,
+                syncId: contentHash,
+                financialYearId: financialYear.Id,
+                balances: 0,
+                pages: changed ? 1 : 0,
+                outOfRange: 0,
+            });
+        }
+        catch (error) {
+            failed.push({ financialYearId: financialYear.Id, error });
+            // The current year is tried every pass anyway; an older one is put back in the queue.
+            if (financialYear !== current)
+                await markYearFailed(host, connectionId, key, binding, financialYear.Id, nowMs);
+        }
+    }
+    return { synced, failed };
+}
+/**
+ * Record that an older year failed, onto the binding as it stands (see the cursor write above). The
+ * year's error is already answered, so a failure to record it only means the year is tried again
+ * next pass, as it was before this was recorded.
+ */
+async function markYearFailed(host, connectionId, key, binding, financialYearId, nowMs) {
+    try {
+        const now = (await host.admin.getConnectorState(connectionId, key));
+        if (!now || typeof now !== 'object' || now.boundAt !== binding.boundAt)
+            return;
+        await host.admin.putConnectorState(connectionId, key, {
+            ...now,
+            yearFailedAt: { ...now.yearFailedAt, [String(financialYearId)]: new Date(nowMs).toISOString() },
+        });
+    }
+    catch {
+        // Answered above: the year's own error is in `failed`.
+    }
+}
+/**
+ * Sync ONE invoice binding (#2422): read the files earlier passes left, list the supplier invoices
+ * changed since its cursor, read each one's rows, land them in one page through the binding's
+ * operation as the connection, read the files the landing asked for, then write back what the
+ * vertical says is waiting.
  *
- * Read-only toward Fortnox. Reads at most `budget.details` invoices, oldest number first, and
- * spends from the budget so bindings sharing a pass share Fortnox's rate limit. The cursor is
- * written only after the landing succeeded, so a refused page is read again next pass.
+ * Read-only toward Fortnox unless the binding declares `writeback`. Reads at most
+ * `budget.details` times for invoices and files, oldest number first, and spends from the budget so
+ * bindings sharing a pass share Fortnox's rate limit. The cursor is written only after the landing
+ * succeeded, so a refused page is read again next pass.
+ *
+ * Files come after the cursor, because a file that cannot be read says nothing about the invoice:
+ * the invoices keep landing, and the file stays queued and fails the scope's row by its number.
  */
 export async function syncFortnoxSupplierInvoices(host, connectionId, binding, options) {
     if (binding.kind !== 'supplier-invoice') {
@@ -391,16 +668,64 @@ export async function syncFortnoxSupplierInvoices(host, connectionId, binding, o
     const conn = await openFortnoxConnection(host.admin, options.fetch, binding.tenantId, binding.vertical, options.timeoutMs ?? 30_000, { externalAccountRef: binding.externalAccountRef ?? null, expected: connectionId });
     const api = new FortnoxApi(conn, apiOptions(options));
     const nowMs = options.now?.() ?? Date.now();
+    const expired = () => (options.now?.() ?? Date.now()) - nowMs >= INVOICE_PASS_DEADLINE_MS;
     const cursor = binding.invoiceSync;
-    const since = cursor ? Date.parse(cursor.since) : nowMs - INVOICE_FIRST_LOOKBACK_MS;
+    const budget = options.budget ?? { details: INVOICE_DETAILS_PER_PASS };
+    const scopeRef = scopeIdSchema.parse(binding.scopeId);
+    let companyRead;
+    const company = () => (companyRead ??= api.companyInformation());
+    const files = new InvoiceFiles(host, connectionId, binding.scopeId, scopeRef, api, budget, expired, binding.files);
+    const withFiles = (base) => {
+        const { files: _held, ...rest } = base;
+        return { ...rest, ...files.held() };
+    };
+    const saveFiles = async (base) => {
+        if (!files.moved)
+            return;
+        await host.admin.putConnectorState(connectionId, bindingKey(binding.scopeId), withFiles(base));
+        files.moved = false;
+    };
+    // The queue goes first, so it never outgrows one pass's budget, and it is saved at once, so a
+    // landing that throws below does not cost what was read. Its failures wait for the end.
+    await files.drain();
+    await saveFiles(binding);
+    // A pass's parts are independent: a landing that throws says nothing about a decision waiting to be
+    // written, and an idle pass is when most decisions are. The first failure is thrown at the end.
+    const landing = await landChangedInvoices(host, connectionId, binding, { api, company, files, budget, expired, nowMs, withFiles, saveFiles })
+        .catch((err) => ({ landed: 0, more: true, failure: asError(err) }));
+    const writes = binding.writeback
+        ? await writeBackInvoices(host, connectionId, binding, binding.writeback, { api, company, budget, expired, nowMs })
+            .catch((err) => ({ held: 0, written: 0, more: true, failure: asError(err) }))
+        : { held: 0, written: 0, more: false, failure: null };
+    const failure = landing.failure ?? files.failed ?? writes.failure;
+    if (failure)
+        throw failure;
+    return {
+        scopeId: binding.scopeId,
+        landed: landing.landed,
+        files: files.landed,
+        ...(files.skipped.length > 0 ? { skipped: files.skipped } : {}),
+        held: writes.held,
+        written: writes.written,
+        pending: landing.more || writes.more || files.queued > 0,
+    };
+}
+const asError = (err) => (err instanceof Error ? err : new Error(String(err)));
+/** Land what changed since the cursor, then read the files the landing asked for. */
+async function landChangedInvoices(host, connectionId, binding, pass) {
+    const { api, company: companyOf, files, budget, expired, nowMs, withFiles, saveFiles } = pass;
+    if (budget.details <= 0 || expired())
+        return { landed: 0, more: true, failure: null };
+    const cursor = binding.invoiceSync;
+    const since = cursor ? (cursor.since === null ? null : Date.parse(cursor.since)) : firstPassSince(binding, nowMs);
     const through = cursor?.pending ? Number(cursor.pending.through) : -Infinity;
-    const changed = [...new Set(await api.supplierInvoicesModifiedSince(lastModifiedFilter(since - INVOICE_OVERLAP_MS)))]
+    const filter = since === null ? null : lastModifiedFilter(since - INVOICE_OVERLAP_MS);
+    const changed = [...new Set(await api.supplierInvoicesModifiedSince(filter))]
         .filter((n) => Number(n) > through)
         .sort((a, b) => Number(a) - Number(b));
-    const budget = options.budget ?? { details: INVOICE_DETAILS_PER_PASS };
     const batch = changed.slice(0, budget.details);
     if (batch.length === 0)
-        return { scopeId: binding.scopeId, landed: 0, pending: changed.length > 0 };
+        return { landed: 0, more: changed.length > 0, failure: null };
     budget.details -= batch.length;
     // Read in number order, stopping at the first read that fails. What was read before it still
     // lands and the cursor moves past it, so a failure costs the pass the rest of its batch, never
@@ -425,13 +750,13 @@ export async function syncFortnoxSupplierInvoices(host, connectionId, binding, o
         }
         handled += 1;
         // Checked after a read, so every pass makes progress however slow the list was.
-        if ((options.now?.() ?? Date.now()) - nowMs >= INVOICE_PASS_DEADLINE_MS)
+        if (expired())
             break;
     }
     if (handled === 0)
-        throw failure;
+        return { landed: 0, more: true, failure };
     if (invoices.length > 0) {
-        const company = await api.companyInformation();
+        const company = await companyOf();
         const payload = fortnoxSupplierInvoicePage.parse({
             connectionId,
             company: { name: company.CompanyName, organizationNumber: company.OrganizationNumber },
@@ -439,23 +764,296 @@ export async function syncFortnoxSupplierInvoices(host, connectionId, binding, o
         });
         // The connection acting as itself (#97), gated on the grant the binding was seated with.
         const scope = await host.getConnectorScope(connectionId, scopeIdSchema.parse(binding.scopeId));
-        await scope.invoke(binding.operation, payload);
+        files.ask(await scope.invoke(binding.operation, payload));
     }
     const more = changed.length > handled;
     const startedAt = cursor?.pending?.startedAt ?? new Date(nowMs).toISOString();
-    const synced = {
+    const synced = withFiles({
         ...binding,
         invoiceSync: {
-            since: more ? new Date(since).toISOString() : startedAt,
+            since: more ? (since === null ? null : new Date(since).toISOString()) : startedAt,
             syncedAt: new Date(nowMs).toISOString(),
             landed: invoices.length,
             ...(more ? { pending: { startedAt, through: batch[handled - 1] } } : {}),
         },
-    };
+    });
     await host.admin.putConnectorState(connectionId, bindingKey(binding.scopeId), synced);
-    if (failure)
-        throw failure;
-    return { scopeId: binding.scopeId, landed: invoices.length, pending: more };
+    files.moved = false;
+    await files.drain();
+    await saveFiles(synced);
+    return { landed: invoices.length, more, failure };
+}
+/** A refusal in Fortnox's own words: the request was read and not carried out. */
+const statedRefusal = (err) => err instanceof FortnoxApiError && err.status >= 400 && err.status < 500 && err.status !== 429;
+/**
+ * Write what the vertical says is waiting: hold what is undecided, then settle the decisions.
+ *
+ * A decision's steps run in the order that fails safe. The block is cleared only after booking went
+ * through, so an invoice that could not be booked stays unpaid, and the comment goes last because
+ * the log is append-only. Every step reads first, so a pass cut off part-way repeats nothing.
+ *
+ * Only `hold` errors and transient failures are retried here. A refusal in Fortnox's own words is
+ * the vertical's at once, because the next pass would get the same answer and a person has to act.
+ */
+async function writeBackInvoices(host, connectionId, binding, operations, pass) {
+    const { api, budget, expired, nowMs } = pass;
+    // A pass with no budget left for one write asks nothing of Fortnox, not even who the company is.
+    if (budget.details < INVOICE_HOLD_CALLS || expired())
+        return { held: 0, written: 0, more: true, failure: null };
+    const scope = await host.getConnectorScope(connectionId, scopeIdSchema.parse(binding.scopeId));
+    const company = await pass.company();
+    const waiting = fortnoxInvoiceWriteback.parse(await scope.invoke(operations.read, {
+        connectionId,
+        company: { name: company.CompanyName, organizationNumber: company.OrganizationNumber },
+    }));
+    const at = new Date(nowMs).toISOString();
+    const out = { held: 0, written: 0, more: false, failure: null };
+    for (const { givenNumber } of waiting.hold) {
+        const key = invoiceHoldKey(givenNumber);
+        // A released hold does not count: an invoice can come back to the queue, and then it is held again.
+        const known = (await host.admin.getConnectorState(connectionId, key));
+        const live = known && !known.cleared ? known : null;
+        // Only a block this connector saw set is left alone. Someone else's is looked at again, because
+        // lifting it would leave the undecided invoice payable, and so is one Fortnox never confirmed.
+        if (live?.ours && !live.unconfirmed)
+            continue;
+        if (budget.details < INVOICE_HOLD_CALLS || expired()) {
+            out.more = true;
+            break;
+        }
+        budget.details -= INVOICE_HOLD_CALLS;
+        let asked = false;
+        try {
+            if ((await api.supplierInvoice(givenNumber)).DisablePaymentFile) {
+                // Blocked already: ours when our unconfirmed write went through, someone else's otherwise.
+                if (!live || live.unconfirmed) {
+                    await host.admin.putConnectorState(connectionId, key, { ours: !!live?.ours, at: live?.at ?? at });
+                }
+                continue;
+            }
+            // Remembered before the write: a pass that dies between them must not leave a block nobody
+            // knows is ours, which no approval would ever clear and which keeps a good invoice unpaid.
+            await host.admin.putConnectorState(connectionId, key, { ours: true, at, unconfirmed: true });
+            asked = true;
+            await api.setSupplierInvoicePaymentBlock(givenNumber, true);
+            await host.admin.putConnectorState(connectionId, key, { ours: true, at });
+            out.held += 1;
+        }
+        catch (err) {
+            // Only a stated refusal says the block was not set. Any other failure may have set it, so the
+            // note stays unconfirmed and the next pass reads the invoice to find out.
+            if (asked && statedRefusal(err))
+                await host.admin.putConnectorState(connectionId, key, known ?? null);
+            out.failure ??= new Error(`hold of supplier invoice ${givenNumber}: ${asError(err).message}`);
+        }
+    }
+    for (const decision of waiting.decisions) {
+        if (budget.details < INVOICE_DECISION_CALLS || expired()) {
+            out.more = true;
+            break;
+        }
+        budget.details -= INVOICE_DECISION_CALLS;
+        const tries = invoiceWriteKey(decision.key);
+        try {
+            await settleInvoiceDecision(host, connectionId, api, decision, at);
+            await scope.invoke(operations.record, fortnoxInvoiceWritebackReceipt.parse({ key: decision.key, status: 'done', error: null }));
+            await host.admin.putConnectorState(connectionId, tries, null);
+            out.written += 1;
+        }
+        catch (err) {
+            const error = asError(err);
+            const attempts = ((await host.admin.getConnectorState(connectionId, tries))?.attempts ?? 0) + 1;
+            out.failure ??= new Error(`write-back of supplier invoice ${decision.givenNumber}: ${error.message}`);
+            if (statedRefusal(err) || attempts >= INVOICE_WRITE_ATTEMPTS) {
+                try {
+                    await scope.invoke(operations.record, fortnoxInvoiceWritebackReceipt.parse({ key: decision.key, status: 'failed', error: error.message }));
+                    await host.admin.putConnectorState(connectionId, tries, null);
+                    continue;
+                }
+                catch {
+                    // The receipt did not land, so the vertical still lists the decision: the next pass tries
+                    // again, and this pass goes on to the rest. The first failure is already the one reported.
+                }
+            }
+            await host.admin.putConnectorState(connectionId, tries, { attempts, lastError: error.message });
+        }
+    }
+    return out;
+}
+/** Bring Fortnox to what one decision says. Safe to repeat: every step looks before it writes. */
+async function settleInvoiceDecision(host, connectionId, api, decision, at) {
+    const { givenNumber, book, release, comment } = decision;
+    const invoice = await api.supplierInvoice(givenNumber);
+    if (book && !invoice.Booked)
+        await api.bookSupplierInvoice(givenNumber);
+    if (release) {
+        const key = invoiceHoldKey(givenNumber);
+        const hold = (await host.admin.getConnectorState(connectionId, key));
+        if (hold?.ours && !hold.cleared) {
+            if (invoice.DisablePaymentFile)
+                await api.setSupplierInvoicePaymentBlock(givenNumber, false);
+            await host.admin.putConnectorState(connectionId, key, { ...hold, cleared: at });
+        }
+    }
+    if (comment !== null && !(await api.supplierInvoiceComments(givenNumber)).includes(comment)) {
+        await api.addSupplierInvoiceComment(givenNumber, comment);
+    }
+}
+/** Where an invoice binding's first pass starts: a number of days back, or `null` for everything. */
+const firstPassSince = (binding, nowMs) => binding.firstPass === 'all' ? null : nowMs - (binding.firstPass ?? INVOICE_FIRST_LOOKBACK_DAYS) * 86_400_000;
+const triedKey = (entry) => JSON.stringify([entry.givenNumber, entry.entity.entityType, entry.entity.entityId]);
+/**
+ * The invoice files one pass reads: the queue the binding carries, plus what the landing asks for.
+ *
+ * Each queued invoice costs its connections plus one read per file. A failure names the invoice and
+ * moves it to the back, so one file that cannot be read does not stop the others. A refusal stops
+ * them all: it is the company's consent, and every other file would answer the same.
+ */
+class InvoiceFiles {
+    host;
+    connectionId;
+    scopeId;
+    scopeRef;
+    api;
+    budget;
+    expired;
+    queue;
+    attachments;
+    failure = null;
+    /** The company's consent refused a read, so the rest of the pass asks nothing more. */
+    refused = false;
+    /**
+     * What failed this pass, by invoice and entity, so the drain after the landing does not read it
+     * again. A landing that names another entity for the invoice is a new request, and is read.
+     */
+    tried = new Set();
+    /** Files landed so far this pass. */
+    landed = 0;
+    skipped = [];
+    /** True once the queue differs from what the binding holds. */
+    moved = false;
+    constructor(host, connectionId, scopeId, scopeRef, api, budget, expired, held = []) {
+        this.host = host;
+        this.connectionId = connectionId;
+        this.scopeId = scopeId;
+        this.scopeRef = scopeRef;
+        this.api = api;
+        this.budget = budget;
+        this.expired = expired;
+        this.queue = [...held];
+    }
+    get queued() {
+        return this.queue.length;
+    }
+    /** The binding's `files` field: absent when nothing is queued. */
+    held() {
+        return this.queue.length > 0 ? { files: this.queue } : {};
+    }
+    /** Queue what a landing asked for. Re-asking for a queued invoice takes its newer entity. */
+    ask(answer) {
+        const asked = fortnoxSupplierInvoiceLandingAnswer.safeParse(answer);
+        if (!asked.success)
+            return;
+        for (const { givenNumber, entity } of asked.data.files ?? []) {
+            const entry = { givenNumber, entity };
+            const at = this.queue.findIndex((e) => e.givenNumber === givenNumber);
+            if (at >= 0)
+                this.queue[at] = { ...this.queue[at], entity };
+            else
+                this.queue.push(entry);
+            this.moved = true;
+        }
+    }
+    /** Read what the budget and the deadline allow. */
+    async drain() {
+        const failed = [];
+        while (!this.refused && this.budget.details >= INVOICE_FILE_READS && !this.expired()) {
+            const at = this.queue.findIndex((e) => !this.tried.has(triedKey(e)));
+            if (at < 0)
+                break;
+            const [entry] = this.queue.splice(at, 1);
+            this.moved = true;
+            try {
+                if (!(await this.read(entry))) {
+                    // The budget or the deadline ran out between its files: it stays first, and what it
+                    // landed is recorded, so the next pass reads only the rest.
+                    this.queue.unshift(entry);
+                    break;
+                }
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                if (err instanceof FortnoxApiError && err.refused) {
+                    this.queue.unshift(entry);
+                    this.refused = true;
+                    this.failure = new Error(`invoice files: Fortnox refused the read (${message}). The company's consent must cover ` +
+                        `the connectfile and archive scopes; connect the company again.`);
+                    break;
+                }
+                this.tried.add(triedKey(entry));
+                entry.attempts = (entry.attempts ?? 0) + 1;
+                // The last try is reported as a skip, so the pass that drops the file says which and why.
+                if (entry.attempts >= INVOICE_FILE_ATTEMPTS) {
+                    this.skipped.push({ givenNumber: entry.givenNumber, reason: `its file failed ${entry.attempts} passes: ${message}` });
+                }
+                else {
+                    failed.push(entry);
+                    this.failure ??= new Error(`file of supplier invoice ${entry.givenNumber}: ${message}`);
+                }
+            }
+        }
+        this.queue.push(...failed);
+    }
+    /** Land an invoice's files not yet landed on its entity. False when the pass ran out first. */
+    async read(entry) {
+        this.budget.details -= 1;
+        const connected = await this.api.supplierInvoiceFiles(entry.givenNumber);
+        const key = filesLandedKey(this.scopeId, entry.givenNumber);
+        const held = (await this.host.admin.getConnectorState(this.connectionId, key));
+        const sameEntity = held?.entity.entityType === entry.entity.entityType && held.entity.entityId === entry.entity.entityId;
+        let landed = sameEntity ? held.fileIds : [];
+        for (const file of connected) {
+            if (landed.includes(file.FileId))
+                continue;
+            if (this.budget.details < 1 || this.expired())
+                return false;
+            this.budget.details -= 1;
+            await this.land(entry, file);
+            landed = [...landed, file.FileId];
+            await this.host.admin.putConnectorState(this.connectionId, key, { entity: entry.entity, fileIds: landed });
+        }
+        return true;
+    }
+    async land(entry, file) {
+        const name = file.Name || `supplier-invoice-${entry.givenNumber}`;
+        let read;
+        try {
+            read = await this.api.archiveFile(file.FileId, INVOICE_FILE_MAX_BYTES);
+        }
+        catch (err) {
+            if (!(err instanceof FortnoxApiError && err.status === 404))
+                throw err;
+            this.skipped.push({ givenNumber: entry.givenNumber, reason: `${name} is gone from the archive` });
+            return;
+        }
+        if (read.tooLarge !== undefined) {
+            this.skipped.push({ givenNumber: entry.givenNumber, reason: `${name} is ${read.tooLarge} bytes, over ${INVOICE_FILE_MAX_BYTES}` });
+            return;
+        }
+        this.attachments ??= await this.host.getConnectorAttachments(this.connectionId, this.scopeRef);
+        await this.attachments.upload({
+            entity: entry.entity,
+            filename: name,
+            contentType: fileType(name, read.contentType),
+            visibility: 'internal',
+            body: read.bytes,
+        });
+        this.landed += 1;
+    }
+    /** The first file that could not be read this pass, or the refusal that stopped them. */
+    get failed() {
+        return this.failure;
+    }
 }
 /** One Fortnox invoice as the page carries it, parsed here so a bad one is named by number. */
 const landedInvoice = (invoice) => fortnoxSupplierInvoicePage.shape.invoices.element.parse({
@@ -466,14 +1064,79 @@ const landedInvoice = (invoice) => fortnoxSupplierInvoicePage.shape.invoices.ele
     invoiceDate: invoice.InvoiceDate,
     dueDate: invoice.DueDate,
     total: { amount: invoice.Total, currency: invoice.Currency },
+    ...(invoice.Balance === null ? {} : { balance: { amount: invoice.Balance, currency: invoice.Currency } }),
+    ...(invoice.VAT === null ? {} : { vat: { amount: invoice.VAT, currency: invoice.Currency } }),
+    ocr: invoice.OCR || null,
     booked: invoice.Booked,
     cancelled: invoice.Cancelled,
+    credit: invoice.Credit,
+    paymentPending: invoice.PaymentPending,
+    comments: invoice.Comments || null,
+    commentLog: invoice.CommentLog.map((c) => ({ comment: c.Comment, createdAt: c.CreatedAt || null, userName: c.UserName || null })),
+    voucher: invoice.VoucherNumber === null || invoice.VoucherNumber === '0'
+        ? null
+        : { series: invoice.VoucherSeries || null, number: Number(invoice.VoucherNumber), year: invoice.VoucherYear === null ? null : Number(invoice.VoucherYear) },
+    project: invoice.Project || null,
+    costCentre: invoice.CostCenter || null,
     rows: invoice.SupplierInvoiceRows.map((row) => ({
         account: row.Account,
+        accountDescription: row.AccountDescription || null,
         costCentre: row.CostCenter || null,
+        project: row.Project || null,
+        transactionInformation: row.TransactionInformation || null,
         amount: { amount: addDecimal(row.Debit, mulDecimal('-1', row.Credit)), currency: 'SEK' },
     })),
 });
+/**
+ * How long a binding's poll lease lasts (#2672): the invoice pass's deadline and a margin, so a
+ * poll that crashed holds no binding past it.
+ */
+const POLL_LEASE_MS = INVOICE_PASS_DEADLINE_MS + 60_000;
+const leaseKey = (scope) => `fortnox:lease:${scope}`;
+/**
+ * Take a binding's poll lease, so a pass and a poll asked for on request do not poll one binding at
+ * once (#2672). Null when a live lease is another's. Best effort: connector state has no
+ * compare-and-set, so the take is a write and a read back of its token, and two takers that
+ * interleave within those few milliseconds can both hold it.
+ */
+async function takePollLease(host, connectionId, scopeId, nowMs) {
+    const key = leaseKey(scopeId);
+    const held = (await host.admin.getConnectorState(connectionId, key));
+    if (held && Date.parse(held.until) > nowMs)
+        return null;
+    const token = ulid();
+    await host.admin.putConnectorState(connectionId, key, { token, until: new Date(nowMs + POLL_LEASE_MS).toISOString() });
+    const after = (await host.admin.getConnectorState(connectionId, key));
+    return after?.token === token ? token : null;
+}
+/**
+ * `fetch`, renewing the lease while the poll still asks Fortnox, so a slow poll (the ledger has no
+ * deadline of its own) keeps it. Every request is a step boundary; a lease another poll took over is
+ * left alone. A body read is not a boundary: one that streams longer than the lease can outlive it.
+ * Best effort, as the release: a renewal that fails leaves the lease to expire, never the request.
+ */
+function leaseRenewing(host, connectionId, scopeId, token, fetch, now) {
+    let renewedAt = now();
+    const renew = async (at) => {
+        const held = (await host.admin.getConnectorState(connectionId, leaseKey(scopeId)));
+        if (held?.token === token)
+            await host.admin.putConnectorState(connectionId, leaseKey(scopeId), { token, until: new Date(at + POLL_LEASE_MS).toISOString() });
+    };
+    return async (input, init) => {
+        if (now() - renewedAt >= POLL_LEASE_MS / 3) {
+            renewedAt = now();
+            await renew(renewedAt).catch(() => undefined);
+        }
+        return fetch(input, init);
+    };
+}
+/** Give the lease back, unless it expired and another poll took it over. */
+async function releasePollLease(host, connectionId, scopeId, token) {
+    const key = leaseKey(scopeId);
+    const held = (await host.admin.getConnectorState(connectionId, key));
+    if (held?.token === token)
+        await host.admin.putConnectorState(connectionId, key, null);
+}
 /**
  * Poll Fortnox for every scope this connection is bound to — the {@link ConnectorSweeper}
  * a deployment schedules. A ledger binding syncs its year of books
@@ -489,11 +1152,12 @@ const landedInvoice = (invoice) => fortnoxSupplierInvoicePage.shape.invoices.ele
  * the pass — one vertical's missing grant must not stop another tenant's books syncing.
  */
 export async function sweepFortnoxLedger(host, connectionId, options) {
-    const rows = await host.admin.listConnectorState(connectionId, BINDING_PREFIX);
-    const result = { found: 0, synced: [], invoices: [], unchanged: 0, failed: [] };
+    const rows = await host.admin.listConnectorState(connectionId, options.scopeId === undefined ? BINDING_PREFIX : bindingKey(options.scopeId));
+    const result = { found: 0, synced: [], invoices: [], unchanged: 0, failed: [], busy: [] };
     // One budget and one rate window per pass: every binding on this connection reads the same company.
     const budget = { details: INVOICE_DETAILS_PER_PASS };
     const pass = { ...options, rateWindow: options.rateWindow ?? [] };
+    const clock = () => options.now?.() ?? Date.now();
     for (const { value } of rows) {
         // A tombstoned binding (`unbindFortnoxScope`) — present as a row, not a target.
         if (value === null || typeof value !== 'object')
@@ -504,16 +1168,42 @@ export async function sweepFortnoxLedger(host, connectionId, options) {
             result.failed.push({ scopeId: binding.scopeId, error: `unknown Fortnox binding kind '${String(binding.kind)}'; upgrade this platform before polling this binding` });
             continue;
         }
+        // The same for the form, so a file binding is never polled as sums of a shape its landing refuses.
+        if (binding.form !== undefined && binding.form !== 'summary' && binding.form !== 'sie') {
+            result.failed.push({ scopeId: binding.scopeId, error: `unknown Fortnox ledger form '${String(binding.form)}'; upgrade this platform before polling this binding` });
+            continue;
+        }
+        let lease = null;
         try {
+            lease = await takePollLease(host, connectionId, binding.scopeId, clock());
+            if (lease === null) {
+                result.busy.push(binding.scopeId);
+                continue;
+            }
+            const leased = { ...pass, fetch: leaseRenewing(host, connectionId, binding.scopeId, lease, pass.fetch, clock) };
             if (binding.kind === 'supplier-invoice') {
-                const r = await syncFortnoxSupplierInvoices(host, connectionId, binding, { ...pass, budget });
-                if (r.landed > 0)
+                const r = await syncFortnoxSupplierInvoices(host, connectionId, binding, { ...leased, budget });
+                if (r.landed > 0 || r.files > 0 || r.held > 0 || r.written > 0 || r.skipped || r.pending)
                     result.invoices.push(r);
                 else
                     result.unchanged += 1;
                 continue;
             }
-            const r = await syncFortnoxScope(host, connectionId, binding, pass);
+            if (binding.form === 'sie') {
+                const { synced, failed } = await syncFortnoxSieFiles(host, connectionId, binding, leased);
+                const landed = synced.filter((r) => r.changed);
+                result.synced.push(...landed);
+                for (const f of failed) {
+                    result.failed.push({
+                        scopeId: binding.scopeId,
+                        error: `financial year ${f.financialYearId}: ${f.error instanceof Error ? f.error.message : String(f.error)}`,
+                    });
+                }
+                if (landed.length === 0 && failed.length === 0)
+                    result.unchanged += 1;
+                continue;
+            }
+            const r = await syncFortnoxScope(host, connectionId, binding, leased);
             if (r.changed)
                 result.synced.push(r);
             else
@@ -525,9 +1215,30 @@ export async function sweepFortnoxLedger(host, connectionId, options) {
                 error: err instanceof Error ? err.message : String(err),
             });
         }
+        finally {
+            // A release that fails leaves the lease to expire.
+            if (lease !== null)
+                await releasePollLease(host, connectionId, binding.scopeId, lease).catch(() => undefined);
+        }
     }
     return result;
 }
+/**
+ * Poll ONE scope's bindings now — {@link sweepFortnoxLedger} narrowed to the scope, so the same
+ * budget, deadline and rate window bound it as bound a pass.
+ */
+export async function pollFortnoxScope(host, connectionId, scopeId, options) {
+    const r = await sweepFortnoxLedger(host, connectionId, { ...options, scopeId });
+    const pending = r.invoices.some((i) => i.pending);
+    if (r.failed.length > 0)
+        return { outcome: 'failed', pending, errors: r.failed.map((f) => f.error) };
+    if (r.found === 0)
+        return { outcome: 'not-bound', pending: false, errors: [] };
+    if (r.busy.length > 0)
+        return { outcome: 'in-progress', pending: false, errors: [] };
+    const landed = r.synced.length > 0 || r.invoices.some((i) => i.landed > 0 || i.files > 0 || i.held > 0 || i.written > 0);
+    return { outcome: landed ? 'landed' : 'unchanged', pending, errors: [] };
+}
 /**
  * Probe a credential that is not stored yet — the connect-time check (#605).
  *
@@ -636,20 +1347,24 @@ export async function fortnoxConnectionActivity(host, connectionId) {
             key,
             title: `${b.vertical} — ${b.scopeId}`,
             reference: b.lastSync ? String(b.lastSync.financialYearId) : null,
-            status: b.lastSync || b.invoiceSync ? 'synced' : 'bound — not yet synced',
+            // A file binding may have landed an older year while its current one is refused.
+            status: b.lastSync || b.invoiceSync || (b.yearSync && Object.keys(b.yearSync).length > 0) ? 'synced' : 'bound — not yet synced',
             at: instant.parse(b.lastSync?.syncedAt ?? b.invoiceSync?.syncedAt ?? b.boundAt),
             facts: [
                 { label: 'Lands through', value: b.operation },
                 { label: 'Permission', value: b.permission },
                 ...(b.lastSync
                     ? [
-                        { label: 'Balances', value: String(b.lastSync.balances) },
+                        // A file binding lands no balance rows, so it has no count to show.
+                        ...(b.form === 'sie' ? [] : [{ label: 'Balances', value: String(b.lastSync.balances) }]),
                         { label: 'Financial year', value: String(b.lastSync.financialYearId) },
                         // The content hash IS the sync identity, so an operator comparing two
                         // scopes can tell "same books" from "same moment" at a glance.
                         { label: 'Content hash', value: b.lastSync.contentHash.slice(0, 12) },
                     ]
                     : []),
+                ...(b.yearSync ? [{ label: 'Financial years held', value: String(Object.keys(b.yearSync).length) }] : []),
+                ...(b.files?.length ? [{ label: 'Invoice files waiting', value: String(b.files.length) }] : []),
             ],
         };
     });