# Theirway for agents

What an agent can do with Theirway today, at https://theirway.app/agents.
Runnable curl and Python examples are on that page.

An agent holding a personal access token that a person made can create a
delivery of files, upload them, make the client's link, email it and read
the checksums back. A CI job can also keep a delivery up to date and
snapshot each version (below). The client still opens the link and downloads
by hand.

## What it does not do

- No machine address for the latest build, and no webhooks. Nothing is
  pushed to an agent when the client downloads. It can ask for the
  delivery's events.
- An agent cannot sign itself up. Accounts are invite only, and a token is
  made by a signed-in person. No account: ask your human to join the waiting
  list at https://theirway.app/agents#join, or write to hello@theirway.app.
- Checksums are as reported when the file was uploaded. Theirway keeps the
  SHA-256 you send and shows it. It does not work it out again, and it does
  not say who made the file. Sign your builds.

## The token

A person signs in at https://theirway.app/app/, opens Access tokens, names
the token, ticks what it may do, chooses 30 days, 90 days or a year, and
presses Create token. It is shown once. Keep it in an environment variable,
THEIRWAY_TOKEN, never in a URL or a committed file. Send it as
`Authorization: Bearer <token>`. It can be revoked on the same page.

Least privilege for an agent that sends deliveries:

| Scope | Ticked in the app as | Lets the agent |
|---|---|---|
| `deliveries:write` | Create deliveries and upload | create, upload, change release notes, withdraw |
| `deliveries:read` | See deliveries | read files, checksums and events |
| `recipients:send` | Send to clients | make a client's link and email it |

Leave Send to clients off for an agent that only uploads, and Ask other
people for files off.

## The steps

Base: https://theirway.app/api/v1. A create takes an `Idempotency-Key`
header; a retry with the same key returns the first answer.

1. `POST /deliveries` with `{"title", "client_name", "client_email"?,
   "presentation": "files", "description": "release notes"}` returns `id`.
   `presentation` is "files" or "pictures", chosen now and never changed.
   `description` is plain text, at most 10,000 characters.
2. `POST /deliveries/{id}/uploads` with `{"filename", "type", "size",
   "relative_path", "sha256"}` returns `uploadId` and `key`. Send the
   SHA-256 here: it is what the client's page shows. An upload that sends
   none is stored without one. 409 `conflict` means
   you already store this file; its detail names it; attach it with
   `POST /deliveries/{id}/files`.
3. For each part n: `GET /deliveries/{id}/uploads/{uploadId}/parts/{n}?key=KEY`
   returns `url`. `PUT` the part's bytes to that url, to storage, with no
   token. Keep the `ETag` response header. Parts are 5 MiB or more except
   the last, at most 10,000. A file under 5 MiB is one part.
4. `POST /deliveries/{id}/uploads/{uploadId}/complete?key=KEY` with
   `{"parts": [{"PartNumber": 1, "ETag": "..."}]}` returns 204 with no body;
   the id of the file it made is in the `Theirway-File-Id` response header.
   The declared size must equal the bytes uploaded, or 422. An interrupted upload:
   `GET /deliveries/{id}/uploads/{uploadId}?key=KEY` lists the parts storage
   has.
5. `POST /deliveries/{id}/recipients` with `{"name", "email"}` returns `id`
   and `link`. Anyone holding the link can download.
6. `POST /deliveries/{id}/recipients/{recipientId}/email`, no body, emails the
   link to that address. Fixed words, Reply-To your account address. The
   answer "sent" means handed to the mail service, not delivered.
7. `GET /deliveries/{id}/files` returns each file's size and `sha256` (null
   for a file stored without one; 100 a page; pass `next` back as `after`).
   `GET /deliveries/{id}/events` returns what happened.
8. `DELETE /deliveries/{id}` withdraws it. It can be restored for 30 days.

## In a CI job: upload each build, then snapshot it

A CI job can keep one delivery up to date and, when a version ships, make a
snapshot: a frozen copy of the files you choose, with its own link and one
tag, such as v2.4.1, that never moves. The token needs `deliveries:write`
and `deliveries:read`; add `recipients:send` only if the job also makes the
snapshot's link. Nothing updates or snapshots by itself: the job asks.
Runnable curl for this is on https://theirway.app/agents#ci.

1. Once, a person or the first run creates the delivery (step 1 above),
   keeps its `id` in a CI variable, and calls
   `PUT /deliveries/{id}/mode` with `{"mode": "maintained"}`. Only a
   delivery kept up to date can have snapshots. Asking for the mode it
   already has changes nothing.
2. Each build, upload the file as in steps 2 to 4 above, with its SHA-256:
   a snapshot refuses a file that has none. Uploading the same name again
   adds a second file of that name beside the first.
3. Keep the file's id: the answer to completing the upload (step 4 above)
   names the file it made in the `Theirway-File-Id` header, so the job needs
   no search, and an earlier build of the same name is never mistaken for it.
4. `POST /deliveries/{id}/snapshots` with `{"tag", "note"?, "file_ids":
   [...]}` and an `Idempotency-Key` returns 200 with the snapshot's `id`,
   `tag`, `files`, `bytes` and `manifest_sha256`, the SHA-256 of its
   SHA256SUMS list.
5. A snapshot is a delivery of its own, with its own link: make it as in
   step 5 above, with the snapshot's `id`. It takes no more of your
   storage.

A retry with the same key and body answers the first snapshot, not a
second. The key belongs to your token and is kept 24 hours, so make it name
the delivery as well as the tag, for example `snapshot-<delivery id>-<tag>`.
After that, the same tag answers 409: a tag is never used twice, not even
after its snapshot is erased. A file that cannot go in (retracted, removed
by Theirway, or with no checksum) makes it 409 `snapshot-refused`, naming
every such file and why; no snapshot is made.

## Limits

- Each account has a storage quota. A file past it is refused with 413.
- A signed part URL works for an hour. An `Idempotency-Key` is kept 24 hours.
- Email: the same link once every 10 minutes; an account 20 an hour and 50 a
  day. Theirway may refuse an address and does not say why. Copying the link
  and sending it yourself always works. No text of your own and no checksum
  in the email.
- Errors are `application/problem+json`; `detail` says what to do next.

## Elsewhere

- OpenAPI: https://theirway.app/api/v1/openapi.json
- Machine-readable index: https://theirway.app/files/llms.txt
- Theirway for files: https://theirway.app/files
