@qkix/strapi-plugin-ferry 0.1.0

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

@@ -0,0 +1,30 @@
+declare const _default: {
+    default: {
+        /**
+         * Content types Ferry will not carry, whatever the UI asks for.
+         *
+         * For anything that must not leave the environment it is in - a table of
+         * customer records, an integration's bookkeeping. The picker hides them and
+         * the endpoints refuse them, so a hidden thing cannot be exported by
+         * guessing its uid.
+         *
+         *   ferry: {
+         *     enabled: true,
+         *     config: { exclude: ['api::invoice.invoice'] },
+         *   }
+         */
+        exclude: string[];
+        /**
+         * The most documents one request will read out.
+         *
+         * An export holds its whole result in memory before writing it, so this is
+         * the honest limit rather than a policy: past it, use the filters.
+         */
+        maxExport: number;
+    };
+    validator(config: {
+        exclude?: unknown;
+        maxExport?: unknown;
+    }): void;
+};
+export default _default;

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

@@ -0,0 +1,12 @@
+declare const _default: {
+    transfer: ({ strapi }: {
+        strapi: import("@strapi/types/dist/core").Strapi;
+    }) => {
+        catalogue(ctx: any): Promise<void>;
+        plan(ctx: any): Promise<void>;
+        export(ctx: any): Promise<void>;
+        preview(ctx: any): Promise<void>;
+        apply(ctx: any): Promise<void>;
+    };
+};
+export default _default;

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

@@ -0,0 +1,14 @@
+import type { Core } from '@strapi/strapi';
+declare const transfer: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => {
+    /** The content types Ferry can carry, for the picker. */
+    catalogue(ctx: any): Promise<void>;
+    /** What would travel, and what would not, before anyone commits to it. */
+    plan(ctx: any): Promise<void>;
+    export(ctx: any): Promise<void>;
+    /** The dry run. Reads everything, writes nothing. */
+    preview(ctx: any): Promise<void>;
+    apply(ctx: any): Promise<void>;
+};
+export default transfer;

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

