# Claim handler examples

Complete handlers to start from. Each one runs in Adorably's test suite against the real sandbox, with a fake of the seller API it calls, including the failure paths. They use `example.com` (and `api.example.com`, `app.example.com`) for your domain: change the hosts, paths and field names to yours. The hosts must be your approved hosts: the landing page hosts of your offers Adorably approved, and their subdomains.

Each is typed against `handler-runtime.d.ts` through its JSDoc line, so an editor that knows the file checks it.

| File | What it shows | Secrets |
| --- | --- | --- |
| `signup-link.js` | A signup link with the email filled in, through `adorably.url`. No API call. | none |
| `trial-magic-link.js` | Create a trial through your API, return its magic link; the claim id as the idempotency key. | `API_KEY` |
| `signed-jwt-link.js` | A signed link that expires in 15 minutes, through `adorably.jwt`. | `LINK_SECRET` |
| `hmac-query.js` | An HMAC-signed query (`adorably.hmac`) your backend verifies (Node and Python code in the guide). | `LINK_SECRET` |
| `promo-code.js` | A per-developer promo code from your API, with `adorably.fallback` on every kind of failure. | `API_KEY` |
| `cta-label.js` | Choosing the button label (`cta_label`) from what your API knows about the developer. | `API_KEY` |
| `defensive.js` | Retries within the time and fetch limits, response checks and a clean fallback. | `API_KEY` |
| `explain-competitor.js` | A sponsored explanation (`explain`) naming the developer's current tool through `adorably.model.complete`, with a cheap second question before it shows. | none |
| `explain-agent-loop.js` | A sponsored explanation from a small agent harness: a streamed tool-call loop over `fetch` against the model API, with one tool over the brief. | none |

Test each one with `test_claim_handler` before you save it with `set_claim_handler`. The guide (`adorably://claim-handler`, or https://adorably.io/docs/claim-handlers) has the contract, the limits and every error.