TypeScript client — Clarity Developer

Nine operations. One small client.

The Clarity Developer Client is a dependency-free, server-side ESM module for the published sandbox API. It validates keys and request IDs, bounds timeouts, preserves rate-limit metadata and returns stable error objects — without pulling private Clarity data or executable tool code into an app.

Quickstart

Keep the key on your server.

The module runs in Node.js, Deno and compatible server runtimes with Fetch and Web Crypto. It is deliberately not a browser SDK: a sandbox key must never be embedded in JavaScript, iOS bundles or public repositories.

download.sh

curl --fail --remote-name \
  https://clarity.audecius.com/developer/clarity-developer-client.mjs

server.mjs

import { ClarityDeveloperClient } from "./clarity-developer-client.mjs";

const clarity = new ClarityDeveloperClient({
  apiKey: process.env.CLARITY_API_KEY,
});

const status = await clarity.status();
const preview = await clarity.previewTool({
  schema: "clarity.tool/v1",
  name: "Study outline",
  entry: "study.outline",
  consequenceClass: "C1",
  permissions: ["profile.read"],
  display: {
    layout: "list",
    icon: "list.bullet.rectangle",
    color: "blue",
    columns: [{ name: "Item", type: "text" }],
  },
});

Client surface

Every published operation is represented.

Read: status · profile · sessions · usage · webhooks · tools
Tool lifecycle: validateTool · previewTool
Delivery: testWebhook
Raw escape hatch: request(path, options)
Specification: Download OpenAPI 3.1

Security contract

No hidden retries. No secret persistence.

Key: Kept only in the calling server's memory; the client writes it neither to disk nor to logs.
Timeout: 12 seconds by default, configurable from 1 to 30 seconds; AbortSignal is supported.
Request ID: Every call carries a secure correlation ID and returns the server-confirmed ID.
Errors: ClarityDeveloperError contains the status, stable code, request ID and optional validation details.
Redirects: Fetch uses redirect:error so credentials do not follow a redirect to another domain.
Mutations: The client does not retry POST requests automatically.

Boundary

A client is not unrestricted platform access.

The client talks only to the sandbox. Keys are project-bound, expiring and revocable. Tools remain declarative, C0–C2 and human-reviewed. Private account, health, school and family data, native StoreKit entitlements and production credentials stay excluded.

View the API contract and error codes ›