@columnus/shared 0.1.47

package/dist/convexSiteUrl.d.ts

@@ -0,0 +1,73 @@
+/** Convex deployment cloud URL (.convex.cloud) → HTTP actions / auth issuer (.convex.site). */
+export declare function convexCloudToSiteUrl(convexUrl: string): string;
+export declare function convexSiteToCloudUrl(siteUrl: string): string;
+type ProcessEnvLike = Record<string, string | undefined>;
+/** Docker runtime-base verify placeholder — must not be used for real BFF prepare. */
+export declare function isPlaceholderManagementSiteUrl(url: string): boolean;
+/**
+ * Management `.convex.site` origin for BFF `prepare`.
+ * Prefers explicit management site env vars, else derives from `VITE_MANAGEMENT_CONVEX_URL`.
+ * Does not read `VITE_CONVEX_SITE_URL` — on web that is the tenant site, not Manage.
+ */
+export declare function resolveBffManagementSiteUrl(env?: ProcessEnvLike): string | undefined;
+/**
+ * Runtime BFF management site: prefer image-baked URL over Coolify env.
+ * Preview Coolify often injects prod `MANAGEMENT_CONVEX_SITE_URL`, which shadows the
+ * ephemeral Manage preview bake and makes prepare return HTTP 404 (no routes on prod).
+ */
+export declare function resolveRuntimeManagementSiteUrl(options: {
+    bakedSiteUrl?: string | null;
+    env?: ProcessEnvLike;
+}): string | undefined;
+/** Deployment name from a Convex cloud/site URL (`https://{name}.convex.cloud`). */
+export declare function convexDeploymentSlugFromUrl(url: string): string | undefined;
+/**
+ * Best-effort `CONVEX_DEPLOYMENT` when only the cloud URL is known (e.g. after `columnus-api pull`).
+ * Defaults to `dev:{slug}` — preview/prod deployments may need an explicit value in `.env.local`.
+ */
+export declare function deriveConvexDeploymentFromCloudUrl(cloudUrl: string): string | undefined;
+export type ConvexSiteUrlEnv = {
+    /** CONVEX_SITE_URL */
+    convexSiteUrl?: string;
+    /** VITE_CONVEX_SITE_URL */
+    viteConvexSiteUrl?: string;
+    /** CONVEX_URL */
+    convexUrl?: string;
+    /** VITE_CONVEX_URL */
+    viteConvexUrl?: string;
+    /** CONVEX_CLOUD_URL */
+    convexCloudUrl?: string;
+};
+/** @deprecated Use `ConvexSiteUrlEnv` */
+export type ResolveConvexSiteUrlOptions = ConvexSiteUrlEnv;
+export declare function readConvexSiteUrlEnv(env: ProcessEnvLike): ConvexSiteUrlEnv;
+/**
+ * Resolve .convex.site URL from env: explicit site URLs first, then derive from Convex cloud/site URLs.
+ * Returns empty string when nothing is configured.
+ */
+export declare function resolveConvexSiteUrlFromEnv(env: ConvexSiteUrlEnv): string;
+/** Better Auth `baseURL` from standard Convex process env. */
+export declare function convexSiteUrlFromProcessEnv(env?: ProcessEnvLike): string;
+/** Resolve .convex.site URL for OTP sign-in and scripts (throws when unset). */
+export declare function resolveConvexSiteUrl(env?: ConvexSiteUrlEnv): string;
+export type AuthConfigIssuerEnv = ConvexSiteUrlEnv & {
+    /** BAKED_AUTH_ISSUER patched at deploy time */
+    bakedAuthIssuer?: string;
+};
+/**
+ * Auth issuer for deploy scripts: baked deploy patch → convex site URL env chain.
+ */
+export declare function resolveAuthConfigIssuerFromEnv(env: AuthConfigIssuerEnv): string;
+export type AuthConfigIssuerFromProcessEnvOptions = {
+    bakedAuthIssuer?: string;
+    /** Derive from CONVEX_URL / VITE_CONVEX_URL when issuer env vars are unset (deploy scripts). */
+    deriveFromCloudUrl?: boolean;
+};
+/** JWT issuer from process env (auth.config.ts bundle vs deploy scripts). */
+export declare function authConfigIssuerFromProcessEnv(env?: ProcessEnvLike, options?: AuthConfigIssuerFromProcessEnvOptions): string;
+/** Comma-separated browser origins (SITE_URL) for Better Auth trustedOrigins / crossDomain. */
+export declare function parseTrustedSiteUrls(siteUrlRaw?: string): string[];
+export declare function primaryTrustedSiteUrl(siteUrlRaw?: string): string;
+/** Better Auth `trustedOrigins` from SITE_URL. */
+export declare function betterAuthTrustedOrigins(siteUrlRaw?: string): string[];
+export {};

