@flowdular/sdk 0.2.3 → 0.3.0

package/modules/exports/src/settings.ts

@@ -0,0 +1,70 @@
+import {
+	defineModuleSettings,
+	PLATFORM_SETTINGS_TENANT,
+	type ModuleSettingsRuntime,
+} from '@flowdular/sdk/kernel';
+
+export const EXPORTS_MODULE_ID = 'exports.core';
+
+export const DEFAULT_EXPORT_MAX_ROWS = 100_000;
+export const DEFAULT_EXPORT_MAX_BYTES = 50 * 1024 * 1024;
+
+export const EXPORTS_MODULE_SETTINGS = defineModuleSettings({
+	moduleId: EXPORTS_MODULE_ID,
+	settings: {
+		maxRows: {
+			type: 'number',
+			defaultValue: DEFAULT_EXPORT_MAX_ROWS,
+			min: 100,
+			max: 5_000_000,
+			visibility: 'shared',
+			client: false,
+			scope: 'platform',
+			labelKey: 'exports.settings.maxRows.label',
+			label: 'Rows per export',
+			descriptionKey: 'exports.settings.maxRows.description',
+			description: 'Rows one export may hold; a longer list fails instead.',
+		},
+		maxBytes: {
+			type: 'number',
+			defaultValue: DEFAULT_EXPORT_MAX_BYTES,
+			min: 1_024,
+			max: 268_435_456,
+			visibility: 'shared',
+			client: false,
+			scope: 'platform',
+			labelKey: 'exports.settings.maxBytes.label',
+			label: 'Bytes per export',
+			descriptionKey: 'exports.settings.maxBytes.description',
+			description:
+				'Bytes one export may hold; the storage object limit still applies.',
+		},
+	},
+});
+
+/* A setting read must never take a running job down, so both accessors fall
+   back to the declared default when the runtime has not registered the module
+   yet. */
+function value(
+	settings: ModuleSettingsRuntime,
+	key: 'maxRows' | 'maxBytes',
+	fallback: number,
+): number {
+	try {
+		return settings.get<number>(
+			PLATFORM_SETTINGS_TENANT,
+			EXPORTS_MODULE_ID,
+			key,
+		);
+	} catch {
+		return fallback;
+	}
+}
+
+export function exportMaxRows(settings: ModuleSettingsRuntime): number {
+	return value(settings, 'maxRows', DEFAULT_EXPORT_MAX_ROWS);
+}
+
+export function exportMaxBytes(settings: ModuleSettingsRuntime): number {
+	return value(settings, 'maxBytes', DEFAULT_EXPORT_MAX_BYTES);
+}

package/modules/exports/translations/en.json

