@infactory/infactory-ts/README.md

Infactory TypeScript SDK for use with Infactory Workshop, MCP Server and API

# Infactory TypeScript SDK

Official TypeScript SDK for interacting with the Infactory AI platform. This SDK allows you to programmatically access and manage your data, projects, and queries through the Infactory API.

## Installation

```bash
npm install @infactory/infactory-ts
```

## Configuration

Before using the SDK, you need to set up your Infactory API credentials:

1. Obtain an API key from the [Infactory Workshop](https://workshop.infactory.ai/api-keys)
2. Use the API key to initialize the client

## Quick Start

```typescript
import { InfactoryClient } from '@infactory/infactory-ts';

// Initialize the client with your API key
const client = new InfactoryClient({
  apiKey: 'your-api-key-here',
  // Optional: baseURL: 'https://api.infactory.ai' // Use custom API endpoint if needed
});

// Example: Get current user information
async function getCurrentUser() {
  const response = await client.users.getCurrentUser();
  if (response.error) {
    console.error(`Error: ${response.error.message}`);
    return null;
  }
  return response.data;
}

// Example: List all projects
async function listProjects() {
  const response = await client.projects.getProjects();
  if (response.error) {
    console.error(`Error: ${response.error.message}`);
    return [];
  }
  return response.data;
}
```

## Environment Variables

The SDK supports loading configuration from environment variables:

```bash
# Required
NF_API_KEY=your-api-key-here

# Optional - defaults to https://api.infactory.ai
NF_BASE_URL=https://api.infactory.ai
```

You can load these variables from a `.env` file using dotenv:

```typescript
import * as dotenv from 'dotenv';
import { InfactoryClient } from '@infactory/infactory-ts';

// Load environment variables
dotenv.config();

// Create client using environment variables
const client = new InfactoryClient({
  apiKey: process.env.NF_API_KEY || '',
});
```

## Available APIs

The SDK provides access to the following Infactory API resources:

- **Build** - Create and manage query programs, APIs, and other build-time assets
- **Run** - Execute query programs and APIs
- **Connect** - Manage connections to external data sources and services
- **Projects** - Create and manage projects
- **Teams** - Manage teams and team memberships
- **Organizations** - Access organization information
- **Users** - User management and authentication
- **Auth** - API key management
- **Chat** - Interact with the chat interface
- **Chat Integrations** - Work with chat tools and custom functions
- **Knowledge Graph** - Create and manage knowledge graphs
- **Datasources** - Connect to and manage data sources
- **Datalines** - Access and transform data
- **QueryPrograms** - Create, run, and publish queries
- **APIs** - Deploy and manage API endpoints
- **Credentials** - Manage connection credentials
- **Integrations** - Work with third-party integrations like Fivetran
- **Secrets** - Store and manage secrets
- **Tasks** - Track and manage tasks
- **Events** - Access event information
- **MCP** - Management Control Plane for administrative operations

## Common Workflows

### Creating a Project and Uploading Data

```typescript
// Create a new project
const projectResponse = await client.projects.createProject({
  name: 'Stock Analysis Project',
  teamId: teamId,
  description: 'Project for analyzing stock data',
});
const project = projectResponse.data;

// Upload a CSV file
const csvFilePath = './data/stocks.csv'; // Replace with your actual CSV file path
const uploadResult = await client.datasources.uploadCsvFile(
  project.id,
  csvFilePath,
  'Stock Data',
);

const datasource = uploadResult.datasource;
console.log(
  `Uploaded CSV to datasource: ${datasource.name} (${datasource.id})`,
);
```

### Working with Query Programs

```typescript
// Get query programs for a project
const queryProgramsResponse = await client.queryPrograms.listQueryPrograms({
  projectId,
});
const queryPrograms = queryProgramsResponse.data;

// Evaluate a query program
const evaluateResponse = await client.run.evaluateQueryProgram(
  projectId,
  queryProgramId,
);
// For streaming responses, process the stream
if (isReadableStream(evaluateResponse)) {
  const result = await processStreamToApiResponse(evaluateResponse);
  console.log('Query Result:', result.data);
} else {
  console.log('Query Result:', evaluateResponse.data);
}

// Publish a query program to make it available as an API
await client.queryPrograms.publishQueryProgram(queryProgramId);
```

### Accessing APIs

```typescript
// Get APIs for a project
const apisResponse = await client.apis.getProjectApis(projectId);
const apis = apisResponse.data;

// Get endpoints for an API
const endpointsResponse = await client.apis.getApiEndpoints(apiId);
const endpoints = endpointsResponse.data;
```

## Authentication Management

The SDK now includes an enhanced authentication manager that provides better control over API keys and authentication state:

```typescript
import { InfactoryClient, AuthManager } from '@infactory/infactory-ts';

// Create an authentication manager
const authManager = new AuthManager({
  apiKey: 'your-api-key-here',
});

// Create a client using the auth manager
const client = new InfactoryClient({
  authManager,
});

// Check if authenticated
if (authManager.isAuthenticated()) {
  console.info('Authenticated with API key!');
}

// Update API key if needed
authManager.setApiKey('new-api-key');
```

## Error Handling

The SDK provides an improved error handling system with specific error classes that match the OpenAPI specification:

```typescript
import {
  InfactoryClient,
  AuthenticationError,
  PermissionError,
  NotFoundError,
  ValidationError,
  RateLimitError,
  ServerError,
} from '@infactory/infactory-ts';

async function handleErrors() {
  try {
    const client = new InfactoryClient({ apiKey: 'your-api-key' });
    const response = await client.projects.getProject('non-existent-id');
    return response.data;
  } catch (error) {
    if (error instanceof AuthenticationError) {
      console.error('Authentication failed. Please check your API key.');
    } else if (error instanceof PermissionError) {
      console.error('You do not have permission to access this resource.');
    } else if (error instanceof NotFoundError) {
      console.error('The requested resource was not found.');
    } else if (error instanceof ValidationError) {
      console.error(`Validation error: ${error.message}`);
      console.error('Validation details:', error.errors);
    } else if (error instanceof RateLimitError) {
      console.error(
        `Rate limit exceeded. Try again in ${error.retryAfter} seconds.`,
      );
    } else if (error instanceof ServerError) {
      console.error(`Server error: ${error.message}`);
    } else {
      console.error(`Unexpected error: ${error.message}`);
    }
  }
}
```

### Handling Streaming Responses

Some API endpoints can return streaming responses. The SDK provides enhanced utilities to handle these responses, including event-based streaming:

```typescript
import {
  InfactoryClient,
  isReadableStream,
  processStreamToApiResponse,
  streamEvents,
} from '@infactory/infactory-ts';

async function handleBasicStreamingResponse() {
  const client = new InfactoryClient({ apiKey: 'your-api-key' });

  // This may return a stream or a regular response
  const result = await client.queryprograms.evaluateQueryProgramSync(
    queryProgramId,
    { stream: true },
  );

  if (isReadableStream(result)) {
    // Process the stream into a regular API response
    const apiResponse = await processStreamToApiResponse(result);
    return apiResponse.data;
  } else {
    // Handle regular API response
    return result.data;
  }
}

// Enhanced event-based streaming for real-time data processing
async function handleEventStreamingResponse() {
  const client = new InfactoryClient({ apiKey: 'your-api-key' });

  // Get a streaming response
  const result = await client.queryprograms.evaluateQueryProgramSync(
    queryProgramId,
    { stream: true },
  );

  if (isReadableStream(result)) {
    // Process events from the stream as they arrive
    for await (const event of streamEvents(result)) {
      switch (event.type) {
        case 'data':
          console.info('Received data chunk:', event.data);
          // Process data in real-time
          break;
        case 'thinking':
          console.info('AI is thinking:', event.content);
          // Update UI with thinking state
          break;
        case 'completion':
          console.info('Received completion:', event.content);
          // Handle final result
          break;
        case 'error':
          console.error('Stream error:', event.error);
          // Handle errors appropriately
          break;
      }
    }
  } else {
    // Handle regular API response
    return result.data;
  }
}
```

## Complete Examples

For complete examples, see:

- [`quickstart.md`](./quickstart.md) - A step-by-step guide that mirrors the end-to-end test, explaining the purpose and SDK methods for each stage of a typical user workflow.
- `example.ts` - Basic SDK usage examples.
- `infactory-e2e-test.ts` - The end-to-end test implementation that creates a project, uploads data, runs queries, and deploys APIs.

## Command Line Tools

To run the included tests from the command line:

```bash
# Set up your API key
export NF_API_KEY=your-api-key-here

# Run the end-to-end tests
npm run test:e2e
```

## Development

### Building from Source

```bash
git clone https://github.com/infactory-io/infactory-ts.git
cd infactory-ts
npm install
npm run build
```

## Testing the SDK

The SDK includes a comprehensive test suite using Vitest.

### Running Tests

- **Run unit & integration tests**:

    ```bash
    npm test
    ```

- **Run end-to-end tests** (requires `NF_API_KEY`):

    ```bash
    npm run test:e2e
    ```

- **Run a specific E2E test** (e.g., the quickstart test):

    ```bash
    npm run test:e2e:quickstart
    ```

- **Run the entire test suite**:

    ```bash
    npm run test:all
    ```

### Test Coverage

Generate a test coverage report for non-E2E tests:

```bash
npm run test:coverage
```

### Testing Dependencies

The test suite uses several tools:

- **Vitest**: Test runner and assertion library
- **nock**: HTTP server mocking
- **MSW**: API mocking via request interception

## License

This Infactory TypeScript SDK is licensed under the MIT License. See the LICENSE file for more details.