About the SDK
What the JavaScript SDK does, where it runs, and how it checks what goes in and out.
The JavaScript SDK is the digitospace package on npm. It calls the same APIs the rest of these docs describe, from code that runs on your servers, with an organisation API key. Everything it does counts toward the project it works in, on your organisation’s bill.
One client for every product
Import space and use the product you need:
| Part | Product | Does |
|---|---|---|
space.fs | Storage | Writes, reads, lists, copies, and deletes files, and manages buckets |
space.ai | AI | Sends chat calls, with or without streaming, and reads models, usage, and limits |
space.schedule | Scheduler | Creates and manages jobs, reads their runs, and checks calls the scheduler makes to your app |
space.hooks | Webhooks | Manages sources, destinations, and connections, reads events and deliveries, and checks deliveries to your app |
space reads your API key and project from the environment. To pass them yourself, or to work in several projects from one app, make your own client with createSpace(). See createSpace() and space.
Typed and checked
Every function has TypeScript types, and the SDK checks values at run time too:
- Before a call is sent. Options, paths, bucket names, keys, messages, and settings are checked first. A wrong value fails with the code
validation_failedand a list ofissuesnaming each field, and nothing is sent. - After an answer arrives. Every answer is checked against the shape the types promise. An answer this version does not understand fails with
unexpected_response, rather than reaching your code with missing fields.
Every failure is a SpaceError with a stable code to branch on. See Handle errors.
It runs on your servers
The SDK holds an API key, and anyone who can see a key can use it. So the SDK runs only on servers: Node 20.3 or newer, Bun, Deno, and Cloudflare Workers. In a web page it refuses every call with browser_not_allowed. See Limits and runtimes.
It does not sign in your app’s users. Your app signs its own users in, and calls the SDK from its backend on their behalf.
What it does for you
- Pages. A list gives every item, fetching page after page as you read. See Paging.
- Retries. A call that is safe to repeat is tried again after a network failure or a busy service. A write that may already have happened is never repeated. See Retries.
- Timeouts and cancelling. Every call has a time limit, and every function takes an
AbortSignal. See Timeouts. - Uploads and downloads.
space.fs.writesends a file with a checksum, so storage keeps exactly the bytes you sent, andspace.fs.readgives a file back as text, JSON, bytes, a blob, or a stream. - Signed calls.
space.schedule.verifyandspace.hooks.verifycheck that a call to your app came from us. See Verify calls to your app.
The SDK logs nothing and sends no telemetry. It identifies itself with a User-Agent of digitospace/<version>.
Last updated