@@ -0,0 +1,69 @@
+{
+	"navigation.label": "Exports",
+	"navigation.description": "Download a list of this workspace as a CSV file.",
+	"page.eyebrow": "Operations",
+	"page.title": "Exports",
+	"page.description": "Every export runs as a job: the list is read page by page under your own permissions, written as one CSV file, and kept for 30 days.",
+	"denied.title": "Access denied",
+	"denied.hint": "You do not have permission to read export jobs in this workspace.",
+	"action.refresh": "Refresh",
+	"action.refreshing": "Refreshing…",
+	"action.open": "Download",
+	"action.start": "Start export",
+	"action.starting": "Starting…",
+	"start.title": "Start an export",
+	"start.description": "Pick a list and the job appears below while it runs.",
+	"start.list": "List",
+	"start.placeholder": "Choose a list…",
+	"start.loading": "Loading the lists this workspace offers…",
+	"start.emptyTitle": "No list to export",
+	"start.emptyHint": "No enabled module offers a list you hold the permission to export.",
+	"start.deniedTitle": "Access denied",
+	"start.deniedHint": "You do not have permission to read the lists of this workspace.",
+	"filter.status": "Status",
+	"filter.any": "Any status",
+	"table.title": "Export jobs",
+	"table.caption": "Export jobs in this workspace",
+	"table.count": "{count} jobs",
+	"table.loading": "Loading export jobs…",
+	"table.emptyTitle": "No exports yet",
+	"table.emptyHint": "Start an export from the list you want to download; it appears here while it runs.",
+	"table.column.listId": "List",
+	"table.column.status": "Status",
+	"table.column.rowCount": "Rows",
+	"table.column.byteCount": "Size",
+	"table.column.startedAt": "Started",
+	"table.column.file": "File",
+	"status.requested": "Requested",
+	"status.running": "Running",
+	"status.completed": "Completed",
+	"status.failed": "Failed",
+	"error.load": "Could not load export jobs.",
+	"error.catalogue": "Could not load the lists this workspace offers.",
+	"error.start": "Could not start that export.",
+	"error.open": "Could not open that export file.",
+	"error.request": "The export operation failed.",
+	"error.code.EXPORT_LIST_UNKNOWN": "No module offers that list for export.",
+	"error.code.EXPORT_LIST_FORBIDDEN": "You do not hold the permission this list requires.",
+	"error.code.EXPORT_JOB_NOT_FOUND": "That export job does not exist in this workspace.",
+	"error.code.EXPORT_NOT_READY": "That export has no file to open.",
+	"error.code.EXPORT_OBJECT_GONE": "That export file is no longer stored.",
+	"error.code.EXPORT_ROWS_EXCEEDED": "The list is longer than an export may hold; narrow it first.",
+	"error.code.EXPORT_BYTES_EXCEEDED": "The file would be larger than an export may hold; narrow the list first.",
+	"error.code.EXPORT_LIST_FAILED": "The list could not be read to the end.",
+	"error.code.EXPORT_LIST_STALLED": "The list did not page to its end, so the export was stopped.",
+	"error.code.EXPORT_PAGE_OVERSIZE": "The list answered more rows than an export page holds.",
+	"error.code.EXPORT_CELL_INVALID": "A column answered a value a CSV file cannot carry.",
+	"error.code.EXPORT_CELL_TOO_LARGE": "A column answered more text than a cell may hold.",
+	"error.code.EXPORT_STORAGE_FAILED": "The file could not be stored.",
+	"error.code.EXPORT_DEFINITION_INVALID": "That list export is declared incorrectly.",
+	"error.code.EXPORT_LIST_DUPLICATE": "That list export is already registered.",
+	"error.code.EXPORT_LIST_INVALID": "That list export declaration is not accepted.",
+	"error.code.EXPORT_LISTS_SEALED": "List exports are registered while the platform starts.",
+	"error.code.REQUESTER_TOO_LARGE": "Your account carries more grants than an export job can record.",
+	"error.code.JOB_FAILED": "The export stopped on an unexpected failure.",
+	"settings.maxRows.label": "Rows per export",
+	"settings.maxRows.description": "Rows one export may hold; a longer list fails instead.",
+	"settings.maxBytes.label": "Bytes per export",
+	"settings.maxBytes.description": "Bytes one export may hold; the storage object limit still applies."
+}

package/modules/exports/translations/pl.json

