@solutiondesk/blog 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wemogy GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,195 @@
-# Temporary Holding Version
+# @solutiondesk/blog
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed client for the public [SolutionDesk](https://solutiondesk.io) blog API. Your team writes the articles in SolutionDesk; your website reads them with this package.
+
+- No dependencies, ESM and CommonJS, full TypeScript types.
+- Runs wherever `fetch` does: Node.js 18+, Deno, Bun, edge runtimes and browsers.
+- No key and no login: the API only ever returns published articles.
+
+```bash
+npm install @solutiondesk/blog
+```
+
+## Quick start
+
+```ts
+import { createBlogClient } from "@solutiondesk/blog";
+
+const blog = createBlogClient({ workspace: "acme", lang: "en" });
+
+const { posts, nextCursor } = await blog.listPosts({ limit: 10 });
+const { post } = await blog.getPost("metadata-that-pays-off");
+```
+
+`workspace` is your workspace's slug, the `acme` in the blog address shown under **Blog → Website** (`https://api.solutiondesk.io/v1/blog/acme`).
+
+## What you can read
+
+| Method | API | Returns |
+| --- | --- | --- |
+| `listPosts({ lang, tag, author, limit, cursor })` | `GET /v1/blog/{workspace}/posts` | One page, newest first, without the text; `nextCursor` for the next page (`limit` 1–50, default 20). |
+| `allPosts({ lang, tag, author })` | the same, page by page | An async iterator over every published post, e.g. for a sitemap. |
+| `getPost(slug, { lang, redirect })` | `GET /v1/blog/{workspace}/posts/{slug}` | One post with `markdown`, `html`, `headings` and `readingMinutes`. |
+| `listTags({ lang })` | `GET /v1/blog/{workspace}/tags` | Every tag with its label and how many published posts carry it. |
+| `listAuthors({ lang })` | `GET /v1/blog/{workspace}/authors` | Every author with their role. |
+| `getPreview(token, { lang })` | `GET /v1/blog/{workspace}/preview?token=` | The current state of a post, drafts too, for your preview route. |
+| `imageUrl(url, width)` | | The image at the next offered width up (320, 640, 960, 1280, 1920). |
+
+`html` is safe to insert as it is: no scripts, links only to web addresses and paths on your site, images only from your blog. Headings carry `id`s for a table of contents. A tag or author key that doesn't exist matches nothing, never everything.
+
+## Example: Next.js App Router
+
+```tsx
+// app/blog/page.tsx
+import { createBlogClient } from "@solutiondesk/blog";
+
+const blog = createBlogClient({ workspace: "acme", lang: "en" });
+
+export default async function BlogPage() {
+  const { posts } = await blog.listPosts({ limit: 20 }, { fetchOptions: { next: { tags: ["blog"] } } });
+  return (
+    <ul>
+      {posts.map((post) => (
+        <li key={post.slug} lang={post.locale}>
+          <a href={`/blog/${post.slug}`}>{post.title}</a> · {post.readingMinutes} min
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+```tsx
+// app/blog/[slug]/page.tsx
+import { createBlogClient, SolutionDeskError } from "@solutiondesk/blog";
+import { notFound, permanentRedirect } from "next/navigation";
+
+const blog = createBlogClient({ workspace: "acme", lang: "en" });
+
+export default async function PostPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  try {
+    const { post, movedFrom } = await blog.getPost(slug, {}, { fetchOptions: { next: { tags: ["blog"] } } });
+    if (movedFrom) permanentRedirect(`/blog/${post.slug}`);
+    return <article lang={post.locale} dangerouslySetInnerHTML={{ __html: post.html }} />;
+  } catch (error) {
+    if (error instanceof SolutionDeskError && error.isNotFound) notFound();
+    throw error;
+  }
+}
+```
+
+Anything that runs on a server works the same way: Astro, Remix, SvelteKit, Nuxt or a plain Node script that renders your site at build time.
+
+## Moved articles
+
+When the team changes an article's address, the old slug answers with a `301` to the new one.
+
+- Default (`redirect: "follow"`): the client follows it and returns the post. `movedFrom` holds the slug you asked for (else `null`) — redirect your page to `post.slug`, as in the example above.
+- `redirect: "manual"`: you get `{ redirectTo: "new-slug" }` instead of the post.
+
+```ts
+const result = await blog.getPost("old-slug", { redirect: "manual" });
+if ("redirectTo" in result) return Response.redirect(`https://www.acme.com/blog/${result.redirectTo}`, 301);
+```
+
+## Languages
+
+Pass `lang` to the client (default for every call) or per call. When an article doesn't exist in that language you get its main language. Every post says which language its text is really in (`locale`) and every language it exists in (`languages`, main language first) — use `locale` for `lang`, `hreflang` and structured data.
+
+```ts
+const { post } = await blog.getPost("hello", { lang: "de" });
+post.locale; // "de", or the main language when there's no German version
+post.languages; // ["en", "de"]
+```
+
+## Images
+
+Image addresses are public and cached for a year. Add a width with `imageUrl(url, width)` to get a WebP at most that wide; the cover has a ready `srcset` and its `width`/`height`. Images inside `html` already come with a `srcset`.
+
+```ts
+// image-loader.ts — Next.js: images.loader "custom", images.loaderFile "./image-loader.ts"
+import { imageUrl } from "@solutiondesk/blog";
+
+export default function solutionDeskLoader({ src, width }: { src: string; width: number }) {
+  return imageUrl(src, width);
+}
+```
+
+## Caching and ETags
+
+Answers are sent with `Cache-Control: public, max-age=60, stale-while-revalidate=600` and an `ETag`. With `etagCache: true` the client remembers each answer's ETag and sends `If-None-Match`; an unchanged answer is a body-less `304` and you get the remembered data back.
+
+```ts
+const blog = createBlogClient({ workspace: "acme", etagCache: true }); // or etagCache: new Map()
+```
+
+Per call, `fetchOptions` is handed to `fetch` unchanged — use it for your framework's caching (Next.js `{ next: { revalidate: 300, tags: ["blog"] } }`) or `{ cache: "no-store" }`. Previews are never cached by the API; in Next.js pass `fetchOptions: { cache: "no-store" }` to `getPreview`.
+
+## Webhooks: refresh when something changes
+
+Under **Blog → Website** set **Tell your website about changes** to a URL on your site and copy the signing secret (shown once). SolutionDesk then `POST`s whenever readers would see something different. Check the `X-SolutionDesk-Signature` header before acting on it:
+
+```ts
+// app/api/solutiondesk/blog/route.ts (Next.js)
+import { parseBlogWebhook } from "@solutiondesk/blog";
+import { revalidatePath, revalidateTag } from "next/cache";
+
+export async function POST(request: Request) {
+  const body = await parseBlogWebhook(
+    process.env.SOLUTIONDESK_BLOG_WEBHOOK_SECRET!,
+    await request.text(), // the raw body, exactly as received
+    request.headers.get("x-solutiondesk-signature"),
+  );
+  if (!body) return new Response("Invalid signature", { status: 401 });
+  if (body.event !== "ping") {
+    revalidateTag("blog");
+    for (const slug of [body.slug, ...body.previousSlugs]) if (slug) revalidatePath(`/blog/${slug}`);
+  }
+  return new Response(null, { status: 204 });
+}
+```
+
+`event` is `post.published`, `post.updated`, `post.unpublished`, `post.deleted` or `ping` (**Send a test**). `parseBlogWebhook` returns `null` for a wrong secret, a changed body, a malformed header or a signature older than five minutes. If you only need the check, use `verifyWebhookSignature(secret, rawBody, header)`, which resolves to `true` or `false`. It uses Web Crypto. On Node 18 pass `{ crypto: require("node:crypto").webcrypto }` as the fourth argument; Node 19 and later need nothing.
+
+Answer with a `2xx` status; anything else is retried a few times.
+
+## Errors
+
+Every failed request rejects with a `SolutionDeskError`:
+
+```ts
+import { SolutionDeskError } from "@solutiondesk/blog";
+
+try {
+  await blog.getPost("nope");
+} catch (error) {
+  if (error instanceof SolutionDeskError) {
+    error.status; // 404 — unknown workspace, blog turned off or unknown post look the same on purpose
+    error.message; // the API's message, e.g. "This blog or article does not exist."
+    error.body; // the parsed error body
+    error.url; // the requested URL
+  }
+}
+```
+
+`status` is `0` when no answer arrived (network error, aborted request). `isNotFound` and `isRateLimited` (`429`) are shortcuts. Each address may be asked 600 times a minute per IP address, the preview 60 times.
+
+## Options
+
+```ts
+createBlogClient({
+  workspace: "acme", // required
+  lang: "en", // default language
+  baseUrl: "https://api.solutiondesk.io", // the API origin
+  fetch: customFetch, // e.g. a fetch with tracing
+  headers: { "x-request-id": "…" }, // sent with every request
+  etagCache: true, // or your own Map
+});
+```
+
+Every method also takes request options as its last argument: `{ signal, headers, fetchOptions }`.
+
+## License
+
+MIT © wemogy GmbH

package/dist/index.cjs

@@ -0,0 +1,355 @@
+'use strict';
+
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// ../sdk-core/src/http.ts
+var DEFAULT_BASE_URL = "https://api.solutiondesk.io";
+var SolutionDeskError = class extends Error {
+  constructor(message, init) {
+    super(message);
+    /** The HTTP status; `0` when no answer arrived (network error, aborted). */
+    __publicField(this, "status");
+    /** The parsed JSON body of the error answer (usually `{ error: string }`), else its text. */
+    __publicField(this, "body");
+    /** The requested URL. */
+    __publicField(this, "url");
+    /** Messages per input field on a `400` (e.g. `{ email: "Enter a valid email address." }`). */
+    __publicField(this, "fields");
+    this.name = "SolutionDeskError";
+    this.status = init.status;
+    this.body = init.body ?? null;
+    this.url = init.url;
+    this.fields = fieldsOf(init.body);
+    if (init.cause !== void 0) {
+      Object.defineProperty(this, "cause", { value: init.cause, enumerable: false });
+    }
+  }
+  /** `404`: unknown workspace, module turned off or unknown item — on purpose indistinguishable. */
+  get isNotFound() {
+    return this.status === 404;
+  }
+  /** `429`: over the rate limit; try again later. */
+  get isRateLimited() {
+    return this.status === 429;
+  }
+};
+function fieldsOf(body) {
+  if (!body || typeof body !== "object") return {};
+  const fields = body.fields;
+  if (!fields || typeof fields !== "object") return {};
+  const out = {};
+  for (const [key, value] of Object.entries(fields)) {
+    if (typeof value === "string") out[key] = value;
+  }
+  return out;
+}
+function messageOf(body, status) {
+  if (body && typeof body === "object") {
+    const { error, message, statusCode } = body;
+    if (typeof statusCode === "number" && typeof message === "string" && message) return message;
+    if (typeof error === "string" && error) return error;
+    if (typeof message === "string" && message) return message;
+    if (Array.isArray(message) && typeof message[0] === "string") return message[0];
+  }
+  if (typeof body === "string" && body.trim() && body.length <= 300) return body.trim();
+  return `SolutionDesk answered ${status}.`;
+}
+function createMemoryEtagCache(maxEntries = 500) {
+  const entries = /* @__PURE__ */ new Map();
+  return {
+    get: (key) => entries.get(key),
+    set(key, value) {
+      entries.delete(key);
+      entries.set(key, value);
+      if (entries.size > maxEntries) {
+        const oldest = entries.keys().next().value;
+        if (oldest !== void 0) entries.delete(oldest);
+      }
+    }
+  };
+}
+function queryString(query) {
+  if (!query) return "";
+  const parts = [];
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0 || value === null || value === "") continue;
+    parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+  }
+  return parts.length ? `?${parts.join("&")}` : "";
+}
+var seg = (value) => encodeURIComponent(String(value));
+function parseBody(text) {
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function createHttp(options = {}) {
+  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "").replace(/\/v1$/, "");
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const cache = options.etagCache === true ? createMemoryEtagCache() : options.etagCache ? options.etagCache : void 0;
+  const url = (path, query) => `${baseUrl}/v1${path}${queryString(query)}`;
+  async function requestWithMeta(req) {
+    if (!fetchImpl) {
+      throw new Error("No global fetch available: pass `fetch` to the client.");
+    }
+    const target = url(req.path, req.query);
+    const headers = {
+      accept: "application/json",
+      ...options.headers,
+      ...req.options?.headers
+    };
+    if (req.body !== void 0) headers["content-type"] = "application/json";
+    if (req.apiKey) headers.authorization = `Bearer ${req.apiKey}`;
+    const cacheKey = req.method === "GET" && !req.apiKey ? target : void 0;
+    const cached = cacheKey && cache ? cache.get(cacheKey) : void 0;
+    if (cached && !Object.keys(headers).some((h) => h.toLowerCase() === "if-none-match")) {
+      headers["if-none-match"] = cached.etag;
+    }
+    const init = {
+      ...req.options?.fetchOptions,
+      method: req.method,
+      headers
+    };
+    if (req.body !== void 0) init.body = JSON.stringify(req.body);
+    if (req.options?.signal !== void 0) init.signal = req.options.signal;
+    let response;
+    try {
+      response = await fetchImpl(target, init);
+    } catch (cause) {
+      const reason = cause instanceof Error ? cause.message : String(cause);
+      throw new SolutionDeskError(`The request to SolutionDesk failed: ${reason}`, {
+        status: 0,
+        url: target,
+        cause
+      });
+    }
+    const finalUrl = response.url;
+    const meta = {
+      status: response.status,
+      finalUrl: typeof finalUrl === "string" && finalUrl ? finalUrl : null
+    };
+    if (response.status === 304 && cached) {
+      return { data: cached.body, ...meta };
+    }
+    const body = parseBody(await response.text());
+    if (!response.ok) {
+      throw new SolutionDeskError(messageOf(body, response.status), {
+        status: response.status,
+        body,
+        url: target
+      });
+    }
+    const etag = response.headers.get("etag");
+    if (cacheKey && cache && etag) cache.set(cacheKey, { etag, body });
+    return { data: body, ...meta };
+  }
+  return {
+    baseUrl,
+    url,
+    requestWithMeta,
+    request: async (req) => (await requestWithMeta(req)).data
+  };
+}
+function required(value, name) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new TypeError(`SolutionDesk: \`${name}\` is required.`);
+  }
+  return value;
+}
+
+// ../sdk-core/src/images.ts
+var IMAGE_WIDTHS = [320, 640, 960, 1280, 1920];
+function imageWidthFor(width) {
+  return IMAGE_WIDTHS.find((w) => w >= width) ?? 1920;
+}
+function imageUrl(url, width) {
+  if (width === void 0) return url;
+  const base = url.replace(/([?&])w=\d+(&|$)/, (_m, sep, end) => end ? sep : "");
+  const join = base.includes("?") ? /[?&]$/.test(base) ? "" : "&" : "?";
+  return `${base}${join}w=${imageWidthFor(width)}`;
+}
+
+// ../sdk-core/src/webhook.ts
+var SIGNATURE_HEADER = "x-solutiondesk-signature";
+var EVENT_HEADER = "x-solutiondesk-event";
+function encoder() {
+  const Encoder = globalThis.TextEncoder;
+  if (!Encoder) throw new Error("TextEncoder is not available in this runtime.");
+  return new Encoder();
+}
+function bytesOf(body) {
+  if (typeof body === "string") return encoder().encode(body);
+  return body instanceof Uint8Array ? body : new Uint8Array(body);
+}
+function webhookBodyText(body) {
+  if (typeof body === "string") return body;
+  const Decoder = globalThis.TextDecoder;
+  if (!Decoder) throw new Error("TextDecoder is not available in this runtime.");
+  return new Decoder().decode(bytesOf(body));
+}
+function hex(buffer) {
+  let out = "";
+  for (const byte of new Uint8Array(buffer)) out += byte.toString(16).padStart(2, "0");
+  return out;
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+function parseHeader(header) {
+  let t = Number.NaN;
+  const signatures = [];
+  for (const part of header.split(",")) {
+    const index = part.indexOf("=");
+    if (index < 0) continue;
+    const key = part.slice(0, index).trim();
+    const value = part.slice(index + 1).trim();
+    if (key === "t" && /^\d{1,12}$/.test(value)) t = Number(value);
+    else if (key === "v1" && /^[0-9a-f]{64}$/i.test(value)) signatures.push(value.toLowerCase());
+  }
+  return Number.isFinite(t) && signatures.length > 0 ? { t, signatures } : null;
+}
+async function verifyWebhookSignature(secret, rawBody, header, options = {}) {
+  if (!secret || !header || header.length > 1e3) return false;
+  const parsed = parseHeader(header);
+  if (!parsed) return false;
+  const now = options.now instanceof Date ? options.now.getTime() : options.now ?? Date.now();
+  const tolerance = options.toleranceSeconds ?? 300;
+  if (Math.abs(now / 1e3 - parsed.t) > tolerance) return false;
+  const subtle = options.crypto?.subtle ?? globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw new Error(
+      "Web Crypto is not available: pass `crypto` (on Node 18: require('node:crypto').webcrypto)."
+    );
+  }
+  const text = encoder();
+  const key = await subtle.importKey(
+    "raw",
+    text.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const prefix = text.encode(`${parsed.t}.`);
+  const body = bytesOf(rawBody);
+  const signed = new Uint8Array(prefix.length + body.length);
+  signed.set(prefix, 0);
+  signed.set(body, prefix.length);
+  const expected = hex(await subtle.sign("HMAC", key, signed));
+  let ok = false;
+  for (const signature of parsed.signatures) ok = constantTimeEqual(expected, signature) || ok;
+  return ok;
+}
+async function parseWebhook(secret, rawBody, header, options = {}) {
+  if (!await verifyWebhookSignature(secret, rawBody, header, options)) return null;
+  try {
+    return JSON.parse(webhookBodyText(rawBody));
+  } catch {
+    return null;
+  }
+}
+
+// src/client.ts
+function createBlogClient(options) {
+  const workspace = required(options.workspace, "workspace");
+  const http = createHttp(options);
+  const base = `/blog/${seg(workspace)}`;
+  const langOf = (params) => params?.lang ?? options.lang;
+  const listPosts = (params = {}, requestOptions) => http.request({
+    method: "GET",
+    path: `${base}/posts`,
+    query: {
+      lang: langOf(params),
+      tag: params.tag,
+      author: params.author,
+      limit: params.limit,
+      cursor: params.cursor
+    },
+    options: requestOptions
+  });
+  const fetchPost = (slug, lang, requestOptions) => http.request({
+    method: "GET",
+    path: `${base}/posts/${seg(slug)}`,
+    query: { lang },
+    options: requestOptions
+  });
+  async function getPost(slug, params = {}, requestOptions) {
+    required(slug, "slug");
+    const lang = langOf(params);
+    const asked = slug.toLowerCase();
+    if (params.redirect === "manual") {
+      try {
+        return await fetchPost(slug, lang, {
+          ...requestOptions,
+          fetchOptions: { ...requestOptions?.fetchOptions, redirect: "manual" }
+        });
+      } catch (error) {
+        if (!(error instanceof SolutionDeskError)) throw error;
+        const redirectTo = error.body?.redirectTo;
+        if (error.status === 301 && typeof redirectTo === "string") return { redirectTo };
+        if (error.status !== 0) throw error;
+      }
+      const payload2 = await fetchPost(slug, lang, requestOptions);
+      return payload2.post.slug !== asked ? { redirectTo: payload2.post.slug } : payload2;
+    }
+    const payload = await fetchPost(slug, lang, requestOptions);
+    return { ...payload, movedFrom: payload.post.slug !== asked ? slug : null };
+  }
+  return {
+    workspace,
+    listPosts,
+    async *allPosts(params = {}, requestOptions) {
+      let cursor = null;
+      do {
+        const page = await listPosts(
+          { ...params, limit: params.limit ?? 50, cursor },
+          requestOptions
+        );
+        yield* page.posts;
+        cursor = page.nextCursor;
+      } while (cursor);
+    },
+    getPost,
+    listTags: async (params, requestOptions) => http.request({
+      method: "GET",
+      path: `${base}/tags`,
+      query: { lang: langOf(params) },
+      options: requestOptions
+    }),
+    listAuthors: async (params, requestOptions) => http.request({
+      method: "GET",
+      path: `${base}/authors`,
+      query: { lang: langOf(params) },
+      options: requestOptions
+    }),
+    getPreview: async (token, params, requestOptions) => http.request({
+      method: "GET",
+      path: `${base}/preview`,
+      query: { token: required(token, "token"), lang: langOf(params) },
+      options: requestOptions
+    }),
+    imageUrl
+  };
+}
+function parseBlogWebhook(secret, rawBody, signatureHeader, options) {
+  return parseWebhook(secret, rawBody, signatureHeader, options);
+}
+
+exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
+exports.EVENT_HEADER = EVENT_HEADER;
+exports.IMAGE_WIDTHS = IMAGE_WIDTHS;
+exports.SIGNATURE_HEADER = SIGNATURE_HEADER;
+exports.SolutionDeskError = SolutionDeskError;
+exports.createBlogClient = createBlogClient;
+exports.createMemoryEtagCache = createMemoryEtagCache;
+exports.imageUrl = imageUrl;
+exports.imageWidthFor = imageWidthFor;
+exports.parseBlogWebhook = parseBlogWebhook;
+exports.verifyWebhookSignature = verifyWebhookSignature;