Core SDK (TypeScript)

v0.1.4 Advanced

@usergist/sdk-core is the shared contract layer used by the API server, dashboard, and every native SDK. It contains:

Strongly-typed shapes for Event, Prompt, Survey, Campaign, Segment, Response.
Pure targeting and branching evaluators used by the API and by verified offline-preview/test paths. Production delivery decisions for every platform SDK come from the server's durable instruction inbox.
nextQuestionId(flow, q, answers) for survey branching.
API endpoint definitions (endpoints object) used for code-gen on every platform.
Push runtime types.

Who needs this

Most apps don't import @usergist/sdk-core directly. Use it when you're building a custom integration—a server-side automation, an internal admin tool, or a non-listed platform.

Install

pnpm add @usergist/sdk-core

Shared types

import type { Event, Survey, Segment, Response } from '@usergist/sdk-core'
 
const event: Event = {
  id: 'evt_123',
  name: 'checkout_completed',
  userId: 'user_42',
  timestamp: '2026-01-12T00:00:00Z',
  properties: { amountUsd: 49 },
}

Segment evaluation

import { evaluateSegment } from '@usergist/sdk-core'
 
const segment = {
  any: [
    { event: 'session_started', count: { gte: 5, window: '7d' } },
    { property: 'plan', op: 'eq', value: 'pro' },
  ],
}
 
const user = {
  userId: 'user_42',
  properties: { plan: 'pro' },
  events: [{ name: 'session_started', timestamp: '2026-01-10T12:00:00Z' }],
}
 
const inSegment: boolean = evaluateSegment(segment, user, new Date())

Survey branching

import { nextQuestionId } from '@usergist/sdk-core'
 
const flow = {
  questions: [
    { id: 'q1', type: 'nps', next: { gte: 9, then: 'q2', else: 'q3' } },
    { id: 'q2', type: 'text', next: null },
    { id: 'q3', type: 'text', next: null },
  ],
}
 
const next = nextQuestionId(flow, 'q1', { q1: 10 }) // → 'q2'

Endpoint definitions

import { endpoints } from '@usergist/sdk-core'
 
await fetch(`https://api.usergist.com${endpoints.ingest.url}`, {
  method: endpoints.ingest.method,
  headers: {
    Authorization: `Bearer ${process.env.USERGIST_WRITE_KEY!}`,
    'X-UserGist-Subject-Token': subjectToken,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ context, events: [/* … */] }),
})

See API → Ingest for the wire format.

Building your own SDK

If you're porting userGist to a platform we don't ship today (e.g. server-side Node, Unity, native macOS):

Implement init / identify / track against the REST contract in endpoints.
Implement anonymous and identified subject sessions plus durable instruction polling; do not authorize identity from a caller-supplied ID.
Use nextQuestionId for branching surveys.
Open a discussion — we'd love to upstream community SDKs.