@qkix/strapi-plugin-rewind 0.1.0

package/dist/server/src/bootstrap.d.ts

@@ -0,0 +1,5 @@
+import type { Core } from '@strapi/strapi';
+declare const bootstrap: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => Promise<void>;
+export default bootstrap;

package/dist/server/src/config/index.d.ts

@@ -0,0 +1,58 @@
+declare const _default: {
+    default: {
+        /**
+         * Content types to version, by uid. Empty means nothing is tracked.
+         *
+         * The default is deliberate. A plugin that silently starts writing a row on
+         * every save the moment it is installed is a plugin that gets uninstalled
+         * after the first disk alert.
+         *
+         *   'rewind': {
+         *     enabled: true,
+         *     config: { contentTypes: ['api::article.article'] },
+         *   }
+         */
+        contentTypes: string[];
+        /**
+         * Whether to version writes that do not come from the Content Manager.
+         *
+         * Strapi's own history ignores them, so `false` keeps the out-of-the-box
+         * behaviour familiar. With `true`, REST/GraphQL and programmatic writes are
+         * versioned too, with `createdById` left null.
+         *
+         * Either way this only ever sees the Document Service. Writes made through
+         * `strapi.db.query()` or the legacy entity service do not pass through the
+         * middleware and cannot be captured.
+         */
+        trackApiWrites: boolean;
+        /**
+         * How long history is kept.
+         *
+         * On by default, because a version table that only grows is a problem the
+         * plugin would be creating rather than solving. The defaults are gentle:
+         * a full week of every save, then a version a day for a month, then one a
+         * week — and anchors (publish, unpublish, discard, restore) and pinned
+         * versions are never removed at all, whatever their age.
+         *
+         * Set `enabled: false` to keep everything forever and manage it yourself.
+         */
+        retention: {
+            enabled: boolean;
+            keepAllDays: number;
+            dailyUntilDays: number;
+            maxAgeDays: number;
+            keepAnchors: boolean;
+        };
+        /** When the thinning runs. Standard cron, in the server's timezone. */
+        cron: string;
+    };
+    validator(config?: {
+        contentTypes?: unknown;
+        retention?: {
+            keepAllDays?: number;
+            dailyUntilDays?: number;
+            maxAgeDays?: number;
+        };
+    }): void;
+};
+export default _default;

package/dist/server/src/content-types/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The versions table.
+ *
+ * `relatedDocumentId`, not `documentId`: Strapi injects a `documentId` into
+ * every content type and rejects the name outright — "The attribute
+ * "documentId" is reserved and cannot be used in a model" — at boot, before
+ * anything else runs. Strapi's own history model calls it `relatedDocumentId`
+ * for the same reason.
+ *
+ * It is a plain string rather than a relation on purpose: a cascading delete
+ * would erase a document's history at the exact moment it becomes most useful.
+ *
+ * `userId` is not `createdById` for a related reason: Strapi adds its own
+ * `createdBy` relation to every content type, which occupies the `created_by_id`
+ * column, and a second attribute snake-casing to the same name fails the table
+ * creation outright.
+ */
+declare const _default: {
+    version: {
+        schema: {
+            kind: string;
+            collectionName: string;
+            info: {
+                singularName: string;
+                pluralName: string;
+                displayName: string;
+                description: string;
+            };
+            options: {
+                draftAndPublish: boolean;
+                comment: string;
+            };
+            pluginOptions: {
+                "content-manager": {
+                    visible: boolean;
+                };
+                "content-type-builder": {
+                    visible: boolean;
+                };
+                i18n: {
+                    localized: boolean;
+                };
+            };
+            attributes: {
+                contentType: {
+                    type: string;
+                    required: boolean;
+                };
+                relatedDocumentId: {
+                    type: string;
+                    required: boolean;
+                };
+                locale: {
+                    type: string;
+                };
+                status: {
+                    type: string;
+                    enum: string[];
+                    required: boolean;
+                };
+                label: {
+                    type: string;
+                };
+                data: {
+                    type: string;
+                    required: boolean;
+                };
+                schemaSnapshot: {
+                    type: string;
+                    required: boolean;
+                };
+                relations: {
+                    type: string;
+                };
+                contentHash: {
+                    type: string;
+                    required: boolean;
+                };
+                origin: {
+                    type: string;
+                    enum: string[];
+                    required: boolean;
+                };
+                pinned: {
+                    type: string;
+                    default: boolean;
+                };
+                userId: {
+                    type: string;
+                };
+            };
+        };
+    };
+};
+export default _default;

