TypeScript Client — Clarity Developer

Quickstart

Keep the key on your server.

Das Modul läuft in Node.js, Deno und kompatiblen Server-Runtimes mit Fetch und Web Crypto. Es ist absichtlich kein Browser-SDK: Ein Sandbox-Key darf nie in JavaScript, iOS-Bundles oder öffentliche Repositories eingebettet werden.

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: OpenAPI 3.1 herunterladen

Security contract

No hidden retries. No secret persistence.

Key: Nur im Speicher des aufrufenden Servers; der Client schreibt ihn weder auf Disk noch in Logs.
Timeout: Standardmäßig 12 Sekunden, zulässig 1–30 Sekunden; AbortSignal wird unterstützt.
Request ID: Jeder Aufruf trägt eine sichere Korrelations-ID und gibt die serverbestätigte ID zurück.
Errors: ClarityDeveloperError enthält Status, stabilen Code, Request-ID und optionale Validierungsdetails.
Redirects: Fetch läuft mit redirect:error, damit Credentials keiner umgeleiteten Domain folgen.
Mutationen: Der Client wiederholt POST-Aufrufe nicht automatisch.

Boundary

A client is not unrestricted platform access.

Der Client spricht ausschließlich mit der Sandbox. Schlüssel sind projektgebunden, ablaufend und widerrufbar. Tools bleiben deklarativ, C0–C2 und menschlich geprüft. Private Account-, Health-, School- und Family-Daten, native StoreKit-Rechte sowie Produktions-Credentials bleiben ausgeschlossen.

API-Vertrag und Fehlercodes ansehen ›