SDK reference

The deepspace package exposes five main entry points (plus two for the documentation feature). Each section of this reference documents the surface of one entry point, organized by feature.

import { ... } from 'deepspace'          // React client SDK
import { ... } from 'deepspace/schema'   // Runtime-neutral schemas (browser + worker safe)
import { ... } from 'deepspace/worker'   // Cloudflare Worker runtime
import { ... } from 'deepspace/server'   // Platform-backed server helpers
import { ... } from 'deepspace/testing'  // Playwright fixture (test files only)

Choosing between deepspace/schema and deepspace/worker for schemas: deepspace/schema is the runtime-neutral entry - import from it for any schema (or schema type) that browser or shared code touches, so neither runtime's surface leaks into the other bundle. Reserve deepspace/worker for worker-only helpers (DO classes, auth verification, metering). Every name deepspace/schema exports is also available from deepspace/worker, so worker-only files may keep importing schemas from deepspace/worker.

Client - deepspace#

Everything you import on the frontend - providers, hooks, components, and utility functions.

The client entry also exports the environment helpers and the wire protocol layer documented at the bottom of this page.

Schemas - deepspace/schema#

Runtime-neutral collection declarations - the CollectionSchema / ColumnDefinition / ColumnInterpretation / RolePermissions / PermissionLevel types plus the drop-in schema constants (USERS_COLUMNS, BASE_USERS_SCHEMA, the messaging schemas, AI_CHATS_SCHEMA / AI_MESSAGES_SCHEMA, CONVERSATION_SCHEMAS, DIRECTORY_SCHEMAS, VOTING_SCHEMAS, WORKSPACE_SCHEMAS). See the schemas reference for every shape - the surface is identical, only the import home differs.

// src/schemas/items-schema.ts — imported by both the worker and the browser
import type { CollectionSchema } from 'deepspace/schema'

Worker - deepspace/worker#

Everything you import inside your Cloudflare Worker - DO base classes, schemas, auth verification, AI helpers.

Server - deepspace/server#

Platform-backed helpers for worker-side code that talks to the DeepSpace platform rather than your own DO:

• captureScreenshot - shared Browser Rendering capture. See bindings reference.
• requireSubscription, getSubscription, cancelSubscription, refundInvoice and their error classes - server-side payment gates and operations. See payments reference.

Testing - deepspace/testing#

Multi-user Playwright fixture and account helpers.

• Testing reference - test, expect, users(N), MultiplayerUser, account helpers.

Environment helpers#

Exported from deepspace (and usable in shared code). The SDK detects which environment the code is running in - build-time __DEEPSPACE_ENV__ define, then runtime window.__DEEPSPACE_ENV__, then server-side process.env.DEEPSPACE_ENV, then hostname - and derives the platform service URLs from it.

import { getApiUrl, isLocalDev } from 'deepspace'

const res = await fetch(`${getApiUrl()}/api/health`)
if (isLocalDev()) console.debug('api health', res.status)

Wire protocol layer#

For apps that build their own WebSocket client against a DeepSpace DO instead of using the built-in hooks. Exported from both deepspace and deepspace/worker, so a custom hook and a custom room speak the same typed vocabulary.

import { MSG, clientBuild, dispatch, encode, type ServerMessage } from 'deepspace'

ws.send(encode(clientBuild.put('notes', noteId, { title: 'Hello' })))

ws.onmessage = (event) => {
  dispatch<ServerMessage>(event.data, {
    [MSG.RECORD_CHANGE]: (payload) => applyChange(payload),
    [MSG.ERROR]: (payload) => console.error(payload.error),
  })
}

Most apps should use the records hooks instead - this layer exists for custom clients and custom rooms.

TypeScript signatures#

This reference shows the most common signatures and shapes. For exact type definitions - including generic constraints, optional fields, and discriminated unions - read the bundled .d.ts files:

deepspace/documentation and deepspace/documentation/react back the documentation feature; apps rarely import them directly.

If a hook or type isn't documented in this reference, it probably exists in the .d.ts. Read the declaration before guessing.