@lytics/lio-client

TypeScript/JavaScript SDK for the Lytics API. Built with proven SDK patterns from jstag, designed with a plugin architecture for any Lytics integration.

What is lio-client?

A modern JavaScript/TypeScript SDK for the Lytics API. It fills the gap between Lytics' mature Go SDK and the JS/TS ecosystem.

Core Features:

• ✅ Full Lytics API access (workflows, content, schema, segments, etc.)
• ✅ Plugin architecture (extend with custom integrations)
• ✅ TypeScript-first with full type safety
• ✅ Works everywhere (Node.js, browser, edge functions)

Use it for:

• 🔌 Building custom integrations (CMS, marketing tools, etc.)
• 📊 Querying Lytics data from your applications
• 🔄 Monitoring workflows and sync status
• 🏗️ Creating marketplace apps

NOT for:

• ❌ User tracking (use jstag instead)
• ❌ Real-time personalization (use jstag + Lytics)

Packages

This is a monorepo with multiple packages:

Core SDK (Generic)

• @lytics/lio-client - Universal Lytics API client
  • Works with any Lytics account
  • Generic APIs: workflows, content, schema
  • No CMS-specific code
  • Framework-agnostic

Integration Plugins (Optional)

• @lytics/lio-client-contentstack - Contentstack CMS integration
  • Monitors contentstack-import workflow
  • Enriches Contentstack entries with Lytics data
  • Built for marketplace apps
  • Optional dependency

Quick Start

Installation

# Core client
npm install @lytics/lio-client
# With Contentstack integration
npm install @lytics/lio-client @lytics/lio-client-contentstack

Basic Usage

import{createLioClient}from'@lytics/lio-client';constlio=createLioClient({apiKey: process.env.LYTICS_API_KEY});// Query contentconstcontent=awaitlio.content.getByUrl('example.com/blog/post');console.log(content.lytics);// Topics: { "AI": 0.95, "Technology": 0.87 }// Monitor workflowsconstworkflows=awaitlio.workflows.list({workflow: 'contentstack-import'});// Get schemaconstschema=awaitlio.schema.get('content');

With Plugins (e.g., Contentstack)

import{createLioClient}from'@lytics/lio-client';import{contentstackPlugin}from'@lytics/lio-client-contentstack';constlio=createLioClient({apiKey: process.env.LYTICS_API_KEY,plugins: [contentstackPlugin()]});// Enrich a Contentstack entryconstenrichedEntry=awaitlio.contentstack.enrich(blogPost);console.log(enrichedEntry._lytics.topics);// Lytics topics added!

Development

This project uses modern TypeScript monorepo tooling:

• 📦 pnpm for package management
• 🏎️ Turborepo for builds
• 📦 tsup for bundling
• 🧪 Vitest for testing
• 🔍 Biome for linting

Setup

# Install dependencies
pnpm install
# Build all packages
pnpm build
# Run tests
pnpm test# Run in watch mode
pnpm dev

Project Structure

lio-client/
├── packages/
│ ├── core/ # @lytics/lio-client
│ └── contentstack/ # @lytics/lio-client-contentstack
├── pnpm-workspace.yaml
├── turbo.json
└── vitest.config.ts

Documentation

SDK Documentation

• Core Package - Core API reference
• Contentstack Plugin - CMS integration guide
• Building Plugins - Create your own integrations

Specifications

• API Discovery - Lytics API endpoints
• Architecture - Plugin design patterns
• Transport Layer - HTTP client architecture

External Resources

• Lytics API Docs - Official REST API
• Go SDK Reference - Go client reference

Contributing

See CONTRIBUTING.md for development workflow and guidelines.

License

MIT - Copyright (c) 2026 Lytics Inc.