@murumets-ee/yhikas-sync 0.38.0

package/LICENSE

@@ -0,0 +1,94 @@
+Elastic License 2.0 (ELv2)
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company
+makes such a claim, your patent license ends immediately for work on behalf
+of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license
+no later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your
+licenses to terminate automatically and permanently.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is
+the software the licensor makes available under these terms, including any
+portion of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or
+the power to direct the management and policies of an entity (for example, by
+voting right, contract, or otherwise). Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your
+licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,192 @@
+# `@murumets-ee/yhikas-sync`
+
+A scheduled, one-directional pull of yhikas-admin's **room types** and **legal
+documents** into lumi-cms content, so the yhikas public site reads exactly one
+origin — its own content-api — and never learns that yhikas-admin exists.
+
+Part of the `frontend-delivery` plan, phase 05 (D014).
+
+## Why a pull and not a push
+
+Three independent facts, each of which would decide it alone:
+
+- **There is nothing to push with.** yhikas-admin has no webhook dispatch, no
+  outbound content HTTP, no content queue and no DB triggers. Its ~30
+  `revalidatePath`/`revalidateTag` calls all target admin pages — in-process
+  Next cache invalidation that never crosses a process boundary.
+- **Its own rules discourage building one.** That app's CLAUDE.md rule 5 is
+  "NEVER create API routes for internal data operations", with rule 6 carving
+  out third-party integrations needing HTTP endpoints. A pull-only reader of
+  `/api/public/*` sits in the carve-out; a push dispatcher does not.
+- **Nothing needs pushing.** `git log -S "monthlyRent" -- src/db/schema.ts`
+  returns one commit — the initial one, 2025-05-14 — against a repo whose HEAD
+  is 2026-08-03. This is a fee schedule revised at most yearly.
+
+The diff is **full-snapshot**, and that is forced rather than chosen:
+`room_type` carries no timestamp of any kind, and `legal_document`'s
+`updated_at` is not in the API response. There is no cursor and no change feed.
+
+## Wiring
+
+```ts
+// lumi.config.ts
+import { content } from '@murumets-ee/content/plugin'
+import { queue } from '@murumets-ee/queue/plugin'
+import { yhikasSync } from '@murumets-ee/yhikas-sync/plugin'
+
+export default defineLumiConfig({
+  plugins: [content({ /* … */ }), queue(), yhikasSync()],
+})
+```
+
+Both `@murumets-ee/content` and `@murumets-ee/queue` are declared in
+`Plugin.requires`, so a misconfigured install fails at boot rather than at the
+first sync — see "Per-locale publish" below for why content in particular is a
+hard requirement rather than a nicety.
+
+### Environment
+
+| Variable | Purpose |
+|---|---|
+| `YHIKAS_ADMIN_BASE_URL` | Origin of the yhikas-admin deployment, e.g. the Docker-internal `http://yhikas-admin:3000`. |
+| `YHIKAS_SYNC_API_KEY` | The sync's **own** bearer credential. |
+
+The credential is deliberately **not** the site's `PUBLIC_SITE_API_KEY`.
+Upstream's rate limiter buckets on `sha256(key).slice(0,16)` rather than on the
+caller IP — over the Docker-internal path there is no `x-forwarded-for` and
+every caller resolves to `'unknown'` — so a shared key means a shared 60/min
+bucket, and revoking one credential would blind both consumers.
+
+The key is never part of the plugin's declared config: resolved config lands in
+the framework's `PluginConfigRegistry`, a process-global any plugin can read,
+and a secret does not belong there. It is read from the environment at job-run
+time.
+
+## What it does, and what it refuses to do
+
+### Identity is the business key
+
+`room_type.code` and `legal_document.type` — 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.
+
+### Semantics 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*. So `currency` and
+`vatTreatment` are real columns here, written with constants, which means a
+mis-entered source value renders as a **visibly wrong number against a declared
+unit** rather than as a plausible one. Period stays in the field name
+(`monthlyRent` / `dailyRent`) because one row carries two different periods.
+
+Decimals stay **strings** end to end. `pg` returns `numeric` as a string and
+upstream passes it through; parsing to a float would put rounding into a price.
+Nulls likewise pass through untouched — a missing price is data, not a zero.
+
+### Per-locale publish, and why `content` is required
+
+One upstream row becomes one entity row with a translation per locale. When the
+English text is empty — both columns are `notNull` upstream but nothing
+validates non-emptiness, so `""` is the expected state of a half-filled row —
+the English locale is set to `draft` and its translation row deleted. No empty
+string is ever written as a translation value, and the English page cannot
+render rather than rendering Estonian text under an English URL.
+
+That mechanism is `AdminClient.updateForLocale`, which routes a non-default
+locale's `status` into `<entity>_locale_status`. Two of its preconditions are
+load-bearing, and both fail SILENTLY rather than loudly:
+
+- **The locale-status writer must exist.** Without it `updateForLocale` falls
+  back to the base row's `status` column, so a request to unpublish English
+  would unpublish Estonian. The writer is installed by
+  `@murumets-ee/content`'s `init`, for entities that are `publishable()` with
+  at least one translatable field — which both entities here satisfy by
+  construction. `Plugin.requires` guarantees content is *configured*; the
+  *ordering* half is bought by constructing the AdminClients inside the job
+  handler rather than in `init`, because `createAdminClient` reads the writer
+  once, at construction. Hoisting that into `init` would reintroduce the hazard
+  while leaving the declaration green.
+- **The default locale must be resolvable.** `updateForLocale` throws when it
+  can find one in neither its options nor the request context — and
+  `elevateRequestContext`, which the sync runs under, deliberately strips
+  `locale`/`defaultLocale`. So the adapter passes it explicitly on every call,
+  and it is read from `resolveI18nConfig(app)` rather than configured: a
+  configured copy could disagree with the app's real default, and that
+  disagreement writes the wrong language to the base row without failing.
+
+### Deletion is a decision
+
+A row that is published locally and absent upstream is **unpublished, never
+deleted**. The row and its audit trail survive, and a wrongly-retired row heals
+automatically on the next successful run. Two guards, both of which abort the
+whole run before a single write:
+
+1. **Nothing acts on an absence from a response that did not fully succeed.**
+   Every upstream failure path sets `success: false` (401, 429, 500), and the
+   wire schema pins `success: z.literal(true)` — so a refusal can never be
+   mistaken for an authoritative empty snapshot.
+2. **A sanity floor.** An empty snapshot against non-empty local content is
+   refused at any size; a run retiring more than half of at least three
+   published rows is refused. Both are needed: the fraction rule is blind at the
+   two-row size a freshly seeded install lives at, and the empty-snapshot rule
+   is blind to the half-truncated response a partial failure actually produces.
+
+An **oversized** snapshot is also refused rather than truncated — capping at N
+and processing the first N would turn the dropped tail into apparent absences,
+and therefore into mass retirement.
+
+### Synced content is not editor-writable
+
+An editable field the next run silently overwrites is a worse affordance than a
+read-only one, because it looks like it worked. A `machineWritten` behavior
+refuses every create/update/delete on the BASE row whose actor is not
+`yhikas-sync`, including an administrator in the generic CRUD UI. (`access`
+metadata and `admin.hidden` cannot do this — neither is read by the firewall.)
+
+**The boundary, stated because a guard documented as total but actually partial
+is worse than one whose limit is written down:** `saveTranslation` and
+`deleteTranslation` run no behaviour hooks, so an edit made through the admin
+*locale switcher* is not refused — and, because it does not change
+`sourceHash`, the sync will not revert it either. Closing that needs a hook
+seam on the translation write path, which is a framework change; tracked as
+finding 12 on the plan.
+
+## Observability
+
+`yhikas_sync_state` holds one row per resource: when it last attempted, when it
+last **succeeded**, the last error, and the counts from the last successful run.
+
+A second scheduled job — the watchdog — alerts when the newest success is older
+than the window, including the case where a sync has never succeeded at all.
+This is new code because nothing shipped can detect it: the queue's heartbeat is
+keyed on `workerId` and answers "is any worker alive", and its alerter fires
+only from `failJob`'s dead-letter branch, i.e. only on a job that ran and
+*threw*. A job that never starts produces no error at all. The watchdog throws,
+and the throw reaches the shipped dedupe/digest/email path — so the detection is
+new, the delivery is not.
+
+Known limit, stated rather than papered over: the watchdog is itself a scheduled
+job, so a worker that is entirely dead runs neither it nor the sync. That case
+is what the queue's worker heartbeat *does* see. The two are complementary.
+
+## Defaults
+
+| Setting | Default | Why |
+|---|---|---|
+| `schedule` | `@every 6h` | Four successes a day against an annually-revised fee schedule. The interval form rather than cron: the queue's cron parser is UTC-only with no DST awareness, so a wall-clock schedule would shift twice a year. |
+| `watchdogSchedule` | `@every 1h` | |
+| `staleAfterMs` | 24h | Four consecutive failures before anyone is woken. |
+| `requestTimeoutMs` | 15s | The queue has **no** per-job timeout; without a deadline a hung fetch holds a slot until lease recovery re-claims it and runs the handler twice, concurrently. |
+| `maxRowsPerResource` | 500 | ~25 room types today. |
+| `maxRetireFraction` | 0.5 | |
+
+## Scope
+
+**In:** room types and legal documents.
+
+**Out:** `site_info` / `site_notice` — they have no write path anywhere in
+yhikas-admin (no admin UI, no server action, no seed), so a sync would pull the
+route's designed-empty fallback. Recorded as Q1, not dropped. Deposits, which
+ship upstream as hardcoded `null` with no backing column. And any write path
+back into yhikas-admin: the client exposes two methods and both are GETs, so
+one-directionality is a property of the type rather than a rule to remember.

