@intelex-ia/sdk 0.6.1 → 0.7.0

package/README.md

@@ -1,310 +1,406 @@
-# `@intelex-ia/sdk`
-
-SDK pra consumir a **Content API IntelexIA** em sites headless (Next.js, Astro etc.). Multiplataforma Fase 2b.
-
-> **O que você ganha:** `getArticles` / `getArticleBySlug` tipados, `mergePosts()` pra unir conteúdo antigo + novo do painel, `<ArticleJsonLd>` pra injetar schema JSON-LD, e `articleToMetadata` pra plugar no `generateMetadata` do Next.js App Router. Zero dependências (usa `fetch` global).
-
-## Instalação rápida (recomendado)
-
-Se você está começando agora, use o CLI — ele detecta a estrutura do seu projeto e configura tudo automaticamente:
-
-```bash
-npx @intelex-ia/cli init
-```
-
-Cria os arquivos no lugar certo (App Router ou Pages Router, com ou sem `src/`), configura `.env.local`, gera um `INTELEXIA.md` completo na raiz e instala o SDK pra você.
-
-## Instalação manual
-
-```bash
-npm install @intelex-ia/sdk
-# ou pnpm add @intelex-ia/sdk / yarn add @intelex-ia/sdk
-```
-
-## Configuração
-
-1. No painel da IntelexIA, **cadastre o site como "Headless (código)"** (vai pedir domain + URL e secret de revalidate).
-2. Abra o site na lista → seção **"Tokens de API (Content API)"** → **Gerar token**. Você recebe `itx_…` (mostrado uma única vez).
-3. Coloque em `.env.local`:
-
-```bash
-INTELEXIA_API_TOKEN=itx_seu_token_aqui
-INTELEXIA_API_URL=https://api.innovarticles.intelexia.com.br  # opcional, é o default
-INTELEXIA_REVALIDATE_SECRET=cole-o-mesmo-segredo-do-painel
-```
-
-## Três modos de integração
-
-Cada cliente tem uma situação diferente. Escolha o modo que faz sentido:
-
-| Modo | Quando usar | O que muda no `/blog` |
-|---|---|---|
-| **🔀 Additive (recomendado)** | Cliente já tem posts antigos e quer **adicionar** os do painel sem perder os antigos | `mergePosts()` une os dois feeds, dedupa por slug, ordena por data |
-| **🔁 Replace** | Cliente migrou tudo pro painel — só os novos contam | Substitui `getAllPosts()` por `client.getArticles()` |
-| **🆕 Isolated** | Cliente quer manter `/blog` antigo intacto e criar rota nova só pra IA | Cria `/blog/ia` separado, blog antigo zero alterado |
-
----
-
-### Modo 1: Additive (cliente existente — caso mais comum)
-
-```tsx
-// app/blog/page.tsx
-import { intelexia } from "@/lib/intelexia";
-import { mergePosts } from "@intelex-ia/sdk";
-import { posts as localPosts } from "@/lib/posts"; // seu array atual
-import Link from "next/link";
-
-export default async function BlogIndex() {
-  // 1) Busca os artigos do painel
-  const { items: remote } = await intelexia.getArticles({ limit: 50 });
-
-  // 2) Mistura com os seus posts antigos
-  const all = mergePosts({
-    local: localPosts,
-    remote,
-    mapLocal: (p) => ({
-      slug: p.slug,
-      title: p.title,
-      excerpt: p.excerpt,
-      publishedAt: p.date,
-      featuredImageUrl: null,
-      category: p.category,
-    }),
-    // Opcional — defaults sensatos:
-    // dedupe: "remote-wins"  (painel substitui local se slug colide)
-    // sortBy: "date-desc"    (mais recente primeiro)
-  });
-
-  return (
-    <ul>
-      {all.map((p) => (
-        <li key={p.slug}>
-          <Link href={`/blog/${p.slug}`}>{p.title}</Link>
-          <time>{new Date(p.publishedAt).toLocaleDateString("pt-BR")}</time>
-          {p.source === "remote" && <span className="badge-ia">✨ IA</span>}
-        </li>
-      ))}
-    </ul>
-  );
-}
-```
-
-Pro post individual, tenta o painel primeiro, cai pro local se 404:
-
-```tsx
-// app/blog/[slug]/page.tsx
-import { intelexia } from "@/lib/intelexia";
-import { IntelexiaApiError } from "@intelex-ia/sdk";
-import { ArticleJsonLd, articleToMetadata } from "@intelex-ia/sdk/react";
-import { getPostBySlug } from "@/lib/posts";
-import { notFound } from "next/navigation";
-
-export default async function PostPage({ params }: { params: Promise<{ slug: string }> }) {
-  const { slug } = await params;
-
-  // 1) Tenta painel
-  try {
-    const { article } = await intelexia.getArticleBySlug(slug);
-    return (
-      <article>
-        <ArticleJsonLd article={article} />
-        <h1>{article.title}</h1>
-        <div dangerouslySetInnerHTML={{ __html: article.contentHtml ?? "" }} />
-      </article>
-    );
-  } catch (err) {
-    if (!(err instanceof IntelexiaApiError) || err.status !== 404) throw err;
-  }
-
-  // 2) Fallback: post antigo local
-  const local = getPostBySlug(slug);
-  if (!local) notFound();
-  return (
-    <article>
-      <h1>{local.title}</h1>
-      {/* renderiza o local do jeito que você já fazia */}
-    </article>
-  );
-}
-```
-
-### Modo 2: Replace (migração completa)
-
-```tsx
-// app/blog/page.tsx
-import { intelexia } from "@/lib/intelexia";
-
-export default async function BlogIndex() {
-  const { items } = await intelexia.getArticles({ limit: 20 });
-  return (
-    <ul>
-      {items.map((a) => (
-        <li key={a.id}>
-          <Link href={`/blog/${a.slug}`}>{a.title}</Link>
-        </li>
-      ))}
-    </ul>
-  );
-}
-```
-
-Pro post individual, sem fallback:
-
-```tsx
-import { intelexia } from "@/lib/intelexia";
-import { IntelexiaApiError } from "@intelex-ia/sdk";
-import { ArticleJsonLd, articleToMetadata } from "@intelex-ia/sdk/react";
-import { notFound } from "next/navigation";
-
-async function fetchArticle(slug: string) {
-  try {
-    return await intelexia.getArticleBySlug(slug);
-  } catch (err) {
-    if (err instanceof IntelexiaApiError && err.status === 404) notFound();
-    throw err;
-  }
-}
-
-export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
-  const { slug } = await params;
-  const { article } = await fetchArticle(slug);
-  return articleToMetadata(article);
-}
-
-export default async function PostPage({ params }: { params: Promise<{ slug: string }> }) {
-  const { slug } = await params;
-  const { article } = await fetchArticle(slug);
-  return (
-    <article>
-      <ArticleJsonLd article={article} />
-      <h1>{article.title}</h1>
-      <div dangerouslySetInnerHTML={{ __html: article.contentHtml ?? "" }} />
-    </article>
-  );
-}
-```
-
-### Modo 3: Isolated (rota nova, blog antigo intacto)
-
-Cria `app/blog/ia/page.tsx` e `app/blog/ia/[slug]/page.tsx` com o mesmo código do modo Replace, mas em rota separada (`/blog/ia` em vez de `/blog`). Zero alteração no blog existente.
-
----
-
-## Cliente — `lib/intelexia.ts`
-
-```ts
-import { createClient } from "@intelex-ia/sdk";
-
-export const intelexia = createClient({
-  token: process.env.INTELEXIA_API_TOKEN!,
-  // ISR: revalida a cada 60s; o webhook revalidate invalida sob demanda
-  init: { next: { revalidate: 60, tags: ["intelexia-articles"] } },
-});
-```
-
-## Webhook de revalidate — `app/api/revalidate/route.ts`
-
-Quando um artigo publica/edita no painel, nosso worker faz `POST` no seu endpoint. Implemente assim:
-
-```ts
-import { NextResponse } from "next/server";
-import { revalidatePath, revalidateTag } from "next/cache";
-
-export async function POST(req: Request) {
-  const headerSecret = req.headers.get("x-revalidate-secret");
-  const body = (await req.json().catch(() => ({}))) as {
-    secret?: string;
-    slug?: string | null;
-    domain?: string;
-  };
-  const got = headerSecret ?? body.secret ?? "";
-  if (!process.env.INTELEXIA_REVALIDATE_SECRET || got !== process.env.INTELEXIA_REVALIDATE_SECRET) {
-    return NextResponse.json({ ok: false, error: "unauthorized" }, { status: 401 });
-  }
-
-  if (body.slug) revalidatePath(`/blog/${body.slug}`);
-  revalidatePath("/blog");
-  revalidateTag("intelexia-articles");
-
-  return NextResponse.json({ ok: true, revalidated: { slug: body.slug ?? null } });
-}
-```
-
-> O worker envia o secret tanto no header `x-revalidate-secret` quanto no body, tem timeout de 15s e é **fire-and-forget** (se seu endpoint falhar, o artigo continua publicado e a ISR atualiza pelo `revalidate: 60`).
-
-## API
-
-### `createClient(config)`
-
-| Opção    | Tipo                 | Default                                           |
-| -------- | -------------------- | ------------------------------------------------- |
-| `token`  | `string` (obrig.)    | —                                                 |
-| `apiUrl` | `string`             | `https://api.innovarticles.intelexia.com.br`      |
-| `fetch`  | `typeof fetch`       | `globalThis.fetch`                                |
-| `init`   | `RequestInit`        | `undefined` (passe `{ next: { revalidate: N } }`) |
-
-### `client.getArticles({ limit?, offset?, init? })`
-
-Resposta: `{ ok, mode, lifecycle, count, items: ArticleListItem[] }`.
-
-### `client.getArticleBySlug(slug, { init? })`
-
-Resposta: `{ ok, mode, lifecycle, article: Article }`. **404 → joga `IntelexiaApiError`** (use `try/catch` + `notFound()`).
-
-### `mergePosts({ local, remote, mapLocal, dedupe?, sortBy? })` 🆕 0.2.0
-
-| Opção      | Tipo                                              | Default          |
-| ---------- | ------------------------------------------------- | ---------------- |
-| `local`    | `readonly TLocal[]` (qualquer shape)              | —                |
-| `remote`   | `readonly ArticleListItem[]`                      | —                |
-| `mapLocal` | `(post: TLocal) => Omit<UnifiedPost,"source"> \| null` | —          |
-| `dedupe`   | `"remote-wins" \| "local-wins" \| "throw"`       | `"remote-wins"`  |
-| `sortBy`   | `"date-desc" \| "date-asc" \| "none"`             | `"date-desc"`    |
-
-Retorna `UnifiedPost[]` com `source: "local" | "remote"`. `mapLocal` retornando `null` filtra o post (útil pra esconder rascunhos). Slugs duplicados resolvidos pela estratégia `dedupe`. Veja exemplo no Modo Additive acima.
-
-### `mode: "full" | "plain"`
-
-- **`full`** (sites `active`/`paused`): inclui schema JSON-LD, metaTitle/Description, keyword(s), interlinking interno no `contentHtml`.
-- **`plain`** (site `cancelled`): só conteúdo cru — schema/meta/keywords vêm `null`, interlinking removido. O `ArticleJsonLd` e o `articleToMetadata` lidam graciosamente (omitem o que não tem).
-
-A decisão é **server-side e não-negociável** — o cliente não escolhe o modo.
-
-### Helpers `/react`
-
-- `<ArticleJsonLd article={article} />` — renderiza `<script type="application/ld+json">` com o `schemaJson`. No-op se ausente.
-- `articleToMetadata(article)` → objeto compatível com o `Metadata` do Next.js App Router (title, description, keywords, openGraph, twitter, customMetaTags como `other`).
-
-## Erros
-
-```ts
-import { IntelexiaApiError, MergeConflictError } from "@intelex-ia/sdk";
-
-try {
-  await intelexia.getArticleBySlug("post-inexistente");
-} catch (err) {
-  if (err instanceof IntelexiaApiError) {
-    console.error(err.status, err.message); // 404, "Artigo não encontrado."
-  }
-}
-
-try {
-  mergePosts({ local, remote, mapLocal, dedupe: "throw" });
-} catch (err) {
-  if (err instanceof MergeConflictError) {
-    console.error(`Conflito de slug: ${err.slug}`);
-  }
-}
-```
-
-## Compatibilidade
-
-- **Node** 18+ (fetch nativo), Edge Runtime, Browser.
-- **React** 18+ (peer dep opcional — só pros helpers `/react`).
-- **TypeScript:** tipos publicados no `dist`.
-- **Frameworks:** Next.js (App Router e Pages Router), Astro, Remix, SvelteKit, Vite, qualquer JS.
-
-## Changelog
-
-- **0.2.0** — adiciona `mergePosts()` + tipo `UnifiedPost` + `MergeConflictError` (3 modos de integração).
-- **0.1.0** — release inicial: `createClient`, `getArticles`, `getArticleBySlug`, `<ArticleJsonLd>`, `articleToMetadata`.
+# `@intelex-ia/sdk`
+
+SDK pra consumir a **Content API IntelexIA** em sites headless (Next.js, Astro etc.). Multiplataforma Fase 2b.
+
+> **O que você ganha:** `getArticles` / `getArticleBySlug` tipados, `mergePosts()` pra unir conteúdo antigo + novo do painel, `<ArticleJsonLd>` pra injetar schema JSON-LD, e `articleToMetadata` pra plugar no `generateMetadata` do Next.js App Router. Zero dependências (usa `fetch` global).
+
+## Instalação rápida (recomendado)
+
+Se você está começando agora, use o CLI — ele detecta a estrutura do seu projeto e configura tudo automaticamente:
+
+```bash
+npx @intelex-ia/cli init
+```
+
+Cria os arquivos no lugar certo (App Router ou Pages Router, com ou sem `src/`), configura `.env.local`, gera um `INTELEXIA.md` completo na raiz e instala o SDK pra você.
+
+## Instalação manual
+
+```bash
+npm install @intelex-ia/sdk
+# ou pnpm add @intelex-ia/sdk / yarn add @intelex-ia/sdk
+```
+
+## Configuração
+
+1. No painel da IntelexIA, **cadastre o site como "Headless (código)"** (vai pedir domain + URL e secret de revalidate).
+2. Abra o site na lista → seção **"Tokens de API (Content API)"** → **Gerar token**. Você recebe `itx_…` (mostrado uma única vez).
+3. Coloque em `.env.local`:
+
+```bash
+INTELEXIA_API_TOKEN=itx_seu_token_aqui
+INTELEXIA_API_URL=https://api.innovarticles.intelexia.com.br  # opcional, é o default
+INTELEXIA_REVALIDATE_SECRET=cole-o-mesmo-segredo-do-painel
+```
+
+## Três modos de integração
+
+Cada cliente tem uma situação diferente. Escolha o modo que faz sentido:
+
+| Modo | Quando usar | O que muda no `/blog` |
+|---|---|---|
+| **🔀 Additive (recomendado)** | Cliente já tem posts antigos e quer **adicionar** os do painel sem perder os antigos | `mergePosts()` une os dois feeds, dedupa por slug, ordena por data |
+| **🔁 Replace** | Cliente migrou tudo pro painel — só os novos contam | Substitui `getAllPosts()` por `client.getArticles()` |
+| **🆕 Isolated** | Cliente quer manter `/blog` antigo intacto e criar rota nova só pra IA | Cria `/blog/ia` separado, blog antigo zero alterado |
+
+---
+
+### Modo 1: Additive (cliente existente — caso mais comum)
+
+```tsx
+// app/blog/page.tsx
+import { intelexia } from "@/lib/intelexia";
+import { mergePosts } from "@intelex-ia/sdk";
+import { posts as localPosts } from "@/lib/posts"; // seu array atual
+import Link from "next/link";
+
+export default async function BlogIndex() {
+  // 1) Busca os artigos do painel
+  const { items: remote } = await intelexia.getArticles({ limit: 50 });
+
+  // 2) Mistura com os seus posts antigos
+  const all = mergePosts({
+    local: localPosts,
+    remote,
+    mapLocal: (p) => ({
+      slug: p.slug,
+      title: p.title,
+      excerpt: p.excerpt,
+      publishedAt: p.date,
+      featuredImageUrl: null,
+      category: p.category,
+    }),
+    // Opcional — defaults sensatos:
+    // dedupe: "remote-wins"  (painel substitui local se slug colide)
+    // sortBy: "date-desc"    (mais recente primeiro)
+  });
+
+  return (
+    <ul>
+      {all.map((p) => (
+        <li key={p.slug}>
+          <Link href={`/blog/${p.slug}`}>{p.title}</Link>
+          <time>{new Date(p.publishedAt).toLocaleDateString("pt-BR")}</time>
+          {p.source === "remote" && <span className="badge-ia">✨ IA</span>}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Pro post individual, tenta o painel primeiro, cai pro local se 404:
+
+```tsx
+// app/blog/[slug]/page.tsx
+import { intelexia } from "@/lib/intelexia";
+import { IntelexiaApiError } from "@intelex-ia/sdk";
+import { ArticleJsonLd, ArticleBody, AuthorBar, AuthorSignature, articleToMetadata } from "@intelex-ia/sdk/react";
+import { getPostBySlug } from "@/lib/posts";
+import { notFound } from "next/navigation";
+
+export default async function PostPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+
+  // 1) Tenta painel
+  try {
+    const { article } = await intelexia.getArticleBySlug(slug);
+    return (
+      <article>
+        <ArticleJsonLd article={article} />
+        <h1>{article.title}</h1>
+        <AuthorBar article={article} empresa="Acme" />
+        <ArticleBody article={article} />
+        <AuthorSignature article={article} empresa="Acme" />
+      </article>
+    );
+  } catch (err) {
+    if (!(err instanceof IntelexiaApiError) || err.status !== 404) throw err;
+  }
+
+  // 2) Fallback: post antigo local
+  const local = getPostBySlug(slug);
+  if (!local) notFound();
+  return (
+    <article>
+      <h1>{local.title}</h1>
+      {/* renderiza o local do jeito que você já fazia */}
+    </article>
+  );
+}
+```
+
+### Modo 2: Replace (migração completa)
+
+```tsx
+// app/blog/page.tsx
+import { intelexia } from "@/lib/intelexia";
+
+export default async function BlogIndex() {
+  const { items } = await intelexia.getArticles({ limit: 20 });
+  return (
+    <ul>
+      {items.map((a) => (
+        <li key={a.id}>
+          <Link href={`/blog/${a.slug}`}>{a.title}</Link>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Pro post individual, sem fallback:
+
+```tsx
+import { intelexia } from "@/lib/intelexia";
+import { IntelexiaApiError } from "@intelex-ia/sdk";
+import { ArticleJsonLd, ArticleBody, AuthorBar, AuthorSignature, articleToMetadata } from "@intelex-ia/sdk/react";
+import { notFound } from "next/navigation";
+
+async function fetchArticle(slug: string) {
+  try {
+    return await intelexia.getArticleBySlug(slug);
+  } catch (err) {
+    if (err instanceof IntelexiaApiError && err.status === 404) notFound();
+    throw err;
+  }
+}
+
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const { article } = await fetchArticle(slug);
+  return articleToMetadata(article);
+}
+
+export default async function PostPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const { article } = await fetchArticle(slug);
+  return (
+    <article>
+      <ArticleJsonLd article={article} />
+      <h1>{article.title}</h1>
+      <AuthorBar article={article} empresa="Acme" />
+      <ArticleBody article={article} />
+      <AuthorSignature article={article} empresa="Acme" />
+    </article>
+  );
+}
+```
+
+### Modo 3: Isolated (rota nova, blog antigo intacto)
+
+Cria `app/blog/ia/page.tsx` e `app/blog/ia/[slug]/page.tsx` com o mesmo código do modo Replace, mas em rota separada (`/blog/ia` em vez de `/blog`). Zero alteração no blog existente.
+
+---
+
+## Cliente — `lib/intelexia.ts`
+
+```ts
+import { createClient } from "@intelex-ia/sdk";
+
+export const intelexia = createClient({
+  token: process.env.INTELEXIA_API_TOKEN!,
+  // ISR: revalida a cada 60s; o webhook revalidate invalida sob demanda
+  init: { next: { revalidate: 60, tags: ["intelexia-articles"] } },
+});
+```
+
+## Webhook de revalidate — `app/api/revalidate/route.ts`
+
+Quando um artigo publica/edita no painel, nosso worker faz `POST` no seu endpoint. Implemente assim:
+
+```ts
+import { NextResponse } from "next/server";
+import { revalidatePath, revalidateTag } from "next/cache";
+
+export async function POST(req: Request) {
+  const headerSecret = req.headers.get("x-revalidate-secret");
+  const body = (await req.json().catch(() => ({}))) as {
+    secret?: string;
+    slug?: string | null;
+    domain?: string;
+  };
+  const got = headerSecret ?? body.secret ?? "";
+  if (!process.env.INTELEXIA_REVALIDATE_SECRET || got !== process.env.INTELEXIA_REVALIDATE_SECRET) {
+    return NextResponse.json({ ok: false, error: "unauthorized" }, { status: 401 });
+  }
+
+  if (body.slug) revalidatePath(`/blog/${body.slug}`);
+  revalidatePath("/blog");
+  revalidateTag("intelexia-articles");
+
+  return NextResponse.json({ ok: true, revalidated: { slug: body.slug ?? null } });
+}
+```
+
+> O worker envia o secret tanto no header `x-revalidate-secret` quanto no body, tem timeout de 15s e é **fire-and-forget** (se seu endpoint falhar, o artigo continua publicado e a ISR atualiza pelo `revalidate: 60`).
+
+## API
+
+### `createClient(config)`
+
+| Opção    | Tipo                 | Default                                           |
+| -------- | -------------------- | ------------------------------------------------- |
+| `token`  | `string` (obrig.)    | —                                                 |
+| `apiUrl` | `string`             | `https://api.innovarticles.intelexia.com.br`      |
+| `fetch`  | `typeof fetch`       | `globalThis.fetch`                                |
+| `init`   | `RequestInit`        | `undefined` (passe `{ next: { revalidate: N } }`) |
+
+### `client.getArticles({ limit?, offset?, init? })`
+
+Resposta: `{ ok, mode, lifecycle, count, items: ArticleListItem[] }`.
+
+### `client.getArticleBySlug(slug, { init? })`
+
+Resposta: `{ ok, mode, lifecycle, article: Article }`. **404 → joga `IntelexiaApiError`** (use `try/catch` + `notFound()`).
+
+### `mergePosts({ local, remote, mapLocal, dedupe?, sortBy? })` 🆕 0.2.0
+
+| Opção      | Tipo                                              | Default          |
+| ---------- | ------------------------------------------------- | ---------------- |
+| `local`    | `readonly TLocal[]` (qualquer shape)              | —                |
+| `remote`   | `readonly ArticleListItem[]`                      | —                |
+| `mapLocal` | `(post: TLocal) => Omit<UnifiedPost,"source"> \| null` | —          |
+| `dedupe`   | `"remote-wins" \| "local-wins" \| "throw"`       | `"remote-wins"`  |
+| `sortBy`   | `"date-desc" \| "date-asc" \| "none"`             | `"date-desc"`    |
+
+Retorna `UnifiedPost[]` com `source: "local" | "remote"`. `mapLocal` retornando `null` filtra o post (útil pra esconder rascunhos). Slugs duplicados resolvidos pela estratégia `dedupe`. Veja exemplo no Modo Additive acima.
+
+### `mode: "full" | "plain"`
+
+- **`full`** (sites `active`/`paused`): inclui schema JSON-LD, metaTitle/Description, keyword(s), interlinking interno no `contentHtml`.
+- **`plain`** (site `cancelled`): só conteúdo cru — schema/meta/keywords vêm `null`, interlinking removido. O `ArticleJsonLd` e o `articleToMetadata` lidam graciosamente (omitem o que não tem).
+
+A decisão é **server-side e não-negociável** — o cliente não escolhe o modo.
+
+### Helpers `/react`
+
+- `<ArticleJsonLd article={article} />`: renderiza `<script type="application/ld+json">` com o `schemaJson`. No-op se ausente.
+- `inteligenciaDoArtigo(article)`: a camada de SEO do artigo, venha **aninhada** em `article.intelligence` (o que a Content API manda em `full`) ou na raiz (payload antigo). É a regra única que o `ArticleJsonLd`, o `articleToMetadata` e o `autoriaDoArtigo` usam.
+
+> 🚨 **Se você lê a inteligência à mão, leia pelo helper.** Até a 0.6.0 o
+> `ArticleJsonLd` e o `articleToMetadata` liam `article.schemaJson` e
+> `article.metaDescription` da RAIZ, onde a Content API não entrega nada no modo
+> `full`. O efeito, medido no ar em 26/10/2026: página com **zero** blocos
+> `application/ld+json` e **sem** meta description. Nada quebrava e nada
+> aparecia no console. Desde a 0.7.0 os três helpers leem pelo
+> `inteligenciaDoArtigo()`, com queda para a raiz.
+- `articleToMetadata(article)`: objeto compatível com o `Metadata` do Next.js App Router (title, description, keywords, openGraph, twitter, customMetaTags como `other`).
+- `<ArticleBody article={article} />`: o corpo do artigo, vestido. **Use este em vez de injetar o `contentHtml` numa div.**
+- `<AuthorBar article={article} empresa="Acme" />`: a barra de autoria, logo abaixo do `<h1>`.
+- `<AuthorSignature article={article} empresa="Acme" />`: a assinatura do fim do artigo, com o selo de apoio de IA.
+
+#### Por que não injetar o `contentHtml` numa div
+
+O corpo chega como HTML semântico **pelado**: `<h2>`, `<ul>`, `<table>`, sem
+classe. No WordPress funciona, porque o tema veste por tag. Num site Tailwind
+não: o `@tailwind base` zera `list-style`, zera tamanho e peso dos seis títulos
+e deixa a tabela sem borda. Medido no preflight 3.4 real, sem folha por cima, o
+`<h2>` sai a 16px peso 400 e a lista sem marcador. Isso não é "sem estilo", é
+pior que sem estilo, e foi o que manteve o blog de um cliente como parede de
+texto por semanas.
+
+O `<ArticleBody>` faz três coisas que ninguém precisa repetir:
+
+1. injeta a folha estrutural, escopada na classe `ia-artigo`, que ele mesmo põe
+   na div. O que você passar em `className` entra **ao lado** do gancho, nunca
+   no lugar dele;
+2. devolve o que o preflight tira, com especificidade de 0,0,1 nas regras que
+   disputam com o reset e 0,0,0 no resto. Regra sua escrita por classe
+   (`.meu-blog h2`) ganha da nossa, sempre;
+3. remove a assinatura que o motor embute no `contentHtml`, para ela não sair
+   duas vezes quando a página usa `<AuthorSignature>`. Por isso os dois andam
+   juntos: `<ArticleBody>` sozinho deixa a página sem autor;
+4. embrulha cada `<table>` num `<div class="tabela-rolante">`. O navegador
+   ignora `overflow-x` em caixa de tabela, então sem o contêiner a tabela larga
+   faz a **página inteira** rolar de lado no celular: medido a 375px, 494
+   contra 375. O embrulho é idempotente e só sai com a folha, porque é ela que
+   traz a regra do contêiner.
+
+`comFolha={false}` dispensa a folha. É obrigatório em **Tailwind v4 cujo corpo
+já é vestido pelo `@tailwindcss/typography` instalado**, ou por utilitário no
+wrapper: ali o site emite tudo dentro de `@layer`, camada é decidida antes de
+especificidade, e a nossa folha, que fica fora de camada, ganharia de quem fez
+certo. Em Tailwind v3 não existe esse caso.
+
+A folha também pode ser importada solta, em `CSS_CORPO_DO_ARTIGO`, com a classe
+em `CLASSE_DO_CORPO`.
+
+#### A folha lê a marca do site, sem configuração
+
+As cores e a fonte de título saem de variável, e a variável LÊ o token que o
+site já tem, com queda para o que a folha fazia antes:
+
+| Variável da folha | Token do site | Queda |
+|---|---|---|
+| `--ia-cor-titulo` | `--primary` | `inherit` |
+| `--ia-cor-destaque` | `--accent` | `currentColor` |
+| `--ia-cor-borda` | `--border` | `currentColor` |
+| `--ia-fonte-titulo` | nenhum | `inherit` |
+
+Site que declara o token como **trio de HSL** (`--primary: 222 47% 11%`, o
+jeito do shadcn) cai na queda e fica igual a antes, nunca pior. Medido nos três
+casos em 26/10/2026, com o preflight 3.4.19 real: sem token, o `h2` herda a cor
+do corpo; com `#003366`, sai `#003366`; com o trio, herda de novo, e a borda da
+tabela segue em 1px.
+
+Para discordar, redeclare a variável na sua folha, sem tocar no pacote:
+
+```css
+.meu-blog .ia-artigo { --ia-cor-titulo: #003366; --ia-fonte-titulo: "Fraunces", serif; }
+```
+
+A FAQ em `<details>` sai em acordeão, com o marcador do navegador escondido,
+triângulo próprio e giro no estado aberto.
+
+#### Site preso numa versão antiga do SDK
+
+Se o site ainda não pode subir para a 0.7.0, `folhaParaSite()` devolve a MESMA
+folha reescrita para o CSS do próprio site, numa classe dele:
+
+```ts
+import { folhaParaSite } from "@intelex-ia/sdk/react";
+console.log(folhaParaSite([".meu-artigo"]));       // cole no globals.css
+console.log(folhaParaSite([".a", ".b"]));          // duas classes de uma vez
+```
+
+O seletor sai por classe, `0,1,1`, então ganha do reset de tipo em qualquer
+versão do Tailwind, com ou sem camada. E quando o site migrar para o
+`<ArticleBody>` nada conflita: `0,1,1` continua ganhando do `0,0,1` do SDK, ou
+seja a folha do site continua mandando no que ela já decidia.
+
+## Erros
+
+```ts
+import { IntelexiaApiError, MergeConflictError } from "@intelex-ia/sdk";
+
+try {
+  await intelexia.getArticleBySlug("post-inexistente");
+} catch (err) {
+  if (err instanceof IntelexiaApiError) {
+    console.error(err.status, err.message); // 404, "Artigo não encontrado."
+  }
+}
+
+try {
+  mergePosts({ local, remote, mapLocal, dedupe: "throw" });
+} catch (err) {
+  if (err instanceof MergeConflictError) {
+    console.error(`Conflito de slug: ${err.slug}`);
+  }
+}
+```
+
+## Compatibilidade
+
+- **Node** 18+ (fetch nativo), Edge Runtime, Browser.
+- **React** 18+ (peer dep opcional — só pros helpers `/react`).
+- **TypeScript:** tipos publicados no `dist`.
+- **Frameworks:** Next.js (App Router e Pages Router), Astro, Remix, SvelteKit, Vite, qualquer JS.
+
+## Changelog
+
+- **0.7.0**: adiciona `<ArticleBody>`, `<AuthorBar>`, `<AuthorSignature>`, `CSS_CORPO_DO_ARTIGO`, `CLASSE_DO_CORPO`, `envolverTabelas` e `folhaParaSite`. O corpo do artigo passa a sair vestido, sem depender de o site lembrar de uma folha. A data da barra passa a sair no fuso de Brasília, e não no do servidor.
+- **0.2.0** — adiciona `mergePosts()` + tipo `UnifiedPost` + `MergeConflictError` (3 modos de integração).
+- **0.1.0** — release inicial: `createClient`, `getArticles`, `getArticleBySlug`, `<ArticleJsonLd>`, `articleToMetadata`.