strapi-plugin-timeline 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patiparnne Vongchompue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# Strapi Plugin Timeline
+
+A content history and version control plugin for **Strapi 5**. Automatically tracks changes to your content entries and lets you browse, compare, and restore previous versions — all from within the Strapi admin panel.
+
+## Features
+
+- **Automatic Change Tracking** — Records snapshots on create, update, delete, and publish actions via lifecycle hooks. No manual work required.
+- **Per-Content-Type Configuration** — Choose which content types to track, which actions to log, and set retention limits independently for each.
+- **Full Snapshot Storage** — Each timeline entry stores the complete content payload and the content type schema at that point in time.
+- **Restore with Diff Preview** — Before restoring, see a side-by-side comparison of what will change. One-click restore reverts the entry and logs a "restore" action.
+- **Homepage Dashboard** — Filterable, sortable, paginated table of all timeline entries across content types, users, locales, actions, and date ranges.
+- **CM Edit View Panel** — A sidebar panel in the content manager showing the history of the document you're editing, grouped by date.
+- **Locale Aware** — Tracks i18n locale per entry. Filter by locale. Restores respect locale context.
+- **Scheduled Cleanup** — Configure a cron job to automatically remove entries older than a retention duration (hours, days, weeks, or months).
+- **Entries Limit** — Set a maximum number of entries per content type. Oldest entries are automatically pruned (FIFO).
+- **Role-Based Permissions** — Separate permissions for read, edit, delete, and schedule actions via Strapi's RBAC system.
+- **User Attribution** — Captures the admin user who performed each action, with links to user profiles.
+- **Schema Migration** — Automatically migrates from legacy configuration format.
+
+## Requirements
+
+- Strapi **v5.x**
+- Node.js **18+**
+
+## Installation
+
+```bash
+npm install strapi-plugin-timeline
+```
+
+Or with yarn:
+
+```bash
+yarn add strapi-plugin-timeline
+```
+
+### Enable the Plugin
+
+Add it to your Strapi plugin configuration:
+
+```typescript
+// config/plugins.ts
+export default () => ({
+  timeline: {
+    enabled: true,
+  },
+});
+```
+
+Then rebuild and restart your Strapi application.
+
+## Configuration
+
+All configuration is done through the **Strapi Admin Panel** — no code changes needed.
+
+### Settings Page
+
+Navigate to **Settings → Timeline** in the admin panel to:
+
+1. **Add content types** to track from a dropdown of all available API content types.
+2. **Configure each content type** independently:
+   - **Enable/Disable** — Toggle tracking on or off.
+   - **Tracked Actions** — Select which actions to log: `create`, `update`, `delete`, `publish`. Leave empty to track all.
+   - **Entries Limit** — Maximum entries to keep (0 = unlimited). When exceeded, oldest entries are removed automatically.
+   - **Retention Duration** — How long to keep entries before scheduled cleanup removes them. Set the value and unit (hours, days, weeks, months).
+3. **Remove content types** — Stop tracking and optionally clean up existing entries.
+
+### Scheduled Cleanup
+
+Navigate to **Settings → Timeline → Schedule** to:
+
+- **Enable/Disable** automatic cleanup.
+- **Set the cron expression** (default: `0 * * * *` — every hour).
+- **Run cleanup manually** with the "Run Now" button.
+- **View last cleanup results** including per-content-type deletion counts.
+
+> **Note:** Changes to the cron schedule require a server restart to take effect.
+
+## Usage
+
+### Homepage
+
+The Timeline homepage (`/plugins/timeline`) shows a paginated table of all tracked changes. You can:
+
+- **Filter** by content type, user, action, locale, date range, or document ID.
+- **Sort** by action, content type, user, or date.
+- **View** — Click the eye icon to open a detail modal showing the full snapshot with formatted content (rich text, blocks, relations, media).
+- **Restore** — Click the restore icon to open a diff preview, then confirm to revert the entry to that snapshot.
+- **Clean** — Bulk delete timeline entries by content type.
+
+### Content Manager Panel
+
+When editing any tracked content entry, a **Timeline** panel appears in the sidebar showing:
+
+- Recent changes to this specific document, grouped by date.
+- A date picker to browse changes on a specific day.
+- Quick view and restore buttons for each entry.
+
+### Restore
+
+When you restore a snapshot:
+
+1. A **diff table** shows which fields will change, comparing current values against the snapshot.
+2. The plugin performs the restore server-side in a single operation.
+3. A "restore" action is logged in the timeline.
+4. The entries limit is enforced after the restore.
+5. The lifecycle `afterUpdate` hook is suppressed during restore to avoid a duplicate "update" entry.
+
+## Tracked Actions
+
+| Action | Description |
+|--------|-------------|
+| `create` | A new entry was created |
+| `update` | An existing draft/entry was modified |
+| `publish` | Content was published |
+| `delete` | An entry was deleted |
+| `restore` | An entry was reverted to a previous snapshot |
+| `clean` | Timeline entries were manually bulk-deleted |
+
+## Permissions
+
+The plugin registers its own permissions under **Settings → Roles**:
+
+| Permission | Description |
+|------------|-------------|
+| `plugin::timeline.read` | View timeline entries and history |
+| `plugin::timeline.edit` | Restore entries and modify settings |
+| `plugin::timeline.delete` | Delete / clean timeline entries |
+| `plugin::timeline.schedule.run` | Execute scheduled cleanup |
+
+## API Endpoints
+
+All endpoints are admin-only and require authentication.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/timeline/settings` | Get plugin settings |
+| `PUT` | `/timeline/settings` | Update plugin settings |
+| `GET` | `/timeline/content-types` | List available content types |
+| `GET` | `/timeline/entries` | Query timeline entries (with filters, pagination, sorting) |
+| `GET` | `/timeline/entries/users` | Get distinct users |
+| `GET` | `/timeline/entries/locales` | Get distinct locales |
+| `GET` | `/timeline/entries/:contentType/:entryDocumentId` | Get history for a specific document |
+| `POST` | `/timeline/entries/snapshot-before-restore` | Restore an entry to a previous snapshot |
+| `POST` | `/timeline/entries/clean` | Delete entries for selected content types |
+| `DELETE` | `/timeline/entries` | Delete all timeline entries |
+| `GET` | `/timeline/schedule` | Get cleanup schedule status |
+| `PUT` | `/timeline/schedule` | Update cleanup schedule |
+| `POST` | `/timeline/schedule/run` | Run cleanup now |
+
+## How It Works
+
+The plugin subscribes to Strapi's database lifecycle events (`afterCreate`, `afterUpdate`, `beforeDelete`) at the global level. On each event:
+
+1. Checks if the content type is tracked and the action is enabled in settings.
+2. Extracts the admin user from the request context.
+3. Resolves relation fields to document IDs.
+4. Captures the content type schema (attributes, types, relations).
+5. Stores the full snapshot as a JSON timeline entry.
+6. Enforces the entries limit by removing the oldest entries if exceeded.
+
+Snapshots are stored in the plugin's own `timeline-entry` collection type, hidden from the content manager.
+
+## License
+
+[MIT](LICENSE) — Patiparnne Vongchompue
+
+## Support
+
+If you find this plugin useful, consider supporting the development:
+
+- [Buy Me a Coffee](https://buymeacoffee.com/patiparnne)
+- [Patreon](https://www.patreon.com/patiparnne)