package/dist/config-CHVLiXZf.d.mts

@@ -0,0 +1,77 @@
+//#region src/config.d.ts
+/**
+ * Plugin configuration — pure resolution, no I/O, no `server-only`.
+ *
+ * There is deliberately no `defaultLocale` knob either. The default locale is
+ * read from `@murumets-ee/content`'s `resolveI18nConfig(app)` at job-run time,
+ * because a configured copy could silently disagree with the app's actual
+ * default — and the consequences run both ways: `updateForLocale` would take
+ * its default-locale branch for what this package believed was the secondary
+ * locale and overwrite the base row with the wrong language, while no
+ * translation was written for the real one. Neither write fails. A knob whose
+ * only reachable states are "correct but redundant" and "wrong and silent" is a
+ * trap, not a setting.
+ *
+ * The bearer credential is deliberately NOT part of this object. Resolved
+ * config is stored in the framework's `PluginConfigRegistry`, which is a
+ * process-global any plugin can read; a secret belongs in the environment and
+ * is read at job-run time instead (`resolveCredential`). This mirrors
+ * `@murumets-ee/merit` D003 — the key never lands in a registry or the DB.
+ */
+interface YhikasSyncConfig {
+  /**
+   * Origin of the yhikas-admin deployment, e.g. `http://yhikas-admin:3000`
+   * over the Docker-internal network. Falls back to `YHIKAS_ADMIN_BASE_URL`.
+   */
+  baseUrl?: string;
+  /** Cron/interval expression for the pull. Default `@every 6h` (D017). */
+  schedule?: string;
+  /** Cron/interval expression for the staleness watchdog. Default `@every 1h`. */
+  watchdogSchedule?: string;
+  /** Alert when the newest successful sync is older than this. Default 24h. */
+  staleAfterMs?: number;
+  /** Per-request deadline. The queue has NO per-job timeout (R012 §3). Default 15s. */
+  requestTimeoutMs?: number;
+  /** Refuse a snapshot larger than this rather than truncating it (D016). */
+  maxRowsPerResource?: number;
+  /** Refuse a run retiring more than this fraction of published rows. Default 0.5. */
+  maxRetireFraction?: number;
+  /** The fraction rule only applies once at least this many rows are published. Default 3. */
+  minRowsForRetireFloor?: number;
+  /**
+   * Explicit opt-out. An unconfigured sync is a BROKEN sync, and a broken sync
+   * must be visibly broken (S7) — so an absent credential fails the job loudly
+   * rather than quietly skipping registration. Set this to `false` when the
+   * install genuinely has no yhikas-admin to talk to.
+   */
+  enabled?: boolean;
+}
+interface ResolvedYhikasSyncConfig {
+  readonly baseUrl: string | undefined;
+  readonly schedule: string;
+  readonly watchdogSchedule: string;
+  readonly staleAfterMs: number;
+  readonly requestTimeoutMs: number;
+  readonly maxRowsPerResource: number;
+  readonly maxRetireFraction: number;
+  readonly minRowsForRetireFloor: number;
+  readonly enabled: boolean;
+}
+/** Thrown at plugin construction for a structurally invalid config. */
+declare class YhikasSyncConfigError extends Error {
+  constructor(message: string);
+}
+/**
+ * Resolve config + environment into the frozen object the plugin declares.
+ *
+ * Throws only on a STRUCTURALLY invalid config — a nonsensical number. It never
+ * throws for a missing credential or a missing base URL: `lumi.config.ts` is
+ * loaded at build time by the CLI, and throwing there breaks every `lumi`
+ * command on a machine that simply has no secrets (see
+ * `gotcha_lumi_config_throw_at_build_time`). A missing credential surfaces at
+ * job-run time, where it becomes an alert.
+ */
+declare function resolveYhikasSyncConfig(config?: YhikasSyncConfig, env?: NodeJS.ProcessEnv): ResolvedYhikasSyncConfig;
+//#endregion
+export { resolveYhikasSyncConfig as i, YhikasSyncConfig as n, YhikasSyncConfigError as r, ResolvedYhikasSyncConfig as t };
+//# sourceMappingURL=config-CHVLiXZf.d.mts.map

