sims-hq/docs/superpowers/specs/2026-07-13-quotation-polish-share.md

# Quotation Polish + Share/Download — Design

**Status:** approved in principle (founder, 2026-07-13). Sequenced to run **after** the
live-preview build (wf live-preview) lands, so it builds on the finished `templates.ts`
rendering + the live preview (every visual change is seen instantly) and never edits the
template file concurrently with that build.

Two threads: (A) make the document **look beautiful**, (B) **share & download** options.

## A. Beautiful document (templates.ts `documentHtml`)

Restyle the one shared letterhead template — this automatically improves the PDF, the
composer live preview, and the Document Template page (one renderer). A print-quality,
professional Indian GST document, not a generic table. Direction (finalised with the
frontend-design skill at build time):

- **Typography:** a clear type hierarchy — company name prominent, a refined document
  title block (TAX INVOICE / QUOTATION), tabular-figure alignment for all money columns
  so rupee amounts line up to the paisa. Keep the bundled Segoe/Inter-class stack (renders
  identically on the office desktops and the Windows server — no web-font fetch in print).
- **Layout:** a proper letterhead band (logo left via `template.logo`, company block +
  GSTIN right), a clean bill-to / ship-to and document-meta row, a well-spaced line table
  with subtle row rules (not heavy borders), a totals block visually anchored bottom-right
  with the grand total emphasised, amount-in-words, then terms / declaration / jurisdiction
  / signatory / footer from the `template.*` fields.
- **Accent:** one restrained accent colour for rules/headers, sourced from a new optional
  `template.accent` setting (defaults to a professional slate/indigo) so it's brandable
  from the Document Template page later — no hard-coded brand colour.
- **Print discipline:** A4, 14mm margins, avoid row-splitting across page breaks
  (`break-inside: avoid` on rows), repeat the table header on page 2+. All screen/print
  parity rules from the live-preview design still hold (one renderer, golden test guards).
- **Fidelity:** the existing string-identity golden test continues to guarantee the
  beautified preview === the beautified PDF.

## B. Share & download (all three channels + download)

On **DocumentView** (and optionally right after composing), an action group:

1. **Download PDF** — button hitting the existing `GET /api/documents/:id/pdf`, served
   with `Content-Disposition: attachment; filename="QT-26-27-0001.pdf"` (doc-no slugged,
   `/` → `-`). Trivial; no new endpoint.
2. **Shareable view link** (the load-bearing one — needs a secure public route):
   - New table `document_share (id, document_id, token, created_by, created_at,
     expires_at NULL, revoked INTEGER DEFAULT 0)` via `CREATE TABLE IF NOT EXISTS`.
   - `POST /api/documents/:id/share` (requireAuth) → mints a **cryptographically random**
     token (≥32 bytes, `randomBytes`), default `expires_at` = +30 days (configurable),
     returns the public URL. Audited.
   - **Public** `GET /share/:token` (NO auth, the ONLY unauthenticated read route) →
     validates token exists, not revoked, not expired; renders **only that one
     document's** PDF (reuse renderPdf) or an HTML view. Serves nothing else — no listing,
     no client record, no API. Unknown/expired/revoked → a plain "link expired" page.
   - `POST /api/documents/:id/share/:shareId/revoke` (requireAuth, audited) → sets
     `revoked=1`. A document's shares are listed on DocumentView so the owner can revoke.
   - **Security stance (documented, accepted):** anyone holding the link sees that one
     document's contents (client name + amounts) — the intended trade-off of any share
     link, mitigated by an unguessable token, optional expiry, and one-click revoke.
     Rate-limit `/share/:token` lookups to blunt token brute-forcing. No document data in
     the URL beyond the opaque token.
3. **WhatsApp (click-to-chat)** — a `wa.me/<client-phone>?text=<encoded>` link opening
   WhatsApp with a ready message: greeting + doc type/no + total + **the shareable view
   link** (so the client taps through to the actual document — this is why the link and
   WhatsApp compose). Needs the client's phone (already on the client record); no WhatsApp
   Business API. If no share link exists yet, minting one is offered inline.
4. **Native share sheet** — `navigator.share({ title, text, url: shareLink })` where
   supported (mobile), sharing the view link to any app; where the File share is
   supported, share the PDF blob directly; desktop/unsupported → falls back to Download.

## Data / files (build time)

- `apps/hq/src/db.ts` — `document_share` table (CREATE TABLE IF NOT EXISTS; no migrate).
- `apps/hq/src/repos-shares.ts` — mint/validate/revoke/list shares.
- `apps/hq/src/api.ts` — `POST /documents/:id/share`, `POST …/share/:shareId/revoke`;
  `GET /api/documents/:id/pdf` gains the attachment filename.
- `apps/hq/src/server.ts` — public `GET /share/:token` mounted OUTSIDE the `/api`
  auth router, rate-limited; renders via renderPdf.
- `apps/hq/src/templates.ts` — the beautification (thread A) + optional
  `template.accent`.
- `apps/hq-web/src/pages/DocumentView.tsx` — the action group (Download / Link / WhatsApp
  / Share) + the shares list with revoke.
- Tests (TDD, server): token mint is random + unguessable; `/share/:token` serves only
  the one doc and 404s on unknown/expired/revoked; revoke works; owner-gate/audit;
  download filename; beautify keeps the golden string-identity test green.

## Not this round

Real WhatsApp Business API sending (click-to-chat only); SMS; share analytics
(opened/viewed tracking) — a nice later addition on the same `document_share` row.

## Sequence

1. Live-preview build (in flight) completes and is verified.
2. Plan this doc (writing-plans) → ultracode build → verify. Beauty pass uses the
   frontend-design skill for the concrete visual system.