Nevai-Public
Netherlands

@nevai/contracts (1.0.0)

Published 2026-10-15 21:43:47 +02:00 by nevai-ci

Installation

@nevai:registry=https://git.nevai.app/api/packages/nevai-public/npm/
npm install @nevai/contracts@1.0.0
"@nevai/contracts": "1.0.0"

About this package

One client-neutral source for validation and transport types. Existing Planning and Classes schemas moved here from Hono; their response types are inferred from those schemas. Hono retains authentication, permissions, repositories, middleware and HTTP errors. UI-only state stays in the client.

Nevai contracts

One client-neutral source for validation and transport types. Existing Planning and Classes schemas moved here from Hono; their response types are inferred from those schemas. Hono retains authentication, permissions, repositories, middleware and HTTP errors. UI-only state stays in the client.

This package is an unpublished release candidate. Connected content-package export, upload, review and transactional concept apply exist in the platform; first-import browser/native and NT Dance acceptance remain open. The former packages/types implementation and its consumers now live under @nevai/contracts/website; the old package is removed from this checkout. Existing published versions and historical Website releases are not deleted. Planning/Courses and Media use shared schemas and inferred response types. Website validators remain the existing tested parsers; converting their remaining handwritten DTO/OpenAPI duplicates is still work, not solved by moving files.

Audit checklist

The machine-readable consumer inventory classifies every current client API adapter, including the separate Student/Teacher services. contracts:check rejects unclassified adapters and new independent definitions of the consolidated names. A green inventory check is not proof of semantic completeness. The current 42 adapters have been reviewed against commands, response decoders and the adapter test files linked per consumer. This final pass corrected Media mutation/usage validation and added direct Account/Page/Form adapter coverage. Future local-review-required or shared-with-remaining-review entries remain explicit open work. Repository interfaces, SQL rows, error classes, UI state and operation-specific projections retain their own owners.