package/dist/config-CHVLiXZf.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-CHVLiXZf.d.mts","names":[],"sources":["../src/config.ts"],"mappings":";;AA+BA;;;;;;;;;;;;;;AA0BS;AAGT;;;UA7BiB,gBAAA;EA8BN;;;;EAzBT,OAAA;EA8BS;EA5BT,QAAA;EA8BS;EA5BT,gBAAA;EA6BgB;EA3BhB,YAAA;EA+BW;EA7BX,gBAAA;;EAEA,kBAAA;EA2ByC;EAzBzC,iBAAA;EA0BY;EAxBZ,qBAAA;EAwB2B;AAoC7B;;;;;EArDE,OAAA;AAAA;AAAA,UAGe,wBAAA;EAAA,SACN,OAAA;EAAA,SACA,QAAA;EAAA,SACA,gBAAA;EAAA,SACA,YAAA;EAAA,SACA,gBAAA;EAAA,SACA,kBAAA;EAAA,SACA,iBAAA;EAAA,SACA,qBAAA;EAAA,SACA,OAAA;AAAA;;cAIE,qBAAA,SAA8B,KAAK;cAClC,OAAA;AAAA;;;;;;;;;;;iBAoCE,uBAAA,CACd,MAAA,GAAQ,gBAAA,EACR,GAAA,GAAK,MAAA,CAAO,UAAA,GACX,wBAAA"}