@gigadrive / sdk

的官方TypeScript SDK Gigadrive网络云平台-组织、应用程序、部署、具有可恢复文件的存储以及兼容openai的AI网关。

可在Node.js 18+、浏览器和edge运行时(任何带有 fetch）。

安装

npm install @gigadrive/sdk
# or: pnpm add @gigadrive/sdk

快速启动

import { GigadriveClient } from '@gigadrive/sdk';

// Credentials are auto-detected from the environment (see below),
// or pass them explicitly.
const client = new GigadriveClient({
  clientId: process.env.GIGADRIVE_CLIENT_ID,
  clientSecret: process.env.GIGADRIVE_CLIENT_SECRET,
});

const { items: organizations } = await client.organizations.list();
const { items: applications } = await client.applications.list();

组织和产品权利

组织是Gigadrive产品的顶级帐户容器。除了列出组织之外，SDK还可以创建组织、检查成员以及检查产品授权（只读，SDK不会激活或更改计划）：

// Create an organization (user-backed token + platform:organizations:write)
const org = await client.organizations.create({ name: 'Acme Corp' });

// Fetch one organization and its members
const details = await client.organizations.get(org.id);
const { items: members } = await client.organizations.members.list(org.id);

// Inspect product access / entitlements (read-only)
const { items: products } = await client.organizations.products.list(org.id);
const office = await client.organizations.products.get(org.id, 'office');
const check = await client.organizations.products.checkEntitlement(org.id, 'office');

console.log(details.name, members.length, office.hasAccess, check.hasAccess, products.length);

身份验证

身份验证是为您处理的——令牌被获取、缓存和刷新在幕后。通过构造函数或环境提供凭据变量（构造函数值优先）：

方法	构造函数	环境
API密钥（机器对机器）	`clientId` + `clientSecret`	`GIGADRIVE_CLIENT_ID` + `GIGADRIVE_CLIENT_SECRET`
预先取得的不记名令牌	`bearerToken`	`GIGADRIVE_BEARER_TOKEN`
刷新令牌	`clientId` + `refreshToken`	`GIGADRIVE_CLIENT_ID` + `GIGADRIVE_REFRESH_TOKEN`
授权码+ PKCE	`clientId` + `onAuthorizationUrl`	- - - - - -

上下文绑定存储调用还解析来自的应用程序UUID applicationId 在构造函数或 GIGADRIVE_APPLICATION_ID． Gigadrive 向后者注入工作负载凭据，因此可以正常部署服务器代码不需要配置SDK。

// Custom fetch / base URL (e.g. for tests or non-standard runtimes)
const client = new GigadriveClient({ bearerToken: 'eyJ...', fetch: myFetch });

粘性的会话

已部署的MicroVM函数可以创建一个保持相同不透明的路由URL 一个函数实例上的应用程序键。注入工作负载凭据平台，因此部署中不需要SDK配置：

import { GigadriveClient } from '@gigadrive/sdk';

const gigadrive = new GigadriveClient();
const { url, expiresAt } = await gigadrive.stickySessions.createUrl({
  key: gameId,
  endpoint: '/socket',
  expiresInSeconds: 14_400,
});

const socket = new WebSocket(url);

URL是路由权限，而不是用户身份验证。应用程序仍然拥有授权和房间成员。状态保存在一个MicroVM的内存，url 过期，并且部署不会将该内存状态迁移到新版本。

文件存储

桶 name 是规范的REST和IaC标识符。名字是不可变的，小写，url安全，并且在环境中是唯一的。返回的桶 slug 仍然是全局CDN/S3标识符，不应该传递给这些其他的帮手。

为下的每个部署环境声明桶 services.storage 在 gigadrive.yaml．映射键是规范的桶名； null 或者一个空对象使用私有可见性。部署决定环境并生成每个全局CDN/S3段塞。

version: 4
services:
  storage:
    buckets:
      assets:
        visibility: public
      uploads: null

在部署的工作负载中，应用程序和环境上下文是推断出来的：

import { GigadriveClient } from '@gigadrive/sdk';

const client = new GigadriveClient();
const { items } = await client.storage.objects.list('assets');

管理调用方可以配置应用程序并选择环境段塞或UUID：

const client = new GigadriveClient({ applicationId, clientId, clientSecret });
const bucket = await client.storage.buckets.create({
  name: 'assets',
  environment: 'production',
  visibility: 'public',
});

const { items } = await client.storage.objects.list(bucket.name, {
  environment: 'production',
});

现有的 client.applications.storage 电话,明确 applicationId 参数和桶uuid作为已弃用的兼容性仍然可用路径。

文件上传

高级 upload() 计算所需的SHA-256校验和，推断出内容类型，创建上传会话，并上传字节与恢复转移-在一个呼叫。

// Node.js — upload straight from a file path (size, checksum, type inferred)
const { url } = await client.storage.upload({
  bucket: 'reports',
  key: 'reports/q1.pdf',
  path: './q1-report.pdf',
});

// Browser — upload a File with progress and cancellation
const controller = new AbortController();
const { url } = await client.storage.upload({
  bucket: 'uploads',
  key: `uploads/${file.name}`,
  data: file,
  onProgress: (sent, total) => console.log(`${Math.round((sent / total) * 100)}%`),
  signal: controller.signal,
});

// Wait until the object is finalized server-side, then read it back
const { object } = await client.storage.upload({
  bucket: 'avatars',
  key: 'avatars/user-1.png',
  data: bytes,
  waitForCompletion: true,
});
console.log(object?.contentLength, 'bytes stored');

可接受的输入：浏览器 File/Blob、节点 Buffer/Uint8Array/ArrayBuffer， a Node文件系统 path，或Node可读 stream (与 contentLength 和 checksumSha256）。

空文件，例如 .gitkeep 或者 __init__.py 处理各种输入类型。这个 API在创建上传会话时存储一个零字节对象，因此没有存储任何东西转移, waitForCompletion 返回而不轮询，结果总是包括 object．为了一个空的 stream,通过 contentLength: 0;空 SHA-256已为您填写。

同时处理多个文件

const results = await client.storage.uploadBatch(
  files.map((f) => ({ bucket: 'uploads', key: f.name, data: f })),
  { concurrency: 6, onProgress: (done, total) => console.log(`${done}/${total}`) }
);
const failed = results.filter((r) => r.error);

处理物品和垃圾

// List a "folder" one level deep
const { items, commonPrefixes } = await client.storage.objects.list('assets', {
  prefix: 'images/',
  limit: 100,
});

// Signed download URL for a private object
const { url } = await client.storage.objects.getAccessUrl('assets', objectId, {
  expiresInSeconds: 3600,
});

// Delete moves an object to trash; restore or permanently purge it later
await client.storage.objects.delete('assets', objectId);
await client.storage.trash.restore('assets', objectId);
await client.storage.trash.purge('assets', objectId);

// Permanently purge every trashed object in the bucket
const { purgedCount } = await client.storage.trash.empty('assets');

人工智能网关

openai兼容聊天完成，响应，音频，视频和模型发现。

// Chat completion
const res = await client.aiGateway.chatCompletions({
  model: 'openai/gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }],
});
console.log(res.choices[0].message.content);

// Streaming
for await (const chunk of client.aiGateway.chatCompletionsStream({
  model: 'openai/gpt-4o',
  messages: [{ role: 'user', content: 'Write a haiku about the sea.' }],
})) {
  process.stdout.write(chunk.choices[0]?.delta.content ?? '');
}

// Models
const { items: models } = await client.aiGateway.listModels();

组织范围的治理（使用分析、预算、策略）生活在下面 client.organizations.aiGateway.

定制域

将您拥有的主机名附加到应用程序。响应列出要发布的DNS记录；Gigadrive 然后网络验证所有权，检查DNS并自行颁发证书。

import { DomainNotActiveError } from '@gigadrive/sdk';

const domain = await client.applications.domains.add('app-id', { hostname: 'shop.example.com' });
for (const record of domain.requiredRecords) {
  console.log(record.type, record.host, record.value);
}

try {
  await client.applications.domains.waitUntilActive('app-id', domain.id, {
    timeoutMs: 15 * 60_000,
    onState: (current) => console.log(current.state),
  });
} catch (error) {
  if (!(error instanceof DomainNotActiveError)) throw error;
  // `reason` is `timeout`, `failed`, `suspended` or `removing`; `domain.error` explains what to fix.
  console.error(error.reason, error.domain.error?.message);
}

重定向一个域，或者服务于分支而不是生产：

await client.applications.domains.update('app-id', domain.id, {
  target: { type: 'redirect', to: 'www.example.com', statusCode: 308 },
});

验证一次可注册域，让组织的每个应用程序附加主机名下面没有另一个TXT记录：

const claim = await client.organizations.domains.add('org-id', 'example.com');
console.log(claim.record.host, claim.record.value); // publish this TXT record
await client.organizations.domains.verify('org-id', claim.id);

队列

队列在后台将工作交付给你的应用程序，现在或以后。具有使用者路径的队列是推送队列：Gigadrive Network将每条消息发送到部署中的该路径。没有一个，它是一个拉队列，你消耗 receive().

import { NonRetryableError, queue, RetryLaterError } from '@gigadrive/sdk';

export const emails = queue<{ to: string; template: string }>('emails');

// Send now, after a delay, or at a time (up to a year ahead).
await emails.send({ to: '[email protected]', template: 'welcome' });
await emails.send({ to: '[email protected]', template: 'nudge' }, { delay: '3d', deduplicationKey: 'nudge:jane' });

// app/api/queues/emails/route.ts: the push consumer. Signatures are verified for you.
export const POST = emails.handler(async (email, { attempt }) => {
  if (!templates.has(email.template)) throw new NonRetryableError('Unknown template'); // dead-letter now
  if (await mailer.isThrottled()) throw new RetryLaterError('1m'); // defer without spending an attempt
  await mailer.send(email); // returning acknowledges the message
});

声明推送消费者和任何cron调度 gigadrive.yaml，或从代码中创建 emails.ensure({ consumerPath: '/api/queues/emails' }) 和 emails.schedule(...).

拉消费者租赁信息并解决它们：

const jobs = queue<{ id: string }>('jobs');

await jobs.consume(async (job) => processJob(job.id), { maxMessages: 10, stopWhenEmpty: true });

client.queues 公开完整的REST表面（队列、消息、死信、调度），并且 createWorkflowQueue() 运行工作流SDK 在gigdrive Network队列上。

microVMs

microvm是您根据需要创建的隔离的Linux机器：运行命令，移动文件输入和输出，并在公共预览url上公开端口。将它们用于代码执行，代理沙箱，CI步骤和预览。

import { MicroVM } from '@gigadrive/sdk';

await using vm = await MicroVM.create({ image: 'node22', ports: [3000], timeout: '10m' });

await vm.files.write('server.js', 'require("http").createServer((_, r) => r.end("hi")).listen(3000)');
const { exitCode, stdout } = await vm.run('node --version');
const server = await vm.spawn('node', ['server.js']);
console.log(await vm.waitForPort(3000)); // https://3000-<slug>.vm.gigadrive.app
// Leaving the block stops the microVM.

MicroVM.create 解析它的客户端 GigadriveClient (通过 client 使用你自己的)和它的应用程序 applicationId，客户的 applicationId 或者 GIGADRIVE_APPLICATION_ID．在千兆驱动器部署中不需要任何配置。内置的图片: node22， node24， python3.13， python3.12， bun1， debian12， ubuntu24.04.

任务	呼叫
创建，连接，列表	`MicroVM.create({ image, vcpus, memoryMb, diskMb, timeout, ports, env, metadata, network })`， `MicroVM.get(id)`， `for await (const vm of MicroVM.list())`
跑啊，等啊	`vm.run('ls -la')`， `vm.run('npm', ['test'], { cwd, env, user, sudo, timeout, onStdout, onStderr, stdin, throwOnError, signal })` → `{ exitCode, signal, timedOut, stdout, stderr, truncated, durationMs }`
在后台运行	`vm.spawn(cmd, args, { stdin, pty, onStdout })` → `Command`： `logs()`， `output()`， `stdout()`， `stderr()`， `wait()`， `kill(signal)`， `write(data)`， `end()`， `resize(cols, rows)`
重新接上	`vm.commands.get(commandId)`， `vm.commands.list()`
文件	`vm.files.write(path, string \| Uint8Array \| Blob \| ReadableStream)`， `writeMany`， `read`， `readText`， `readStream`， `list(path, { recursive })`， `stat`， `exists`， `mkdir`， `remove`， `move`
港口	`vm.url(port)`， `vm.waitForPort(port)`
一生	`vm.extendTimeout('30m')`， `vm.stop()`， `vm.delete()`， `await using vm = ...`
网络	`vm.updateNetwork('deny')`， `vm.updateNetwork({ egress: 'allow', allow: ['registry.npmjs.org', '*.github.com'] })`：改变它运行时可能到达的位置
指标	`vm.getMetrics({ windowMinutes: 60 })` → `{ cpu: [{ time, cpuPercent }], current: { memoryUsedBytes, memoryTotalBytes, diskUsedBytes, diskTotalBytes } \| null }`
人则	`client.microvms.webhooks.create({ url, events: ['microvm.stopped'] })` → `{ id, secret }`， `.list()`， `.update(id, { enabled })`， `.rotateSecret(id)`， `.listDeliveries(id)`;验证请求 `verifyMicroVmWebhook({ body, headers, secret })`
图片	`client.microvms.images.create({ name, from: 'python:3.13' \| { dockerfile } })`， `.waitUntilReady(id)`， `.list()`， `.get(id)`， `.delete(id)`

命令输出保留在microVM中，因此 command.logs() 可以从另一个过程是 vm.commands.get(id)，并恢复断开的连接在下一个未读字节。非零退出码是正常结果；通过 throwOnError: true 为了得到一个 CommandFailedError．其他输入错误： MicroVmNotRunningError， MicroVmNotFoundError， MicroVmFileNotFoundError， MicroVmQuotaExceededError， MicroVmBusyError， MicroVmUnreachableError， MicroVmImageNotReadyError， MicroVmPortNotExposedError， MicroVmTimeoutError， MicroVmStartError 和 MicroVmImageBuildError. 当microVM应答时，读取和日志流将以backoff方式重试 microvm_busy． microVM最多存活24小时(MICROVM_MAX_TIMEOUT_MS)，或者在你的计划中更少。

client.microvms 底层REST表面是每个路由一个方法吗（create， list， listAll， get， getMetrics， extendTimeout， updateNetwork， stop， delete， commands.*， files.*， images.*， webhooks.*）. SDK只使用 fetch，所以它运行 Node.js 18+, Bun, Deno， edge运行时和Gigadrive函数。

分页

接受列表端点 page / perPage / cursor 并返回 { items, total } (游标分页的端点也会返回 nextCursor）. 迭代所有内容这个 paginate 助手:

import { paginate } from '@gigadrive/sdk';

for await (const object of paginate((cursor) => client.storage.objects.list('assets', { cursor }))) {
  console.log(object.key);
}

错误

所有错误扩展 GigadriveError．明显的子类: ApiError (与 status 和可选的 code)， AuthenticationError， ConfigurationError， UploadError, UploadSessionExpiredError.

import { ApiError } from '@gigadrive/sdk';

try {
  await client.deployments.get('missing');
} catch (err) {
  if (err instanceof ApiError) console.error(err.status, err.message);
}

许可证

apache - 2.0

版本	发布日期	距今
`0.16.0`latest	2026/11/01	2 天前
`0.15.0`	2026/11/01	2 天前
`0.14.0`	2026/11/01	2 天前
`0.13.1`	2026/10/27	7 天前
`0.13.0`	2026/10/27	7 天前
`0.12.0`	2026/10/27	7 天前

@gigadrive/sdk

@gigadrive / sdk

安装

快速启动

组织和产品权利

身份验证

粘性的会话

文件存储

文件上传

同时处理多个文件

处理物品和垃圾

人工智能网关

定制域

队列

microVMs

错误

许可证

版本与发布记录

关于 @gigadrive/sdk 的常见问题

@gigadrive/sdk 是什么？

如何安装 @gigadrive/sdk？

@gigadrive/sdk 支持 TypeScript 吗？

@gigadrive/sdk 支持 ESM 还是 CommonJS？

@gigadrive/sdk 需要什么版本的 Node.js？

@gigadrive/sdk 可以商用吗？

@gigadrive/sdk 还在维护吗？