# Provider calls in development

In `jadpo dev`, every call to a provider is faked by default, so nothing
leaves your machine and you need no credential. You let chosen calls
through to the provider's sandbox when you want real answers, and never
to the live service.

## Faked answers

A faked call is answered, in this order, by:

1. what `jadpo calls script` set for it (below);
2. the operation's recording, when the package keeps one, its
   placeholders filled with generated values of the right types (logged
   as `recording`);
3. the operation's generated default, a valid value of its output type
   ([Tests and fakes](tests-and-fakes.md)).

A provider connection's setting that nothing gives (its credential,
environment or address) gets a stand-in value, so the app starts with no
credential set.

## Letting calls through to the sandbox

Name the operations or whole resources that go to the provider's sandbox
in `development: { sandbox: }` on the connection, where review and agents
see it. Each name is an operation, `resource.operation`, or a whole
resource, and is checked against the package
(`connection.value_invalid`):

```jadpo
application {
    connections: {
        couriers: {
            package: AcmeCouriers.v1
            domains: [shipping]
            environment: config.couriers_environment
            development: {
                sandbox: [bookings.create]
            }
        }
    }
}
```

The named calls go to the sandbox once the sandbox credential is set in
`.env.local`. Until then the connection stays faked, and `jadpo dev`
prints one line naming the setting to set. Only the credential is per
developer; everything else about where calls go is in `app.jadpo`.

A connection whose environment is `live` stops `jadpo dev` starting, or
a save reloading, with `cli.dev_start_failed`. Calls never go to the live
service from `jadpo dev`.

`--sandbox` and `--fake` on `jadpo dev` change one session only, and
nothing about them is kept: `--sandbox couriers.pickups.create` (or a
resource) lets a call through, and `--fake couriers` fakes a connection.

## Scripting the next answer

`jadpo calls script <operation> <failure>` sets the next answer for an
operation, as a test's `fakes:` does
([Fakes for integrations](fakes-for-integrations.md)), so an
agent can walk a failure path by hand. Fakes keep no state: a flow that
creates an object and then reads it either lets both calls through or
scripts the read.

## The call log

Every call is logged, faked or real, with its connection, operation,
inputs and answer in full (in development only, and never a secret), its
source (`recording`, `generated`, `scripted` or `sandbox`), attempts,
duration and request id. Read it with `jadpo calls` (`--connection`,
`--operation`, `--request`), `jadpo calls show <id>`, `jadpo trace` and
`--json`. Calls are kept with the last 500 timelines in `build/dev/`,
never committed. [Debugging and review](debugging-and-review.md)
otherwise hashes the text it shows; call payloads in development are the
one exception. Production keeps telemetry spans with no values
([Telemetry](telemetry.md)).

Each request's line in `jadpo dev` lists its calls:

```text
jadpo dev, started 07:34:33
listening on http://localhost:3918
    routes     2 routes
    settings   2 checked
    providers  couriers faked
serving: saves reload, press ctrl-c to quit
req_58d4  POST /pickups                      201   9 ms   127.0.0.1
  └─ couriers.pickups.create · generated · answered
req_9588  POST /pickups                      409 pickup_slot_gone   1 ms   127.0.0.1
  └─ couriers.pickups.create · scripted · slot_taken
```

How each part works is under
[Fakes and the development call log](fakes-and-the-development-call-log.md).

> `jadpo trace` and the timelines aren't built yet. The call log keeps
> the last 500 calls.