@own-your-computer/wikimix-client

Framework-neutral TypeScript client for Wikimix Engine API v1. It has no React, router, CSS, or host-taxonomy dependency and uses the platform fetch, Headers, and URLSearchParams APIs.

import { createWikimixClient } from '@own-your-computer/wikimix-client'

const wikimix = createWikimixClient({
  baseUrl: 'https://example.test/api/wikimix/v1',
  headers: () => ({ Authorization: `Bearer ${readToken()}` }),
})

const firstPage = await wikimix.listThreads({ limit: 25 })

The package supports API major version 1. Its semantic version is independent of the Go module version. WikimixError exposes the stable HTTP status, engine error code, message, and field errors returned by the API.

Thread.content_revision is an opaque equality token for committed head, tail, status and predecessor changes. Server-rendered hosts can retain the public Go facade's Thread.ContentRevision as a decimal string in their control slot, then compare it with getThread(id, { limit: 1 }).content_revision before navigating to fresh server HTML. Compare against the server snapshot, not the first browser response, and do not convert the token to a JavaScript number. Queued, silent, skipped and failed agent work, feedback and subject changes leave it unchanged.

Installation and reference

Candidate 0.1.0 targets API major 1, Node 24+, and the browser floors in the repository README. Public registry publication is pending. Once published:

npm install --save-exact --ignore-scripts --registry=https://registry.npmjs.org/ \
  @own-your-computer/[email protected]

For local evaluation install the exact packed .tgz instead. The package is ESM, with its types exported at the root. The default base URL is /api/wikimix/v1; use an absolute URL in Node. fetch, headers and credentials are injectable. Authentication and CSRF policy remain host-owned.

Use listThreads, getThread, listEvents, listHeadVersions, listFeedback, listSubjects and runTrace for bounded reads. Their options accept limit and cursor. Follow page.next_cursor or tail_page.next_cursor. listAll* and getCompleteThread aggregate pages in memory and are inappropriate for polling. createThread, reply, editHead, rollback, resolve, setSupersedes, subject, feedback and agent methods expose the generated API types. Use the exported TypeScript declarations and server openapi.json as the complete signature/schema reference; the repository API.md includes the action matrix and failure semantics.

A head edit sends {expected_version, body_md}. Preserve the original version when handling WikimixError status 409; do not silently retry against newer content. Run results and traces have separate methods and policy. Fetching query state never refreshes a server-owned document by itself.

Apache-2.0; LICENSE and NOTICE are included. See the repository for backend embedding, security and release instructions.