External services

An external service is another company's API, such as Stripe, a courier or another Jadpo app, that your actions call. You call it like an SDK: couriers.bookings.create(request). Jadpo makes the HTTP request, adds the secret, picks the host, retries and reads the response. Your code never builds a URL, sets a header or sees a raw response.

Each API is described once, in a provider package: Jadpo source that lists the API's operations, types, failures and webhook events. It also says which calls change something, which take an idempotency key (a value that lets the provider spot a repeated request), how values are written on the wire, how errors and pages of results come back and how webhooks are signed. Your app connects to the package in app.jadpo, and then calls its operations.

The other kind of package, a library package, holds types, failures and pure functions that several apps share, such as a postcode parser.

The next topic says how packages, providers, connections, drivers, capabilities, built-in services and the services Jadpo runs fit together, and where each runs.

Topic	In short
How the pieces fit	Package, provider, connection, driver, capability, built-in service and service run by Jadpo: what each is, where it runs, what is built; Docker or Podman only for a service run by Jadpo
Kinds of package	Library (types, failures, pure functions) and provider (one API); the kind follows from what is inside
The golden rule	A package can do nothing the app cannot, and the app can do everything a package can
The format	`package.jadpo` (`licence:`, `jadpo:`), an optional `provider.jadpo`, folders laid out as `shared/` is, `public` as the API
Where packages live	Installed in `packages/<name>/<version>/`, committed, digest-checked, read-only; the app's own in `shared/providers/`
Where they come from	Jadpo's registry, a git repository, an importer, another Jadpo app's OpenAPI, or written by an agent from the docs
The surface	`surface.jadpo_record`, generated and readable, pointing at each file; `jadpo package show`
Connecting	`connections:` in `app.jadpo`; built-in drivers are configured there, never packaged
Calling	`couriers.bookings.create(request)` and package actions such as `stripe.start_subscription(...)`, from actions only, failures mapped at the call
Decoding	The package declares how values are written on the wire; the runtime decodes; the app translates
Package code	No state; package actions call only their own API; events only about the outside world; polls; services
Several calls in order	Each step recorded before it is sent, replayed on a rerun, stopped as `diverged` on any difference
Receiving	Webhooks, replies, handshakes and queues, each arriving as an event
Acting for each user	OAuth grants owned by one of the app's records; `on_behalf_of:` on every call
Capabilities	Only jobs Jadpo itself does, each whole (email, files, search and the rest); the provider chosen in `app.jadpo`
Development	Provider calls faked by default, let through to the sandbox by name, every call logged
Tests	A generated fake per package; scheduled contract runs against the sandbox