zuora-html-template-designer

Files (13)

• SKILL.md
• expressions.md · references/
• functions.md · references/
• javascript.md · references/
• logic-control.md · references/
• merge-field-syntax.md · references/
• objects-index.json · references/
• objects.yaml · references/
• requirements.txt
• convert_office.py · scripts/
• convert_pdf.py · scripts/
• extract_colors.py · scripts/
• security.py · scripts/

SKILL.md (first lines)

Codex-only path resolution: When an instruction refers to `${CLAUDE_PLUGIN_ROOT}`, treat it as the root of this installed plugin. In Codex, resolve that root as the ancestor directory containing `skills/`, `references/`, and `.codex-plugin/`.

## Input

The user's request: $ARGUMENTS

# HTML Template Designer

This skill designs Zuora HTML Templates for Invoice/CreditMemo/DebitMemo documents.

## Workflow Detection

Detect the request type and route to appropriate workflow:

| Request Type | Detection | Workflow |
|--------------|-----------|----------|
| **PDF-based** | Attachment line: `* [PDF] /tmp/...` | 9-step PDF workflow (see below) |
| **Image-based** | Attachment line: `* [PNG]`, `* [JPG]`, `* [JPEG]`, or `* [WEBP] /tmp/...` | Image workflow (Steps 1 + 3–9; skip PDF conversion) |
| **Word-based** | Attachment line: `* [DOC]` or `* [DOCX] /tmp/...` | Office workflow (Steps 1 + Office→PDF + Step 2 + 3–9) |
| **Text-only** | No file attachment | Direct generation |

## Image Workflow (PNG / JPG / WEBP)

When an image attachment is detected, follow the PDF workflow but **skip Step 2** (`convert_pdf.py`).

1. **Step 1** — Setup folders (same as PDF workflow).
2. **Use the uploaded image path directly** as `png_path` for visual analysis (e.g. `/tmp/.../uploads/abc123.png`).
3. **Steps 3–9** — Same as the PDF workflow: analyze the image with Read, generate HTML, self-check, merge fields, validate.

## Word Workflow (DOC / DOCX)

When a Word attachment is detected:

1. **Step 1** — Setup folders (same as PDF workflow).
2. **Convert Office document to PDF** before PNG conversion:

**Install dependencies first (once per session):**
```bash
pip install -r ${CLAUDE_PLUGIN_ROOT}/skills/zuora-html-template-designer/requirements.txt
```

```bash
python ${CLAUDE_PLUGIN_ROOT}/skills/zuora-html-template-designer/scripts/convert_office.py \
  --input <doc_file_path> \
  --output {session-folder}/uploads/
```

Response:
```json
{
  "success": true,
  "pdf_path": "/tmp/.../uploads/abc123.pdf",
  "source": "docx"
}
```

3. **Step 2** — Run `convert_pdf.py` on `pdf_path` (same as PDF workflow).
4. **Steps 3–9** — Same as the PDF workflow.

---

## CRITICAL: Root Object Rules

**Every merge field MUST trace back to the root object.** This is the #1 cause of validation errors.

| Template Type | Root Object | Example |
|--------------|-------------|---------|
| Invoice | `Invoice` | `{{Invoice.Account.Name}}` |
| CreditMemo | `CreditMemo` | `{{CreditMemo.Account.Name}}` |
| DebitMemo | `DebitMemo` | `{{DebitMemo.Account.Name}}` |

**Two valid approaches:**
1. **Full path**: `{{Invoice.Account.Name}}`
2. **Contextual section**: `{{#Invoice}}{{Account.Name}}{{/Invoice}}`

**WRONG** (will fail validation):
- `{{Account.Name}}` - Missing root object
- `{{InvoiceItems.ChargeName}}` - Missing root object

**CORRECT** equivalents:
- `{{Invoice.Account.Name}}` - Full path from root
- `{{#Invoice.InvoiceItems}}{{ChargeName}}{{/Invoice.InvoiceItems}}` - Inside section

---

## Progress Tracking

**IMPORTANT:** At the start of each workflow, use `TodoWrite` to create a todo list for all steps. Update each todo as you progress (mark in_progress when starting, completed when done). This gives the user visibility into your progress.

---

## Common Pitfalls & Lessons Learned

**Why templates fail user expectations (in order of frequency):**

### 1. Title Case Handling for ALL-CAPS Labels

**Problem:** Users ask for "camel case" on values like `CITY SALES TAX`, but there's no native merge-field function for this. Wrong approaches emerge (CSS-only tricks, unsafe JavaScript hacks).

**Root Cause:** Misunderstanding of "camel case" request (users mean **title case**: `City Sales Tax`). Native Zuora merge-field syntax has no title-case function.

**Solution:** Use a template `<script>` block with a `title-case` CSS class and JavaScript transformation. Requires **Enable JavaScript for HTML templates** in Billing settings. If JS is disabled, fix the value upstream instead.

**Correct approach:**
```html
<style>
  .title-case {
    /* CSS alone cannot capitalize all words; JavaScript is required */
    font-variant: small-caps; /* Optional visual hint while awaiting JS */
  }
</style>

<script>
  function titleCase(str) {
    return str.replace(/\b\w/g, c => c.toUpperCase());
  }
  document.querySelectorAll('.title-case').forEach(el => {
    el.textContent = titleCase(el.textContent);
  });

From zuora/zuora-coding-agent, MIT.

More from zuora/zuora-coding-agent