Boundary Current evidence Remaining work
Primitives UUID/resource/locale patterns and version/timestamp schemas share one source; OpenAPI adds metadata only. Normalized workspace locale input remains a distinct operation. Inventory other operation-specific normalizers; do not change their coercion by name matching.
Appointments Requests, response schemas and DTOs share /appointments and /planning; client parses complete records. Create interval default 15 and omission on update stay different. Connected scenario acceptance; authorization and resource availability remain server-owned.
Reservations/shifts Existing requests and workspace schemas share /restaurants; client parses complete records. Recurrence, staff uniqueness, capacities and guest-retention rules stay unchanged. TastyIgniter adapter is deferred; these contracts do not claim engine compatibility.
Website editorial/package/Media Canonical editor/value schemas and tested package adapters serve API, client, offline files and concept writers. Template tools, connected first-import/NT acceptance and existing customer seed migration remain separate gates. Manifest/change-set and Media adapter transport reviews are complete.
Publication transport Readiness uses /website-publication; commands, source selection, hybrid results and change/history pages use /website-publication-transport. Recovery uses /website, rollback uses /website-delivery; exact response scope and historical reads are tested. Privileged runner-control and source-registration transports remain separately owned. Registry publication, template transition and connected deployment acceptance remain open.
Build/deployment responses /website-delivery owns response schemas and inferred DTOs. Runner control claims/requests and source registration remain separately typed; audit those privileged transports before consolidation.
People /people owns existing request/response schemas and inferred DTOs; client validates complete records and invitation results. Connected scenario acceptance; guardian/tenant authority and private invitation digests remain server-owned.
Accounts /account owns profile, closure and preference requests/response DTOs; management and Student/Teacher clients validate responses. Persisted profile checks retain their distinct projection; preference writes omit read-only timestamps. Real client/device acceptance; private avatar Storage data, recent password authentication, last-owner rules and preference scope remain server-owned.
Company login /company-login owns operator input, public branding, aliases and client projection validation. Domain admission, CORS, Auth and private logo storage remain server-owned; aliases are presentation hints.
Access /access owns role/user/invitation request and response schemas; complete client validation retains role consistency checks. Connected acceptance; tenant/owner authority, private token digests and transactional role/lifecycle effects remain server-owned.
Mail /mail owns existing connector/sender commands and complete delivery/workspace schemas, including trial activation. Sender edits omit read-only fields. Provider allowlist, credential storage, queue claims and owner authority remain API-owned.
Inbox /inbox owns configuration/submission/bulk transports and query defaults. Client read defaults and limits derive from API projections; Form IDs match intake. Mutations no longer refetch their complete detail. Connected acceptance; assignment checks, destructive confirmations and legal-hold authority remain server-owned. Bulk selection/repository intent remains distinct from the strict HTTP action union.
Privacy/Retention /privacy and /retention own existing requests and response schemas; clients validate events, complete exports, destruction and exact hold outcomes. Manual verification excludes authenticated-session assertions. Recent-auth, subject authorization/rights, bounded export/destruction and legal-hold policy stay server-owned. Export SQL snapshots intentionally remain heterogeneous records; redacted actor projections differ from full legal holds.
Commerce/Menu Catalogue/order/payment/history responses share /commerce; the client validates nested records and mutation results. Event sales are readable; order commands retain their narrower sources. Menu read/write schemas share /commerce-menu; table-service and remaining command schemas share /commerce. Website Menu types derive from these schemas. Provider credentials, payment authority and financial snapshots stay server-owned.
Calendar export /calendar-export owns requests, redacted workspaces, provider calendar results and token/feed creation identity. Configured destinations use Nevai UUIDs; provider calendar IDs remain external strings. Vault credentials, provider claims and token generation/hashing stay API-owned.
Floor plans /floor-plan owns element/document/read/write schemas and inferred DTOs. The client renderer minimum and root projection derive from shared validation; table assignment, active-plan immutability and tenant permissions remain API-owned.
Planning status /planning-status owns overview/setup and recipient notification schemas/DTOs. Initial setup version zero, exact client notification copy and unread-page constraints remain explicit; counters derive from repository projections, while recipient/tenant authority and optimistic writes remain API-owned.
Planning credits /planning-credits owns ledger/workspace/transfer/expiry and request schemas; foundation credit settings and CourseCreditSettings derive from them. Signed adjustments/deltas, UTC-only write expiry, optional settings update fields and initial version zero remain distinct. Ledger effects, guardian authority and idempotency stay server-owned.
Planning helpers /planning-helpers owns call/application/invitation/assignment/workspace schemas, commands and mutation envelopes. Shared role/version definitions retain defaults and limits. Optional candidate decision assignment differs from required attendance/cancel/complete output. Eligibility, atomic writes and idempotent rewards stay API/database-owned.
Planning News /planning-news owns editorial read/write/list schemas and inferred DTOs. Database status/publication timestamp consistency and client exact-copy projection are explicit; audience/tenant permissions, request identity and optimistic writes stay server-owned.
Planning foundation /planning-foundation owns settings/workspace and location/resource/staff/availability commands, reusing existing entity response schemas. Create defaults, version-zero settings and availability rules stay explicit. Course/Teacher transport is covered by the rows below; table/staff/tenant authority stays server-owned.
Planning Events /planning-events owns management Event/registration commands and responses and Student Event workspace DTOs. Clients validate complete nested replies and availability flags. Held is read-only for management commands; UTC, defaults, duration, staff uniqueness and cancellation reasons are preserved. Student/public paid checkout and cancellation share schemas with the stricter public date/token projection. Clients validate both free/paid envelopes; payments, refund policy and tenant authority stay server-owned.
Planning Courses /courses owns command DTOs, configuration writes and occurrence/promotion replies. Management validates complete mutation responses. Strict versioned updates preserve template refinements and defaults. Enrollment commands exclude read-only helper admissions. Holiday and Teacher transport is covered below; scheduling/credit effects stay in Hono and PostgreSQL.
Planning holidays /planning-holidays owns snapshot/date DTOs and import/manual commands; clients validate complete list and mutation reads. Preserve provider range/uppercase codes versus manual two-character codes. Fetching and transactional tenant snapshot replacement remain server-owned.
Teacher cash /planning-teacher-cash owns policies, requests/workspaces and command DTOs; management and Teacher validate complete replies. Nullable SQL references/unlimited offer validity and version-zero policies remain explicit. Manager identities derive from the base schema. Offer/decision/VAT rules stay shared; authority and sale/credit effects stay server-owned.
Teacher operations /planning-teacher-operations owns Today/student/leave projections and note/promotion/resolution commands; clients validate nested replies and envelopes. Preserve zero approval versions and per-session action versions/reasons. Scheduling, promotion eligibility, affected-session coverage and idempotency remain server-owned. Management Planning and Student adapters are reviewed.
Student Planning /planning-student owns profile/family/Course/attendance/lesson/own-leave contracts; clients validate complete nested reads and mutations. Preserve distinct Student enrollment reads/commands, version-zero lesson content, video limits and leave duration. Family authority, Storage/transcoding and Course effects remain server-owned. Personal schedule reuses shared Planning items; work-state is a UI decoration. Published News validates the exact-copy client projection. Organization selection uses the shared access projection and validates before filtering; the Student adapter is reviewed.
Organization /organization owns HTTP schemas, derived client normalization, settings/feature commands and product/feature/subscription vocabulary. Management and Student validate complete replies. Legacy module defaults and family-to-news mapping are explicit read behavior. Command uniqueness/start-screen rules and zero versions are retained. API repository context keeps fixture/bootstrap optional fields; membership, entitlements and mutation authority remain server-owned.
Organization Setup /organization-setup owns progress counters, step vocabulary and preference commands. Clients validate full progress and save replies. Zero initial versions and unique skipped steps remain supported. Product-derived completion, tenant authority and optimistic saves remain server-owned.
AI tariffs /ai owns provider/rate vocabulary, tariff DTOs and command/read schemas. Clients validate nested rates and output/context limits. Preserve integer micro-euro bounds and finite-date client projection. Revision authority, pricing arithmetic and budget reservation remain API-owned; other Platform/AI adapters remain open.
Platform AI and Help /ai owns redacted connection/task/usage responses and platform commands, plus Help question/history/reply shapes. Clients validate complete results. Preserve initial versus positive versions, integral client usage counters and decimal micro-euro strings. Endpoint/Vault/provider authority, tenant role, rates/budgets and approved citations remain server-owned.
Platform companies /platform owns company/account/subscription/product/domain DTOs and commands; client reads validate nested roles/maintenance, pages and dashboard counters. Derive pending-invitation/nonempty display rules. Preserve product dependencies, periods, hostnames and lifecycle versions. Operator/token/entitlement authority stays server-owned; invitation/transfer receipts and host/service snapshots are shared and validated. Recovery acknowledgement and bodyless revoke are covered; the Platform adapter is reviewed.
Website settings and policy /website-shell owns setting configuration/save/lifecycle/reset schemas and section-derived drafts; /website-publication-policy owns policy transport. Clients validate full replies and the requested setting section. Preserve version-zero policy semantics and immediate targets. Tenant-locale/completeness and target/organization authority remain API-owned; stored JSON is opaque until admitted. Package apply uses the canonical setting command.
Planning/Classes/Calendar and Platform/AI Existing shared Planning/Course policy remains; remaining adapters are individually classified. Review helper/notification/credit/resource and operator/AI DTOs; do not infer completeness from package membership.
Historical releases Archive recovery alone accepts retired field names without changing stored bytes. Retain until retained-artifact recovery has a replacement; active package/import paths get no legacy facade.
Companion template Public remote dev was d47c038d28470baf05b17b3934e636ae117ecbcc during this audit; detached local checkout differs. The public registry returned 404 for the canonical 1.0.0 candidate. In an isolated copy of that remote commit, imports were switched to the locally packed candidate; TypeScript, manifest validation and all 27 adapter test files passed. Registry integrity/production checks and content-package starter/tool migration are not proved by that rehearsal. No registry pin/lock or customer repo is changed before that exact candidate is available.

