Integrations
TypeScript SDK
Typed, promise-based Node.js client for deplo.sh.
The deplo package provides a typed, promise-based interface for Node.js agents and TypeScript applications.
Why use the SDK?
If you're building a TypeScript agent, an automated pipeline, or a Node.js application that produces files, the SDK is the most ergonomic way to deploy. It gives you:
- Type-safe API — full IntelliSense for every method, parameter, and response
- No shell spawning — deploy from within your process, no
child_process.exec("deplo deploy ...") - Structured results — get back
{ url, id, version }as typed objects, not parsed CLI output - Error handling — catch
DeploErrorwith typed status codes and error codes
When to use the SDK vs. other methods:
| Use the SDK when... | Use something else when... |
|---|---|
| Your agent is written in TypeScript/Node.js | Your agent uses Python, Go, etc. → use the REST API |
| You need programmatic access to deploy results | You're deploying from a shell script → use the CLI |
| You want type safety and IntelliSense | You're using Claude, Cursor, or an MCP host → use the MCP server |
deplo.sh vs. manual deployment
// ❌ Without deplo.sh: manually upload, configure hosting, set up TLS...
const s3 = new S3Client({ region: 'us-east-1' });
await s3.send(new PutObjectCommand({ Bucket: '...', Key: '...', Body: html }));
// Then configure CloudFront, Route53, ACM certificate...
// ✅ With deplo.sh: one call, done
const { url } = await client.deploy({
project: 'weekly-report',
files: [{ path: 'index.html', content: html, encoding: 'utf8' }],
});
// → https://weekly-report.deplo.sh — live, TLS, CDN, doneInstall
npm install deploInitialise the client
import { deplo.sh } from 'deplo';
const client = new deplo.sh({
apiKey: process.env.DEPLO_KEY!,
// Optional: override base URL
// baseUrl: 'https://api.deplo.sh',
});Deploying
Deploy a file from a string
const dep = await client.deploy({
project: 'weekly-report',
type: 'static_file',
files: [{ path: 'index.html', content: htmlString, encoding: 'utf8' }],
ttl: '7d',
});
console.log(dep.url); // https://weekly-report.deplo.sh
console.log(dep.id); // dep_abc123
console.log(dep.version); // 3Deploy a local directory
const site = await client.deployDir('./dist', {
project: 'my-app',
type: 'static_site',
ttl: 'forever',
});Deploy structured JSON as a live API
const api = await client.deployJSON(leadsArray, {
project: 'enriched-leads',
ttl: '24h',
});
// GET https://enriched-leads.deplo.sh → returns leadsArray as JSONProjects
// List all projects
const projects = await client.projects.list();
// Get a specific project
const project = await client.projects.get('proj_abc123');
// or by slug
const project2 = await client.projects.get('weekly-report');
// Create a project
const newProject = await client.projects.create({
name: 'Monthly Report',
slug: 'monthly-report',
type: 'static_file',
defaultTtl: '30d',
});
// Delete a project
await client.projects.delete('proj_abc123');Deployments
// List all versions
const deployments = await client.deployments.list('proj_abc123');
// Promote an old deployment (rollback)
await client.deployments.promote('proj_abc123', 'dep_old123');
// Archive a deployment
await client.deployments.archive('proj_abc123', 'dep_ancient');Error handling
import { deplo.sh, DeploError } from 'deplo';
try {
await client.deploy({ ... });
} catch (e) {
if (e instanceof DeploError) {
console.error(`Deploy failed [${e.status}]: ${e.message}`);
// e.status → HTTP status code (e.g. 402 for quota exceeded)
// e.code → machine-readable error code (e.g. "QUOTA_EXCEEDED")
}
}TypeScript types
Key types exported from the package:
type DeploymentType = 'static_file' | 'static_site' | 'json_api';
type TTL = '1h' | '24h' | '7d' | '30d' | 'forever';
type TokenScope = 'deploy' | 'read' | 'delete' | 'admin';
interface DeployResult {
id: string;
url: string;
version: number;
size_bytes: number;
file_count: number;
expires_at: string | null;
}
interface Project {
id: string;
slug: string;
name: string;
type: DeploymentType;
custom_domain: string | null;
custom_domain_status: 'pending' | 'active' | 'error' | null;
live_deployment_id: string | null;
}What's next?
- Quickstart — deploy your first file via the CLI
- REST API — the HTTP API the SDK uses under the hood
- What is deplo.sh? — platform overview and design principles
- Ship a JSON Mock API — deploy data as a live REST endpoint
- Core Concepts — understand projects, deployments, and TTL