@murumets-ee/yhikas-sync 0.38.0

package/dist/index.d.mts

@@ -0,0 +1,1026 @@
+import { i as resolveYhikasSyncConfig, n as YhikasSyncConfig, r as YhikasSyncConfigError, t as ResolvedYhikasSyncConfig } from "./config-CHVLiXZf.mjs";
+import { Behavior } from "@murumets-ee/entity";
+import { z } from "zod";
+import { ToolkitApp } from "@murumets-ee/core";
+
+//#region src/constants.d.ts
+/**
+ * Names, identifiers and stated numbers for the yhikas-admin sync.
+ *
+ * Pure module — no imports, no side effects. Both the jiti-loaded plugin entry
+ * and the worker-side job modules read from here, so nothing in this file may
+ * reach a `server-only` module.
+ */
+/** Plugin name, as it appears in `app.plugins` and `Plugin.requires`. */
+declare const YHIKAS_SYNC_PLUGIN_NAME = "@murumets-ee/yhikas-sync";
+/**
+ * The synthetic actor every sync write is attributed to.
+ *
+ * Not `'cli'`. `auditable()` records this in `created_by`/`updated_by`, so a
+ * human reading the audit log can tell a sync write from an operator running a
+ * `lumi` command — and the machine-written guard (see `entities/guard.ts`) can
+ * refuse every other writer by name. Fits `varchar(255)`; user ids in this
+ * codebase are varchar, never uuid.
+ */
+declare const YHIKAS_SYNC_ACTOR_ID = "yhikas-sync";
+/**
+ * Job names. `JOB_NAME_RE` in `@murumets-ee/queue` is
+ * `/^[a-zA-Z0-9:_-]{1,128}$/` — colons are the `plugin:action` separator and
+ * dots are rejected outright.
+ */
+declare const SYNC_JOB_NAME = "yhikas-sync:pull";
+declare const WATCHDOG_JOB_NAME = "yhikas-sync:staleness-watchdog";
+/** The two resources in scope. `site_info` / `site_notice` are Q1, deliberately absent. */
+declare const ROOM_TYPES_RESOURCE = "room_types";
+declare const LEGAL_DOCUMENTS_RESOURCE = "legal_documents";
+declare const SYNC_RESOURCES: readonly ["room_types", "legal_documents"];
+type SyncResource = (typeof SYNC_RESOURCES)[number];
+/**
+ * Locale codes. Upstream `MultilingualText` is `{ en, et }` and the lumi codes
+ * are identical, so there is no mapping to configure — inventing one would be
+ * a seam for a second customer this package does not have (N1).
+ */
+declare const ET_LOCALE = "et";
+declare const EN_LOCALE = "en";
+/**
+ * Currency and VAT treatment, DECLARED here because they are not data upstream
+ * (R009 §6 / R013): `room_type` has no currency column and no tax column, and
+ * VAT is computed at invoice time against Merit article codes, never stored.
+ * Stating them makes a mis-entered source value render as a visibly wrong
+ * number against a declared unit rather than as a plausible one.
+ *
+ * The third semantic — the period — stays encoded in the field NAME
+ * (`monthlyRent` / `dailyRent`), because one row carries two different periods
+ * and a single `period` column could only be wrong about one of them.
+ */
+declare const DECLARED_CURRENCY = "EUR";
+/** `net` = the amount excludes VAT. */
+declare const DECLARED_VAT_TREATMENT = "net";
+/**
+ * Env var carrying the sync's OWN bearer credential — deliberately not the
+ * site's `PUBLIC_SITE_API_KEY`. The upstream limiter buckets on
+ * `sha256(key).slice(0,16)` rather than on the caller IP (there is no
+ * `x-forwarded-for` over the Docker-internal path), so sharing a key means
+ * sharing one 60/min bucket, and revoking one credential would blind both.
+ */
+declare const API_KEY_ENV_VAR = "YHIKAS_SYNC_API_KEY";
+declare const BASE_URL_ENV_VAR = "YHIKAS_ADMIN_BASE_URL";
+//#endregion
+//#region src/diff.d.ts
+/** One local row, reduced to what the diff needs. */
+interface LocalRow {
+  readonly id: string;
+  /** The business key this row was synced under. */
+  readonly key: string;
+  readonly status: string;
+  /**
+   * `null` on a row whose last sync did not complete — the hash is written
+   * LAST, after every other write for the row succeeded, so a null (or stale)
+   * hash is exactly the signal that the row needs redoing.
+   */
+  readonly sourceHash: string | null;
+  /** Preserved across updates so it keeps meaning "first published". */
+  readonly publishedAt: Date | null;
+}
+interface DiffPlan<T> {
+  /** Upstream rows with no local counterpart. */
+  readonly create: readonly T[];
+  /** Local rows whose hash differs, OR whose status drifted from `published`. */
+  readonly update: readonly {
+    readonly local: LocalRow;
+    readonly row: T;
+  }[];
+  /** Local rows already identical and already published — no write at all. */
+  readonly unchanged: readonly LocalRow[];
+  /** Published locally, absent upstream. Unpublished, never deleted (D016). */
+  readonly retire: readonly LocalRow[];
+}
+interface SanityFloor {
+  /** Refuse a snapshot larger than this rather than truncating it. */
+  readonly maxRows: number;
+  /** Refuse a run retiring more than this fraction of published rows. */
+  readonly maxRetireFraction: number;
+  /** The fraction rule applies only once at least this many rows are published. */
+  readonly minRowsForFraction: number;
+}
+interface PlanDiffInput<T> {
+  readonly resource: SyncResource;
+  readonly upstream: readonly T[];
+  readonly local: readonly LocalRow[];
+  readonly keyOf: (row: T) => string;
+  readonly hashOf: (row: T) => string;
+  readonly floor: SanityFloor;
+}
+/**
+ * Stable content hash of an upstream row.
+ *
+ * Keys are sorted so the hash does not depend on JSON property order, which no
+ * part of the HTTP stack guarantees. `undefined` and `null` are distinguished
+ * because a null price is meaningful data here, not an absence.
+ */
+declare function stableHash(value: unknown): string;
+/**
+ * Compare an authoritative upstream snapshot against local state.
+ *
+ * **The caller must not invoke this with a snapshot that did not fully
+ * succeed.** That guard lives one level up, in the client: a non-2xx, a
+ * timeout or a body failing the wire schema throws before the differ is ever
+ * reached, so a partial response can never present as an absence here. This
+ * function's own guards are for a snapshot that IS authoritative but whose
+ * shape makes acting on it reckless.
+ *
+ * @throws {YhikasSyncRefusedError} for any of the D016 refusals. Every one of
+ *   them aborts before a single write, so a refused run leaves local content
+ *   exactly as it was — which is the first of PR 05's three obligatory
+ *   negative tests.
+ */
+declare function planDiff<T>(input: PlanDiffInput<T>): DiffPlan<T>;
+//#endregion
+//#region src/upstream/wire.d.ts
+/**
+ * `MultilingualText` — a Postgres `json` column, so it arrives as a nested
+ * object and is never stringified.
+ *
+ * NOT `.strict()`: unknown keys are stripped rather than rejected, so adding a
+ * third language upstream degrades to "the sync ignores it" instead of "every
+ * run fails".
+ */
+declare const multilingualTextSchema: z.ZodObject<{
+  et: z.ZodString;
+  en: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+  et: string;
+  en: string;
+}, {
+  et: string;
+  en: string;
+}>;
+type MultilingualText = z.infer<typeof multilingualTextSchema>;
+/**
+ * One `room_type` row.
+ *
+ * `depositAmount` / `discountedDepositAmount` are absent by design. Upstream
+ * ships them as hardcoded `null` with no backing column; validating them as
+ * `z.null()` would turn the day someone adds the column into a hard sync
+ * failure. Deposits are unbuilt admin-side work, not something the sync can
+ * surface.
+ */
+declare const roomTypeRowSchema: z.ZodObject<{
+  code: z.ZodString;
+  name: z.ZodObject<{
+    et: z.ZodString;
+    en: z.ZodString;
+  }, "strip", z.ZodTypeAny, {
+    et: string;
+    en: string;
+  }, {
+    et: string;
+    en: string;
+  }>;
+  totalArea: z.ZodNullable<z.ZodString>;
+  livingArea: z.ZodNullable<z.ZodString>;
+  commonArea: z.ZodNullable<z.ZodString>;
+  capacity: z.ZodNullable<z.ZodNumber>;
+  monthlyRent: z.ZodNullable<z.ZodString>;
+  discountedRent: z.ZodNullable<z.ZodString>;
+  dailyRent: z.ZodNullable<z.ZodString>;
+  placesOccupied: z.ZodNullable<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+  code: string;
+  name: {
+    et: string;
+    en: string;
+  };
+  totalArea: string | null;
+  livingArea: string | null;
+  commonArea: string | null;
+  capacity: number | null;
+  placesOccupied: number | null;
+  monthlyRent: string | null;
+  dailyRent: string | null;
+  discountedRent: string | null;
+}, {
+  code: string;
+  name: {
+    et: string;
+    en: string;
+  };
+  totalArea: string | null;
+  livingArea: string | null;
+  commonArea: string | null;
+  capacity: number | null;
+  placesOccupied: number | null;
+  monthlyRent: string | null;
+  dailyRent: string | null;
+  discountedRent: string | null;
+}>;
+type RoomTypeRow = z.infer<typeof roomTypeRowSchema>;
+/**
+ * One active `legal_document` row.
+ *
+ * `type` is `text().notNull().unique()` upstream — NOT a pgEnum, and there is
+ * no TS union anywhere. The five values seeded today are closed by convention
+ * only and the admin UI can mint a sixth, so this validates the SHAPE of the
+ * business key and never its membership in a list. A whitelist here would turn
+ * a new upstream document into a hard sync failure.
+ */
+declare const legalDocumentRowSchema: z.ZodObject<{
+  type: z.ZodString;
+  title: z.ZodObject<{
+    et: z.ZodString;
+    en: z.ZodString;
+  }, "strip", z.ZodTypeAny, {
+    et: string;
+    en: string;
+  }, {
+    et: string;
+    en: string;
+  }>;
+  /**
+   * Accepted as free text HERE, and screened per-row in the projection.
+   *
+   * Upstream derives it from an unvalidated free-text form field
+   * (`type.toLowerCase().replace(/_/g, '-')`), so an Estonian title yields an
+   * Estonian slug — `üldtingimused` — and a title with a space yields a slug
+   * with a space. A character-class regex on the RESPONSE schema would fail
+   * `legalDocumentsResponseSchema` for the whole payload, so one newly
+   * authored document would take the entire resource offline every six hours
+   * until someone edited it upstream. The blast radius belongs at one row.
+   */
+  slug: z.ZodString;
+  htmlContentEt: z.ZodString;
+  htmlContentEn: z.ZodString;
+  order: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+  type: string;
+  slug: string;
+  title: {
+    et: string;
+    en: string;
+  };
+  order: number;
+  htmlContentEt: string;
+  htmlContentEn: string;
+}, {
+  type: string;
+  slug: string;
+  title: {
+    et: string;
+    en: string;
+  };
+  order: number;
+  htmlContentEt: string;
+  htmlContentEn: string;
+}>;
+type LegalDocumentRow = z.infer<typeof legalDocumentRowSchema>;
+/**
+ * `success: z.literal(true)` is the load-bearing clause, not decoration.
+ *
+ * Every upstream failure path sets `success: false` — 401 (missing header,
+ * wrong scheme, wrong key, AND an unset server-side key: all four
+ * indistinguishable, deny-by-default through one branch), 429, and 500. No
+ * route returns 200 with a degraded body. So the discriminator is `success`,
+ * never array length, and a snapshot that fails this schema can never be
+ * mistaken for an authoritative empty one.
+ */
+declare const roomTypesResponseSchema: z.ZodObject<{
+  success: z.ZodLiteral<true>;
+  roomTypes: z.ZodArray<z.ZodObject<{
+    code: z.ZodString;
+    name: z.ZodObject<{
+      et: z.ZodString;
+      en: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+      et: string;
+      en: string;
+    }, {
+      et: string;
+      en: string;
+    }>;
+    totalArea: z.ZodNullable<z.ZodString>;
+    livingArea: z.ZodNullable<z.ZodString>;
+    commonArea: z.ZodNullable<z.ZodString>;
+    capacity: z.ZodNullable<z.ZodNumber>;
+    monthlyRent: z.ZodNullable<z.ZodString>;
+    discountedRent: z.ZodNullable<z.ZodString>;
+    dailyRent: z.ZodNullable<z.ZodString>;
+    placesOccupied: z.ZodNullable<z.ZodNumber>;
+  }, "strip", z.ZodTypeAny, {
+    code: string;
+    name: {
+      et: string;
+      en: string;
+    };
+    totalArea: string | null;
+    livingArea: string | null;
+    commonArea: string | null;
+    capacity: number | null;
+    placesOccupied: number | null;
+    monthlyRent: string | null;
+    dailyRent: string | null;
+    discountedRent: string | null;
+  }, {
+    code: string;
+    name: {
+      et: string;
+      en: string;
+    };
+    totalArea: string | null;
+    livingArea: string | null;
+    commonArea: string | null;
+    capacity: number | null;
+    placesOccupied: number | null;
+    monthlyRent: string | null;
+    dailyRent: string | null;
+    discountedRent: string | null;
+  }>, "many">;
+}, "strip", z.ZodTypeAny, {
+  success: true;
+  roomTypes: {
+    code: string;
+    name: {
+      et: string;
+      en: string;
+    };
+    totalArea: string | null;
+    livingArea: string | null;
+    commonArea: string | null;
+    capacity: number | null;
+    placesOccupied: number | null;
+    monthlyRent: string | null;
+    dailyRent: string | null;
+    discountedRent: string | null;
+  }[];
+}, {
+  success: true;
+  roomTypes: {
+    code: string;
+    name: {
+      et: string;
+      en: string;
+    };
+    totalArea: string | null;
+    livingArea: string | null;
+    commonArea: string | null;
+    capacity: number | null;
+    placesOccupied: number | null;
+    monthlyRent: string | null;
+    dailyRent: string | null;
+    discountedRent: string | null;
+  }[];
+}>;
+declare const legalDocumentsResponseSchema: z.ZodObject<{
+  success: z.ZodLiteral<true>;
+  documents: z.ZodArray<z.ZodObject<{
+    type: z.ZodString;
+    title: z.ZodObject<{
+      et: z.ZodString;
+      en: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+      et: string;
+      en: string;
+    }, {
+      et: string;
+      en: string;
+    }>;
+    /**
+     * Accepted as free text HERE, and screened per-row in the projection.
+     *
+     * Upstream derives it from an unvalidated free-text form field
+     * (`type.toLowerCase().replace(/_/g, '-')`), so an Estonian title yields an
+     * Estonian slug — `üldtingimused` — and a title with a space yields a slug
+     * with a space. A character-class regex on the RESPONSE schema would fail
+     * `legalDocumentsResponseSchema` for the whole payload, so one newly
+     * authored document would take the entire resource offline every six hours
+     * until someone edited it upstream. The blast radius belongs at one row.
+     */
+    slug: z.ZodString;
+    htmlContentEt: z.ZodString;
+    htmlContentEn: z.ZodString;
+    order: z.ZodNumber;
+  }, "strip", z.ZodTypeAny, {
+    type: string;
+    slug: string;
+    title: {
+      et: string;
+      en: string;
+    };
+    order: number;
+    htmlContentEt: string;
+    htmlContentEn: string;
+  }, {
+    type: string;
+    slug: string;
+    title: {
+      et: string;
+      en: string;
+    };
+    order: number;
+    htmlContentEt: string;
+    htmlContentEn: string;
+  }>, "many">;
+}, "strip", z.ZodTypeAny, {
+  success: true;
+  documents: {
+    type: string;
+    slug: string;
+    title: {
+      et: string;
+      en: string;
+    };
+    order: number;
+    htmlContentEt: string;
+    htmlContentEn: string;
+  }[];
+}, {
+  success: true;
+  documents: {
+    type: string;
+    slug: string;
+    title: {
+      et: string;
+      en: string;
+    };
+    order: number;
+    htmlContentEt: string;
+    htmlContentEn: string;
+  }[];
+}>;
+//#endregion
+//#region src/projection.d.ts
+/** Injected at the seam; see the module docblock for why it is not imported. */
+type HtmlSanitizer = (html: string) => string;
+interface ProjectionOptions {
+  /** The locale whose values live on the base entity row. `et` or `en`. */
+  readonly defaultLocale: string;
+}
+interface ProjectedRow {
+  /** The business key — `room_type.code` or `legal_document.type`. */
+  readonly key: string;
+  /** Base-row fields, including the default locale's values for translatable fields. */
+  readonly base: Record<string, unknown>;
+  /**
+   * Translatable values for the non-default locale, or `null` when that
+   * locale's text is empty upstream. `null` means "unpublish that locale",
+   * never "write an empty string".
+   */
+  readonly secondary: Record<string, unknown> | null;
+  readonly hash: string;
+}
+interface SkippedRow {
+  readonly key: string;
+  readonly reason: string;
+}
+interface ProjectionResult {
+  readonly projected: readonly ProjectedRow[];
+  readonly skipped: readonly SkippedRow[];
+}
+/** The locale that is NOT the base row's. */
+declare function secondaryLocaleOf(defaultLocale: string): string;
+declare function projectRoomTypes(rows: readonly RoomTypeRow[], options: ProjectionOptions): ProjectionResult;
+declare function projectLegalDocuments(rows: readonly LegalDocumentRow[], options: ProjectionOptions, sanitize: HtmlSanitizer): ProjectionResult;
+//#endregion
+//#region src/apply.d.ts
+/**
+ * The `AdminClient` surface the sync uses, structurally.
+ *
+ * Declared rather than imported so the apply logic is unit-testable with a
+ * fake — CI runs unit tests only, with no database, so a design that could
+ * only be exercised by an integration test would in practice be exercised by
+ * nothing.
+ */
+interface SyncEntityClient {
+  findMany(options: {
+    limit: number;
+  }): Promise<Record<string, unknown>[]>;
+  create(data: Record<string, unknown>): Promise<Record<string, unknown>>;
+  update(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+  updateForLocale(id: string, data: Record<string, unknown>, locale: string): Promise<Record<string, unknown>>;
+  deleteTranslation(id: string, locale: string): Promise<void>;
+}
+interface SyncLogger {
+  info(obj: Record<string, unknown>, msg: string): void;
+  warn(obj: Record<string, unknown>, msg: string): void;
+  error(obj: Record<string, unknown>, msg: string): void;
+}
+interface ApplyCounts {
+  created: number;
+  updated: number;
+  retired: number;
+  unchanged: number;
+  failed: number;
+}
+/** Thrown when at least one row failed; carries the counts that were achieved. */
+declare class YhikasApplyPartialError extends Error {
+  readonly counts: ApplyCounts;
+  constructor(resource: SyncResource, counts: ApplyCounts);
+}
+declare function readLocalRows(client: SyncEntityClient, keyField: string, limit: number): Promise<LocalRow[]>;
+interface ApplyPlanInput {
+  readonly resource: SyncResource;
+  readonly plan: DiffPlan<ProjectedRow>;
+  readonly client: SyncEntityClient;
+  /** The locale that is NOT on the base row — the one whose publish state is toggled. */
+  readonly secondaryLocale: string;
+  readonly logger: SyncLogger;
+}
+declare function applyPlan(input: ApplyPlanInput): Promise<ApplyCounts>;
+//#endregion
+//#region src/entities/guard.d.ts
+/** Thrown when a writer other than the sync tries to mutate synced content. */
+declare class YhikasSyncedContentReadOnlyError extends Error {
+  constructor(entityName: string, action: 'create' | 'update' | 'delete' | 'bulk update', actorId: string);
+}
+/**
+ * Refuse every create/update/delete not performed by the sync actor.
+ *
+ * @param entityName Used only in the refusal message — the hook context does
+ *   not carry the entity name in a shape this can rely on.
+ */
+declare function machineWritten<N extends string>(entityName: N): Behavior<Record<never, never>, `yhikas-sync:machine-written:${N}`>;
+//#endregion
+//#region src/entities/legal-document.d.ts
+/**
+ * `yhikas_legal_document` — the local projection of yhikas-admin's
+ * `legal_document` (active rows only; the upstream route filters
+ * `is_active = true` server-side so an unpublished draft cannot leak).
+ *
+ * ## The body is HTML, and it is sanitized on the way in
+ *
+ * Upstream stores raw TipTap-authored HTML in parallel `html_content_et` /
+ * `html_content_en` columns, so this side stores and renders trusted HTML
+ * rather than markdown. Every value passes through `@murumets-ee/blocks`'
+ * allowlist-based `sanitizeHtml()` at INGEST, not at render: sanitizing at the
+ * boundary means the stored bytes are already safe, so a future reader that
+ * forgets to sanitize is not a stored-XSS hole.
+ *
+ * "It comes from our own admin" is not a reason to skip it — F006 is precisely
+ * why. The upstream price mutations are unauthenticated, which means the
+ * premise that this content is trusted is weaker than it looks, and the sync
+ * would propagate whatever it was handed with complete fidelity.
+ *
+ * ## Security
+ *
+ * Same two controls as `yhikas_room_type`: deny-by-default for every non-admin
+ * role, plus `machineWritten` refusing any writer that is not the sync actor.
+ * `access` is advisory metadata only.
+ */
+declare const YHIKAS_LEGAL_DOCUMENT_ENTITY = "yhikas_legal_document";
+declare const YhikasLegalDocument: import("@murumets-ee/entity").Entity<{
+  id: import("@murumets-ee/entity").IdField;
+} & import("@murumets-ee/entity").AuditableFields & import("@murumets-ee/entity").PublishableFields & Record<never, never> & {
+  /**
+   * The business key. `legal_document.type` is `text().notNull().unique()`
+   * upstream — NOT a pgEnum, and there is no TS union anywhere. The five
+   * values seeded today are closed by convention only, so nothing here
+   * validates membership in a list: doing so would turn a newly authored
+   * upstream document into a hard sync failure.
+   */
+  type: import("@murumets-ee/entity").TextField & {
+    readonly required: true;
+    readonly unique: true;
+    readonly indexed: true;
+    readonly maxLength: 190;
+  };
+  title: import("@murumets-ee/entity").TextField & {
+    readonly required: true;
+    readonly translatable: true;
+  };
+  /**
+   * The upstream slug, verbatim — deliberately `field.text` and not
+   * `field.slug`, which would regenerate it from a source field and silently
+   * diverge from the anchor links yhikas-admin already publishes.
+   *
+   * Indexed but NOT unique: it is unique upstream, but the sync writes rows
+   * one at a time, so a run in which two documents exchange slugs would hit
+   * a transient collision mid-run and fail a sync that is not actually
+   * invalid. `type` is the identity and carries the uniqueness guarantee.
+   */
+  sourceSlug: import("@murumets-ee/entity").TextField & {
+    readonly required: true;
+    readonly indexed: true;
+    readonly maxLength: 190;
+  }; /** Sanitized HTML. Translatable: `et` on the base row, `en` in the translations table. */
+  body: import("@murumets-ee/entity").RichTextField & {
+    readonly required: true;
+    readonly translatable: true;
+  }; /** Upstream display order. */
+  order: import("@murumets-ee/entity").NumberField & {
+    readonly integer: true;
+    readonly required: true;
+    readonly default: 0;
+  };
+  /**
+   * Whether the upstream row carried non-empty English content. A
+   * convenience for the renderer — the control is per-locale publish status
+   * (D015). Serving Estonian legal text under an English URL is the failure
+   * this exists to prevent, and it is worse than the document being absent:
+   * rental terms and fire-safety instructions read as correct English-locale
+   * content to every automated check.
+   */
+  hasEnglish: import("@murumets-ee/entity").BooleanField & {
+    readonly required: true;
+    readonly default: false;
+  };
+  /**
+   * Stable hash of the normalized upstream row. `legal_document` DOES carry
+   * an `updated_at` — set by hand rather than by `$onUpdate` — but the public
+   * route deliberately excludes it from the projection, so it is not
+   * available as a change signal on this side.
+   */
+  sourceHash: import("@murumets-ee/entity").TextField & {
+    readonly maxLength: 64;
+  };
+}, "yhikas_legal_document", [import("@murumets-ee/entity").Behavior<import("@murumets-ee/entity").AuditableFields, string>, import("@murumets-ee/entity").Behavior<import("@murumets-ee/entity").PublishableFields, "publishable">, import("@murumets-ee/entity").Behavior<Record<never, never>, "yhikas-sync:machine-written:yhikas_legal_document">]>;
+//#endregion
+//#region src/entities/room-type.d.ts
+/**
+ * `yhikas_room_type` — the local projection of yhikas-admin's `room_type`.
+ *
+ * ## Decimals are text, and that is not a style choice
+ *
+ * `field.number()` maps to Postgres `doublePrecision` unless `integer: true`
+ * — a float8. Every money and area value here arrives from `pg` as a STRING
+ * (`numeric` serialization) and is stored as one, because routing a price
+ * through a binary float introduces rounding that nothing downstream can undo.
+ * `capacity` and `placesOccupied` are genuine integers and use `field.number`.
+ *
+ * ## Nulls are data
+ *
+ * Upstream passes nulls through untouched and says why: "so the site can
+ * decide how to render a missing price rather than displaying a fabricated
+ * zero." None of the price fields is `required`, and the sync substitutes no
+ * defaults — a missing price stays missing all the way to the renderer.
+ *
+ * ## What this side declares
+ *
+ * There is no currency column, no VAT column and no period column upstream;
+ * EUR-net-per-month is a convention held in column NAMING. `currency` and
+ * `vatTreatment` are therefore real columns written with constants, so a
+ * mis-entered source value renders as a visibly wrong number against a
+ * declared unit rather than as a plausible one.
+ *
+ * ## Security
+ *
+ * `access` below is advisory metadata — the firewall does not read it and the
+ * `admin` role bypasses it unconditionally. The real controls are (a)
+ * deny-by-default: `buildInitialRoleDefinitions` grants no non-admin role any
+ * permission on this entity, and (b) `machineWritten`, which refuses every
+ * writer that is not the sync actor, including an administrator in the CRUD
+ * UI. `admin.disableCreate` is a UI affordance, never a gate.
+ */
+declare const YHIKAS_ROOM_TYPE_ENTITY = "yhikas_room_type";
+/** VAT treatments this projection can express. `net` = the amount excludes VAT. */
+declare const VAT_TREATMENTS: readonly ["net", "gross"];
+declare const YhikasRoomType: import("@murumets-ee/entity").Entity<{
+  id: import("@murumets-ee/entity").IdField;
+} & import("@murumets-ee/entity").AuditableFields & import("@murumets-ee/entity").PublishableFields & Record<never, never> & {
+  /**
+   * The business key. `room_type.code` is `notNull().unique()` upstream and
+   * is what identity is keyed on — never the serial `id`, which is an
+   * implementation detail of the other system and would make this system's
+   * content depend on the other's insert order.
+   */
+  code: import("@murumets-ee/entity").TextField & {
+    readonly required: true;
+    readonly unique: true;
+    readonly indexed: true;
+    readonly maxLength: 190;
+  }; /** Translatable: `et` on the base row, `en` in `yhikas_room_type_translations`. */
+  name: import("@murumets-ee/entity").TextField & {
+    readonly required: true;
+    readonly translatable: true;
+  }; /** Areas in m², as strings. See the note on decimals above. */
+  totalArea: import("@murumets-ee/entity").TextField & {
+    readonly maxLength: 32;
+  };
+  livingArea: import("@murumets-ee/entity").TextField & {
+    readonly maxLength: 32;
+  };
+  commonArea: import("@murumets-ee/entity").TextField & {
+    readonly maxLength: 32;
+  };
+  capacity: import("@murumets-ee/entity").NumberField & {
+    readonly integer: true;
+  };
+  placesOccupied: import("@murumets-ee/entity").NumberField & {
+    readonly integer: true;
+  };
+  /**
+   * Period is carried in the field NAME rather than in a `period` column,
+   * deliberately: one row holds both a monthly and a daily rate, so a single
+   * period column could only ever be wrong about one of them.
+   */
+  monthlyRent: import("@murumets-ee/entity").TextField & {
+    readonly maxLength: 32;
+  };
+  discountedMonthlyRent: import("@murumets-ee/entity").TextField & {
+    readonly maxLength: 32;
+  };
+  dailyRent: import("@murumets-ee/entity").TextField & {
+    readonly maxLength: 32;
+  }; /** Declared by this side; not data upstream. */
+  currency: import("@murumets-ee/entity").TextField & {
+    readonly required: true;
+    readonly maxLength: 3;
+    readonly default: "EUR";
+  };
+  vatTreatment: import("@murumets-ee/entity").SelectField & {
+    options: readonly ["net", "gross"];
+  } & {
+    readonly options: readonly ["net", "gross"];
+    readonly required: true;
+    readonly default: "net";
+  };
+  /**
+   * Whether the upstream row carried a non-empty English name. A convenience
+   * for a renderer building an English price sheet — NOT the control. The
+   * control is per-locale publish status (D015): when this is `false` the
+   * `en` locale is unpublished, so the public read path cannot serve it
+   * whether or not anyone reads this flag.
+   */
+  hasEnglish: import("@murumets-ee/entity").BooleanField & {
+    readonly required: true;
+    readonly default: false;
+  };
+  /**
+   * Stable hash of the normalized upstream row. `room_type` carries no
+   * timestamp of any kind — no `created_at`, no `updated_at`, no version —
+   * so this is the only available change signal, and without it every run
+   * would rewrite all ~25 rows and fill the audit log with ~100 no-op
+   * updates a day.
+   */
+  sourceHash: import("@murumets-ee/entity").TextField & {
+    readonly maxLength: 64;
+  };
+}, "yhikas_room_type", [import("@murumets-ee/entity").Behavior<import("@murumets-ee/entity").AuditableFields, string>, import("@murumets-ee/entity").Behavior<import("@murumets-ee/entity").PublishableFields, "publishable">, import("@murumets-ee/entity").Behavior<Record<never, never>, "yhikas-sync:machine-written:yhikas_room_type">]>;
+//#endregion
+//#region src/entity-client.d.ts
+/** The `AdminClient` methods the adapter forwards, structurally. */
+type AdminClientLike = ReturnType<ToolkitApp['getClient']>;
+/**
+ * @param defaultLocale The app's REAL default locale — resolved from
+ *   `@murumets-ee/content`, never configured. It is passed explicitly on every
+ *   `updateForLocale` call and is not optional, because
+ *   `elevateRequestContext` deliberately strips `locale`/`defaultLocale` from
+ *   the context it builds, and `updateForLocale` THROWS when it can resolve
+ *   the default locale from neither the options nor the context.
+ */
+declare function toSyncEntityClient(client: AdminClientLike, defaultLocale: string): SyncEntityClient;
+//#endregion
+//#region src/sync-state-table.d.ts
+/**
+ * `yhikas_sync_state` — one row per synced resource, recording when that
+ * resource last synced successfully.
+ *
+ * ## Why this table exists at all
+ *
+ * Phase 05 hoped the job could record success through
+ * `@murumets-ee/queue`'s `heartbeats-table.ts` "rather than inventing a status
+ * field". Measured (R012 §1), that is not available:
+ *
+ * - `toolkit_worker_heartbeats` is keyed on `workerId` — one row per worker
+ *   PROCESS. It answers "is any worker alive", never "did this schedule fire".
+ * - `QueueAlerter.recordFailure` is reached from exactly one place,
+ *   `failJob`'s dead-letter branch, so it fires only on a job that RAN and
+ *   THREW. A job that never starts produces no error and therefore no alert.
+ *
+ * The failure S7 requires be observable — a job that silently stops running
+ * while the site keeps serving last month's prices — is precisely the one
+ * neither can see. So the detection is new; only the alert channel is
+ * inherited (the watchdog throws, and the throw reaches the shipped
+ * dedupe/digest/email path).
+ *
+ * This is infrastructure, not content: `defineTable` + `TableClient`, per
+ * CLAUDE.md's two-tier rule. It is also the surface a human or a monitor reads
+ * to answer "how stale is the site's price sheet right now", which is what
+ * makes the staleness observable rather than merely bounded.
+ */
+declare const yhikasSyncStateTable: {
+  table: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: string;
+    schema: undefined;
+    columns: {
+      [x: string]: import("drizzle-orm/pg-core").PgColumn<{
+        name: string;
+        tableName: string;
+        dataType: import("drizzle-orm").ColumnDataType;
+        columnType: string;
+        data: unknown;
+        driverParam: unknown;
+        notNull: false;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: string[] | undefined;
+        baseColumn: never;
+        identity: undefined;
+        generated: undefined;
+      }, {}, {}>;
+    };
+    dialect: "pg";
+  }>;
+  schema: import("@murumets-ee/db").TableDefinition<{
+    /** `room_types` | `legal_documents` — see `SyncResource`. */readonly resource: import("@murumets-ee/db").ColumnFactory<string, "varchar", true, false>;
+    /**
+     * When this resource was first tracked. The watchdog measures staleness
+     * from `lastSuccessAt ?? firstSeenAt`, so a sync that has NEVER once
+     * succeeded eventually alerts instead of looking indistinguishable from
+     * one that is merely young.
+     */
+    readonly firstSeenAt: import("@murumets-ee/db").ColumnFactory<Date, "timestamp", true, true>; /** Updated on every run, successful or not. */
+    readonly lastAttemptAt: import("@murumets-ee/db").ColumnFactory<Date, "timestamp", false, false>; /** Updated ONLY on a fully applied run. This is what the watchdog reads. */
+    readonly lastSuccessAt: import("@murumets-ee/db").ColumnFactory<Date, "timestamp", false, false>;
+    /**
+     * The last failure's message, cleared on the next success. Bounded, and
+     * carries no credential: the client never puts a response body or a key
+     * into an error message.
+     */
+    readonly lastError: import("@murumets-ee/db").ColumnFactory<string, "varchar", false, false>; /** Counts from the last successful run — what a human wants to see first. */
+    readonly lastCreated: import("@murumets-ee/db").ColumnFactory<number, "integer", true, true>;
+    readonly lastUpdated: import("@murumets-ee/db").ColumnFactory<number, "integer", true, true>;
+    readonly lastRetired: import("@murumets-ee/db").ColumnFactory<number, "integer", true, true>;
+    readonly lastUnchanged: import("@murumets-ee/db").ColumnFactory<number, "integer", true, true>;
+  }>;
+  columnKinds: Readonly<Record<string, import("@murumets-ee/db").ColumnKind>>;
+  primaryKeyColumns: readonly string[];
+  makeClient: (database: import("drizzle-orm/postgres-js").PostgresJsDatabase) => import("@murumets-ee/db").TableClient<{
+    /** `room_types` | `legal_documents` — see `SyncResource`. */readonly resource: import("@murumets-ee/db").ColumnFactory<string, "varchar", true, false>;
+    /**
+     * When this resource was first tracked. The watchdog measures staleness
+     * from `lastSuccessAt ?? firstSeenAt`, so a sync that has NEVER once
+     * succeeded eventually alerts instead of looking indistinguishable from
+     * one that is merely young.
+     */
+    readonly firstSeenAt: import("@murumets-ee/db").ColumnFactory<Date, "timestamp", true, true>; /** Updated on every run, successful or not. */
+    readonly lastAttemptAt: import("@murumets-ee/db").ColumnFactory<Date, "timestamp", false, false>; /** Updated ONLY on a fully applied run. This is what the watchdog reads. */
+    readonly lastSuccessAt: import("@murumets-ee/db").ColumnFactory<Date, "timestamp", false, false>;
+    /**
+     * The last failure's message, cleared on the next success. Bounded, and
+     * carries no credential: the client never puts a response body or a key
+     * into an error message.
+     */
+    readonly lastError: import("@murumets-ee/db").ColumnFactory<string, "varchar", false, false>; /** Counts from the last successful run — what a human wants to see first. */
+    readonly lastCreated: import("@murumets-ee/db").ColumnFactory<number, "integer", true, true>;
+    readonly lastUpdated: import("@murumets-ee/db").ColumnFactory<number, "integer", true, true>;
+    readonly lastRetired: import("@murumets-ee/db").ColumnFactory<number, "integer", true, true>;
+    readonly lastUnchanged: import("@murumets-ee/db").ColumnFactory<number, "integer", true, true>;
+  }, import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: string;
+    schema: undefined;
+    columns: {
+      [x: string]: import("drizzle-orm/pg-core").PgColumn<{
+        name: string;
+        tableName: string;
+        dataType: import("drizzle-orm").ColumnDataType;
+        columnType: string;
+        data: unknown;
+        driverParam: unknown;
+        notNull: false;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: string[] | undefined;
+        baseColumn: never;
+        identity: undefined;
+        generated: undefined;
+      }, {}, {}>;
+    };
+    dialect: "pg";
+  }>>;
+};
+//#endregion
+//#region src/sync-state.d.ts
+interface SyncStateRecord {
+  readonly resource: string;
+  readonly firstSeenAt: Date;
+  readonly lastAttemptAt: Date | null;
+  readonly lastSuccessAt: Date | null;
+  readonly lastError: string | null;
+}
+interface SyncStateStore {
+  /** Create the row if absent, so the watchdog can measure a never-ran sync from somewhere. */
+  ensure(resource: SyncResource, now: Date): Promise<void>;
+  recordAttempt(resource: SyncResource, now: Date): Promise<void>;
+  recordSuccess(resource: SyncResource, now: Date, counts: ApplyCounts): Promise<void>;
+  recordFailure(resource: SyncResource, now: Date, error: string): Promise<void>;
+  readAll(): Promise<SyncStateRecord[]>;
+}
+type SyncStateClient = ReturnType<typeof yhikasSyncStateTable.makeClient>;
+declare function truncateError(message: string): string;
+declare function createSyncStateStore(client: SyncStateClient): SyncStateStore;
+//#endregion
+//#region src/upstream/client.d.ts
+interface YhikasUpstreamClientOptions {
+  /** Origin of the yhikas-admin deployment. Must be http or https. */
+  baseUrl: string;
+  /** The sync's OWN bearer credential — never the site's (see `API_KEY_ENV_VAR`). */
+  apiKey: string;
+  /** Per-request deadline in milliseconds. */
+  timeoutMs: number;
+  /** Injectable for tests. Defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch;
+}
+declare class YhikasUpstreamClient {
+  #private;
+  constructor(options: YhikasUpstreamClientOptions);
+  /** `GET /api/public/room-types`. Ordered by `code` upstream; unpaginated. */
+  fetchRoomTypes(): Promise<RoomTypeRow[]>;
+  /** `GET /api/public/legal-documents`. Active only, ordered by `order`; unpaginated. */
+  fetchLegalDocuments(): Promise<LegalDocumentRow[]>;
+}
+//#endregion
+//#region src/run-sync.d.ts
+interface SyncRunDeps {
+  readonly upstream: YhikasUpstreamClient;
+  readonly roomTypeClient: SyncEntityClient;
+  readonly legalDocumentClient: SyncEntityClient;
+  readonly state: SyncStateStore;
+  readonly sanitizeHtml: HtmlSanitizer;
+  readonly logger: SyncLogger;
+  readonly defaultLocale: string;
+  readonly floor: SanityFloor;
+  /** Injectable so tests are not order-dependent on the wall clock. */
+  readonly now?: () => Date;
+}
+interface ResourceOutcome {
+  readonly resource: SyncResource;
+  readonly ok: boolean;
+  readonly counts: ApplyCounts | null;
+  readonly skipped: number;
+  readonly error: string | null;
+}
+interface SyncRunSummary {
+  readonly outcomes: readonly ResourceOutcome[];
+  readonly ok: boolean;
+}
+/** Thrown when at least one resource failed, so the queue retries and eventually alerts. */
+declare class YhikasSyncRunError extends Error {
+  readonly summary: SyncRunSummary;
+  constructor(summary: SyncRunSummary);
+}
+declare function runYhikasSync(deps: SyncRunDeps): Promise<SyncRunSummary>;
+//#endregion
+//#region src/upstream/errors.d.ts
+type UpstreamFailureKind = /** DNS failure, connection refused, TLS error — the request never completed. */'network' /** The per-request deadline elapsed. The queue has no per-job timeout (R012 §3). */ | 'timeout' /** A completed response the sync will not act on: 401, 429, 5xx, or any non-2xx. */ | 'http' /** A 2xx whose body failed the wire schema — including `success: false`. */ | 'shape';
+declare class YhikasUpstreamError extends Error {
+  readonly resource: SyncResource;
+  readonly kind: UpstreamFailureKind;
+  readonly status: number | undefined;
+  constructor(resource: SyncResource, kind: UpstreamFailureKind, message: string, options?: {
+    status?: number;
+    cause?: unknown;
+  });
+}
+/**
+ * Thrown when a snapshot IS authoritative but applying it would be reckless —
+ * the D016 guards. Separate from {@link YhikasUpstreamError} because the
+ * remedies differ: an upstream failure usually resolves itself on the next
+ * run, whereas this one wants a human to look at why the source shrank.
+ */
+declare class YhikasSyncRefusedError extends Error {
+  readonly resource: SyncResource;
+  readonly reason: 'empty-snapshot' | 'retire-fraction' | 'oversized-snapshot' | 'duplicate-key';
+  constructor(resource: SyncResource, reason: YhikasSyncRefusedError['reason'], message: string);
+}
+//#endregion
+//#region src/watchdog.d.ts
+interface ResourceStaleness {
+  readonly resource: SyncResource;
+  /** `null` when this resource has never once synced successfully. */
+  readonly lastSuccessAt: Date | null;
+  /** Age of the last success, or of the tracking row when there has never been one. */
+  readonly ageMs: number;
+  readonly stale: boolean;
+  readonly lastError: string | null;
+}
+/** Thrown to reach the queue's dead-letter alerting. */
+declare class YhikasSyncStaleError extends Error {
+  readonly stale: readonly ResourceStaleness[];
+  constructor(stale: readonly ResourceStaleness[], staleAfterMs: number);
+}
+/**
+ * Assess every in-scope resource.
+ *
+ * A resource with no state row at all counts as stale with an age of
+ * `Infinity`: "nothing has ever written this row" is the loudest possible
+ * version of "this sync has never run", and treating a missing row as
+ * not-yet-stale would make an install that never once synced look healthy
+ * forever — the exact unobserved-bound failure S7 names.
+ *
+ * A resource that HAS a row but no success is measured from `firstSeenAt`, so
+ * a freshly installed sync gets one full window to succeed before it alerts.
+ */
+declare function assessStaleness(records: readonly SyncStateRecord[], now: Date, staleAfterMs: number): ResourceStaleness[];
+/**
+ * Assess, and throw if anything is stale.
+ *
+ * @throws {YhikasSyncStaleError} which the queue turns into a dead-lettered
+ *   job and therefore into the shipped alert.
+ */
+declare function assertNotStale(records: readonly SyncStateRecord[], now: Date, staleAfterMs: number): ResourceStaleness[];
+//#endregion
+export { API_KEY_ENV_VAR, type AdminClientLike, type ApplyCounts, type ApplyPlanInput, BASE_URL_ENV_VAR, DECLARED_CURRENCY, DECLARED_VAT_TREATMENT, type DiffPlan, EN_LOCALE, ET_LOCALE, type HtmlSanitizer, LEGAL_DOCUMENTS_RESOURCE, type LegalDocumentRow, type LocalRow, type MultilingualText, type PlanDiffInput, type ProjectedRow, type ProjectionOptions, type ProjectionResult, ROOM_TYPES_RESOURCE, type ResolvedYhikasSyncConfig, type ResourceOutcome, type ResourceStaleness, type RoomTypeRow, SYNC_JOB_NAME, SYNC_RESOURCES, type SanityFloor, type SkippedRow, type SyncEntityClient, type SyncLogger, type SyncResource, type SyncRunDeps, type SyncRunSummary, type SyncStateRecord, type SyncStateStore, type UpstreamFailureKind, VAT_TREATMENTS, WATCHDOG_JOB_NAME, YHIKAS_LEGAL_DOCUMENT_ENTITY, YHIKAS_ROOM_TYPE_ENTITY, YHIKAS_SYNC_ACTOR_ID, YHIKAS_SYNC_PLUGIN_NAME, YhikasApplyPartialError, YhikasLegalDocument, YhikasRoomType, type YhikasSyncConfig, YhikasSyncConfigError, YhikasSyncRefusedError, YhikasSyncRunError, YhikasSyncStaleError, YhikasSyncedContentReadOnlyError, YhikasUpstreamClient, type YhikasUpstreamClientOptions, YhikasUpstreamError, applyPlan, assertNotStale, assessStaleness, createSyncStateStore, legalDocumentRowSchema, legalDocumentsResponseSchema, machineWritten, multilingualTextSchema, planDiff, projectLegalDocuments, projectRoomTypes, readLocalRows, resolveYhikasSyncConfig, roomTypeRowSchema, roomTypesResponseSchema, runYhikasSync, secondaryLocaleOf, stableHash, toSyncEntityClient, truncateError, yhikasSyncStateTable };
+//# sourceMappingURL=index.d.mts.map