package/dist/server/src/controllers/index.d.ts

@@ -0,0 +1,12 @@
+declare const _default: {
+    version: ({ strapi }: {
+        strapi: import("@strapi/types/dist/core").Strapi;
+    }) => {
+        find(ctx: any): Promise<any>;
+        findOne(ctx: any): Promise<any>;
+        diff(ctx: any): Promise<any>;
+        preview(ctx: any): Promise<any>;
+        restore(ctx: any): Promise<any>;
+    };
+};
+export default _default;

package/dist/server/src/controllers/version.d.ts

@@ -0,0 +1,11 @@
+import type { Core } from '@strapi/strapi';
+declare const version: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => {
+    find(ctx: any): Promise<any>;
+    findOne(ctx: any): Promise<any>;
+    diff(ctx: any): Promise<any>;
+    preview(ctx: any): Promise<any>;
+    restore(ctx: any): Promise<any>;
+};
+export default version;

package/dist/server/src/destroy.d.ts

@@ -0,0 +1,9 @@
+import type { Core } from '@strapi/strapi';
+/**
+ * Without this the dev server stacks up a new thinning job on every reload,
+ * and they all fire together.
+ */
+declare const destroy: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => void;
+export default destroy;

package/dist/server/src/index.d.ts

@@ -0,0 +1,166 @@
+declare const _default: {
+    bootstrap: ({ strapi }: {
+        strapi: import("@strapi/types/dist/core").Strapi;
+    }) => Promise<void>;
+    destroy: ({ strapi }: {
+        strapi: import("@strapi/types/dist/core").Strapi;
+    }) => void;
+    config: {
+        default: {
+            contentTypes: string[];
+            trackApiWrites: boolean;
+            retention: {
+                enabled: boolean;
+                keepAllDays: number;
+                dailyUntilDays: number;
+                maxAgeDays: number;
+                keepAnchors: boolean;
+            };
+            cron: string;
+        };
+        validator(config?: {
+            contentTypes?: unknown;
+            retention?: {
+                keepAllDays?: number;
+                dailyUntilDays?: number;
+                maxAgeDays?: number;
+            };
+        }): void;
+    };
+    contentTypes: {
+        version: {
+            schema: {
+                kind: string;
+                collectionName: string;
+                info: {
+                    singularName: string;
+                    pluralName: string;
+                    displayName: string;
+                    description: string;
+                };
+                options: {
+                    draftAndPublish: boolean;
+                    comment: string;
+                };
+                pluginOptions: {
+                    "content-manager": {
+                        visible: boolean;
+                    };
+                    "content-type-builder": {
+                        visible: boolean;
+                    };
+                    i18n: {
+                        localized: boolean;
+                    };
+                };
+                attributes: {
+                    contentType: {
+                        type: string;
+                        required: boolean;
+                    };
+                    relatedDocumentId: {
+                        type: string;
+                        required: boolean;
+                    };
+                    locale: {
+                        type: string;
+                    };
+                    status: {
+                        type: string;
+                        enum: string[];
+                        required: boolean;
+                    };
+                    label: {
+                        type: string;
+                    };
+                    data: {
+                        type: string;
+                        required: boolean;
+                    };
+                    schemaSnapshot: {
+                        type: string;
+                        required: boolean;
+                    };
+                    relations: {
+                        type: string;
+                    };
+                    contentHash: {
+                        type: string;
+                        required: boolean;
+                    };
+                    origin: {
+                        type: string;
+                        enum: string[];
+                        required: boolean;
+                    };
+                    pinned: {
+                        type: string;
+                        default: boolean;
+                    };
+                    userId: {
+                        type: string;
+                    };
+                };
+            };
+        };
+    };
+    controllers: {
+        version: ({ strapi }: {
+            strapi: import("@strapi/types/dist/core").Strapi;
+        }) => {
+            find(ctx: any): Promise<any>;
+            findOne(ctx: any): Promise<any>;
+            diff(ctx: any): Promise<any>;
+            preview(ctx: any): Promise<any>;
+            restore(ctx: any): Promise<any>;
+        };
+    };
+    routes: {
+        admin: {
+            type: string;
+            routes: {
+                method: string;
+                path: string;
+                handler: string;
+                config: {
+                    policies: string[];
+                };
+            }[];
+        };
+    };
+    services: {
+        snapshot: ({ strapi }: {
+            strapi: import("@strapi/types/dist/core").Strapi;
+        }) => {
+            readRows: (uid: string, relatedDocumentId: string, locales: string[]) => Promise<Record<string, unknown>[]>;
+            captureAll(intents: import("./utils/captureContext").SnapshotIntent[], userId: number): Promise<void>;
+            capture(intent: import("./utils/captureContext").SnapshotIntent, userId: number): Promise<void>;
+        };
+        restore: ({ strapi }: {
+            strapi: import("@strapi/types/dist/core").Strapi;
+        }) => {
+            preview(versionId: number): Promise<import("./services/restore").RestorePreview>;
+            apply(versionId: number, userId: number): Promise<{
+                documentId: string;
+                warnings: string[];
+            }>;
+        };
+        diff: ({ strapi }: {
+            strapi: import("@strapi/types/dist/core").Strapi;
+        }) => {
+            between(versionId: number, againstId?: number): Promise<import("./services/diff").VersionDiff>;
+        };
+        retention: ({ strapi }: {
+            strapi: import("@strapi/types/dist/core").Strapi;
+        }) => {
+            prune(now?: Date): Promise<import("./services/retention").PruneResult>;
+        };
+        lock: ({ strapi }: {
+            strapi: import("@strapi/types/dist/core").Strapi;
+        }) => {
+            acquire(name: string, ttlMs: number): Promise<boolean>;
+            release(name: string): Promise<void>;
+        };
+    };
+};
+export default _default;