package/dist/convexSiteUrl.js

@@ -0,0 +1,137 @@
+// packages/@columnus/shared/src/convexSiteUrl.ts
+function convexCloudToSiteUrl(convexUrl) {
+  const trimmed = convexUrl.trim().replace(/\/$/, "");
+  if (trimmed.includes(".convex.site")) return trimmed;
+  if (trimmed.includes(".convex.cloud")) {
+    return trimmed.replace(/\.convex\.cloud\b/, ".convex.site");
+  }
+  return trimmed;
+}
+function convexSiteToCloudUrl(siteUrl) {
+  const trimmed = siteUrl.trim().replace(/\/$/, "");
+  if (trimmed.includes(".convex.cloud")) return trimmed;
+  if (trimmed.includes(".convex.site")) {
+    return trimmed.replace(/\.convex\.site\b/, ".convex.cloud");
+  }
+  return trimmed;
+}
+function trimOptional(value) {
+  const trimmed = value?.trim();
+  return trimmed || void 0;
+}
+function normalizeTrailingSlash(url) {
+  return url.trim().replace(/\/$/, "");
+}
+function deriveSiteFromCloudUrl(cloud) {
+  const trimmed = cloud?.trim();
+  if (!trimmed) return void 0;
+  if (trimmed.includes(".convex.cloud") || trimmed.includes(".convex.site")) {
+    return convexCloudToSiteUrl(trimmed);
+  }
+  return void 0;
+}
+function isPlaceholderManagementSiteUrl(url) {
+  try {
+    const host = new URL(/:\/\//.test(url) ? url : `https://${url}`).hostname;
+    return host === "placeholder.convex.site" || host.endsWith(".placeholder.convex.site");
+  } catch {
+    return /placeholder\.convex\.site/i.test(url);
+  }
+}
+function resolveBffManagementSiteUrl(env = process.env) {
+  for (const key of ["COLUMNUS_MANAGEMENT_SITE_URL", "MANAGEMENT_CONVEX_SITE_URL"]) {
+    const value = trimOptional(env[key]);
+    if (value && !isPlaceholderManagementSiteUrl(value)) {
+      return normalizeTrailingSlash(value);
+    }
+  }
+  const managementCloud = trimOptional(env.VITE_MANAGEMENT_CONVEX_URL);
+  if (managementCloud) return convexCloudToSiteUrl(managementCloud);
+  return void 0;
+}
+function resolveRuntimeManagementSiteUrl(options) {
+  const bakedSite = trimOptional(options.bakedSiteUrl ?? void 0);
+  if (bakedSite && !isPlaceholderManagementSiteUrl(bakedSite)) {
+    return normalizeTrailingSlash(bakedSite);
+  }
+  return resolveBffManagementSiteUrl(options.env ?? process.env);
+}
+function convexDeploymentSlug(url) {
+  const match = url.match(/https:\/\/([^.]+)\.convex\.(?:cloud|site)/);
+  return match?.[1];
+}
+function convexDeploymentSlugFromUrl(url) {
+  return convexDeploymentSlug(url);
+}
+function deriveConvexDeploymentFromCloudUrl(cloudUrl) {
+  const slug = convexDeploymentSlug(cloudUrl);
+  return slug ? `dev:${slug}` : void 0;
+}
+function explicitSiteMatchesCloud(explicit, cloud) {
+  const explicitSlug = convexDeploymentSlug(explicit);
+  const cloudSlug = convexDeploymentSlug(cloud);
+  if (!explicitSlug || !cloudSlug) return true;
+  return explicitSlug === cloudSlug;
+}
+function readConvexSiteUrlEnv(env) {
+  return {
+    convexSiteUrl: env.CONVEX_SITE_URL,
+    viteConvexSiteUrl: env.VITE_CONVEX_SITE_URL,
+    convexUrl: env.CONVEX_URL,
+    viteConvexUrl: env.VITE_CONVEX_URL,
+    convexCloudUrl: env.CONVEX_CLOUD_URL
+  };
+}
+function resolveConvexSiteUrlFromEnv(env) {
+  const explicit = trimOptional(env.convexSiteUrl) ?? trimOptional(env.viteConvexSiteUrl);
+  const cloud = trimOptional(env.convexUrl) ?? trimOptional(env.viteConvexUrl) ?? trimOptional(env.convexCloudUrl);
+  if (explicit && cloud && !explicitSiteMatchesCloud(explicit, cloud)) {
+    return deriveSiteFromCloudUrl(cloud) ?? normalizeTrailingSlash(explicit);
+  }
+  if (explicit) return normalizeTrailingSlash(explicit);
+  return deriveSiteFromCloudUrl(cloud) ?? "";
+}
+function convexSiteUrlFromProcessEnv(env = process.env) {
+  return resolveConvexSiteUrlFromEnv(readConvexSiteUrlEnv(env));
+}
+function resolveConvexSiteUrl(env) {
+  const url = resolveConvexSiteUrlFromEnv(env ?? {});
+  if (!url) {
+    throw new Error("Convex URL required to derive .convex.site URL for OTP sign-in");
+  }
+  return url;
+}
+function resolveAuthConfigIssuerFromEnv(env) {
+  const baked = trimOptional(env.bakedAuthIssuer);
+  if (baked) return normalizeTrailingSlash(baked);
+  return resolveConvexSiteUrlFromEnv(env);
+}
+function authConfigIssuerFromProcessEnv(env = process.env, options = {}) {
+  return resolveAuthConfigIssuerFromEnv({
+    bakedAuthIssuer: options.bakedAuthIssuer,
+    convexSiteUrl: env.CONVEX_SITE_URL,
+    ...options.deriveFromCloudUrl ? {
+      convexUrl: env.CONVEX_URL,
+      viteConvexUrl: env.VITE_CONVEX_URL
+    } : {}
+  });
+}
+function parseTrustedSiteUrls(siteUrlRaw) {
+  const raw = siteUrlRaw?.trim() ?? "";
+  if (!raw) return [];
+  return raw.split(",").map((url) => url.trim()).filter(Boolean);
+}
+function primaryTrustedSiteUrl(siteUrlRaw) {
+  const urls = parseTrustedSiteUrls(siteUrlRaw);
+  return urls[0] ?? siteUrlRaw?.trim() ?? "";
+}
+function betterAuthTrustedOrigins(siteUrlRaw) {
+  const urls = parseTrustedSiteUrls(siteUrlRaw);
+  if (urls.length > 0) return urls;
+  const primary = primaryTrustedSiteUrl(siteUrlRaw);
+  return primary ? [primary] : [];
+}
+
+export { authConfigIssuerFromProcessEnv, betterAuthTrustedOrigins, convexCloudToSiteUrl, convexDeploymentSlugFromUrl, convexSiteToCloudUrl, convexSiteUrlFromProcessEnv, deriveConvexDeploymentFromCloudUrl, isPlaceholderManagementSiteUrl, parseTrustedSiteUrls, primaryTrustedSiteUrl, readConvexSiteUrlEnv, resolveAuthConfigIssuerFromEnv, resolveBffManagementSiteUrl, resolveConvexSiteUrl, resolveConvexSiteUrlFromEnv, resolveRuntimeManagementSiteUrl };
+//# sourceMappingURL=convexSiteUrl.js.map
+//# sourceMappingURL=convexSiteUrl.js.map

package/dist/convexSiteUrl.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/convexSiteUrl.ts"],"names":[],"mappings":"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","file":"convexSiteUrl.js","sourcesContent":["/** Convex deployment cloud URL (.convex.cloud) → HTTP actions / auth issuer (.convex.site). */\nexport function convexCloudToSiteUrl(convexUrl: string): string {\n  const trimmed = convexUrl.trim().replace(/\\/$/, \"\");\n  if (trimmed.includes(\".convex.site\")) return trimmed;\n  if (trimmed.includes(\".convex.cloud\")) {\n    return trimmed.replace(/\\.convex\\.cloud\\b/, \".convex.site\");\n  }\n  return trimmed;\n}\n\nexport function convexSiteToCloudUrl(siteUrl: string): string {\n  const trimmed = siteUrl.trim().replace(/\\/$/, \"\");\n  if (trimmed.includes(\".convex.cloud\")) return trimmed;\n  if (trimmed.includes(\".convex.site\")) {\n    return trimmed.replace(/\\.convex\\.site\\b/, \".convex.cloud\");\n  }\n  return trimmed;\n}\n\ntype ProcessEnvLike = Record<string, string | undefined>;\n\nfunction trimOptional(value?: string): string | undefined {\n  const trimmed = value?.trim();\n  return trimmed || undefined;\n}\n\nfunction normalizeTrailingSlash(url: string): string {\n  return url.trim().replace(/\\/$/, \"\");\n}\n\nfunction deriveSiteFromCloudUrl(cloud?: string): string | undefined {\n  const trimmed = cloud?.trim();\n  if (!trimmed) return undefined;\n  if (trimmed.includes(\".convex.cloud\") || trimmed.includes(\".convex.site\")) {\n    return convexCloudToSiteUrl(trimmed);\n  }\n  return undefined;\n}\n\n/** Docker runtime-base verify placeholder — must not be used for real BFF prepare. */\nexport function isPlaceholderManagementSiteUrl(url: string): boolean {\n  try {\n    const host = new URL(/:\\/\\//.test(url) ? url : `https://${url}`).hostname;\n    return host === \"placeholder.convex.site\" || host.endsWith(\".placeholder.convex.site\");\n  } catch {\n    return /placeholder\\.convex\\.site/i.test(url);\n  }\n}\n\n/**\n * Management `.convex.site` origin for BFF `prepare`.\n * Prefers explicit management site env vars, else derives from `VITE_MANAGEMENT_CONVEX_URL`.\n * Does not read `VITE_CONVEX_SITE_URL` — on web that is the tenant site, not Manage.\n */\nexport function resolveBffManagementSiteUrl(env: ProcessEnvLike = process.env): string | undefined {\n  for (const key of [\"COLUMNUS_MANAGEMENT_SITE_URL\", \"MANAGEMENT_CONVEX_SITE_URL\"] as const) {\n    const value = trimOptional(env[key]);\n    if (value && !isPlaceholderManagementSiteUrl(value)) {\n      return normalizeTrailingSlash(value);\n    }\n  }\n  const managementCloud = trimOptional(env.VITE_MANAGEMENT_CONVEX_URL);\n  if (managementCloud) return convexCloudToSiteUrl(managementCloud);\n  return undefined;\n}\n\n/**\n * Runtime BFF management site: prefer image-baked URL over Coolify env.\n * Preview Coolify often injects prod `MANAGEMENT_CONVEX_SITE_URL`, which shadows the\n * ephemeral Manage preview bake and makes prepare return HTTP 404 (no routes on prod).\n */\nexport function resolveRuntimeManagementSiteUrl(options: {\n  bakedSiteUrl?: string | null;\n  env?: ProcessEnvLike;\n}): string | undefined {\n  const bakedSite = trimOptional(options.bakedSiteUrl ?? undefined);\n  if (bakedSite && !isPlaceholderManagementSiteUrl(bakedSite)) {\n    return normalizeTrailingSlash(bakedSite);\n  }\n  return resolveBffManagementSiteUrl(options.env ?? process.env);\n}\n\nfunction convexDeploymentSlug(url: string): string | undefined {\n  const match = url.match(/https:\\/\\/([^.]+)\\.convex\\.(?:cloud|site)/);\n  return match?.[1];\n}\n\n/** Deployment name from a Convex cloud/site URL (`https://{name}.convex.cloud`). */\nexport function convexDeploymentSlugFromUrl(url: string): string | undefined {\n  return convexDeploymentSlug(url);\n}\n\n/**\n * Best-effort `CONVEX_DEPLOYMENT` when only the cloud URL is known (e.g. after `columnus-api pull`).\n * Defaults to `dev:{slug}` — preview/prod deployments may need an explicit value in `.env.local`.\n */\nexport function deriveConvexDeploymentFromCloudUrl(cloudUrl: string): string | undefined {\n  const slug = convexDeploymentSlug(cloudUrl);\n  return slug ? `dev:${slug}` : undefined;\n}\n\nfunction explicitSiteMatchesCloud(explicit: string, cloud: string): boolean {\n  const explicitSlug = convexDeploymentSlug(explicit);\n  const cloudSlug = convexDeploymentSlug(cloud);\n  if (!explicitSlug || !cloudSlug) return true;\n  return explicitSlug === cloudSlug;\n}\n\nexport type ConvexSiteUrlEnv = {\n  /** CONVEX_SITE_URL */\n  convexSiteUrl?: string;\n  /** VITE_CONVEX_SITE_URL */\n  viteConvexSiteUrl?: string;\n  /** CONVEX_URL */\n  convexUrl?: string;\n  /** VITE_CONVEX_URL */\n  viteConvexUrl?: string;\n  /** CONVEX_CLOUD_URL */\n  convexCloudUrl?: string;\n};\n\n/** @deprecated Use `ConvexSiteUrlEnv` */\nexport type ResolveConvexSiteUrlOptions = ConvexSiteUrlEnv;\n\nexport function readConvexSiteUrlEnv(env: ProcessEnvLike): ConvexSiteUrlEnv {\n  return {\n    convexSiteUrl: env.CONVEX_SITE_URL,\n    viteConvexSiteUrl: env.VITE_CONVEX_SITE_URL,\n    convexUrl: env.CONVEX_URL,\n    viteConvexUrl: env.VITE_CONVEX_URL,\n    convexCloudUrl: env.CONVEX_CLOUD_URL,\n  };\n}\n\n/**\n * Resolve .convex.site URL from env: explicit site URLs first, then derive from Convex cloud/site URLs.\n * Returns empty string when nothing is configured.\n */\nexport function resolveConvexSiteUrlFromEnv(env: ConvexSiteUrlEnv): string {\n  const explicit = trimOptional(env.convexSiteUrl) ?? trimOptional(env.viteConvexSiteUrl);\n  const cloud =\n    trimOptional(env.convexUrl) ??\n    trimOptional(env.viteConvexUrl) ??\n    trimOptional(env.convexCloudUrl);\n\n  if (explicit && cloud && !explicitSiteMatchesCloud(explicit, cloud)) {\n    return deriveSiteFromCloudUrl(cloud) ?? normalizeTrailingSlash(explicit);\n  }\n\n  if (explicit) return normalizeTrailingSlash(explicit);\n\n  return deriveSiteFromCloudUrl(cloud) ?? \"\";\n}\n\n/** Better Auth `baseURL` from standard Convex process env. */\nexport function convexSiteUrlFromProcessEnv(env: ProcessEnvLike = process.env): string {\n  return resolveConvexSiteUrlFromEnv(readConvexSiteUrlEnv(env));\n}\n\n/** Resolve .convex.site URL for OTP sign-in and scripts (throws when unset). */\nexport function resolveConvexSiteUrl(env?: ConvexSiteUrlEnv): string {\n  const url = resolveConvexSiteUrlFromEnv(env ?? {});\n  if (!url) {\n    throw new Error(\"Convex URL required to derive .convex.site URL for OTP sign-in\");\n  }\n  return url;\n}\n\nexport type AuthConfigIssuerEnv = ConvexSiteUrlEnv & {\n  /** BAKED_AUTH_ISSUER patched at deploy time */\n  bakedAuthIssuer?: string;\n};\n\n/**\n * Auth issuer for deploy scripts: baked deploy patch → convex site URL env chain.\n */\nexport function resolveAuthConfigIssuerFromEnv(env: AuthConfigIssuerEnv): string {\n  const baked = trimOptional(env.bakedAuthIssuer);\n  if (baked) return normalizeTrailingSlash(baked);\n\n  return resolveConvexSiteUrlFromEnv(env);\n}\n\nexport type AuthConfigIssuerFromProcessEnvOptions = {\n  bakedAuthIssuer?: string;\n  /** Derive from CONVEX_URL / VITE_CONVEX_URL when issuer env vars are unset (deploy scripts). */\n  deriveFromCloudUrl?: boolean;\n};\n\n/** JWT issuer from process env (auth.config.ts bundle vs deploy scripts). */\nexport function authConfigIssuerFromProcessEnv(\n  env: ProcessEnvLike = process.env,\n  options: AuthConfigIssuerFromProcessEnvOptions = {},\n): string {\n  return resolveAuthConfigIssuerFromEnv({\n    bakedAuthIssuer: options.bakedAuthIssuer,\n    convexSiteUrl: env.CONVEX_SITE_URL,\n    ...(options.deriveFromCloudUrl\n      ? {\n          convexUrl: env.CONVEX_URL,\n          viteConvexUrl: env.VITE_CONVEX_URL,\n        }\n      : {}),\n  });\n}\n\n/** Comma-separated browser origins (SITE_URL) for Better Auth trustedOrigins / crossDomain. */\nexport function parseTrustedSiteUrls(siteUrlRaw?: string): string[] {\n  const raw = siteUrlRaw?.trim() ?? \"\";\n  if (!raw) return [];\n  return raw\n    .split(\",\")\n    .map((url) => url.trim())\n    .filter(Boolean);\n}\n\nexport function primaryTrustedSiteUrl(siteUrlRaw?: string): string {\n  const urls = parseTrustedSiteUrls(siteUrlRaw);\n  return urls[0] ?? siteUrlRaw?.trim() ?? \"\";\n}\n\n/** Better Auth `trustedOrigins` from SITE_URL. */\nexport function betterAuthTrustedOrigins(siteUrlRaw?: string): string[] {\n  const urls = parseTrustedSiteUrls(siteUrlRaw);\n  if (urls.length > 0) return urls;\n  const primary = primaryTrustedSiteUrl(siteUrlRaw);\n  return primary ? [primary] : [];\n}\n"]}

package/dist/csv.d.ts

@@ -0,0 +1,54 @@
+import type { FieldType, Table as TableT } from "./schemaTypes.ts";
+export { addRef, collectIdsFromField, collectIdsFromValues, collectReferencedIds, } from "./refGraph.ts";
+export declare function serializeCsvValue(value: unknown, type: FieldType): string;
+export type CsvExport = {
+    headers: string[];
+    data: string[][];
+};
+export type DisplayIdLookup = Map<string, Map<string, string>>;
+/** Referenced ids plus exported row ids (for the table's own Id display template on `_id`). */
+export declare function collectExportDisplayIdRefs(table: TableT, rows: Record<string, unknown>[]): Map<string, Set<string>>;
+export declare function buildCsvRows(rows: Record<string, unknown>[], table: TableT, displayIds?: DisplayIdLookup): CsvExport;
+/** Subset export for grid clipboard copy (no `_id` / `_creationTime`). */
+export declare function buildCsvRowsForColumns(rows: Record<string, unknown>[], table: TableT, columnNames: readonly string[], displayIds?: DisplayIdLookup): CsvExport;
+export declare function unparseCsv({ headers, data }: CsvExport): string;
+export type CoerceResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function coerceCsvValue(raw: string, type: FieldType, optional: boolean): CoerceResult;
+export declare function applyDisplayIdResolution(rows: ImportRow[], table: TableT, resolved: Map<string, Map<string, string | null>>): ImportRow[];
+export declare function collectImportDisplayIds(rows: ImportRow[], table: TableT): Map<string, Set<string>>;
+/** Display ids in the `_id` column for replace-mode rows (not raw Convex document ids). */
+export declare function collectImportRowDisplayIds(rows: ImportRow[]): Set<string>;
+export declare function applyImportRowIdResolution(rows: ImportRow[], tableName: string, resolved: Map<string, Map<string, string | null>>): ImportRow[];
+export type ImportMode = "insert" | "replace";
+export type ImportRow = {
+    /** Sequential row index from the CSV (1-based, excluding header). */
+    rowNum: number;
+    /** Document to send to Convex (system fields stripped). */
+    doc: Record<string, unknown>;
+    /** Insert vs. replace decision. "replace" iff `_id` was supplied. */
+    mode: ImportMode;
+    /** Defined when `mode === "replace"`. */
+    id?: string;
+    /** Per-field error map. */
+    errors: Record<string, string>;
+};
+export declare function validateImportRow(raw: Record<string, string>, table: TableT, rowNum: number): ImportRow;
+export type ParseResult = {
+    /** Header row exactly as it appeared in the file. */
+    headers: string[];
+    /** Each row keyed by header name. */
+    rows: Record<string, string>[];
+    /** Headers that don't match a schema field or system column. */
+    unknownColumns: string[];
+    /** Required schema fields with no matching CSV column. */
+    missingRequired: string[];
+    /** papaparse parse errors. */
+    parseErrors: string[];
+};
+export declare function parseCsvText(text: string, table: TableT): ParseResult;