@openinc/parse-server-opendash 4.1.1 → 4.1.2

package/dist/scripts/migration/lib/pass.d.ts

@@ -0,0 +1,67 @@
+import { type MigrationConfig } from "./env.js";
+import type { MigrationMap } from "./map.js";
+import type { PassReport, Report } from "./report.js";
+/** Everything a pass needs, handed to it by the orchestrator. */
+export interface PassContext {
+    config: MigrationConfig;
+    map: MigrationMap;
+    report: Report;
+    entry: PassReport;
+}
+/**
+ * A migration pass. `id` doubles as the ordering key and the `--only` selector;
+ * `needs` names the pass ids whose output this one reads, which the orchestrator
+ * enforces rather than trusting the operator to invoke things in order.
+ */
+export interface Pass {
+    id: string;
+    title: string;
+    needs: string[];
+    run(ctx: PassContext): Promise<void>;
+}
+/**
+ * Page through a query, yielding batches.
+ *
+ * Paging rule for every read in the migration: **stop only on an empty page.**
+ *
+ * A short page must NOT be read as "no more data". Parse Server silently clamps a
+ * requested `limit` down to its configured `maxLimit`
+ * (`parse-server/lib/Routers/ClassesRouter.js`: `options.limit = maxLimit`) with no
+ * error, so a `--batch` above that ceiling makes every page come back short — and a
+ * `page.length < batchSize` break would end the loop after the first page and
+ * migrate a fraction of the data while reporting a clean run.
+ *
+ * Stopping on empty costs one extra round trip per table and is correct whatever
+ * the server's limit config happens to be.
+ *
+ * Deliberately *not* the v1 read pattern: `openinc-openservice-ticket-data.ts`
+ * issues roughly ten point queries per ticket, which at 10k tickets is 100k
+ * round-trips. Passes load each source table once in pages and reduce in memory.
+ *
+ * Ordered by `createdAt` so paging is stable and so passes that depend on insert
+ * order (tickets, whose numbers come from the backend counter) get it for free.
+ */
+export declare function pages<T extends Parse.Object>(build: () => Parse.Query<T>, batchSize: number): AsyncGenerator<T[]>;
+/**
+ * Count rows by paging, not with `Query.count()`.
+ *
+ * `count()` is **not** usable under maintenance auth: Parse's class-level
+ * permissions carry a separate `count` action, and that check is not bypassed for
+ * maintenance the way `find` is. Verified against this server — an identical query
+ * on a role-restricted class succeeds with `find()` and fails with
+ * `count()`: "Permission denied". Left as `count()`, every counting check in
+ * `verify.ts` would report a permissions error dressed up as a data problem.
+ *
+ * Costs one request per page, which at this volume is a handful.
+ */
+export declare function countAll<T extends Parse.Object>(build: () => Parse.Query<T>, batchSize: number): Promise<number>;
+/** Collect every row of a query. Only for tables known to be small. */
+export declare function all<T extends Parse.Object>(build: () => Parse.Query<T>, batchSize: number): Promise<T[]>;
+/**
+ * Scope a query to one tenant when `--tenant` was given.
+ *
+ * Passing the id as a bare pointer avoids fetching the Tenant object first.
+ */
+export declare function scopeToTenant<T extends Parse.Object>(query: Parse.Query<T>, tenantId: string | undefined): Parse.Query<T>;
+/** The objectId behind a pointer-ish value, without fetching it. */
+export declare function refId(value: unknown): string | undefined;

