TypeScript SDK

The @sota-io/sdk (source) provides typed methods for all sota.io API operations.

Installation

npm install @sota-io/sdk

Quick Start

import { SotaClient } from '@sota-io/sdk';

const sota = new SotaClient({ apiKey: 'sota_your_api_key' });

// List projects
const { projects } = await sota.listProjects();

// Create a project
const project = await sota.createProject({ name: 'my-app' });

// Deploy
const deployment = await sota.deploy(project.id, archiveBuffer);

Methods

Projects

Method	Description
`listProjects(options?)`	List all projects with optional pagination
`createProject({ name, slug? })`	Create a new project
`getProject(projectId)`	Get project details
`deleteProject(projectId)`	Delete a project permanently

Deployments

Method	Description
`deploy(projectId, archive)`	Deploy from a tar.gz archive
`listDeployments(projectId)`	List all deployments
`getLogs(projectId, deploymentId)`	Get build/runtime logs
`rollback(projectId)`	Rollback to previous deployment
`redeploy(projectId)`	Redeploy current deployment

Environment Variables

Method	Description
`listEnvVars(projectId)`	List all environment variables
`setEnvVar(projectId, { key, value })`	Set an environment variable
`deleteEnvVar(projectId, key)`	Delete an environment variable

Custom Domains

Method	Description
`listDomains(projectId)`	List all custom domains for a project
`addDomain(projectId, domain)`	Add a custom domain, returns DNS instructions
`getDomain(projectId, domainId)`	Get domain details with DNS instructions
`removeDomain(projectId, domainId)`	Remove a custom domain

addDomain

Add a custom domain to a project. Returns the domain object and DNS instructions for configuring at your registrar.

const result = await sota.addDomain(projectId, 'app.example.com');
console.log(result.domain.status); // 'pending'
console.log(result.dns_instructions);
// { type: 'CNAME', name: 'app', value: 'my-app.sota.io' }

Parameter	Type	Description
`projectId`	string	Project UUID
`domain`	string	Domain name (e.g., `app.example.com` or `example.com`)

Returns a DomainResponse with:

domain -- The domain object (id, domain, status, dns_type, timestamps)
dns_instructions -- Record type, name, and value to configure at your registrar

listDomains

List all custom domains for a project.

const domains = await sota.listDomains(projectId);
domains.forEach(d => console.log(`${d.domain} - ${d.status}`));

getDomain

Get a custom domain by ID with DNS instructions.

const result = await sota.getDomain(projectId, domainId);
console.log(result.domain.status); // 'active'
console.log(result.dns_instructions);

removeDomain

Remove a custom domain from a project.

await sota.removeDomain(projectId, domainId);

Error Handling

All SDK methods throw SotaAPIError on failure, providing the HTTP status code, API error code, and message.

import { SotaClient, SotaAPIError } from '@sota-io/sdk';

try {
  await sota.addDomain(projectId, 'example.com');
} catch (err) {
  if (err instanceof SotaAPIError) {
    console.log(err.status);  // HTTP status code (e.g., 409)
    console.log(err.code);    // API error code (e.g., 'conflict')
    console.log(err.message); // Error description
  }
}

Status	Code	Description
404	`not_found`	Project or domain not found
409	`conflict`	Domain already exists on a project
422	`validation_error`	Invalid domain format or limit reached