Ownership

Surface Definition Consumers
Planning responses and public projections src/planning-schemas.ts API and schema-derived DTOs
Privacy and legal-hold transport src/privacy.ts, src/retention.ts API, OpenAPI and complete client validation
Inbox transport src/inbox.ts API, OpenAPI and client response validation/defaults
Mail transport src/mail.ts API, OpenAPI and client response/write projection validation
Company login transport src/company-login.ts API, operator client and client entry branding
Access transport src/access.ts API, OpenAPI and complete client validation
Account transport src/account.ts API, OpenAPI, management and Student/Teacher clients
People transport src/people.ts API, OpenAPI and complete client response validation
Appointment transport src/appointments.ts API and complete client response validation
Restaurant transport src/restaurants.ts API and complete client response validation
Publication transport src/website-publication.ts, src/website-publication-transport.ts API, OpenAPI and complete client response validation
Delivery responses src/website-delivery.ts API DTOs and OpenAPI
Course requests src/course-inputs.ts API
Course workspace src/course-workspace.ts API and client response validation
Course response DTOs src/course-model.ts API repositories and client
Media files/catalogue src/media.ts API, client and content package
Website/Access/Menu contracts src/website/ API, client, workers and import tools
Editable package and field values src/content-package.ts Offline inspection, Hono transfer and App editor
Editable export creation src/content-export.ts Hono and App creation metadata
Editable JSON merge review src/content-package-review.ts Hono and App review requests/responses
Checksum-bound Media reviews src/content-media-review.ts API request/response and private persistence
Three-way content merge src/content-merge.ts Offline preview and transactional draft apply

