Resources

Each area of Gigadrive Network hangs off the client as a resource object, and every method maps to one HTTP endpoint. The names repeat across families, so list, get, create and delete mean the same thing wherever you meet them.

client.storage and client.applications.storage are the same object. Prefer client.storage.

Every example uses a client built as described in Authentication:

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

const client = new GigadriveClient();
const applicationId = process.env.GIGADRIVE_APPLICATION_ID as string;

Organizations

Membership is read-only here, and so is product access: the SDK cannot add a member, change a role, or activate a plan. create needs a user-backed token with platform:organizations:write, and the caller becomes the owner.

const org = await client.organizations.create({ name: 'Acme Corp' });
const { items: members } = await client.organizations.members.list(org.id);
const { hasAccess } = await client.organizations.products.checkEntitlement(org.id, 'office');

console.log(`${members.length} members, office access: ${hasAccess}`);

Applications

There is no applications.get(id) and no applications.delete(id). Filter list by organizationId to narrow it down.

pull merges the organization, application and environment layers into the values a deployment would see, and it never returns a sensitive value. It reports how many it skipped as omittedSensitive, so a build script can fail loudly instead of booting with a missing secret:

const { items, omittedSensitive } = await client.applications.envVars.pull(applicationId, {
  environment: 'production',
});

if (omittedSensitive > 0) {
  throw new Error(`${omittedSensitive} sensitive variables were not returned`);
}

for (const variable of items) {
  console.log(`${variable.key} (from ${variable.source})`);
}

Request logs are filtered through ListRequestsQuery: from, to, method, status, statusFamily, hostname, pathPrefix, country, cacheStatus, cacheHit, deploymentId, plus limit and cursor. get returns the same record with sanitized request and response headers attached. Request logs explains what each field means.

Custom domains

client.applications.domains manages the custom domains of an application, and client.organizations.domains manages the domains an organization verified with a TXT record. Custom domains explains the lifecycle and the DNS records.

add returns the records to publish in requiredRecords. target chooses what the domain serves: { type: 'production' } (the default), { type: 'branch', branchId }, or { type: 'redirect', to, statusCode?, preservePath? }. update also accepts primary: true.

waitUntilActive polls every 5 seconds for up to 10 minutes, and returns once the domain is active or degraded. Set timeoutMs, intervalMs or signal to change that, or pass onState to follow each state change. Rate limits, server errors and network failures do not end the wait. It throws DomainNotActiveError when the domain fails, is suspended or removed, or the timeout runs out. Read error.reason (timeout, failed, suspended or removing) and error.domain.error?.message to see what to fix:

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

try {
  await client.applications.domains.waitUntilActive(applicationId, domain.id, {
    onState: (current) => console.log(current.state),
  });
} catch (error) {
  if (!(error instanceof DomainNotActiveError)) throw error;
  console.error(error.reason, error.domain.error?.message);
}

Deployments

status moves through PENDING, QUEUED, STARTING, BUILDING, PROVISIONING, and ends at ACTIVE or FAILED. A deployment created from an uploaded archive stays PENDING until the upload completes.

Uploading an artifact runs through create, startUpload, one presigned PUT per part, and completeUpload. Parts are numbered from 1, every part is sent as application/zip, and each returns the ETag that completeUpload needs:

import { readFileSync } from 'node:fs';
import type { UploadPart } from '@gigadrive/sdk';

const archive = readFileSync('./build.zip');
const deployment = await client.deployments.create({ applicationId });
const { uploadId } = await client.deployments.startUpload(deployment.id);

const partSize = 10 * 1024 * 1024;
const parts: UploadPart[] = [];

for (let offset = 0, partNumber = 1; offset < archive.byteLength; offset += partSize, partNumber++) {
  const { url } = await client.deployments.getPresignedUrl(deployment.id, uploadId, partNumber);
  parts.push(await client.deployments.uploadPart(url, archive.subarray(offset, offset + partSize), partNumber));
}

await client.deployments.completeUpload(deployment.id, uploadId, parts);

Build output arrives through getLogs, which pages by offset and limit rather than by cursor. Errors and pagination has a loop that tails a build to its final status.

Storage

Buckets are addressed by name, the immutable identifier that is unique within an environment. The global slug is for CDN and S3 delivery and is not accepted here; bucket UUIDs still work but are deprecated.

The bucket and object methods in this table also have older overloads that take an application ID as the first argument. Set applicationId on the client, or run inside a Function, and you can omit it.

objects.delete is a soft delete that moves the object to the bucket trash, where restore can bring it back and purge removes it for good. Deleting the bucket takes live and trashed objects with it. Trash and restore covers the retention side.

New buckets are private unless you say otherwise, and a private object needs a signed URL from getAccessUrl:

const bucket = await client.storage.buckets.create({
  name: 'invoices',
  environment: 'production',
  visibility: 'private',
});

