obm-upload-form-ui 0.1.0

package/README.md

@@ -0,0 +1,153 @@
+# obm-upload-form-ui
+
+[![npm version](https://img.shields.io/npm/v/obm-upload-form-ui.svg)](https://www.npmjs.com/package/obm-upload-form-ui)
+[![pipeline status](https://gitlab.com/openbiomaps/obm-upload-form-ui-library/badges/main/pipeline.svg)](https://gitlab.com/openbiomaps/obm-upload-form-ui-library/-/pipelines)
+[![license](https://img.shields.io/npm/l/obm-upload-form-ui.svg)](./LICENSE)
+
+A reusable UI component library for rendering and submitting [OpenBioMaps](https://openbiomaps.org)
+upload forms, built on the `obm-project-api` v3 form schema
+(`GET /forms`, `GET /forms/{publishedFormId}`, `POST /forms/{formId}`).
+
+> **Status: v0, work in progress.** Photo/attachment upload (`file_id`/`photo_id` fields) and the
+> `spatial`/`custom_check` validation rules are explicitly out of scope for this version and render
+> or report as "unsupported".
+
+## Installation
+
+```sh
+npm install obm-upload-form-ui
+```
+
+The `/custom-elements` entry point is also published to npm, so no-build hosts can load it straight
+from a CDN mirror instead of installing it, e.g.:
+
+```html
+<script
+  type="module"
+  src="https://cdn.jsdelivr.net/npm/obm-upload-form-ui/dist/custom-elements/obm-upload-form.js"
+></script>
+```
+
+## Packages in one repo
+
+| Entry point                          | What it is                                                                                                  | Dependencies                             |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| `obm-upload-form-ui`                 | Framework-free core: typed form schema, API client, validation engine, submit client, WKT↔GeoJSON utilities | none                                     |
+| `obm-upload-form-ui/vue`             | Vue 3 field widgets and the `<UploadForm>` orchestrator                                                     | `vue` (peer)                             |
+| `obm-upload-form-ui/vue-leaflet`     | Leaflet-based geometry field widget                                                                         | `vue`, `leaflet`, `leaflet-draw` (peers) |
+| `obm-upload-form-ui/custom-elements` | Self-contained `<obm-upload-form>` custom element (ES + IIFE bundles, Vue inlined) for no-build hosts       | none                                     |
+
+## Quick start (core)
+
+```ts
+import {
+  createFormApi,
+  cookieAuth,
+  validateForm,
+  canSubmit,
+  submitObservation,
+  buildMetadata,
+} from 'obm-upload-form-ui';
+
+const config = {
+  baseUrl: 'https://example.org/projects/my_project/api/v3',
+  language: 'en', // sent as Accept-Language; the API uses the first 2 characters
+  appVersion: 'my-app 1.0.0',
+  auth: cookieAuth(),
+};
+
+const api = createFormApi(config);
+const forms = await api.listForms();
+const schema = await api.getForm(forms[0].published_form_id);
+
+const data = { species: 'Lanius collurio', number: 5 };
+const result = validateForm(schema, data, 'final');
+if (canSubmit(result)) {
+  const live = await api.resolveLiveForm(schema.header.published_form_id);
+  await submitObservation(config, {
+    formId: live.formId,
+    data,
+    metadata: buildMetadata({ formVersion: live.formVersion, appVersion: config.appVersion }),
+  });
+}
+```
+
+### Validation model
+
+The API currently performs **no field-level validation** on write (it proxies to the legacy
+upload engine), so this library's validation engine is the enforcement layer. See
+`docs/adr/0002-validation-policy-model.md`:
+
+- Document states: `draft` (skips checks by default, matching existing OBM client behavior) and
+  `final` (enforces).
+- `soft` rules warn but never block.
+- `ValidationPolicy.enforcement` can be set to `'warn'` to make all validation non-blocking once
+  server-side validation exists.
+
+### Linked submissions (repeated groups)
+
+The form schema has no repeated/nested field groups. The established OBM convention is separate
+linked forms sharing a client-generated UUID as a foreign key. `submitLinked()` orchestrates this:
+one parent POST plus N child POSTs, all stamped with the shared id. **There is no server-side
+transaction** — partial failure is reported per item so callers can retry the remainder.
+
+## Development
+
+```sh
+npm install
+npm test              # unit + component tests (integration tests skip without OBM_API_BASE)
+npm run dev           # Storybook
+npm run build         # library + custom-elements bundles into dist/
+npm run typecheck
+npm run lint
+```
+
+### Testing against a live API
+
+Contract fixtures under `tests/fixtures/forms/` prefixed `synthetic-` are hand-derived from the
+API source, not captured responses. Replace them with real captures:
+
+```sh
+OBM_API_BASE=https://example.org/projects/my_project/api/v3 OBM_ACCESS_TOKEN=... npm run capture:fixtures
+OBM_API_BASE=... npm run test:integration
+```
+
+Note: the API allows `localhost`/`127.0.0.1` origins only when its `ENV != PROD`.
+
+### Demo app
+
+`demo/` is a Vite app deployable into an OBM project via the `spa_integration` module. See
+`docs/spa-integration-deployment.md` for build/packaging constraints and known host-side bugs.
+
+```sh
+npm run demo:dev      # local dev server
+npm run demo:build    # dist + dist-archives/<appName>.zip ready for upload
+```
+
+## Releases
+
+Versioning, `CHANGELOG.md`, GitLab Releases, and npm publishing are all automated by
+[semantic-release](https://semantic-release.gitbook.io/) from commit messages on `main` — see
+`.releaserc.json`. Use [Conventional Commits](https://www.conventionalcommits.org/) prefixes
+(`feat:`, `fix:`, `docs:`, `refactor:`, etc.) so the pipeline can compute the next version
+correctly; a `feat:` commit triggers a minor release, `fix:`/`docs:`/`refactor:`/... trigger a
+patch release, and a `BREAKING CHANGE:` footer (or `!` after the type) triggers a major release.
+See `docs/adr/0004-release-and-publish-strategy.md` for the full pipeline design.
+
+Publishing to npm uses [Trusted Publishing (OIDC)](https://docs.npmjs.com/trusted-publishers) —
+the CI pipeline exchanges a short-lived GitLab-issued token for a one-time npm publish token, so no
+long-lived `NPM_TOKEN` is stored in the project. See
+`docs/adr/0005-npm-trusted-publishing.md` for the setup and the one-time manual bootstrap it
+required.
+
+## Design documents
+
+- Architecture decisions: `docs/adr/`
+- Live-verification checklist (what automated tests cannot cover): `docs/live-verification.md`
+- Upstream feasibility study: `web-app/docs/architecture/upload-form-component-library-feasibility-study.md`
+
+## License
+
+GPL-3.0-or-later, matching the OpenBioMaps ecosystem. Note: GPL on a library means consumers must
+be GPL-compatible; if embedding into non-GPL third-party apps ever becomes a goal, LGPL would be
+the deliberate alternative — relicensing later requires all contributors' consent (see ADR 0001).

package/dist/_plugin-vue_export-helper-DQLEQ__A.js

@@ -0,0 +1,44 @@
+const n = {
+  saveDraft: "Save draft",
+  finalize: "Finalize",
+  required: "required",
+  unsupportedField: "This field is not supported in this interface yet.",
+  unsupportedFieldType: "Unsupported field type: {type}",
+  validationSummaryTitle: "The form cannot be finalized:",
+  warningsTitle: "Warnings:",
+  noticesTitle: "Not checked client-side:",
+  addItem: "Add",
+  removeItem: "Remove",
+  invalidWkt: "The value is not valid WKT geometry text.",
+  noOptions: "No options"
+}, r = {
+  saveDraft: "Piszkozat mentése",
+  finalize: "Véglegesítés",
+  required: "kötelező",
+  unsupportedField: "Ezt a mezőt ez a felület még nem támogatja.",
+  unsupportedFieldType: "Nem támogatott mezőtípus: {type}",
+  validationSummaryTitle: "Az űrlap nem véglegesíthető:",
+  warningsTitle: "Figyelmeztetések:",
+  noticesTitle: "Kliensoldalon nem ellenőrzött:",
+  addItem: "Hozzáadás",
+  removeItem: "Eltávolítás",
+  invalidWkt: "Az érték nem érvényes WKT geometria.",
+  noOptions: "Nincs választható elem"
+}, d = { en: n, hu: r };
+function m(e, i = "en", t = {}) {
+  return ((d[i.slice(0, 2).toLowerCase()] ?? n)[e] ?? n[e]).replace(
+    /\{(\w+)\}/g,
+    (s, l) => l in t ? String(t[l]) : s
+  );
+}
+const p = (e, i) => {
+  const t = e.__vccOpts || e;
+  for (const [o, a] of i)
+    t[o] = a;
+  return t;
+};
+export {
+  p as _,
+  m as u
+};
+//# sourceMappingURL=_plugin-vue_export-helper-DQLEQ__A.js.map

package/dist/_plugin-vue_export-helper-DQLEQ__A.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_plugin-vue_export-helper-DQLEQ__A.js","sources":["../src/vue/uiText.ts"],"sourcesContent":["/** Small catalog for UI strings the widgets themselves render. */\n\nexport type UiTextKey =\n  | 'saveDraft'\n  | 'finalize'\n  | 'required'\n  | 'unsupportedField'\n  | 'unsupportedFieldType'\n  | 'validationSummaryTitle'\n  | 'warningsTitle'\n  | 'noticesTitle'\n  | 'addItem'\n  | 'removeItem'\n  | 'invalidWkt'\n  | 'noOptions';\n\ntype UiCatalog = Record<UiTextKey, string>;\n\nconst en: UiCatalog = {\n  saveDraft: 'Save draft',\n  finalize: 'Finalize',\n  required: 'required',\n  unsupportedField: 'This field is not supported in this interface yet.',\n  unsupportedFieldType: 'Unsupported field type: {type}',\n  validationSummaryTitle: 'The form cannot be finalized:',\n  warningsTitle: 'Warnings:',\n  noticesTitle: 'Not checked client-side:',\n  addItem: 'Add',\n  removeItem: 'Remove',\n  invalidWkt: 'The value is not valid WKT geometry text.',\n  noOptions: 'No options',\n};\n\nconst hu: UiCatalog = {\n  saveDraft: 'Piszkozat mentése',\n  finalize: 'Véglegesítés',\n  required: 'kötelező',\n  unsupportedField: 'Ezt a mezőt ez a felület még nem támogatja.',\n  unsupportedFieldType: 'Nem támogatott mezőtípus: {type}',\n  validationSummaryTitle: 'Az űrlap nem véglegesíthető:',\n  warningsTitle: 'Figyelmeztetések:',\n  noticesTitle: 'Kliensoldalon nem ellenőrzött:',\n  addItem: 'Hozzáadás',\n  removeItem: 'Eltávolítás',\n  invalidWkt: 'Az érték nem érvényes WKT geometria.',\n  noOptions: 'Nincs választható elem',\n};\n\nconst catalogs: Record<string, UiCatalog> = { en, hu };\n\nexport function uiText(\n  key: UiTextKey,\n  language = 'en',\n  params: Record<string, unknown> = {},\n): string {\n  const catalog = catalogs[language.slice(0, 2).toLowerCase()] ?? en;\n  const template = catalog[key] ?? en[key];\n  return template.replace(/\\{(\\w+)\\}/g, (match, name: string) =>\n    name in params ? String(params[name]) : match,\n  );\n}\n"],"names":["en","hu","catalogs","uiText","key","language","params","match","name"],"mappings":"AAkBA,MAAMA,IAAgB;AAAA,EACpB,WAAW;AAAA,EACX,UAAU;AAAA,EACV,UAAU;AAAA,EACV,kBAAkB;AAAA,EAClB,sBAAsB;AAAA,EACtB,wBAAwB;AAAA,EACxB,eAAe;AAAA,EACf,cAAc;AAAA,EACd,SAAS;AAAA,EACT,YAAY;AAAA,EACZ,YAAY;AAAA,EACZ,WAAW;AACb,GAEMC,IAAgB;AAAA,EACpB,WAAW;AAAA,EACX,UAAU;AAAA,EACV,UAAU;AAAA,EACV,kBAAkB;AAAA,EAClB,sBAAsB;AAAA,EACtB,wBAAwB;AAAA,EACxB,eAAe;AAAA,EACf,cAAc;AAAA,EACd,SAAS;AAAA,EACT,YAAY;AAAA,EACZ,YAAY;AAAA,EACZ,WAAW;AACb,GAEMC,IAAsC,EAAE,IAAAF,GAAI,IAAAC,EAAA;AAE3C,SAASE,EACdC,GACAC,IAAW,MACXC,IAAkC,CAAA,GAC1B;AAGR,WAFgBJ,EAASG,EAAS,MAAM,GAAG,CAAC,EAAE,YAAA,CAAa,KAAKL,GACvCI,CAAG,KAAKJ,EAAGI,CAAG,GACvB;AAAA,IAAQ;AAAA,IAAc,CAACG,GAAOC,MAC5CA,KAAQF,IAAS,OAAOA,EAAOE,CAAI,CAAC,IAAID;AAAA,EAAA;AAE5C;;;;;;;"}

package/dist/core/client/auth.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Pluggable authentication strategies. Which one applies depends entirely on
+ * where the library is hosted (same-origin page, separate SPA, no-build host),
+ * so auth is injected via ObmClientConfig, never assumed.
+ */
+export interface AuthStrategy {
+    /** Adjust the outgoing request (headers/credentials) before it is sent. */
+    apply(init: RequestInit & {
+        headers: Headers;
+    }): void | Promise<void>;
+    /**
+     * Called once when a request gets HTTP 401. Return true to retry the
+     * request (e.g. after refreshing a token).
+     */
+    onUnauthorized?(): Promise<boolean>;
+}
+/**
+ * Same-origin session-cookie auth — the proven path for pages hosted inside
+ * an OBM project (the API also accepts the `access_token` cookie).
+ */
+export declare function cookieAuth(): AuthStrategy;
+/** Opaque or pre-obtained bearer token, supplied by the host. */
+export declare function bearerAuth(tokenProvider: () => string | Promise<string>): AuthStrategy;
+export interface JwtAuthOptions {
+    /**
+     * Endpoint returning a JWT for the current session, e.g. the spa_integration
+     * host pattern `https://host/projects/<project>/<appName>/ajax?jwt`.
+     * Fetched with credentials included (the session cookie authenticates it).
+     */
+    tokenUrl: string;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * JWT auth that lazily fetches (and on 401 refreshes) its token from a host
+ * endpoint. The refresh is single-flighted: concurrent 401s share one fetch.
+ */
+export declare function jwtAuth(options: JwtAuthOptions): AuthStrategy;

package/dist/core/client/errors.d.ts

@@ -0,0 +1,31 @@
+/** Base class for every error thrown by this library. */
+export declare class ObmError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The request never produced an HTTP response (network failure, CORS, abort). */
+export declare class ObmNetworkError extends ObmError {
+}
+/** RFC 9457 Problem Details, the API's error body format. */
+export interface ProblemDetails {
+    type?: string;
+    title?: string;
+    detail?: string;
+    status?: number;
+    instance?: string;
+    [extension: string]: unknown;
+}
+/** A non-2xx HTTP response from the API. */
+export declare class ObmApiError extends ObmError {
+    readonly status: number;
+    /** Parsed Problem JSON body, when the response carried one. */
+    readonly problem: ProblemDetails | null;
+    /** Raw response body text, for non-Problem error responses. */
+    readonly body: string;
+    constructor(status: number, body: string, problem: ProblemDetails | null);
+}
+/** The API returned a payload whose structure this library cannot interpret. */
+export declare class ObmSchemaError extends ObmError {
+}
+/** WKT/GeoJSON conversion failure. */
+export declare class ObmGeometryError extends ObmError {
+}

package/dist/core/client/formApi.d.ts

@@ -0,0 +1,23 @@
+import { ObmClientConfig } from '../config';
+import { FormListItem, FormSchema } from '../schema/types';
+export interface LiveFormRef {
+    /** The live form id POST /forms/{formId} expects. */
+    formId: number;
+    /** The form's last_modification_timestamp, sent as metadata.form_version. */
+    formVersion: number;
+}
+export interface FormApi {
+    /** GET /forms — memoized. */
+    listForms(): Promise<FormListItem[]>;
+    /** GET /forms/{publishedFormId}, normalized — memoized per id. */
+    getForm(publishedFormId: number): Promise<FormSchema>;
+    /**
+     * Resolve a stable published form id to the live form id + version via the
+     * form list. Host configs should store published ids; uploads need this
+     * mapping (thr_vizfolyasok getFormMapping precedent).
+     */
+    resolveLiveForm(publishedFormId: number): Promise<LiveFormRef>;
+    /** Drop all memoized responses. */
+    invalidate(): void;
+}
+export declare function createFormApi(config: ObmClientConfig): FormApi;

package/dist/core/client/http.d.ts

@@ -0,0 +1,10 @@
+import { ObmClientConfig } from '../config';
+/**
+ * Thin fetch wrapper shared by every API call: applies the configured auth
+ * strategy and Accept-Language, retries once after a successful
+ * auth.onUnauthorized() on 401, and turns non-2xx responses into ObmApiError
+ * (parsing RFC 9457 Problem JSON bodies when present).
+ */
+export declare function apiFetch(config: ObmClientConfig, path: string, init?: RequestInit): Promise<Response>;
+/** apiFetch + JSON body parsing. */
+export declare function apiFetchJson<T>(config: ObmClientConfig, path: string, init?: RequestInit): Promise<T>;

package/dist/core/config.d.ts

@@ -0,0 +1,25 @@
+import { AuthStrategy } from './client/auth';
+/**
+ * Project configuration, injected explicitly wherever the library talks to
+ * the API — never read from globals (a deliberate break from the
+ * thr_vizfolyasok precedent of module-level config constants).
+ */
+export interface ObmClientConfig {
+    /**
+     * Base URL of the project API, e.g.
+     * "https://example.org/projects/my_project/api/v3". Trailing slash tolerated.
+     */
+    baseUrl: string;
+    /**
+     * Language sent as Accept-Language on reads. The API uses the first two
+     * characters and falls back to the project language, then Hungarian.
+     */
+    language?: string;
+    /** Client application identifier reported in upload metadata (`app_version`). */
+    appVersion?: string;
+    /** Authentication strategy; defaults to cookie/session auth. */
+    auth?: AuthStrategy;
+    /** Custom fetch implementation (tests, Node hosts). Defaults to globalThis.fetch. */
+    fetchImpl?: typeof fetch;
+}
+export declare function normalizeBaseUrl(baseUrl: string): string;

package/dist/core/geo/wkt.d.ts

@@ -0,0 +1,7 @@
+import { Geometry } from 'geojson';
+/** Parse a WKT string into a GeoJSON geometry. Throws ObmGeometryError on invalid input. */
+export declare function wktToGeoJSON(wkt: string): Geometry;
+/** Serialize a GeoJSON geometry to WKT. Throws ObmGeometryError on failure. */
+export declare function geoJSONToWkt(geometry: Geometry): string;
+/** True when the string parses as (E)WKT. */
+export declare function isWkt(value: string): boolean;

package/dist/core/i18n/messages.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Message catalog for strings the library itself generates (validation
+ * messages). Hosts can override individual keys per call via MessageOverrides.
+ */
+export type MessageKey = 'validation.required' | 'validation.regexp' | 'validation.minmax.belowMin' | 'validation.minmax.aboveMax' | 'validation.minmax.notNumber' | 'validation.invalidRule' | 'validation.notSupported';
+export type MessageCatalog = Record<MessageKey, string>;
+export type MessageOverrides = Partial<MessageCatalog>;
+export declare const DEFAULT_LANGUAGE = "en";
+/**
+ * Resolve a message for the given language ('en' fallback for unknown
+ * languages/keys) and interpolate `{param}` placeholders.
+ */
+export declare function formatMessage(key: MessageKey, params?: Record<string, unknown>, language?: string, overrides?: MessageOverrides): string;

package/dist/core/index.d.ts

@@ -0,0 +1,16 @@
+/** Public API of the framework-free core (`obm-upload-form-ui`). */
+export { normalizeBaseUrl, type ObmClientConfig } from './config';
+export { ObmApiError, ObmError, ObmGeometryError, ObmNetworkError, ObmSchemaError, type ProblemDetails, } from './client/errors';
+export { bearerAuth, cookieAuth, jwtAuth, type AuthStrategy, type JwtAuthOptions, } from './client/auth';
+export { apiFetch, apiFetchJson } from './client/http';
+export { createFormApi, type FormApi, type LiveFormRef } from './client/formApi';
+export { FORM_COLUMN_TYPES, UNKNOWN_COLUMN_TYPE, type ColumnSchema, type ColumnValidation, type FormApiParameters, type FormColumnType, type FormHeader, type FormListElement, type FormListItem, type FormSchema, type ImportantField, type ListDefinition, type NormalizedColumnType, type ObservationListSettings, type RawFormDetails, type ValidationControlType, } from './schema/types';
+export { normalizeFormDetails } from './schema/normalize';
+export { DEFAULT_VALIDATION_POLICY, type DocumentState, type IssueSeverity, type ValidationIssue, type ValidationOptions, type ValidationPolicy, type ValidationResult, type ValidationRuleName, } from './validation/types';
+export { canSubmit, validateField, validateForm } from './validation/engine';
+export { isEmpty, parseMinmaxBounds } from './validation/rules';
+export { buildMetadata, generateUuid, type BuildMetadataOptions, type UploadMetadata, } from './submit/metadata';
+export { submitObservation, ValidationRefusedError, type SubmitObservationOptions, type SubmitResult, type SubmitValidationGate, } from './submit/submitClient';
+export { submitLinked, type LinkedItemFailure, type LinkedItemRef, type LinkedItemSuccess, type LinkedSubmissionItem, type LinkedSubmissionPlan, type LinkedSubmissionResult, } from './submit/linked';
+export { geoJSONToWkt, isWkt, wktToGeoJSON } from './geo/wkt';
+export { DEFAULT_LANGUAGE, formatMessage, type MessageCatalog, type MessageKey, type MessageOverrides, } from './i18n/messages';

package/dist/core/schema/guards.d.ts

@@ -0,0 +1,12 @@
+import { FormColumnType } from './types';
+export declare function isFormColumnType(value: unknown): value is FormColumnType;
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Tolerant boolean coercion for values that legacy data may deliver as
+ * 0/1, '0'/'1', 't'/'f' or 'true'/'false' instead of JSON booleans.
+ */
+export declare function toBoolean(value: unknown, fallback?: boolean): boolean;
+/** Tolerant numeric coercion; returns the fallback for non-numeric input. */
+export declare function toNumber(value: unknown, fallback?: number): number;
+export declare function toNullableString(value: unknown): string | null;
+export declare function toStringArray(value: unknown): string[];

package/dist/core/schema/normalize.d.ts

@@ -0,0 +1,10 @@
+import { FormSchema } from './types';
+/**
+ * Normalize a raw GET /forms/{publishedFormId} response into a FormSchema.
+ *
+ * Structural problems (not an object, missing form_body array) throw
+ * ObmSchemaError. Per-column oddities never throw: the schema is re-derived
+ * server-side from legacy data, so unknown types, missing blocks and loosely
+ * typed booleans are smoothed into safe defaults instead.
+ */
+export declare function normalizeFormDetails(raw: unknown): FormSchema;

package/dist/core/schema/types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Typed model of the obm-project-api form schema.
+ *
+ * Field names mirror the API's JSON serialization exactly
+ * (obm-project-api src/Models/FormDetails/**), except where a normalized
+ * shape is explicitly documented (FormSchema).
+ */
+/** Field types returned by GET /forms/{publishedFormId} (obm-project-api FormColumnType enum). */
+export declare const FORM_COLUMN_TYPES: readonly ["array", "autocomplete", "autocompletelist", "boolean", "crings", "custom_list", "date", "datetime", "file_id", "line", "list", "numeric", "photo_id", "point", "polygon", "text", "textarea", "time", "time_interval", "timetominutes", "wkt"];
+export type FormColumnType = (typeof FORM_COLUMN_TYPES)[number];
+/**
+ * Sentinel used by normalization when the API reports a type this library
+ * version does not know. Such columns render as "unsupported" instead of failing.
+ */
+export declare const UNKNOWN_COLUMN_TYPE = "__unknown";
+export type NormalizedColumnType = FormColumnType | typeof UNKNOWN_COLUMN_TYPE;
+/** obm-project-api ControlType enum (the `validate.type` field). */
+export type ValidationControlType = 'custom_check' | 'minmax' | 'nocheck' | 'regexp' | 'spatial';
+export interface ColumnValidation {
+    required: boolean;
+    /** Warn-but-allow tier: failures are reported as warnings and never block. */
+    soft: boolean;
+    type: ValidationControlType;
+    /** Rule payload: regexp pattern, "min,max" bounds, custom function name, ... */
+    value: string | null;
+}
+export interface FormApiParameters {
+    sticky: boolean;
+    hidden: boolean;
+    readonly: boolean;
+    list_elements_as_buttons: boolean;
+    once_field: boolean;
+    unfolding_list: boolean;
+    /** Only present in the JSON when non-null server-side. */
+    auto_geometry?: unknown;
+}
+export interface ListDefinition {
+    custom_list: boolean;
+    extendable: boolean;
+    /** Columns whose picklists should refresh when this column changes. */
+    trigger_target_column: string[];
+    selected: unknown;
+    multiselect: boolean;
+    /** The API spreads extra snake_case keys (pre_filter_*, ...) into this object. */
+    [passthrough: string]: unknown;
+}
+export interface FormListElement {
+    value: string;
+    /** The API falls back to `value` when the label is empty; normalization guarantees it here. */
+    label: string;
+    filter_value?: string;
+}
+/** One item of `form_body`, normalized (see `normalizeFormDetails`). */
+export interface ColumnSchema {
+    column: string;
+    short_name: string;
+    description: string | null;
+    type: NormalizedColumnType;
+    /** Raw type string as received; diagnostic aid when `type` is `__unknown`. */
+    raw_type: string;
+    default_value: unknown;
+    relation: string | null;
+    position_order: number;
+    validate: ColumnValidation;
+    pseudo_column: string | null;
+    api_params: FormApiParameters;
+    has_empty_line: boolean;
+    list_definition: ListDefinition | null;
+    generated_list_elements: FormListElement[];
+    /** Options per trigger value, keyed by the triggering column's value. */
+    filterable_list_elements: Record<string, FormListElement[]> | null;
+}
+export interface ObservationListSettings {
+    mode?: string;
+    time_limit?: number;
+    [passthrough: string]: unknown;
+}
+export interface ImportantField {
+    column: string;
+    type: string;
+    [passthrough: string]: unknown;
+}
+/** `form_header` of GET /forms/{publishedFormId}. */
+export interface FormHeader {
+    user?: unknown;
+    form_id: number;
+    published_form_id: number;
+    name: string;
+    description: string | null;
+    project_table: string;
+    destination_table: string;
+    tracklog_mode: string | null;
+    observation_list: ObservationListSettings | null;
+    periodic_notification?: unknown;
+    important_fields: ImportantField[];
+    highlighted_fields: string[];
+}
+/**
+ * Normalized form schema produced by `normalizeFormDetails` from the raw
+ * `{form_header, form_body}` API response: columns are sorted by
+ * `position_order` and per-column oddities are smoothed over.
+ */
+export interface FormSchema {
+    header: FormHeader;
+    columns: ColumnSchema[];
+}
+/** One row of GET /forms. */
+export interface FormListItem {
+    form_id: number;
+    published_form_id: number;
+    /** Unix timestamp; doubles as the `form_version` sent in upload metadata. */
+    last_modification_timestamp: number;
+    name: string;
+}
+/** Raw, un-normalized response shape of GET /forms/{publishedFormId}. */
+export interface RawFormDetails {
+    form_header: Record<string, unknown>;
+    form_body: unknown[];
+}

package/dist/core/submit/linked.d.ts

@@ -0,0 +1,58 @@
+import { FormApi } from '../client/formApi';
+import { ObmClientConfig } from '../config';
+import { SubmitResult } from './submitClient';
+/**
+ * Linked submissions generalize the OBM convention for repeated/nested field
+ * groups: the form schema is flat, so "add another X" data goes into separate
+ * linked forms whose rows carry a client-generated shared UUID as a foreign
+ * key (thr_vizfolyasok precedent: one parent POST + N child POSTs).
+ */
+export interface LinkedSubmissionItem {
+    /** Stable published form id; resolved to the live form id at submit time. */
+    publishedFormId: number;
+    data: Record<string, unknown>;
+}
+export interface LinkedSubmissionPlan {
+    /** Data column that carries the shared UUID in the parent and every child. */
+    sharedIdColumn: string;
+    /** Shared UUID; generated when omitted. */
+    sharedId?: string;
+    parent: LinkedSubmissionItem;
+    children: LinkedSubmissionItem[];
+    /** Access rules included in every item's metadata, e.g. `{ write: [...] }`. */
+    rules?: Record<string, unknown>;
+}
+export type LinkedItemRef = 'parent' | number;
+export interface LinkedItemSuccess {
+    item: LinkedItemRef;
+    publishedFormId: number;
+    result: SubmitResult;
+}
+export interface LinkedItemFailure {
+    item: LinkedItemRef;
+    publishedFormId: number;
+    error: unknown;
+}
+export interface LinkedSubmissionResult {
+    sharedId: string;
+    /** True when the parent and every child were accepted. */
+    complete: boolean;
+    succeeded: LinkedItemSuccess[];
+    /** The first failing item; submission stops there. */
+    failed?: LinkedItemFailure;
+    /** Child indexes that were not attempted because of the failure. */
+    remaining: number[];
+}
+/**
+ * Submit a parent record and its linked children, all stamped with a shared
+ * UUID, sequentially (parent first). Each POST gets fresh metadata with its
+ * own id and the target form's version.
+ *
+ * There is NO server-side transaction — each POST hits the legacy upload
+ * engine independently. On failure this resolves (never rejects) with
+ * `failed` + `remaining` so the caller can retry the remainder with the same
+ * `sharedId`.
+ */
+export declare function submitLinked(config: ObmClientConfig, plan: LinkedSubmissionPlan, dependencies?: {
+    formApi?: FormApi;
+}): Promise<LinkedSubmissionResult>;

package/dist/core/submit/metadata.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Upload metadata for POST /forms/{formId}. Field semantics follow the
+ * working thr_vizfolyasok client (getBaseMetadata): epoch-second timestamps,
+ * timezone as signed hours (UTC+2 → 2), a fresh UUID per observation.
+ */
+export interface UploadMetadata {
+    /** Unique id of this observation upload; the API requires it. */
+    id: string;
+    app_version: string;
+    /** The form's last_modification_timestamp (see FormApi.resolveLiveForm). */
+    form_version: number | null;
+    /** Signed offset from UTC in hours (UTC+2 → 2). */
+    timezone: number;
+    /** Epoch seconds. */
+    started_at: number;
+    /** Epoch seconds. */
+    finished_at: number;
+    rules?: Record<string, unknown>;
+    [extension: string]: unknown;
+}
+export interface BuildMetadataOptions {
+    /** The form's last_modification_timestamp; null only when genuinely unknown. */
+    formVersion: number | null;
+    /** Client application identifier; falls back to the library's own name. */
+    appVersion?: string;
+    /** Epoch seconds; defaults to now. */
+    startedAt?: number;
+    /** Epoch seconds; defaults to now. */
+    finishedAt?: number;
+    /** Access rules, e.g. `{ write: [...user groups] }`. */
+    rules?: Record<string, unknown>;
+    /** Extra metadata fields spread into the payload (e.g. observation_list). */
+    extra?: Record<string, unknown>;
+}
+/** crypto.randomUUID with a getRandomValues-based fallback for older webviews. */
+export declare function generateUuid(): string;
+export declare function buildMetadata(options: BuildMetadataOptions): UploadMetadata;

package/dist/core/submit/submitClient.d.ts

@@ -0,0 +1,40 @@
+import { ObmError } from '../client/errors';
+import { ObmClientConfig } from '../config';
+import { FormSchema } from '../schema/types';
+import { DocumentState, ValidationOptions, ValidationResult } from '../validation/types';
+import { UploadMetadata } from './metadata';
+/** Thrown by submitObservation when its validation gate blocks the payload. */
+export declare class ValidationRefusedError extends ObmError {
+    readonly result: ValidationResult;
+    constructor(result: ValidationResult);
+}
+export interface SubmitValidationGate {
+    schema: FormSchema;
+    state: DocumentState;
+    options?: ValidationOptions;
+}
+export interface SubmitObservationOptions {
+    /** The live form id (not the published id — see FormApi.resolveLiveForm). */
+    formId: number;
+    data: Record<string, unknown>;
+    metadata: UploadMetadata;
+    /**
+     * Optional validation gate: when present, the payload is validated first
+     * and a blocking result throws ValidationRefusedError. The refuse-vs-warn
+     * knob lives in the gate's ValidationPolicy, not here.
+     */
+    validate?: SubmitValidationGate;
+}
+export interface SubmitResult {
+    status: number;
+    /** The API responds 201 with a text/plain confirmation message. */
+    message: string;
+    /** Present when a validation gate ran (blocking or not). */
+    validation?: ValidationResult;
+}
+/**
+ * POST /forms/{formId} with the `{data, metadata}` JSON body. Success is
+ * HTTP 201 with a text/plain body — not JSON. API errors arrive as
+ * RFC 9457 Problem JSON and are thrown as ObmApiError by the HTTP layer.
+ */
+export declare function submitObservation(config: ObmClientConfig, options: SubmitObservationOptions): Promise<SubmitResult>;