telescope-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Telescope AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,280 @@
+# telescope-ai
+
+Official JavaScript/TypeScript client for the [Telescope API](https://docs.telescope.co/sdk).
+
+## Features
+
+- Full TypeScript support with strict typing
+- Supports Telescope's v2 SSE streaming format
+- React hooks with automatic re-render batching
+
+## Installation
+
+```bash
+npm install -S telescope-ai
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+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
+
+```typescript
+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
+
+```tsx
+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](https://docs.telescope.co/sdk).
+
+### TelescopeClient
+
+The main client class for interacting with the Telescope API.
+
+```typescript
+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
+- `client.atlas` - Namespaced access to Atlas 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.
+
+```typescript
+// 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);
+```
+
+### Atlas API
+
+Access via `client.atlas`:
+
+```typescript
+// Streaming
+const session = client.atlas.streamAdvice({
+  advisor_environment_id: "...",
+  client_details: "...",
+  // ... other required fields
+});
+
+// Non-streaming
+const advice = await client.atlas.getAdvice("advice-id");
+const recent = await client.atlas.getLatestAdvice(30);
+await client.atlas.archiveAdvice(["id1", "id2"], true);
+```
+
+> **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.
+
+```typescript
+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`.
+
+```typescript
+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:
+
+```typescript
+// 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.
+
+```typescript
+import type {
+  TelescopeClientOptions,
+  StreamSession,
+  StreamStatus,
+  StreamPhase,
+  InstrumentInsightsResponse,
+  AtlasAdviceResponse,
+} 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](./LICENSE) for details.
+
+## Links
+
+- [Documentation](https://docs.telescope.co/sdk)
+- [npm](https://www.npmjs.com/package/telescope-ai)
+- [Changelog](./CHANGELOG.md)