@cognicloud / sdk

调用CogniCloud AI网关端点并从Node.js, Bun， Deno和edge运行时管理它们。

预览。第一个版本涵盖了AI网关端点。包括浏览器会话；代理，抓取，保险库和活动还不包括在内。

安装

npm install @cognicloud/sdk

键入ESM使用平台 fetch，没有运行时依赖。

调用端点

import { EndpointClient } from "@cognicloud/sdk"

const endpoint = new EndpointClient({
  endpointId: process.env.COGNICLOUD_ENDPOINT_ID!,
  credential: process.env.COGNICLOUD_KEY!,
})

const { output, finishReason, usage } = await endpoint.invoke({
  input: [
    { role: "system", content: "Answer in one sentence." },
    { role: "user", content: "Summarise this ticket." },
  ],
  max_output_tokens: 256,
})

调用地址为 <baseUrl>/invoke/<tenant>/<endpointId>． 端点属于平台租户， cognicloud除非你通过 tenant． 您还可以传递为端点(endpoint.url), url 而不是 endpointId.

在没有请求映射的情况下，消息体会按原样返回给提供商，并且只接受纯文本消息：

• 没有部署的端点使用响应API： input (一串或 system/developer/user/assistant 消息), max_output_tokens， temperature， top_p.
• Azure部署的端点使用聊天完成： messages， max_completion_tokens (或 max_tokens)， temperature， top_p.

store 和 text.format （结构化输出）被拒绝使用 400 invalid_request． 为 instructions， MCP工具和链条的使用 responses;用于流媒体使用 stream． 有些模特拒绝 temperature;然后网关回答 502 provider_refused． 端点总是选择模型。

每个模型的答案都是一样的： output (文本), finishReason （stop， length， content_filter， other，或者 null), usage (令牌数)。

invoke 永远不会重试，因为重试的呼叫可以被计费两次。

工具响应

responses 接受一个带有optional的响应体 instructions， MCP工具和 previous_response_id． MCP工具将其服务器命名为 server_url 和它的信物 headers,因为 { Authorization: "Bearer <token>" }． 网关检查地址（https，没有凭据或片段），将批准设置为 never，并将两者传递给提供程序。一个只有 server_label 指定网关配置的服务器名称。

const answer = await endpoint.responses({
  input: "Is this invoice valid?",
  instructions: "Check invoices.",
  tools: [{ type: "mcp", server_label: "ksef", allowed_tools: ["validate_invoice_xml"] }],
  tool_choice: "required",
})

const next = await endpoint.responses({ input: "And this one?", previous_response_id: answer.responseId })

答案是 responseId （用于在同一端点上链接）和 outputItems （工具调用和提供者返回的消息）。

嵌入的

const { data } = await endpoint.embeddings({ input: ["first text", "second text"], dimensions: 256 })
const first = data[0].embedding

端点必须指向嵌入部署。 data 按输入顺序，每个输入有一个项，并且每个调用都作为提示令牌计费。

流式传输响应

stream 集合 stream: true 并在答案被写入时生成事件：

for await (const event of await endpoint.stream({ messages: [{ role: "user", content: "Write a haiku." }] })) {
  if (event.type === "delta") process.stdout.write(event.text)
  if (event.type === "done") console.log(`\n${event.answer.usage.totalTokens} tokens`)
  if (event.type === "error") console.error(`${event.code}: ${event.message}`)
}

每个事件都是 delta （text)，然后一个 done （answer与…形状相同 invoke)，或一个 error （code， message）. 被拒绝的呼叫用A拒绝 CogniCloudError 在任何事件发生之前。流不会重试，也没有总超时；入口在五分钟后结束。提前停止 break 关闭连接，网关仍然处理呼叫。

发送PDF或图像

import { EndpointClient, pdfPart, textPart } from "@cognicloud/sdk"
import { readFile } from "node:fs/promises"

const endpoint = new EndpointClient({ url: process.env.COGNICLOUD_ENDPOINT_URL!, credential: process.env.COGNICLOUD_KEY! })
const cv = await readFile("cv.pdf")