@@ -0,0 +1,97 @@
+declare const _default: {
+    register: ({ strapi }: {
+        strapi: import("@strapi/types/dist/core").Strapi;
+    }) => void;
+    config: {
+        default: {
+            exclude: string[];
+            maxExport: number;
+        };
+        validator(config: {
+            exclude?: unknown;
+            maxExport?: unknown;
+        }): void;
+    };
+    controllers: {
+        transfer: ({ strapi }: {
+            strapi: import("@strapi/types/dist/core").Strapi;
+        }) => {
+            catalogue(ctx: any): Promise<void>;
+            plan(ctx: any): Promise<void>;
+            export(ctx: any): Promise<void>;
+            preview(ctx: any): Promise<void>;
+            apply(ctx: any): Promise<void>;
+        };
+    };
+    policies: {
+        canExport: (policyContext: any) => any;
+        canImport: (policyContext: any) => any;
+    };
+    routes: {
+        admin: {
+            type: string;
+            routes: {
+                method: string;
+                path: string;
+                handler: string;
+                config: {
+                    policies: string[];
+                };
+            }[];
+        };
+    };
+    services: {
+        schema: ({ strapi }: {
+            strapi: import("@strapi/types/dist/core").Strapi;
+        }) => {
+            model(uid: string): import("./services/schema").RawModel;
+            component(uid: string): import("./services/schema").RawModel;
+            plan(uid: string): import("./types").Plan;
+            componentPlan(uid: string): import("./types").Plan;
+            excluded(): Set<string>;
+            allowed(uid: string): boolean;
+            catalogue(): {
+                uid: string;
+                label: string;
+                kind: string;
+                count?: number;
+            }[];
+        };
+        exporter: ({ strapi }: {
+            strapi: import("@strapi/types/dist/core").Strapi;
+        }) => {
+            run(options: import("./types").ExportOptions): Promise<import("./services/export").ExportResult>;
+            readSingle(uid: string, query: Record<string, unknown>): Promise<any[]>;
+        };
+        importer: ({ strapi }: {
+            strapi: import("@strapi/types/dist/core").Strapi;
+        }) => {
+            preview(options: Partial<import("./types").ImportOptions> & {
+                uid: string;
+            }, parsed: import("./services/parse").Parsed): Promise<import("./types").Report>;
+            apply(options: Partial<import("./types").ImportOptions> & {
+                uid: string;
+            }, parsed: import("./services/parse").Parsed): Promise<import("./types").Report>;
+            run(options: Partial<import("./types").ImportOptions> & {
+                uid: string;
+            }, parsed: import("./services/parse").Parsed, apply: boolean): Promise<import("./types").Report>;
+            decide(entry: import("./services/import").Entry, plan: import("./types").Plan, existing: Set<string>, opts: import("./types").ImportOptions): "create" | "update" | "skip";
+            existingDocuments(plan: import("./types").Plan, opts: import("./types").ImportOptions, entries: import("./services/import").Entry[]): Promise<Set<string>>;
+            resolveRelations(plan: import("./types").Plan, opts: import("./types").ImportOptions, entries: import("./services/import").Entry[], report: import("./types").Report): Promise<Map<string, Set<string>>>;
+            resolveMedia(plan: import("./types").Plan, entries: import("./services/import").Entry[], report: import("./types").Report): Promise<Map<string, number>>;
+            content(entry: import("./services/import").Entry, plan: import("./types").Plan, media: Map<string, number>): Record<string, unknown>;
+            wiring(entry: import("./services/import").Entry, plan: import("./types").Plan, media: Map<string, number>, exists: (target: string, key: string) => boolean): Record<string, unknown>;
+            withMedia(data: Record<string, unknown>, plan: import("./types").Plan, media: Map<string, number>): Record<string, unknown>;
+            write(decided: {
+                entry: import("./services/import").Entry;
+                outcome: "create" | "update" | "skip";
+            }[], plan: import("./types").Plan, opts: import("./types").ImportOptions, context: {
+                media: Map<string, number>;
+                exists: (target: string, key: string) => boolean;
+                hasRelations: boolean;
+            }, report: import("./types").Report): Promise<void>;
+            singleTypeId(plan: import("./types").Plan, opts: import("./types").ImportOptions): Promise<string>;
+        };
+    };
+};
+export default _default;

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

@@ -0,0 +1,5 @@
+declare const _default: {
+    canExport: (policyContext: any) => any;
+    canImport: (policyContext: any) => any;
+};
+export default _default;

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

@@ -0,0 +1,12 @@
+import type { Core } from '@strapi/strapi';
+/**
+ * Two permissions: taking content out, and putting content in.
+ *
+ * Kept apart because they are not the same risk. An export is a copy; an import
+ * replaces what is there. A role that may do the first has no automatic claim
+ * on the second.
+ */
+declare const register: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => void;
+export default register;

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

@@ -0,0 +1,12 @@
+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/csv.d.ts

