@stoxim/client

Official TypeScript SDK for the Stoxim Financial Data API — company master, financials, ratios, shareholding patterns, corporate actions, governance, and announcements for BSE/NSE-listed companies.

Installation

npm install @stoxim/client

Requires Node.js 20+. Zero runtime dependencies — uses native fetch.

Quick Start

import { StoximClient } from "@stoxim/client";

const client = new StoximClient({ apiKey: "sk_live_your_key_here" });

// ── Company lookup ─────────────────────────────────────────────────────────────
const company = await client.getCompany("INE040A01034");
console.log(company.name, company.sector);
// HDFC Bank  Financial Services

// ── Search ─────────────────────────────────────────────────────────────────────
const results = await client.searchCompanies("Bajaj Finance", 5);
for (const c of results.items) {
  console.log(c.isin, c.name);
}

// ── Financial periods ──────────────────────────────────────────────────────────
const financials = await client.listFinancials("INE040A01034", {
  period_type: "annual",
  limit: 5,
});
for (const p of financials.items) {
  console.log(p.period_label, p.revenue, p.pat);
}

// ── Ratios (includes gross_margin) ────────────────────────────────────────────
const ratios = await client.getRatios("INE040A01034", "annual");
for (const r of ratios.items) {
  console.log(r.period_label, r.roe, r.gross_margin, r.pe_ratio);
}

// ── Shareholding pattern ───────────────────────────────────────────────────────
const shareholding = await client.listShareholding("INE040A01034");
for (const s of shareholding.items) {
  console.log(s.period_end, s.promoter_pct, s.fii_pct);
}

// ── Corporate actions ──────────────────────────────────────────────────────────
const actions = await client.listCorporateActions("INE040A01034", {
  action_type: "dividend",
});
for (const a of actions.items) {
  console.log(a.ex_date, a.dividend_amount);
}

// ── Board composition (Starter+ plan) ─────────────────────────────────────────
const board = await client.getBoardComposition("INE040A01034");
for (const member of board.items) {
  console.log(member.name, member.designation);
}

// ── AGM records ────────────────────────────────────────────────────────────────
const agms = await client.getAGMRecords("INE040A01034");

// ── Related-party transactions ─────────────────────────────────────────────────
const rpts = await client.getRelatedPartyTransactions("INE040A01034");

// ── Announcements ──────────────────────────────────────────────────────────────
const announcements = await client.listAnnouncements("INE040A01034", {
  category: "financials",
  from_date: "2024-01-01",
});
for (const ann of announcements.items) {
  console.log(ann.filing_date, ann.subject);
}

Pagination

for await (const page of client.paginateCompanies({ market_cap_category: "large" })) {
  for (const company of page) {
    console.log(company.isin, company.name);
  }
}

Error Handling

import {
  AuthenticationError,
  NotFoundError,
  PlanRestrictionError,
  RateLimitError,
  InvalidParameterError,
  ApiError,
} from "@stoxim/client";

try {
  const company = await client.getCompany("INVALID_ISIN");
} catch (e) {
  if (e instanceof NotFoundError) {
    console.error("Not found:", e.message);
  } else if (e instanceof PlanRestrictionError) {
    console.error("Upgrade your plan to access this endpoint");
  } else if (e instanceof RateLimitError) {
    console.error(`Rate limited — retry after ${e.retryAfter}s`);
  } else if (e instanceof AuthenticationError) {
    console.error("Invalid API key");
  } else if (e instanceof ApiError) {
    console.error(`[${e.errorCode}] ${e.message}`);
  }
}

Configuration

const client = new StoximClient({
  apiKey: "sk_live_...",
  timeout: 60_000,     // ms (default: 30_000)
  maxRetries: 5,       // default: 3
  retryOn429: true,    // respect Retry-After header on 429 (default: true)
  baseUrl: "https://api.stoxim.com/v1",  // override for testing
});

Development

npm install
npm run build       # tsc
npm run typecheck   # tsc --noEmit
npm test            # vitest run

Publishing

npm run build
npm pack --dry-run
npm publish --access public

License

MIT — see LICENSE.