@@ -0,0 +1,69 @@
+{
+	"navigation.label": "Eksporty",
+	"navigation.description": "Pobierz listę z tego obszaru roboczego jako plik CSV.",
+	"page.eyebrow": "Operacje",
+	"page.title": "Eksporty",
+	"page.description": "Każdy eksport działa jako zadanie: lista jest czytana strona po stronie z Twoimi uprawnieniami, zapisywana jako jeden plik CSV i przechowywana przez 30 dni.",
+	"denied.title": "Brak dostępu",
+	"denied.hint": "Nie masz uprawnień do odczytu zadań eksportu w tym obszarze roboczym.",
+	"action.refresh": "Odśwież",
+	"action.refreshing": "Odświeżanie…",
+	"action.open": "Pobierz",
+	"action.start": "Uruchom eksport",
+	"action.starting": "Uruchamianie…",
+	"start.title": "Uruchom eksport",
+	"start.description": "Wybierz listę, a zadanie pojawi się poniżej w trakcie działania.",
+	"start.list": "Lista",
+	"start.placeholder": "Wybierz listę…",
+	"start.loading": "Wczytywanie list dostępnych w tym obszarze roboczym…",
+	"start.emptyTitle": "Brak listy do eksportu",
+	"start.emptyHint": "Żaden włączony moduł nie udostępnia listy, do której masz uprawnienie eksportu.",
+	"start.deniedTitle": "Brak dostępu",
+	"start.deniedHint": "Nie masz uprawnień do odczytu list w tym obszarze roboczym.",
+	"filter.status": "Status",
+	"filter.any": "Dowolny status",
+	"table.title": "Zadania eksportu",
+	"table.caption": "Zadania eksportu w tym obszarze roboczym",
+	"table.count": "Zadania: {count}",
+	"table.loading": "Wczytywanie zadań eksportu…",
+	"table.emptyTitle": "Brak eksportów",
+	"table.emptyHint": "Uruchom eksport z listy, którą chcesz pobrać; pojawi się tutaj w trakcie działania.",
+	"table.column.listId": "Lista",
+	"table.column.status": "Status",
+	"table.column.rowCount": "Wiersze",
+	"table.column.byteCount": "Rozmiar",
+	"table.column.startedAt": "Rozpoczęto",
+	"table.column.file": "Plik",
+	"status.requested": "Zgłoszone",
+	"status.running": "W toku",
+	"status.completed": "Zakończone",
+	"status.failed": "Nieudane",
+	"error.load": "Nie udało się wczytać zadań eksportu.",
+	"error.catalogue": "Nie udało się wczytać list dostępnych w tym obszarze roboczym.",
+	"error.start": "Nie udało się uruchomić tego eksportu.",
+	"error.open": "Nie udało się otworzyć pliku eksportu.",
+	"error.request": "Operacja eksportu nie powiodła się.",
+	"error.code.EXPORT_LIST_UNKNOWN": "Żaden moduł nie udostępnia tej listy do eksportu.",
+	"error.code.EXPORT_LIST_FORBIDDEN": "Nie masz uprawnienia wymaganego przez tę listę.",
+	"error.code.EXPORT_JOB_NOT_FOUND": "To zadanie eksportu nie istnieje w tym obszarze roboczym.",
+	"error.code.EXPORT_NOT_READY": "To zadanie eksportu nie ma pliku do otwarcia.",
+	"error.code.EXPORT_OBJECT_GONE": "Plik tego eksportu nie jest już przechowywany.",
+	"error.code.EXPORT_ROWS_EXCEEDED": "Lista jest dłuższa, niż może pomieścić eksport; najpierw ją zawęź.",
+	"error.code.EXPORT_BYTES_EXCEEDED": "Plik byłby większy, niż może pomieścić eksport; najpierw zawęź listę.",
+	"error.code.EXPORT_LIST_FAILED": "Nie udało się odczytać listy do końca.",
+	"error.code.EXPORT_LIST_STALLED": "Lista nie doszła do końca stronicowania, więc eksport został zatrzymany.",
+	"error.code.EXPORT_PAGE_OVERSIZE": "Lista zwróciła więcej wierszy, niż mieści strona eksportu.",
+	"error.code.EXPORT_CELL_INVALID": "Kolumna zwróciła wartość, której plik CSV nie może przenieść.",
+	"error.code.EXPORT_CELL_TOO_LARGE": "Kolumna zwróciła więcej tekstu, niż może pomieścić komórka.",
+	"error.code.EXPORT_STORAGE_FAILED": "Nie udało się zapisać pliku.",
+	"error.code.EXPORT_DEFINITION_INVALID": "Ta deklaracja eksportu listy jest niepoprawna.",
+	"error.code.EXPORT_LIST_DUPLICATE": "Ten eksport listy jest już zarejestrowany.",
+	"error.code.EXPORT_LIST_INVALID": "Ta deklaracja eksportu listy nie została przyjęta.",
+	"error.code.EXPORT_LISTS_SEALED": "Eksporty list rejestruje się podczas startu platformy.",
+	"error.code.REQUESTER_TOO_LARGE": "Twoje konto ma więcej uprawnień, niż może zapisać zadanie eksportu.",
+	"error.code.JOB_FAILED": "Eksport zatrzymał się na nieoczekiwanym błędzie.",
+	"settings.maxRows.label": "Wiersze na eksport",
+	"settings.maxRows.description": "Liczba wierszy, jaką może pomieścić jeden eksport; dłuższa lista kończy się niepowodzeniem.",
+	"settings.maxBytes.label": "Bajty na eksport",
+	"settings.maxBytes.description": "Liczba bajtów, jaką może pomieścić jeden eksport; limit obiektu w magazynie nadal obowiązuje."
+}

package/modules/import/migrations/0001_import_core.down.sql

@@ -0,0 +1,6 @@
+DROP POLICY IF EXISTS import_mappings_tenant_policy ON import_mappings;
+DROP TABLE IF EXISTS import_mappings;
+DROP POLICY IF EXISTS import_job_rows_tenant_policy ON import_job_rows;
+DROP TABLE IF EXISTS import_job_rows;
+DROP POLICY IF EXISTS import_jobs_tenant_policy ON import_jobs;
+DROP TABLE IF EXISTS import_jobs;

package/modules/import/migrations/0001_import_core.up.sql

