@andesine/sdk 0.1.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.4.0
+
+- Document the limits: per-minute rate limits, the monthly API call and AI credit
+  meters, the Pro spending limit, the `X-RateLimit-*`, `X-API-Usage*`, and
+  `X-AI-Credits*` headers, and the new `limit` field of `TOO_MANY_REQUESTS` error
+  data (`rate`, `api-calls`, `ai-credits`, or `spending`). `X-RateLimit-*` now
+  describes the rate limit, not the monthly usage.
+
+- Document publishable keys (`adn_pk_...`) for browser use: published content
+  reads, search, and answers from the key's collections and origins, and server
+  reads without an `Origin`, e.g. site builds.
+
+## 0.3.0
+
+- Add generated webhook methods for management (including bulk enable/disable and
+  delete), delivery history, signed tests, and single or bulk replay, plus public
+  webhook event types.
+- Add the isolated `@andesine/sdk/webhooks` verifier with raw-body authentication,
+  timestamp and schema checks, plus receiver and durable deduplication examples.
+
+## 0.2.0
+
+- Add derived `slugPath` selectors and responses, slug-based sibling uniqueness,
+  slug-aware workspace maps, and slug URLs by default in `toContentURL`.
+
+- Add type-only workspace maps through `createClient<Workspace>()`, with selector-aware
+  content types, revision unions, optional entry/tree bindings, and typed content helpers.
+- Add bulk current/published type metadata with effective schema revisions,
+  optional entries/tree, consistent source reads, and stable fingerprints.
+- Explicit OAuth access tokens without API-key environment fallback, plus credential identity and user workspace discovery.
+
 ## 0.1.0
 
 - Initial public TypeScript client generated from the Andesine OpenAPI document.

package/README.md

@@ -2,7 +2,7 @@
 
 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 private API keys in server code.
+AbortSignal.any. Keep secret API keys in server code; browsers use publishable keys.
 
 ## Use
 
@@ -25,13 +25,51 @@ const published = await client.content.get({
 });
 ```
 
-`baseURL` is required. A trailing slash is optional; path prefixes are preserved.
+`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.
+
+```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
+
+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.
+
+```ts
+const client = createClient({ apiKey: "adn_pk_..." });
+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, and instance information. Internal
+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.
 
@@ -68,7 +106,7 @@ try {
     }
 
     if (error.is("TOO_MANY_REQUESTS")) {
-      console.log(error.data?.retryAfterSeconds);
+      console.log(error.data?.limit, error.data?.retryAfterSeconds);
     }
   }
 }
@@ -89,6 +127,48 @@ 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; Pro
+  includes 500,000 and bills the rest.
+- **AI credits:** an AI answer uses 3 credits, and a semantic search uses 1. Requests
+  from the app use credits too. Free includes 5,000; Pro includes 50,000 and bills
+  the rest.
+
+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
@@ -361,9 +441,8 @@ public package imports the private editor or backend at runtime.
 From the repository root:
 
 ```sh
-pnpm --filter @andesine/backend openapi:export
-pnpm --filter @andesine/sdk generate
-pnpm --filter @andesine/sdk build
+pnpm api:generate
+pnpm build --filter=@andesine/sdk
 ```
 
 The export calls oRPC's OpenAPI generator on the same contracts implemented by
@@ -403,7 +482,8 @@ keeps runtime dependencies small.
 ## Content names
 
 Sibling entries and collections share names. Names are trimmed, normalized to
-Unicode NFC, and compared case-sensitively. Names cannot contain `/` or equal
+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.
@@ -413,20 +493,20 @@ 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`, `parentID`, and optional `hints`.
+`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 or by path. Use exactly one selector:
+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({ collectionPath: "/Docs" });
+const tree = await client.content.getTree({ collectionSlugPath: "/docs" });
 const content = client.atSnapshot(tree.snapshotID);
-const page = await content.get({ path: "/Docs/Getting started" });
-const definition = await content.getSchema({ path: page.path });
+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" });
 ```
 
@@ -441,23 +521,56 @@ 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`.
+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: ""`, and `path: "/"`. It contains top-level entries and collections.
+`id: null`, `name: ""`, `path: "/"`, and `slugPath: "/"`. It contains top-level entries and collections.
 
 `entries.list`, `collections.list`, `content.listEntries`, and
-`content.listCollections` accept either `collectionID` or `collectionPath` to
+`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` and an optional heading `anchor`.
+`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
@@ -473,7 +586,7 @@ publication leaves the channel and its snapshot unchanged.
 ## Search and source links
 
 Published search results include required `channel`, `snapshotID`, `versionID`,
-and canonical entry `path` fields. `entryID` remains the stable identity.
+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.
@@ -488,9 +601,8 @@ for (const result of matches.results) {
   const page = await client.atSnapshot(result.snapshotID).get({
     entryID: result.entryID
   });
-  const pathname = result.path.split("/").map(encodeURIComponent).join("/");
-  const link = pathname + (result.anchor ? `#${encodeURIComponent(result.anchor)}` : "");
-  // Map pathname to your docs site's route and render page with matching heading IDs.
+  const link = toContentURL(result, { rootPath: "/Docs", baseURL: "/docs" });
+  // Render page headings with matching IDs.
 }
 ```
 
@@ -547,9 +659,9 @@ Both complete and streamed answers use the same inputs and source-selection rule
 
 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. The existing Ask
-AI rate limit is 10 requests per 60 seconds per credential. API usage metering
-is unchanged: a successful complete response counts once when billing is enabled.
+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.
@@ -590,6 +702,121 @@ on publication, with issue paths and available entry, version, and revision IDs.
 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,
@@ -670,11 +897,10 @@ 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 counts as one API call when generation starts, including generation that
-later fails or is cancelled. Source preparation alone is not charged. The existing
-Ask AI rate limit and quota checks run before opening the stream. Usage headers
-show the allowance when the stream opens; chunks do not update headers or create
-additional usage records.
+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
 
@@ -726,3 +952,11 @@ 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.
+
+## Webhooks
+
+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).