> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/sdk-reference/analytics-sdk/type-script-sdk/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# Typescript SDK

> Installation, configuration, and usage of the Alephant Analytics TypeScript SDK

The official Alephant Analytics TypeScript SDK provides access to the Alephant Analytics API from TypeScript and Node.js applications. It allows you to query telemetry, fetch daily usage series, and retrieve real-time summary statistics for FinOps dashboards.

## Installation

Install the SDK via npm, yarn, or pnpm:

```bash
npm install @alephantai/logs-collector-analytics
```

## Initialization

Import and initialize the client. The default environment is development (`https://analytics-dev.alephant.io`). Use the production environment only after the production Analytics service has been deployed.

```typescript
import {
  LogsCollectorAnalyticsClient,
  LogsCollectorAnalyticsEnvironment,
} from "@alephantai/logs-collector-analytics";

const client = new LogsCollectorAnalyticsClient({
  environment: LogsCollectorAnalyticsEnvironment.Development,
});
```

## Example Usage

### Smoke test

Use the public health endpoint to verify that the SDK can reach the Analytics dev service.

```typescript
const health = await client.analyticsAtomic.getHealth();
console.log(health.data.status);
```

### Live 24-hour panel

Retrieve a rolling live-24h dashboard panel. Authenticated SaaS analytics routes accept the `Authorization` and `X-Workspace-Id` headers as request fields.

```typescript
async function fetchLivePanel() {
  try {
    const response = await client.analyticsSaas.getSaasLive24H({
      limit: 5,
      Authorization: `Bearer ${process.env.ALEPHANT_API_TOKEN}`,
      "X-Workspace-Id": process.env.ALEPHANT_WORKSPACE_ID,
    });

    console.log(response.data);
  } catch (error) {
    console.error("Failed to fetch live panel:", error);
  }
}
```

### Retrieving usage series

Fetch daily usage metrics over a specified date range.

```typescript
async function fetchCostTimeseries() {
  const response = await client.analyticsSaas.getSaasUsage({
    dateFrom: "2026-03-01",
    dateTo: "2026-03-31",
    Authorization: `Bearer ${process.env.ALEPHANT_API_TOKEN}`,
    "X-Workspace-Id": process.env.ALEPHANT_WORKSPACE_ID,
  });

  console.log(response.data);
}
```

## Error Handling

The SDK throws structured errors for non-2xx API responses, allowing you to gracefully handle authentication, rate limits, or validation errors programmatically.

> Integrate Alephant Analytics into your TypeScript & Node.js applications