const { output } = await endpoint.invoke({
  messages: [{ role: "user", content: [textPart("Match this CV to the job."), pdfPart(cv, "cv.pdf")] }],
})

文件的最大容量为10mb。网关在呼叫之前以令牌形式保留文件大小的四分之一，因此端点的月限制必须覆盖它。

管理端点

电话作为帐户 token，登录者的Amadeus会话令牌或浏览器调用的浏览器密钥，作为 Authorization: Bearer． 抛出一个缺失、空或空白的标记 CogniCloudError 使用代码 missing_token 创建客户端时。工作空间(tenant、默认 cognicloud)作为 tenant_id 头。

import { CogniCloud } from "@cognicloud/sdk"

const cc = new CogniCloud({ token: amadeusToken, locale: "en" })

const { endpoint, credential } = await cc.endpoints.create({
  name: "Support bot",
  providerId: "azure-openai",
  model: "gpt-5-mini",
  tokenLimit: 1_000_000,
})

await cc.endpoints.update(endpoint.id, { tokenLimit: 2_000_000 })
await cc.endpoints.update(endpoint.id, { status: "paused" })
const usage = await cc.endpoints.usage(endpoint.id)
const days = await cc.endpoints.dailyUsage(endpoint.id, { from: "2026-10-01", to: "2026-10-20" })
const { secret } = await cc.endpoints.rotateCredential(endpoint.id)
await cc.endpoints.delete(endpoint.id)

也可用: cc.endpoints.list() 和 cc.endpoints.get(id).

浏览器会话

浏览器调用接受登录人员的令牌或浏览器密钥。在仪表板中创建一个密钥 浏览器→API密钥 并将其作为令牌传递。密钥在其所有者注销后仍然有效。不能通过SDK或API创建密钥。

仅使用浏览器密钥即可使用浏览器产品。该密钥命名其工作空间，因此不需要Amadeus令牌或租户：

import { CogniCloudBrowser } from "@cognicloud/sdk"

const browser = new CogniCloudBrowser({ key: process.env.COGNICLOUD_BROWSER_KEY! })
const session = await browser.browser.sessions.create({ timeoutMinutes: 15 })

上传一个配置文件文件夹 .tar.gz （请参阅应用文档了解如何打包它），然后从它开始一个会话：

import { readFile } from "node:fs/promises"

const profile = await browser.browser.importProfile("Shop account", await readFile("shop-profile.tar.gz"))
const session = await browser.browser.sessions.create({ profileId: profile.id })

浏览器会话是您的代理通过Chrome DevTools协议驱动的Chrome浏览器。启动一个，将您的自动化库连接到它的 cdpUrl，并在完成时停止它。

import { CogniCloud } from "@cognicloud/sdk"
import { chromium } from "playwright"

const cc = new CogniCloud({ token: amadeusToken })

const session = await cc.browser.sessions.create({ timeoutMinutes: 15 })
const browser = await chromium.connectOverCDP(session.cdpUrl!)
const page = browser.contexts()[0].pages()[0] ?? (await browser.contexts()[0].newPage())
await page.goto("https://example.com")

await browser.close()
await cc.browser.sessions.stop(session.id)

• timeoutMinutes 取值范围为1 ~ 240，默认为15。当超时时间过去时，会话将自行停止。
• 关闭CDP连接不会停止会话。呼叫 stop 如上所述。
• status 是 active 或者 stopped. cdpUrl 和 liveUrl 是 null 一旦会话停止。 liveUrl 是一个页面，一个人可以观看和接管浏览器。
• sessions.list() 返回工作区的会话，最新的优先，使用 concurrency: { active, limit }． 超出极限的起跑失败了 429 和代码 concurrency_limit.
• 代理国家、个人资料、屏幕尺寸、验证码解决和记录尚未提供。 countries() 和 profiles() 返回空列表，并且请求这些选项之一的start失败 422.

邮件

