From 7b4fd63a91830676da833926ba3bde138f7e69a7 Mon Sep 17 00:00:00 2001
From: Ethan Davidson <31261035+EthanThatOneKid@users.noreply.github.com>
Date: Sun, 16 Aug 2026 10:38:15 -0700
Subject: [PATCH] docs: add @worlds/client install + usage page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document the generated data-plane HTTP client: install, createClient
with wzw_ tokens, listWorlds/search/import/sparql/export/reindex,
self-hosting baseUrl override, and the generation workflow.

Adds the page to the Worlds nav group.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
---
 docs.json         |   3 +-
 worlds/client.mdx | 124 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 126 insertions(+), 1 deletion(-)
 create mode 100644 worlds/client.mdx

diff --git a/docs.json b/docs.json
index 6788649..652d4ab 100644
--- a/docs.json
+++ b/docs.json
@@ -103,7 +103,8 @@
           "worlds/index",
           "worlds/search",
           "worlds/query",
-          "worlds/update"
+          "worlds/update",
+          "worlds/client"
         ]
       },
       {
diff --git a/worlds/client.mdx b/worlds/client.mdx
new file mode 100644
index 0000000..3969f85
--- /dev/null
+++ b/worlds/client.mdx
@@ -0,0 +1,124 @@
+---
+title: "Client"
+description: "The generated TypeScript client for the Worlds Data API."
+---
+
+The Worlds Data API client (`@worlds/client`) is a typed HTTP client generated
+from the canonical
+[Worlds Data API OpenAPI document](https://worlds-api.wazoo.dev/openapi.json).
+It mirrors the management-plane client pattern: `@wazoo/client` talks to the
+platform API, `@worlds/client` talks to the data plane.
+
+Use it for remote data-plane operations: world lifecycle, import, export,
+search, SPARQL, and reindexing against `worlds-api.wazoo.dev`.
+
+For an embeddable, provider-swappable interface over the same operations, use
+the [Worlds SDK](/platform/typescript-sdk) instead.
+
+## Install
+
+```sh
+npx jsr add @worlds/client
+```
+
+## Create a client
+
+Data-plane requests authenticate with a `wzw_` world token:
+
+```ts
+import { createClient, listWorlds } from "@worlds/client";
+
+const client = createClient({
+  baseUrl: "https://worlds-api.wazoo.dev",
+  auth: process.env.WORLDS_TOKEN,
+});
+```
+
+## List worlds
+
+```ts
+const response = await listWorlds({ client });
+
+for (const world of response.data?.worlds ?? []) {
+  console.log(world.uid, world.displayName);
+}
+```
+
+## Search
+
+The data-plane search endpoint performs hybrid retrieval across a world:
+
+```ts
+import { searchWorld } from "@worlds/client";
+
+const response = await searchWorld({
+  client,
+  path: { id: "w_<uuid>" },
+  body: { query: "Ethan's manager", limit: 5 },
+});
+
+for (const result of response.data?.results ?? []) {
+  console.log(result.subject, result.content);
+}
+```
+
+Results return the matching subject and predicate IRIs plus the literal
+`content`, so an agent can bind the exact entity before running
+[SPARQL](/worlds/query).
+
+## Import data
+
+```ts
+import { importWorld } from "@worlds/client";
+
+const response = await importWorld({
+  client,
+  path: { id: "w_<uuid>" },
+  body: {
+    data: '(<urn:subject> <urn:predicate> "object") .',
+    contentType: "text/turtle",
+  },
+});
+```
+
+## SPARQL
+
+```ts
+import { sparqlWorld } from "@worlds/client";
+
+const response = await sparqlWorld({
+  client,
+  path: { id: "w_<uuid>" },
+  body: { query: 'SELECT ?s WHERE { ?s <urn:predicate> "object" }' },
+});
+```
+
+## Export and reindex
+
+```ts
+import { exportWorld, reindexWorld } from "@worlds/client";
+
+const exported = await exportWorld({ client, path: { id: "w_<uuid>" } });
+const reindexed = await reindexWorld({ client, path: { id: "w_<uuid>" } });
+```
+
+## Self-hosting
+
+Point the client at a self-hosted Worlds Data API instance by overriding
+`baseUrl`:
+
+```ts
+const client = createClient({
+  baseUrl: "https://worlds.example.com",
+  auth: process.env.WORLDS_TOKEN,
+});
+```
+
+## Generated code
+
+The package is generated with `@hey-api/openapi-ts` from a committed OpenAPI
+snapshot in the
+[`wazootech/worlds-client-ts`](https://github.com/wazootech/worlds-client-ts)
+repository. Run `deno task sync:openapi` to refresh the snapshot, and
+`deno task generate` to regenerate `src/generated/`. CI fails if the checked-in
+snapshot drifts from the canonical document.