@@ -0,0 +1,61 @@
+CREATE TABLE IF NOT EXISTS import_jobs (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  target TEXT NOT NULL CHECK (length(target) BETWEEN 3 AND 96),
+  document_id TEXT NOT NULL CHECK (length(document_id) BETWEEN 1 AND 128),
+  document_ref TEXT NOT NULL CHECK (length(document_ref) BETWEEN 1 AND 200),
+  mode TEXT NOT NULL CHECK (mode IN ('create-only', 'update-existing', 'skip-existing')),
+  dry_run SMALLINT NOT NULL CHECK (dry_run IN (0, 1)),
+  valid_only SMALLINT NOT NULL CHECK (valid_only IN (0, 1)),
+  status TEXT NOT NULL CHECK (status IN ('parsing', 'validated', 'writing', 'completed', 'failed', 'cancelled')),
+  total_rows BIGINT NOT NULL CHECK (total_rows >= 0),
+  valid_rows BIGINT NOT NULL CHECK (valid_rows >= 0),
+  written_rows BIGINT NOT NULL CHECK (written_rows >= 0),
+  failed_rows BIGINT NOT NULL CHECK (failed_rows >= 0),
+  requester_account_id TEXT NOT NULL CHECK (length(requester_account_id) BETWEEN 1 AND 128),
+  requester_json TEXT NOT NULL CHECK (length(requester_json) <= 8192 AND requester_json::jsonb IS NOT NULL),
+  columns_json TEXT NOT NULL CHECK (length(columns_json) <= 8192 AND columns_json::jsonb IS NOT NULL),
+  failure_code TEXT CHECK (failure_code IS NULL OR length(failure_code) BETWEEN 1 AND 64),
+  claimed_at BIGINT,
+  started_at BIGINT NOT NULL,
+  completed_at BIGINT,
+  CHECK ((status IN ('completed', 'failed', 'cancelled')) = (completed_at IS NOT NULL))
+);
+CREATE INDEX IF NOT EXISTS import_jobs_tenant_started_idx
+  ON import_jobs (tenant_id, started_at DESC, id);
+ALTER TABLE import_jobs ENABLE ROW LEVEL SECURITY;
+ALTER TABLE import_jobs FORCE ROW LEVEL SECURITY;
+CREATE POLICY import_jobs_tenant_policy ON import_jobs
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+
+CREATE TABLE IF NOT EXISTS import_job_rows (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  job_id TEXT NOT NULL,
+  row_number BIGINT NOT NULL CHECK (row_number >= 1),
+  outcome TEXT NOT NULL CHECK (outcome IN ('valid', 'invalid', 'created', 'updated', 'skipped', 'failed')),
+  field TEXT CHECK (field IS NULL OR length(field) BETWEEN 1 AND 64),
+  reason TEXT CHECK (reason IS NULL OR length(reason) BETWEEN 1 AND 200),
+  record_ref TEXT CHECK (record_ref IS NULL OR length(record_ref) BETWEEN 1 AND 200),
+  UNIQUE (tenant_id, job_id, row_number)
+);
+ALTER TABLE import_job_rows ENABLE ROW LEVEL SECURITY;
+ALTER TABLE import_job_rows FORCE ROW LEVEL SECURITY;
+CREATE POLICY import_job_rows_tenant_policy ON import_job_rows
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+
+CREATE TABLE IF NOT EXISTS import_mappings (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  target TEXT NOT NULL CHECK (length(target) BETWEEN 3 AND 96),
+  columns_json TEXT NOT NULL CHECK (length(columns_json) <= 8192 AND columns_json::jsonb IS NOT NULL),
+  updated_at BIGINT NOT NULL,
+  UNIQUE (tenant_id, target)
+);
+ALTER TABLE import_mappings ENABLE ROW LEVEL SECURITY;
+ALTER TABLE import_mappings FORCE ROW LEVEL SECURITY;
+CREATE POLICY import_mappings_tenant_policy ON import_mappings
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));

package/modules/import/migrations/0002_import_job_routing_role.down.sql

@@ -0,0 +1,4 @@
+REVOKE SELECT (tenant_id, id, status, started_at)
+  ON import_jobs FROM coreloom_background;
+DROP POLICY IF EXISTS import_jobs_background_policy ON import_jobs;
+DROP INDEX IF EXISTS import_jobs_routing_idx;

package/modules/import/migrations/0002_import_job_routing_role.up.sql

@@ -0,0 +1,20 @@
+-- The poll loop must find queued jobs across workspaces before it knows whose
+-- they are, so it reads the routing columns alone on the background role: the
+-- document, the target, the mapping, the requester and every row outcome stay
+-- invisible to it, and each job it picks is claimed and processed again under
+-- the workspace the routing row named. PostgreSQL checks column privileges in
+-- WHERE too, so `status` is part of the grant.
+CREATE INDEX IF NOT EXISTS import_jobs_routing_idx
+  ON import_jobs (status, started_at, tenant_id, id);
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'coreloom_background') THEN
+    RAISE EXCEPTION 'The coreloom_background role must exist before this migration.';
+  END IF;
+END
+$$;
+CREATE POLICY import_jobs_background_policy ON import_jobs
+  FOR SELECT TO coreloom_background
+  USING (status IN ('parsing', 'writing'));
+REVOKE SELECT ON import_jobs FROM coreloom_background;
+GRANT SELECT (tenant_id, id, status, started_at) ON import_jobs TO coreloom_background;