Flippico邮件服务器上的邮箱。 token 是已登录人员的令牌或邮件密钥(cgm_...）. 密码返回一次；储存它。

const { mailbox, password } = await cc.mail.create("support")
const settings = await cc.mail.connectionSettings() // IMAP and SMTP hosts, and defaultDomain

// Your own domain: add it, publish domain.records at your DNS provider, then verify.
const domain = await cc.mail.domains.add("yourcompany.com")
await cc.mail.domains.verify(domain.id)
await cc.mail.create("ceo", { domain: "yourcompany.com" })

mail.list， get， rotatePassword 和 delete 管理邮箱; mail.domains.list， get 和 delete 管理域。添加、验证和删除域需要登录人员的令牌。

数据库

托管Postgres。一个登录的人创建数据库；数据库键(cgd_...)从仪表板查询其中一个，不需要其他任何东西。一个 read 按键只能读取。一个 write 键作为数据库所有者运行。

import { CogniCloud, CogniCloudDatabase } from "@cognicloud/sdk"

const cc = new CogniCloud({ token: sessionToken })
const database = await cc.database.create("Orders")

const db = new CogniCloudDatabase({ key: process.env.COGNICLOUD_DATABASE_KEY! })

await db.query("CREATE TABLE orders (id serial PRIMARY KEY, email text, total numeric)")
const { rows } = await db.query("SELECT * FROM orders WHERE total > $1", [100])

await db.table("orders").insert({ email: "[email protected]", total: "19.90" })
const paid = await db.table("orders").select("id", "email").gt("total", 10).order("id", { desc: true }).limit(20)
await db.table("orders").update({ total: "0" }).eq("id", 1)
await db.table("orders").delete().eq("id", 1)

await db.transaction([
  { sql: "UPDATE accounts SET balance = balance - $1 WHERE id = $2", params: [10, 1] },
  { sql: "UPDATE accounts SET balance = balance + $1 WHERE id = $2", params: [10, 2] },
])
const tables = await db.tables()

• 过滤器是 eq， neq， gt， gte， lt， lte， like， ilike， is 和 in. update 和 delete 至少需要一个；要更改每一行，请使用 query.
• select， update 和 delete 等待时运行。 insert 马上就跑。
• 结果是 rows， columns， rowCount 和 truncated． 一个请求在15秒后停止，并返回最多1,000行和5mb。
• numeric 值, bigint 超过2^53的值会以字符串形式返回，所以不会四舍五入。 bytea 返回base64。
• 失败的语句将抛出 CogniCloudError 与 code query_failed 和 queryCode：一个Postgres SQLSTATE，例如 23505，或者 query_timeout.
• query 和 transaction、插入、更新和删除永远不会重试，因为它们可能会更改数据。

将值传递为 params，而不是在SQL中。它们不需要引号，也不能中断语句：

await db.query("INSERT INTO members (id, user_id) VALUES ($1, $2)", [id, userId])

一个登录的人可以在自己的数据库中运行SQL而不需要key： cc.database.query(database.id, sql, params) 和 cc.database.tables(database.id).

cc.database.list， get 和 delete 管理数据库, cc.database.keys.list 和 revoke 管理密钥，以及 cc.database.actions 列出已完成的工作。在仪表板中创建密钥。

错误

import { CogniCloudError } from "@cognicloud/sdk"

try {
  await endpoint.invoke({ input: "Hi" })
} catch (error) {
  if (error instanceof CogniCloudError && error.code === "credits_exhausted") {
    // top up credits
  }
  throw error
}

status 为HTTP状态(0 当请求没有得到答复时)； code 是CogniCloud的稳定错误代码。

配置

这个 CogniCloud 客户端也需要 token （登录者的Amadeus会话令牌）， tenant (工作空间，作为 tenant_id 头;默认的 "cognicloud"（平台工作空间）； browserBaseUrl (默认 https://cognicloud.dev/api/v1/browser） mailBaseUrl (默认 https://cognicloud.dev/api/v1/mail), databaseBaseUrl (默认 https://cognicloud.dev/api/v1/database）。

变化

看到 CHANGELOG.md． 代理、抓取、保险库和活动计划在以后的版本中使用。

来源: https://github.com/Flippico/cognicloud-js-sdk

开发

npm install
npm test
npm run build