---
name: timer-frame-draft
description: Create, edit, preview, and save NiftyImages Timer Frame drafts through a conversation. Use when a user wants an agent to build or tweak a countdown timer before making it live, including requests like create a timer, change colors, resize, hide labels, add pie charts or rings, preview the timer, start over, or save the final timer.
---

# Timer Frame Draft

Use this skill to guide a user through a conversational timer draft workflow.

## API Context

- Base URL: `https://dev.niftyimages.com/v2`
- OpenAPI: `https://dev.niftyimages.com/openapi/v1.json`
- Guide: `https://dev.niftyimages.com/docs/timer-frames.md`
- Auth: `Authorization: Bearer {apiKey}`

## Credential Rules

- If the user wants live API calls and no NiftyImages API key is available, ask for one before calling `/v2`.
- If the user only wants planning or code generation, continue without an API key.
- Never invent, guess, log, or expose the API key.

## Core Contract

Timer Frames are temporary drafts. The user should be able to create, preview, and tweak the draft repeatedly before saving.

Treat `POST /v2/timer-frames/{timerFrameId}/save` as the final commit step. Do not call `/save` until the user explicitly approves the final preview. After `/save` succeeds, stop editing the draft and return the live saved image/deployment details.

`saveReady` means the draft is valid enough to save. It does not mean the user approved the design.

## Workflow

1. Gather missing requirements: target date/time, timezone, size, colors, labels, backplate style, and optional font.
2. Optionally list fonts with `GET /v2/fonts` if the user asks for a specific font or font choice matters.
3. Create a draft with `POST /v2/timer-frames`.
4. Preserve `conversationId`, `timerFrameId`, `expiresUtc`, `preview.url`, and `saveReady`.
5. Show or return `preview.url` after create, get, and update responses.
6. Translate user edits into `PATCH /v2/timer-frames/{timerFrameId}` fields.
7. Keep iterating until the user says the preview is final.
8. Before saving, summarize the timer name, target date/time, timezone, visual choices, and preview URL.
9. Ask for explicit confirmation.
10. Save with `POST /v2/timer-frames/{timerFrameId}/save`.

## Common Edit Mapping

- "make the background black": `backgroundColor`
- "white numbers": `numberColor`
- "hide labels": `showLabels: false`
- "show labels": `showLabels: true`
- "make it 600 by 300": `width: 600`, `height: 300`
- "make the numbers bigger": `numberFontSizeDelta`
- "add pie charts": `numberBackplate: "pie"`
- "remove backplates": `numberBackplate: "none"`
- "add rings": `numberBackplate: "ring"`
- "add ticks" or "segmented circles": `numberBackplate: "ticks"` or `"segmented"`

## Final Confirmation Prompt

Before `/save`, ask something like:

```text
The current preview is ready to save as "{name}" for {targetDateUtc} in {timeZoneId}. Once I save it, this draft is locked in and the timer will be live for campaigns or websites. Save it now?
```

## Do Not

- Do not call `/save` after the first create unless the user explicitly asks to create and save immediately.
- Do not continue PATCH calls after a successful `/save`.
- Do not construct preview URLs manually. Use `preview.url`.
- Do not discard `conversationId` between turns.
- Do not treat an expired draft as editable. Start over instead.