package/dist/server/src/routes/admin.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Read and restore are separate permissions on purpose: a reviewer should be
+ * able to see what changed without being able to undo someone else's work.
+ */
+declare const _default: {
+    type: string;
+    routes: {
+        method: string;
+        path: string;
+        handler: string;
+        config: {
+            policies: string[];
+        };
+    }[];
+};
+export default _default;

package/dist/server/src/routes/index.d.ts

@@ -0,0 +1,14 @@
+declare const _default: {
+    admin: {
+        type: string;
+        routes: {
+            method: string;
+            path: string;
+            handler: string;
+            config: {
+                policies: string[];
+            };
+        }[];
+    };
+};
+export default _default;

package/dist/server/src/services/diff.d.ts

@@ -0,0 +1,55 @@
+import type { Core } from '@strapi/strapi';
+import type { RelationRef } from './serializer';
+import { type DiffSpan } from '../utils/textDiff';
+export type ChangeKind = 'added' | 'removed' | 'changed';
+export interface FieldChange {
+    field: string;
+    /** The attribute's type in the live model, or 'unknown' if it is gone. */
+    type: string;
+    /**
+     * A custom field's uid, when the attribute is one. Custom fields all report
+     * their storage type — usually `json` — so this is the only thing specific
+     * enough for the owning package to key a diff renderer on.
+     */
+    customField?: string;
+    kind: ChangeKind;
+    /** Scalars only — the values themselves, for a plain before/after. */
+    before?: unknown;
+    after?: unknown;
+    /** Prose fields — a word-level diff of the readable text. */
+    spans?: DiffSpan[];
+    /** Relations and media — what was linked and unlinked. */
+    linked?: RelationRef[];
+    unlinked?: RelationRef[];
+}
+export interface VersionDiff {
+    from: {
+        id: number;
+        label: string | null;
+        createdAt: string;
+        origin: string;
+    } | null;
+    to: {
+        id: number;
+        label: string | null;
+        createdAt: string;
+        origin: string;
+    };
+    changes: FieldChange[];
+    /** True when the two versions hold identical content. */
+    identical: boolean;
+}
+declare const diff: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => {
+    /**
+     * What changed between a version and the one before it.
+     *
+     * Comparing against the previous version — rather than against the document
+     * as it stands — is what makes a history readable: each entry answers "what
+     * did this edit do?". The other question, "what would restoring this
+     * change?", is what `restore.preview()` already answers.
+     */
+    between(versionId: number, againstId?: number): Promise<VersionDiff>;
+};
+export default diff;

package/dist/server/src/services/index.d.ts

