@naturali / sdk

的TypeScript SDK naturali.ai API，从 它的 OpenAPI规格.

pnpm add @naturali/sdk

使用

import { NaturaliClient } from '@naturali/sdk';

const naturali = new NaturaliClient({
  token: process.env.NATURALI_TOKEN, // nat_sk_… or a session access JWT
});

const { data, error } = await naturali.agents.listAgents({
  path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
  query: { limit: 10 },
});

if (error) {
  // The platform's error envelope, typed: { error: { code, message, details } }
  console.error(error);
} else {
  console.log(data.data);
}

方法永远不会抛出非2xx响应——它会解析为 { data, error }， 所以是机器可读的 code （approval_required， budget_exceeded， access_denied)作为类型化数据可用。

选项

客户总是与 https://api.naturali.ai -唯一的自然。ai API 起源，不可配置。

没有 project 选项：项目范围内的操作需要 project_id 在 它的路径，这是API授权的唯一对象。

电话的形状

每个资源属性都镜像一个生成的服务类，并使用配置的 HTTP客户端已经绑定。参数遵循规范自己的结构和 snake_case 字段名:

await naturali.sessions.addSessionMessage({
  path: { project_id, agent_id, session_id },
  body: { message: 'What is the capital of France?' },
});

await naturali.knowledge.queryKnowledgeCollection({
  path: { project_id, collection_id },
  body: { query: 'refund policy', limit: 5 },
});

资源: agents， apiKeys， auth， channels， contacts， generations， knowledge， models， projects， providers， sessions， tools， traces.

naturali.http 为拦截器或一次性公开底层客户端 请求(naturali.http.get({ url: '/health' })）。

类型

规范中的每个模式都被导出为一个类型：

import type { Agent, AgentCreate, ErrorResponse } from '@naturali/sdk';

created_at / updated_at 是递给来电者的 Date 对象;一切 Else与线的形状完全匹配。

一代

src/generated/ 是构建输出——永远不要编辑它，也不要提交它。它是 重建的 api/openapi/v1/*.yaml 由 pnpm generate,这 typecheck， test 和 build 所有人先跑。看到 ../README.md 为 管道。

唯一的手写资料是 src/naturaliClient.ts.

版本控制

发布是自动的，版本是自动的 与API共享 @naturali/cli -一个号码，一个git标签，三个包。 @naturali/[email protected] 客户端是API 0.28.0，所以你安装的版本名称是你的合同 持有。

任何改变 api/openapi/v1/*.yaml 重新生成这个包并发布它， 因为规范就是它生成的东西 从 -所以一个新的版本可以意味着 API获得了资源，而不是手写的客户机发生了变化。

fix:/chore: 更改发布补丁和 feat: 从…中推断出的 压缩提交主题。每个案例都在合并时发布，打破更改 包括在内。请参阅存储库的 PIPELINE.md 和 CHANGELOG.md.