Tidelight TypeScript SDK

Official TypeScript client for supported Tidelight Intelligence Cloud v1 market, asynchronous company research, and webhook endpoints. Research calls require research:run; webhook calls require alerts:manage.

Install with npm install @tidelight/sdk. Keep the API key on your server.

Build locally with npm run build in this directory.

import { TidelightClient } from "@tidelight/sdk";

const client = new TidelightClient({ apiKey: process.env.TIDELIGHT_API_KEY! });
const page = await client.listTokenizedEquities({ limit: 20, underlyingTicker: "AAPL" });
for (const instrument of page.data) console.log(instrument.symbol, instrument.underlying_ticker);

for await (const instrument of client.tokenizedEquities({ limit: 50 })) {
  console.log(instrument.symbol);
}

const accepted = await client.startCompanyResearch("NVDA", crypto.randomUUID());
const result = await client.waitForResearchJob(accepted.job_id, { intervalMs: 2000, timeoutMs: 120000 });
if (result.status === "complete") console.log(result.result);

const created = await client.createWebhook({
  name: "Research events",
  url: "https://your-service.example/tidelight",
  events: ["research.job.completed", "research.job.failed"],
});
if (!created.signing_secret) throw new Error("The create response did not include its one-time signing secret.");
// TODO: Persist created.signing_secret with your approved secrets manager before
// finishing setup. Do not print it. It cannot be recovered by listing the endpoint.
const deliveries = await client.listWebhookDeliveries();
console.log(deliveries.deliveries);

Webhook mutations are not retried automatically because the API does not yet accept webhook idempotency keys; this avoids duplicate endpoint creation or secret rotation after an ambiguous timeout. Webhook destination reachability and DNS safety are checked by the API. A client-side HTTPS check is not an authorization to deliver to a destination.

The client retries network errors, 429, and transient 5xx statuses at most twice by default. It enforces a 10 second request timeout and returns TidelightApiError with status, code, and request ID.

Run the asynchronous research example

From a mother-repository checkout:

npm ci --prefix sdk/typescript
npm test --prefix sdk/typescript
export TIDELIGHT_API_KEY='tl_test_…'
node sdk/typescript/examples/research.mjs NVDA

The example calls the SDK company snapshot job flow and prints a result only after the API reports complete. It preserves job and request IDs and never prints the key. CI injects a mock transport and makes no network calls. A live run requires research:run and consumes project quota (10 jobs per rolling hour).