npm package: @jedify/sdk
Description: TypeScript SDK for Jedify semantic functions
Author: Jedify
Latest version: 3.0.0

# @jedify/sdk

TypeScript SDK for calling Jedify semantic functions (cloud functions).

## Installation

```bash
npm install @jedify/sdk
```

## Quick Start

### Backend Usage (Node.js)

```typescript
import { Jedify } from '@jedify/sdk';

// API key is REQUIRED (TypeScript enforced)
const jedify = new Jedify({
  apiKey: process.env.JEDIFY_API_KEY,  // Get from: https://app.jedify.com/settings/api-keys
  baseUrl: 'https://be-dev.jedify.com'  // Optional: for dev environment
});

// List available functions
const { functions } = await jedify.listFunctions();
console.log(`Found ${functions.length} functions`);

// Call a function - returns data array directly (v2.0)
const data = await jedify.call('_REVENUE_BY_PRODUCT', {
  region: 'North America',
  start_date: '2025-01-01',
  end_date: '2025-03-31',
});

// ⚠️ Field names are UPPERCASE (Snowflake behavior)
data.forEach(row => {
  console.log(row.PRODUCT_CATEGORY, row.TOTAL_REVENUE);  // UPPERCASE!
});
```

### Error Handling

```typescript
try {
  const data = await jedify.call('_REVENUE', params);
  console.log(`Got ${data.length} rows`);
  setData(data);
} catch (error) {
  if (error instanceof JedifyExecutionError) {
    console.error('Execution failed:', error.message);
    console.error('SQL:', error.sqlExecuted);
  }
}
```

## API Reference

### Constructor

```typescript
const jedify = new Jedify(config: JedifyConfig);
```

**Config options:**

- `apiKey` (string, **REQUIRED**): Jedify API key. Get from https://app.jedify.com/settings/api-keys
- `baseUrl` (string, optional): API base URL. Default: `https://api.jedify.com`
- `timeout` (number, optional): Request timeout in milliseconds. Default: `30000` (30 seconds)
- `maxRetries` (number, optional): Max retry attempts for 5xx errors. Default: `3`
- `headers` (object, optional): Custom headers for every request
- `debug` (boolean, optional): Enable debug logging. Default: `false`

### Methods

#### `listFunctions(filters?)`

List available semantic functions.

```typescript
const result = await jedify.listFunctions({
  search: 'revenue',      // Optional: search in name/description
  category: 'sales',      // Optional: filter by category
  limit: 100,             // Optional: results per page
  offset: 0,              // Optional: pagination offset
});

// Returns: ListFunctionsResult
{
  functions: FunctionSchema[],  // Array of functions with full schemas
  total: number,                // Total matching functions
  limit: number,
  offset: number
}
```

#### `getSchema(functionName)`

Get detailed schema for a specific function.

```typescript
const schema = await jedify.getSchema('_REVENUE_BY_PRODUCT');

// Returns: FunctionSchema
{
  function_id: string,
  name: string,
  description: string,
  parameters: ParameterDefinition[],  // Input parameters
  output_schema: OutputColumn[],      // Output columns
  example_usage: {
    typescript: string,               // TS example code
    python: string                    // Python example code
  }
}
```

#### `call(functionName, parameters?, options?)`

Execute a semantic function. Returns data array directly, throws exceptions on errors.

```typescript
// Returns T[] directly
const data = await jedify.call('_REVENUE_BY_PRODUCT', {
  region: 'Europe',
  start_date: '2025-01-01',
  end_date: '2025-12-31'
});

// ⚠️ Field names are UPPERCASE (Snowflake)
data.forEach(row => {
  console.log(row.PRODUCT_CATEGORY, row.TOTAL_REVENUE);  // UPPERCASE!
});
```

**Options:**
```typescript
{
  fetchAll?: boolean,    // Auto-fetch all pages
  page?: number,         // Manual pagination: page number
  limit?: number,        // Manual pagination: rows per page
  timeout?: number,      // Override default timeout
  signal?: AbortSignal   // For cancellation
}
```

## Features

### Automatic Pagination

```typescript
// Fetch all pages automatically
const allData = await jedify.call('_LARGE_DATASET', {}, { fetchAll: true });
console.log(`Got ${allData.length} rows`);
```

### Available Error Classes

```typescript
import {
  JedifyExecutionError,      // SQL execution failed
  JedifyValidationError,     // Invalid parameters
  JedifyHttpError,           // HTTP errors (401, 404, etc.)
  JedifyTimeoutError,        // Request timeout
  JedifyNetworkError,        // Network failure
} from '@jedify/sdk';
```

## TypeScript Support

```typescript
interface RevenueRow {
  PRODUCT_CATEGORY: string;  // ← UPPERCASE (Snowflake)
  TOTAL_REVENUE: number;
}

const data = await jedify.call<RevenueRow>('_REVENUE_BY_PRODUCT', {});
data.forEach(row => console.log(row.PRODUCT_CATEGORY, row.TOTAL_REVENUE));
```

## Requirements

- Node.js >= 18.0.0
- TypeScript >= 5.0 (for type definitions)

## License

MIT