TypeScript and Node.js

The server client covers control-plane resources, participant session creation, results, continuous evaluation, analytics, and webhooks.

@apart-ai/synapse@0.1.0 currently requires access to the project’s GitHub Packages registry and Node.js 20 or newer.

Create a client

import { SynapseClient } from "@apart-ai/synapse";

const synapse = new SynapseClient({
  baseUrl: process.env.SYNAPSE_API_URL!,
  apiKey: process.env.SYNAPSE_ENVIRONMENT_KEY!,
});

// Generate once, persist with the workflow, and reuse after timeouts/restarts.
const requestId = crypto.randomUUID();
const scope = [organizationId, appId, environmentId] as const;

const { subject } = await synapse.subjects.upsert(
  ...scope,
  { externalId: authenticatedUser.id, profile: { locale: "en" } },
  { idempotencyKey: `${requestId}:subject` },
);

await synapse.programs.enroll(
  ...scope,
  { subjectId: subject.id, programId },
  { idempotencyKey: `${requestId}:enrollment` },
);

const session = await synapse.participantSessions.create(
  ...scope,
  { programId, subjectId: subject.id, expiresInSeconds: 3600 },
  { idempotencyKey: `${requestId}:session` },
);

console.log(session.hosted_url, session.expires_at);

expiresInSeconds defaults to one hour and accepts 300 seconds up to ten years (315360000). Resending the same launch with a new idempotency key while its session is still open returns that session and extends expires_at to at least expiresInSeconds from now; only the expiry may differ, and it is never shortened.

Namespaces

Namespace	Use it for
`organizations / apps / environments`	Tenant control plane and environment keys
`subjects`	Upsert, batch import, export, deletion, and legal holds
`definitions / bundles`	Governed scoring and presentation versions
`programs / participantSessions`	Deploy bundles, enroll subjects, and mint participant tokens
`evaluations / reports`	Internal results, drift, release decisions, and revocable shares
`continuousEvaluation`	Host events, due questions, answers, current alignment, and drift
`webhooks / analytics / audit`	Integrations and privacy-safe operational insight

Builder workflow

Environment keys may create and validate drafts. Publication, activation, evaluation release, and report-share management require an authenticated owner/admin session.

const cloned = await synapse.definitions.cloneTemplate(
  organizationId,
  appId,
  templateId,
  "advisor-alignment",
  { idempotencyKey: requestIds.clone },
);

// Edit and calibrate drafts first.
for (const definition of cloned.definitions) {
  await synapse.definitions.validate(organizationId, appId, definition.id);
  await synapse.definitions.transition(
    organizationId,
    appId,
    definition.id,
    "validated",
    { idempotencyKey: requestIds[definition.id] },
  );
}

const bundle = await synapse.bundles.create(
  organizationId,
  appId,
  {
    name: "Advisor alignment v1",
    experience_version_id: experienceId,
    scorecard_version_id: scorecardId,
    context_version_id: contextId,
    guardrail_version_id: guardrailId,
    adaptive_policy_version_id: adaptivePolicyId,
    report_template_version_id: reportId,
  },
  { idempotencyKey: requestIds.bundle },
);

Errors, retries, and pages

import { ApiError } from "@apart-ai/synapse";

try {
  await synapse.subjects.upsert(/* ... */);
} catch (error) {
  if (error instanceof ApiError) {
    console.error(
      error.status,
      error.detail,
      error.requestId,
      error.retryAfter,
    );
  }
  throw error;
}

Persist caller-generated idempotency keys across restarts. Automatic keys protect only one invocation.
List methods return { items, next_cursor }. Use the namespace’s listAll* helper when available.
Respect retryAfter for 429, and retry only transport errors plus supported 408, 425, 429, and 5xx responses.

Continue with browser and React integration or inspect the wire contract.