Content Versioning

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/content-versioning/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Content Versioning automatically tracks all changes to products, blog posts, and content, storing a history of edits with timestamps and staff member attribution. Merchants can view version history, see what changed between versions, and restore to any prior version. This is core GPL functionality: infrastructure, honest diff-based storage, no per-country obligation.

The problem

Merchants accidentally overwrite content and can’t recover older versions. A team member’s mistake deletes product descriptions, or an editor reverts a good change. Without version history, losing work is permanent and frustrating.

What it does

• Automatic version capture: every save (PATCH) creates a new version with timestamp and staff member
• Version list: show all versions of a product, ordered by most recent
• Diff view: show what changed between version N-1 and N (title: ‘Old Title’ → ‘New Title’, price: 1999 → 2499)
• Restore: revert to any prior version, creates new version (no destructive restore; old version remains)
• Audit log: version creation event with staff member and change summary
• Storage efficiency: store diffs (what changed), not full copies (save 80% space vs full snapshots)
• Version limit: retain last 50 versions per record (older versions auto-delete)
• Bulk compare: compare version A to version B (skipping intermediate versions)
• Export: download single version as JSON, or version history as CSV (timestamp, author, change summary)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Scheduled version snapshots (‘checkpoint every day at noon’) — scope is automatic per-edit; scheduled snapshots are separate
• Version branching (fork product to two versions, merge later) — scope is linear history only; branching requires separate feature
• Access control per version (restrict viewing old versions) — scope is audit log only; access control is policy layer

Data model

Extend core content schema: add versions array or separate VersionHistory collection storing {id, parent_id, versionNumber, timestamp, author_id, changeDiff, fullSnapshot}. Use diff storage for efficiency (store only what changed). No breaking migration if using extension.

API

• GET /api/products/:id/versions — list version history
• GET /api/products/:id/versions/:versionId — fetch single version (full record state)
• GET /api/products/:id/versions/:v1/diff/:v2 — show changes between two versions
• POST /api/products/:id/restore/:versionId — restore to prior version (creates new version)

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Product edit form shows ‘Versions’ link. Version history pane lists all versions with timestamp, author, and change summary (‘Updated title and price’). Click version to view full state at that time. Diff view highlights changes (red for removed, green for added). Restore button: ‘Revert to this version’ creates new version with old content and marks as restored.

The seam — why this is core

Core owns: version storage (diff-based), version history UI, restore logic, audit log. No paid pack owns this; it’s infrastructure.

Core owns the interface + honest change tracking; versioning is infrastructure, not a support commitment or credential.

Dependencies

• core-audit-log (version events logged)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Edit product name from ‘Shoes’ to ‘Running Shoes’; new version created with timestamp and author
• Version history shows 5 versions, most recent first
• Diff view shows ‘name: “Shoes” → “Running Shoes”’ in green, other fields unchanged
• Restore to version 2 (old name ‘Shoes’): status changes to ‘Published’, new version created with full history
• Version limit: after 50 edits, oldest version (version 1) auto-deleted; only versions 2–51 retained
• Export version history as CSV shows: timestamp, author, change summary for all versions

Risks

Diff storage vulnerability: if diff format corrupted, cannot reconstruct full state (must keep periodic snapshots). Restore creates new version without user confirmation; accidentally restoring wrong version hard to undo. Version limit too small (10) breaks editing audits; too large (1,000) wastes storage. Audit log missing version events makes versioning untrustworthy.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.