@@ -0,0 +1,59 @@
+/**
+ * CSV, done properly, with no dependency.
+ *
+ * "Split on commas" handles the CSV nobody has, and the abandoned plugin in
+ * this niche has two open bug reports that read exactly like a split: a comma
+ * inside a title, a newline inside a body. RFC 4180 is small enough to
+ * implement once and be done with, so it is implemented here as a state machine
+ * over characters rather than as a regular expression that is nearly right.
+ */
+declare const DELIMITERS: readonly [",", ";", "\t", "|"];
+export type Delimiter = (typeof DELIMITERS)[number];
+/**
+ * Guess the delimiter from the header line.
+ *
+ * A comma is the standard and a semicolon is what a spreadsheet saves in every
+ * locale that uses a comma as the decimal separator - which is most of Europe.
+ * Getting this wrong turns the whole file into one column, so it is worth the
+ * twenty lines: count candidates outside quotes and take the winner.
+ */
+export declare const sniffDelimiter: (text: string) => Delimiter;
+/**
+ * One value, as a cell.
+ *
+ * `null` and `undefined` both become empty, and that is a real loss of
+ * information the format cannot avoid: a CSV has no way to say "this field is
+ * null" as distinct from "this field is blank". The importer resolves the
+ * ambiguity in the safe direction by leaving blank cells alone rather than
+ * writing empty values over existing content. Anything structured is written as
+ * JSON, which survives the round trip and is at least readable in a cell.
+ */
+export declare const cell: (value: unknown, delimiter: string) => string;
+export interface EncodeOptions {
+    delimiter?: string;
+    /**
+     * Prefix the byte order mark. Excel opens a UTF-8 CSV as the local codepage
+     * without it, which turns every accented character into mojibake - so it is
+     * on by default and can be turned off for anything that is not a spreadsheet.
+     */
+    bom?: boolean;
+    /** Excel wants CRLF; everything else tolerates it. */
+    newline?: '\n' | '\r\n';
+}
+export declare const encode: (rows: Array<Record<string, unknown>>, columns: string[], options?: EncodeOptions) => string;
+/**
+ * The parser.
+ *
+ * Character by character, tracking whether it is inside quotes, because that is
+ * the only thing that decides whether a delimiter or a newline is data or
+ * structure. A doubled quote inside a quoted field is one literal quote, which
+ * is the rule everyone forgets.
+ */
+export declare const parse: (text: string, delimiter: string) => string[][];
+export interface Decoded {
+    columns: string[];
+    /** Rows keyed by column name. Extra cells beyond the header are dropped. */
+    rows: Array<Record<string, string>>;
+}
+export declare const decode: (text: string, delimiter?: string) => Decoded;
+export {};

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

@@ -0,0 +1,24 @@
+import type { Core } from '@strapi/strapi';
+import type { ExportOptions } from '../types';
+export interface ExportResult {
+    filename: string;
+    mime: string;
+    body: string;
+    count: number;
+    /** Things left out, said plainly rather than discovered later. */
+    warnings: string[];
+}
+export declare const DEFAULTS: Omit<ExportOptions, 'uid'>;
+declare const exportService: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => {
+    /** Everything of one content type that matches, as a file. */
+    run(options: ExportOptions): Promise<ExportResult>;
+    /**
+     * A single type is one document, or none at all before anyone has saved it.
+     * The document service still answers `findFirst`, so the only difference
+     * from a collection is the shape of the answer.
+     */
+    readSingle(uid: string, query: Record<string, unknown>): Promise<any[]>;
+};
+export default exportService;

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

