@solutiondesk/blog 0.0.0-stage → 1.0.0-1cb60bf

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,271 @@
-# 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
+```
+
+The guide [Blog on your website](https://help.solutiondesk.io/docs/team/blog-website) explains the API behind this package and where to set it up in SolutionDesk.
+
+## 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`, `readingMinutes`, `summary`, `faq`, `seo` and the blog's own building blocks it uses (`customBlocks`, `blocks`). |
+| `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.
+
+## Search engines, link previews and answer engines
+
+Every post carries `seo`: what belongs in the page's `<head>`, with the fallbacks already applied — the search title or else the title, the search description or else the description, the link preview image or else the cover.
+
+| Field | Use it for |
+| --- | --- |
+| `seo.title`, `seo.description` | `<title>` and `<meta name="description">` |
+| `seo.canonicalUrl` | `<link rel="canonical">` — the original address the team set, else the post's address on your site |
+| `seo.alternates` | `<link rel="alternate" hreflang>` for every language (when the post address has `{lang}`) |
+| `seo.noindex` | the team asked search engines not to list the post (`robots` is in `meta` too) |
+| `seo.meta` | every meta tag: description, robots, Open Graph (`og:*`, `article:*`) and Twitter cards |
+| `seo.jsonLd` | schema.org structured data: `BlogPosting`, and `FAQPage` when the post has a FAQ |
+
+Canonical links, alternates, `og:url` and the address in the structured data need the post address from **Blog → Website** (e.g. `https://www.example.com/{lang}/blog/{slug}`); every post then also has its `url`. The website's name there becomes `og:site_name` and the publisher.
+
+`renderBlogHead(post)` renders all of it as escaped HTML. With a framework's own head API, map the fields instead:
+
+```tsx
+// app/blog/[slug]/page.tsx (Next.js)
+import { renderBlogJsonLd } from "@solutiondesk/blog";
+
+export async function generateMetadata({ params }) {
+  const { post } = await blog.getPost((await params).slug);
+  return {
+    title: post.seo.title,
+    description: post.seo.description,
+    alternates: {
+      canonical: post.seo.canonicalUrl,
+      languages: Object.fromEntries(post.seo.alternates.map((a) => [a.locale, a.url])),
+    },
+    robots: post.seo.noindex ? { index: false, follow: true } : undefined,
+    openGraph: { images: post.seo.image ? [post.seo.image.url] : [] },
+  };
+}
+
+// in the page component:
+{post.seo.jsonLd.map((data, i) => (
+  <script key={i} type="application/ld+json" dangerouslySetInnerHTML={{ __html: renderBlogJsonLd(data) }} />
+))}
+```
+
+For answer engines (ChatGPT, Perplexity, Google's AI answers) a post can have a `summary` (the key points in a few sentences) and a `faq` (questions and answers). Show them on the page — answer engines quote what readers can see — the FAQ is in `seo.jsonLd` already.
+
+`GET /v1/blog/{workspace}/llms.txt?lang=` lists every published post that search engines may list, as an [llms.txt](https://llmstxt.org) file. Serve it at `/llms.txt` on your site, e.g. with a rewrite to that address.
+
+## Your own building blocks
+
+In SolutionDesk, the blog can define its own building blocks under **Blog → Website**: what a block is called, whether it sits in a sentence, on its own line or around content, and which fields it has — a newsletter box, a product card, an app button. Writers add them to posts from **Block**. How a block looks is up to your website.
+
+In `html`, every such block is a neutral element with its **text version** (set in SolutionDesk, e.g. `Subscribe to Weekly tips`), so a page without your markup still reads well:
+
+| Kind | HTML |
+| --- | --- |
+| in a sentence | `<span class="sd-block" data-block="app-button" data-props="{…}">…</span>` |
+| on its own line | `<div class="sd-block" data-block="newsletter" data-props="{…}">…</div>` |
+| around content | `<div class="sd-block" …><p class="sd-block-text">…</p><div class="sd-block-body">…</div></div>` |
+
+`data-props` holds the block's field values as JSON, already checked the way SolutionDesk checks them: text fields as strings, on/off fields as `true`/`false`; a value that isn't valid (an unsafe address, a picture that isn't from your blog, an option that isn't offered) is left out. `post.customBlocks` names the blocks a post uses, `post.blocks` describes them (name, kind, fields, text version template).
+
+`renderBlogBlocks` swaps them for your own markup, by block name:
+
+```ts
+import { escapeBlogHtml, renderBlogBlocks } from "@solutiondesk/blog";
+
+const html = renderBlogBlocks(post.html, {
+  newsletter: ({ props }) =>
+    `<newsletter-signup list="${escapeBlogHtml(String(props.list ?? ""))}"></newsletter-signup>`,
+  aside: ({ props, childrenHtml }) =>
+    `<aside class="note"><h4>${escapeBlogHtml(String(props.title ?? ""))}</h4>${childrenHtml}</aside>`,
+});
+```
+
+Your renderer gets `block` (the name), `props`, `inline`, `textHtml` (the text version) and, for a block around content, `childrenHtml` (that content, with blocks inside already rendered). Return `undefined` to keep the neutral element. Values in `props` are raw text — escape them with `escapeBlogHtml` before putting them into HTML. A block without a renderer keeps its text version. With React, you can also hydrate your own components from `data-block` and `data-props` with an HTML parser of your choice.
+
+## 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