package/dist/scripts/migration/lib/pass.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pages = pages;
+exports.countAll = countAll;
+exports.all = all;
+exports.scopeToTenant = scopeToTenant;
+exports.refId = refId;
+const env_js_1 = require("./env.js");
+/**
+ * Page through a query, yielding batches.
+ *
+ * Paging rule for every read in the migration: **stop only on an empty page.**
+ *
+ * A short page must NOT be read as "no more data". Parse Server silently clamps a
+ * requested `limit` down to its configured `maxLimit`
+ * (`parse-server/lib/Routers/ClassesRouter.js`: `options.limit = maxLimit`) with no
+ * error, so a `--batch` above that ceiling makes every page come back short — and a
+ * `page.length < batchSize` break would end the loop after the first page and
+ * migrate a fraction of the data while reporting a clean run.
+ *
+ * Stopping on empty costs one extra round trip per table and is correct whatever
+ * the server's limit config happens to be.
+ *
+ * Deliberately *not* the v1 read pattern: `openinc-openservice-ticket-data.ts`
+ * issues roughly ten point queries per ticket, which at 10k tickets is 100k
+ * round-trips. Passes load each source table once in pages and reduce in memory.
+ *
+ * Ordered by `createdAt` so paging is stable and so passes that depend on insert
+ * order (tickets, whose numbers come from the backend counter) get it for free.
+ */
+async function* pages(build, batchSize) {
+    let skip = 0;
+    for (;;) {
+        const page = await build().limit(batchSize).skip(skip).ascending("createdAt").find(env_js_1.MK);
+        if (page.length === 0)
+            return;
+        yield page;
+        // Advance by what came back, not by what was asked for — see the note above.
+        skip += page.length;
+    }
+}
+/**
+ * Count rows by paging, not with `Query.count()`.
+ *
+ * `count()` is **not** usable under maintenance auth: Parse's class-level
+ * permissions carry a separate `count` action, and that check is not bypassed for
+ * maintenance the way `find` is. Verified against this server — an identical query
+ * on a role-restricted class succeeds with `find()` and fails with
+ * `count()`: "Permission denied". Left as `count()`, every counting check in
+ * `verify.ts` would report a permissions error dressed up as a data problem.
+ *
+ * Costs one request per page, which at this volume is a handful.
+ */
+async function countAll(build, batchSize) {
+    let total = 0;
+    for await (const page of pages(build, batchSize))
+        total += page.length;
+    return total;
+}
+/** Collect every row of a query. Only for tables known to be small. */
+async function all(build, batchSize) {
+    const out = [];
+    for await (const page of pages(build, batchSize))
+        out.push(...page);
+    return out;
+}
+/**
+ * Scope a query to one tenant when `--tenant` was given.
+ *
+ * Passing the id as a bare pointer avoids fetching the Tenant object first.
+ */
+function scopeToTenant(query, tenantId) {
+    if (!tenantId)
+        return query;
+    return query.equalTo("tenant", {
+        __type: "Pointer",
+        className: "OD3_Tenant",
+        objectId: tenantId,
+    });
+}
+/** The objectId behind a pointer-ish value, without fetching it. */
+function refId(value) {
+    if (!value)
+        return undefined;
+    if (typeof value === "string")
+        return value;
+    const obj = value;
+    return obj.id ?? obj.objectId;
+}

package/dist/scripts/migration/lib/ptr.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Pointer construction without fetching.
+ *
+ * Every pass writes pointers whose targets it already knows the id of, so
+ * materialising the target object first would be pure round-trips. Parse accepts a
+ * bare pointer literal on save.
+ */
+export interface Ptr {
+    __type: "Pointer";
+    className: string;
+    objectId: string;
+}
+export declare function ptr(className: string, objectId: string): Ptr;
+export declare function maybePtr(className: string, objectId: string | undefined): Ptr | undefined;
+export declare const tenantPtr: (id: string) => Ptr;
+export declare const userPtr: (id: string) => Ptr;
+export declare const rolePtr: (id: string) => Ptr;
+/**
+ * The wire form of a Date, as Parse serialises it.
+ *
+ * Needed when building the `original` / `value` snapshots for reconstructed
+ * changelog entries: the changelog viewer's diff renderer keys off `__type`, so a
+ * raw JS Date in a snapshot would render as an opaque string instead of a date.
+ */
+export declare function dateVal(d: Date): {
+    __type: "Date";
+    iso: string;
+};
+/** JSON-stringified context array, matching how the chat and meta plugins store it. */
+export declare function contextToString(parts: string[]): string;
+/** The context every artefact attached to one ticket shares (chat, assets, ...). */
+export declare function ticketContext(ticketId: string): string[];

package/dist/scripts/migration/lib/ptr.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rolePtr = exports.userPtr = exports.tenantPtr = void 0;
+exports.ptr = ptr;
+exports.maybePtr = maybePtr;
+exports.dateVal = dateVal;
+exports.contextToString = contextToString;
+exports.ticketContext = ticketContext;
+function ptr(className, objectId) {
+    return { __type: "Pointer", className, objectId };
+}
+function maybePtr(className, objectId) {
+    return objectId ? ptr(className, objectId) : undefined;
+}
+const tenantPtr = (id) => ptr("OD3_Tenant", id);
+exports.tenantPtr = tenantPtr;
+const userPtr = (id) => ptr("_User", id);
+exports.userPtr = userPtr;
+const rolePtr = (id) => ptr("_Role", id);
+exports.rolePtr = rolePtr;
+/**
+ * The wire form of a Date, as Parse serialises it.
+ *
+ * Needed when building the `original` / `value` snapshots for reconstructed
+ * changelog entries: the changelog viewer's diff renderer keys off `__type`, so a
+ * raw JS Date in a snapshot would render as an opaque string instead of a date.
+ */
+function dateVal(d) {
+    return { __type: "Date", iso: d.toISOString() };
+}
+/** JSON-stringified context array, matching how the chat and meta plugins store it. */
+function contextToString(parts) {
+    return JSON.stringify(parts);
+}
+/** The context every artefact attached to one ticket shares (chat, assets, ...). */
+function ticketContext(ticketId) {
+    return ["service", "ticket", ticketId];
+}

