telescope-ai

telescope-ai

Official JavaScript/TypeScript client for the Telescope API.

Features

• Full TypeScript support with strict typing
• Supports Telescope's v2 SSE streaming format
• React hooks with automatic re-render batching

Installation

npm install -S telescope-ai

Quick Start

Basic Usage

import { TelescopeClient } from "telescope-ai";

const client = new TelescopeClient({
  apiKey: "your-api-key",    // defaults to TELESCOPE_API_KEY in backend environments
  connectTimeout: 30000,     // optional, max ms to wait for server response (default: 30s)
  debug: false,              // optional, enables console logging
});

// Use namespaced product APIs
const data = await client.insights.instrument.generate({
  instrument_reference_id1: "AAPL_US",
});

Streaming Example

import { TelescopeClient } from "telescope-ai";

const client = new TelescopeClient({ apiKey: "your-api-key" });

// Start a streaming request
const session = client.insights.instrument.stream({
  instrument_reference_id1: "AAPL_US",
});

// Subscribe to updates
session.subscribe({
  onPatch: (data) => {
    console.log("Progress:", data.groups?.length, "groups loaded");
  },
  onComplete: (data) => {
    console.log("Complete:", data);
  },
  onError: (error) => {
    console.error("Stream error:", error);
  },
});

// Or await the final result
const result = await session.complete();

React Integration

import { useInstrumentInsights } from "telescope-ai/react";

function InstrumentView({ instrumentId }: { instrumentId: string }) {
  const { data, isStreaming, isComplete, stream } = useInstrumentInsights({
    clientToken: "your-client-token", // or apiKey: "your-api-key" for backend usage
  });

  useEffect(() => {
    stream({ instrument_id: instrumentId });
  }, [instrumentId, stream]);

  if (isStreaming) {
    return <div>Loading insights...</div>;
  }

  return (
    <div>
      <h1>{data.instrument?.title}</h1>
      {data.groups?.map((group, i) => (
        <section key={i}>
          <h2>{group.title}</h2>
          <p>{group.content}</p>
        </section>
      ))}
    </div>
  );
}

API Reference

Full documentation is available at docs.telescope.co/sdk.

TelescopeClient

The main client class for interacting with the Telescope API.

const client = new TelescopeClient({
  apiKey?: string;      // Organization API key (starts with `tsk_`). Defaults to TELESCOPE_API_KEY env var.
  clientToken?: string; // Client token for frontend use (starts with `tsc_`). Cannot be used with apiKey.
  baseUrl?: string;     // API base URL (default: https://api.telescope.co)
  connectTimeout?: number; // Max ms to wait for server to start responding (default: 30000)
  debug?: boolean;      // Enable debug logging (default: false)
});

Properties

• TelescopeClient.VERSION - Static property containing the SDK version
• client.insights - Namespaced access to Insights API

Methods

Method	Description
get<T>(path, options?)	Make a GET request
post<T>(path, body?, options?)	Make a POST request
request<T>(path, options?)	Make a generic HTTP request
stream<T>(path, body, options?)	Start an SSE streaming request
streamFromResponse<T>(source)	Create a StreamSession from a pre-existing SSE response
generateClientToken()	Generate a client token for frontend use

Insights API

Access via client.insights. Uses a nested sub-client pattern with instrument and portfolio namespaces.

// Streaming
const session = client.insights.instrument.stream({ instrument_reference_id1: "AAPL_US" });
const session = client.insights.portfolio.stream({ instrument_reference_id1s: ["AAPL_US", "GOOGL_US"] });

// Non-streaming
const data = await client.insights.instrument.generate({ instrument_reference_id1: "AAPL_US" });
const data = await client.insights.portfolio.generate({ instrument_reference_id1s: ["AAPL_US", "GOOGL_US"] });

// From proxy/custom fetch responses
const session = client.insights.instrument.streamFromResponse(response);
const data = await client.insights.portfolio.generateFromResponse(response);

Note: Ripple and Guardrails clients are coming in a future release once their backends support the V2 SSE format.

StreamSession

Returned by streaming methods. Provides real-time access to streaming data.

const session = client.insights.instrument.stream({ instrument_reference_id1: "AAPL_US" });

// Current data (updates in real-time)
console.log(session.data);

// Current status
console.log(session.status); // { phase: 'streaming', startedAt: 1234567890 }

// Subscribe to events
const unsubscribe = session.subscribe({
  onPatch: (data, event) => { /* called on each update */ },
  onPathComplete: (path, data) => { /* called when a path finishes */ },
  onComplete: (data) => { /* called when stream completes */ },
  onError: (error) => { /* called on SSE errors */ },
  onTransportError: (error) => { /* called on connection errors */ },
  onHeartbeat: () => { /* called on heartbeat events */ },
  onStatusChange: (status) => { /* called on any status change */ },
});

// Wait for completion
const finalData = await session.complete();

// Cleanup
unsubscribe();

Error Handling

The SDK provides a typed error hierarchy. All errors extend TelescopeClientError.

import {
  TelescopeClientError,
  ApiError,
  NetworkError,
  StreamingError,
  SSEError,
} from "telescope-ai";

try {
  const data = await client.get("/v2/endpoint");
} catch (error) {
  if (error instanceof ApiError) {
    console.log(error.status, error.body);
  } else if (error instanceof NetworkError) {
    console.log(error.message);
  }
}

Error	Description
ApiError	HTTP errors from the API (4xx, 5xx). Has status and body properties.
NetworkError	Connection failures, timeouts, DNS errors.
StreamingError	Transport-level streaming failures (connection dropped, bad content-type). Has an optional status property.
SSEError	Application-level errors received via SSE error events. Has code, httpStatus, and optional path properties.

Security Warning

Do not expose your API key in client-side code.

For browser applications, use client tokens:

// Backend: Generate a client token
const serverClient = new TelescopeClient({ apiKey: process.env.TELESCOPE_API_KEY });
const clientToken = await serverClient.generateClientToken();

// Frontend: Use the client token
const browserClient = new TelescopeClient({ clientToken });

Client tokens have limited permissions and expire after a short time, making them safe for frontend use.

TypeScript

This package includes TypeScript declarations. No additional @types package is needed.

import type {
  TelescopeClientOptions,
  StreamSession,
  StreamStatus,
  StreamPhase,
  InstrumentInsightsResponse,
} from "telescope-ai";

Browser Support

This SDK supports modern browsers (ES2022+) and Node.js 18+.

For older environments, you may need to polyfill:

• AbortSignal.timeout()
• fetch()

License

MIT - see LICENSE for details.

Links

• Documentation
• npm
• Changelog