@@ -0,0 +1,78 @@
+import type { Parsed } from './parse';
+import type { Core } from '@strapi/strapi';
+import type { ImportOptions, Plan, Report } from '../types';
+export declare const DEFAULTS: Omit<ImportOptions, 'uid'>;
+/**
+ * One row of the file, before anything has been decided about it.
+ *
+ * Exported because it turns up in the signatures of the service's own methods,
+ * and a name that a declaration file cannot reach fails the build rather than
+ * merely being inconvenient.
+ */
+export interface Entry {
+    row: number;
+    documentId?: string;
+    data: Record<string, unknown>;
+}
+declare const importService: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => {
+    /**
+     * A dry run: the whole resolution, none of the writes.
+     *
+     * Same code path as the real thing, so what it promises is what happens.
+     */
+    preview(options: Partial<ImportOptions> & {
+        uid: string;
+    }, parsed: Parsed): Promise<Report>;
+    apply(options: Partial<ImportOptions> & {
+        uid: string;
+    }, parsed: Parsed): Promise<Report>;
+    run(options: Partial<ImportOptions> & {
+        uid: string;
+    }, parsed: Parsed, apply: boolean): Promise<Report>;
+    decide(entry: Entry, plan: Plan, existing: Set<string>, opts: ImportOptions): 'create' | 'update' | 'skip';
+    /** Which of the documents in the file are already here. */
+    existingDocuments(plan: Plan, opts: ImportOptions, entries: Entry[]): Promise<Set<string>>;
+    /**
+     * Which relation targets are really there.
+     *
+     * One query per target content type rather than one per key. A file of a
+     * thousand articles all pointing at the same twenty authors asks about
+     * twenty authors once, not a thousand times - and the abandoned plugin's
+     * habit of resolving inside the row loop is why importing anything sizeable
+     * takes minutes.
+     */
+    resolveRelations(plan: Plan, opts: ImportOptions, entries: Entry[], report: Report): Promise<Map<string, Set<string>>>;
+    /**
+     * Media, matched by hash.
+     *
+     * The hash is derived from the file's contents, so the same image uploaded
+     * to two environments matches even when the filenames and the ids differ.
+     * Ferry does not carry the bytes; when the upload is not there, the field is
+     * left unset and said so, rather than pointing at somebody else's file.
+     */
+    resolveMedia(plan: Plan, entries: Entry[], report: Report): Promise<Map<string, number>>;
+    /** The payload for the first pass: content, with nothing pointing outward. */
+    content(entry: Entry, plan: Plan, media: Map<string, number>): Record<string, unknown>;
+    /** The payload for the second pass: the same content, now wired up. */
+    wiring(entry: Entry, plan: Plan, media: Map<string, number>, exists: (target: string, key: string) => boolean): Record<string, unknown>;
+    withMedia(data: Record<string, unknown>, plan: Plan, media: Map<string, number>): Record<string, unknown>;
+    /**
+     * The writes, in two passes.
+     *
+     * Everything exists before anything points at it. There is no ordering of a
+     * single pass that works: two documents that refer to each other cannot both
+     * be written second.
+     */
+    write(decided: Array<{
+        entry: Entry;
+        outcome: 'create' | 'update' | 'skip';
+    }>, plan: Plan, opts: ImportOptions, context: {
+        media: Map<string, number>;
+        exists: (target: string, key: string) => boolean;
+        hasRelations: boolean;
+    }, report: Report): Promise<void>;
+    singleTypeId(plan: Plan, opts: ImportOptions): Promise<string | undefined>;
+};
+export default importService;

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

@@ -0,0 +1,54 @@
+declare const _default: {
+    schema: ({ strapi }: {
+        strapi: import("@strapi/types/dist/core").Strapi;
+    }) => {
+        model(uid: string): import("./schema").RawModel;
+        component(uid: string): import("./schema").RawModel;
+        plan(uid: string): import("../types").Plan;
+        componentPlan(uid: string): import("../types").Plan;
+        excluded(): Set<string>;
+        allowed(uid: string): boolean;
+        catalogue(): {
+            uid: string;
+            label: string;
+            kind: string;
+            count?: number;
+        }[];
+    };
+    exporter: ({ strapi }: {
+        strapi: import("@strapi/types/dist/core").Strapi;
+    }) => {
+        run(options: import("../types").ExportOptions): Promise<import("./export").ExportResult>;
+        readSingle(uid: string, query: Record<string, unknown>): Promise<any[]>;
+    };
+    importer: ({ strapi }: {
+        strapi: import("@strapi/types/dist/core").Strapi;
+    }) => {
+        preview(options: Partial<import("../types").ImportOptions> & {
+            uid: string;
+        }, parsed: import("./parse").Parsed): Promise<import("../types").Report>;
+        apply(options: Partial<import("../types").ImportOptions> & {
+            uid: string;
+        }, parsed: import("./parse").Parsed): Promise<import("../types").Report>;
+        run(options: Partial<import("../types").ImportOptions> & {
+            uid: string;
+        }, parsed: import("./parse").Parsed, apply: boolean): Promise<import("../types").Report>;
+        decide(entry: import("./import").Entry, plan: import("../types").Plan, existing: Set<string>, opts: import("../types").ImportOptions): "create" | "update" | "skip";
+        existingDocuments(plan: import("../types").Plan, opts: import("../types").ImportOptions, entries: import("./import").Entry[]): Promise<Set<string>>;
+        resolveRelations(plan: import("../types").Plan, opts: import("../types").ImportOptions, entries: import("./import").Entry[], report: import("../types").Report): Promise<Map<string, Set<string>>>;
+        resolveMedia(plan: import("../types").Plan, entries: import("./import").Entry[], report: import("../types").Report): Promise<Map<string, number>>;
+        content(entry: import("./import").Entry, plan: import("../types").Plan, media: Map<string, number>): Record<string, unknown>;
+        wiring(entry: import("./import").Entry, plan: import("../types").Plan, media: Map<string, number>, exists: (target: string, key: string) => boolean): Record<string, unknown>;
+        withMedia(data: Record<string, unknown>, plan: import("../types").Plan, media: Map<string, number>): Record<string, unknown>;
+        write(decided: {
+            entry: import("./import").Entry;
+            outcome: "create" | "update" | "skip";
+        }[], plan: import("../types").Plan, opts: import("../types").ImportOptions, context: {
+            media: Map<string, number>;
+            exists: (target: string, key: string) => boolean;
+            hasRelations: boolean;
+        }, report: import("../types").Report): Promise<void>;
+        singleTypeId(plan: import("../types").Plan, opts: import("../types").ImportOptions): Promise<string>;
+    };
+};
+export default _default;

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