const { items, commonPrefixes } = await client.storage.objects.list(bucket.name, {
  prefix: '2026/',
  delimiter: '/',
});

for (const object of items) {
  const { url, expiresAt } = await client.storage.objects.getAccessUrl(bucket.name, object.id, {
    expiresInSeconds: 3600,
  });
  console.log(object.key, url, `expires ${expiresAt}`);
}

console.log('folders:', commonPrefixes);

Sending bytes is a subject of its own, in Uploading files.

AI Gateway

chatCompletions forces stream: false and chatCompletionsStream forces stream: true, so the stream field you pass is ignored either way.

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 ?? '');
}

Use chatCompletionsWithResponse when you want the response object alongside the body: it returns data, the raw response, and the requestId the gateway puts in the X-Gigadrive-Request-Id header. The result type also declares costMicros, which is always undefined, because no endpoint returns a cost header. Spend per request comes from Analytics.

Governance lives under the organization, and is separate from inference:

budgets.replace overwrites the whole set. Passing [] clears every budget on the organization. usage.export returns CSV text rather than JSON.

API keys

Keys are application-scoped, so applicationId is required on both create and list. Requested scopes must be a subset of the scopes your own token carries, and a key cannot be granted API key management scopes.

const key = await client.apiKeys.create({
  name: 'ci',
  applicationId,
  scopes: ['network:deployments:trigger', 'network:deployments:read'],
});

// key.secret is returned once and cannot be read again.
const ci = new GigadriveClient({ clientId: key.id, clientSecret: key.secret });

Omit expiresAt and the key expires in 90 days.

Sticky sessions

A sticky URL routes every request that uses it to the same Function, which is what makes in-memory state such as a WebSocket room work. It is routing authority and not user authentication, so keep your own authorization checks. expiresInSeconds defaults to 14400 and accepts 60 to 86400.

const { url, expiresAt } = await client.stickySessions.createUrl({
  key: 'room-42',
  endpoint: '/socket',
  expiresInSeconds: 3600,
});

console.log(`join at ${url}, valid until ${expiresAt}`);

Only a Function may mint one, and only for its own deployment.

Image optimization

createManagedImageUrl is exported from the package root, so a component can build image URLs without holding a client. purge with no source clears every optimized image in the deployment.

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

const src = createManagedImageUrl({
  origin: 'https://acme.gigadrive.app',
  source: '/photos/hero.jpg',
  width: 1280,
  format: 'avif',
  quality: 80,
});

Queues

client.queues manages the queues of an application, and the top-level queue() function returns the same handle from a client it configures from the environment. Every endpoint sits under /applications/{id}/queues, shortened to .../queues in the following table.

options is a QueueScopeOptions: applicationId defaults to the client's application, and environment takes a slug or UUID. A deployed Function omits environment, because its credential selects the environment.

queue(name) returns the typed handle the Queues pages use for sending, push handlers and pull consumers. Prefer it to the raw methods, which take bodies as strings:

const emails = client.queues.queue<{ to: string }>('emails', { environment: 'production' });

await emails.send({ to: 'jane@example.com' }, { delay: '10m' });

const { items, total } = await client.queues.listMessages(
  'emails',
  { state: 'scheduled', limit: 20 },
  { environment: 'production' }
);

console.log(`${items.length} of ${total} scheduled messages`);

microVMs

MicroVM is exported from the package root and configures its client from the environment, like queue(). Pass client in its options to use a client you built yourself. client.microvms is the same API as plain request methods that return the JSON objects, client.microvms.images manages images, client.microvms.volumes manages volumes, and client.microvms.webhooks manages webhooks.

MicroVM.create takes image, vcpus, memoryMb, diskMb, timeout, ports, env, metadata, network, volumes and applicationId, all optional. network: 'deny' blocks outbound traffic, and wait: false returns before the microVM is running. vm.run and vm.spawn take cwd, env, user, sudo, timeout, onStdout and onStderr. vm.run also takes stdin, throwOnError and signal, and vm.spawn takes stdin: true and pty. Commands and Files describe what each option does.

Durations such as timeout and extendTimeout take milliseconds or a string such as '30s', '10m' or '2h'.

A microVM is disposable, so declare it with await using and it stops when the scope ends, even when a command throws:

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

await using vm = await MicroVM.create({ image: 'python3.13', timeout: '10m' });

const { exitCode, stdout } = await vm.run('python', ['-c', 'print(sum(range(10)))']);

console.log(exitCode, stdout); // 0 "45\n"

Failures throw typed errors, among them MicroVmNotRunningError, MicroVmNotFoundError, MicroVmFileNotFoundError, MicroVmQuotaExceededError, MicroVmStartError when the microVM fails to start, and MicroVmTimeoutError when a wait gives up.