# Previewer
> Previewer (https://previewer.agency) hosts live previews of HTML5 banners, images and videos for an agency's clients. Each campaign gets one private link where the client sees every size running and approves it. This file tells an AI agent how to set up a project to upload to Previewer and how to work with it.
Everything goes through the `previewer-agency` npm package (Node 20.11 or newer, no other dependencies): a command line tool, and an MCP server (`npx -y previewer-agency mcp`).
## Set up a project
Do these in order. Ask the user whenever a step needs a choice you can't make from the project.
1. **Check Node.** `node --version` must be 20.11 or newer.
2. **Connect the MCP server** if your environment supports MCP (preferred: you then get typed tools instead of parsing command output).
- Claude Code: `claude mcp add previewer -- npx -y previewer-agency mcp`, or `claude mcp add --scope project previewer -- npx -y previewer-agency mcp` to share it with the team through `.mcp.json`.
- Other clients: add `{ "mcpServers": { "previewer": { "command": "npx", "args": ["-y", "previewer-agency", "mcp"] } } }` to their MCP settings.
- The tools appear after the client reloads its MCP servers; tell the user if a restart is needed.
3. **Sign in.** Call the `whoami` tool (or run `npx -y previewer-agency whoami`). If not signed in:
- MCP: call `sign_in`. It returns a code and a page and opens the browser. It always signs in to previewer.agency (or the `PREVIEWER_URL` the user set); you can't pick another site.
- Command line: run `npx -y previewer-agency login` in the background; it prints a code and a link and waits up to 10 minutes.
- Either way, **a person must approve**: give the user the code, ask them to type it on that page and approve. You cannot approve it yourself. Then check with `whoami`.
4. **Find the build output.** Look for the folder the banner build writes to (often `dist/`, `build/` or `export/`). Previewer takes, from that folder: HTML5 banner ZIPs, banner folders with an `index.html` (zipped automatically), images and videos, and backup images (`300x250.jpg` next to `300x250.zip`, or anything in `backups/`). The size comes from `` or a `300x250` token in the name. Run a dry run to see what would go up: `upload_folder` with `dry_run: true`, or `npx -y previewer-agency push --dry-run`.
5. **Choose the campaign.** List them with `list_campaigns` (or `npx -y previewer-agency campaigns --json`) and ask the user which client and campaign this project belongs to, or whether to create a new one (`create_client` makes a client that isn't there yet; it needs Manage access). Link the project with `link_folder` (or `npx -y previewer-agency link --client "" --campaign ""`). This writes `.previewer.json` in the project root: ids, names and the site, never a token; safe to commit.
6. **Add a script** to `package.json`, matching the build folder: `"preview": "previewer push dist"` (with `previewer-agency` as a devDependency; it installs the `previewer` command), or `"preview": "npx -y previewer-agency push dist"`.
7. **Upload, check and share.** Run the first upload (`upload_folder` or `npm run preview`). It returns the `previewUrl` and `checks`: what the upload check found in each HTML5 banner. Fix what is marked `fail` in the source (see "The upload check" below), build and upload again. Then generate the backup images (`generate_backups`, or `npx -y previewer-agency backups`) and give the user the `previewUrl`. That link is what they send their client.
8. **CI (only if the user wants it).** In the Previewer admin, under API, an owner creates a token with Upload access (narrowed to the client or campaign if they like). Store it as the CI secret `PREVIEWER_TOKEN`; never commit it. GitHub Actions step, after the build:
```yaml
- run: npx -y previewer-agency push dist --backups
env:
PREVIEWER_TOKEN: ${{ secrets.PREVIEWER_TOKEN }}
```
## Working with it
- Uploading a file with the same name as a banner already in the campaign replaces it as a new version; the client's link stays the same and shows the new version.
- `get_campaign` (or `npx -y previewer-agency status --json`) shows per banner whether it's approved (and the name the client gave), has a backup image, is hidden from the preview, what the upload check found, and when the client last opened the preview.
- Approvals are given by the client in the preview. You can read them, not set them. `wait_for_approval` waits up to about 45 seconds per call and reports where approvals stand; clients usually take hours, so don't loop on it: tell the user and check again when asked. In a script, `npx -y previewer-agency wait --timeout 240` exits 0 once everything is approved, 2 when the time is up and 3 when the campaign has nothing to approve.
- `download_campaign` with `approved_only: true` (or `npx -y previewer-agency download ./handoff --approved`) saves one ZIP with the approved creatives and their backup images, for the hand-off to the media agency.
- `set_note` sets the note at the top of the preview (what changed this round). `update_banner` hides a banner from the preview or shows it again, and puts it in a group.
- Only remove or hide a banner, and only set or remove a preview password (`set_preview_password`), when the user asked for exactly that. Never make up a password: use the one the user gave, and tell them they pass it on to their client themselves.
- A campaign's name, look, approval setting and preview link, and deleting campaigns or clients, are done by people in the admin, not through the API.
- Tokens: never print, log or commit them. The sign-in is stored in `~/.config/previewer/config.json`.
## The upload check
Every HTML5 banner is checked when it is uploaded. `upload_folder` returns the banners with something to fix; `get_campaign` has it per banner under `checks.problems`. Each problem has a `status`: `fail` needs fixing, `warn` needs a look.
- **Click-through** (`fail`): the banner has a hard-coded link (`window.open('https://…')`) or no click handling. Use the ad platform's own exit: a `clickTag` variable for Google Ads and most others, `Enabler.exit()` for Campaign Manager 360 / Google Web Designer, `EB.clickThrough()` for Sizmek, `clickTAG` (from `dhtml.getVar('clickTAG', …)`) for Adform, `ftClick`/`ftExit` for Flashtalking. `checks.platform` says which platform Previewer recognised. Ask the user which platform the campaign runs on if it isn't clear.
- **ad.size meta**: add `` to the ``, matching the banner's size.
- **Initial weight / ZIP weight** (`warn`): over the campaign's weight budget (150 KB unless the agency set another). Compress images, drop unused files, load a library from the platform's hosted copy instead of bundling it.
- **Secure assets**: change `http://` links to images, fonts and scripts to `https://`.
- **File count** (`warn`): more than 30 files in the ZIP.
- **Backup weight**: the backup image is over 50 KB; generate it again or upload a smaller one.
The checks read the code; they don't run the banner on the ad platform. A click-through built in an unusual way can be marked `fail` while it works. Say so to the user rather than rewriting working code, and never change a banner's design to pass a check without asking.
## Docs
- [Command line tool and API](https://previewer.agency/docs/api): the CLI, MCP setup, and every API endpoint.
- [Full text for agents](https://previewer.agency/llms-full.txt): this file plus the complete CLI and API docs in one file.