Subpath exports avoid loading every domain into a client bundle. Zod is the runtime schema source; TypeScript DTOs and JSON Schema derive from it. Classes policy shapes now have one owner in src/course-policy.ts: capacity, series state, enrollment mode, access methods, booking windows and participation policy. Requests, stored responses, Course templates and inferred policy types reuse it. Existing response capacity limits remain 1,000,000 while new writes retain 100,000; consolidation does not silently change historical read limits. Privileged runner-control/source-registration transports and private operation projections remain a separate audit. Do not introduce another handwritten client response copy in an API route or service adapter.

Upstream models and deliberate differences

These are design references, not drop-in Nevai wire formats. No upstream source code is copied. Exact inspected commits are in sources.json.

  • Decap fields inform name, label, widget, requiredness, options, nested objects/lists, relations and Media. Nevai uses JSON and stable document/Media IDs instead of Git-relative content paths. Files are bytes with checksums and approval metadata. This first format supports an explicit subset, not arbitrary Decap YAML or custom widgets. required currently defaults false; definitions should state it explicitly. Non-translated values must match the default locale; locale values are not silently copied or translated by the validator. Arbitrary widget JavaScript, regex execution and dynamic defaults are excluded.
  • Frappe Course Schedule informs the separation of curriculum, learner group, scheduled occurrence and attendance. Nevai already has styles/levels, CourseSeries, CourseSession, CourseEnrollment and CourseAttendance. Preserve those useful contracts. Teacher/resource scheduling, partner roles, balanced capacity, trial lessons, credits and waitlists remain explicit Nevai behavior. This does not install Frappe or claim a complete Frappe JSON mapping. Its current source tree differs from the documented Course Schedule model; use the recorded documentation as the conceptual reference until a matching source revision is inspected.
  • TastyIgniter API and reservations inform the planned Hospitality engine boundary: locations, menus/options/prices, orders/statuses, tables/dining areas, party size, slots and duration. API CRUD does not prove waiter, QR ordering, kitchen display or bill settlement support. Inspect and test each operation against the engine before defining its Nevai adapter. No parallel editable restaurant catalogue is introduced here.

Validation

npm run build --workspace=@nevai/contracts
npm run schemas --workspace=@nevai/contracts
npm run contracts:check

Generated JS/declarations and JSON Schema are committed and checked against the source. Semantic checks (relations, translations, Media approval) also require the runtime parser; JSON Schema alone is insufficient.

Package transport

@nevai/contracts/node is a Node-only export for directory inspection, ZIP packing/unpacking and merge preview. Browser imports must use the root or a domain subpath; they never import the archive tools. ZIP support uses streaming yauzl and yazl, with pinned dependency versions. Every extracted package is validated before it is returned. Extraction uses a new private directory and rejects unsafe/duplicate paths, special files, encryption, oversized expansion and undeclared files. A caller must dispose the temporary directory after use.

The baseline now includes definitions, locale configuration, documents and Media metadata. Schema definitions, Media versions and locale configuration merge as indivisible units; document object fields merge independently and lists remain atomic. Invalid combined values are reported as issues. A resolved local preview still grants no server authority or Media publication permission.

Media catalogue and metadata commands also share /media normalization and admission. Folder/Tag reads and mutations validate complete records; Usage reports validate kinds, statuses, optional Website IDs and nonnegative historical counts. Native upload/download and the temporary scoped read cache remain transport behavior.

