@substrat-run/connector-fortnox 0.2.0

package/README.md

@@ -0,0 +1,204 @@
+# @substrat-run/connector-fortnox
+
+Fortnox accounting for Substrat: reads a company's bookkeeping out of Fortnox as **SIE4**, parses
+and sums it, and lands the result into a scope through the consuming vertical's own operation. A
+**connector** is host code — you sweep it on a scope host; it is never module code.
+
+**Full documentation: https://substrat.net/connectors/fortnox**
+
+## What it does
+
+One half, not two. `connector-scrive` has a dispatch handler *and* a poll; this connector has
+**only the poll**, and that is a design fact rather than an omission. Nothing inside a scope
+initiates this work: a vertical does not *ask* for last month's bookkeeping the way it asks for a
+signature — the books simply change at Fortnox, and the platform finds out by looking.
+
+So there is no `registerFortnoxConnector`. `sweepFortnoxLedger` is a `ConnectorSweeper`, the
+deployment binds it into the platform sweeper exactly as it binds Scrive's, and that is the whole
+trigger surface.
+
+Each pass, per bound scope: mint a token → list financial years → pick the one that **overlaps**
+the period → download SIE4 → hash it → parse, sum per (account, cost centre, month) → land it in
+pages through the vertical's operation, as the connection itself ([#97](https://github.com/substrat-run/substrat/issues/97)).
+
+## The credential: client credentials, not the authorization-code flow
+
+This is the most important thing on this page, because it is the opposite of what most Fortnox
+integration write-ups describe.
+
+Fortnox's usual flow is OAuth2 authorization-code: a person signs in, you store an access token
+and a **refresh token**, and you refresh forever. Fortnox's refresh tokens are **single-use and
+rotating** — each refresh mints a new one and kills the old — so two concurrent refreshes race,
+one wins, the other saves an already-dead token and the connection is bricked. Every integration
+built that way ends up carrying the same three mitigations: per-company coalescing of concurrent
+refreshes, optimistic locking on the token write, and a distinct "reconnect Fortnox" error.
+
+**This connector does not have that problem, because it never holds a refresh token.** Fortnox
+supports `grant_type=client_credentials` against a *service* consent, and a token minted that way
+comes from three static values:
+
+```ts
+{ clientId, clientSecret, tenantId }   // tenantId = the company's numeric DatabaseNumber
+```
+
+An access token lives an hour and is minted on demand, cached for the life of one sweep pass.
+There is no rotating state, so there is no rotation race, no coalescing map, no optimistic write,
+and no token table. The connection's sealed secret is the whole credential.
+
+The price is a **one-time consent round per company**, in a browser:
+
+```ts
+import { fortnoxConsentUrl } from '@substrat-run/connector-fortnox';
+
+const url = fortnoxConsentUrl({
+  clientId, redirectUri, state,
+  scopes: ['bookkeeping', 'companyinformation'],
+});
+```
+
+`account_type=service` is what makes the resulting consent mintable by client credentials
+afterwards, and `fortnoxConsentUrl` always sets it. Your callback exchanges the code once, reads
+`GET /3/companyinformation` for `DatabaseNumber`, and that number becomes the connection's
+`tenantId`. After that the code path is never used again.
+
+**To do that round once, locally**, from the repo root:
+
+```text
+pnpm fortnox:connect --client-id=<id> --client-secret=<secret>
+```
+
+Or paste the portal pair into `connectors/fortnox/.dev.vars` (gitignored) as
+`FORTNOX_CLIENT_ID` / `FORTNOX_CLIENT_SECRET` and run `pnpm fortnox:connect` with no flags —
+it reads that file for defaults, so a retry needs no arguments and no secret reaches shell
+history. It prints the `FORTNOX_TENANT_ID` line to add, which is the one value that cannot be
+typed by hand.
+
+The redirect URI must match one registered in the portal exactly; the default is
+`http://localhost:8899/callback`. Whether Fortnox accepts `http://` or `localhost` is not
+documented — if it refuses, register a tunnel's https URL, pass it as `--redirect-uri`, and point
+the tunnel at `--listen-port` (default 8899). The callback always speaks plain HTTP; terminating
+TLS is the tunnel's job.
+
+It serves the callback, completes the consent, reads the `DatabaseNumber`, then **mints again
+with `client_credentials`** to prove the service consent actually works — and prints the three
+lines for `connectors/fortnox/.dev.vars`. That last step is the point: it is this connector's
+whole premise, and it fails loudly here rather than silently skipping a test. `DatabaseNumber` is
+shown nowhere in the Developer Portal, so there is no way to assemble the credential by hand.
+
+**Scopes cannot be widened without a new consent round.** Ask for what the integration will need,
+not what it needs today — this is the single most expensive thing to get wrong, because fixing it
+means going back to every customer.
+
+## Using it
+
+```ts
+import {
+  bindFortnoxScope,
+  sweepFortnoxLedger,
+  probeFortnoxSecret,
+} from '@substrat-run/connector-fortnox';
+
+// 1. Check the credential BEFORE storing it (#605) — connecting should not mean
+//    "write the row and find out on the next sweep".
+const probe = await probeFortnoxSecret(secret, { fetch });
+if (!probe.ok && probe.refused) throw new Error(probe.error!);
+
+// 2. Open the connection with the client-credentials triple.
+await host.admin.createConnection(actor, {
+  id, tenantId, vertical, provider: 'fortnox', label,
+  // String(): `DatabaseNumber` comes off the API as a number, and `fortnoxSecret`
+  // wants a digit-only STRING (it is a header value, never arithmetic).
+  secret: { clientId, clientSecret, tenantId: String(databaseNumber) },  // sealed by the SecretBox
+});
+
+// 3. Grant the connection the permission YOUR landing operation checks, then bind.
+await host.admin.grantToConnection(actor, {
+  connectionId: id, permission: 'ledger:record', node, grantedBy: actor,
+});
+await bindFortnoxScope(host, {
+  connectionId: id, tenantId, scopeId, vertical,
+  operation: 'ledger/record-period',   // yours
+  permission: 'ledger:record',         // what it checks
+});
+
+// 4. Schedule the poll — YOUR deployment calls the sweep on a timer, as with Scrive.
+const sweeper = (h, id, o) => sweepFortnoxLedger(h, id, { ...o });
+//    Node:        startPlatformSweeper(host, { sweepers: { fortnox: sweeper }, intervalMs })
+//    Cloudflare:  definePlatformSweeperDO (@substrat-run/adapter-cloudflare)
+```
+
+### Why you name the operation, and the connector does not
+
+What comes out of Fortnox is neutral accounting fact: accounts, cost centres, months,
+debit-positive sums. What a business *means* by them — which account is `lokal_grundhyra`, which
+sign normalizes it, which group it rolls into — is **vocabulary**, and vocabulary is the vertical's
+layer. A connector that mapped account numbers to row keys would be a vertical wearing a
+connector's clothes, and the second customer with a different chart of accounts would have to fork
+it.
+
+So the connector hands you `FortnoxLedgerPage` and stops. Your operation does the mapping.
+
+### `bindFortnoxScope` refuses without the grant, on purpose
+
+A sweep has no delivered event, so it has neither a scope to write to nor authority to write with.
+Scrive gets both from the ledger row it wrote when the event arrived; this connector has no such
+moment, so the binding is the declaration — and it is verified when it is made.
+
+Without that check the binding is written, and the missing grant surfaces on the next sweep: in a
+background timer nobody is watching, after a year of bookkeeping has already been fetched. That is
+the shape of [#841](https://github.com/substrat-run/substrat/issues/841). Here it fails in the
+operator's hands, naming the permission to grant.
+
+It is also why `FORTNOX_CONNECTION_GRANTS` is empty rather than absent: the permission is the
+consumer's and cannot be declared at this package's build time, so the check moved from build time
+to bind time rather than disappearing.
+
+## Caveats worth knowing
+
+1. **Your deployment must schedule the poll** (step 4). The connector provides the driver; it
+   cannot hold a timer — that is a deployment concern. Without one wired, a binding is inert.
+
+2. **The live round-trip is unverified.** Everything here is built and tested against
+   `FortnoxMock`, and `test/live.test.ts` runs the real API — mint, `companyinformation`,
+   `financialyears`, `sie/4` — but **only when `connectors/fortnox/.dev.vars` holds a complete
+   credential**, which as of this writing it does not. The Developer Portal creates up to 30
+   **test databases**, administered like ordinary companies, and one of those is the right
+   target — `pnpm fortnox:connect` (above) is what fills the file. Until that has run,
+   three specific claims rest on documentation rather than measurement: that client-credentials
+   minting works as described, that the SIE4 response really is ISO-8859-1, and that the response
+   envelopes are `FinancialYears` / `CompanyInformation`. It stays a `0.x` release for this reason.
+
+   `test/live.test.ts` reads only: the data calls are GETs, and the one POST is the token mint,
+   which creates no Fortnox record. This connector has no write path to Fortnox at all, so
+   running it against a production company cannot damage anything.
+
+3. **SIE4 is ISO-8859-1, and nothing in the response says so.** Decoding it as UTF-8 does not
+   throw; it silently mangles every å/ä/ö in every account name and cost-centre label. That is a
+   corrupted ledger that looks like a working one. `FortnoxApi.sieFile` is the only place that
+   knows, and `FortnoxMock` serves real latin1 bytes so a regression fails in the suite rather than
+   in production.
+
+4. **Pick the financial year by OVERLAP, never containment.** A newly-acquired company's first
+   financial year can start mid-month (24 April, say). A search for "the year containing 1 January"
+   finds nothing and the sync reports empty books for a company with a full year of bookkeeping.
+   `financialYearFor` does this correctly and is exported for callers that need to ask directly.
+
+5. **Amounts are debit-positive, and this connector does not normalize them.** A cost account
+   carries a positive amount for a cost; a revenue account (a credit) carries a negative one. That
+   is correct double-entry, and inventing a sign here would put business meaning in a format
+   reader. Your mapping applies the sign.
+
+6. **A sync is all-or-nothing per scope, by cursor.** The content hash is written only after every
+   page has landed, so a failure part-way leaves the cursor at the previous hash and the next sweep
+   retries the whole year — rather than resuming into a half-written ledger. The `syncId` is that
+   hash, so every page of one run shares it and a consumer can swap a whole run atomically.
+
+## Testing
+
+`FortnoxMock` implements the token endpoint and the three REST reads in memory, so the whole sweep
+runs without a Fortnox account — credential minting, latin1 decoding, year selection, paging,
+the unchanged-hash skip, and the bind-time grant refusal.
+
+**What a mock proves:** that our shape works. **What it cannot prove:** that our reading of
+Fortnox's API is correct — the mock *is* our reading. Green here means *ready to check against a
+real company*, which is caveat 2.

package/dist/aggregate.d.ts

@@ -0,0 +1,69 @@
+import { type Money } from '@substrat-run/contracts';
+import type { FortnoxFinancialYear } from './api.js';
+import type { SieLedger } from './sie4.js';
+/**
+ * The cost-centre dimension. SIE reserves dimension `1` for kostnadsställe, and
+ * Fortnox follows the standard — so a per-property or per-unit breakdown needs no
+ * extra API call and no server-side filtering, only this constant.
+ */
+export declare const COST_CENTRE_DIMENSION = "1";
+/** One summed cell: an account, a cost centre, and a month. */
+export interface LedgerBalance {
+    account: string;
+    /** The dimension-1 object code, or `null` for rows booked without one. */
+    costCentre: string | null;
+    /** `YYYY-MM`. */
+    month: string;
+    /** Debit-positive, exactly as SIE stated it — see {@link SieLedger}. */
+    amount: Money;
+}
+/** What {@link summarizeLedger} produces: the sums plus the labels to render them. */
+export interface LedgerSummary {
+    currency: string;
+    balances: LedgerBalance[];
+    /** Only the accounts that actually carry a balance, with their `#KONTO` names. */
+    accounts: {
+        number: string;
+        name: string;
+    }[];
+    /** Only the dimension-1 objects that actually appear, with their `#OBJEKT` names. */
+    costCentres: {
+        code: string;
+        name: string;
+    }[];
+    /** Rows skipped because their date fell outside the requested window. */
+    outOfRange: number;
+}
+/**
+ * Pick the financial year to export for a given period.
+ *
+ * **Overlap, not containment** — this is the PDF's trap, and it is a real one. A
+ * newly-acquired company's first financial year can start mid-month (24 April, say),
+ * so a search for "the year containing 1 January" finds nothing and the sync reports
+ * an empty ledger for a company that has a full year of bookkeeping. Asking instead
+ * for the year that *overlaps* the period always finds it.
+ *
+ * Ties are broken toward the later year: when a period spans a year boundary, the
+ * newer year is the one still being posted to.
+ */
+export declare function financialYearFor(years: readonly FortnoxFinancialYear[], period: {
+    from: string;
+    to: string;
+}): FortnoxFinancialYear | null;
+/**
+ * Sum a parsed ledger per (account, cost centre, month).
+ *
+ * Exact decimal arithmetic throughout (`addDecimal` over micro-units), never floats:
+ * a ledger summed with `+=` on JavaScript numbers drifts by öre over a year of
+ * vouchers, and an accounting figure that is nearly right is worse than one that is
+ * obviously missing.
+ *
+ * The window is inclusive on both ends and filters on the TRANSACTION's date, which
+ * is the voucher's unless a row overrode it — so a voucher straddling a month
+ * boundary lands its rows in the months they belong to.
+ */
+export declare function summarizeLedger(ledger: SieLedger, window?: {
+    from: string;
+    to: string;
+}): LedgerSummary;
+//# sourceMappingURL=aggregate.d.ts.map

package/dist/aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../src/aggregate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,+DAA+D;AAC/D,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,MAAM,EAAE,KAAK,CAAC;CACf;AAED,sFAAsF;AACtF,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,kFAAkF;IAClF,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC7C,qFAAqF;IACrF,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9C,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,oBAAoB,EAAE,EACtC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACnC,oBAAoB,GAAG,IAAI,CAI7B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,EACjB,MAAM,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACpC,aAAa,CAqEf"}

package/dist/aggregate.js

@@ -0,0 +1,101 @@
+import { addDecimal, moneyOf } from '@substrat-run/contracts';
+/**
+ * The cost-centre dimension. SIE reserves dimension `1` for kostnadsställe, and
+ * Fortnox follows the standard — so a per-property or per-unit breakdown needs no
+ * extra API call and no server-side filtering, only this constant.
+ */
+export const COST_CENTRE_DIMENSION = '1';
+/**
+ * Pick the financial year to export for a given period.
+ *
+ * **Overlap, not containment** — this is the PDF's trap, and it is a real one. A
+ * newly-acquired company's first financial year can start mid-month (24 April, say),
+ * so a search for "the year containing 1 January" finds nothing and the sync reports
+ * an empty ledger for a company that has a full year of bookkeeping. Asking instead
+ * for the year that *overlaps* the period always finds it.
+ *
+ * Ties are broken toward the later year: when a period spans a year boundary, the
+ * newer year is the one still being posted to.
+ */
+export function financialYearFor(years, period) {
+    const overlapping = years.filter((y) => y.FromDate <= period.to && y.ToDate >= period.from);
+    if (overlapping.length === 0)
+        return null;
+    return overlapping.sort((a, b) => (a.FromDate < b.FromDate ? 1 : -1))[0];
+}
+/**
+ * Sum a parsed ledger per (account, cost centre, month).
+ *
+ * Exact decimal arithmetic throughout (`addDecimal` over micro-units), never floats:
+ * a ledger summed with `+=` on JavaScript numbers drifts by öre over a year of
+ * vouchers, and an accounting figure that is nearly right is worse than one that is
+ * obviously missing.
+ *
+ * The window is inclusive on both ends and filters on the TRANSACTION's date, which
+ * is the voucher's unless a row overrode it — so a voucher straddling a month
+ * boundary lands its rows in the months they belong to.
+ */
+export function summarizeLedger(ledger, window) {
+    const sums = new Map();
+    const seenAccounts = new Set();
+    const seenCentres = new Set();
+    let outOfRange = 0;
+    for (const voucher of ledger.vouchers) {
+        for (const t of voucher.transactions) {
+            if (t.account === '')
+                continue;
+            const date = t.date === '' ? voucher.date : t.date;
+            if (window && (date < window.from || date > window.to)) {
+                outOfRange += 1;
+                continue;
+            }
+            const month = date.slice(0, 7);
+            if (month === '')
+                continue;
+            const costCentre = t.objects[COST_CENTRE_DIMENSION] ?? null;
+            // NUL as the delimiter, because SIE cannot carry one in a field. A space could:
+            // `#OBJEKT` codes are quoted free text, so `{"1" "KV 1"}` is legal, and joining on
+            // spaces lets two distinct (account, cost centre, month) triples produce one key —
+            // silently summing two unrelated balances into a single cell.
+            const key = `${t.account}\u0000${costCentre ?? ''}\u0000${month}`;
+            const existing = sums.get(key);
+            // Seeded through `addDecimal` rather than stored raw, so a cell with ONE
+            // transaction is as canonical as a cell with two. `t.amount` is whatever the file
+            // said; `moneyOf` below demands `moneyAmount`'s shape, and a >6dp value satisfies
+            // the first and not the second — so a single-row cell was the one path that could
+            // reach `moneyOf` unnormalized.
+            if (existing)
+                existing.amount = addDecimal(existing.amount, t.amount);
+            else
+                sums.set(key, { account: t.account, costCentre, month, amount: addDecimal('0', t.amount) });
+            seenAccounts.add(t.account);
+            if (costCentre !== null)
+                seenCentres.add(costCentre);
+        }
+    }
+    const accountNames = new Map(ledger.accounts.map((a) => [a.number, a.name]));
+    const centreNames = new Map(ledger.objects.filter((o) => o.dimension === COST_CENTRE_DIMENSION).map((o) => [o.code, o.name]));
+    // Sorted so a sync is stable: the same year exported twice produces the same pages
+    // in the same order, which is what lets a consumer diff two runs and lets a test
+    // assert on a page without sorting it first.
+    const balances = [...sums.values()]
+        .sort((a, b) => a.account.localeCompare(b.account) ||
+        (a.costCentre ?? '').localeCompare(b.costCentre ?? '') ||
+        a.month.localeCompare(b.month))
+        .map((s) => ({
+        account: s.account,
+        costCentre: s.costCentre,
+        month: s.month,
+        amount: moneyOf(s.amount, ledger.currency),
+    }));
+    return {
+        currency: ledger.currency,
+        balances,
+        accounts: [...seenAccounts]
+            .sort()
+            .map((number) => ({ number, name: accountNames.get(number) ?? '' })),
+        costCentres: [...seenCentres].sort().map((code) => ({ code, name: centreNames.get(code) ?? '' })),
+        outOfRange,
+    };
+}
+//# sourceMappingURL=aggregate.js.map

package/dist/aggregate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.js","sourceRoot":"","sources":["../src/aggregate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,OAAO,EAAc,MAAM,yBAAyB,CAAC;AAI1E;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAyBzC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAsC,EACtC,MAAoC;IAEpC,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,IAAI,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;IAC5F,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC;AAC5E,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAiB,EACjB,MAAqC;IAErC,MAAM,IAAI,GAAG,IAAI,GAAG,EAGjB,CAAC;IACJ,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAC;IACtC,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACtC,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;YACrC,IAAI,CAAC,CAAC,OAAO,KAAK,EAAE;gBAAE,SAAS;YAC/B,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YACnD,IAAI,MAAM,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,IAAI,GAAG,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;gBACvD,UAAU,IAAI,CAAC,CAAC;gBAChB,SAAS;YACX,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAC/B,IAAI,KAAK,KAAK,EAAE;gBAAE,SAAS;YAC3B,MAAM,UAAU,GAAG,CAAC,CAAC,OAAO,CAAC,qBAAqB,CAAC,IAAI,IAAI,CAAC;YAC5D,gFAAgF;YAChF,mFAAmF;YACnF,mFAAmF;YACnF,8DAA8D;YAC9D,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,OAAO,SAAS,UAAU,IAAI,EAAE,SAAS,KAAK,EAAE,CAAC;YAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC/B,yEAAyE;YACzE,kFAAkF;YAClF,kFAAkF;YAClF,kFAAkF;YAClF,gCAAgC;YAChC,IAAI,QAAQ;gBAAE,QAAQ,CAAC,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;;gBACjE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACjG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YAC5B,IAAI,UAAU,KAAK,IAAI;gBAAE,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7E,MAAM,WAAW,GAAG,IAAI,GAAG,CACzB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,qBAAqB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CACjG,CAAC;IAEF,mFAAmF;IACnF,iFAAiF;IACjF,6CAA6C;IAC7C,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;SAChC,IAAI,CACH,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC;QAClC,CAAC,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC;QACtD,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CACjC;SACA,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACX,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC;KAC3C,CAAC,CAAC,CAAC;IAEN,OAAO;QACL,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,QAAQ;QACR,QAAQ,EAAE,CAAC,GAAG,YAAY,CAAC;aACxB,IAAI,EAAE;aACN,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACtE,WAAW,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACjG,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/api.d.ts

@@ -0,0 +1,154 @@
+import { z } from 'zod';
+import type { ConnectorConnection } from '@substrat-run/kernel';
+/**
+ * A thin, typed client over the Fortnox REST API and its OAuth2 token endpoint.
+ *
+ * Every call goes through the connection's `fetch`, never a global one: that is what
+ * gets it a timeout, an egress policy, and health recorded against the right
+ * connection. Module code cannot reach any of this — boundary-lint bans `fetch`
+ * outright — and a connector is host code.
+ *
+ * ## The two hosts are different, and mixing them is the first mistake
+ *
+ * OAuth lives at `apps.fortnox.se/oauth-v1`; the API lives at `api.fortnox.se/3`.
+ * They are separate origins with separate paths, so both are named here and neither
+ * is derived from the other.
+ */
+/** The OAuth2 host — `/auth` (consent) and `/token` (minting) hang off this. */
+export declare const FORTNOX_OAUTH_BASE = "https://apps.fortnox.se/oauth-v1";
+/** The REST host — every data read hangs off this. */
+export declare const FORTNOX_API_BASE = "https://api.fortnox.se/3";
+/**
+ * A Fortnox connection's credential — the CLIENT-CREDENTIALS triple.
+ *
+ * Deliberately NOT the authorization-code flow's tokens. Fortnox supports
+ * `grant_type=client_credentials` for a *service* consent, and that changes what a
+ * connection has to store: an access token is minted on demand from these three
+ * static values and lives one hour, so there is no refresh token — and therefore
+ * none of the rotation hazard the authorization-code flow carries. Fortnox's refresh
+ * tokens are single-use and rotating: two concurrent refreshes kill the connection,
+ * one winning and the other saving an already-dead token. A connector that mints
+ * from static credentials cannot reach that state at all.
+ *
+ * The price is a one-time consent round per company, in a browser, with
+ * `account_type=service` — see {@link fortnoxConsentUrl}. What that round yields is
+ * the `tenantId` below; the client pair comes from the Developer Portal and is the
+ * same for every company this integration serves.
+ */
+export declare const fortnoxSecret: z.ZodObject<{
+    clientId: z.ZodString;
+    clientSecret: z.ZodString;
+    tenantId: z.ZodString;
+}, z.core.$strip>;
+export type FortnoxSecret = z.infer<typeof fortnoxSecret>;
+/**
+ * The consent URL a company's sysadmin visits ONCE (the PDF's step 1, with the one
+ * parameter that changes everything).
+ *
+ * `account_type=service` is what makes the resulting consent mintable by
+ * `client_credentials` afterwards. Without it the consent is bound to the person who
+ * granted it, and this connector's whole credential model does not apply — you are
+ * back to storing and rotating refresh tokens per company.
+ *
+ * `access_type=offline` is kept because the callback still exchanges a code once, to
+ * discover the `DatabaseNumber` this connection will be keyed by
+ * ({@link FortnoxApi.companyInformation}). After that the code path is never used
+ * again.
+ *
+ * **Scopes cannot be widened later without a new consent round.** Ask for what the
+ * integration will need, not what it needs today — this is the single most expensive
+ * thing to get wrong here, because fixing it means going back to every customer.
+ */
+export declare function fortnoxConsentUrl(input: {
+    clientId: string;
+    redirectUri: string;
+    /** e.g. `['bookkeeping', 'companyinformation']` — `bookkeeping` is what SIE export needs. */
+    scopes: readonly string[];
+    /** Opaque round-trip value; the caller correlates its own record by it. */
+    state: string;
+    oauthBase?: string;
+}): string;
+/** One financial year, as `GET /3/financialyears` returns it. Extra fields ignored. */
+export declare const fortnoxFinancialYear: z.ZodObject<{
+    Id: z.ZodNumber;
+    FromDate: z.ZodString;
+    ToDate: z.ZodString;
+    AccountingMethod: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type FortnoxFinancialYear = z.infer<typeof fortnoxFinancialYear>;
+/**
+ * The company, as `GET /3/companyinformation` returns it.
+ *
+ * `DatabaseNumber` is the whole reason this endpoint is called: it IS the `TenantId`
+ * header value, and it is how a connect flow learns which company the consent it just
+ * received belongs to. It is also the cheapest authenticated read Fortnox offers, so
+ * it doubles as the credential probe.
+ */
+export declare const fortnoxCompany: z.ZodObject<{
+    CompanyName: z.ZodDefault<z.ZodString>;
+    OrganizationNumber: z.ZodDefault<z.ZodString>;
+    DatabaseNumber: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    CountryCode: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type FortnoxCompany = z.infer<typeof fortnoxCompany>;
+/**
+ * A Fortnox API failure, with the one bit a caller actually branches on.
+ *
+ * `refused` means the provider said "not with these credentials" — a 401 or 403.
+ * Everything else (a timeout, a 5xx, a parse failure) says nothing about the
+ * credential, and treating it as a refusal would make a Fortnox outage look like
+ * every tenant's keys going bad at once.
+ */
+export declare class FortnoxApiError extends Error {
+    readonly status: number;
+    readonly refused: boolean;
+    readonly body: string;
+    constructor(message: string, status: number, body: string);
+}
+export declare class FortnoxApi {
+    private readonly conn;
+    private readonly apiBase;
+    private readonly oauthBase;
+    /**
+     * The minted token and when it dies, cached for the life of THIS instance.
+     *
+     * Per-instance rather than per-connection-global on purpose: an instance is built
+     * for one sweep pass, so the cache lives exactly as long as the work that uses it
+     * and no cross-request state accumulates in a Worker's isolate. A token is an hour
+     * long and a pass is seconds, so one mint serves a whole pass.
+     */
+    private token;
+    constructor(conn: ConnectorConnection, options?: {
+        apiBase?: string;
+        oauthBase?: string;
+        now?: () => number;
+    });
+    private readonly now;
+    private secret;
+    /**
+     * Mint (or reuse) an access token via `grant_type=client_credentials`.
+     *
+     * The 60-second skew is the PDF's, and it is right for a different reason here:
+     * there is no refresh token to lose, so an early re-mint costs one extra round trip
+     * rather than risking a rotation race. Cheap insurance against a token expiring
+     * mid-pass.
+     */
+    accessToken(): Promise<string>;
+    /** A JSON GET against the REST host, authenticated with a freshly-ensured token. */
+    private getJson;
+    /** The company — the probe read, and where a connect flow learns `DatabaseNumber`. */
+    companyInformation(): Promise<FortnoxCompany>;
+    /** Every financial year the company has, newest first is NOT guaranteed — sort yourself. */
+    financialYears(): Promise<FortnoxFinancialYear[]>;
+    /**
+     * The whole year's bookkeeping as one SIE4 file — the read this connector exists for.
+     *
+     * **The response is ISO-8859-1, not UTF-8**, and nothing in the response says so.
+     * Decoding it as UTF-8 does not throw; it silently mangles every å/ä/ö in every
+     * account name, cost-centre label and verification text — which is a corrupted
+     * ledger that looks like a working one. So the bytes are taken as an ArrayBuffer and
+     * decoded explicitly, and this is the only place in the connector that knows.
+     */
+    sieFile(financialYearId: number): Promise<string>;
+}
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAQhE;;;;;;;;;;;;;GAaG;AAEH,gFAAgF;AAChF,eAAO,MAAM,kBAAkB,qCAAqC,CAAC;AACrE,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,6BAA6B,CAAC;AAE3D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa;;;;iBAcxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,6FAA6F;IAC7F,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,CAUT;AAED,uFAAuF;AACvF,eAAO,MAAM,oBAAoB;;;;;iBAK/B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;;;;iBAKzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAS5D;;;;;;;GAOG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,YAAY,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAMxD;CACF;AA+CD,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAsB;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC;;;;;;;OAOG;IACH,OAAO,CAAC,KAAK,CAAuD;IAEpE,YACE,IAAI,EAAE,mBAAmB,EACzB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;KAAE,EAMvE;IAED,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC,OAAO,CAAC,MAAM;IAYd;;;;;;;OAOG;IACG,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,CA+BnC;IAED,oFAAoF;YACtE,OAAO;IAgBrB,sFAAsF;IAChF,kBAAkB,IAAI,OAAO,CAAC,cAAc,CAAC,CAKlD;IAED,4FAA4F;IACtF,cAAc,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAGtD;IAED;;;;;;;;OAQG;IACG,OAAO,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAetD;CACF"}