TypeScript SDK

@rstglobal/oneanalytics is the official TypeScript SDK for OneAnalytics. It's generated from the OpenAPI spec, ships typed models for every resource, and handles auth, pagination, and retries automatically.

Install

npm install @rstglobal/oneanalytics
# or
pnpm add @rstglobal/oneanalytics

Node 18+ and modern browsers supported (uses fetch).

Quickstart

import { OneAnalytics } from "@rstglobal/oneanalytics";

const oa = new OneAnalytics({
  baseUrl: "https://api.analytics.rstglobal.in",
  token:   process.env.OA_TOKEN!,
});

// list workspaces
const ws = await oa.workspaces.list({ limit: 100 });

// create one
const finance = await oa.workspaces.create({
  name: "Finance",
  description: "GL, AP, AR, cash",
});

// query a dataset
const result = await oa.datasets.query(datasetId, {
  dimensions: [{ id: "order_date", grain: "month" }],
  measures:   ["revenue"],
  filters:    [{ field: "region", op: "in", value: ["North", "South"] }],
  limit:      1000,
});

for (const row of result.rows) {
  console.log(row);
}

Pagination

list() returns an async iterator that handles cursors for you:

for await (const ws of oa.workspaces.listAll()) {
  console.log(ws.name);
}

Internally it calls listWorkspaces with next_cursor on every page until has_more: false.

Idempotency

Every POST method accepts an optional idempotencyKey string. Omit it and we generate a v4 UUID — safe by default. Pass one explicitly to make the same logical operation replayable:

await oa.sharing.create(
  { subjectType: "report", subjectId: rptId, principalType: "link", actions: ["view"] },
  { idempotencyKey: "export-2026-04-16-rpt-123" },
);

Errors

API errors throw OAError subclasses:

try {
  await oa.datasets.query(id, req);
} catch (e) {
  if (e instanceof OAError && e.code === "query/timeout") {
    // retry with simpler query
  }
  throw e;
}

e.code, e.status, e.traceId, e.detail are all populated from the problem+json response.

Retries

Built-in: 5xx and 429 are retried with exponential backoff (5 attempts, capped at 30 s total). Override:

const oa = new OneAnalytics({ token, retry: { maxAttempts: 3, maxDelayMs: 10_000 } });

Streaming query results (Apache Arrow)

const arrow = await oa.datasets.queryArrow(datasetId, req);  // Uint8Array stream

20× faster than JSON for large result sets. Parse with apache-arrow.

Browser safety

The SDK is safe in the browser only with short-lived tokens minted by your backend. Never ship a long-lived API token to the browser.