@@ -0,0 +1,38 @@
+import type { Plan } from '../types';
+/**
+ * Relations do not only live at the top of a document.
+ *
+ * A component can hold one, and a component inside a component inside a dynamic
+ * zone can hold one too. Strapi refuses the entire write when any of them
+ * points at something absent, so an importer that only looks at the document's
+ * own fields will fail on rows it never inspected and blame the row.
+ *
+ * These three walks are the same walk with different jobs: find the keys, take
+ * the relations out, put the resolvable ones back.
+ */
+export interface FoundRelation {
+    /** Where it was, for a message a person can act on: `seo.author`. */
+    path: string;
+    target: string;
+    keys: string[];
+}
+type PlanFor = (componentUid: string) => Plan;
+/** Every relation key in the document, however deep, with where it came from. */
+export declare const collectRelations: (document: Record<string, unknown>, plan: Plan, planFor: PlanFor) => FoundRelation[];
+/**
+ * A copy with every relation removed, at every depth.
+ *
+ * What the first pass writes. Every document in the file has to exist before
+ * any of them can point at another, so the first pass carries the content and
+ * the second pass carries the wiring.
+ */
+export declare const stripRelations: (value: Record<string, unknown>, plan: Plan, planFor: PlanFor) => Record<string, unknown>;
+/**
+ * A copy with the relations kept, minus the keys that lead nowhere.
+ *
+ * What the second pass writes. Dropping an unresolvable key rather than passing
+ * it on is the difference between a row that lands with one link missing and a
+ * row that Strapi refuses outright, taking the content with it.
+ */
+export declare const filterRelations: (value: Record<string, unknown>, plan: Plan, planFor: PlanFor, exists: (target: string, key: string) => boolean) => Record<string, unknown>;
+export {};

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

@@ -0,0 +1,25 @@
+import type { Format, Plan, Status } from '../types';
+export interface Parsed {
+    /** What the file says it holds, when it says anything. */
+    contentType?: string;
+    status?: Status;
+    locale?: string;
+    documents: Array<Record<string, unknown>>;
+    warnings: string[];
+}
+/**
+ * A cell, back into the type the schema says it is.
+ *
+ * CSV has one type, and it is string. Everything a spreadsheet hands back has
+ * to be talked out of being text before Strapi will accept it, and the schema
+ * is the only thing that knows into what.
+ */
+export declare const coerce: (raw: string, type: string) => unknown;
+/**
+ * Read a file into documents, without deciding anything about them.
+ *
+ * Parsing and importing are kept apart so that a malformed file fails before
+ * the database is opened, and so the dry run and the real run read exactly the
+ * same thing.
+ */
+export declare const parseFile: (text: string, format: Format, plan: Plan) => Parsed;

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

