14 — PRODUCT SPECIFICATION

Depends on: 13_PACKAGE_SELECTION_POLICY.md · Counts: 50 FREE + 100 PAID = 150 Features Phase 1 delivers: 5 features FULLY (marked ✅) + 5 blogs fully + all listed

Every feature = UI + API + DB + Validation + AuthZ + Tests + Docs. No feature without all six.

1. Plans & Limits — Single Source packages/config/plans.ts

Limits enforced at API + shown in UI with upgrade prompts. No duplicated numbers.

2. FREE — 50 Features (All users)

Group FREE-A: Core Link Management (18)

Group FREE-B: Analytics Basic (10)

Group FREE-C: Organization (6)

Group FREE-D: Account & System (8)

Group FREE-E: Tools (Basic) (3)

Group FREE-F: Content & Support (5)

Phase 1 ships F01, F14, F19-F22, F35, F38 fully. All 50 have UI shell + OpenAPI stub + docs entry; 5 are executable.

3. PAID — 100 Features (Unlock by plan)

PAID-1: Teams & RBAC (12) — Starter+

PAID-2: Custom Domains & Branding (10) — Starter+

PAID-3: Advanced QR (8) — Starter+

PAID-4: Analytics Pro (15) — Pro+

PAID-5: Bulk & Developer Platform (12) — Pro+

PAID-6: Bio Pages (Link-in-Bio) (10) — Pro+

PAID-7: Tools Suite (20) — Pro / Business

Each is modules/tools/<name> with tool.json + UI + POST /v1/tools/<name>/*:

PAID-8: Admin & Security (8) — Business/Enterprise

PAID-9: Billing & Enterprise (5) — Pro+

4. Phase 1 — 5 Features Fully Specified

F01 — Shorten URL

• UI: Dashboard New Link → input (2048) → custom alias (optional, 3-30, regex) → create → toast + row in table
• API: POST /v1/links (Zod: originalUrl url, customAlias?, title?, expiresAt?, password?) → 201 { shortCode, url: https://yas.sh/<code>, ... } — 400 validation, 409 alias taken, 429 rate limited
• DB: Link(userId, originalUrl, shortCode UNIQUE, customAlias UNIQUE?, createdAt) + increment user.linkCount check against plan limit
• Tests: unit duplicate, integration auth/unauth, e2e: shorten → appears in list

Redirect Engine (GET /:code)

• Flow: Lookup shortCode or customAlias → 404 if missing → 410 if expired/deleted/killed → 401 if password & missing → increment clicks + ClickEvent (bot-filter: exclude known bot UA + ?bot=1 param) → 302 to originalUrl (configurable 301/302)
• Perf: First-hit DB, then Valkey/memory cache 60s; p95 <50ms cached
• Tests: e2e loop shorten→redirect→analytics count 1 → repeat with bot UA count stays 1

F14 — QR Static

• UI: Per-link QR button → modal with size 256/512/1024, format PNG/SVG, download, copy image
• API: GET /v1/qr?url=https://yas.sh/abc&size=512&format=png → image/png (qrcode lib, EC M, margin 2) — rate-limited, validates url http(s), size ∈ {128,256,512,1024}
• Tests: content-type + magic bytes, invalid url 400

Analytics Overview (F19-22)

• UI: /dashboard/analytics → cards (total links, total clicks, avg CTR), 30-day line (ECharts), breakdowns (country/device/referrer top 10), per-link drill GET /v1/analytics/:linkId
• API: GET /v1/analytics/overview?days=30&linkId? → { totalLinks, totalClicks, series: [{date, clicks}], breakdowns } — auth required, RBAC: owner or team member
• DB: Aggregates from ClickEvent (phase 1 direct query with indexes; daily rollup added Phase 4)
• Tests: shorten→redirect→overview totalClicks:1, bot excluded

Auth + API Keys (F35, F38)

• UI: /login, /register, /dashboard/keys → create (name + scopes multi-select) → show yas_live_... once with copy + warning → revoke with confirm
• API: POST /v1/auth/register (email, password Argon2id ≥12 chars), POST /v1/auth/login (sets __Host-session, rotation), POST /v1/auth/logout, GET /v1/auth/me, POST /v1/api-keys (stores SHA-256 hash only), DELETE /v1/api-keys/:id, Bearer usage Authorization: Bearer yas_live_...
• Security: Anti-enumeration identical timings, per-IP throttling 10/min, session expiry 30d idle / 90d absolute
• Tests: register→login→me 200, unauth matrix 401, API key create→use Bearer 200→revoke→401, IDOR: user A cannot delete B's link

5. Blogs — 5 Fully Production (Phase 1)

Each: index.mdx 1,200-2,200 words + hero.webp + cover.webp + thumb.webp + frontmatter (see 07_BLOG_SYSTEM.md) + FAQ + TOC + 4 internal links + JSON-LD

Remaining stubs (45 more) to reach 50: utm-campaign-guide, branded-links-trust, password-links-use-cases, link-expiration-strategy, bio-pages-conversion, ... (full list in blog/content/_stubs.json).

6. Acceptance Per Feature

Before a feature is marked ✅: UI works → API validates → DB persists → authZ enforced → unit + integration + e2e green → docs example executes → PROJECT_MEMORY.md updated.

All 150 features have module.json + docs.md placeholder at repo init so scripts/gen:modules lists the full roadmap. Only 5 are executable in Phase 1; others return 501 not_implemented with RFC9457 + upgrade CTA.