@mozaik-ai/cloud-sdk

Send events to mozaik cloud from any Node app — no Mozaik runtime required. Running a Mozaik runtime? Import the exporter from @mozaik-ai/cloud-sdk/exporter — a Participant that joins the bus and forwards everything automatically (@mozaik-ai/core is an optional peer, needed only for that entrypoint).

Setup

Put your credentials in the environment or a .env file in the working directory:

MOZAIK_API_KEY=pk_...
MOZAIK_PROJECT_ID=prj_...

MOZAIK_API_KEY authenticates (the server derives the project from it); MOZAIK_PROJECT_ID is the project's handle shown in the UI — informational for now. Both are shown on first sign-in at https://app.jigjoy.ai. MOZAIK_PROJECT_KEY is accepted as a legacy alias for the key. No key found? The client never throws — it logs one warning and returns a disabled no-op client (enabled: false), so instrumented apps run unchanged without credentials. Optional overrides: MOZAIK_CLOUD_ENDPOINT (default https://api.app.jigjoy.ai), MOZAIK_CLOUD_APP_URL.

Pairing — no key copying

npx @mozaik-ai/cloud-sdk pair

Prints a short code and an approve link; open it in the browser where you're signed in to app.jigjoy.ai, click Approve device, and the key lands in ~/.mozaik/credentials.json (0600). From then on createCloudClient() finds it on its own — no .env needed. First-time users get their project created by the same click. Programmatic: await pairDevice() from the package does the same.

Credential resolution order: projectKey option → MOZAIK_API_KEY → MOZAIK_PROJECT_KEY (legacy) → paired credentials for the endpoint.

Usage

import { createCloudClient } from "@mozaik-ai/cloud-sdk"

const client = createCloudClient() // prints ▶ watching live: https://app.jigjoy.ai/?s=<sessionId>

client.send({ type: "inference.started", producerId: "planner", payload: { model: "glm-5.2" } })
client.send({ type: "inference.completed", producerId: "planner", payload: { answer: "..." } })

await client.end() // flushes and closes the session

• send({ type, payload, producerId?, occurredAt? }) — batched (100 events or 1s, whichever first). Unknown producers are auto-announced as agents; call client.join({ id, name, role }) first if you want a different name/role in the roster.
• Event types the loop view understands: message_received.*, inference.started|stream|completed, function_call.started|completed, model.answer. Anything else is stored and listed, just not drawn as a loop state.
• Full payloads ship by default. For privacy set MOZAIK_REDACTION=content (strips prompts/answers/tool output, keeps shape + sizes — the UI then shows {"redacted":true,"chars":1076}) or all (event types only); the redaction option does the same in code.
• client.sessionUrl is the live view; flush() forces a send; stats() shows queued/sent/dropped.

Options

createCloudClient({ projectKey, endpoint, sessionId, redaction, batchSize, flushIntervalMs, appUrl, envFile, onError, onSessionUrl, fetch }) — everything optional; env/.env fills the gaps. envFile: false disables .env reading.

Mozaik runtime exporter

Inside a Mozaik app, skip manual send() — join the exporter to the runtime and every bus event is forwarded automatically:

import { createCloudExporter } from "@mozaik-ai/cloud-sdk/exporter"

const cloud = createCloudExporter({
  endpoint: "https://api.app.jigjoy.ai",
  projectKey: process.env.MOZAIK_API_KEY!,
  participants: () => runtime.state.getParticipants(), // roster source
})
join(cloud.participant)
// ...
await cloud.end()

It synthesizes session.started / participant.joined / session.ended, batches, retries, caps payloads and honours MOZAIK_REDACTION exactly like the client. Requires @mozaik-ai/core >= 4.0.0-beta.1 (optional peer — the root entrypoint never loads it).