# PhotoPrintAgent self-service sandbox

Start at https://photoprintagent.com/developers#sandbox. No account, inbox, owner approval, OAuth approval or manually issued key is required. This sandbox is deliberately separate from production: it cannot charge, accept payment details, or send anything to fulfillment.

## Discovery and authentication

- Public production MCP discovery tool: `get_sandbox_options`.
- Sandbox Streamable HTTP endpoint: `https://photoprintagent.com/mcp/sandbox`.
- REST discovery: `GET https://photoprintagent.com/api/sandbox/options`.
- Machine-readable contract: https://photoprintagent.com/docs/sandbox.json.
- For MCP POSTs send `Content-Type: application/json` and `Accept: application/json, text/event-stream`.
- Call `start_sandbox` with `{"integrationName":"iSuper 8"}`, without Authorization. Or POST that JSON to `/api/sandbox/sessions`.
- Save the returned `token` securely. On subsequent sandbox requests use `Authorization: Bearer <token>`. The prefix is `pps_`; it is not an account key or guest checkout token.
- Credentials last 24 hours. Call `revoke_sandbox` or DELETE `/api/sandbox/session` to revoke immediately. No refresh or password is needed. Revocation prevents new operations and stops future webhook attempts; an already in-flight HTTP delivery may finish.
- Production credentials are rejected here. Sandbox credentials are rejected by production. Never put credentials in URLs, source control, logs or screenshots.
- MCP tools `get_sandbox_options`, `list_products`, and `start_sandbox` are public. All other tools require the sandbox credential.
- Each private MCP tool also has a REST equivalent: POST `/api/sandbox/tools/<tool_name>` with the same JSON arguments.

A client configuration after provisioning:
```json
{"mcpServers":{"photoprintagent-sandbox":{"url":"https://photoprintagent.com/mcp/sandbox","headers":{"Authorization":"Bearer <sandbox-token>"}}}}
```
Use your client's supported secret store or environment substitution instead of saving the actual credential in shared configuration.

## Run the complete example

Requires Node.js 22 or newer; no packages, account, image editor, public callback server or payment method are needed.

```sh
curl --fail --proto '=https' --tlsv1.2 https://photoprintagent.com/sdk/sandbox-walkthrough.mjs -o sandbox-walkthrough.mjs
node sandbox-walkthrough.mjs
```

Review the downloaded source before running. The example provisions one ephemeral sandbox, discovers the product, downloads synthetic bear artwork, uploads it, creates and downloads the exact crop preview, quotes a synthetic address, registers the built-in HTTP receiver, simulates checkout, recovers by client reference, tests an idempotent retry, waits for an actual signed HTTP delivery and independently verifies its signature. It revokes its credential in a finally block. It prints only non-secret result identifiers and checks, never the credential or signing secret.

The script uses MCP tools plus authenticated binary upload and preview URLs. On a timeout it retries the same request identifiers, rather than opening another order. An optional `PPA_SANDBOX_TOKEN` uses an existing fresh sandbox instead; the script does not revoke a credential you supplied.

## Glossy 4x6 product and artwork

`list_products` returns these structured fields:

```json
{
  "id":"p-0f3fba1a71305db628118c5e155f0280",
  "productCode":"PPA0F3FBA1A7130",
  "sku":"PPA0F3FBA1A7130",
  "title":"Print 4x6",
  "finish":"Glossy",
  "widthInches":4,
  "heightInches":6,
  "artwork":{
    "widthPixels":1205,
    "heightPixels":1807,
    "recommendedDpi":300,
    "minimumDpi":100,
    "minimumDpiIsRejectionThreshold":false,
    "allowRotate":false,
    "minImages":1,
    "maxImages":1,
    "bleed":{"left":9,"right":9,"top":12,"bottom":12},
    "colorSpace":"sRGB",
    "outputMimeType":"image/jpeg"
  }
}
```

These identifiers and dimensions were checked against the public catalog on November 13, 2026. This is a fixed sandbox fixture, not a live availability promise. Production integrations must discover current `products[]` using `list_products` with `{"finish":"Glossy","widthInches":4,"heightInches":6}`. The legacy top-level `product` entry `photo-4x6` / `PPA5B2F748CE094` is a compatibility default; it does not identify this verified glossy product. Do not infer its finish.

The sandbox accepts single-frame JPEG, PNG and WebP, up to 2 MiB and 12 million decoded pixels. It applies EXIF orientation, strips metadata, flattens transparency to white and converts to sRGB. The sample is https://photoprintagent.com/api/sandbox/sample.png. Lower resolution receives a nonblocking quality warning. Cover crops at normalized `centerX`/`centerY`; contain preserves the image with white borders. Download the authenticated JPEG preview to inspect the exact 1205×1807 artwork before proceeding.

## Walkthrough tool sequence