@@ -0,0 +1,20 @@
+import type { Core } from '@strapi/strapi';
+import type { Plan } from '../types';
+/** Enough of a file to identify it on the far side without carrying the bytes. */
+export declare const MEDIA_FIELDS: string[];
+interface Options {
+    relations: boolean;
+    media: boolean;
+}
+/**
+ * The populate argument, built from the schema rather than guessed.
+ *
+ * This is the difference between an export that contains a document's
+ * components and one that contains `[object Object]`, and it is where a naive
+ * implementation reaches for `populate: '*'` - which goes exactly one level
+ * deep. One level is enough for a component and not enough for a component
+ * inside a component, so half of a real schema comes out empty and nobody
+ * notices until the import is missing content.
+ */
+export declare const buildPopulate: (strapi: Core.Strapi, plan: Plan, options: Options, depth?: number) => Record<string, unknown>;
+export {};

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

@@ -0,0 +1,81 @@
+import type { Core } from '@strapi/strapi';
+import type { Plan } from '../types';
+export interface RawAttribute {
+    type: string;
+    relation?: string;
+    target?: string;
+    component?: string;
+    components?: string[];
+    repeatable?: boolean;
+    multiple?: boolean;
+    required?: boolean;
+    private?: boolean;
+    mappedBy?: string;
+    inversedBy?: string;
+    pluginOptions?: Record<string, any>;
+}
+export interface RawModel {
+    uid: string;
+    kind?: string;
+    modelType?: string;
+    options?: {
+        draftAndPublish?: boolean;
+    };
+    info?: {
+        displayName?: string;
+        singularName?: string;
+    };
+    attributes?: Record<string, RawAttribute>;
+    pluginOptions?: {
+        'content-type-builder'?: {
+            visible?: boolean;
+        };
+        i18n?: {
+            localized?: boolean;
+        };
+    };
+}
+declare const schema: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => {
+    model(uid: string): RawModel | undefined;
+    component(uid: string): RawModel | undefined;
+    /**
+     * Sort one content type's attributes into how each has to be carried.
+     *
+     * Everything downstream - the populate call, the CSV header, the two import
+     * passes - reads this and nothing else, so there is exactly one place that
+     * decides what a field is.
+     */
+    plan(uid: string): Plan;
+    /**
+     * The same sorting for a component, which needs it too: components nest,
+     * and a component three levels down still has relations to resolve.
+     */
+    componentPlan(uid: string): Plan;
+    /** Uids the project has put out of bounds in its plugin config. */
+    excluded(): Set<string>;
+    /**
+     * Whether Ferry may touch this content type at all.
+     *
+     * Checked by the endpoints as well as the picker. A hidden thing that can
+     * still be fetched by typing its uid is not hidden, and the reason someone
+     * excludes a content type is usually that its contents must not leave.
+     */
+    allowed(uid: string): boolean;
+    /**
+     * What Ferry will carry, for the picker in the admin panel.
+     *
+     * Only the project's own types. Strapi's internal tables are real content
+     * types, but exporting the admin user table or the upload file index moves
+     * infrastructure rather than content, and importing it into another
+     * environment breaks that environment.
+     */
+    catalogue(): Array<{
+        uid: string;
+        label: string;
+        kind: string;
+        count?: number;
+    }>;
+};
+export default schema;

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

@@ -0,0 +1,14 @@
+import type { Core } from '@strapi/strapi';
+import type { ExportedDocument, Plan } from '../types';
+interface Options {
+    relations: boolean;
+    media: boolean;
+}
+export declare const makeSerialiser: (strapi: Core.Strapi) => {
+    document: (raw: any, plan: Plan, options: Options) => ExportedDocument;
+    componentValue: (value: any, plan: Plan, options: Options) => unknown;
+    zoneValue: (value: any, options: Options) => unknown[];
+    relationValue: (value: any, many: boolean) => unknown;
+    mediaValue: (value: any, many: boolean) => unknown;
+};
+export {};