package/dist/scripts/migration/lib/report.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Per-pass tally. Every pass reports what it did, what it skipped and why, so a
+ * run leaves an artefact you can diff against the next one rather than a wall of
+ * log lines.
+ */
+export interface PassReport {
+    pass: string;
+    created: number;
+    updated: number;
+    skipped: number;
+    /** Non-fatal oddities worth a human look — unparseable values, missing refs. */
+    warnings: string[];
+    /** Pass-level summary lines. Never suppressed — see `Report.info`. */
+    notes: string[];
+    /** Fatal per-row failures; the pass continues, the run is marked failed. */
+    errors: string[];
+    startedAt: string;
+    finishedAt?: string;
+}
+export declare class Report {
+    private readonly passes;
+    private current?;
+    begin(pass: string): PassReport;
+    end(): void;
+    /**
+     * A pass-level summary line — counts, totals, what was skipped in bulk.
+     *
+     * Deliberately a separate channel from {@link warn}. Warnings are capped, because
+     * a per-row warning over 10k rows must not print 10k lines — but the summaries
+     * are emitted *after* the loop that produced those warnings, so sharing the cap
+     * would suppress exactly the lines the run report is read for.
+     */
+    info(report: PassReport, message: string): void;
+    /** A capped sample of per-row warnings. */
+    warn(report: PassReport, message: string, cap?: number): void;
+    error(report: PassReport, message: string): void;
+    get failed(): boolean;
+    /** Machine-readable summary — write this next to the run for later comparison. */
+    toJSON(): PassReport[];
+    printSummary(runId: string, dryRun: boolean): void;
+}

package/dist/scripts/migration/lib/report.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Report = void 0;
+class Report {
+    passes = [];
+    current;
+    begin(pass) {
+        this.current = {
+            pass,
+            created: 0,
+            updated: 0,
+            skipped: 0,
+            warnings: [],
+            notes: [],
+            errors: [],
+            startedAt: new Date().toISOString(),
+        };
+        this.passes.push(this.current);
+        console.log(`\n── ${pass} ${"─".repeat(Math.max(0, 60 - pass.length))}`);
+        return this.current;
+    }
+    end() {
+        if (!this.current)
+            return;
+        this.current.finishedAt = new Date().toISOString();
+        const { created, updated, skipped, warnings, errors } = this.current;
+        console.log(`   created ${created} · updated ${updated} · skipped ${skipped}` +
+            `${warnings.length ? ` · ${warnings.length} warning(s)` : ""}` +
+            `${errors.length ? ` · ${errors.length} ERROR(S)` : ""}`);
+        this.current = undefined;
+    }
+    /**
+     * A pass-level summary line — counts, totals, what was skipped in bulk.
+     *
+     * Deliberately a separate channel from {@link warn}. Warnings are capped, because
+     * a per-row warning over 10k rows must not print 10k lines — but the summaries
+     * are emitted *after* the loop that produced those warnings, so sharing the cap
+     * would suppress exactly the lines the run report is read for.
+     */
+    info(report, message) {
+        report.notes.push(message);
+        console.log(`   · ${message}`);
+    }
+    /** A capped sample of per-row warnings. */
+    warn(report, message, cap = 25) {
+        if (report.warnings.length < cap) {
+            report.warnings.push(message);
+            console.warn(`   ! ${message}`);
+        }
+        else if (report.warnings.length === cap) {
+            report.warnings.push(`… further warnings suppressed`);
+            console.warn(`   ! further warnings suppressed`);
+        }
+    }
+    error(report, message) {
+        report.errors.push(message);
+        console.error(`   ✗ ${message}`);
+    }
+    get failed() {
+        return this.passes.some((p) => p.errors.length > 0);
+    }
+    /** Machine-readable summary — write this next to the run for later comparison. */
+    toJSON() {
+        return this.passes;
+    }
+    printSummary(runId, dryRun) {
+        console.log(`\n${"═".repeat(64)}`);
+        console.log(`run ${runId}${dryRun ? "  (DRY RUN — nothing written)" : ""}`);
+        for (const p of this.passes) {
+            const flag = p.errors.length ? "FAIL" : "ok  ";
+            console.log(`  ${flag}  ${p.pass.padEnd(22)} ` +
+                `+${String(p.created).padStart(6)}  ~${String(p.updated).padStart(6)}  ` +
+                `skip ${String(p.skipped).padStart(6)}`);
+        }
+        console.log(`${"═".repeat(64)}\n`);
+    }
+}
+exports.Report = Report;

