@andesine/sdk 0.9.0 → 0.11.0

package/README.md

@@ -1,970 +1,36 @@
 # @andesine/sdk
 
-MIT-licensed TypeScript client for the public Andesine HTTP API. ESM only. Requires
-Node.js 22 or later, or a browser/worker runtime with Fetch, Blob, FormData, and
-AbortSignal.any. Keep secret API keys in server code; browsers use publishable keys.
+The TypeScript client for the [Andesine](https://andesine.app) API. It works in Node.js 22 or
+later, and in browsers and workers.
 
-## Use
+## Install
 
 ```sh
 npm install @andesine/sdk
 ```
 
-```ts
-import { createClient } from "@andesine/sdk";
-
-const client = createClient({
-  baseURL: "https://api.andesine.app",
-  apiKey: process.env.ANDESINE_API_KEY
-});
-
-const entry = await client.entries.get({ id: "ent_123" });
-const published = await client.content.get({
-  entryID: entry.id,
-  channel: "published"
-});
-```
-
-`baseURL` defaults to `https://api.andesine.app`. A trailing slash is optional; path prefixes are preserved.
-Each client has its own configuration. You can supply `fetch` and default
-`headers` for proxies, instrumentation, or other authentication arrangements.
-
-For OAuth credentials, use `accessToken` instead of `apiKey`. This disables the
-`ANDESINE_API_KEY` fallback. The SDK does not log in or refresh tokens.
+## Example
 
 ```ts
-const client = createClient({ accessToken });
-const identity = await client.auth.getIdentity();
-const workspaces = await client.workspaces.list();
-const workspaceClient = createClient({
-  accessToken,
-  headers: { "x-workspace-id": selectedWorkspaceID }
-});
-```
-
-### Publishable keys
+import { createClient } from "@andesine/sdk";
 
-Publishable keys (`adn_pk_...`) are safe in browsers. Create one in the Andesine
-app, with its collections and the origins of the sites that use it. A publishable
-key can read the published content of its collections (`content.getTree`,
-`content.get`, `content.listEntries`), search it (`search.published`), and, when
-the key allows it, answer questions about it (`search.askPublished` and
-`search.askPublishedStream`). Browser requests need an allowed `Origin`, so the key
-works only on its sites; requests without `Origin`, e.g. from a site build on a
-server, are allowed. Other operations are refused.
+const client = createClient({ apiKey: process.env.ANDESINE_API_KEY });
 
-```ts
-const client = createClient({ apiKey: "adn_pk_..." });
+const page = await client.content.get({ path: "/Docs/Quickstart", channel: "published" });
 const results = await client.search.published({ query: "install", channel: "published" });
 ```
 
-Pass the key as `apiKey`. This also disables the `ANDESINE_API_KEY` fallback, so a
-bundler that defines `process.env` cannot add a secret key to browser code. The key
-has the same rate limits and usage quota as other API access, and all visitors of a
-site share them.
-
-Select a workspace explicitly for OAuth workspace operations. The server checks
-current user permissions on each request. Browser-only operations remain excluded.
-API keys keep their workspace binding and cannot list a user's workspaces.
-
-Resource methods are generated from the checked-in OpenAPI document. They cover
-assets, entries, collections, content delivery, roles, search, schemas, schema
-migrations, schema versions, memberships, publishing, entry versions, webhooks, and instance information. Internal
-session-only operations are excluded. Published asset delivery does not require
-an API key.
-
-Methods accept one object containing path, query, and body fields. Operations
-without required fields can be called without arguments. Date/time values remain
-JSON strings. File inputs and binary outputs use `Blob`.
-
-```ts
-await client.assets.upload({ assetID: "ast_123", file: new Blob([bytes]) });
-const image = await client.assets.get({ assetID: "ast_123", entryID: entry.id });
-```
-
-The client does not add a content-save endpoint. Use converters to produce JSON;
-storage remains a separate responsibility.
-
-## Errors and responses
-
-Methods return data directly. HTTP failures throw `AndesineAPIError`, with
-`status`, `code`, `message`, `data`, `defined`, `hints`, and the Fetch `response`. Network failures and
-cancellation retain their native errors.
-
-```ts
-import { AndesineAPIError } from "@andesine/sdk";
-
-try {
-  await client.entries.update({ id: "ent_123", name: "Installation" });
-} catch (error) {
-  if (error instanceof AndesineAPIError) {
-    console.error(error.status, error.code, error.message, error.hints);
-
-    if (error.is("SCHEMA_MIGRATION_IN_PROGRESS")) {
-      // data is typed for this code.
-      console.log(error.data.migrationID);
-    }
-
-    if (error.is("TOO_MANY_REQUESTS")) {
-      console.log(error.data?.limit, error.data?.retryAfterSeconds);
-    }
-  }
-}
-
-const result = await client.content.get(
-  { entryID: "ent_123" },
-  { response: "full", headers: { "If-None-Match": cachedETag } }
-);
-
-if (result.notModified) {
-  // Reuse the cached content.
-} else {
-  console.log(result.data, result.headers.get("ETag"));
-}
-```
-
-Use full-response mode for conditional requests. A 304 response has
-`notModified: true` and no data. A 304 in data mode causes a clear error because
-the client does not store a response cache.
-
-## Limits and usage
-
-Rate limits stop abuse; they count requests for each credential (API key, OAuth
-grant, or app session) in one-minute windows.
-
-| Requests a minute                 | Free | Pro   |
-| --------------------------------- | ---- | ----- |
-| All requests                      | 600  | 6,000 |
-| AI answers                        | 60   | 600   |
-| Semantic search (with `semantic`) | 300  | 3,000 |
-
-Each workspace also has two monthly meters, which reset at 00:00 UTC on the first
-day of each month:
-
-- **API calls:** each request with an API key or OAuth. Free includes 50,000; on Pro,
-  each seat adds 150,000 to a pool shared across the workspace, and the rest is billed.
-- **AI credits:** an AI answer uses 10 credits, and a semantic search uses 1. Requests
-  from the app use credits too. Free includes 5,000; on Pro, each seat adds 15,000 to
-  the shared pool, and the rest is billed.
-
-On Free, the meters are hard limits. On Pro, a workspace admin can set a monthly
-spending limit for the billed usage; when it is reached, metered requests stop until
-the next month.
-
-Every limit returns `TOO_MANY_REQUESTS` with `data.limit` (`rate`, `api-calls`,
-`ai-credits`, or `spending`) and `data.retryAfterSeconds`, also sent as
-`Retry-After`. A `rate` limit passes within a minute; the others last until the
-monthly reset, so do not retry them automatically.
-
-Responses describe the limits in headers:
-
-- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`: the rate
-  limit that applies to the request; AI requests show their AI limit.
-- `X-API-Usage`, `X-API-Usage-Limit`, and `X-API-Usage-Reset`: the month's API calls,
-  on metered requests.
-- `X-AI-Credits`, `X-AI-Credits-Limit`, and `X-AI-Credits-Reset`: the month's AI
-  credits, on AI requests.
-
-Limits are the hard limit on Free, or the included amount on Pro. Reset values are
-Unix times in seconds. Self-hosted instances without billing have the Pro rate limits
-and no meters.
-
-## Cancellation, timeouts, and retries
-
-The default timeout is 30 seconds. Set `timeout: 0` to disable it. Timeouts include
-request execution, response reading, and retry delays. Supply `signal` per call
-for cancellation.
-
-Retries are **disabled by default**. Set `retries: 2` on the client or a call to
-allow up to two retries of GET requests and idempotent writes. They retry network
-`TypeError` failures and HTTP 429, 500, 502, 503, and 504. They respect
-`Retry-After`, otherwise use increasing delays with jitter. Other writes are never
-retried automatically.
-
-Idempotent writes (`entries.create`, `entries.update`, and `versions.create`) send
-an `Idempotency-Key` header, generated for each call unless you supply one in
-`headers`. The server applies a key once and returns the first result for 24 hours,
-so retries can't apply a write twice. A retry that arrives while the first attempt
-still runs gets `IDEMPOTENCY_KEY_IN_PROGRESS` and is retried after `Retry-After`. Supply your own key to make a write safe
-across separate calls, for example after a process restart.
-
-```ts
-await client.entries.get(
-  { id: "ent_123" },
-  { signal: controller.signal, timeout: 10_000, retries: 2 }
-);
-```
-
-## Snapshots and pagination
-
-Pin related content reads to the snapshot returned by the first read:
-
-```ts
-const tree = await client.content.getTree({ collectionID: "col_123" });
-const content = client.atSnapshot(tree.snapshotID);
-const entry = await content.get({ entryID: "ent_123" });
-```
-
-`atSnapshot()` returns content resource methods. It rejects a conflicting channel
-or snapshot selector. It does not pin unrelated management operations. Snapshot
-image URLs can expire; copying images for archival export is the caller's task.
-
-```ts
-import { paginate } from "@andesine/sdk";
-
-for await (const entry of paginate((cursor) => client.entries.list({ cursor }))) {
-  console.log(entry.name);
-}
-```
-
-Cursor lists default to 50 items and accept at most 100. `memberships.list()` and
-`memberships.listInvites()` return `{ data, pagination }`. Migration status no longer
-includes `contentLossEntries`; use `schemaMigrations.listContentLossEntries()` for
-that paginated list. Mutable management lists are not snapshots: concurrent edits
-can change their contents between requests.
-
-Use `paginatePages()` to keep page metadata and save a cursor after processing a
-whole page. Both iterators accept `{ cursor }` to resume. Save the same filters with
-your cursor. A missing or repeated continuation cursor causes an error.
-
-Published listings also require the snapshot ID on later pages. The first page
-selects a channel; later pages select that exact snapshot:
-
-```ts
-import { paginatePages } from "@andesine/sdk";
-
-let snapshotID: string | undefined; // Restore this together with a saved cursor.
-const savedCursor: string | undefined = undefined;
-
-for await (const page of paginatePages(
-  (cursor) =>
-    client.content.listEntries({
-      ...(snapshotID ? { snapshotID } : { channel: "published" }),
-      cursor,
-      limit: 100
-    }),
-  { cursor: savedCursor }
-)) {
-  snapshotID = page.snapshotID;
-  // Process page.data, then save snapshotID and page.pagination.nextCursor.
-  // A null nextCursor means the listing is complete.
-}
-```
-
-`content.listCollections()` uses the same format. Both return flat records ordered
-by ID, with parent/collection IDs for links. Entry summaries include a version ID and
-hash. Use `includeContent: true` for full entry records, or fetch one entry with
-`client.atSnapshot(snapshotID).get()`. Snapshot expiry
-still applies. If a saved snapshot is unavailable, start a new listing from its
-channel; do not combine the old cursor with a new snapshot.
-
-### Filtered full-content lists
-
-```ts
-const page = await client.content.listEntries({
-  collectionPath: "/Tutorials",
-  descendants: true,
-  includeContent: true,
-  filters: [
-    { kind: "text", key: "audience", values: ["beginner"] },
-    { kind: "boolean", key: "enabled", value: true }
-  ],
-  limit: 50
-});
-
-for (const entry of page.data) {
-  console.log(entry.path, entry.content, entry.properties, entry.schema);
-}
-
-if (page.pagination.nextCursor) {
-  const next = await client.atSnapshot(page.snapshotID).listEntries({
-    collectionPath: "/Tutorials",
-    descendants: true,
-    includeContent: true,
-    filters: [
-      { kind: "text", key: "audience", values: ["beginner"] },
-      { kind: "boolean", key: "enabled", value: true }
-    ],
-    cursor: page.pagination.nextCursor,
-    limit: 50
-  });
-}
-```
-
-`includeContent` defaults to false. A literal true gives full items; false or an
-omitted option gives summaries. A runtime boolean gives their union. This also
-works with full-response mode, `atSnapshot()`, and `paginatePages()`. Full items
-add `content`, `properties`, `fragments`, `assets`, `schema`, and full version
-metadata. Channel and snapshot metadata stay in the page envelope. The generated
-`PublishedEntryContent` and `PublishedEntrySummary` types are public.
-
-With a collection selector, the list returns direct entries by default.
-`descendants: true` includes nested collections and requires a collection selector.
-Use `collectionPath: "/"` with descendants for the complete snapshot tree. Without
-a scope, the list includes all snapshot entries.
-
-Filters use the same contract as search: text `any`/`all`/`none`, number and date
-comparisons, and boolean equality. All filters must match. Text comparison ignores
-case; missing or incompatible properties do not match negative operators. Filters
-use the assigned version's property records, including fields between content
-blocks. They do not use the current draft or the search index. The SDK encodes
-nested filters automatically.
-
-Keep the same scope and filters across pages. Limits remain 1–100 entries and up
-to 20 filters, with the existing per-filter bounds. Assets are URLs and metadata.
-The server validates each returned full document against its recorded schema. An
-invalid document fails the page with `CONTENT_SCHEMA_INVALID`; it is not skipped.
-Summary reads do not load or validate full documents.
-
-### Structured content
-
-Use `toStructuredContent()` to remove property and fragment wrappers:
-
-```ts
-import { toStructuredContent } from "@andesine/sdk";
-
-const page = await client.content.get({ path: "/Tutorials/Welcome" });
-const tutorial = toStructuredContent(page);
-
-console.log(tutorial.properties); // Each property's value, keyed by derived key.
-console.log(tutorial.fragments); // Each fragment's content, keyed by derived key.
-console.log(tutorial.schema, tutorial.path); // Other response fields are preserved.
-```
-
-The helper also accepts current full entries and full published list items:
-`page.data.map(toStructuredContent)`. Property and fragment maps stay separate.
-Values such as `null`, false, zero, empty strings, and empty arrays are preserved.
-The helper is synchronous. It creates a new object and maps, does not change its
-input, and retains references to values and other fields. It does not validate,
-coerce, fetch, or generate collection-specific types. Types follow the supplied
-input; API property values retain their generated union types. `StructuredContent<T>`
-is available for explicit annotations. Collection type generation remains deferred.
-
-## Publishing preconditions
-
-Pass `expectedSnapshotID` to publish, unpublish, or delete a channel only if its
-publication state still matches a prior read:
-
-```ts
-const reviewed = await client.content.listEntries({ channel: "published", limit: 1 });
-
-await client.publishing.publishEntry({
-  entryID: "ent_123",
-  channel: "published",
-  expectedSnapshotID: reviewed.snapshotID
-});
-```
-
-The server checks the channel inside the mutation transaction. A mismatch returns
-HTTP 409 with code `PUBLISHING_SNAPSHOT_CHANGED`, the expected and current snapshot
-IDs, and a hint. Read the current state and review it before another write. Omitting
-the precondition makes no comparison with your prior read. Draft edits are not
-covered by this check.
-
-`setCollection()` and `bulkSetCollections()` can affect multiple channels. Their
-optional `expectedSnapshots` map checks each supplied channel before the change,
-for example `{ published: "snp_123", preview: "snp_456" }`. Omitted channels are not
-checked. `revertChanges()` continues to require its reviewed `snapshotID`.
-
-Bulk inputs accept at most 100 selected items. Revert selections share that limit
-across entries and collections. A selected collection can contain more descendants;
-this is an input limit, not a limit on the number of affected records. Separate bulk
-requests are separate transactions.
-
-## Instance information
-
-```ts
-const instance = await client.instance.get();
-console.log(instance.features.imageStorage, instance.features.semanticSearch);
-console.log(instance.features.aiAnswers, instance.features.aiAnswerStreaming);
-console.log(instance.limits.maxUploadBytes, instance.limits.assetStorageBytes);
-console.log(instance.limits.maxPageSize, instance.limits.maxBulkItems);
-```
-
-This authenticated call returns the API contract version, configured features,
-and effective workspace limits, including the search result limit. Features do
-not grant permissions or report live service health. Storage limits are capacity,
-not remaining space. `aiAnswers` requires search, embedding, and answer-model
-configuration. `aiAnswerStreaming` reports the configured streaming implementation;
-the AI provider must support Chat Completions SSE. These flags do not report
-remaining quota. The SDK makes no discovery request automatically.
-
-## Types
-
-Named types are generated from the public OpenAPI components. Import them directly
-or through the type-only `Andesine` namespace:
-
-```ts
-import type { Entry, PropertyFilter, Andesine } from "@andesine/sdk";
-
-const renderEntry = (entry: Entry): string => entry.name;
-const renderAsset = (asset: Andesine.Asset): string => asset.filename;
-const filter: PropertyFilter = {
-  kind: "text",
-  key: "category",
-  values: ["guides"]
-};
-```
-
-The exports cover entries and properties; assets, files, and analysis; collections;
-entry and schema versions; schema fields, inheritance, and migrations; memberships,
-invites, roles, and permissions; published content and trees; publishing channels;
-search results and filters; and pagination.
-
-`Entry` includes content, fragments, and properties. `EntrySummary` is the metadata
-returned by entry lists and creation. `SchemaDefinition` describes a collection's
-content schema; `CollectionSchema` contains its local and effective schema details.
-Types describe the HTTP data: dates are strings and binary values are `Blob`.
-Search filter types describe inputs, so fields with server defaults can be omitted.
-
-Every public operation also has generated input, output, and error aliases. Their names
-combine the resource and method with `Input`, `Output`, or `Error`:
-
-```ts
-import type { EntriesCreateInput, EntriesListOutput, Andesine } from "@andesine/sdk";
-
-const input: EntriesCreateInput = { name: "Getting started" };
-type EntryPage = EntriesListOutput;
-type SearchRequest = Andesine.SearchCurrentInput;
-```
-
-Operation inputs match the SDK's single argument object, including path, query,
-and body fields. Outputs match the returned data, excluding the full-response
-wrapper. All these exports, including `Andesine`, are types only and add no runtime
-code. The generic helpers and raw `components`, `operations`, and `paths` types
-remain available:
-
-```ts
-import type { OperationInput, OperationOutput } from "@andesine/sdk";
-
-type CreateEntry = OperationInput<"entries.create">;
-type EntryPage = OperationOutput<"entries.list">;
-```
-
-Content types are structurally compatible with `@andesine/converters`. Neither
-public package imports the private editor or backend at runtime.
-
-## Maintainer workflow
-
-From the repository root:
-
-```sh
-pnpm api:generate
-pnpm build --filter=@andesine/sdk
-```
-
-The export calls oRPC's OpenAPI generator on the same contracts implemented by
-the server. It imports no request handlers or service initialization and needs no
-backend environment variables, database, queue, or running server. The export
-uses the default upload-size limit; self-hosted instances can set a different
-limit, which their own OpenAPI document reflects. The checked-in document's
-server URL is a placeholder; consumers must supply their instance URL.
-
-Commit `openapi.json` and `src/generated/` together. Do not edit generated files.
-Public schema names are defined in the backend's
-`src/contracts/schemas/public.ts` registry. Adding a component there generates its
-named SDK export and its `Andesine` member; no SDK alias list needs to be updated.
-The generator also creates input/output/error aliases for each public operation and
-rejects invalid or duplicate public type names.
-Generation is a maintainer operation, never an install-time operation. `prepack`
-checks types, bundles ESM and declarations with Rolldown, and checks
-package metadata with publint. These 0.x packages are pre-release; review
-generated changes together with API changes.
-
-See the [release guide](https://github.com/vriteio/andesine/blob/andesine/packages/public/README.md)
-for archive checks, versioning, and npm publishing. This package uses the
-[MIT license](./LICENSE).
-
-### Generator choice
-
-Both Hey API 0.99.0 and openapi-typescript 7.13.0 generated output from the Andesine
-spec. This package uses openapi-typescript and openapi-fetch. A small generated
-resource layer supplies the flat argument objects and instance methods; a shared
-transport supplies errors, retries, multipart serialization, and full responses.
-
-Hey API generated operation functions and a larger client layer, but still needed
-adaptation for the selected public interface and multipart operation defaults.
-The selected approach keeps these behaviors in one maintained transport and
-keeps runtime dependencies small.
-
-## Content names
-
-Sibling entries and collections share names. Names are trimmed, normalized to
-Unicode NFC, and must have unique derived URL slugs at each level. Exact names
-also remain unique, including symbol-only names. Names cannot contain `/` or equal
-`.` or `..`. The limit is 300 JavaScript string units. The collection name `~`
-is reserved for the internal workspace root. Root entries and root collections
-share the same level.
-
-Creation chooses an available name, adding suffixes such as ` (2)` when needed.
-Use the returned name rather than assuming that your requested name was saved.
-Rename, move, and restore operations reject conflicts. Deleted items release
-names; a schema move temporarily reserves its source name for rollback.
-
-`CONTENT_NAME_CONFLICT` (409) includes `name`, `slug`, `parentID`, and optional `hints`.
-Use `error.is("CONTENT_NAME_CONFLICT")` to access typed data. Renaming never
-chooses a different name for you.
-
-## Content paths
-
-Read an entry by ID, `path`, or `slugPath`. Use exactly one selector:
-
-```ts
-const current = await client.entries.get({ path: "/Docs/Getting started" });
-const tree = await client.content.getTree({ collectionSlugPath: "/docs" });
-const content = client.atSnapshot(tree.snapshotID);
-const page = await content.get({ slugPath: "/docs/getting-started" });
-const definition = await content.getSchema({ slugPath: page.slugPath });
-const activeSchema = await client.schemas.get({ collectionPath: "/Docs" });
-```
-
-Paths use names from the tree, with `/` between levels. Names are case-sensitive;
-each segment is trimmed and NFC-normalized. Pass decoded names to the SDK. It
-encodes query parameters once, so a name containing the literal text `%2F` keeps
-that text. Empty segments, trailing slashes, `.` and `..` are invalid.
-
-An absolute path starts with `/`. An anchored path starts with a collection ID,
-such as `coll_67bqzSOb9kct2DaVkTwT53/Getting started`. The anchor must exist in the
-selected current tree or snapshot. A name that looks like an ID is still a name
-when it occurs in an absolute path. A bare collection ID is also a valid
-`collectionPath`. `/` selects the root. Neither selects an entry on its own.
-
-Current entry and collection responses include their canonical absolute `path` and `slugPath`.
-Published content, trees, and list results use snapshot collection names and the
-titles of assigned versions. Draft renames, moves, and deletions do not change
-those snapshot paths. Full published content also includes `id` and `collectionID`.
-Saved versions remain ID-based because a version alone has no snapshot location.
-
-`content.getTree({ collectionPath: "/" })` returns a virtual root collection with
-`id: null`, `name: ""`, `path: "/"`, and `slugPath: "/"`. It contains top-level entries and collections.
-
-`entries.list`, `collections.list`, `content.listEntries`, and
-`content.listCollections` accept one of `collectionID`, `collectionPath`, or `collectionSlugPath` to
-select direct children. Keep the same scope while paging. With no scope,
-`collections.list` selects root children; the other lists select all accessible
-items. `collections.list` now uses these fields instead of `ancestorID`.
-Search accepts the same collection selectors and includes descendants. Its `/`
-scope covers the whole accessible tree. Search results include a canonical entry
-`path`, `slugPath`, and an optional heading `anchor`.
-
-Slugs use Unicode NFKC normalization, lowercase, Unicode letters/marks/numbers,
-and single hyphens between other character groups. Accents and non-Latin letters
-are retained. A symbol-only name uses its public ID in lowercase with `-` instead
-of `_`. Slugs are derived, never edited separately. Renaming or moving content
-changes its path; redirects are not stored. `Getting Started`, `getting-started`,
-and `Getting Started!` conflict at the same level. Existing conflicting content
-must be renamed before publishing it again.
-
-`slugPath` and `collectionSlugPath` accept absolute paths and collection-ID
-anchors, with the same snapshot and scope rules as name paths. Pass decoded
-segments, for example `coll_ID/getting-started`. The URL route should be decoded
-once by your framework before passing it to the SDK.
-
-```ts
-import { toContentURL } from "@andesine/sdk";
-
-// Prefer the API object: its slugPath also covers symbol-only ancestor names.
-const url = toContentURL(page, { rootPath: "/Docs", baseURL: "/docs" });
-// /docs/getting-started
-const originalNames = toContentURL(page, { format: "name" });
-// /Docs/Getting%20started
-```
-
-`toContentURL` defaults to slug URLs. A string input derives slugs from the path;
-API objects use their returned `slugPath`. `format: "name"` preserves original
-names. `rootPath` accepts a name or slug prefix in slug mode. Destination prefixes
-and heading anchors are not slugified. `toContentSlug(name, id?)` exposes the
-shared segment rule; symbol-only names require a public content ID. It is also
-available from `@andesine/sdk/slug`, which loads only the slug helper.
-
-Search indexes must be rebuilt after this upgrade to populate `slugPath` on
-existing results and AI sources. No database schema migration is needed.
-
-HTTP reads use query selectors on `GET /entries/get`, `GET /content/entries/get`,
-`GET /content/tree`, and `GET /schemas/collection`. The published schema route
-remains `GET /content/entries/schema`. These replace the former ID-in-path GET
-routes; mutation routes are unchanged. SDK method names are unchanged.
-
-Publication checks names across the complete next snapshot, including retained
-versions. `PUBLISHING_NAME_CONFLICT` (409) includes `name`, `parentID`, and `hints`.
-Publish related replacements together or unpublish the conflict first. A draft
-rename alone does not remove a name from an existing publication. A rejected
-publication leaves the channel and its snapshot unchanged.
-
-## Search and source links
-
-Published search results include required `channel`, `snapshotID`, `versionID`,
-and canonical entry `path` and `slugPath` fields. `entryID` remains the stable identity.
-An optional `anchor` identifies a heading in that version; a result before any
-heading has no anchor. Current results have their indexed working path. Search
-index updates are asynchronous, so current paths can briefly lag draft changes.
-
-```ts
-const matches = await client.search.published({
-  channel: "published",
-  query: "installation"
-});
-
-for (const result of matches.results) {
-  const page = await client.atSnapshot(result.snapshotID).get({
-    entryID: result.entryID
-  });
-  const link = toContentURL(result, { rootPath: "/Docs", baseURL: "/docs" });
-  // Render page headings with matching IDs.
-}
-```
-
-Paths and anchors are decoded data, not application URLs. Encode each path segment
-when building a URL. Reading by `entryID` at the source snapshot preserves the
-content version even if the channel advances. A retained snapshot can expire;
-handle an unavailable snapshot with a new search. Search still uses the current
-channel and does not support historical snapshot queries.
-
-The converters' `getHeadingAnchors()` helper derives matching targets. HTML
-conversion applies those IDs; other renderers must preserve AST IDs or apply the
-helper themselves. Duplicate headings are numbered across all fragments. Existing
-`headingPath` is retained for editor navigation. Answer sources use the same path,
-snapshot, and anchor metadata, plus a numbered citation `id` and `relevance`.
-
-## AI answers
-
-Call these methods from your server with an API key. For published documentation,
-grant `ai-answers` and `read:publishing`. For current workspace content, grant
-`ai-answers`, `read:entries`, and `read:collections`. Write permissions also supply
-the corresponding read access, but never imply `ai-answers`. The key editor has a
-separate AI answers option.
-
-```ts
-import type { AnswerHistoryMessage, PublishedAnswerSource } from "@andesine/sdk";
-
-const history: AnswerHistoryMessage[] = [];
-const result = await client.search.askPublished({
-  channel: "published",
-  collectionPath: "/Docs",
-  question: "How do I install Andesine?",
-  history
-});
-const sources: PublishedAnswerSource[] = result.sources;
-
-// [1] in result.answer refers to the source with id === 1.
-// Use each source's path/anchor for links and snapshotID/entryID for content reads.
-history.push(
-  { role: "user", content: "How do I install Andesine?" },
-  { role: "assistant", content: result.answer }
-);
-```
-
-`client.search.askCurrent({ question, collectionPath, history })` reads current
-content with the caller's collection access rules. Both methods accept optional
-property `filters` and either `collectionID` or `collectionPath`. Published scopes
-resolve within the channel's current snapshot. Omit the collection selector to
-search all content available to the caller.
-
-Responses contain the complete `answer` and `sources`. The generated `Answer`,
-`PublishedAnswer`, `AnswerSource`, `PublishedAnswerSource`, and
-`AnswerHistoryMessage` types are also available through `Andesine`.
-Both complete and streamed answers use the same inputs and source-selection rules.
-
-The limits are 1,000 characters per question, 10 history messages of up to 4,000
-characters each, and 20 property filters. History is supplied per request; the SDK
-does not store it. Trim history before sending a later question. Each answer uses 3
-AI credits and has its own rate limit; see [Limits and usage](#limits-and-usage). A
-complete response is counted when it succeeds.
-A rate-limit error includes `Retry-After` and `data.retryAfterSeconds`. Provider
-failures return `SERVICE_UNAVAILABLE` with hints. Answer POST requests are never
-automatically retried, even when read retries are enabled.
-
-## Recorded content schemas
-
-Full entry, version, and published-content responses include `schema`, containing
-`revisionID` and `hash`, or `null` for content without a recorded schema. Reads and
-publication validate the document against that recorded revision, including
-inherited fields. They do not repair content or use the latest schema instead.
-
-```ts
-const page = await client.content.get({ entryID: "ent_123" });
-const definition = await client.atSnapshot(page.snapshotID).getSchema({
-  entryID: page.id
-});
-
-// Use a hash saved by your application when it requires a specific definition.
-const checked = await client.content.get({
-  entryID: page.id,
-  snapshotID: page.snapshotID,
-  expectedSchemaHash: "YOUR_SAVED_64_CHARACTER_SHA256_HASH"
-});
-```
-
-`content.getSchema()` uses published-content access. It returns the selected
-entry's recorded definition or `null`. `schemas.getRevision({ revisionID })`
-requires collection-read access and returns an exact revision, including inactive
-revisions. Both return `{ revisionID, hash, definition }`. The definition combines
-inherited fields without internal source metadata and matches the recorded hash.
-
-`expectedSchemaHash` is also available on `entries.get()`, `versions.get()`, and
-`publishing.getEntryVersion()`. A mismatch, including content without a schema,
-returns `CONTENT_SCHEMA_MISMATCH` (409) with the expected hash and actual metadata.
-Invalid stored content returns `CONTENT_SCHEMA_INVALID` (500) on delivery or (409)
-on publication, with issue paths and available entry, version, and revision IDs.
-`SCHEMA_FIELD_KEY_CONFLICT` (409) identifies conflicting derived field keys.
-Use `error.is(code)` to read the generated error data types. Schema definitions
-remain readable when their associated document is invalid.
-
-## Type-generation metadata
-
-Read collection/schema metadata in bulk without fetching content bodies:
-
-```ts
-const published = await client.typeMetadata.getPublished({
-  collections: ["/Tutorials"],
-  channel: "published",
-  includeEntries: true
-});
-const current = await client.typeMetadata.getCurrent({
-  collections: ["/Tutorials"],
-  includeTree: true
-});
-```
-
-Selectors accept IDs, decoded name paths, or `{ collectionSlugPath: "/docs" }`
-objects and include descendant collections. An
-empty list selects all accessible collections. Each response is one consistent
-database snapshot; published metadata also returns its publication snapshot ID
-for related reads. Published paths and schemas come from the assigned versions,
-including mixed revisions and schema-free entries. A collection without recorded
-schemas uses a general type without a warning. Current metadata uses active
-effective schemas and rejects selected collections with an active schema migration.
-
-`revisions` contains the referenced effective definitions, including inherited
-fields. Each collection lists its `schemaRevisionIDs`: `null` means schema-free
-content, while an empty array means there is no recorded schema evidence.
-`includeEntries` adds entry identifiers, names, paths, and revision associations;
-`includeTree` also includes entries and adds child IDs in display order. Current
-entry/tree metadata requires `read:entries` in addition to `read:collections`.
-Published metadata follows the existing `read:publishing` access rules.
-
-The `fingerprint` changes with the returned type metadata. It excludes content
-bodies, snapshot IDs, expiry, and entry/tree data that was not requested. These
-endpoints provide metadata only; `andesine types generate` creates project declarations.
-
-## Workspace content types
-
-`createClient<Workspace>()` accepts a type-only workspace map. Generate it with
-`andesine types generate`. A small map can also be defined directly:
-
-```ts
-import {
-  createClient,
-  toStructuredContent,
-  type EntryFragment,
-  type WorkspaceCollection,
-  type WorkspaceTypeMap
-} from "@andesine/sdk";
-
-interface Tutorials extends WorkspaceCollection {
-  id: "coll_tutorials";
-  path: "/Tutorials";
-  slugPath: "/tutorials";
-  schemaRevisionIDs: readonly ["schr_tutorial"];
-  descendants: readonly [];
-}
-
-interface Workspace extends WorkspaceTypeMap {
-  source: { kind: "published"; channel: "published" };
-  collections: { "coll_tutorials": Tutorials; "/Tutorials": Tutorials; "/tutorials": Tutorials };
-  schemas: {
-    schr_tutorial: {
-      hash: "RECORDED_SCHEMA_HASH";
-      properties: {
-        title: { name: "Title"; type: "text"; value: string };
-        duration?: { name: "Duration"; type: "number"; value: number | null };
-      };
-      fragments: { body: EntryFragment };
-    };
-  };
-}
-
-const client = createClient<Workspace>();
-
-for await (const entry of client.content.paginateEntries({
-  collectionPath: "/Tutorials",
-  channel: "published",
-  includeContent: true
-})) {
-  const tutorial = toStructuredContent(entry);
-  const title: string = tutorial.properties.title;
-  const duration: number | null | undefined = tutorial.properties.duration;
-}
-```
-
-Replace the example IDs, hash, and fields with the recorded metadata. Collections
-can have several revision IDs; results then preserve each revision's fields as a
-union. `null` represents schema-free content. An empty revision tuple uses general
-content types. `descendants` contains all descendant collection keys; recursive
-lists include their shapes. If the hierarchy is incomplete, recursive results
-also retain the general content type.
-
-Exact entry reads narrow only when the map has an `entries` binding for the given
-ID, path, or slug path. Each binding supplies `collection` and `schemaRevisionID`. Optional
-`tree` bindings supply published tree shapes by collection selector. Unknown keys
-and dynamic strings keep general SDK types. Current maps apply to `entries.get`;
-published maps apply to content delivery. Summary lists do not gain content fields.
-Snapshots, full responses, pagination, and `toStructuredContent` preserve the map.
-
-`SchemaContent<Workspace, "schr_tutorial">` exposes one revision's content fields.
-`OperationOutput<"content.get", Workspace, { path: "/Tutorials/First" }>` exposes
-a full result when that entry path is bound. For mixed revisions, TypeScript does
-not narrow the parent entry after a nested `entry.schema.revisionID` check. Use a
-type predicate with `Extract<Result, { schema: { revisionID: "schr_tutorial" } }>`
-to narrow the entry. Collection lists can also narrow on their top-level
-`collectionID` when the collections have distinct IDs.
-
-The map makes no requests and changes no request options. Supply the workspace,
-channel, and snapshot through the usual runtime options. The types assume those
-options and the server content match the map; they do not validate responses or
-detect stale generated types. Different clients can use different maps without
-module augmentation. Plain `createClient()` keeps the general SDK types.
-
-## Operation documentation and error hints
-
-All public methods include generated summaries, descriptions, API key permissions,
-and input examples in editor tooltips. The same examples appear in OpenAPI parameters
-and request bodies. IDs and file contents in examples are placeholders; replace them
-with values from your instance. Role permissions differ from API key permissions.
+Keep secret API keys in server code. In browsers, use a publishable key (`adn_pk_...`), which can
+only read and search published content.
 
-Error declarations come from the backend contracts. `error.is(code)` narrows `data`
-only when the server marks the error as defined by its contract. An undeclared error,
-proxy response, or network failure does not become a typed domain error. Handle the
-remaining error cases as well. `data` stays `unknown` until narrowed.
-
-`APIErrorCode`, `APIErrorBody`, `APIErrorData<Code>`, and
-`OperationError<"entries.create">` are available for application types. Operation
-aliases such as `EntriesCreateError` are also available as
-`Andesine.EntriesCreateError`. These types describe declared errors, not every
-possible failure. TypeScript does not enforce the types of thrown errors.
-
-`data.hints` is optional advice. `error.hints` returns an empty array when no hints
-are present. Use stable codes and structured data for program logic; never parse
-hint text. Hints do not trigger retries. Automatic retries remain disabled by default.
-
-Common errors can include validation `issues`, `missingPermissions`, `requiredPlan`,
-or `retryAfterSeconds`. Domain errors include `SCHEMA_MIGRATION_IN_PROGRESS`,
-`PUBLISHING_SNAPSHOT_CHANGED`, `ROLE_NAME_DUPLICATE`, `ROLE_NAME_INVALID`,
-`MEMBERSHIP_ALREADY_EXISTS`, and `INVITE_ALREADY_PENDING`. Migration and snapshot
-conflicts now use their specific codes instead of the generic `CONFLICT` code.
-
-Asset operation errors can also include the current `assetStatus`, expected and
-actual file sizes and checksums, or storage `limitBytes`, `usedBytes`, and
-`requiredBytes`. Storage reservations include processed image variants.
-These fields are declared on the applicable operation error types, such as
-`AssetsUploadError` and `AssetsRegisterError`; not every error with the same code
-contains asset data. With `AndesineAPIError`, check for the field before using it.
-Known rate-limit delays appear in both `data.retryAfterSeconds` and `Retry-After`.
-Concurrency limits have no fixed delay and only supply a hint.
-
-## Streaming AI answers
-
-`search.askCurrentStream()` and `search.askPublishedStream()` return a promise of
-an async iterator. They require the same permissions and inputs as their complete
-answer methods. Published source types require `snapshotID`, `versionID`, and
-`channel`. `AnswerEvent` and `PublishedAnswerEvent` are available directly and
-through `Andesine`.
-
-```ts
-const controller = new AbortController();
-const events = await client.search.askPublishedStream(
-  { channel: "published", collectionPath: "/Docs", question: "How do I install Andesine?" },
-  { signal: controller.signal, timeout: 120_000 }
-);
-
-for await (const event of events) {
-  if (event.type === "sources") console.log(event.sources);
-  if (event.type === "textDelta") process.stdout.write(event.text);
-  if (event.type === "completed") console.log(event.answer);
-}
-```
-
-The order is one `sources` event, non-empty `textDelta` events, then one
-`completed` event. A no-source answer may complete without deltas. The completed
-answer contains the final text and sources. Deltas contain plain text, including
-any Markdown syntax; choose how to render it in your application.
-
-Use `controller.abort()` to cancel, or `break` from the loop to stop early. If you
-open a stream but do not iterate it, call `await events.return?.()` to close it.
-The request timeout covers both opening and consuming the stream; `timeout: 0`
-disables it. The SDK never reconnects or retries generation, even if read retries
-are enabled. `response: "full"` returns the iterator in `data`, with the actual
-response status and headers.
-
-Errors before SSE headers are normal `AndesineAPIError` failures. A declared
-error after headers throws `AndesineStreamError`, which extends `AndesineAPIError`
-and supports `.is()`, `code`, `data`, and `hints`. Its `status` is the error status
-from the frame; `response.status` remains the actual HTTP status, usually 200.
-Malformed streams throw `AndesineStreamProtocolError` with `INVALID_STREAM`.
-Missing completion or an interrupted body uses `INCOMPLETE_STREAM`. These are
-local protocol errors, not API errors with an invented HTTP status. Abort and
-timeout reasons are preserved.
-
-A stream is counted when generation starts, including generation that later fails
-or is cancelled. Source preparation alone is not charged. The rate limit, quota, and
-spending limit checks run before the stream opens. Usage headers show the allowance
-when the stream opens; chunks do not update headers or create more usage records.
-
-### Forward a stream from your server
-
-The optional `@andesine/sdk/streaming` entry has no framework dependency. It uses
-standard Fetch types, preserves backpressure and cancellation, and forwards no
-upstream headers or credentials.
-
-```ts
-import { toAnswerResponse } from "@andesine/sdk/streaming";
-
-async function answerRequest(request: Request): Promise<Response> {
-  const { question } = await request.json();
-  const events = await client.search.askPublishedStream(
-    { channel: "published", collectionPath: "/Docs", question },
-    { signal: request.signal, timeout: 120_000 }
-  );
-
-  return toAnswerResponse(events);
-}
-```
-
-Keep the configured `client` and API key on your server. Handle errors before
-`toAnswerResponse()` with your application's normal HTTP error handler. Once
-streaming starts, the helper preserves typed API error frames and uses a generic
-error frame for other failures. Its response disables caching and requests that
-proxies do not buffer the stream. Your hosting platform must support streamed
-responses.
-
-A browser can read the forwarded response without an Andesine API key:
-
-```ts
-import { readAnswerStream } from "@andesine/sdk/streaming";
-
-const controller = new AbortController();
-const response = await fetch("/api/ask", {
-  method: "POST",
-  headers: { "Content-Type": "application/json" },
-  body: JSON.stringify({ question: "How do I install Andesine?" }),
-  signal: controller.signal
-});
-
-for await (const event of await readAnswerStream(response, { signal: controller.signal })) {
-  console.log(event);
-}
-```
+## Documentation
 
-Both helpers use oRPC's SSE framing: `event: message` carries an answer event as
-JSON; `event: error` carries the error envelope. Completion is an application
-`completed` event. Comments are ignored, and a transport `done` event cannot
-replace application completion. Event IDs and retry fields never trigger
-reconnection.
+- [SDK](https://andesine.app/docs/developers/sdk/)
+- [API overview](https://andesine.app/docs/developers/api-overview/)
+- [API reference](https://andesine.app/docs/api/)
+- [Webhooks](https://andesine.app/docs/developers/webhooks/), and the
+  [webhook receivers guide](WEBHOOKS.md) in this package
 
-## Webhooks
+## License
 
-Manage endpoints and delivery history through `client.webhooks`. Verify incoming
-requests in server code with `verifyWebhook` or `verifyWebhookRequest` from
-`@andesine/sdk/webhooks`. Both helpers return a validated, typed event after
-authenticating the unchanged body and checking the five-minute timestamp window.
-See [webhook setup, receivers, rotation, and replay](WEBHOOKS.md).
+MIT