@wizchat/management

Official TypeScript SDK for the WizChat Management API — the programmatic control plane for WizChat chatbots, including the config-as-code workflow (GET /config → edit → apply).

The SDK is generated from the canonical OpenAPI 3.1 document (GET /api/v1/openapi.json) via openapi-typescript and runs on the minimal openapi-fetch client — fully typed, no heavy framework dependencies.

Install

npm install @wizchat/management

Requires Node 18+ (uses the global fetch).

Authentication

Authenticate with a Management API key (wpk_live_…). It is sent on every request as Authorization: Bearer <key>. Keys are scoped — each operation requires specific scopes (chatbots:read, chatbots:write, mcp:*, skills:*, security:*, domains:*, deploy, analytics:read, documents:*, videos:*). A request with insufficient scope rejects with a WizChatApiError (status: 403, code: 'insufficient_scope').

import { createWizChatClient } from '@wizchat/management';

const wizchat = createWizChatClient({
  apiKey: process.env.WIZCHAT_API_KEY!, // wpk_live_...
  // baseUrl defaults to https://www.wizchat.com — override for staging/self-host.
});

Quickstart

import { createWizChatClient, WizChatApiError } from '@wizchat/management';

const wizchat = createWizChatClient({ apiKey: process.env.WIZCHAT_API_KEY! });

try {
  // 1. List your chatbots.
  const chatbots = await wizchat.listChatbots();
  const chatbotId = chatbots[0].id;

  // 2. Export the current configuration as a desired-state document.
  const config = await wizchat.getConfig(chatbotId);

  // 3. Edit the document in memory (config-as-code).
  config.spec.core = { ...(config.spec.core ?? {}), name: 'Acme Support Bot' };

  // 4. Preview the change with a dry-run — returns the reconcile plan, no writes.
  const plan = await wizchat.applyConfig(chatbotId, config, { dryRun: true });
  console.log(plan.plan.summary); // { create, update, delete, noop }

  // 5. Apply for real once the plan looks right.
  const result = await wizchat.applyConfig(chatbotId, config);
  console.log(result.applied);
} catch (err) {
  if (err instanceof WizChatApiError) {
    console.error(`API error ${err.status} [${err.code}]: ${err.message}`, err.details);
  } else {
    throw err;
  }
}

Prune semantics

apply defaults to prune: true — array sections (mcpServers, skills, domains) are authoritative: resources present on the chatbot but absent from the document are deleted. Every delete is surfaced in the dry-run plan first. Pass { prune: false } for merge-only (create/update, never delete):

await wizchat.applyConfig(chatbotId, config, { prune: false });

Ergonomic helpers

| Method | HTTP | Scope | |---|---|---| | listChatbots() | GET /api/v1/chatbots | chatbots:read | | getChatbot(id) | GET /api/v1/chatbots/{id} | chatbots:read | | getConfig(id) | GET /api/v1/chatbots/{id}/config | chatbots:read (+ per-section read) | | applyConfig(id, doc, opts?) | POST /api/v1/chatbots/{id}/apply | per-section read (dry-run) / write (apply) |

Each helper returns the parsed payload directly and throws WizChatApiError on a non-2xx response.

Raw typed client

Every operation in the API is reachable through the underlying, fully-typed openapi-fetch client at client.raw. It returns the { data, error } tuple (it does not throw):

const { data, error } = await wizchat.raw.GET(
  '/api/v1/chatbots/{chatbotId}/mcp-servers',
  { params: { path: { chatbotId } } },
);
if (error) { /* { error: { code, message, details? } } */ }

Generated types are exported for advanced use:

import type { paths, components, operations, ChatbotConfigDocument } from '@wizchat/management';

type PublicMcpServer = components['schemas']['PublicMcpServer'];

Errors

All non-2xx responses are surfaced as WizChatApiError:

class WizChatApiError extends Error {
  status: number;                       // HTTP status (401, 403, 404, 422, 429, …)
  code: string;                         // e.g. 'not_found', 'insufficient_scope'
  message: string;                      // human-readable
  details?: Record<string, unknown>;    // optional structured context
  body?: { code; message; details? };   // raw parsed envelope
}

Development

This package is generated from the app's OpenAPI document.

npm run gen     # snapshot openapi.json from buildOpenApiDocument() + regenerate src/schema.ts
npm run build   # tsc -> dist/
npm test        # build, then node --test against the fetch-stub suite

The version tracks the OpenAPI info.version.