package/modules/import/migrations/0003_import_jobs_export_index.down.sql

@@ -0,0 +1 @@
+DROP INDEX IF EXISTS import_jobs_tenant_export_idx;

package/modules/import/migrations/0003_import_jobs_export_index.up.sql

@@ -0,0 +1,7 @@
+-- The data class export walks a workspace oldest first by (started_at, id) and
+-- the retention sweep picks its batch by the same key. The listing index orders
+-- started_at descending, and reading it backwards pairs an ascending started_at
+-- with a descending id, so neither walk can be served by it. The outcome and
+-- mapping walks keep using the unique keys their tables already carry.
+CREATE INDEX IF NOT EXISTS import_jobs_tenant_export_idx
+  ON import_jobs (tenant_id, started_at, id);

package/modules/import/migrations/0004_import_jobs_traceparent.down.sql

@@ -0,0 +1 @@
+ALTER TABLE import_jobs DROP COLUMN IF EXISTS traceparent;

package/modules/import/migrations/0004_import_jobs_traceparent.up.sql

@@ -0,0 +1,7 @@
+-- The trace that enqueued the job, as a W3C traceparent header value, so the
+-- pass that claims it can be read against the request that started it. Nullable
+-- because a job enqueued outside a traced scope, and every job that predates
+-- this column, is a new root. It is written once at insert and never used as a
+-- predicate, so it carries no index and stays off the background routing grant:
+-- the claim returns it under the tenant that owns the job.
+ALTER TABLE import_jobs ADD COLUMN IF NOT EXISTS traceparent text;

package/modules/import/migrations/README.md

@@ -0,0 +1,3 @@
+# Migrations
+
+Migrations in this directory are append-only after release.

package/modules/import/module.json

@@ -0,0 +1,37 @@
+{
+	"$schema": "../../packages/contracts/schemas/module.schema.json",
+	"schemaVersion": 1,
+	"id": "import.core",
+	"package": "@flowdular/module-import",
+	"version": "0.1.8",
+	"platformApi": "^0.1.0",
+	"profile": "full",
+	"capabilities": ["api", "database", "client", "translations"],
+	"platform": {
+		"server": true,
+		"client": true
+	},
+	"dependencies": [
+		{
+			"id": "system.core",
+			"range": "^0.7.0"
+		},
+		{
+			"id": "auth.core",
+			"range": "^0.13.0"
+		},
+		{
+			"id": "documents.core",
+			"range": "^0.1.2"
+		}
+	],
+	"provides": ["import.ports.v1"],
+	"requires": [
+		{
+			"id": "documents.attachments.v1"
+		}
+	],
+	"tenancy": "required",
+	"locales": ["en", "pl"],
+	"stability": "experimental"
+}

package/modules/import/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@flowdular/module-import",
+	"version": "0.1.8",
+	"private": true,
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts",
+		"./client": "./src/client/index.ts",
+		"./server": "./src/server/index.ts",
+		"./platform": "./src/platform.ts",
+		"./module.json": "./module.json"
+	},
+	"files": [
+		"src",
+		"schemas",
+		"dist",
+		"bin",
+		"public",
+		"module.json",
+		"migrations",
+		"translations",
+		"spec",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"typecheck": "tsrx-tsc --noEmit -p tsconfig.json",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@flowdular/client": "workspace:*",
+		"@flowdular/contracts": "workspace:*",
+		"@flowdular/database": "workspace:*",
+		"@flowdular/kernel": "workspace:*",
+		"@flowdular/module-auth": "workspace:*",
+		"@flowdular/module-documents": "workspace:*",
+		"@flowdular/server": "workspace:*",
+		"@flowdular/storage": "workspace:*",
+		"@flowdular/ui": "workspace:*",
+		"octane": "0.1.51",
+		"segment-state": "0.2.1"
+	},
+	"devDependencies": {
+		"@flowdular/database-testing": "workspace:*",
+		"@tsrx/typescript-plugin": "0.3.120",
+		"@types/node": "24.13.3",
+		"typescript": "5.9.3",
+		"vitest": "4.1.11"
+	}
+}