1. `get_sandbox_options {}` → endpoints and fixtures.
2. `start_sandbox {"integrationName":"iSuper 8"}` → save token.
3. Authenticated `list_products {}` → select Glossy 4×6 by structured fields.
4. `create_upload {}` → POST sample image bytes to uploadUrl, with Bearer, image/png and a unique stable Idempotency-Key. Save photoId.
5. `preview_print_item {"photoId":"<photoId>","fit":"cover","centerX":0.5,"centerY":0.5}` → download previewUrl with Bearer.
6. `quote_prints` with previewId, quantity 1 and the exact synthetic shipping fixture below.
7. `register_webhook {}` → built-in receiver URL and one-time signing secret.
8. `simulate_checkout {"quoteId":"<quoteId>","clientReference":"isuper8-demo-001","idempotencyKey":"isuper8-demo-order-001"}`.
9. `get_order {"clientReference":"isuper8-demo-001"}` → recover the same order after a timeout.
10. `get_webhook_receipts {}` → exact received rawBody, signature headers and delivery states. Pending means not yet delivered. `retry_webhooks {}` can retry pending/failed events without repeating checkout.
11. `revoke_sandbox {}`.

Only this synthetic address is accepted; no real customer details should be uploaded:
```json
{"firstName":"Sandbox","lastName":"Customer","email":"sandbox@example.test","phone":"2025550100","address1":"123 Sandbox Test Lane","city":"Testville","state":"CT","postalCode":"00000","country":"US"}
```

Test prices are 35 cents per print, 299 cents shipping, and synthetic 6.25% tax rounded once on prints plus shipping. A single print totals 355 cents in the simulated quote. `chargedCents` is always zero. Quotes expire in 15 minutes or at sandbox expiry, whichever is first. Orders return `status:"simulated_complete"`, `paymentStatus:"simulated"`, `environment:"sandbox"`, and `fulfillmentEnabled:false`. These are not real charges, deliveries or tax calculations.

## Recovery and isolation

An upload's idempotency key is scoped to the sandbox and exact image bytes; different bytes with the same key return 409. Preview retries with identical photo/crop options return the same preview. Quote creation can produce another harmless quote; only checkout is order-creating.

Checkout atomically stores the order, client reference and key mapping. Retrying the same key and quote/reference returns the original order, even after the quote expires. A conflicting key returns 409. A client reference cannot point to two orders: the same reference and quote return the existing order; a different quote returns 409. Preserve your reference/key until you have reconciled the result.

Use `get_order` by clientReference or GET `/api/sandbox/orders?clientReference=<reference>`. A 404 means no matching order in this sandbox; retry the original checkout with its original key. Never switch to the production endpoint to resolve a sandbox timeout. Tenant credentials cannot read another sandbox's images, previews, quotes, orders, receivers or receipts. Credentials cannot be refreshed after expiry; expired test data is cleaned up automatically.

Limits per sandbox: 500 authenticated operations, 20 uploads, 40 crop previews, 40 quotes, 20 orders, one webhook, and up to 10 copies per order. Provisioning is limited to 10 sandboxes per source IP per hour and 200 per day globally. HTTP 429 is a limit, not an order failure. Do not provision repeated replacements to bypass limits. Revocation still works after the request limit.

## External signed webhooks

To test your own receiver, pass its public HTTPS URL to `register_webhook`. The service first POSTs `{"type":"sandbox.endpoint_verification","challenge":"<random-value>"}`. Respond with a 2xx JSON body containing that exact `challenge`. No order or secret is sent during verification. Keep this endpoint separate from production webhooks.

After registration, save the one-time secret. Order events are sent by actual HTTP POST, with:
- `X-PPA-Timestamp`: Unix seconds.
- `X-PPA-Signature`: lowercase hex HMAC-SHA256 of `timestamp + "." + exact raw request body`, keyed by the secret.
- `X-PPA-Event-Id`: stable event UUID.
- `X-PPA-Environment: sandbox`; also verify the signed body contains `environment:"sandbox"`.

Reject timestamps more than five minutes old or ahead; compare HMACs in constant time before parsing or acting on data. Deduplicate the signed event ID (and orderId/sequence), and verify it matches the header. Respond 2xx only after durably accepting the event. The built-in receiver follows these checks and exposes received bodies for independent verification. It is a test tool, not proof that your own external handler works.

Delivery is at least once. Failed requests use bounded backoff and eight attempts; event IDs/raw bodies remain stable while timestamp/signature are refreshed. Pending delivery survives request interruption. The scheduled worker retries it; `get_webhook_receipts` distinguishes pending, failed and delivered. No redirects, private addresses, credentials in URLs or nonstandard HTTPS ports are allowed. DNS is checked and pinned on every request. Revoking/expiring a sandbox stops new attempts.
