@forkzz/squarecloud

TypeScript/JavaScript SDK for the Square Cloud API — deploy and manage your apps programmatically.

Installation

npm install @forkzz/squarecloud
# or
pnpm add @forkzz/squarecloud
# or
yarn add @forkzz/squarecloud

Quick Start

import { Client } from "@forkzz/squarecloud";

const client = new Client({
  apiKey: process.env.SQUARECLOUD_API_KEY,
});

const user = await client.users.me();
console.log(user.applications);

⚠️ Generate your API key at: squarecloud.app/account/security

Reference

new Client(config)

| Option | Type | Required | Description | |-----------|-----------|----------|------------------------------------------| | apiKey | string | ✅ | Your Square Cloud API key | | baseUrl | string | ❌ | Custom base URL (optional) | | timeout | number | ❌ | Request timeout in ms (default: 30000) | | debug | boolean | ❌ | Log all requests/responses |

client.users

| Method | Route | Description | |--------|------------------|--------------------------------------| | me() | GET /users/me | Get authenticated user + their apps |

client.apps

| Method | Route | Description | |-------------------------------|------------------------------------|---------------------------------------| | upload(options) | POST /apps | Deploy app via .zip | | get(appId) | GET /apps/{id} | Get app info | | status(appId) | GET /apps/{id}/status | CPU, RAM, uptime, network | | statusAll(workspaceId?) | GET /apps/status | Status of all apps | | logs(appId) | GET /apps/{id}/logs | Last 1000 log lines | | start(appId) | POST /apps/{id}/start | Start app | | stop(appId) | POST /apps/{id}/stop | Stop app | | restart(appId) | POST /apps/{id}/restart | Restart app | | commit(appId, file) | POST /apps/{id}/commit | Update app with new .zip | | delete(appId) | DELETE /apps/{id} | ⚠️ Permanently delete app | | getEnvs(appId) | GET /apps/{id}/envs | List environment variables | | setEnvs(appId, envs) | POST /apps/{id}/envs | Add/edit environment variables | | listSnapshots(appId) | GET /apps/{id}/snapshots | List app snapshots | | createSnapshot(appId) | POST /apps/{id}/snapshots | Create a snapshot | | realtime(appId, apiKey) | GET /apps/{id}/realtime | Real-time logs via SSE |

client.databases

| Method | Route | Description | |-------------------------------------|---------------------------------------------|--------------------------------| | create(options) | POST /databases | Create a database | | edit(dbId, options) | PATCH /databases/{id} | Edit name or RAM | | delete(dbId) | DELETE /databases/{id} | ⚠️ Permanently delete | | metrics(dbId) | GET /databases/{id}/metrics | CPU, RAM, network metrics | | getCertificate(dbId) | GET /databases/{id}/credentials/certificate | Get TLS certificate | | resetCredentials(dbId, type) | POST /databases/{id}/credentials/reset | Reset password or certificate | | listSnapshots(dbId) | GET /databases/{id}/snapshots | List snapshots | | createSnapshot(dbId) | POST /databases/{id}/snapshots | Create a snapshot | | restoreSnapshot(dbId, options) | POST /databases/{id}/snapshots/restore | Restore from snapshot |

Error Handling

import {
  SquareCloudApiError,
  SquareCloudTimeoutError,
  SquareCloudValidationError,
} from "@forkzz/squarecloud";

try {
  await client.apps.get("invalid-id");
} catch (err) {
  if (err instanceof SquareCloudApiError) {
    console.error(`API Error ${err.status}:`, err.message);
    console.error("Body:", err.body);
    console.error("Path:", err.path);
  } else if (err instanceof SquareCloudTimeoutError) {
    console.error(`Timed out after ${err.timeoutMs}ms`);
  } else if (err instanceof SquareCloudValidationError) {
    console.error("Invalid argument:", err.message);
  }
}

Build

npm run build   # outputs CJS, ESM and .d.ts to /dist
npm run dev     # watch mode
npm run lint    # type check

License

GPL-3.0 — © forkzz