@solutiondesk/legal 0.0.0 → 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,456 @@
+/**
+ * The HTTP part shared by the public SolutionDesk SDKs. Runs on any runtime with
+ * a WHATWG `fetch` (Node ≥ 18, Deno, Bun, edge runtimes, browsers) — and on
+ * purpose names no DOM or Node type, so the published `.d.ts` files need neither
+ * `lib: ["dom"]` nor `@types/node`.
+ */
+/** The production API. */
+declare const DEFAULT_BASE_URL = "https://api.solutiondesk.io";
+/** The response parts the SDK reads — what every `fetch` implementation returns. */
+interface FetchResponseLike {
+    readonly status: number;
+    readonly ok: boolean;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}
+/** What the SDK passes to `fetch` (plus whatever you set in `fetchOptions`). */
+interface FetchInitLike {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}
+/**
+ * A `fetch` implementation. The global `fetch` fits, so do `undici`, `node-fetch`
+ * and wrappers (e.g. one that adds tracing). Declared bivariantly so a fetch with
+ * a richer `init` type is accepted.
+ */
+type FetchLike = {
+    bivarianceHack(input: string, init?: FetchInitLike): Promise<FetchResponseLike>;
+}["bivarianceHack"];
+/** A response kept for `If-None-Match` revalidation. */
+interface CachedResponse {
+    etag: string;
+    body: unknown;
+}
+/**
+ * Where the client keeps answers for ETag revalidation. Any `Map` fits; bring
+ * your own to share it between clients or to bound it differently.
+ */
+interface EtagCache {
+    get(key: string): CachedResponse | undefined;
+    set(key: string, value: CachedResponse): unknown;
+}
+/** Options every client factory takes. */
+interface BaseClientOptions {
+    /** The API origin, without `/v1`. Defaults to `https://api.solutiondesk.io`. */
+    baseUrl?: string;
+    /** A `fetch` implementation; defaults to the global one. */
+    fetch?: FetchLike;
+    /** Headers sent with every request (e.g. `accept-language` forwarded from your visitor). */
+    headers?: Record<string, string>;
+    /**
+     * Revalidate with `If-None-Match`: the client remembers each answer's `ETag`
+     * and, when the API answers `304 Not Modified`, returns the remembered body.
+     * `true` keeps up to 500 answers in memory; or pass your own {@link EtagCache}.
+     * Off by default (your framework's fetch cache may already do this).
+     */
+    etagCache?: boolean | EtagCache;
+}
+/** Per-call options. */
+interface RequestOptions {
+    /** Cancels the request (an `AbortSignal`). */
+    signal?: unknown;
+    /** Extra headers for this request. */
+    headers?: Record<string, string>;
+    /**
+     * Extra `fetch` options for this request, passed through unchanged — e.g.
+     * Next.js `{ next: { revalidate: 60, tags: ["legal"] } }` or `{ cache: "no-store" }`.
+     */
+    fetchOptions?: Record<string, unknown>;
+}
+/** Any non-2xx answer of the API (and a failed network request, with `status` 0). */
+declare class SolutionDeskError extends Error {
+    /** The HTTP status; `0` when no answer arrived (network error, aborted). */
+    readonly status: number;
+    /** The parsed JSON body of the error answer (usually `{ error: string }`), else its text. */
+    readonly body: unknown;
+    /** The requested URL. */
+    readonly url: string;
+    /** Messages per input field on a `400` (e.g. `{ email: "Enter a valid email address." }`). */
+    readonly fields: Record<string, string>;
+    constructor(message: string, init: {
+        status: number;
+        body?: unknown;
+        url: string;
+        cause?: unknown;
+    });
+    /** `404`: unknown workspace, module turned off or unknown item — on purpose indistinguishable. */
+    get isNotFound(): boolean;
+    /** `429`: over the rate limit; try again later. */
+    get isRateLimited(): boolean;
+}
+/** A bounded in-memory {@link EtagCache} (oldest entry dropped first). */
+declare function createMemoryEtagCache(maxEntries?: number): EtagCache;
+
+/**
+ * Webhook signature check with Web Crypto only — the same code runs in Node,
+ * Deno, Bun, edge runtimes and browsers. The header SolutionDesk sends is
+ * `X-SolutionDesk-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>`.
+ */
+/** The header that carries the signature. */
+declare const SIGNATURE_HEADER = "x-solutiondesk-signature";
+/** The header that names the event (also in the body as `event`). */
+declare const EVENT_HEADER = "x-solutiondesk-event";
+interface VerifyWebhookOptions {
+    /** How old (or how far in the future) the signed time may be. Default 300 (5 minutes). */
+    toleranceSeconds?: number;
+    /** "Now" in milliseconds (or a `Date`) — for tests. Default `Date.now()`. */
+    now?: number | Date;
+    /**
+     * A Web Crypto implementation. Default `globalThis.crypto`. On Node 18 pass
+     * `require("node:crypto").webcrypto` (Node 19+ has it globally).
+     */
+    crypto?: {
+        subtle: object;
+    };
+}
+/** The raw request body, exactly as received. */
+type WebhookBody = string | Uint8Array | ArrayBuffer;
+/**
+ * Check a SolutionDesk webhook signature. `true` only when the header is well
+ * formed, its time lies within the tolerance and the HMAC matches — anything
+ * else (missing, tampered, expired, malformed) is `false`, never an exception.
+ *
+ * @param secret The webhook's signing secret (`whsec_…`), shown once in SolutionDesk.
+ * @param rawBody The request body exactly as received — not re-serialized JSON.
+ * @param header The `X-SolutionDesk-Signature` header.
+ */
+declare function verifyWebhookSignature(secret: string, rawBody: WebhookBody, header: string | null | undefined, options?: VerifyWebhookOptions): Promise<boolean>;
+
+/**
+ * The answers of the public Legal Hub API (`GET /v1/legal/{workspace}/…`), the
+ * host integration (`/v1/integration/legal/…`) and the webhook. Written by hand
+ * so the package has no dependencies; a drift test in the SolutionDesk
+ * repository keeps them in line with the API's own contracts.
+ */
+/** What a legal text is. */
+type LegalDocumentKind = "imprint" | "privacy" | "terms" | "dpa" | "subprocessors" | "custom";
+/** Where a version stands at the time of the request (decided by date). */
+type PublicLegalVersionStatus = "draft" | "upcoming" | "current" | "earlier";
+/** A heading of the text, for a table of contents. */
+interface LegalHeading {
+    /** 1–6. */
+    level: number;
+    text: string;
+    /** Unique within the text; `#<id>` links to the heading. */
+    id: string;
+}
+/** A version in short: its number, when it applies, what changed. */
+interface PublicLegalVersionRef {
+    number: number;
+    effectiveAt: string;
+    summary: string;
+}
+/** One sub-processor as your website shows it (entries marked internal are never included). */
+interface PublicLegalSubprocessor {
+    /** Stable across versions (`azure`, `postmark`). */
+    key: string;
+    name: string;
+    website: string | null;
+    /** What they do for you (in the requested language). */
+    purpose: string;
+    /** Which data they process (in the requested language). */
+    data: string;
+    /** ISO 3166-1 alpha-2 country codes (`DE`, `IE`, `US`) and an optional note. */
+    location: {
+        countries: string[];
+        note: string | null;
+    };
+    /** For a country outside the EU/EEA: `adequacy`, `scc`, `bcr` or `other`. */
+    transferSafeguard: {
+        kind: string;
+        note: string | null;
+    } | null;
+}
+/** A field of a sub-processor entry that changed. */
+type PublicLegalSubprocessorField = "name" | "website" | "purpose" | "data" | "location" | "transferSafeguard";
+/** What an announced sub-processor list changes against the one in force. */
+interface PublicLegalSubprocessorChanges {
+    added: PublicLegalSubprocessor[];
+    removed: PublicLegalSubprocessor[];
+    changed: {
+        key: string;
+        fields: PublicLegalSubprocessorField[];
+        before: PublicLegalSubprocessor;
+        after: PublicLegalSubprocessor;
+    }[];
+}
+/** The announced next version. */
+interface PublicLegalUpcoming extends PublicLegalVersionRef {
+    /** Only for the sub-processor list. */
+    changes?: PublicLegalSubprocessorChanges;
+}
+/** One entry of `GET …/documents`. */
+interface PublicLegalDocumentSummary {
+    slug: string;
+    kind: LegalDocumentKind;
+    title: string;
+    /** The language of `title` and `current.summary`. */
+    locale: string;
+    /** Every language the version in force is offered in, its main one first. */
+    languages: string[];
+    current: PublicLegalVersionRef;
+    upcoming: PublicLegalVersionRef | null;
+}
+/** `GET …/documents`. */
+interface PublicLegalDocumentsPayload {
+    documents: PublicLegalDocumentSummary[];
+}
+/** One version in full (`documents/{slug}`, `…/versions/{number}`, `preview`). */
+interface PublicLegalDocument {
+    slug: string;
+    kind: LegalDocumentKind;
+    title: string;
+    status: PublicLegalVersionStatus;
+    /** Null only for a draft that was never published. */
+    number: number | null;
+    effectiveAt: string | null;
+    summary: string;
+    /** The language the text is really in. */
+    locale: string;
+    languages: string[];
+    markdown: string;
+    /** Safe to insert as it is: no scripts, no images, links only to web addresses. */
+    html: string;
+    headings: LegalHeading[];
+    /** The sub-processor list (internal entries removed); null for other kinds. */
+    subprocessors: PublicLegalSubprocessor[] | null;
+    /** The announced next version — only on the version in force. */
+    upcoming: PublicLegalUpcoming | null;
+}
+/** `GET …/documents/{slug}`, `…/versions/{number}` and `…/preview`. */
+interface PublicLegalDocumentPayload {
+    document: PublicLegalDocument;
+}
+/** One entry of the archive. `until` is when a later version replaced it. */
+interface PublicLegalArchiveEntry extends PublicLegalVersionRef {
+    status: Exclude<PublicLegalVersionStatus, "draft">;
+    until: string | null;
+}
+/** `GET …/documents/{slug}/versions`. */
+interface PublicLegalVersionsPayload {
+    document: {
+        slug: string;
+        kind: LegalDocumentKind;
+        title: string;
+        locale: string;
+    };
+    versions: PublicLegalArchiveEntry[];
+}
+/** `GET …/subprocessors`: the list in force and what the announced one changes. */
+interface PublicLegalSubprocessorsPayload {
+    document: {
+        slug: string;
+        title: string;
+        number: number;
+        effectiveAt: string;
+        locale: string;
+        languages: string[];
+    };
+    subprocessors: PublicLegalSubprocessor[];
+    upcoming: PublicLegalUpcoming | null;
+}
+/** How an agreement was given. */
+type LegalAcceptanceChannel = "host" | "portal" | "email_link";
+/** One version an end user still has to agree to. */
+interface LegalHostPendingItem {
+    /** Document slug — what {@link LegalHostAcceptanceInput.document} takes. */
+    document: string;
+    kind: LegalDocumentKind;
+    /** Title in the requested language (else the main one). */
+    title: string;
+    number: number;
+    /** When the version takes (or took) effect. */
+    effectiveAt: string;
+    /** Already in force (false: announced, takes effect at `effectiveAt`). */
+    inForce: boolean;
+    /** What changed, in the requested language (else the main one). */
+    summary: string;
+    /** Where the full text can be read (in `locale`). */
+    url: string;
+    /** The language of `title`, `summary` and `url`. */
+    locale: string;
+    /** Agreed per company by an administrator: the company (your id) this agreement is for. */
+    companyExternalId: string | null;
+}
+/** `GET /v1/integration/legal/pending`. */
+interface LegalHostPendingPayload {
+    pending: LegalHostPendingItem[];
+}
+/** `POST /v1/integration/legal/acceptances` — your user agreed in your own dialog. */
+interface LegalHostAcceptanceInput {
+    /** The end user's id in your app. */
+    externalId: string;
+    /** The document's slug, e.g. `terms`. */
+    document: string;
+    /** The version number the user agreed to. */
+    number: number;
+    /** When the user agreed (ISO 8601 with offset or `Z`); defaults to now. Never in the future. */
+    acceptedAt?: string;
+    /** The user's IP address, kept as proof. */
+    ip?: string;
+    /** The user's browser, kept as proof. */
+    userAgent?: string;
+    /**
+     * The company the user agreed for (texts agreed per company by an
+     * administrator) — also the company a new end user is created in.
+     */
+    companyExternalId?: string;
+    /** With `name` and `companyExternalId`: creates an end user SolutionDesk doesn't know yet. */
+    email?: string;
+    name?: string;
+}
+/** The answer to a reported agreement. */
+interface LegalHostAcceptanceRecordedPayload {
+    ok: true;
+    /** False when nothing new was stored: the same agreement, or one that already covers it. */
+    created: boolean;
+    acceptance: {
+        id: string;
+        document: string;
+        /** The version the stored agreement is for (an earlier one covers an editorial change). */
+        number: number;
+        channel: LegalAcceptanceChannel;
+        acceptedAt: string;
+        /** Agreed for a company: its id in your app. */
+        companyExternalId: string | null;
+    };
+}
+/** What a legal webhook announces. */
+type LegalWebhookEvent = "version.published" | "version.effective" | "version.withdrawn" | "acceptance.recorded" | "ping";
+/** Who agreed, in your app's own ids (`acceptance.recorded`). */
+interface LegalWebhookAcceptance {
+    /** The end user's id in your app (null for a user without one). */
+    externalId: string | null;
+    /** The company's id in your app, when one administrator agreed for it. */
+    company: string | null;
+    channel: LegalAcceptanceChannel;
+    acceptedAt: string;
+}
+/** The body of a legal webhook call (verify it first — see `parseLegalWebhook`). */
+interface LegalWebhookBody {
+    event: LegalWebhookEvent;
+    /** The workspace slug, as in the public API path. */
+    workspace: string;
+    /** Document slug (null for `ping`). */
+    document: string | null;
+    kind: string | null;
+    number: number | null;
+    effectiveAt: string | null;
+    /** Languages the version is offered in (empty for `acceptance.recorded`). */
+    locales: string[];
+    occurredAt: string;
+    /** Only on `acceptance.recorded`. */
+    acceptance?: LegalWebhookAcceptance;
+}
+/** The body of an `acceptance.recorded` call. */
+type LegalAcceptanceRecordedWebhook = LegalWebhookBody & {
+    event: "acceptance.recorded";
+    document: string;
+    kind: string;
+    acceptance: LegalWebhookAcceptance;
+};
+
+interface LegalClientOptions extends BaseClientOptions {
+    /** Your workspace's slug — the `acme` in `https://api.solutiondesk.io/v1/legal/acme`. */
+    workspace: string;
+    /**
+     * The language to ask for by default. You get exactly it if the text exists
+     * in it, else the same language of another region (`de-AT` → `de`), else the
+     * main language — `locale` in each answer says which. Override per call.
+     */
+    lang?: string;
+}
+interface LangParams {
+    /** The language to ask for; overrides the client's `lang`. */
+    lang?: string;
+}
+interface LegalClient {
+    /** The workspace this client reads. */
+    readonly workspace: string;
+    /** Every text with the version that applies today and, if announced, the next one. */
+    listDocuments(params?: LangParams, options?: RequestOptions): Promise<PublicLegalDocumentsPayload>;
+    /**
+     * The version of a text that applies today, in full (`GET …/documents/{slug}`).
+     * Throws a `SolutionDeskError` with status 404 for an unknown slug, a
+     * workspace without legal texts and a text without a published version alike.
+     */
+    getDocument(slug: string, params?: LangParams, options?: RequestOptions): Promise<PublicLegalDocumentPayload>;
+    /**
+     * Every published version of a text — earlier, current and announced. Only
+     * while "Show earlier versions on your website" is on (else 404).
+     */
+    listVersions(slug: string, params?: LangParams, options?: RequestOptions): Promise<PublicLegalVersionsPayload>;
+    /** One version in full: the current one, the announced one, or an earlier one (when shown). */
+    getVersion(slug: string, number: number, params?: LangParams, options?: RequestOptions): Promise<PublicLegalDocumentPayload>;
+    /** The list of sub-processors in force and what the announced list changes. */
+    getSubprocessors(params?: LangParams, options?: RequestOptions): Promise<PublicLegalSubprocessorsPayload>;
+    /**
+     * Any version (also a draft) for your preview route — the `token` from your
+     * preview address (valid for one hour). The API sends it with
+     * `Cache-Control: no-store`; in Next.js also pass `fetchOptions: { cache: "no-store" }`.
+     */
+    getPreview(token: string, params?: LangParams, options?: RequestOptions): Promise<PublicLegalDocumentPayload>;
+}
+/**
+ * A client for the public Legal Hub API — no key, no login; only published
+ * versions. Load legal texts on the server or at build time and keep the last
+ * answer, so your imprint stays up even when SolutionDesk can't be reached.
+ *
+ * @example
+ * const legal = createLegalClient({ workspace: "acme", lang: "en" });
+ * const { document } = await legal.getDocument("imprint");
+ */
+declare function createLegalClient(options: LegalClientOptions): LegalClient;
+interface LegalHostClientOptions extends Omit<BaseClientOptions, "etagCache"> {
+    /** An API key of your workspace (Settings → API keys). Keep it on your server. */
+    apiKey: string;
+}
+interface PendingParams {
+    /** The end user's id in your app. */
+    externalId: string;
+    /** The language for `title`, `summary` and `url`. */
+    lang?: string;
+}
+interface LegalHostClient {
+    /**
+     * The versions an end user still has to agree to
+     * (`GET /v1/integration/legal/pending`) — show them in your own dialog.
+     * Throws 404 for an unknown end user or with legal texts turned off.
+     */
+    pending(params: PendingParams, options?: RequestOptions): Promise<LegalHostPendingPayload>;
+    /**
+     * Report that an end user agreed in your app
+     * (`POST /v1/integration/legal/acceptances`). Repeating it is harmless:
+     * `created` is false when nothing new was stored.
+     */
+    recordAcceptance(input: LegalHostAcceptanceInput, options?: RequestOptions): Promise<LegalHostAcceptanceRecordedPayload>;
+}
+/**
+ * **Server only.** A client for the legal part of the host API, authenticated
+ * with your workspace's API key (`Authorization: Bearer …`). Never ship the key
+ * to a browser.
+ */
+declare function createLegalHostClient(options: LegalHostClientOptions): LegalHostClient;
+/**
+ * Verify a legal webhook call and return its body — or `null` when the
+ * `X-SolutionDesk-Signature` header doesn't match (wrong secret, changed body,
+ * older than 5 minutes, malformed). Pass the raw body exactly as received.
+ */
+declare function parseLegalWebhook(secret: string, rawBody: WebhookBody, signatureHeader: string | null | undefined, options?: VerifyWebhookOptions): Promise<LegalWebhookBody | null>;
+/** Narrows a verified webhook body to `acceptance.recorded`. */
+declare function isAcceptanceRecorded(body: LegalWebhookBody): body is LegalAcceptanceRecordedWebhook;
+
+export { type BaseClientOptions, type CachedResponse, DEFAULT_BASE_URL, EVENT_HEADER, type EtagCache, type FetchInitLike, type FetchLike, type FetchResponseLike, type LangParams, type LegalAcceptanceChannel, type LegalAcceptanceRecordedWebhook, type LegalClient, type LegalClientOptions, type LegalDocumentKind, type LegalHeading, type LegalHostAcceptanceInput, type LegalHostAcceptanceRecordedPayload, type LegalHostClient, type LegalHostClientOptions, type LegalHostPendingItem, type LegalHostPendingPayload, type LegalWebhookAcceptance, type LegalWebhookBody, type LegalWebhookEvent, type PendingParams, type PublicLegalArchiveEntry, type PublicLegalDocument, type PublicLegalDocumentPayload, type PublicLegalDocumentSummary, type PublicLegalDocumentsPayload, type PublicLegalSubprocessor, type PublicLegalSubprocessorChanges, type PublicLegalSubprocessorField, type PublicLegalSubprocessorsPayload, type PublicLegalUpcoming, type PublicLegalVersionRef, type PublicLegalVersionStatus, type PublicLegalVersionsPayload, type RequestOptions, SIGNATURE_HEADER, SolutionDeskError, type VerifyWebhookOptions, type WebhookBody, createLegalClient, createLegalHostClient, createMemoryEtagCache, isAcceptanceRecorded, parseLegalWebhook, verifyWebhookSignature };