@pilotiq/pilotiq 0.7.2 → 0.8.1

package/dist/routes/globals.js

@@ -0,0 +1,131 @@
+import { view } from '@rudderjs/view';
+import { dispatchFormSubmit, findForms, selectForm } from '../elements/dispatchForm.js';
+import { globalBasePath } from '../clusterPaths.js';
+import { callPageSchema, tagFormActions, globalEditData, globalViewData, } from '../pageData.js';
+import { wantsJson, readFormBody, normalizeRedirect, splitMeta, forbidden, checkPolicy, policyAccess, handleFormState, handleFormWizard, handleFormCreateOption, handleFormMentions, sendRedirectResponse, } from './helpers.js';
+/**
+ * Register the per-Global routes — edit GET / POST, the four form-state
+ * companion endpoints (`_form/:formId/state` / `wizard` / `mentions` /
+ * `create-option`), and the optional view route.
+ *
+ * Pulled out of `registerPilotiqRoutes` in 2026-05-12 (Phase 3 of the
+ * routes.ts split). Called once per `cfg.globals` entry.
+ */
+export function registerGlobalRoutes(router, pilotiq, G, base) {
+    const slug = G.getSlug();
+    const editUrl = globalBasePath(base, G);
+    const pages = G.resolvePages();
+    if (pages.edit) {
+        const PageClass = pages.edit;
+        // Plan #5 partial-resolve endpoint for the global's edit form.
+        // POST ${editUrl}/_form/:formId/state
+        router.post(`${editUrl}/_form/:formId/state`, async (req, res) => {
+            const user = await pilotiq.resolveUser(req);
+            if (!await policyAccess(G, user))
+                return forbidden(res, true);
+            if (!await checkPolicy(() => G.canEdit(user, undefined)))
+                return forbidden(res, true);
+            const formId = req.params['formId'];
+            return handleFormState(req, res, pilotiq, { kind: 'global-edit', slug }, formId);
+        });
+        // Plan #8 wizard step-validate endpoint for the global's edit form.
+        router.post(`${editUrl}/_form/:formId/wizard`, async (req, res) => {
+            const user = await pilotiq.resolveUser(req);
+            if (!await policyAccess(G, user))
+                return forbidden(res, true);
+            if (!await checkPolicy(() => G.canEdit(user, undefined)))
+                return forbidden(res, true);
+            const formId = req.params['formId'];
+            return handleFormWizard(req, res, pilotiq, { kind: 'global-edit', slug }, formId);
+        });
+        // Async-mention endpoint for the global's edit form.
+        router.post(`${editUrl}/_form/:formId/mentions`, async (req, res) => {
+            const user = await pilotiq.resolveUser(req);
+            if (!await policyAccess(G, user))
+                return forbidden(res, true);
+            if (!await checkPolicy(() => G.canEdit(user, undefined)))
+                return forbidden(res, true);
+            const formId = req.params['formId'];
+            return handleFormMentions(req, res, pilotiq, { kind: 'global-edit', slug }, formId);
+        });
+        // SelectField inline-create modal endpoint for the global's edit form.
+        router.post(`${editUrl}/_form/:formId/create-option/:fieldName`, async (req, res) => {
+            const user = await pilotiq.resolveUser(req);
+            if (!await policyAccess(G, user))
+                return forbidden(res, true);
+            if (!await checkPolicy(() => G.canEdit(user, undefined)))
+                return forbidden(res, true);
+            const formId = req.params['formId'];
+            const fieldName = req.params['fieldName'];
+            return handleFormCreateOption(req, res, pilotiq, { kind: 'global-edit', slug }, formId, fieldName);
+        });
+        router.get(editUrl, async (req, res) => {
+            const user = await pilotiq.resolveUser(req);
+            if (!await policyAccess(G, user))
+                return forbidden(res, wantsJson(req));
+            // Globals carry their record on the singleton form's `loadRecord`;
+            // we don't pre-load here — pass a stub so canEdit's signature is
+            // honored, and let user code decide whether to consult it.
+            if (!await checkPolicy(() => G.canEdit(user, undefined)))
+                return forbidden(res, wantsJson(req));
+            const data = await globalEditData(pilotiq, slug, undefined, req);
+            return view('pilotiq.slug', data ?? {});
+        });
+        router.post(editUrl, async (req, res) => {
+            const body = await readFormBody(req);
+            const { values, formId } = splitMeta(body);
+            const json = wantsJson(req);
+            const user = await pilotiq.resolveUser(req);
+            if (!await policyAccess(G, user))
+                return forbidden(res, json);
+            if (!await checkPolicy(() => G.canEdit(user, undefined)))
+                return forbidden(res, json);
+            const ctx = { mode: 'edit', basePath: base, ...(user !== null ? { user: user } : {}) };
+            const elements = await callPageSchema(PageClass, ctx);
+            tagFormActions(elements, editUrl);
+            const form = selectForm(findForms(elements), formId);
+            if (!form) {
+                if (json) {
+                    res.status(404);
+                    return res.json({ ok: false, error: 'No form found on page' });
+                }
+                res.status(404);
+                return res.send('No form found on page');
+            }
+            // Provide the existing singleton record to the lifecycle context
+            // so cross-field validators / mutateData see prior state.
+            let record = undefined;
+            if (form.getLoadRecord()) {
+                try {
+                    record = await form.getLoadRecord()('', { values });
+                }
+                catch { /* ignore */ }
+            }
+            const result = await dispatchFormSubmit(form, values, record !== undefined ? { values, record, basePath: base } : { values, basePath: base });
+            if (!result.ok) {
+                if (json) {
+                    res.status(422);
+                    return res.json({ ok: false, errors: result.errors });
+                }
+                const data = await globalEditData(pilotiq, slug, { values, errors: result.errors });
+                res.status(422);
+                return view('pilotiq.slug', data ?? {});
+            }
+            const redirect = normalizeRedirect(result.redirect, base) ?? editUrl;
+            return sendRedirectResponse(req, res, json, redirect, result.notifications);
+        });
+    }
+    // Optional view page when the user opts in via pages().view
+    if (pages.view) {
+        router.get(`${editUrl}/view`, async (req, res) => {
+            const user = await pilotiq.resolveUser(req);
+            if (!await policyAccess(G, user))
+                return forbidden(res, wantsJson(req));
+            if (!await checkPolicy(() => G.canView(user, undefined)))
+                return forbidden(res, wantsJson(req));
+            const data = await globalViewData(pilotiq, slug, req);
+            return view('pilotiq.resource-view', data ?? {});
+        });
+    }
+}
+//# sourceMappingURL=globals.js.map

