@solutiondesk/blog 0.0.0 → 1.0.0-69d9f69

package/dist/index.d.cts

@@ -0,0 +1,349 @@
+/**
+ * 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;
+
+/**
+ * Public blog and event images come in a fixed set of widths (`<url>?w=<width>`,
+ * WebP, never wider than the original); the API refuses any other width.
+ */
+declare const IMAGE_WIDTHS: readonly [320, 640, 960, 1280, 1920];
+type ImageWidth = (typeof IMAGE_WIDTHS)[number];
+/** The smallest offered width that is at least `width` (1920 for anything wider). */
+declare function imageWidthFor(width: number): ImageWidth;
+/**
+ * The address of an image at (at least) `width` pixels — e.g. for a Next.js
+ * custom image loader: `({ src, width }) => imageUrl(src, width)`. Without a
+ * width the original address is returned.
+ */
+declare function imageUrl(url: string, width?: number): string;
+
+/**
+ * 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 blog API (`GET /v1/blog/{workspace}/…`). Written by
+ * hand so the package has no dependencies; a drift test in the SolutionDesk
+ * repository keeps them identical to the API's own contracts.
+ */
+/** An author as readers see them. */
+interface PublicBlogAuthor {
+    key: string;
+    name: string;
+    initials: string;
+    kind: "person" | "organization";
+    /** The role in the requested language (the main role when not translated). */
+    role: string | null;
+}
+interface PublicBlogTag {
+    key: string;
+    /** The label in the requested language. */
+    label: string;
+}
+/** The cover image of a post. */
+interface PublicBlogImage {
+    url: string;
+    /** Every web-ready width (WebP, `<url>?w=<width>`) for `<img srcset>`. */
+    srcset: string;
+    width: number | null;
+    height: number | null;
+    alt: string | null;
+    /** A short caption or placeholder text. */
+    hint: string | null;
+    /** Made with AI: show a disclosure. */
+    ai: boolean;
+    credit: string | null;
+}
+/** The call to action at the end of a post. */
+interface PublicBlogClosing {
+    title: string | null;
+    lead: string | null;
+    label: string | null;
+    href: string | null;
+}
+/** A heading of the text, for a table of contents. */
+interface BlogHeading {
+    /** 1–6. */
+    level: number;
+    text: string;
+    /** Unique within the post; `#<id>` links to the heading. */
+    id: string;
+}
+/** A post in the list: everything but the text. */
+interface PublicBlogPostSummary {
+    slug: string;
+    title: string;
+    description: string;
+    /** ISO time readers see as the publication date. */
+    publishedAt: string;
+    /** "Updated on" as the team set it, or null. */
+    contentUpdatedAt: string | null;
+    /** The last change of any kind (for caches and sitemaps). */
+    updatedAt: string;
+    authors: PublicBlogAuthor[];
+    tags: PublicBlogTag[];
+    cover: PublicBlogImage | null;
+    /** The language the texts above are in — may differ from the one asked for. */
+    locale: string;
+    /** Every language the post is offered in, main language first. */
+    languages: string[];
+    readingMinutes: number;
+}
+/** One post with its text. */
+interface PublicBlogPost extends PublicBlogPostSummary {
+    markdown: string;
+    /** The Markdown as safe HTML (headings carry `id`s). */
+    html: string;
+    /** The outline, for a table of contents. */
+    headings: BlogHeading[];
+    closing: PublicBlogClosing | null;
+}
+/** `GET …/posts`. */
+interface PublicBlogPostsPayload {
+    posts: PublicBlogPostSummary[];
+    /** Pass as `cursor` for the next page; null on the last page. */
+    nextCursor: string | null;
+}
+/** `GET …/posts/{slug}` and `GET …/preview`. */
+interface PublicBlogPostPayload {
+    post: PublicBlogPost;
+}
+/** `GET …/tags`: every tag with how many published posts carry it, most used first. */
+interface PublicBlogTagsPayload {
+    tags: (PublicBlogTag & {
+        count: number;
+    })[];
+}
+/** `GET …/authors`. */
+interface PublicBlogAuthorsPayload {
+    authors: PublicBlogAuthor[];
+}
+/** What a blog webhook announces. */
+type BlogWebhookEvent = "post.published" | "post.updated" | "post.unpublished" | "post.deleted" | "ping";
+/** The body of a blog webhook call (verify it first — see `parseBlogWebhook`). */
+interface BlogWebhookBody {
+    event: BlogWebhookEvent;
+    /** The workspace slug, as in the public API path. */
+    workspace: string;
+    /** The post's slug; null for `ping`. */
+    slug: string | null;
+    /** Earlier slugs of the post — their pages are stale too. */
+    previousSlugs: string[];
+    /** The languages the post is offered in after the change. */
+    locales: string[];
+    occurredAt: string;
+}
+
+interface BlogClientOptions extends BaseClientOptions {
+    /** Your workspace's slug — the `acme` in `https://api.solutiondesk.io/v1/blog/acme`. */
+    workspace: string;
+    /**
+     * The language to ask for by default (`de`, `en`, `de-AT` …). Each answer
+     * says in `locale` which language it really is in. Override per call.
+     */
+    lang?: string;
+}
+interface LangParams {
+    /** The language to ask for; overrides the client's `lang`. */
+    lang?: string;
+}
+interface ListPostsParams extends LangParams {
+    /** Only posts with this tag key. An unknown key matches nothing. */
+    tag?: string;
+    /** Only posts by this author key. An unknown key matches nothing. */
+    author?: string;
+    /** Page size, 1–50 (default 20). */
+    limit?: number;
+    /** `nextCursor` of the previous page. */
+    cursor?: string | null;
+}
+interface GetPostParams extends LangParams {
+    /**
+     * What to do when the slug is an earlier address of a post:
+     * - `"follow"` (default): return the post; `movedFrom` holds the slug you asked for.
+     * - `"manual"`: return `{ redirectTo }` with the current slug instead.
+     */
+    redirect?: "follow" | "manual";
+}
+/** A post fetched with `redirect: "follow"`. */
+interface BlogPostResult extends PublicBlogPostPayload {
+    /**
+     * The slug you asked for when the post has moved to `post.slug` since
+     * (redirect your page there, e.g. with a 301); null when it hasn't.
+     */
+    movedFrom: string | null;
+}
+/** The post lives at another slug now (with `redirect: "manual"`). */
+interface BlogPostMoved {
+    redirectTo: string;
+}
+interface BlogClient {
+    /** The workspace this client reads. */
+    readonly workspace: string;
+    /** Published posts, newest first, one page (`GET /v1/blog/{workspace}/posts`). */
+    listPosts(params?: ListPostsParams, options?: RequestOptions): Promise<PublicBlogPostsPayload>;
+    /** Every published post, page by page — e.g. for a sitemap or a static build. */
+    allPosts(params?: Omit<ListPostsParams, "cursor">, options?: RequestOptions): AsyncGenerator<PublicBlogPostSummary, void, undefined>;
+    /**
+     * One published post with its text (`GET /v1/blog/{workspace}/posts/{slug}`).
+     * Throws a `SolutionDeskError` with status 404 for an unknown or unpublished post.
+     */
+    getPost(slug: string, params?: GetPostParams & {
+        redirect?: "follow";
+    }, options?: RequestOptions): Promise<BlogPostResult>;
+    getPost(slug: string, params: GetPostParams & {
+        redirect: "manual";
+    }, options?: RequestOptions): Promise<PublicBlogPostPayload | BlogPostMoved>;
+    /** Every tag with how many published posts carry it, most used first. */
+    listTags(params?: LangParams, options?: RequestOptions): Promise<PublicBlogTagsPayload>;
+    /** Every author with their role in the asked-for language. */
+    listAuthors(params?: LangParams, options?: RequestOptions): Promise<PublicBlogAuthorsPayload>;
+    /**
+     * The current state of a post (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<PublicBlogPostPayload>;
+    /** The address of a blog image at (at least) `width` pixels: 320, 640, 960, 1280 or 1920. */
+    imageUrl(url: string, width?: number): string;
+}
+/**
+ * A client for the public blog API — no key, no login; only published posts.
+ * Safe in the browser and on the server.
+ *
+ * @example
+ * const blog = createBlogClient({ workspace: "acme", lang: "en" });
+ * const { posts, nextCursor } = await blog.listPosts({ limit: 10 });
+ */
+declare function createBlogClient(options: BlogClientOptions): BlogClient;
+/**
+ * Verify a blog 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 parseBlogWebhook(secret: string, rawBody: WebhookBody, signatureHeader: string | null | undefined, options?: VerifyWebhookOptions): Promise<BlogWebhookBody | null>;
+
+export { type BaseClientOptions, type BlogClient, type BlogClientOptions, type BlogHeading, type BlogPostMoved, type BlogPostResult, type BlogWebhookBody, type BlogWebhookEvent, type CachedResponse, DEFAULT_BASE_URL, EVENT_HEADER, type EtagCache, type FetchInitLike, type FetchLike, type FetchResponseLike, type GetPostParams, IMAGE_WIDTHS, type ImageWidth, type LangParams, type ListPostsParams, type PublicBlogAuthor, type PublicBlogAuthorsPayload, type PublicBlogClosing, type PublicBlogImage, type PublicBlogPost, type PublicBlogPostPayload, type PublicBlogPostSummary, type PublicBlogPostsPayload, type PublicBlogTag, type PublicBlogTagsPayload, type RequestOptions, SIGNATURE_HEADER, SolutionDeskError, type VerifyWebhookOptions, type WebhookBody, createBlogClient, createMemoryEtagCache, imageUrl, imageWidthFor, parseBlogWebhook, verifyWebhookSignature };