Quickstart

type NoxstockEnvelope<T> =
  | { data: T }
  | { error: { code: string; message: string; retryable: boolean } };

// A headline multiple is { value, vs_5y?, caveat? } when computable.
// Missing inputs return an { available: false, reason } object instead.
type QuickMultiple = { value: number; vs_5y?: string; caveat?: string };

type Snapshot = {
  symbol: string;
  freshness: string;
  as_of: string;
  quote?: { price?: number };
  fundamentals_quick?: { pe_ttm?: QuickMultiple };
};

const baseUrl = process.env.STOCKCONTEXT_API_BASE_URL ?? "https://api.stockcontext.com";
const apiKey = process.env.STOCKCONTEXT_API_KEY;

if (!apiKey) {
  throw new Error("Missing STOCKCONTEXT_API_KEY");
}

async function noxstockGet<T>(path: string, params: Record<string, string>) {
  const url = new URL(path, baseUrl);
  url.search = new URLSearchParams(params).toString();

  const response = await fetch(url, {
    headers: { "X-API-Key": apiKey },
    signal: AbortSignal.timeout(10_000),
    cache: "no-store",
  });

  const body = (await response.json()) as NoxstockEnvelope<T>;

  if ("error" in body) {
    const error = new Error(`${body.error.code}: ${body.error.message}`) as Error & {
      retryable?: boolean;
    };
    error.retryable = body.error.retryable;
    throw error;
  }

  if (!response.ok) {
    throw new Error(`HTTP ${response.status} without a StockContext error envelope`);
  }

  return body.data;
}

async function main() {
  const snapshot = await noxstockGet<Snapshot>("/v2/snapshot", { symbol: "AAPL" });
  const pe = snapshot.fundamentals_quick?.pe_ttm;
  const peValue = typeof pe === "number" ? pe : pe?.value;
  console.log(snapshot.symbol, snapshot.freshness, snapshot.as_of, snapshot.quote?.price, peValue);
}

main();