Packages

The existing tutorial at /tutorials/local-development covers the Python + Make workflow. This section covers the npm package quickstart path and local runtime operated by spaps.

Source Compatibility Snapshot

Verified against Sweet Potato 5b09d3df1194577c5313c865fef1db98f694cdea:

Surface	Source version	Minimum runtime	Authoritative metadata
`spaps` CLI	0.10.1	Node.js 22	`packages/spaps/package.json`
`spaps-sdk`	1.14.1	Node.js 14	`packages/sdk/package.json`
Python `spaps` client	0.7.1	Python 3.9	`packages/python-client/pyproject.toml`
`spaps-server-quickstart`	0.7.1	Python 3.12	`packages/python-server-quickstart/pyproject.toml`

These are checkout versions. Before copying an example, compare your installed version; remote registries and deployed services can lag the source checkout.


npx spaps --version
npm ls spaps-sdk
python -c "from importlib.metadata import version; print(version('spaps'))"
python -c "from importlib.metadata import version; print(version('spaps-server-quickstart'))"

When the published artifact does not match this snapshot, use the sibling checkout explicitly instead of silently mixing versions:


node ../sweet-potato/packages/spaps/bin/spaps.js --version
npm install ../sweet-potato/packages/sdk
pip install ../sweet-potato/packages/python-client
pip install ../sweet-potato/packages/python-server-quickstart

These local-path installs prove source integration only; they do not prove registry publication.

Which quickstart should you use?

Start with	Use it when	First command
`npx spaps`	You have a frontend or Node app and need local auth/runtime quickly without building backend infrastructure first	`npx spaps`
`spaps-server-quickstart`	You are building or extending the FastAPI backend service in this repo	`pip install spaps-server-quickstart`

If you are changing backend routes, middleware, or migrations, stay on the Python path: /tutorials/first-service and /tutorials/local-development.

Pick The Surface

Surface	Install or entry point	Owns	First proof
SPAPS CLI	`npx spaps`	Local runtime, app provisioning, fixtures, auth commands, diagnostics, domain control-plane commands	`npx spaps quickstart --json` then `npx spaps verify --json`
TypeScript SDK	`npm install spaps-sdk`	Browser/server clients, sessions, payments, entitlements, issue reporting, webhook helpers	Create a browser or server client with the correct key type
Python client	`pip install spaps`	Server-to-server auth, sessions, payments, entitlements, issue reporting, webhook helpers	Instantiate `SpapsClient` against the selected API URL
Python quickstart package	`pip install spaps-server-quickstart`	FastAPI app factory, settings, middleware, DB helpers, task setup, server-side helpers	Build the tutorial service and hit `/health`
Companion packages	See Companion packages	Shared types, wallet utilities, React issue-reporting UI	Run the package-specific build or test command

Capability matrix

Use this matrix to find which package surface owns a feature; click into each package page for the API shape.

Capability	TypeScript SDK (`spaps-sdk`)	Python client	SPAPS CLI	Companion packages
Auth & session	`auth` and `sessions` namespaces	`auth`, `sessions`, `DeviceFlowClient`	`spaps login` / `connect` / `whoami` / `token` / `logout`	—
Billing & entitlements	`payments` and `entitlements` namespaces	`payments`, `EntitlementsClient`	—	—
Wallet	—	—	—	`spaps-wallet-utils` (EVM connect/switch/sign)
Webhooks delivery	`verifyCryptoWebhookSignature`	`verify_spaps_webhook`, `verify_crypto_webhook_signature`	`spaps webhook list` / `register`	—
Issue reporting	`issueReporting` namespace	`IssueReportingClient`	`spaps issue-reports list-mine`	`spaps-issue-reporting-react` provider, hooks, and components
Local runtime	—	—	`spaps local`, `spaps status`, `spaps verify`, `spaps doctor`	—
Reusable FastAPI app	—	—	—	`spaps-server-quickstart` package API

npm Quickstart Path


npx spaps
npx spaps local
npx spaps quickstart --json
npx spaps connect
npx spaps verify --json
npx spaps create demo-app --template react
npx spaps fixtures apply --base-url http://localhost:5173

Package Docs In This Section

SPAPS CLI Quickstart Local Runtime Integration Recipes TypeScript SDK Python Client Companion Packages

/tutorials/local-development for Docker + Make local stack operations inside the sweet-potato repo.
/guides/auth-and-local-mode for API-key rules and local-mode behavior in the Python server.
/operations/troubleshooting for backend diagnostics when runtime startup fails.