Skip to content
squarecloudofcPublic

Repository files navigation

Square Cloud Banner

@squarecloud/api-types

Official type definitions for the Square Cloud API.

Tip

@squarecloud/api 6 ships its own types and is the recommended way to use the Square Cloud API from JavaScript and TypeScript. Use this package when you call the REST API directly, without the SDK.

Installation

npm install @squarecloud/api-types
# or
yarn add @squarecloud/api-types
# or
pnpm add @squarecloud/api-types

Documentation

The API reference describes every route, payload and error code. Most types in this package also link to their page there.

Getting started

Import the types from @squarecloud/api-types/v2, which covers the /v2 routes of the REST API:

import type { APIApplicationStatusPayload } from "@squarecloud/api-types/v2";

const res = await fetch(`https://api.squarecloud.app/v2/apps/${appId}/status`, {
  headers: { Authorization: process.env.SQUARECLOUD_API_KEY ?? "" },
});
const payload = (await res.json()) as APIApplicationStatusPayload;

if (payload.status === "success") {
  console.log(payload.response.cpu, payload.response.ram);
} else {
  console.error(payload.code, payload.message);
}

You can also import one part of the package: common/v2, utils, payloads/v2 or rest/v2.

import type { RESTPostAPIApplicationCommitQuery } from "@squarecloud/api-types/rest/v2";

Note

@squarecloud/api-types/v2 includes payloads/v2 and rest/v2, together with common/v2 and utils.

Project structure

The types of each API version fall into two groups:

  • Types with an API prefix describe data the REST API returns.
  • Types with a REST prefix are named after a route and describe what you send to it and what it returns.

REST type names follow the pattern REST<HTTP method><Type><Query|JSONBody|FormDataBody|Result|ResultPayload>, such as RESTPostAPIApplicationCommitQuery or RESTPostAPIApplicationUploadResult.

  • A name that ends with Result is the data the route returns.
  • A name that ends with ResultPayload is the whole response, with the status envelope around the data.

The APIErrorCode constant lists the error codes the API returns in code, and each code says when it happens and what to do. The list grows over time, so treat a code you do not know as a generic failure of the HTTP status it came with.

Related projects

Contributing

Bug reports and pull requests are welcome at squarecloudofc/api-types.

Releases

Packages

Used by

Contributors

Languages