@@ -0,0 +1,35 @@
+declare const _default: {
+    snapshot: ({ strapi }: {
+        strapi: import("@strapi/types/dist/core").Strapi;
+    }) => {
+        readRows: (uid: string, relatedDocumentId: string, locales: string[]) => Promise<Record<string, unknown>[]>;
+        captureAll(intents: import("../utils/captureContext").SnapshotIntent[], userId: number): Promise<void>;
+        capture(intent: import("../utils/captureContext").SnapshotIntent, userId: number): Promise<void>;
+    };
+    restore: ({ strapi }: {
+        strapi: import("@strapi/types/dist/core").Strapi;
+    }) => {
+        preview(versionId: number): Promise<import("./restore").RestorePreview>;
+        apply(versionId: number, userId: number): Promise<{
+            documentId: string;
+            warnings: string[];
+        }>;
+    };
+    diff: ({ strapi }: {
+        strapi: import("@strapi/types/dist/core").Strapi;
+    }) => {
+        between(versionId: number, againstId?: number): Promise<import("./diff").VersionDiff>;
+    };
+    retention: ({ strapi }: {
+        strapi: import("@strapi/types/dist/core").Strapi;
+    }) => {
+        prune(now?: Date): Promise<import("./retention").PruneResult>;
+    };
+    lock: ({ strapi }: {
+        strapi: import("@strapi/types/dist/core").Strapi;
+    }) => {
+        acquire(name: string, ttlMs: number): Promise<boolean>;
+        release(name: string): Promise<void>;
+    };
+};
+export default _default;

package/dist/server/src/services/lock.d.ts

@@ -0,0 +1,20 @@
+import type { Core } from '@strapi/strapi';
+/**
+ * A best-effort lock held in the core store.
+ *
+ * Two instances behind a load balancer run the same cron, so without this they
+ * both start pruning the same rows at the same time. Deleting a row twice is
+ * harmless; doing the whole scan twice on a large table is not.
+ *
+ * Best-effort is the honest description: read-then-write is not atomic, so two
+ * instances starting within the same millisecond can both win. That is
+ * acceptable for a nightly tidy-up and not for anything else — do not reuse
+ * this for something that must happen exactly once.
+ */
+declare const lock: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => {
+    acquire(name: string, ttlMs: number): Promise<boolean>;
+    release(name: string): Promise<void>;
+};
+export default lock;

package/dist/server/src/services/restore.d.ts

@@ -0,0 +1,44 @@
+import type { Core } from '@strapi/strapi';
+import type { RelationRef } from './serializer';
+export interface RestorePreview {
+    /** Fields that will be written back. */
+    fieldsToRestore: string[];
+    /** In the model but not in the version — left exactly as they are. */
+    fieldsKeptAsIs: string[];
+    /** In the version but no longer in the model — skipped. */
+    fieldsDropped: string[];
+    /** Not localised, so restoring them changes every locale at once. */
+    crossLocaleFields: string[];
+    /** Polymorphic relations, which this version of the plugin does not carry. */
+    unsupportedFields: string[];
+    /** Relation targets that no longer exist. */
+    brokenRelations: RelationRef[];
+    /** Media that has since been deleted. */
+    missingMedia: RelationRef[];
+    /** Locales affected by the cross-locale fields above. */
+    affectedLocales: string[];
+}
+declare const restore: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => {
+    /**
+     * What restoring this version would actually do.
+     *
+     * A separate call, and the UI shows it before asking for confirmation.
+     * Restore without a preview of the consequences is a trap rather than a
+     * tool — `crossLocaleFields` in particular, where restoring the Polish
+     * version of a document quietly rewrites a field in every other language.
+     */
+    preview(versionId: number): Promise<RestorePreview>;
+    /**
+     * Writes the version back, to the draft only.
+     *
+     * The document lands in "modified" and publishing stays a deliberate act —
+     * restoring must never change what the public sees on its own.
+     */
+    apply(versionId: number, userId: number | null): Promise<{
+        documentId: string;
+        warnings: string[];
+    }>;
+};
+export default restore;

package/dist/server/src/services/retention.d.ts

@@ -0,0 +1,18 @@
+import type { Core } from '@strapi/strapi';
+export interface PruneResult {
+    scanned: number;
+    deleted: number;
+    documents: number;
+}
+declare const retention: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => {
+    /**
+     * Thins the history according to the configured policy.
+     *
+     * Returns what it did rather than logging and forgetting, so the cron can
+     * report it and a test can assert on it.
+     */
+    prune(now?: Date): Promise<PruneResult>;
+};
+export default retention;

