@spacefast/sdk

The typed TypeScript client for the Spacefast 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

npm install @spacefast/sdk

Quickstart

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:

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

npm install -g spacefast
sf login
sf api-keys create --name "my-integration"

The key is shown once. Full auth docs: https://spacefast.com/docs/api.

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 — <operationId>Options(), QueryKey(), InfiniteOptions(), Mutation() — plus a small invalidation vocabulary (bySpace, byTeam, STALE_TIME_MS). Spread one into any TanStack Query call:

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/<id>/blobs/<sha> 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:

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:

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 <SiteList sites={sites.data?.data ?? []} />;
}

<QueryClientProvider client={scope.queryClient}>
  <Sites />
</QueryClientProvider>;

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 https://spacefast.com/docs/platforms/api/reference.

Also

• Changelog
• API reference
• MIT licensed.