package/dist/scripts/migration/lib/rest.d.ts

@@ -0,0 +1,47 @@
+import type { MigrationConfig } from "./env.js";
+/**
+ * Creating objects with historical timestamps.
+ *
+ * **Why this exists instead of `object.save()`.** The Parse JS SDK silently drops
+ * `createdAt` / `updatedAt`:
+ *
+ * ```js
+ * // ParseObject.js, in the set() path
+ * if (k === "createdAt" || k === "updatedAt") {
+ *   // This property is read-only, but for legacy reasons we silently ignore it
+ *   continue;
+ * }
+ * ```
+ *
+ * So `object.set("createdAt", …)` never reaches `dirtyKeys()` and never reaches the
+ * wire — the save succeeds and the server stamps `now`. No error anywhere. Since
+ * the whole point of running under the maintenance key is to preserve the original
+ * timestamps, every create has to bypass the SDK and post the REST body itself.
+ *
+ * Queries and updates stay on the SDK: reads do not care, and Parse ignores
+ * `createdAt` on update regardless.
+ */
+interface CreateResult {
+    objectId: string;
+    createdAt: string;
+}
+/**
+ * POST a new object with explicit timestamps, returning its new objectId.
+ *
+ * `object.toJSON()` already produces exactly the REST body shape — dates and
+ * pointers encoded, ACL included — so the typed Parse subclasses stay usable for
+ * building the object even though the SDK cannot save it for us.
+ *
+ * The trigger context travels in `X-Parse-Cloud-Context` (see
+ * `parse-server/lib/middlewares.js`), which is how `skipChangelog` still reaches
+ * the changelog hook on this path.
+ */
+export declare function restCreate(config: MigrationConfig, className: string, object: Parse.Object, createdAt: Date | undefined, updatedAt?: Date): Promise<CreateResult>;
+/**
+ * The same create, from a plain REST body rather than a Parse.Object.
+ *
+ * Used by the v1 test-data seeder, which is clearer to read as literal payloads
+ * than as a pile of `.set()` calls.
+ */
+export declare function restCreateRaw(config: MigrationConfig, className: string, payload: Record<string, unknown>, createdAt: Date | undefined, updatedAt?: Date): Promise<CreateResult>;
+export {};