package/dist/routes/globals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"globals.js","sourceRoot":"","sources":["../../src/routes/globals.ts"],"names":[],"mappings":"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"}

package/dist/routes/helpers.d.ts

@@ -0,0 +1,217 @@
+import type { AppRequest, AppResponse } from '@rudderjs/contracts';
+import type { Pilotiq } from '../Pilotiq.js';
+import { type DispatchActionResult } from '../elements/dispatchAction.js';
+import type { NotificationMeta } from '../notifications/Notification.js';
+import { type ModelQuery } from '../orm/modelDefaults.js';
+import type { ResourceClass } from '../Resource.js';
+import { type FormStateScope, type WidgetScope } from '../pageData.js';
+/** True when the client wants a JSON response (modal-form action submitting
+ * via fetch), false for a browser-style form post that wants a 303 redirect.
+ * Both action endpoints honor this so confirm/handler buttons (form-post)
+ * keep working unchanged while modal dialogs use fetch. */
+export declare function wantsJson(req: AppRequest): boolean;
+/**
+ * Read the request body as a `Record<string, unknown>`. The hono adapter
+ * auto-parses JSON, but `application/x-www-form-urlencoded` and
+ * `multipart/form-data` need a manual fall-through to Hono's own parser.
+ */
+export declare function readFormBody(req: AppRequest): Promise<Record<string, unknown>>;
+/**
+ * Normalize a user-supplied redirect URL. Returns absolute URLs and
+ * scheme-prefixed URLs unchanged. Bare relative paths (no leading `/`)
+ * are joined under the panel's `basePath` — without this, the browser
+ * resolves the redirect against the current request URL and produces
+ * paths like `/admin/articles/{id}/articles/{id}/edit`.
+ *
+ * `getRedirectUrl` page hooks and `Form.redirectAfterSave` callbacks
+ * are user-authored; this protects the framework against the common
+ * authoring slip while keeping absolute URLs (the documented form)
+ * working as-is.
+ */
+export declare function normalizeRedirect(url: string | undefined, basePath: string): string | undefined;
+/** Strip framework meta keys (`_formId`, `_method`, `_continueCreate`)
+ * from a parsed body. `continueCreate` mirrors the secondary
+ * "Create & create another" submit on `CreatePage`: when `'1'`, the
+ * create POST handler routes the redirect back to the create URL
+ * instead of the new record's edit page. */
+export declare function splitMeta(body: Record<string, unknown>): {
+    values: Record<string, unknown>;
+    formId: string | undefined;
+    continueCreate: boolean;
+};
+/** Strip control characters (`"\\\r\n`) from a download filename so
+ *  the `Content-Disposition: attachment; filename="…"` header stays
+ *  unbreakable. Defends against a handler that returns a hostile
+ *  filename string. Empty fallback `'export'`. */
+export declare function sanitizeFilename(name: string): string;
+/** Write an `Action`-handler download envelope as the response. Sets
+ *  `Content-Type` + `Content-Disposition: attachment` and ends with
+ *  the body. Mutually exclusive with redirect — call sites consult
+ *  `result.download` first. */
+export declare function sendDownload(res: AppResponse, env: {
+    filename: string;
+    contentType: string;
+    body: string;
+}): void;
+/** Low-level success-or-redirect responder. Either emits a JSON envelope
+ *  (`{ ok: true, redirect, notifications?, force? }`) when the client
+ *  asked for JSON, or flashes notifications to the next request and
+ *  issues a 303 redirect. Shared by `sendActionResult`,
+ *  `sendMutationSuccess`, and the form-submit success branches in
+ *  resources / globals / pages / relations. */
+export declare function sendRedirectResponse(req: AppRequest, res: AppResponse, json: boolean, redirect: string, notifications: ReadonlyArray<NotificationMeta> | undefined, extras?: {
+    force?: boolean;
+}): unknown;
+/** Action-dispatch result responder. Branches on `result.ok` / download
+ *  envelope / redirect. Consumed by every `_action/:actionName` endpoint
+ *  in resources / pages / relations.
+ *
+ *  - `!result.ok` → 422 (with `errors`) or 500 (`error` only). JSON path
+ *    returns `{ ok: false, error, errors? }`; HTML path sends `error`.
+ *  - `result.download` → calls `sendDownload` (mutually exclusive with
+ *    `redirect`; binary response has no JSON envelope to carry
+ *    notifications).
+ *  - otherwise → `sendRedirectResponse` with the normalized redirect
+ *    (defaulting to `fallbackUrl`) and `result.notifications`. */
+export declare function sendActionResult(req: AppRequest, res: AppResponse, json: boolean, result: DispatchActionResult, base: string, fallbackUrl: string): unknown;
+/** Synthetic-notification mutation responder for delete / restore /
+ *  force-delete / detach routes. The form-method 303 path doesn't have
+ *  the form-lifecycle toast pipeline; this synthesizes one
+ *  notification so the SPA path gets the same toast UX as a JSON-
+ *  dispatched action handler. `kind` becomes part of the notification
+ *  id (`n-${kind}-${id}-${Date.now()}`) so the client can dedupe. */
+export declare function sendMutationSuccess(req: AppRequest, res: AppResponse, json: boolean, opts: {
+    id: string;
+    kind: string;
+    title: string;
+    redirect: string;
+}): unknown;
+/** Soft-delete record lookup. Runs `q.withTrashed().where(pk, '=', id)
+ *  .paginate(1, 1)` and returns the first row, or `undefined` when the
+ *  query has no `withTrashed()` method (caller falls back to a normal
+ *  `M.find(id)` or returns 404). `.catch(...)` swallows the paginate
+ *  error so a bad query shape surfaces as "not found" rather than a
+ *  500. */
+export declare function findInQueryWithTrashed(q: ModelQuery, pk: string, id: string): Promise<unknown>;
+/** Plan #10 — send a 403 response. Branches on `Accept: application/json`
+ * the same way the action / form dispatch paths do. Used by every route
+ * after a `Resource.canX(...)` check fails. We deliberately do NOT
+ * redirect to login: 403 means "authenticated but not allowed"; the
+ * 401-unauthenticated case is `Pilotiq.guard()`'s job. */
+export declare function forbidden(res: AppResponse, json: boolean): unknown;
+/** Extract a user-facing message from a thrown value inside an editable
+ *  column's beforeStateUpdated / afterStateUpdated hook. Stamped under
+ *  the reserved `_cell` key in the 422 response. */
+export declare function cellHookErrorMessage(err: unknown): string;
+/** Run a `canX(...)` predicate, treating throws as `false`. The predicate
+ * is user-authored and we want a flaky check to fail closed (deny) rather
+ * than 500 the page. */
+export declare function checkPolicy(fn: () => boolean | Promise<boolean>): Promise<boolean>;
+export declare function policyAccess(owner: {
+    canAccess: (user: unknown) => boolean | Promise<boolean>;
+    cluster?: {
+        canAccess: (user: unknown) => boolean | Promise<boolean>;
+    };
+}, user: unknown): Promise<boolean>;
+/** Run `policyAccess(R, user)` and `findRecord(R, recordId, { user })`
+ *  in parallel. Both depend only on `user`, so the two round-trips
+ *  overlap instead of waiting on each other. When `R.model` isn't set
+ *  the record falls back to a stub `{ id: recordId }` so record-aware
+ *  predicates can still pattern-match. Throws are caught — a failed
+ *  record load resolves to `undefined`, mirroring the pre-helper inline
+ *  shape `findRecord(...).catch(() => undefined)`. */
+export declare function loadAccessGated(R: ResourceClass, recordId: string, user: unknown): Promise<{
+    access: boolean;
+    record: unknown;
+}>;
+/**
+ * Locate an action by name in a resolved page schema. Looks at both
+ * page-level actions (`findActions`) AND row-scoped extraItemActions on
+ * Repeater/Builder fields (`findRowExtraActions`). When the match is
+ * row-scoped, also returns the parent field reference and the form
+ * schema array — the dispatcher uses both to coerce the form body and
+ * navigate to the right row when stamping `ctx.row`.
+ *
+ * Page-level matches win when a page-level + row-scoped action share the
+ * same name (page-level is strictly more privileged: it has access to
+ * the full form, not just one row). The collision is undocumented
+ * behavior — authors should use distinct names.
+ */
+export declare function resolveDispatchTarget(elements: import('../schema/Element.js').Element[], actionName: string): {
+    action: import('../actions/Action.js').Action;
+    rowField?: import('../fields/RepeaterField.js').RepeaterField | import('../fields/BuilderField.js').BuilderField;
+    formSchema?: import('../schema/Element.js').Element[];
+} | null;
+/**
+ * Plan #5 — handle a partial-resolve POST. The body shape is
+ * `{ changed, values }`; `formId` comes from the URL path. Response
+ * is `{ ok, form, dirty }` on success or `{ ok: false, error }` for
+ * missing form / unknown field.
+ */
+export interface FormStateBody {
+    changed?: unknown;
+    values?: unknown;
+}
+export declare function handleFormState(req: AppRequest, res: AppResponse, pilotiq: Pilotiq, scope: FormStateScope, formId: string): Promise<unknown>;
+export interface FormWizardBody {
+    step?: unknown;
+    values?: unknown;
+}
+export declare function handleFormWizard(req: AppRequest, res: AppResponse, pilotiq: Pilotiq, scope: FormStateScope, formId: string): Promise<unknown>;
+/**
+ * Audit row 2026-05-07 cont'd⁸ — `SelectField.createOptionForm()` modal
+ * submit. Body carries `{ values }`; `formId` + `fieldName` come from
+ * the URL path. Returns `{ ok, option: { value, label } }` on success
+ * or `{ ok: false, error }` for missing scope / form / field, 403 for
+ * authorize failure, or 422 with `errors` for validation.
+ *
+ * One handler shared across all four scopes (resource-create /
+ * resource-edit / global-edit / custom-page) — caller passes the
+ * matching `FormStateScope` so the same `canAccess + canCreate / canEdit`
+ * predicates apply to the parent form's policy gate.
+ */
+export interface FormCreateOptionBody {
+    values?: unknown;
+}
+export declare function handleFormCreateOption(req: AppRequest, res: AppResponse, pilotiq: Pilotiq, scope: FormStateScope, formId: string, fieldName: string): Promise<unknown>;
+/**
+ * Async-mention round-trip handler. Body is `{ field, trigger, query }`;
+ * `formId` comes from the URL path. Returns `{ ok, items }` on success
+ * or `{ ok: false, error }` for missing form / field / trigger.
+ *
+ * Each scope (resource-create, resource-edit, global-edit, custom-page)
+ * registers its own route — the auth gate matches the matching `_form/
+ * :formId/state` endpoint so the same `canAccess + canCreate / canEdit`
+ * predicates apply.
+ */
+export interface FormMentionsBody {
+    field?: unknown;
+    trigger?: unknown;
+    query?: unknown;
+}
+export declare function handleFormMentions(req: AppRequest, res: AppResponse, pilotiq: Pilotiq, scope: FormStateScope, formId: string): Promise<unknown>;
+/**
+ * Plan #15 — handle a widget polling POST. Body is `{ filter? }`;
+ * `:id` comes from the URL. Returns `{ ok, data, timestamp }` on
+ * success or `{ ok: false, error }` on failure. Used by lazy-loading
+ * widgets (first fetch on mount) and `poll(seconds)` widgets (interval
+ * re-fetch).
+ */
+export interface WidgetBody {
+    filter?: unknown;
+}
+export declare function handleWidgetData(req: AppRequest, res: AppResponse, pilotiq: Pilotiq, scope: WidgetScope, id: string): Promise<unknown>;
+/**
+ * Handle a single file upload from a `FileUpload` field. Validates
+ * accept / maxSize against the (optional) per-request hints, hands
+ * the file off to the configured adapter, returns `{ ok, url }`.
+ *
+ * Body shape (multipart/form-data):
+ *   - `file`: the file blob
+ *   - `directory`: optional sub-directory hint
+ *   - `accept`: optional comma-separated MIME list to enforce
+ *   - `maxSize`: optional byte cap
+ *   - `fieldName`: optional tag forwarded to the adapter for routing
+ */
+export declare function handleUploadRequest(req: AppRequest, res: AppResponse, pilotiq: Pilotiq): Promise<unknown>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/routes/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/routes/helpers.ts"],"names":[],"mappings":"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"}