Infactory TypeScript SDK

用于与 Infactory AI 平台交互的官方 TypeScript SDK。 此 SDK 允许您通过 Infactory API 以编程方式访问和管理您的数据、项目和查询。

安装

npm install @infactory/infactory-ts

配置

在使用 SDK 之前，您需要设置您的 Infactory API 凭据：

1. 从 Infactory Workshop 获取 API 密钥
2. 使用 API 密钥初始化客户端

快速开始

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

// 使用您的 API 密钥初始化客户端
const client = new InfactoryClient({
  apiKey: 'your-api-key-here',
  // 可选: baseURL: 'https://api.infactory.ai' // 如果需要，使用自定义 API 端点
});

// 示例：获取当前用户信息
async function getCurrentUser() {
  const response = await client.users.getCurrentUser();
  if (response.error) {
    console.error(`Error: ${response.error.message}`);
    return null;
  }
  return response.data;
}

// 示例：列出所有项目
async function listProjects() {
  const response = await client.projects.getProjects();
  if (response.error) {
    console.error(`Error: ${response.error.message}`);
    return [];
  }
  return response.data;
}

环境变量

SDK 支持从环境变量加载配置：

# 必需
NF_API_KEY=your-api-key-here

# 可选 - 默认为 https://api.infactory.ai
NF_BASE_URL=https://api.infactory.ai

您可以使用 dotenv 从 .env 文件加载这些变量：

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

// 加载环境变量
dotenv.config();

// 使用环境变量创建客户端
const client = new InfactoryClient({
  apiKey: process.env.NF_API_KEY || '',
});

可用 API

SDK 提供对以下 Infactory API 资源的访问：

• Projects - 创建和管理项目
• Teams - 管理团队和团队成员
• Organizations - 访问组织信息
• Users - 用户管理和身份验证
• Auth - API 密钥管理
• Chat - 与聊天界面交互
• Datasources - 连接和管理数据源
• Datalines - 访问和转换数据
• QueryPrograms - 创建、运行和发布查询
• APIs - 部署和管理 API 端点
• Credentials - 管理连接凭据
• Secrets - 存储和管理密钥
• Tasks - 跟踪和管理任务
• Events - 访问事件信息

常用工作流程

创建项目和上传数据

// 创建一个新项目
const projectResponse = await client.projects.createProject({
  name: 'Stock Analysis Project',
  team_id: teamId,
  description: 'Project for analyzing stock data',
});
const project = projectResponse.data;

// 创建一个数据源
const datasourceResponse = await client.datasources.createDatasource({
  name: 'Stock Data',
  project_id: project.id,
  type: 'csv',
});
const datasource = datasourceResponse.data;

// 上传 CSV 文件（这是一个简化的示例）
const formData = new FormData();
formData.append('file', fs.createReadStream('./data/stocks.csv'));

// 使用数据源上传
await fetch(
  `${client.getBaseURL()}/v1/actions/load/${project.id}?datasource_id=${datasource.id}`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${client.getApiKey()}`,
    },
    body: formData,
  },
);

使用查询程序

// 获取项目的查询程序
const queryProgramsResponse =
  await client.queryprograms.getQueryProgramsByProject(projectId);
const queryPrograms = queryProgramsResponse.data;

// 执行查询程序
const evaluateResponse =
  await client.queryprograms.executeQueryProgram(queryProgramId);
const queryResult = evaluateResponse.data;

// 发布查询程序以使其可用作 API
await client.queryprograms.publishQueryProgram(queryProgramId);

访问 API

// 获取项目的 API
const apisResponse = await client.apis.getProjectApis(projectId);
const apis = apisResponse.data;

// 获取 API 的端点
const endpointsResponse = await client.apis.getApiEndpoints(apiId);
const endpoints = endpointsResponse.data;

错误处理

SDK 提供了一致的错误处理策略，针对不同类型的错误提供特定的错误类：

import {
  InfactoryClient,
  AuthenticationError,
  PermissionError,
  NotFoundError,
} 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 {
      console.error(`Unexpected error: ${error.message}`);
    }
  }
}

处理流式响应

某些 API 端点（如 executeQueryProgram）可以返回流式响应。 SDK 提供了处理这些响应的实用程序：

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

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

  // 这可能会返回流或常规响应
  const result = await client.queryprograms.executeQueryProgram(
    queryProgramId,
    { stream: true },
  );

  if (isReadableStream(result)) {
    // 将流处理为常规 API 响应
    const apiResponse = await processStreamToApiResponse(result);
    return apiResponse.data;
  } else {
    // 处理常规 API 响应
    return result.data;
  }
}

完整示例

有关完整示例，请参见：

• example.ts - 基本 SDK 用法示例
• infactory-e2e-test.ts - 端到端测试工作流程，包括项目创建、数据上传、查询执行和 API 使用

命令行工具

要运行包含的示例文件：

# 设置您的 API 密钥
export NF_API_KEY=your-api-key-here

# 运行基本示例
npm run example

# 运行端到端测试
npm run e2e-test

开发

从源代码构建

git clone https://github.com/infactory-io/infactory-ts.git
cd infactory-ts
npm install
npm run e2e-test

测试 SDK

SDK 包含一个使用 Jest 的综合测试套件，其中包含几种类型的测试：

单元测试

单元测试在隔离状态下验证 SDK 的各个组件：

npm run test:unit

集成测试

集成测试验证组件如何协同工作以及与 Infactory API 的协同工作：

npm run test:integration

Mock Service Worker 测试

MSW 测试使用请求拦截模拟 API 交互：

npm run test:msw

运行所有测试

要运行整个测试套件：

npm test

测试覆盖率

生成测试覆盖率报告：

npm run test:coverage

设置测试

对于编写测试的贡献者：

1. 单元测试：放置在 src/__tests__/ 中，并命名为 *.test.ts
2. 集成测试：放置在 src/__tests__/integration/ 目录中
3. MSW 测试：放置在 src/__tests__/msw/ 目录中

测试依赖项

测试套件使用以下几种工具：

• Jest：测试运行器和断言库
• ts-jest：Jest 的 TypeScript 支持
• jest-fetch-mock：模拟 fetch 请求
• nock：HTTP 服务器模拟
• MSW：通过请求拦截进行 API 模拟

许可证

此 Infactory TypeScript SDK 在 MIT 许可证下获得许可。 有关更多详细信息，请参见 LICENSE 文件。