Website editor contracts

@nevai/contracts/website-pages owns Page requests, draft lifecycle and response schemas with inferred DTOs. Hono OpenAPI and client parsing use these schemas, including all five system-page identities. @nevai/contracts/website-editor owns SEO and template binding/Form/Collection field schemas. SEO canonical URLs must use HTTP(S), with a 2048-character limit.

Page bindings preserve declared boolean and text-list values as native JSON. projectWebsitePage and readPackagePage in the root export cover the Page editor/package roundtrip, including draft overlay, routes, SEO, visibility and stable Media references. They preserve textual numeric/date representations; unsupported values fail rather than being stringified. Structure is carried by definition.websitePage, editorial metadata by document.page, and free values by document translations. Row versions are server-owned and excluded. Full Website snapshot projection and connected concept apply now reuse these adapters; see the directory runbook.

Collection transport also owns entry-order commands and reset/order acknowledgements; reset reports whether an unpublished entry was removed. Repository conflict and missing states are separate from the successful HTTP outcome.

Collections/entries and Forms use /website-collections and /website-forms. projectWebsiteCollection / readPackageCollection and projectWebsiteContentEntry / readPackageContentEntry preserve configuration, item order/routes/SEO and native boolean/list values. Structures use definition.websiteCollection; documents use collection or entry metadata. projectWebsiteForm / readPackageForm preserve localized choices, conditional fields and confirmation copy in document.form, with template structure in definition.websiteForm. Both adapters overlay draft locales and exclude row counters. Duplicate identities, unknown source data and lossy storage values are rejected. Connection/status metadata expresses review intentions, not authority. Published Form copy updates cannot alter field structure; drafts use the full field contract and still require server-owned Inbox/sender authorization before activation. Client editor state is distinct from published update requests: delivery mode is a Collection draft setting, and Form confirmation/schema settings use drafts.

Connected package transfer scopes derive from package tenant identities and are shared by Hono and the client. Initial packages remain allowed to be unbound; a connected transfer scope requires both identities.

Publication/source/delivery history transport uses /website-publication-transport. HTTP schemas own the commands and DTOs; derived client schemas preserve legacy date/ID admission, bounded versions and exact history/delivery relationships. Hybrid commands and publication generations/checksums use the same transport owner. Recovery uses shared /website projection/proposal/command schemas, including recursive JSON, counts and scope checks. Publication changes share query/kind/DTO definitions and retain client uniqueness/count/cursor checks. Rollback uses a shared command and complete deployment response; artifact scope and historical reads remain explicit. The client adapter audit is complete; privileged runner/source-registration transports and template/connected acceptance remain separate gates.

Manifest/change-set HTTP schemas and DTOs use /website-developer. Client decoders retain manifest/source/kind checks and complete proposal/review/conflict consistency. The canonical schema-sync vocabulary also feeds OpenAPI, including Commerce and binding type/Media changes. Acceptance admission preserves raw conflict lookup IDs; active revisions, tenant authority and acceptance planning stay API-owned.

Website AI transport uses /website-ai for complete settings/model/note/conversation responses and distinct note create/save/approve commands. Provider vocabulary and model syntax derive from /ai; availability, pilot limits, citations and conversation authority stay server-owned. Website workspace create/read schemas use /website-workspaces, preserving normalized locale input and derived nonempty client reads.

Website diagnostic events, pages/cursors and filters use /website-diagnostics. The existing stricter client validation derives from the HTTP schema; actor redaction, retention and tenant inspection remain API-owned.

Website Content consolidation uses /website-consolidation for read/write contracts and cadence/time-zone validation; leases and schedule effects remain server-owned.

Website QR commands and complete catalog/link responses use /website-qr. Catalog destinations add a title to the command union; target availability, tenant permissions, public redirects and opening counts remain server-owned.

Shell/navigation commands, pure write admission, audit projections and reset acknowledgements also share /website-shell. Lowercase/unpadded command identities and raw external URL limits remain distinct from general read identity schemas.

