Knowledge base (direct)

• Use it for: Public website · Server integration
• Reads: public token — works in the browser
• Writes: Bearer (apiKey) — server-side only
• CLI: uidu kb-collections, uidu kb-articles
• Auth: what each token can do and where it may run — Authentication

The knowledge base is the content behind the Help Center: collections of articles. The functions on this page read and write them at the workspace level, with no channel in between — use them to list every collection across channels, to fetch an article without knowing its collection, or to go past the 100-per-level cap of getChannel.

Mental model

Workspace
├── KbCollection     { id, name, description, iconData, position, createdAt, updatedAt }
│   └── KbArticle    { id, name, body, position, isDraft, createdAt, updatedAt, kbCollection { id, name } }
└── Channel          a help center: shows some collections, in its own order (see Help Center)

• Lists are flat arrays, one Relay page at a time: listKbCollections and listKbArticles take first/after (or last/before). For all of them, paginate with ListKbCollectionsDocument or ListKbArticlesDocument — see Pagination.
• listKbArticles spans every collection and returns summaries — name, position, isDraft, kbCollection { id, name }, timestamps — without body. Only getKbArticle returns the body.
• getKbCollection embeds its first 50 articles (id, name, position, isDraft, updatedAt) with their pageInfo, ordered by position. A bigger collection needs listKbArticles, filtered on kbCollection.id.
• Drafts are left out of the article lists server-side, so isDraft is false on everything a list returns.
• Field shapes. A collection's name and description are JSON — often a string, possibly a localization map like { en, it }; iconData is JSON. An article's name is a string when you read it; its body is Tiptap JSON, rendered with <RichText>.
• Writes need the Bearer client. createKbCollection returns the new collection at kbCollection.node; createKbArticle creates the article in attributes.kbCollectionId and returns it at kbArticle.node. update* take { input: { id, attributes } }, delete* { input: { id } }. Validation failures come back in errors, not as a throw: Writes. Collection attributes: name, description, iconData, position. Article attributes: name, body, isDraft, kbCollectionId, position, workspaceTagIds.

For a ready-made help center (channel → collections → articles in one request), use getChannel; reach for these functions when you don't want channel scoping.

Use cases

Cross-channel article index

Goal: one page listing every published article in the workspace, grouped by collection.

// src/app/kb/page.tsx
import Link from 'next/link';
import {
  ListKbArticlesDocument,
  listKbCollections,
  paginate,
} from '@uidu/client';
import { uidu } from '@/lib/uidu';

export default async function KbIndexPage() {
  const [collections, articles] = await Promise.all([
    listKbCollections(uidu, { first: 100 }),
    paginate(uidu, ListKbArticlesDocument, {
      variables: { first: 100 },
      extract: (data) => data.currentWorkspace?.kbArticles,
    }),
  ]);

  return collections
    .sort((a, b) => a.position - b.position)
    .map((c) => (
      <section key={c.id}>
        <h2>{typeof c.name === 'string' ? c.name : c.name?.en}</h2>
        <ul>
          {articles
            .filter((a) => a.kbCollection?.id === c.id)
            .sort((a, b) => a.position - b.position)
            .map((a) => (
              <li key={a.id}>
                <Link href={`/kb/article/${encodeURIComponent(a.id)}`}>{a.name}</Link>
              </li>
            ))}
        </ul>
      </section>
    ));
}

• paginate walks every page of articles; listKbArticles(uidu, { first: 100 }) would stop at the first 100.
• The article page is getKbArticle(uidu, { id }) + <RichText doc={article.body} /> — the same route as the Help Center article page.

Sync articles from your own docs

Goal: a server job that creates an article in a collection, then publishes it once its body is in.

// scripts/sync-kb.ts — runs with the apiKey client, never in a browser
import { createKbArticle, updateKbArticle } from '@uidu/client';
import { uiduAdmin } from '@/lib/uidu-admin';

export async function upsertArticle(kbCollectionId: string, title: string, body: unknown) {
  const created = await createKbArticle(uiduAdmin, {
    input: { attributes: { kbCollectionId, name: title, body, isDraft: true } },
  });
  if (!created || created.errors?.length) {
    throw new Error(created?.errors?.map((e) => e.name).join(', ') ?? 'createKbArticle failed');
  }

  const id = created.kbArticle!.node!.id;
  const published = await updateKbArticle(uiduAdmin, {
    input: { id, attributes: { isDraft: false } },
  });
  if (published?.errors?.length) {
    throw new Error(published.errors.map((e) => e.name).join(', '));
  }
  return id;
}

• The new article is at kbArticle.node on create, but at kbArticle on update — the payloads differ.
• body is Tiptap JSON ({ type: 'doc', content: [...] }), the same shape getKbArticle returns.
• While isDraft is true the article stays out of listKbArticles, getKbCollection and the Help Center's getChannel.
• From the terminal: uidu kb-articles create --attributes '{"kbCollectionId":"…","name":"…"}' --json. Server client set-up: Server integration.

API at a glance

Every @uidu/client function in Knowledge base, generated from the source — the full reference has the rest of the SDK.

Types: KbArticle, KbCollection

CLI: