@objectstack/rest 11.4.0 → 11.5.0

package/dist/index.js

@@ -211,6 +211,503 @@ var RouteGroupBuilder = class {
   }
 };
 
+// src/export-format.ts
+var REFERENCE_TYPES = /* @__PURE__ */ new Set(["lookup", "master_detail", "user", "reference", "tree"]);
+var OPTION_TYPES = /* @__PURE__ */ new Set(["select", "radio"]);
+var MULTI_OPTION_TYPES = /* @__PURE__ */ new Set(["multiselect", "checkboxes", "tags"]);
+var NAME_KEY_FALLBACKS = [
+  "name",
+  "title",
+  "label",
+  "full_name",
+  "fullName",
+  "display_name",
+  "username",
+  "email"
+];
+function buildFieldMetaMap(schema) {
+  const map = /* @__PURE__ */ new Map();
+  const fields = schema?.fields;
+  let entries;
+  if (Array.isArray(fields)) {
+    entries = fields.filter((f) => f && typeof f === "object").map((f) => [typeof f.name === "string" ? f.name : "", f]);
+  } else if (fields && typeof fields === "object") {
+    entries = Object.entries(fields).map(
+      ([key, def]) => [
+        def && typeof def === "object" && typeof def.name === "string" ? def.name : key,
+        def
+      ]
+    );
+  } else {
+    return map;
+  }
+  for (const [name, f] of entries) {
+    if (!name || !f || typeof f !== "object") continue;
+    map.set(name, {
+      name,
+      type: typeof f.type === "string" ? f.type : void 0,
+      label: typeof f.label === "string" ? f.label : void 0,
+      options: Array.isArray(f.options) ? f.options : void 0,
+      reference: typeof f.reference === "string" ? f.reference : void 0,
+      displayField: typeof f.displayField === "string" ? f.displayField : void 0
+    });
+  }
+  return map;
+}
+function referenceFieldNames(metaMap) {
+  const out = [];
+  for (const meta of metaMap.values()) {
+    if (meta.type && REFERENCE_TYPES.has(meta.type) && meta.reference) out.push(meta.name);
+  }
+  return out;
+}
+function headerLabel(field, metaMap) {
+  return metaMap.get(field)?.label || field;
+}
+function pad2(n) {
+  return n < 10 ? `0${n}` : String(n);
+}
+function toDate(value) {
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value;
+  if (typeof value === "number" || typeof value === "string") {
+    const d = new Date(value);
+    return Number.isNaN(d.getTime()) ? null : d;
+  }
+  return null;
+}
+function formatDate(value, withTime) {
+  const d = toDate(value);
+  if (!d) return value;
+  const ymd = `${d.getUTCFullYear()}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())}`;
+  if (!withTime) return ymd;
+  return `${ymd} ${pad2(d.getUTCHours())}:${pad2(d.getUTCMinutes())}:${pad2(d.getUTCSeconds())}`;
+}
+function optionLabel(value, options) {
+  if (!options) return value;
+  const hit = options.find((o) => o && o.value === value);
+  return hit?.label ?? value;
+}
+function displayFromRecord(rec, displayField) {
+  if (displayField && rec[displayField] != null) return String(rec[displayField]);
+  for (const k of NAME_KEY_FALLBACKS) {
+    const v = rec[k];
+    if (v != null && typeof v !== "object") return String(v);
+  }
+  if (rec.id != null) return String(rec.id);
+  try {
+    return JSON.stringify(rec);
+  } catch {
+    return String(rec);
+  }
+}
+function formatReference(value, displayField) {
+  const one = (v) => v && typeof v === "object" ? displayFromRecord(v, displayField) : v;
+  if (Array.isArray(value)) return value.map(one).join(", ");
+  return one(value);
+}
+function formatCellValue(value, meta) {
+  if (value === null || value === void 0) return value;
+  if (!meta || !meta.type) return value;
+  const t = meta.type;
+  if (t === "boolean" || t === "toggle") {
+    if (value === true || value === "true" || value === 1) return "\u662F";
+    if (value === false || value === "false" || value === 0) return "\u5426";
+    return value;
+  }
+  if (OPTION_TYPES.has(t)) return optionLabel(value, meta.options);
+  if (MULTI_OPTION_TYPES.has(t)) {
+    const arr = Array.isArray(value) ? value : [value];
+    return arr.map((v) => optionLabel(v, meta.options)).join(", ");
+  }
+  if (t === "date") return formatDate(value, false);
+  if (t === "datetime") return formatDate(value, true);
+  if (REFERENCE_TYPES.has(t)) return formatReference(value, meta.displayField);
+  return value;
+}
+function formatRowCells(row, fields, metaMap) {
+  return fields.map((f) => formatCellValue(row?.[f], metaMap.get(f)));
+}
+function formatRowForJson(row, metaMap) {
+  if (metaMap.size === 0 || !row || typeof row !== "object") return row;
+  let copy = null;
+  for (const key of Object.keys(row)) {
+    const meta = metaMap.get(key);
+    if (!meta) continue;
+    const formatted = formatCellValue(row[key], meta);
+    if (formatted !== row[key]) {
+      if (!copy) copy = { ...row };
+      copy[key] = formatted;
+    }
+  }
+  return copy ?? row;
+}
+
+// src/import-coerce.ts
+var REFERENCE_TYPES2 = /* @__PURE__ */ new Set(["lookup", "master_detail", "user", "reference", "tree"]);
+var OPTION_TYPES2 = /* @__PURE__ */ new Set(["select", "radio"]);
+var MULTI_OPTION_TYPES2 = /* @__PURE__ */ new Set(["multiselect", "checkboxes", "tags"]);
+var NUMBER_TYPES = /* @__PURE__ */ new Set(["number", "currency", "percent", "rating", "slider"]);
+var BOOL_TYPES = /* @__PURE__ */ new Set(["boolean", "toggle"]);
+function normalizeRefMatch(result) {
+  if (result == null) return {};
+  if (typeof result === "string") return result ? { id: result } : {};
+  return result;
+}
+function isBlank(value, nullValues) {
+  if (value === null || value === void 0) return true;
+  if (typeof value === "string") {
+    const s = value.trim();
+    if (s === "") return true;
+    if (nullValues && nullValues.some((nv) => nv === value || nv === s)) return true;
+  }
+  return false;
+}
+var BOOL_TRUE = /* @__PURE__ */ new Set(["true", "t", "yes", "y", "1", "on", "\u662F", "\u5BF9", "\u2713", "\u221A"]);
+var BOOL_FALSE = /* @__PURE__ */ new Set(["false", "f", "no", "n", "0", "off", "\u5426", "\u9519", "\u2717", "\xD7"]);
+function parseBooleanCell(raw) {
+  if (typeof raw === "boolean") return raw;
+  if (typeof raw === "number") {
+    if (raw === 1) return true;
+    if (raw === 0) return false;
+    return void 0;
+  }
+  const s = String(raw).trim().toLowerCase();
+  if (BOOL_TRUE.has(s)) return true;
+  if (BOOL_FALSE.has(s)) return false;
+  return void 0;
+}
+function parseNumberCell(raw) {
+  if (typeof raw === "number") return Number.isFinite(raw) ? raw : void 0;
+  let s = String(raw).trim();
+  if (s === "") return void 0;
+  let negative = false;
+  if (/^\(.*\)$/.test(s)) {
+    negative = true;
+    s = s.slice(1, -1).trim();
+  }
+  s = s.replace(/^[$¥€£￥]\s*/, "");
+  s = s.replace(/%$/, "").trim();
+  s = s.replace(/,/g, "");
+  if (s === "" || !/^[+-]?\d*\.?\d+(e[+-]?\d+)?$/i.test(s)) return void 0;
+  const n = Number(s);
+  if (!Number.isFinite(n)) return void 0;
+  return negative ? -n : n;
+}
+function pad22(n) {
+  return n < 10 ? `0${n}` : String(n);
+}
+var TIME_OF_DAY = /^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d)?$/;
+function parseDateCell(raw, kind) {
+  if (raw instanceof Date) {
+    if (Number.isNaN(raw.getTime())) return void 0;
+    if (kind === "datetime") return raw.toISOString();
+    if (kind === "date") return `${raw.getUTCFullYear()}-${pad22(raw.getUTCMonth() + 1)}-${pad22(raw.getUTCDate())}`;
+    return `${pad22(raw.getUTCHours())}:${pad22(raw.getUTCMinutes())}:${pad22(raw.getUTCSeconds())}`;
+  }
+  const s = String(raw).trim();
+  if (s === "") return void 0;
+  if (kind === "time") {
+    if (TIME_OF_DAY.test(s)) return s.length === 5 ? `${s}:00` : s;
+    const t = new Date(s);
+    if (!Number.isNaN(t.getTime())) return `${pad22(t.getUTCHours())}:${pad22(t.getUTCMinutes())}:${pad22(t.getUTCSeconds())}`;
+    return void 0;
+  }
+  const ymd = s.match(/^(\d{4})[-/](\d{1,2})[-/](\d{1,2})$/);
+  if (ymd) {
+    const y = Number(ymd[1]);
+    const mo = Number(ymd[2]);
+    const d = Number(ymd[3]);
+    if (mo < 1 || mo > 12 || d < 1 || d > 31) return void 0;
+    if (kind === "date") return `${y}-${pad22(mo)}-${pad22(d)}`;
+    return new Date(Date.UTC(y, mo - 1, d)).toISOString();
+  }
+  const parsed = new Date(s);
+  if (Number.isNaN(parsed.getTime())) return void 0;
+  if (kind === "date") {
+    return `${parsed.getUTCFullYear()}-${pad22(parsed.getUTCMonth() + 1)}-${pad22(parsed.getUTCDate())}`;
+  }
+  return parsed.toISOString();
+}
+function matchOption(raw, options) {
+  const s = String(raw).trim();
+  if (!options || options.length === 0) return s;
+  for (const o of options) {
+    if (o && o.value !== void 0 && String(o.value) === s) return o.value;
+  }
+  const lower = s.toLowerCase();
+  for (const o of options) {
+    if (o && typeof o.label === "string" && o.label.trim().toLowerCase() === lower) return o.value;
+  }
+  return void 0;
+}
+function splitMulti(raw) {
+  if (Array.isArray(raw)) return raw.map((v) => String(v).trim()).filter((v) => v !== "");
+  return String(raw).split(/[,;、\n]/).map((v) => v.trim()).filter((v) => v !== "");
+}
+async function coerceFieldValue(raw, meta, ctx) {
+  const trim = ctx.trimWhitespace !== false;
+  const field = meta?.name ?? "";
+  if (isBlank(raw, ctx.nullValues)) return { value: void 0 };
+  const t = meta?.type;
+  if (!t) return { value: trim && typeof raw === "string" ? raw.trim() : raw };
+  if (BOOL_TYPES.has(t)) {
+    const b = parseBooleanCell(raw);
+    if (b === void 0) return { error: { field, code: "invalid_boolean", message: `${field}: "${String(raw)}" is not a boolean` } };
+    return { value: b };
+  }
+  if (NUMBER_TYPES.has(t)) {
+    const n = parseNumberCell(raw);
+    if (n === void 0) return { error: { field, code: "invalid_number", message: `${field}: "${String(raw)}" is not a number` } };
+    return { value: n };
+  }
+  if (t === "date" || t === "datetime" || t === "time") {
+    const d = parseDateCell(raw, t);
+    if (d === void 0) return { error: { field, code: "invalid_date", message: `${field}: "${String(raw)}" is not a valid ${t}` } };
+    return { value: d };
+  }
+  if (OPTION_TYPES2.has(t)) {
+    const v = matchOption(raw, meta?.options);
+    if (v === void 0) {
+      if (ctx.createMissingOptions) return { value: String(raw).trim() };
+      return { error: { field, code: "invalid_option", message: `${field}: "${String(raw)}" is not a known option` } };
+    }
+    return { value: v };
+  }
+  if (MULTI_OPTION_TYPES2.has(t)) {
+    const parts = splitMulti(raw);
+    const out = [];
+    for (const part of parts) {
+      const v = matchOption(part, meta?.options);
+      if (v === void 0) {
+        if (ctx.createMissingOptions) {
+          out.push(part);
+          continue;
+        }
+        return { error: { field, code: "invalid_option", message: `${field}: "${part}" is not a known option` } };
+      }
+      out.push(v);
+    }
+    return { value: out };
+  }
+  if (REFERENCE_TYPES2.has(t)) {
+    const display = String(raw).trim();
+    if (!ctx.resolveRef || !meta?.reference) return { value: display };
+    const match = normalizeRefMatch(await ctx.resolveRef(meta.reference, display, meta));
+    if (match.ambiguous) {
+      return { error: { field, code: "reference_ambiguous", message: `${field}: "${display}" matches more than one ${meta.reference} \u2014 use a unique value or the record id` } };
+    }
+    if (match.id === void 0) {
+      return { error: { field, code: "reference_not_found", message: `${field}: no ${meta.reference} matches "${display}"` } };
+    }
+    return { value: match.id };
+  }
+  return { value: trim && typeof raw === "string" ? raw.trim() : raw };
+}
+async function coerceRow(rawRow, metaMap, ctx) {
+  const data = {};
+  const errors = [];
+  for (const [key, raw] of Object.entries(rawRow)) {
+    const meta = metaMap.get(key);
+    const res = await coerceFieldValue(raw, meta ? meta : void 0, ctx);
+    if ("error" in res) {
+      errors.push({ ...res.error, field: res.error.field || key });
+      continue;
+    }
+    if (res.value !== void 0) data[key] = res.value;
+  }
+  return { data, errors };
+}
+
+// src/import-runner.ts
+function runImport(opts) {
+  const {
+    p,
+    objectName,
+    environmentId,
+    context,
+    rows,
+    metaMap,
+    writeMode,
+    matchFields,
+    dryRun,
+    runAutomations,
+    trimWhitespace,
+    nullValues,
+    createMissingOptions,
+    skipBlankMatchKey,
+    onProgress,
+    shouldCancel,
+    captureUndo
+  } = opts;
+  const collectUndo = !!captureUndo && !dryRun;
+  const undoLog = { created: [], updated: [] };
+  const captureBefore = (before, written) => {
+    const snap = {};
+    for (const k of Object.keys(written)) snap[k] = before[k] ?? null;
+    return snap;
+  };
+  const progressEvery = Math.max(1, opts.progressEvery ?? 200);
+  const findRows = (r) => Array.isArray(r?.records) ? r.records : Array.isArray(r?.data) ? r.data : Array.isArray(r?.rows) ? r.rows : Array.isArray(r) ? r : [];
+  const findArgsBase = (query) => ({
+    object: "",
+    query,
+    ...environmentId ? { environmentId } : {},
+    ...context ? { context } : {}
+  });
+  const refCache = /* @__PURE__ */ new Map();
+  const resolveRef = async (referenceObject, display, meta) => {
+    const cacheKey = `${referenceObject}::${display}`;
+    const cached = refCache.get(cacheKey);
+    if (cached) return cached;
+    const candidates = [.../* @__PURE__ */ new Set([
+      "id",
+      ...meta.displayField ? [meta.displayField] : [],
+      "name",
+      "title",
+      "label",
+      "full_name",
+      "email",
+      "username"
+    ])];
+    let match = {};
+    for (const f of candidates) {
+      try {
+        const r = await p.findData({
+          ...findArgsBase({ $filter: { [f]: display }, $top: 2 }),
+          object: referenceObject
+        });
+        const recs = findRows(r);
+        if (recs.length === 0) continue;
+        if (recs.length > 1) {
+          match = { ambiguous: true, matchedField: f };
+          break;
+        }
+        if (recs[0]?.id != null) {
+          match = { id: String(recs[0].id), matchedField: f };
+          break;
+        }
+      } catch {
+      }
+    }
+    refCache.set(cacheKey, match);
+    return match;
+  };
+  const findExisting = async (data) => {
+    const filter = {};
+    for (const f of matchFields) {
+      const v = data[f];
+      if (v === void 0 || v === null || v === "") return "blank";
+      filter[f] = v;
+    }
+    const r = await p.findData({ ...findArgsBase({ $filter: filter, $top: 2 }), object: objectName });
+    const recs = findRows(r);
+    if (recs.length === 0) return "none";
+    if (recs.length > 1) return "ambiguous";
+    return recs[0];
+  };
+  const writeCtx = { ...context ?? {}, skipAutomations: !runAutomations };
+  const results = [];
+  let okCount = 0, errCount = 0, created = 0, updated = 0, skipped = 0;
+  let cancelled = false;
+  const snapshot = (processed) => ({
+    processed,
+    total: rows.length,
+    created,
+    updated,
+    skipped,
+    errors: errCount
+  });
+  return (async () => {
+    for (let i = 0; i < rows.length; i++) {
+      const rowNo = i + 1;
+      try {
+        const { data, errors } = await coerceRow(rows[i], metaMap, {
+          trimWhitespace,
+          nullValues,
+          createMissingOptions,
+          resolveRef
+        });
+        if (errors.length > 0) {
+          const first = errors[0];
+          errCount++;
+          results.push({ row: rowNo, ok: false, action: "failed", field: first.field, code: first.code, error: first.message });
+        } else {
+          let existing = "none";
+          let handled = false;
+          if (writeMode !== "insert") {
+            existing = await findExisting(data);
+            if (existing === "ambiguous") {
+              errCount++;
+              results.push({ row: rowNo, ok: false, action: "failed", code: "AMBIGUOUS_MATCH", error: `matchFields matched more than one ${objectName} record` });
+              handled = true;
+            } else if (existing === "blank" && (skipBlankMatchKey || writeMode === "update")) {
+              skipped++;
+              results.push({ row: rowNo, ok: true, action: "skipped", code: "BLANK_MATCH_KEY" });
+              handled = true;
+            }
+          }
+          if (!handled) {
+            const willUpdate = existing && typeof existing === "object";
+            const willCreate = !willUpdate && (writeMode === "insert" || writeMode === "upsert");
+            if (!willUpdate && !willCreate) {
+              skipped++;
+              results.push({ row: rowNo, ok: true, action: "skipped", code: "NO_MATCH" });
+            } else if (dryRun) {
+              okCount++;
+              if (willUpdate) {
+                updated++;
+                results.push({ row: rowNo, ok: true, action: "updated", id: String(existing.id ?? "") || void 0 });
+              } else {
+                created++;
+                results.push({ row: rowNo, ok: true, action: "created" });
+              }
+            } else if (willUpdate) {
+              const target = existing;
+              const res2 = await p.updateData({ object: objectName, id: target.id, data, context: writeCtx, ...environmentId ? { environmentId } : {} });
+              const id = res2?.id ?? res2?.record?.id ?? target.id;
+              okCount++;
+              updated++;
+              if (collectUndo && target.id != null) {
+                undoLog.updated.push({ id: String(target.id), before: captureBefore(target, data) });
+              }
+              results.push({ row: rowNo, ok: true, action: "updated", id: id != null ? String(id) : void 0 });
+            } else {
+              const res2 = await p.createData({ object: objectName, data, context: writeCtx, ...environmentId ? { environmentId } : {} });
+              const id = res2?.id ?? res2?.record?.id;
+              okCount++;
+              created++;
+              if (collectUndo && id != null) undoLog.created.push(String(id));
+              results.push({ row: rowNo, ok: true, action: "created", id: id != null ? String(id) : void 0 });
+            }
+          }
+        }
+      } catch (err) {
+        errCount++;
+        const code = err?.code ?? "IMPORT_ROW_FAILED";
+        const message = typeof err?.message === "string" ? err.message.slice(0, 300) : "Row failed";
+        results.push({ row: rowNo, ok: false, action: "failed", error: message, code });
+      }
+      const processed = i + 1;
+      if (onProgress && (processed % progressEvery === 0 || processed === rows.length)) {
+        await onProgress(snapshot(processed));
+      }
+      if (shouldCancel && processed < rows.length && processed % progressEvery === 0) {
+        if (await shouldCancel()) {
+          cancelled = true;
+          break;
+        }
+      }
+    }
+    return {
+      ...snapshot(results.length),
+      ok: okCount,
+      results,
+      cancelled,
+      ...collectUndo ? { undoLog } : {}
+    };
+  })();
+}
+
 // src/rest-server.ts
 var logError = (...args) => globalThis.console?.error(...args);
 var TRANSLATABLE_META_TYPES = /* @__PURE__ */ new Set(["view", "action", "object", "app", "dashboard"]);
