Kelviq Node SDK

The official Node.js SDK for interacting with the Kelviq API. Manage customers, checkout sessions, entitlements, usage reporting, and subscriptions from your backend.

Installation

npm install @kelviq/node-sdk

Quick Start

import { Kelviq } from '@kelviq/node-sdk';

const client = new Kelviq({ accessToken: process.env.KELVIQ_API_KEY });

// Check feature access
const hasAccess = await client.entitlements.hasAccess({
  customerId: "cust_123",
  featureId: "premium-reporting"
});

Caching & Offline Resilience

The SDK includes a two-tier cache that keeps entitlement checks fast and lets your app keep working during transient network/API outages.

• L1 — in-memory (on by default): entitlements are cached per-process. Fresh entries (within the TTL) are served without a network call; if the API is unreachable or returns a 5xx, the last-known value is served as a fallback.
• L2 — distributed (optional): a shared store (e.g. Redis) so the cache and the offline usage queue are shared across processes and containers, and survive restarts.

Read-through order is L1 → L2 → API, with write-through to both on every successful fetch. Usage reports that fail due to a network error are queued and replayed automatically on the next report call (or via client.reporting.flush()).

Configuration

const client = new Kelviq({
  accessToken: process.env.KELVIQ_API_KEY,
  enableCache: true,   // default true
  cacheTtlMs: 60_000,  // freshness window in ms (default 60000)
});

Set enableCache: false to disable caching entirely.

Distributed cache (Redis)

Redis support uses ioredis (an optional dependency):

npm install ioredis

Pass a RedisStore as cacheStore:

import { Kelviq, RedisStore } from '@kelviq/node-sdk';

const store = new RedisStore({ url: 'redis://localhost:6379/0', prefix: 'kelviq:prod' });
const client = new Kelviq({ accessToken: process.env.KELVIQ_API_KEY, cacheStore: store });

RedisStore also accepts host/port/db, or a pre-configured client via new RedisStore({ client: myRedis }). All instances that should share a cache must use the same prefix.

Multi-instance note: with only L1, each Node process / container has its own cache and offline queue. Configure an L2 cacheStore (Redis) so multiple replicas share one cache and a durable usage queue. (A single-process, single-instance deployment already shares one L1 cache across all requests.)

Bring your own store

RedisStore implements the public CacheStore interface. To use another backend, implement CacheStore and pass it as cacheStore. Every method may be sync or return a Promise:

import { CacheStore } from '@kelviq/node-sdk';

class MyStore implements CacheStore {
  get(key: string): Promise<string | null> | string | null { /* ... */ }
  set(key: string, value: string, ttlSeconds?: number): Promise<void> | void { /* ... */ }
  delete(key: string): Promise<void> | void { /* ... */ }
  listAppend(key: string, value: string): Promise<void> | void { /* ... */ }
  listPopAll(key: string): Promise<string[]> | string[] { /* ... */ } // should be atomic
  listPrependMany(key: string, values: string[]): Promise<void> | void { /* ... */ }
}

The SDK serialises all values to JSON strings. The store is treated as best-effort: if it errors, the SDK logs and falls back to L1 + network rather than failing.

Flushing queued usage

Offline reports flush automatically on the next reportUsage/reportEvent. To flush explicitly (e.g. on a timer or before shutdown):

const remaining = await client.reporting.flush(); // count still queued

Documentation

For full documentation, including setup guides and API reference, visit docs.kelviq.com.

License

MIT