package/dist/server/src/services/serializer.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Turning a stored document into a version, and back.
+ *
+ * Written for this plugin rather than lifted from Strapi's own history module.
+ * Where the shapes here resemble theirs it is because Strapi's populate API
+ * dictates them — a relation can only be populated by naming its fields, a
+ * dynamic zone only through `on` fragments — not because the code was copied.
+ * Their implementation is MIT and was read while working out what the problem
+ * actually is; two facts learned that way are worth stating outright, since
+ * both cost a day if you meet them the hard way:
+ *
+ *   - a component's `id` must not be stored, or restoring into a component row
+ *     that has since been recreated throws;
+ *   - the fields in FIELDS_TO_IGNORE change on every write, so a version that
+ *     keeps them can never be compared against another one.
+ *
+ * `buildSchemaSnapshot` goes further than theirs on purpose: Strapi's descends a
+ * single level and carries an open TODO about nested components, which leaves a
+ * component inside a component indistinguishable from a field that never
+ * existed.
+ */
+import type { Core } from '@strapi/strapi';
+/**
+ * Fields Strapi manages, which a version has no business storing or restoring.
+ *
+ * The timestamps and author columns change on every write, so a version that
+ * keeps them can never be compared with another. `locale` and `localizations`
+ * are injected by i18n and describe how the document is wired up rather than
+ * what it says — restoring them would try to rewrite the translation graph.
+ */
+export declare const FIELDS_TO_IGNORE: string[];
+export interface RelationRef {
+    documentId?: string;
+    /** Media lives in `plugin::upload.file` and is addressed by numeric id. */
+    id?: number;
+    locale?: string | null;
+    targetUid: string;
+}
+export interface SplitDocument {
+    data: Record<string, unknown>;
+    relations: Record<string, RelationRef[]>;
+    schemaSnapshot: Record<string, unknown>;
+}
+type Attribute = Record<string, any>;
+/** Morph relations are skipped: Strapi's own populate builder skips them too. */
+export declare const isMorphRelation: (attribute: Attribute) => boolean;
+/** Populate object covering everything a snapshot needs, and nothing more. */
+export declare const buildDeepPopulate: (strapi: Core.Strapi, uid: string, useDatabaseSyntax?: boolean) => Record<string, unknown>;
+/**
+ * The content type's attributes plus every component reachable from it, however
+ * deeply nested.
+ *
+ * Without the nesting a restore cannot tell "this field was empty" from "this
+ * field did not exist yet" for anything below the first level of components.
+ */
+export declare const buildSchemaSnapshot: (strapi: Core.Strapi, uid: string) => Record<string, unknown>;
+/**
+ * Splits a populated entry into the three things a version stores.
+ *
+ * Relations are kept apart from `data` so a diff can treat "the body changed"
+ * and "the author changed" as different kinds of change, and so a restore can
+ * check each target still exists before writing it back.
+ */
+export declare const split: (strapi: Core.Strapi, uid: string, entry: Record<string, unknown>) => SplitDocument;
+export {};

package/dist/server/src/services/snapshot.d.ts

@@ -0,0 +1,17 @@
+import type { Core } from '@strapi/strapi';
+import type { SnapshotIntent } from '../utils/captureContext';
+export declare const VERSION_UID = "plugin::rewind.version";
+declare const snapshot: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => {
+    readRows: (uid: string, relatedDocumentId: string, locales: (string | null)[]) => Promise<Record<string, unknown>[]>;
+    /**
+     * Writes one version per affected locale, for each buffered intent.
+     *
+     * Called from the transaction's commit hook and never awaited by the write
+     * path — a failure here must not be able to reach the editor's save.
+     */
+    captureAll(intents: SnapshotIntent[], userId: number | null): Promise<void>;
+    capture(intent: SnapshotIntent, userId: number | null): Promise<void>;
+};
+export default snapshot;

package/dist/server/src/utils/backfillLabels.d.ts

@@ -0,0 +1,18 @@
+import type { Core } from '@strapi/strapi';
+/**
+ * Gives versions recorded before labels existed something to show.
+ *
+ * Without this, upgrading leaves a history where older entries are a badge and
+ * a timestamp and newer ones have a title — the list stays half-unreadable for
+ * exactly as long as the old versions are worth keeping.
+ *
+ * Two details that matter:
+ *
+ * - Rows whose content yields no label are written as an empty string, not left
+ *   null. Leaving them null would make the next batch select the same rows
+ *   again, forever.
+ * - It runs detached. The work is proportional to how many versions exist, and
+ *   a site with a long history should not pay minutes of boot time for a
+ *   cosmetic column.
+ */
+export declare const backfillLabels: (strapi: Core.Strapi, versionUid: string) => Promise<number>;