Image Relay live-verify runbook (kind: imagerelay)

The tenant-day checklist for the imagerelay driver. Every endpoint path and field name in that driver comes from Image Relay's public v2 documentation and none of it has been confirmed against a real tenant; this pass confirms the driver against your tenant. Steps 1 and 2 store nothing; step 3 writes only into your own store. About 30 minutes. Canto owns the platform now, so check the fork matrix first and confirm this is the driver you exit through at all.

Before you start

• An Image Relay tenant you are allowed to test against, and a folder id if you want step 3 scoped to one folder.
• The sealed OAuth blob, {"clientId":"…","clientSecret":"…","refreshToken":"…"}, from an app you registered in Image Relay with read access.
• A refresh token minted against that app, obtained by hand through Image Relay's own documented authorization-code flow: lw providers auth registers no consent flow for this kind. Record the authorize and token URLs you used; confirming them is rows 5 and 5a.
• catalog.provider.manage on this instance, plus catalog.provider.credential (owner-only) for the credential and enable in step 3.
• One file per type you plan to exit (a photo, a PDF, a video) that you can also open in the Image Relay UI, for step 3.

Step 1: auth

export LW_BASE=https://lolly.example
lw login --cookie 'lw_session=…'          # dev instances: lw login --email you@acme.example

lw providers preview --kind imagerelay

The credential prompt is hidden; paste the blob on one line. health ok - imagerelay followed by a mapped sample table means the token exchange and the first list call both worked, and that table is where you pick the file id step 2 needs. Exit code 2 means health failed.

Step 2: capture the shape

lw providers preview --kind imagerelay --shape --remote-id 55 > imagerelay-shape.txt

Shape mode lists no sample and returns no values: key names and types only, so that file is sendable as it stands (the credential prompt goes to stderr). It runs only when health is ok. --remote-id (any id from the step 1 table) adds a second report, on the call resolveBlob reads: it re-reads one file and follows the link in that response, so the wrapper and the download-link keys are guesses no list page can answer. That is rows 17 and 18. Still read-only: JSON about one file, never its bytes.

imagerelay  GET /api/v2/files?per_page=100&page=1
  envelope: files: object[] (100) · meta: { next_page: null }
  record: (100 under "files", keys unioned)
    id: number · filename: string · name: string · extension: string · size: number
    updated_at: string · keywords: string[] · deleted: boolean
    folder: { id: number, name: string } · custom_fields: { Expiry Date: string }
    quick_link: string
  MAPPED BY THIS DRIVER: files · meta · id · filename · name · extension · size · updated_at
    keywords · deleted · folder · custom_fields
  IN THE RESPONSE, NOT MAPPED: quick_link
  EXPECTED BY THIS DRIVER, ABSENT: (none)

imagerelay  GET /api/v2/files/55
  envelope: file: { id: number, filename: string, size: number, download_url: string, … }
  record: (the one record this call returned, wrapped in "file")
    id: number · filename: string · size: number · download_url: string · quick_link: string
  MAPPED BY THIS DRIVER: file · download_url · size
  IN THE RESPONSE, NOT MAPPED: id · filename · quick_link
  EXPECTED BY THIS DRIVER, ABSENT: (none)

• EXPECTED BY THIS DRIVER, ABSENT is the answer. Each entry reads key|alternatives (CONSTANT_NAME), so it identifies the constant to widen; (none) means every guess matched.
• IN THE RESPONSE, NOT MAPPED holds the replacement: an ABSENT updated_at (UPDATED_AT_KEYS) beside a NOT MAPPED modified_at is one constant edit.
• Record keys are unioned across the page, and tags fold (keywords+tags) rather than falling back, so read the record: block to see which half this tenant sends. On the detail report that row answers the wrapper question: a tenant wrapping under a name this driver does not try reads as not wrapped, with the wrapper key in NOT MAPPED and the link ABSENT.

The assumption table

One row per LIVE-VERIFY bullet in the driver header (server/src/catalog/providers/imagerelay.ts), with the field-names bullet expanded per constant. If a row and that header disagree, the header is right and this table is stale.

Step 3: bytes

Only a blob fetch proves the export capability the exit depends on, so this step creates a real provider record.

lw providers add acme-imagerelay --kind imagerelay --label "Acme Image Relay" \
    --options '{"folderId":"1234","recursive":true}' \
    --exposure '{"groups":["admin"]}'     # verification pass: admins only, not the whole org
lw providers credential acme-imagerelay   # same blob as step 1, prompt hidden
lw providers enable acme-imagerelay       # owner-only
lw providers sync acme-imagerelay         # federation proof: read the count and any notes
lw providers materialize acme-imagerelay --remote-id 55 --json

--remote-id filters the walk rather than skipping it, so options.folderId is what keeps the pass short and inside the 5 req/s cap. Every per-asset failure prints under the summary as <remoteId>: <message>, and each message identifies the assumption that broke, the constant to edit and this page.

The fidelity check (true original, or a recompressed rendition?):

curl -sS -b "$(cat ~/.config/lolly-work/session)" \
    "$LW_BASE/catalog/ext/acme-imagerelay/55/download" -o /tmp/imagerelay-lolly.bin
shasum -a 256 /tmp/imagerelay-lolly.bin
file /tmp/imagerelay-lolly.bin

Download the same file from the Image Relay UI as the original and checksum that too. A match means download_url served the true original: strike row 18. A smaller file, different pixel dimensions or stripped EXIF/ICC means the link is a rendition or a quick link, which is row 18 and not a materialize bug: materialize checksums whatever it is given. Repeat per file type you plan to exit, since one type may come from a different link. A driver failure on this route surfaces as 502 PROVIDER_UNAVAILABLE; the diagnosis is in the materialize output.

Last, lw providers drift acme-imagerelay. Every copy that could not be compared is counted under its own reason, so a zero cannot read as a clean bill of health: no readable change stamp means row 12 is wrong, and an unparsable one prints its shape (digits N, letters A) to report.

Then take the pass down. Materialized copies are instance-owned and survive the delete:

lw providers disable acme-imagerelay
lw providers rm acme-imagerelay

Step 4: sign off

In the driver (server/src/catalog/providers/imagerelay.ts): strike the LIVE-VERIFY bullets this pass actually exercised and only those. A folder-scoped listing you never ran and a file type you never fetched stay on the list. Name the date, and say whether the tenant was still on the legacy platform or mid-migration to Canto.

Where a guess was wrong, widen rather than replace: add the real key and keep the old ones. Then pin it with a fixture case in tests/provider-shape.test.ts, and one in tests/provider-live-verify.test.ts if the failure path changed.

In the guides: the fixture-verified paragraph in providers/README.md and the readiness row in offboarding.md are where the "live confirmation open" claim lives. Both should now say what was confirmed, on what date, and what remains open. No field name here carries over to the canto driver, a different API; the tenant knowledge does, and mapping.availabilityFields moves across with only the field name changed.

Send back: imagerelay-shape.txt, the verbatim text of any driver error you hit, which constants you edited and to what, and the step 3 fidelity result per file type.

See also: the Image Relay guide · off-boarding · the CLI · the other three runbooks: canto · intelligencebank · acquia-dam.