Metadata-Version: 2.4
Name: api-sandbox
Version: 0.1.2
Summary: CLI for API sandboxes. Test your APIs in a sandbox env.
Author-email: Subbu Athikunte <subramani.a@digitalapi.ai>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://www.digitalapi.ai/
Project-URL: Documentation, https://github.com/digitalapicraft/api-sandbox/tree/main/docs
Project-URL: Repository, https://github.com/digitalapicraft/api-sandbox
Keywords: api,sandbox,cli,openapi,simulation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=46.0
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.8
Requires-Dist: psycopg[binary]>=3.3
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn>=0.30
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Requires-Dist: pytest>=8.3; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: twine>=6.1; extra == "dev"
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: twine>=6.1; extra == "release"

# `api-sandbox`

`api-sandbox` installs the `sdb` CLI.

Use it to:

- publish an API into a sandbox from an OpenAPI spec
- consume a sandboxed API with issued credentials and bearer login
- inspect traces and exercise customer-facing simulation behavior

Publisher + consumer only. No DAC operator workflows here.

## Install

Recommended:

```bash
pipx install api-sandbox
```

Upgrade:

```bash
pipx upgrade api-sandbox
```

If you already manage your own virtualenv:

```bash
python -m pip install api-sandbox
```

Requirements:

- Python `3.12+`
- `pipx` recommended

Verify:

```bash
sdb --help
sdb doctor --json
```

## Configure A Profile

Hosted sandbox setup:

```bash
export API_SANDBOX_TOKEN=replace-me

sdb config init customer \
  --base-url https://control-plane.example.com \
  --runtime-base-url https://runtime.example.com \
  --control-plane-token-env API_SANDBOX_TOKEN \
  --activate

sdb doctor --json
```

The control-plane token stays outside config JSON.

## Publisher Flow

Import a spec:

```bash
sdb spec import ./openapi.yaml
```

Create a sandbox:

```bash
sdb sandbox create bank-sim --api "Payments API" --mode mock
```

Create release inputs:

```bash
sdb auth create-profile payments-sim \
  --mode simulated \
  --scheme ApiKeyAuth=api_key \
  --scheme BearerAuth=bearer

sdb policy create scope-only
```

Create the release with exact names:

```bash
sdb release create bank-sim \
  --spec "Payments API@2026-04-14" \
  --auth-profile payments-sim \
  --policy-pack scope-only
```

List the release, then promote:

```bash
sdb release list --sandbox bank-sim
sdb release promote bank-sim --alias latest --release <RELEASE_ID>
```

## Consumer Flow

Create an application:

```bash
sdb auth create-app bank-sim partner-app \
  --alias latest \
  --auth-profile payments-sim \
  --scheme BearerAuth
```

Issue client credentials by app name:

```bash
sdb auth issue-client partner-app --sandbox bank-sim --scope refunds.read
```

Discover auth:

```bash
sdb auth discover bank-sim --alias latest
sdb auth scopes bank-sim --alias latest
```

Login once:

```bash
printf '%s\n' "<CLIENT_SECRET>" | sdb auth login bank-sim \
  --alias latest \
  --client-id <CLIENT_ID> \
  --client-secret-stdin \
  --scope refunds.read
```

`auth login` saves a local bearer session by default.

Call the runtime without re-threading the bearer token:

```bash
sdb sandbox request bank-sim GET /refunds/ref_123 --alias latest
```

Inspect traces:

```bash
sdb trace tail bank-sim --limit 10
sdb trace list --sandbox bank-sim
```

## Simulation

Create a customer simulation pack:

```bash
sdb simulation create-pack retail-banking-sim \
  --kind scenario_v1 \
  --seed 'getAccount@{"account_id":"{account_id}","balance":100}' \
  --scenario '{"scenario_id":"credit-ladder","name":"Credit ladder","state_patches":[{"path":"/accounts/{account_id}","body":{"status":"credited"}}]}'
```

List packs or attach one to a release by name:

```bash
sdb simulation list-packs --limit 10
sdb release create bank-sim \
  --spec "Payments API@2026-04-14" \
  --simulation-pack retail-banking-sim
```

## End-User Docs

- Install + setup: [Public CLI install](https://github.com/digitalapicraft/api-sandbox/blob/main/docs/runbooks/public-cli-install.md)
- Publisher journey: [Publisher runbook](https://github.com/digitalapicraft/api-sandbox/blob/main/docs/runbooks/publisher.md)
- Consumer journey: [Consumer runbook](https://github.com/digitalapicraft/api-sandbox/blob/main/docs/runbooks/consumer.md)
- Simulation journey: [Simulation runbook](https://github.com/digitalapicraft/api-sandbox/blob/main/docs/runbooks/simulation.md)
- Troubleshooting: [Troubleshooting](https://github.com/digitalapicraft/api-sandbox/blob/main/docs/runbooks/troubleshooting.md)
- CLI contract: [CLI contract](https://github.com/digitalapicraft/api-sandbox/blob/main/docs/product-specs/cli-contract-sdb.md)

## What Works

- spec import, validate, diff, list, get
- sandbox create, list, get, clone, archive, export-manifest, reset
- release create, list, get, promote
- auth profiles, apps, client credentials, discovery, scopes, login
- exact-name selectors on hot refs: spec, sandbox, auth profile, app, policy pack, simulation pack
- saved bearer sessions reused by `sdb sandbox request`
- customer simulation packs, scenarios, snapshots, timers, webhooks, events
- trace list, get, replay, tail
- `--dry-run`, `--yes`, `--watch`, `--trace`

Homepage: [digitalapi.ai](https://www.digitalapi.ai/)
