@znjy/sdk

TypeScript SDK for ZNJY services.

The first supported module is marketData, which wraps the standalone ZNJY market-data HTTP service.

Documentation

• Usage guide
• AI usage prompt

Install

npm install @znjy/sdk

Browser Usage

Browser clients must not receive MARKET_DATA_SERVICE_TOKEN. Use browser clients for public read operations only.

import { ZnjyClient } from "@znjy/sdk";

const znjy = new ZnjyClient({
  baseUrl: "https://market-data.example.com",
});

const prices = await znjy.marketData.getPrices(["600000", "000001"]);
const matches = await znjy.marketData.searchStocks("浦发");
const sources = await znjy.marketData.getSourceStatus();
const market = await znjy.marketData.getMarketStatus();
const indices = await znjy.marketData.getIndices();
const indexKlines = await znjy.marketData.getIndexKlines({ codes: ["000001", "000300"], days: 250 });
const discovery = await znjy.marketData.getDiscovery("merged");
const global = await znjy.marketData.getInsight("global-market");

Server Usage

Use the service token only from server-side code such as API routes, workers, cron jobs, or backend services.

import { ZnjyClient } from "@znjy/sdk";

const znjy = new ZnjyClient({
  baseUrl: process.env.MARKET_DATA_BASE_URL!,
  serviceToken: process.env.MARKET_DATA_SERVICE_TOKEN!,
});

await znjy.marketData.syncSubscriptions({
  source: "manual",
  sourceRef: "portfolio-a",
  replaceSourceRef: true,
  items: [{ code: "600000", name: "浦发银行", market: "cn-a", priority: 100 }],
});

await znjy.marketData.refreshPrices();
await znjy.marketData.refreshSources({ codes: ["600000", "000001"], days: 60 });
await znjy.marketData.refreshInsights({ datasets: ["indices", "breadth"] });
await znjy.marketData.refreshIndexKlines({ codes: ["000001", "000300"], days: 250 });
await znjy.marketData.refreshDiscovery({ datasets: ["merged"] });

Recommended browser-to-admin flow:

Browser
  -> your backend/API route
    -> ZnjyClient with serviceToken
      -> market-data service

Market Data API

Browser-safe methods:

await znjy.marketData.getPrices(["600000", "000001"]);
await znjy.marketData.getPrices();
await znjy.marketData.searchStocks("浦发");
await znjy.marketData.getSourceStatus();
await znjy.marketData.getMarketStatus();
await znjy.marketData.getIndices();
await znjy.marketData.getIndexKlines({ codes: ["000001", "000300"], days: 250 });
await znjy.marketData.getDiscovery("merged");
await znjy.marketData.getCapitalFlow({ codes: ["600000", "000001"] });
await znjy.marketData.getKline("600000", 60);

Privileged methods require serviceToken:

await znjy.marketData.listSubscriptions({ active: "all", limit: 100 });
await znjy.marketData.syncSubscriptions({ source: "manual", items: [] });
await znjy.marketData.refreshPrices();
await znjy.marketData.refreshSources({ codes: ["600000", "000001"] });
await znjy.marketData.refreshInsights({ datasets: ["capital-flow"], codes: ["600000"] });
await znjy.marketData.refreshIndexKlines({ codes: ["000001", "000300"] });
await znjy.marketData.refreshDiscovery({ datasets: ["oversold", "bluechips", "merged"] });

listSubscriptions is intentionally treated as privileged by the SDK because subscription lists can reveal watchlists, portfolios, or internal source references.

Errors

import { ZnjyAuthError, ZnjyHttpError, ZnjyNetworkError } from "@znjy/sdk";

try {
  await znjy.marketData.refreshPrices();
} catch (err) {
  if (err instanceof ZnjyAuthError) {
    // Missing serviceToken for a privileged operation.
  } else if (err instanceof ZnjyHttpError) {
    console.error(err.status, err.code, err.message);
  } else if (err instanceof ZnjyNetworkError) {
    console.error(err.message);
  }
}

Development

bun install
bun test
bun run check
bun run build
npm pack --dry-run

Release

Dry-run the release flow without publishing:

bun run release:dry-run

Dry-run temporarily bumps the package version while npm builds the dry-run tarball, then restores package.json.

Publish a new patch version to npm:

bun run release

The release script runs tests, type-checking, bumps package.json from x.y.z to x.y.(z+1), rebuilds dist, then runs:

npm publish --access public --tag latest

Security

Never expose MARKET_DATA_SERVICE_TOKEN in browser bundles, mobile apps, public repositories, or client-side environment variables. Keep privileged calls on your server.