@substrat-run/connector-fortnox 0.2.0

package/dist/api.js

@@ -0,0 +1,276 @@
+import { z } from 'zod';
+/**
+ * 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 const FORTNOX_OAUTH_BASE = 'https://apps.fortnox.se/oauth-v1';
+/** The REST host — every data read hangs off this. */
+export 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 const fortnoxSecret = z.object({
+    /** From the Fortnox Developer Portal — the integration's identity. */
+    clientId: z.string().min(1),
+    /** From the Developer Portal — write-only, sealed by the host's SecretBox. */
+    clientSecret: z.string().min(1),
+    /**
+     * WHICH Fortnox company this connection reads, as the `TenantId` header.
+     *
+     * Numeric, and it is the company's `DatabaseNumber` — not a name, not the org
+     * number, and not anything a person would recognise. It is the one part of this
+     * credential that differs per company, which is what makes one client pair serve a
+     * whole fleet. Held as a string because it is a header value, never arithmetic.
+     */
+    tenantId: z.string().regex(/^\d+$/, 'Fortnox TenantId is the numeric DatabaseNumber'),
+});
+/**
+ * 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 function fortnoxConsentUrl(input) {
+    const url = new URL(`${input.oauthBase ?? FORTNOX_OAUTH_BASE}/auth`);
+    url.searchParams.set('client_id', input.clientId);
+    url.searchParams.set('redirect_uri', input.redirectUri);
+    url.searchParams.set('scope', input.scopes.join(' '));
+    url.searchParams.set('state', input.state);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('access_type', 'offline');
+    url.searchParams.set('account_type', 'service');
+    return url.toString();
+}
+/** One financial year, as `GET /3/financialyears` returns it. Extra fields ignored. */
+export const fortnoxFinancialYear = z.object({
+    Id: z.number(),
+    FromDate: z.string().min(1),
+    ToDate: z.string().min(1),
+    AccountingMethod: z.string().optional(),
+});
+/**
+ * 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 const fortnoxCompany = z.object({
+    CompanyName: z.string().default(''),
+    OrganizationNumber: z.string().default(''),
+    DatabaseNumber: z.union([z.number(), z.string()]).optional(),
+    CountryCode: z.string().optional(),
+});
+const tokenResponse = z.object({
+    access_token: z.string().min(1),
+    token_type: z.string().default('bearer'),
+    expires_in: z.number().default(3600),
+    scope: z.string().default(''),
+});
+/**
+ * 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 class FortnoxApiError extends Error {
+    status;
+    refused;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = 'FortnoxApiError';
+        this.status = status;
+        this.refused = status === 401 || status === 403;
+        this.body = body;
+    }
+}
+/**
+ * Fortnox's error envelope. Two shapes in the wild, and a caller wants the message
+ * from whichever arrived rather than a bare status.
+ */
+function errorMessage(body, status) {
+    try {
+        const parsed = JSON.parse(body);
+        const e = parsed;
+        const found = e.ErrorInformation?.message ??
+            e.ErrorInformation?.Message ??
+            e.error_description ??
+            e.message ??
+            (typeof e.error === 'string' ? e.error : undefined);
+        if (found)
+            return found;
+    }
+    catch {
+        // Not JSON — fall through to the raw slice, which is more use than nothing.
+    }
+    const slice = body.trim().slice(0, 200);
+    return slice === '' ? `HTTP ${status}` : slice;
+}
+/**
+ * `JSON.parse`, but a non-JSON body stays inside this module's error contract.
+ *
+ * Both parse sites run AFTER `res.ok`, which is exactly when this bites: a proxy,
+ * captive portal or gateway that answers `200` with an HTML page makes a bare
+ * `JSON.parse` throw a `SyntaxError`, and the caller loses `status`, `body` and
+ * `refused` — the three fields {@link FortnoxApiError} exists to carry, and the ones a
+ * sweep reports and a probe branches on. A parse failure is a fact about the response,
+ * so it is reported as one.
+ */
+function asJson(body, what) {
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        throw new FortnoxApiError(`${what} was not JSON`, 502, body);
+    }
+}
+export class FortnoxApi {
+    conn;
+    apiBase;
+    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.
+     */
+    token = null;
+    constructor(conn, options) {
+        this.conn = conn;
+        this.apiBase = options?.apiBase ?? FORTNOX_API_BASE;
+        this.oauthBase = options?.oauthBase ?? FORTNOX_OAUTH_BASE;
+        this.now = options?.now ?? (() => Date.now());
+    }
+    now;
+    secret() {
+        const parsed = fortnoxSecret.safeParse(this.conn.secret);
+        if (!parsed.success) {
+            throw new FortnoxApiError(`incomplete Fortnox credential: ${parsed.error.issues.map((i) => i.path.join('.')).join(', ')}`, 400, '');
+        }
+        return parsed.data;
+    }
+    /**
+     * 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.
+     */
+    async accessToken() {
+        if (this.token && this.token.expiresAtMs - this.now() > 60_000)
+            return this.token.value;
+        const { clientId, clientSecret, tenantId } = this.secret();
+        const res = await this.conn.fetch(`${this.oauthBase}/token`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Basic ${btoa(`${clientId}:${clientSecret}`)}`,
+                'Content-Type': 'application/x-www-form-urlencoded',
+                // The company. Without it Fortnox cannot tell which consent to mint against,
+                // and answers 400 — which reads like a bad client pair and is not.
+                TenantId: tenantId,
+            },
+            body: 'grant_type=client_credentials',
+        });
+        const body = await res.text();
+        if (!res.ok) {
+            throw new FortnoxApiError(`Fortnox token mint failed: ${errorMessage(body, res.status)}`, res.status, body);
+        }
+        const parsed = tokenResponse.safeParse(asJson(body, 'Fortnox token response'));
+        if (!parsed.success) {
+            throw new FortnoxApiError('Fortnox token response was not the documented shape', 502, body);
+        }
+        this.token = {
+            value: parsed.data.access_token,
+            expiresAtMs: this.now() + parsed.data.expires_in * 1000,
+        };
+        return this.token.value;
+    }
+    /** A JSON GET against the REST host, authenticated with a freshly-ensured token. */
+    async getJson(path) {
+        const token = await this.accessToken();
+        const res = await this.conn.fetch(`${this.apiBase}${path}`, {
+            headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+        });
+        const body = await res.text();
+        if (!res.ok) {
+            throw new FortnoxApiError(`Fortnox GET ${path} failed: ${errorMessage(body, res.status)}`, res.status, body);
+        }
+        return asJson(body, `Fortnox GET ${path}`);
+    }
+    /** The company — the probe read, and where a connect flow learns `DatabaseNumber`. */
+    async companyInformation() {
+        const raw = (await this.getJson('/companyinformation'));
+        return fortnoxCompany.parse(raw.CompanyInformation ?? raw);
+    }
+    /** Every financial year the company has, newest first is NOT guaranteed — sort yourself. */
+    async financialYears() {
+        const raw = (await this.getJson('/financialyears'));
+        return z.array(fortnoxFinancialYear).parse(raw.FinancialYears ?? []);
+    }
+    /**
+     * 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.
+     */
+    async sieFile(financialYearId) {
+        const token = await this.accessToken();
+        const path = `/sie/4?financialyear=${financialYearId}`;
+        const res = await this.conn.fetch(`${this.apiBase}${path}`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new FortnoxApiError(`Fortnox SIE4 export failed: ${errorMessage(body, res.status)}`, res.status, body);
+        }
+        return new TextDecoder('iso-8859-1').decode(await res.arrayBuffer());
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,260 @@
+import { z } from 'zod';
+import { type ConnectionActivity, type ConnectionProbe, type ConnectionId } from '@substrat-run/contracts';
+import type { FetchLike, ScopeHost } from '@substrat-run/kernel';
+export { FortnoxApi, FortnoxApiError, FORTNOX_API_BASE, FORTNOX_OAUTH_BASE, fortnoxConsentUrl, fortnoxSecret, type FortnoxCompany, type FortnoxFinancialYear, type FortnoxSecret, } from './api.js';
+export { parseSie4, splitSieLine, sieAmount, sieDate, type SieAccount, type SieDimension, type SieLedger, type SieObject, type SieTransaction, type SieVoucher, } from './sie4.js';
+export { COST_CENTRE_DIMENSION, financialYearFor, summarizeLedger, type LedgerBalance, type LedgerSummary, } from './aggregate.js';
+export { FortnoxMock, type FortnoxMockOptions } from './mock.js';
+/**
+ * The Fortnox connector — the INBOUND half of accounting integration.
+ *
+ * ## Poll-only, and that is a design fact rather than an omission
+ *
+ * `connector-scrive` has two halves: a dispatch handler driven by an engine event, and
+ * a sweep that polls the provider. This connector has **only the sweep**, and registers
+ * no event handler at all, because nothing inside a scope initiates the work. A
+ * vertical does not *ask* for last month's bookkeeping the way it asks for a signature;
+ * the bookkeeping simply changes at Fortnox, and the platform finds out by looking.
+ *
+ * So there is no `registerFortnoxConnector`. `sweepFortnoxLedger` is a
+ * {@link ConnectorSweeper}, the deployment binds it into the platform sweeper exactly
+ * as it binds Scrive's, and that is the whole trigger surface.
+ *
+ * ## Where the data lands, and why the connector does not decide
+ *
+ * A sweep has no delivered event, so it has neither a scope to write to nor authority
+ * to write with. Scrive gets both from its dispatch ledger — the row it wrote when the
+ * event arrived. This connector has no such moment, so the scope is declared **once**,
+ * explicitly, by {@link bindFortnoxScope}: which scope, which operation to land the
+ * ledger through, and which permission that operation checks.
+ *
+ * The operation is the *consumer's*, not this connector's, and that is deliberate. 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 accounts 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.
+ */
+/**
+ * The standing grants this connector requires — deliberately EMPTY, with a mechanism
+ * in place of a declaration.
+ *
+ * Every other connector names its return-path permissions here so `lint:connector-grants`
+ * can prove the dashboard's door is able to grant them. This one genuinely cannot: the
+ * permission it needs is whatever the *consumer's* landing operation checks, which
+ * differs per vertical and is unknown at this package's build time.
+ *
+ * That would be an invisible hole — the exact shape of #841, where a connector needed a
+ * grant no door could give and the way it surfaced was a failure months later. So the
+ * check moves from build time to bind time: {@link bindFortnoxScope} verifies the
+ * connection actually holds the named permission in the named scope and **refuses the
+ * binding otherwise**, naming what is missing. A sweep can therefore never be configured
+ * into a state where it fetches a year of bookkeeping and cannot write it down.
+ */
+export declare const FORTNOX_CONNECTION_GRANTS: readonly [];
+/**
+ * What the connector remembers about one scope it syncs into.
+ *
+ * Directory-side (`putConnectorState`) for the same reason Scrive's ledger is: this is
+ * a connector's own bookkeeping, it must survive across sweeps, and it must be readable
+ * without entering a scope.
+ */
+export interface FortnoxBinding {
+    scopeId: string;
+    tenantId: string;
+    /** The scope's vertical — half the key that reopens the connection to poll. */
+    vertical: string;
+    /**
+     * The operation the parsed ledger is landed through, e.g. `'ledger/record-period'`.
+     *
+     * Named by whoever binds, never defaulted. A default here would be a name this
+     * package invented for an operation it does not implement — so the first deployment
+     * to get it wrong would find out at sweep time, from an `unknown operation` error
+     * three layers down, rather than at bind time from this function.
+     */
+    operation: string;
+    /**
+     * The permission `operation` checks, which the connection must hold on `scopeId`.
+     *
+     * Recorded so the sweep can re-verify cheaply and so an operator can read the whole
+     * authority of this binding without opening the vertical's source.
+     */
+    permission: string;
+    boundAt: string;
+    /** Set after the first successful sync — the cursor that makes a re-sync cheap. */
+    lastSync?: {
+        financialYearId: number;
+        syncedAt: string;
+        /**
+         * SHA-256 of the SIE payload AND the window it was read through. Unchanged ⇒ the
+         * sync is skipped without landing. The window is in here because what lands is the
+         * payload filtered to it, so the same bytes read through a different period are a
+         * different result — see the note where this is computed.
+         */
+        contentHash: string;
+        balances: number;
+    };
+}
+/**
+ * One page of parsed bookkeeping, as it crosses into a scope.
+ *
+ * Parsed with this schema on the way OUT, before every `invoke`. The engine-seam rule
+ * (`returns()`) exists because a value crossing a version boundary must be pinned to a
+ * published shape rather than to whatever the code currently produces, and a connector
+ * seam is the same boundary with a network in the middle: a vertical compiled against
+ * one version of this package and running against another must get a throw, never a
+ * silently-reshaped ledger on a screen.
+ */
+export declare const fortnoxLedgerPage: z.ZodObject<{
+    syncId: z.ZodString;
+    connectionId: z.ZodString;
+    company: z.ZodObject<{
+        name: z.ZodString;
+        organizationNumber: z.ZodString;
+    }, z.core.$strip>;
+    financialYear: z.ZodObject<{
+        id: z.ZodNumber;
+        from: z.ZodString;
+        to: z.ZodString;
+    }, z.core.$strip>;
+    page: z.ZodNumber;
+    pageCount: z.ZodNumber;
+    final: z.ZodBoolean;
+    accounts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        number: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>>;
+    costCentres: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>>;
+    balances: z.ZodArray<z.ZodObject<{
+        account: z.ZodString;
+        costCentre: z.ZodNullable<z.ZodString>;
+        month: z.ZodString;
+        amount: z.ZodObject<{
+            amount: z.core.$ZodBranded<z.ZodString, "MoneyAmount", "out">;
+            currency: z.core.$ZodBranded<z.ZodString, "CurrencyCode", "out">;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type FortnoxLedgerPage = z.infer<typeof fortnoxLedgerPage>;
+export interface FortnoxConnectorOptions {
+    fetch: FetchLike;
+    apiBase?: string;
+    oauthBase?: string;
+    timeoutMs?: number;
+    /** Injected so a test can assert elapsed time without sleeping. */
+    now?: () => number;
+}
+/**
+ * Declare that a connection should sync one scope — the one-time setup a poll-only
+ * connector needs in place of a dispatch.
+ *
+ * **Refuses a binding whose grant is missing**, which is the whole reason this is a
+ * function rather than a config object. The alternative — write the binding, discover
+ * at sweep time that the connection cannot invoke the operation — fails in the worst
+ * possible place: after a year of bookkeeping has been fetched, in a background timer
+ * nobody is watching, with a provider round trip already spent. Here it fails in the
+ * operator's hands, naming the permission to grant.
+ */
+export declare function bindFortnoxScope(host: ScopeHost, input: {
+    connectionId: ConnectionId;
+    tenantId: string;
+    scopeId: string;
+    vertical: string;
+    operation: string;
+    permission: string;
+    now?: () => number;
+}): Promise<FortnoxBinding>;
+/** Every scope this connection syncs into. */
+export declare function listFortnoxBindings(host: ScopeHost, connectionId: ConnectionId): Promise<FortnoxBinding[]>;
+/**
+ * Stop syncing one scope. The binding row is replaced with a tombstone rather than
+ * removed, because `putConnectorState` is the only verb this surface has — and an
+ * unbound scope that a later sweep silently re-adopts would be worse than a visible
+ * dead row.
+ */
+export declare function unbindFortnoxScope(host: ScopeHost, connectionId: ConnectionId, scopeId: string): Promise<void>;
+/** What one scope's sync did. */
+export interface FortnoxSyncResult {
+    scopeId: string;
+    /** False when the books were byte-identical to the last sync — nothing was landed. */
+    changed: boolean;
+    syncId: string;
+    financialYearId: number | null;
+    balances: number;
+    pages: number;
+    /** Transactions dropped for falling outside the requested window. */
+    outOfRange: number;
+}
+/**
+ * Sync ONE bound scope: fetch the year that covers `period`, parse it, sum it, and land
+ * it through the binding's operation as the connection itself (#97).
+ *
+ * Idempotent and cheap on a no-op. The SIE payload is hashed before anything is landed,
+ * and an unchanged hash returns `changed: false` without a single `invoke` — which
+ * matters because a sweep runs on a timer and most passes find books nobody has touched.
+ */
+export declare function syncFortnoxScope(host: ScopeHost, connectionId: ConnectionId, binding: FortnoxBinding, options: FortnoxConnectorOptions & {
+    period?: {
+        from: string;
+        to: string;
+    };
+}): Promise<FortnoxSyncResult>;
+/** What one sweep pass over a connection did. */
+export interface FortnoxSweepResult {
+    found: number;
+    synced: FortnoxSyncResult[];
+    unchanged: number;
+    failed: {
+        scopeId: string;
+        error: string;
+    }[];
+}
+/**
+ * Poll Fortnox for every scope this connection is bound to — the {@link ConnectorSweeper}
+ * a deployment schedules.
+ *
+ * A timer calls this; it holds no timer itself. That keeps the trigger a deployment
+ * concern (`startPlatformSweeper` on node, `definePlatformSweeperDO`'s alarm on
+ * Cloudflare) and this a plain, testable function.
+ *
+ * Robust the way a poller must be: an unchanged year is skipped without landing
+ * anything, and a failure on one scope is recorded and stepped over rather than sinking
+ * the pass — one vertical's missing grant must not stop another tenant's books syncing.
+ */
+export declare function sweepFortnoxLedger(host: ScopeHost, connectionId: ConnectionId, options: FortnoxConnectorOptions & {
+    period?: {
+        from: string;
+        to: string;
+    };
+}): Promise<FortnoxSweepResult>;
+/**
+ * Probe a credential that is not stored yet — the connect-time check (#605).
+ *
+ * Takes the candidate secret directly, touches no connection and no store, and records
+ * no health: there may be no connection to record against, and a candidate's failure is
+ * not a fact about a live one.
+ *
+ * The probe is a token mint followed by `companyinformation`, and it must be both:
+ * minting alone proves the client pair and the consent, but only the company read proves
+ * the `TenantId` names a company this integration can actually see — which is the field
+ * an operator is most likely to paste wrong.
+ */
+export declare function probeFortnoxSecret(secret: Record<string, string>, options: FortnoxConnectorOptions): Promise<ConnectionProbe>;
+/** Probe the credential a live connection already holds. Verifying is itself a use. */
+export declare function probeFortnoxConnection(host: ScopeHost, connection: {
+    tenantId: string;
+    vertical: string;
+}, options: FortnoxConnectorOptions): Promise<ConnectionProbe>;
+/**
+ * What this connection has been doing, for a console — one entry per bound scope.
+ *
+ * Reads the binding ledger rather than the provider: this answers "what has the platform
+ * synced", which is the question an operator asks when a figure looks stale, and it
+ * answers it without spending a provider round trip.
+ */
+export declare function fortnoxConnectionActivity(host: ScopeHost, connectionId: ConnectionId): Promise<ConnectionActivity>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}