package/dist/scripts/migration/lib/rest.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.restCreate = restCreate;
+exports.restCreateRaw = restCreateRaw;
+function dateVal(d) {
+    return { __type: "Date", iso: d.toISOString() };
+}
+/**
+ * POST a new object with explicit timestamps, returning its new objectId.
+ *
+ * `object.toJSON()` already produces exactly the REST body shape — dates and
+ * pointers encoded, ACL included — so the typed Parse subclasses stay usable for
+ * building the object even though the SDK cannot save it for us.
+ *
+ * The trigger context travels in `X-Parse-Cloud-Context` (see
+ * `parse-server/lib/middlewares.js`), which is how `skipChangelog` still reaches
+ * the changelog hook on this path.
+ */
+async function restCreate(config, className, object, createdAt, updatedAt) {
+    const body = { ...object.toJSON() };
+    // toJSON() carries these on an existing object; a create must not send them.
+    delete body.objectId;
+    delete body.className;
+    return restCreateRaw(config, className, body, createdAt, updatedAt);
+}
+/**
+ * The same create, from a plain REST body rather than a Parse.Object.
+ *
+ * Used by the v1 test-data seeder, which is clearer to read as literal payloads
+ * than as a pile of `.set()` calls.
+ */
+async function restCreateRaw(config, className, payload, createdAt, updatedAt) {
+    const body = { ...payload };
+    if (createdAt) {
+        body.createdAt = dateVal(createdAt);
+        // Parse rejects an updatedAt earlier than createdAt, and defaults it to
+        // createdAt when omitted.
+        const resolved = updatedAt && updatedAt.getTime() >= createdAt.getTime()
+            ? updatedAt
+            : createdAt;
+        body.updatedAt = dateVal(resolved);
+    }
+    const response = await fetch(`${config.parseUrl}/classes/${encodeURIComponent(className)}`, {
+        method: "POST",
+        headers: {
+            "X-Parse-Application-Id": config.appId,
+            "X-Parse-Maintenance-Key": config.maintenanceKey,
+            "X-Parse-Cloud-Context": JSON.stringify({ skipChangelog: true }),
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    const text = await response.text();
+    if (!response.ok) {
+        throw new Error(`POST /classes/${className} → ${response.status}: ${text.slice(0, 400)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`POST /classes/${className} returned unparseable body: ${text.slice(0, 200)}`);
+    }
+    if (!parsed.objectId) {
+        throw new Error(`POST /classes/${className} returned no objectId: ${text.slice(0, 200)}`);
+    }
+    return { objectId: parsed.objectId, createdAt: parsed.createdAt ?? "" };
+}

package/dist/scripts/migration/lib/ticket.d.ts

@@ -0,0 +1,72 @@
+import type { MigrationConfig } from "./env.js";
+/**
+ * Hands out `Ticket.number` the way the backend hook would.
+ *
+ * Per-project when the ticket has one (`Project.ticketCounter`), otherwise
+ * per-tenant (`OD3_Service_TicketCounter.value`).
+ *
+ * Counters are seeded from their **current** stored values and flushed once at the
+ * end, rather than incremented per ticket. That is both far fewer round trips and
+ * safe for a re-run: an already-migrated ticket keeps the number it has and
+ * consumes nothing, so a resumed run continues the sequence instead of restarting
+ * it. Safe precisely because the migration is single-threaded — the hook needs
+ * atomic `$inc` because concurrent clients race; here nothing else is writing.
+ */
+export declare class TicketNumberer {
+    private readonly config;
+    private readonly projectCounters;
+    private readonly tenantCounters;
+    private readonly tenantCounterIds;
+    private readonly dirtyProjects;
+    private readonly dirtyTenants;
+    constructor(config: MigrationConfig);
+    /** Read the current counter values so numbering continues rather than restarts. */
+    load(): Promise<void>;
+    /**
+     * The next number for a ticket, or undefined when there is no scope to count in
+     * (no project and no tenant) — matching the hook, which leaves those unnumbered.
+     */
+    next(projectId: string | undefined, tenantId: string | undefined): number | undefined;
+    /**
+     * Persist the counters.
+     *
+     * Must run even if the pass had per-ticket errors: leaving a counter behind the
+     * numbers already handed out would make the *next* run reuse them, producing
+     * duplicates that `verify.ts` would then flag.
+     */
+    flush(): Promise<{
+        projects: number;
+        tenants: number;
+    }>;
+}
+/** Role id → role name, needed because Parse ACLs grant by name, not by id. */
+export declare function loadRoleNames(config: MigrationConfig): Promise<Map<string, string>>;
+/**
+ * The ACL a v2 ticket should carry.
+ *
+ * `migrationAcl` covers what `defaultAclHandler` would have granted (od-admin and
+ * the tenant roles); this adds what `setTicketACL` would have granted on top —
+ * creator and assignees, read and write.
+ *
+ * Note the hook cannot actually do the assignee half today: it reads the arrays via
+ * a helper that takes `.id` off each entry, but the entity adapter stores
+ * array-of-ref fields as plain id **strings**, so it always resolves to nothing.
+ * Here we use the ids directly, so migrated tickets end up with the grants the hook
+ * was intended to give. That is a deliberate divergence, not an oversight.
+ */
+export declare function ticketAcl(options: {
+    tenantId: string;
+    creatorId?: string;
+    assignedUserIds: string[];
+    assignedRoleIds: string[];
+    roleNames: Map<string, string>;
+}): Parse.ACL;
+/**
+ * The ACLs of the already-migrated v2 tickets, keyed by ticket id.
+ *
+ * Pass 12 needs these twice: the reconstructed changelog entry must carry the ACL
+ * of the ticket it describes (normally `beforeSave(OD3_Changelog)` mirrors it from
+ * the snapshot, but that trigger is suppressed too), and the snapshot itself should
+ * show the v2 ACL rather than the v1 one.
+ */
+export declare function loadTicketAcls(config: MigrationConfig): Promise<Map<string, Parse.ACL>>;