Error handling
The SDK does not have its own error classes and never retries a request. There are two kinds of errors, and both are thrown (the returned promise rejects):Validation errors
Before sending a request, each method checks some of its arguments and throws a plainError when they are invalid. No request is made in this case.
API errors
Requests are made with Axios. When the API answers with an error status (or cannot be reached), the Axios error is thrown as is:error.response.statusis the HTTP status.error.response.data.erroris the message returned by the API.error.responseisundefinedwhen there was no response at all (network error).
downloadFile asks Axios for binary data, so when it fails error.response.data is a Buffer containing the JSON of the error. Use JSON.parse(error.response.data.toString()) to read the message.Pitfalls
getApplications only returns the first 10 personal applications
getApplications only returns the first 10 personal applications
getApplications() takes no parameters and calls GET /v1/apps without a query string. The API then returns the first page (10 applications) of your personal applications only. Applications of teams and the following pages cannot be requested through the SDK. Check pagination.hasNextPage and call the API directly when you need more.uploadFile without path extracts into a folder named undefined
uploadFile without path extracts into a folder named undefined
/apps/{appId}/upload?path=${path}. When path is omitted, the text undefined is sent and the API extracts the zip into an undefined folder. Always pass path ("/" for the root).uploadFile only accepts zip files, and they are extracted
uploadFile only accepts zip files, and they are extracted
file.zip. A zip is extracted into path, overwriting files with the same name. To send a single file, zip it first.downloadFile always returns a zip
downloadFile always returns a zip
Buffer returned by downloadFile is a zip archive that contains it.Paths are not URL encoded
Paths are not URL encoded
uploadFile and downloadFile insert path in the URL without encoding it. Paths with spaces or with &, #, ? or % may be misread. Encode them yourself with encodeURIComponent.Application.uploadFile takes an object
Application.uploadFile takes an object
app.uploadFile({ file, path }). Passing two positional arguments (app.uploadFile(file, "/path")) fails with File must be a valid Buffer., because the SDK looks for the file and path properties on the first argument.Application.data is never refreshed
Application.data is never refreshed
data of an Application instance is the response of the request that created the instance. Calling start(), stop(), restart() or update() does not change it.start, stop and restart throw when there is nothing to do
start, stop and restart throw when there is nothing to do
500 when you start an application that is already running, stop one that is already stopped, or restart one that is not running. Check currentResourceMetrics.online first, or catch the error.exposedViaWeb cannot be enabled through the SDK
exposedViaWeb cannot be enabled through the SDK
exposedViaWeb is true the API requires port (and assignedSubdomain on creation). The SDK has no parameter for them, so createApplication and updateApplication fail with 400 in that case. Use the API directly to expose an application to the web.The bun runtime is not in the types
The bun runtime is not in the types
"nodejs", "bun" and "python", but runtimeEnvironment is typed as "nodejs" | "python". The SDK does not check the value at runtime, so in TypeScript you can pass "bun" as any.Environment variables: empty values and empty arrays
Environment variables: empty values and empty arrays
value makes the API answer with 500. In updateApplication, omitting environmentVariables keeps the current variables, while passing [] removes all of them.updateApplication always needs appName, memoryMB and runtimeEnvironment
updateApplication always needs appName, memoryMB and runtimeEnvironment
Application.data (name, allocatedMemoryMB, runtimeEnvironment) and send them back. teamId is accepted by the type but ignored.deleteApplication returns the Axios response
deleteApplication returns the Axios response
deleteApplication (and Application.delete) resolves with the complete Axios response. The body is in .data.Rate limits are not handled
Rate limits are not handled
Default import in native ES Modules
Default import in native ES Modules
.mjs file or a "type": "module" project, import CamposCloudSDK from "@camposcloud/sdk" gives you the module object instead of the class. See Getting started.Types are narrower than the responses
Types are narrower than the responses