@@ -423,6 +920,212 @@ function parseCsvToRows(csv, mapping = {}) {
   }
   return out;
 }
+function xlsxCellToString(value) {
+  if (value === null || value === void 0) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "object") {
+    if ("result" in value && value.result !== void 0 && value.result !== null) return xlsxCellToString(value.result);
+    if ("text" in value && typeof value.text === "string") return value.text;
+    if ("hyperlink" in value && typeof value.hyperlink === "string") return value.hyperlink;
+    if (Array.isArray(value.richText)) return value.richText.map((r) => r?.text ?? "").join("");
+    if ("error" in value && value.error) return String(value.error);
+  }
+  try {
+    return String(value);
+  } catch {
+    return "";
+  }
+}
+async function parseXlsxToRows(buffer, mapping = {}, sheet) {
+  const ExcelJS = (await import("exceljs")).default ?? await import("exceljs");
+  const wb = new ExcelJS.Workbook();
+  await wb.xlsx.load(buffer);
+  const ws = sheet !== void 0 ? wb.getWorksheet(sheet) : wb.worksheets[0];
+  if (!ws) return [];
+  const cells = [];
+  ws.eachRow({ includeEmpty: false }, (row) => {
+    const values = row.values;
+    const line = [];
+    for (let c = 1; c < values.length; c++) line.push(xlsxCellToString(values[c]));
+    cells.push(line);
+  });
+  while (cells.length > 0 && cells[cells.length - 1].every((c) => c === "")) cells.pop();
+  if (cells.length < 2) return [];
+  const header = cells[0].map((h) => h.trim());
+  const fields = header.map((h) => mapping[h] ?? h);
+  const out = [];
+  for (let r = 1; r < cells.length; r++) {
+    const line = cells[r];
+    const obj = {};
+    for (let c = 0; c < fields.length; c++) {
+      const key = fields[c];
+      if (!key) continue;
+      obj[key] = line[c] ?? "";
+    }
+    out.push(obj);
+  }
+  return out;
+}
+async function prepareImportRequest(body, opts) {
+  const { p, objectName, environmentId, maxRows } = opts;
+  const dryRun = body?.dryRun === true;
+  const writeMode = body?.writeMode === "update" || body?.writeMode === "upsert" ? body.writeMode : "insert";
+  const matchFields = Array.isArray(body?.matchFields) ? body.matchFields.filter((f) => typeof f === "string" && f.length > 0) : [];
+  const runAutomations = body?.runAutomations === true;
+  const trimWhitespace = body?.trimWhitespace !== false;
+  const nullValues = Array.isArray(body?.nullValues) ? body.nullValues.filter((v) => typeof v === "string") : void 0;
+  const createMissingOptions = body?.createMissingOptions === true;
+  const skipBlankMatchKey = body?.skipBlankMatchKey === true;
+  if (writeMode !== "insert" && matchFields.length === 0) {
+    return { ok: false, status: 400, code: "INVALID_REQUEST", error: `writeMode "${writeMode}" requires a non-empty matchFields[]` };
+  }
+  const mapping = {};
+  if (Array.isArray(body?.mapping)) {
+    for (const e of body.mapping) {
+      if (e && typeof e.sourceField === "string" && typeof e.targetField === "string") {
+        mapping[e.sourceField] = e.targetField;
+      }
+    }
+  } else if (body?.mapping && typeof body.mapping === "object") {
+    for (const [k, v] of Object.entries(body.mapping)) {
+      if (typeof v === "string") mapping[k] = v;
+    }
+  }
+  const applyMapping = (row) => {
+    if (Object.keys(mapping).length === 0) return row;
+    const out = {};
+    for (const [k, val] of Object.entries(row)) out[mapping[k] ?? k] = val;
+    return out;
+  };
+  let rows = [];
+  if (body?.format === "json" && Array.isArray(body.rows)) {
+    rows = body.rows.map(applyMapping);
+  } else if ((body?.format === "csv" || typeof body?.csv === "string") && typeof body?.csv === "string") {
+    rows = parseCsvToRows(body.csv, mapping);
+  } else if ((body?.format === "xlsx" || typeof body?.xlsxBase64 === "string") && typeof body?.xlsxBase64 === "string") {
+    try {
+      const buf = Buffer.from(body.xlsxBase64, "base64");
+      rows = await parseXlsxToRows(buf, mapping, body.sheet);
+    } catch (e) {
+      return { ok: false, status: 400, code: "INVALID_REQUEST", error: `Failed to parse xlsx: ${e?.message ?? String(e)}` };
+    }
+  } else if (Array.isArray(body)) {
+    rows = body.map(applyMapping);
+  } else {
+    return { ok: false, status: 400, code: "INVALID_REQUEST", error: 'Provide format:"csv" with csv text, format:"json" with rows[], or format:"xlsx" with xlsxBase64' };
+  }
+  if (rows.length > maxRows) {
+    return { ok: false, status: 413, code: "PAYLOAD_TOO_LARGE", error: `Import limit is ${maxRows} rows per request (got ${rows.length}).` };
+  }
+  let metaMap = /* @__PURE__ */ new Map();
+  try {
+    let schema = void 0;
+    if (typeof p.getMetaItem === "function") {
+      const r = await p.getMetaItem({ type: "object", name: objectName });
+      schema = isMetaEnvelope(r) ? r.item : r;
+    }
+    if (!schema && typeof p.getObjectSchema === "function") {
+      schema = await p.getObjectSchema(objectName, environmentId);
+    }
+    metaMap = buildFieldMetaMap(schema);
+  } catch {
+  }
+  return {
+    ok: true,
+    prepared: {
+      rows,
+      metaMap,
+      writeMode,
+      matchFields,
+      dryRun,
+      runAutomations,
+      trimWhitespace,
+      nullValues,
+      createMissingOptions,
+      skipBlankMatchKey
+    }
+  };
+}
+var IMPORT_JOB_OBJECT = "sys_import_job";
+var IMPORT_JOB_MAX_ROWS = 5e4;
+var IMPORT_JOB_RESULTS_CAP = 500;
+var IMPORT_JOB_UNDO_MAX_ROWS = 5e3;
+function newImportJobId() {
+  return `imp_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+}
+function capImportResults(results) {
+  if (results.length <= IMPORT_JOB_RESULTS_CAP) return { items: results, truncated: false };
+  const failures = results.filter((r) => !r.ok);
+  const successes = results.filter((r) => r.ok);
+  const items = [...failures, ...successes].slice(0, IMPORT_JOB_RESULTS_CAP);
+  return { items, truncated: true };
+}
+function parseUndoLog(raw) {
+  if (!raw) return void 0;
+  let v = raw;
+  if (typeof v === "string") {
+    try {
+      v = JSON.parse(v);
+    } catch {
+      return void 0;
+    }
+  }
+  if (!v || typeof v !== "object") return void 0;
+  const created = Array.isArray(v.created) ? v.created.map(String) : [];
+  const updated = Array.isArray(v.updated) ? v.updated.filter((u) => u && u.id != null).map((u) => ({ id: String(u.id), before: u.before ?? {} })) : [];
+  return { created, updated };
+}
+function importJobUndoable(row) {
+  if (row?.reverted_at) return false;
+  const status = String(row?.status ?? "");
+  if (status !== "succeeded" && status !== "cancelled") return false;
+  const log = parseUndoLog(row?.undo_log);
+  return !!log && (log.created.length > 0 || log.updated.length > 0);
+}
+function importJobToProgress(row) {
+  const total = Number(row?.total_rows ?? 0);
+  const processed = Number(row?.processed_rows ?? 0);
+  return {
+    undoable: importJobUndoable(row),
+    ...row?.reverted_at ? { revertedAt: String(row.reverted_at) } : {},
+    jobId: String(row?.id ?? ""),
+    object: String(row?.object_name ?? ""),
+    status: String(row?.status ?? "pending"),
+    dryRun: !!row?.dry_run,
+    writeMode: String(row?.write_mode ?? "insert"),
+    total,
+    processed,
+    created: Number(row?.created_count ?? 0),
+    updated: Number(row?.updated_count ?? 0),
+    skipped: Number(row?.skipped_count ?? 0),
+    errors: Number(row?.error_count ?? 0),
+    percentComplete: total > 0 ? Math.min(100, Math.round(processed / total * 100)) : processed > 0 ? 100 : 0,
+    ...row?.error ? { error: String(row.error) } : {},
+    ...row?.started_at ? { startedAt: String(row.started_at) } : {},
+    ...row?.completed_at ? { completedAt: String(row.completed_at) } : {},
+    createdAt: String(row?.created_at ?? "")
+  };
+}
+function importJobToSummary(row) {
+  const p = importJobToProgress(row);
+  return {
+    jobId: p.jobId,
+    object: p.object,
+    status: p.status,
+    total: p.total,
+    processed: p.processed,
+    created: p.created,
+    updated: p.updated,
+    skipped: p.skipped,
+    errors: p.errors,
+    createdAt: p.createdAt,
+    undoable: p.undoable,
+    ...p.completedAt ? { completedAt: p.completedAt } : {},
+    ...p.revertedAt ? { revertedAt: p.revertedAt } : {}
+  };
+}
 function formatCsvCell(value) {
   if (value === null || value === void 0) return "";
   let s;
@@ -441,14 +1144,42 @@ function formatCsvCell(value) {
   }
   return s;
 }
-function rowsToCsv(fields, rows, includeHeader) {
+function rowsToCsv(fields, rows, includeHeader, metaMap) {
   const lines = [];
-  if (includeHeader) lines.push(fields.map(formatCsvCell).join(","));
+  if (includeHeader) lines.push(fields.map((f) => formatCsvCell(headerLabel(f, metaMap))).join(","));
   for (const row of rows) {
-    lines.push(fields.map((f) => formatCsvCell(row?.[f])).join(","));
+    lines.push(formatRowCells(row, fields, metaMap).map(formatCsvCell).join(","));
   }
   return lines.join("\r\n") + (lines.length > 0 ? "\r\n" : "");
 }
+async function createXlsxStream(res) {
+  const { PassThrough } = await import("stream");
+  const ExcelJS = (await import("exceljs")).default ?? await import("exceljs");
+  const passthrough = new PassThrough();
+  const done = new Promise((resolve, reject) => {
+    passthrough.on("data", (chunk) => {
+      res.write(chunk);
+    });
+    passthrough.on("end", () => {
+      try {
+        res.end();
+      } catch {
+      }
+      resolve();
+    });
+    passthrough.on("error", reject);
+  });
+  const wb = new ExcelJS.stream.xlsx.WorkbookWriter({ stream: passthrough, useStyles: false });
+  const ws = wb.addWorksheet("Export");
+  return {
+    ws,
+    finalize: async () => {
+      await ws.commit();
+      await wb.commit();
+      await done;
+    }
+  };
+}
 var RestServer = class {
   constructor(server, protocol, config = {}, kernelManager, envRegistry, defaultEnvironmentIdProvider, authServiceProvider, objectQLProvider, emailServiceProvider, sharingServiceProvider, reportsServiceProvider, approvalsServiceProvider, sharingRulesServiceProvider, i18nServiceProvider, analyticsServiceProvider, settingsServiceProvider, serviceExistsProvider) {
     /**
@@ -473,6 +1204,13 @@ var RestServer = class {
      * in-flight Promise so concurrent callers share one resolution.
      */
     this.execCtxMemo = /* @__PURE__ */ new WeakMap();
+    /**
+     * In-flight async import jobs the caller has asked to cancel. The worker
+     * checks membership at each progress boundary and stops cooperatively. This
+     * is process-local (single-node); the persisted `sys_import_job.status` is
+     * the durable source of truth a restarted/other node reads.
+     */
+    this.cancelledImportJobs = /* @__PURE__ */ new Set();
     /**
      * Lazily load the OpenAPI spec JSON shipped by @objectstack/spec.
      * Cached after first read. Resilient to missing files / parse errors
@@ -2467,63 +3205,31 @@ var RestServer = class {
           }
           if (await this.enforceApiAccess(req, res, p, environmentId, "import")) return;
           const body = req.body ?? {};
-          const dryRun = body.dryRun === true;
-          const mapping = body.mapping ?? {};
-          let rows = [];
-          if (body.format === "json" && Array.isArray(body.rows)) {
-            rows = body.rows;
-          } else if ((body.format === "csv" || typeof body.csv === "string") && typeof body.csv === "string") {
-            rows = parseCsvToRows(body.csv, mapping);
-          } else if (Array.isArray(body)) {
-            rows = body;
-          } else {
-            res.status(400).json({
-              code: "INVALID_REQUEST",
-              error: 'Provide either format:"csv" with csv text or format:"json" with rows[]'
-            });
+          const prep = await prepareImportRequest(body, { p, objectName, environmentId, maxRows: 5e3 });
+          if (!prep.ok) {
+            if (prep.status === 413) prep.error += " Use an async import job for larger files.";
+            res.status(prep.status).json({ code: prep.code, error: prep.error });
             return;
           }
-          const max = 5e3;
-          if (rows.length > max) {
-            res.status(413).json({
-              code: "PAYLOAD_TOO_LARGE",
-              error: `Import limit is ${max} rows per request (got ${rows.length})`
-            });
-            return;
-          }
-          const results = [];
-          let okCount = 0;
-          let errCount = 0;
-          for (let i = 0; i < rows.length; i++) {
-            const data = rows[i];
-            try {
-              if (dryRun) {
-                const validate = p.validate;
-                if (typeof validate === "function") {
-                  await validate.call(p, { object: objectName, data, context });
-                }
-                results.push({ row: i + 1, ok: true });
-                okCount++;
-              } else {
-                const created = await p.createData({ object: objectName, data, context });
-                const id = created?.id ?? created?.record?.id;
-                results.push({ row: i + 1, ok: true, id });
-                okCount++;
-              }
-            } catch (err) {
-              errCount++;
-              const code = err?.code ?? "IMPORT_ROW_FAILED";
-              const message = typeof err?.message === "string" ? err.message.slice(0, 300) : "Row failed";
-              results.push({ row: i + 1, ok: false, error: message, code });
-            }
-          }
+          const { rows, writeMode, dryRun } = prep.prepared;
+          const summary = await runImport({
+            p,
+            objectName,
+            environmentId,
+            context,
+            ...prep.prepared
+          });
           res.json({
             object: objectName,
             dryRun,
+            writeMode,
             total: rows.length,
-            ok: okCount,
-            errors: errCount,
-            results
+            ok: summary.ok,
+            errors: summary.errors,
+            created: summary.created,
+            updated: summary.updated,
+            skipped: summary.skipped,
+            results: summary.results
           });
         } catch (error) {
           logError("[REST] Unhandled error:", error);
@@ -2535,6 +3241,291 @@ var RestServer = class {
         tags: ["data", "import"]
       }
     });
+    this.routeManager.register({
+      method: "POST",
+      path: `${dataPath}/:object/import/jobs`,
+      handler: async (req, res) => {
+        try {
+          const environmentId = isScoped ? req.params?.environmentId : void 0;
+          const p = await this.resolveProtocol(environmentId, req);
+          const context = await this.resolveExecCtx(environmentId, req);
+          if (this.enforceAuth(req, res, context)) return;
+          const objectName = String(req.params.object || "");
+          if (!objectName) {
+            res.status(400).json({ code: "INVALID_REQUEST", error: "object is required" });
+            return;
+          }
+          if (await this.enforceApiAccess(req, res, p, environmentId, "import")) return;
+          const prep = await prepareImportRequest(req.body ?? {}, { p, objectName, environmentId, maxRows: IMPORT_JOB_MAX_ROWS });
+          if (!prep.ok) {
+            if (prep.status === 413) prep.error += ` This is the async import ceiling; split the file into batches of ${IMPORT_JOB_MAX_ROWS}.`;
+            res.status(prep.status).json({ code: prep.code, error: prep.error });
+            return;
+          }
+          const prepared = prep.prepared;
+          const jobId = newImportJobId();
+          const createdAt = (/* @__PURE__ */ new Date()).toISOString();
+          const createdBy = String(context?.userId ?? context?.user?.id ?? "") || void 0;
+          const jobRow = {
+            id: jobId,
+            object_name: objectName,
+            status: "pending",
+            total_rows: prepared.rows.length,
+            processed_rows: 0,
+            created_count: 0,
+            updated_count: 0,
+            skipped_count: 0,
+            error_count: 0,
+            write_mode: prepared.writeMode,
+            dry_run: prepared.dryRun,
+            run_automations: prepared.runAutomations,
+            created_at: createdAt,
+            ...createdBy ? { created_by: createdBy } : {}
+          };
+          try {
+            await p.createData({ object: IMPORT_JOB_OBJECT, data: jobRow, context, ...environmentId ? { environmentId } : {} });
+          } catch (err) {
+            logError("[REST] Failed to persist import job:", err);
+            res.status(500).json({ code: "IMPORT_JOB_CREATE_FAILED", error: "Could not create import job" });
+            return;
+          }
+          res.status(201).json({ jobId, object: objectName, status: "pending", total: prepared.rows.length, createdAt });
+          const patch = async (data) => {
+            try {
+              await p.updateData({ object: IMPORT_JOB_OBJECT, id: jobId, data, context, ...environmentId ? { environmentId } : {} });
+            } catch (err) {
+              logError("[REST] import job progress write failed:", err);
+            }
+          };
+          const captureUndo = !prepared.dryRun && prepared.rows.length <= IMPORT_JOB_UNDO_MAX_ROWS;
+          void (async () => {
+            await patch({ status: "running", started_at: (/* @__PURE__ */ new Date()).toISOString() });
+            try {
+              const summary = await runImport({
+                p,
+                objectName,
+                environmentId,
+                context,
+                ...prepared,
+                captureUndo,
+                progressEvery: 200,
+                onProgress: (pr) => patch({
+                  processed_rows: pr.processed,
+                  created_count: pr.created,
+                  updated_count: pr.updated,
+                  skipped_count: pr.skipped,
+                  error_count: pr.errors
+                }),
+                shouldCancel: () => this.cancelledImportJobs.has(jobId)
+              });
+              await patch({
+                status: summary.cancelled ? "cancelled" : "succeeded",
+                processed_rows: summary.processed,
+                created_count: summary.created,
+                updated_count: summary.updated,
+                skipped_count: summary.skipped,
+                error_count: summary.errors,
+                results: capImportResults(summary.results),
+                completed_at: (/* @__PURE__ */ new Date()).toISOString(),
+                ...summary.undoLog ? { undo_log: summary.undoLog } : {}
+              });
+            } catch (err) {
+              await patch({
+                status: "failed",
+                error: String(err?.message ?? err).slice(0, 1e3),
+                completed_at: (/* @__PURE__ */ new Date()).toISOString()
+              });
+            } finally {
+              this.cancelledImportJobs.delete(jobId);
+            }
+          })();
+        } catch (error) {
+          logError("[REST] Unhandled error:", error);
+          sendError(res, error, String(req.params?.object || ""));
+        }
+      },
+      metadata: {
+        summary: "Create an asynchronous import job (large files, up to 50k rows)",
+        tags: ["data", "import"]
+      }
+    });
+    const loadImportJob = async (p, jobId, environmentId, context) => {
+      const r = await p.findData({
+        object: IMPORT_JOB_OBJECT,
+        query: { $filter: { id: jobId }, $top: 1 },
+        ...environmentId ? { environmentId } : {},
+        ...context ? { context } : {}
+      });
+      const rows = Array.isArray(r?.records) ? r.records : Array.isArray(r?.data) ? r.data : Array.isArray(r?.rows) ? r.rows : Array.isArray(r) ? r : [];
+      return rows[0];
+    };
+    this.routeManager.register({
+      method: "POST",
+      path: `${dataPath}/import/jobs/:jobId/cancel`,
+      handler: async (req, res) => {
+        try {
+          const environmentId = isScoped ? req.params?.environmentId : void 0;
+          const p = await this.resolveProtocol(environmentId, req);
+          const context = await this.resolveExecCtx(environmentId, req);
+          if (this.enforceAuth(req, res, context)) return;
+          const jobId = String(req.params.jobId || "");
+          const row = await loadImportJob(p, jobId, environmentId, context);
+          if (!row) {
+            res.status(404).json({ code: "NOT_FOUND", error: `No import job ${jobId}` });
+            return;
+          }
+          const status = String(row.status ?? "");
+          if (status === "pending" || status === "running") {
+            this.cancelledImportJobs.add(jobId);
+            try {
+              await p.updateData({ object: IMPORT_JOB_OBJECT, id: jobId, data: { status: "cancelled", completed_at: (/* @__PURE__ */ new Date()).toISOString() }, context, ...environmentId ? { environmentId } : {} });
+            } catch {
+            }
+          }
+          res.json({ success: true });
+        } catch (error) {
+          logError("[REST] Unhandled error:", error);
+          sendError(res, error, "");
+        }
+      },
+      metadata: { summary: "Cancel an in-flight import job", tags: ["data", "import"] }
+    });
+    this.routeManager.register({
+      method: "POST",
+      path: `${dataPath}/import/jobs/:jobId/undo`,
+      handler: async (req, res) => {
+        try {
+          const environmentId = isScoped ? req.params?.environmentId : void 0;
+          const p = await this.resolveProtocol(environmentId, req);
+          const context = await this.resolveExecCtx(environmentId, req);
+          if (this.enforceAuth(req, res, context)) return;
+          const jobId = String(req.params.jobId || "");
+          const row = await loadImportJob(p, jobId, environmentId, context);
+          if (!row) {
+            res.status(404).json({ code: "NOT_FOUND", error: `No import job ${jobId}` });
+            return;
+          }
+          if (row.reverted_at) {
+            res.status(409).json({ code: "ALREADY_REVERTED", error: "This import has already been undone" });
+            return;
+          }
+          if (!importJobUndoable(row)) {
+            res.status(422).json({ code: "NOT_UNDOABLE", error: "This import cannot be undone (too large, still running, or nothing was written)" });
+            return;
+          }
+          const objectName = String(row.object_name ?? "");
+          const log = parseUndoLog(row.undo_log);
+          const writeCtx = { ...context ?? {}, skipAutomations: true };
+          let deleted = 0, restored = 0, failed = 0;
+          for (const id of log.created) {
+            try {
+              await p.deleteData({ object: objectName, id, context: writeCtx, ...environmentId ? { environmentId } : {} });
+              deleted++;
+            } catch {
+              failed++;
+            }
+          }
+          for (const u of log.updated) {
+            try {
+              await p.updateData({ object: objectName, id: u.id, data: u.before, context: writeCtx, ...environmentId ? { environmentId } : {} });
+              restored++;
+            } catch {
+              failed++;
+            }
+          }
+          await p.updateData({
+            object: IMPORT_JOB_OBJECT,
+            id: jobId,
+            data: { reverted_at: (/* @__PURE__ */ new Date()).toISOString() },
+            context,
+            ...environmentId ? { environmentId } : {}
+          });
+          res.json({ success: true, jobId, object: objectName, deleted, restored, failed });
+        } catch (error) {
+          logError("[REST] Unhandled error:", error);
+          sendError(res, error, "");
+        }
+      },
+      metadata: { summary: "Undo (logically roll back) a finished import job", tags: ["data", "import"] }
+    });
+    this.routeManager.register({
+      method: "GET",
+      path: `${dataPath}/import/jobs/:jobId/results`,
+      handler: async (req, res) => {
+        try {
+          const environmentId = isScoped ? req.params?.environmentId : void 0;
+          const p = await this.resolveProtocol(environmentId, req);
+          const context = await this.resolveExecCtx(environmentId, req);
+          if (this.enforceAuth(req, res, context)) return;
+          const jobId = String(req.params.jobId || "");
+          const row = await loadImportJob(p, jobId, environmentId, context);
+          if (!row) {
+            res.status(404).json({ code: "NOT_FOUND", error: `No import job ${jobId}` });
+            return;
+          }
+          const stored = row.results;
+          const items = Array.isArray(stored?.items) ? stored.items : Array.isArray(stored) ? stored : [];
+          res.json({ ...importJobToProgress(row), results: items, resultsTruncated: !!stored?.truncated });
+        } catch (error) {
+          logError("[REST] Unhandled error:", error);
+          sendError(res, error, "");
+        }
+      },
+      metadata: { summary: "Import job results (capped per-row report)", tags: ["data", "import"] }
+    });
+    this.routeManager.register({
+      method: "GET",
+      path: `${dataPath}/import/jobs/:jobId`,
+      handler: async (req, res) => {
+        try {
+          const environmentId = isScoped ? req.params?.environmentId : void 0;
+          const p = await this.resolveProtocol(environmentId, req);
+          const context = await this.resolveExecCtx(environmentId, req);
+          if (this.enforceAuth(req, res, context)) return;
+          const jobId = String(req.params.jobId || "");
+          const row = await loadImportJob(p, jobId, environmentId, context);
+          if (!row) {
+            res.status(404).json({ code: "NOT_FOUND", error: `No import job ${jobId}` });
+            return;
+          }
+          res.json(importJobToProgress(row));
+        } catch (error) {
+          logError("[REST] Unhandled error:", error);
+          sendError(res, error, "");
+        }
+      },
+      metadata: { summary: "Import job progress", tags: ["data", "import"] }
+    });
+    this.routeManager.register({
+      method: "GET",
+      path: `${dataPath}/import/jobs`,
+      handler: async (req, res) => {
+        try {
+          const environmentId = isScoped ? req.params?.environmentId : void 0;
+          const p = await this.resolveProtocol(environmentId, req);
+          const context = await this.resolveExecCtx(environmentId, req);
+          if (this.enforceAuth(req, res, context)) return;
+          const q = req.query ?? {};
+          const filter = {};
+          if (typeof q.object === "string" && q.object) filter.object_name = q.object;
+          if (typeof q.status === "string" && q.status) filter.status = q.status;
+          const limit = Math.min(200, Math.max(1, Number(q.limit) || 50));
+          const offset = Math.max(0, Number(q.offset) || 0);
+          const r = await p.findData({
+            object: IMPORT_JOB_OBJECT,
+            query: { $filter: filter, $orderby: { created_at: "desc" }, $top: limit, $skip: offset },
+            ...environmentId ? { environmentId } : {},
+            ...context ? { context } : {}
+          });
+          const rows = Array.isArray(r?.records) ? r.records : Array.isArray(r?.data) ? r.data : Array.isArray(r?.rows) ? r.rows : Array.isArray(r) ? r : [];
+          res.json({ jobs: rows.map(importJobToSummary) });
+        } catch (error) {
+          logError("[REST] Unhandled error:", error);
+          sendError(res, error, "");
+        }
+      },
+      metadata: { summary: "List import jobs (history)", tags: ["data", "import"] }
+    });
     this.routeManager.register({
       method: "GET",
       path: `${dataPath}/:object/export`,
@@ -2551,7 +3542,9 @@ var RestServer = class {
           }
           if (await this.enforceApiAccess(req, res, p, environmentId, "export")) return;
           const q = req.query ?? {};
-          const format = String(q.format ?? "csv").toLowerCase() === "json" ? "json" : "csv";
+          const fmtRaw = String(q.format ?? "csv").toLowerCase();
+          const format = fmtRaw === "json" ? "json" : fmtRaw === "xlsx" ? "xlsx" : "csv";
+          const includeHeader = String(q.header ?? "true").toLowerCase() !== "false";
           const HARD_CAP = 5e4;
           const MAX_CHUNK = 5e3;
           const requestedLimit = q.limit != null ? Math.max(1, Number(q.limit) || 0) : 1e4;
@@ -2590,21 +3583,33 @@ var RestServer = class {
           } else if (Array.isArray(q.fields)) {
             fields = q.fields.filter((s) => typeof s === "string" && s.length > 0);
           }
-          if (!fields || fields.length === 0) {
-            try {
-              const schema = await p.getObjectSchema?.(objectName, environmentId);
-              const schemaFields = schema?.fields;
-              if (Array.isArray(schemaFields)) {
-                fields = schemaFields.map((f) => f.name).filter((n) => typeof n === "string");
-              }
-            } catch {
+          let metaMap = /* @__PURE__ */ new Map();
+          try {
+            let schema = void 0;
+            if (typeof p.getMetaItem === "function") {
+              const res2 = await p.getMetaItem({ type: "object", name: objectName });
+              schema = isMetaEnvelope(res2) ? res2.item : res2;
+            }
+            if (!schema && typeof p.getObjectSchema === "function") {
+              schema = await p.getObjectSchema(objectName, environmentId);
             }
+            schema = await this.translateMetaItem(req, "object", environmentId, schema);
+            metaMap = buildFieldMetaMap(schema);
+            if (!fields || fields.length === 0) {
+              const names = [...metaMap.keys()];
+              if (names.length > 0) fields = names;
+            }
+          } catch {
           }
+          const expandFields = referenceFieldNames(metaMap);
           const stamp = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
           const safeObj = objectName.replace(/[^A-Za-z0-9_.-]/g, "_");
           if (format === "csv") {
             res.header("Content-Type", "text/csv; charset=utf-8");
             res.header("Content-Disposition", `attachment; filename="${safeObj}-${stamp}.csv"`);
+          } else if (format === "xlsx") {
+            res.header("Content-Type", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
+            res.header("Content-Disposition", `attachment; filename="${safeObj}-${stamp}.xlsx"`);
           } else {
             res.header("Content-Type", "application/json; charset=utf-8");
             res.header("Content-Disposition", `attachment; filename="${safeObj}-${stamp}.json"`);
@@ -2616,6 +3621,7 @@ var RestServer = class {
           let firstChunk = true;
           let skip = 0;
           if (format === "json") res.write("[");
+          const xlsx = format === "xlsx" ? await createXlsxStream(res) : null;
           while (exported < limit) {
             const take = Math.min(chunkSize, limit - exported);
             const findArgs = {
@@ -2623,6 +3629,7 @@ var RestServer = class {
               query: {
                 ...filter ? { $filter: filter } : {},
                 ...orderby ? { $orderby: orderby } : {},
+                ...expandFields.length > 0 ? { $expand: expandFields.join(",") } : {},
                 $top: take,
                 $skip: skip
               },
@@ -2630,18 +3637,25 @@ var RestServer = class {
               ...context ? { context } : {}
             };
             const result = await p.findData(findArgs);
-            const rows = Array.isArray(result?.data) ? result.data : Array.isArray(result?.rows) ? result.rows : Array.isArray(result) ? result : [];
+            const rows = Array.isArray(result?.records) ? result.records : Array.isArray(result?.data) ? result.data : Array.isArray(result?.rows) ? result.rows : Array.isArray(result) ? result : [];
             if (rows.length === 0) break;
+            if ((!fields || fields.length === 0) && firstChunk) {
+              fields = Object.keys(rows[0] ?? {});
+            }
             if (format === "csv") {
-              if ((!fields || fields.length === 0) && firstChunk) {
-                fields = Object.keys(rows[0] ?? {});
-              }
-              const text = rowsToCsv(fields ?? [], rows, firstChunk);
+              const text = rowsToCsv(fields ?? [], rows, firstChunk && includeHeader, metaMap);
               res.write(text);
+            } else if (format === "xlsx") {
+              if (firstChunk && includeHeader) {
+                xlsx.ws.addRow((fields ?? []).map((f) => headerLabel(f, metaMap))).commit();
+              }
+              for (const row of rows) {
+                xlsx.ws.addRow(formatRowCells(row, fields ?? [], metaMap)).commit();
+              }
             } else {
               for (let i = 0; i < rows.length; i++) {
                 const prefix = firstChunk && i === 0 ? "" : ",";
-                res.write(prefix + JSON.stringify(rows[i]));
+                res.write(prefix + JSON.stringify(formatRowForJson(rows[i], metaMap)));
               }
             }
             firstChunk = false;
@@ -2649,8 +3663,14 @@ var RestServer = class {
             skip += rows.length;
             if (rows.length < take) break;
           }
-          if (format === "json") res.write("]");
-          res.end();
+          if (format === "json") {
+            res.write("]");
+            res.end();
+          } else if (format === "xlsx") {
+            await xlsx.finalize();
+          } else {
+            res.end();
+          }
         } catch (error) {
           logError("[REST] Unhandled error:", error);
           try {
@@ -2664,7 +3684,7 @@ var RestServer = class {
         }
       },
       metadata: {
-        summary: "Streaming export of object rows (CSV or JSON)",
+        summary: "Streaming export of object rows (CSV, JSON, or XLSX)",
         tags: ["data", "export"]
       }
     });
@@ -4374,11 +5394,26 @@ function registerExternalDatasourceRoutes(server, ctx, basePath = "/api/v1") {
 }
 
 // src/rest-api-plugin.ts
+import { SysImportJob } from "@objectstack/platform-objects/audit";
 function createRestApiPlugin(config = {}) {
   return {
     name: "com.objectstack.rest.api",
     version: "1.0.0",
-    init: async (_ctx) => {
+    init: async (ctx) => {
+      try {
+        ctx.getService("manifest").register({
+          id: "com.objectstack.rest.api",
+          name: "REST API",
+          version: "1.0.0",
+          type: "plugin",
+          scope: "system",
+          defaultDatasource: "cloud",
+          namespace: "sys",
+          objects: [SysImportJob]
+        });
+      } catch (err) {
+        ctx.logger.warn("RestApiPlugin: manifest service unavailable; sys_import_job not registered", err);
+      }
     },
     start: async (ctx) => {
       const serverService = config.serverServiceName || "http.server";