Shell/navigation responses and inferred DTOs use /website-shell. Shared configuration schemas also cover General, SEO, presentation, notices and cookies. projectWebsiteShell / readPackageShell preserve Site language routes and metadata in document.shell, with template slots in definition.websiteShell. projectWebsiteNavigation / readPackageNavigation use document.navigationItem for targets, hierarchy, slots, order, localized labels and archival intentions. New item drafts do not require a synthetic published record. General/navigation/ SEO/presentation/notice/cookie drafts overlay their own section; missing optional settings retain current values. Notice lists retain stable identities, schedules and localized copy; incomplete notice titles are allowed in drafts but block publication. Cookie flags and localized consent labels remain explicit editorial settings. The public notices list never replaces legacy notice configuration. Complete transactional Website reads and connected concept apply are implemented; hosted pilot acceptance remains open.

Manifest field validation and editor response validation share the semantic field-array schemas too: choice options are unique, conditional visibility references existing choices, and Media bindings declare their kind. Choice values are preserved verbatim because they are identities, not labels to normalize. Unfinished Form draft writes retain their bounded draft validator; activation still checks complete fields and server-owned connections.

Website Media reference baseline/draft/write/lifecycle schemas and inferred types live in /media, shared by Hono and the client. projectWebsiteMedia overlays saved/staged Website alt drafts over their published reference and exports only checksum-bound file metadata and Website public alt. readPackageWebsiteMedia restores reference intent without storage paths, lifecycle counters or authority. Organization-wide Media metadata remains outside this Website editor boundary; rights and approval are explicit export inputs, subject to server verification at connected apply. File IDs and source organization must match. Empty decorative alt remains distinct from an absent Website reference. The repeatable-read Website snapshot includes this projection.

Planning/Commerce Website reference schemas are canonical in website-references: manifests, public release types, API request/response types and client response parsing consume them. projectWebsiteReferences / readPackageWebsiteReferences keep declarations in Page structure (websitePage.connections) and binding intentions in Page editorial metadata (page.connections). All six operational kinds are retained; class views and session limits are manifest-bounded. Required unconnected blocks are draft-valid and publication-invalid. This projection performs no writes and cannot prove that a target belongs to the importing tenant or authorize it. Connected apply must recheck actual operational targets and permissions. The transactional Website read and ordinary authorized concept writers include these intentions.

projectWebsitePageActions / readPackagePageActions retain semantic Page action targets in document.page.actions beside the existing template declarations. The server normalizes scoped stored rows to websitePageActionSchema; only matching Website/Page rows and declared, unique reference IDs are accepted. Targets reuse the navigation schema (Page, Collection, item, external or module). Unselected targets remain editable; required targets and absent package content block publication validation. The same existence checks serve navigation. Changing a target is editorial; changing its declaration requires a structure revision. No changeset acceptance, activation or module access is implied.

Shared import preflight and development content

preflightEditableContent in the root export checks the canonical package and restores Website editor documents through the existing reverse adapters. It returns structured issues and no usable value on failure. With website: true, generic offline documents without Website structure are not import-ready. checkContentDirectory in the Node export adds schema/baseline integrity and exact Media file verification. ZIP and directory reads also reject editor values that cannot be restored without loss. No check grants tenant, activation or publication authority. Typed Page storage is implemented. Registered-source first-import preparation and definition upload exist; connected first-import acceptance remains open.

resolveContentPreview is the shared content-source rule for development tools. Disconnected always returns no content or languages, even if a prior package is supplied. Demo and Connected require an explicit package; neither supplies editorial seeds. Available languages come from the package; one selected locale has no default-language translation fallback. Operational sources remain separate: unavailable for Disconnected, synthetic scenarios for Demo, and connected for Connected. This is a tested contract, not yet a template/App UI integration.

Local edited-package preparation

The Node-only prepareEditedContentDirectory(input, newDirectory) and packEditedContentDirectory(input, newZip) refresh declared Media sizes/checksums from local file bytes. They preserve the downloaded baseline and working files, reset approval intentions for changed bytes, and verify the resulting package. They confer no server upload, Media promotion or publication authority. The content:archive command supports pack-edited for this explicit workflow.

Dependencies

Dependencies

ID Version
yauzl 3.4.0
yazl 3.3.1
zod 4.4.3

Development Dependencies

ID Version
typescript ~6.0.3
Details
npm
2026-10-15 21:43:47 +02:00
88
225 KiB
Assets (1)
Versions (2) View all
1.1.0 2026-10-19
1.0.0 2026-10-15