# @spacefast/sdk > Typed TypeScript client for the Spacefast API, generated from the public OpenAPI spec. Latest version **0.5.0** (published 2026-09-27) · MIT license · 0 weekly downloads ## Install ```sh npm install @spacefast/sdk pnpm add @spacefast/sdk yarn add @spacefast/sdk bun add @spacefast/sdk ``` ## Health **Score 60/100 (C)** — status: active. Positive: esm support; no vulnerabilities; recently updated; high maintenance score. Warnings: low downloads; no types; large bundle; pre 1.0. ## Facts | | | |---|---| | Version | 0.5.0 | | Published | 2026-09-27 | | First published | 2026-06-30 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | ESM | | Node | >=20 | | Dependencies | 2 | | Unpacked size | 35.1 MB | | Known vulnerabilities | 0 | | Install scripts | no | | Maintainers | bi | ## Links - npm: https://www.npmjs.com/package/@spacefast/sdk - Repository: https://github.com/spacefast/monorepo - Homepage: https://github.com/spacefast/monorepo#readme - Issues: https://github.com/spacefast/monorepo/issues - npm.io page: https://npm.io/package/@spacefast/sdk ## Dependencies (2) - [ignore](https://npm.io/package/ignore.md) ^7.0.6 - [@spacefast/common](https://npm.io/package/@spacefast/common.md) 0.5.0 ## Recent versions - 0.5.0 (latest) — 2026-09-27 - 0.4.1 — 2026-09-10 - 0.2.2 — 2026-08-28 - 0.0.26 — 2026-08-22 - 0.0.24 — 2026-08-12 - 0.0.23 — 2026-08-06 - 0.0.21 — 2026-08-05 - 0.0.20 — 2026-08-05 - 0.0.19 — 2026-08-05 - 0.0.18 — 2026-08-05 - 0.0.17 — 2026-08-05 - 0.0.13 — 2026-07-31 - 0.0.12 — 2026-07-27 - 0.0.11 — 2026-07-19 - 0.0.10 — 2026-07-19 - … 7 more at https://npm.io/package/@spacefast/sdk/versions ## README # @spacefast/sdk The typed TypeScript client for the [Spacefast](https://spacefast.com) API. Every path, parameter and response body is generated from the published OpenAPI spec, so the compiler knows which routes exist, which arguments they take, and what comes back — autocomplete a path string and the rest of the call types itself. No runtime dependencies, works anywhere `fetch` does. ## Install ```sh npm install @spacefast/sdk ``` ## Quickstart ```ts import { createSpacefastClient, SpacefastApiError } from "@spacefast/sdk"; const client = createSpacefastClient({ baseUrl: "https://api.spacefast.com", apiKey: process.env.SPACEFAST_API_KEY, }); try { // Typed all the way through: the path picks the operation, `path` and `query` // are checked against it, and `space` is the space resource. const space = await client.get("/v1/spaces/{spaceId}", { path: { spaceId: "spc_..." } }); console.log(space.slug, space.liveUrl); } catch (error) { if (!(error instanceof SpacefastApiError)) throw error; // Failures are RFC 9457 problem documents, kept whole. console.error(error.status, error.code, error.message); console.error(error.pointer); // JSON Pointer into your body, on validation errors console.error(error.next); // copy-pasteable commands that fix it console.error(error.requestId); // quote this in a support request } ``` Plain `{ data }` responses unwrap to the resource. Paginated lists come back whole, so `pagination` is still there: ```ts const { data: spaces, pagination } = await client.get("/v1/spaces", { query: { limit: 20 } }); ``` Mutations take `body`, and any of them can carry an `idempotencyKey` that makes a retry safe. ## Getting a credential ```sh npm install -g spacefast sf login sf api-keys create --name "my-integration" ``` The key is shown once. Full auth docs: . ## What's in the box | Import | What it gives you | | ----------------------------- | ---------------------------------------------------------------------- | | `@spacefast/sdk` | `createSpacefastClient`, `SpacefastApiError`, the operation index | | `@spacefast/sdk/schema` | The raw generated `paths` and `components` types | | `@spacefast/sdk/query` | TanStack Query factories for every operation | | `@spacefast/sdk/transport` | The HTTP core — retries, problem-document parsing — for custom clients | | `@spacefast/sdk/publish` | The publish pipeline: manifest, upload, finalize, wait | | `@spacefast/sdk/openapi.json` | The spec itself, for your own codegen | ### `@spacefast/sdk/query` Every operation also ships as TanStack Query option factories — `Options()`, `QueryKey()`, `InfiniteOptions()`, `Mutation()` — plus a small invalidation vocabulary (`bySpace`, `byTeam`, `STALE_TIME_MS`). Spread one into any TanStack Query call: ```ts import { getSpaceOptions, bySpace, STALE_TIME_MS } from "@spacefast/sdk/query"; const space = useQuery({ ...getSpaceOptions({ path: { spaceId } }), staleTime: STALE_TIME_MS.normal, }); queryClient.invalidateQueries({ queryKey: bySpace(spaceId) }); ``` This layer authenticates with browser session cookies by default. Use `configureSpacefastQuery({ apiKey, credentials: "omit" })` for one API key or partner token per process and cache. Point it at another API origin with the same call. Do not switch credentials without also replacing or clearing the `QueryClient`; credentials intentionally stay out of query keys. `@tanstack/react-query` is an optional peer dependency, and only this subpath imports it. ### `@spacefast/sdk/publish` The four steps of a publish, importable as one barrel: build a manifest (`manifestFileEntry`), open a version (`createVersionIntent`), push the bytes (`uploadSessionFiles`), finalize and wait (`finalizeVersion`, `waitUntil`). `publishDirect` is the one-request shortcut for small payloads. `uploadSessionFiles` requires the `apiUrl` you configured for the transport. That origin is what a relative upload target resolves against, and the only non-runtime origin an upload may reach. Pass your own configured value — never one read back out of the upload session. Every request is then bound to the session response that origin returned: bytes go only to a host that response named, and only to a runtime upload endpoint naming your own Space or upload session. A route that merely _looks_ like yours does not admit a host — the Space id in `/spaces//blobs/` is already in every legitimate target, so anyone could copy it. Filesystem walking lives one level down in `@spacefast/sdk/publish/node` (`collectManifest`), which is Node-only and stays out of the barrel so browser bundles don't pull in `node:fs`. ## The partner tier Partner applications get the complete partner contract without local codegen: ```ts import { createSpacefastPartnerClient } from "@spacefast/sdk/partner"; const partner = createSpacefastPartnerClient({ baseUrl: "https://api.spacefast.com", apiKey: process.env.SPACEFAST_PARTNER_API_KEY, }); const principals = await partner.get("/v1/principals", { query: { limit: 100 }, }); ``` The partner family includes all consumer operations plus tenant, principal, usage, and other partner-only operations. It uses the same transport, `SpacefastApiError`, envelopes, retries, and idempotency behavior as the consumer client. Use `@spacefast/sdk/partner/query` for TanStack Query and React Query: ```tsx import { QueryClientProvider, useQuery } from "@tanstack/react-query"; import { createSpacefastPartnerQueryScope } from "@spacefast/sdk/partner/query"; const scope = createSpacefastPartnerQueryScope({ requestOrigin: "https://api.spacefast.com", identity: { type: "customer", teamId: partnerTeam.id, issuer: "https://partner.example", principalId: customer.id, }, credential: { kind: "bearer-provider", getAccessToken: () => currentCustomerToken(), }, }); function Sites() { const sites = useQuery(scope.query.listSpacesOptions({ query: { limit: 50 } })); return ; } ; ``` One scope owns one generated HTTP client and one `QueryClient`. Refreshing the token inside the same principal is safe. Create and dispose a scope when the principal changes, so cached customer data cannot cross identities. Lower-level types and the exact generation input are available from `@spacefast/sdk/partner/schema` and `@spacefast/sdk/openapi.partner.json`. Start at . ## Also - [Changelog](./CHANGELOG.md) - [API reference](https://spacefast.com/docs/api/reference) - MIT licensed. --- _Source: https://npm.io/package/@spacefast/sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._