Skip to content

AGENTS.md

Latest commit

 

History

History
121 lines (84 loc) · 12.8 KB

AGENTS.md

File metadata and controls

121 lines (84 loc) · 12.8 KB

Agent primer — hds-lib-js

This file orients agents (Claude or others) working on hds-lib-js. It deliberately does not duplicate information that already lives in this repo — it links you to the right document for each concern. Read this first; then read the linked docs as you start a task.

Read first

Before touching code, read these in order:

  1. README.md — what the package is, public surface, dev commands. Also lists the badge URLs and the public docs site.
  2. docs/index.md plus the published site at https://healthdatasafe.github.io/hds-lib-js/ — full user-facing API documentation. The pages under docs/ are the source for that site.
  3. docs/getting-started.md — install + bootstrap (settings.setServiceInfoURL, initHDSModel).
  4. docs/hds-model.md — HDSModel, itemsDefs, streams, eventTypes, datasources, authorizations, conversions, converters, appStreams, Overload.
  5. docs/app-templates.md + AppTemplates.md — AppManagingAccount / AppClientAccount / Collector / CollectorClient / CollectorRequest / Contact. The legal/consent-flow shape used by every HDS app.
  6. docs/settings.md — global library settings (settings.setServiceInfoURL, init order). Distinct from per-user HDSSettings.
  7. docs/localization.md — localizableText shape and localizeText(...) resolution rules.
  8. docs/toolkit.md — StreamsAutoCreate, reminders, duration parsing, event formatters.
  9. docs/utilities.md — HDSLibError, misc helpers.
  10. CHANGELOG.md — every behaviour change worth knowing about, in reverse chronological order. Read the most recent entries before estimating an API.

Anything not covered above is either internal or new; in that case, read the source under ts/ and add docs as you go (do not let new public surface escape docs/).

Pryv concepts you must hold in your head

hds-lib-js wraps and extends pryv JS lib. Most of what this library does is express HDS-specific patterns on top of standard Pryv objects. Before designing anything that touches Pryv data shapes, read the corresponding section of the Pryv API reference.

Authoritative sources:

Key concepts you will encounter constantly here:

Pryv concept Why it matters in hds-lib Reference
Service info Discovery endpoint published by every Pryv platform. settings.setServiceInfoURL(url) is the only mandatory bootstrap. The HDS data-model URL is published as an assets.hds-model override on top of this. Service info
Streams Tree of clinical-domain containers. The HDS data-model defines the stream tree; HDSModel.streams exposes it. Permissions are stream-scoped and inherit down the tree. Stream · methods
Events The actual data points. Each event has streamIds, type, content, time, optional duration, integrity. HDS items map (streamId × type) → an HDSItemDef. Event · methods
Event types Schema + unit. HDS event types live in data-model/definitions/eventTypes/; Pryv's catalogue of standard types is at the link. HDSModel.eventTypes.getEventTypeSymbol(type) resolves the unit. Event-types catalogue
Accesses & permissions personal, app, shared. App auth produces an app access; Collector flows produce shared accesses. Levels: read / contribute / manage. Many HDS bugs come from confusing these. Access · methods
Authentication / app auth app-web-auth3-hds drives the OAuth-like flow. The HDS Application / AppClientAccount / AppManagingAccount classes wrap pryv.Browser.AuthController. Auth request · authenticate-your-app
Methods (events.get, events.create, ...) The API verbs. HDSConnection wraps pryv.Connection and adds apiOne(method, params). Methods · method-ids
WebSockets / Socket.io / monitor Real-time event change feed. MonitorScope here is a thin wrapper around the Pryv socket layer. Call with WebSockets · Subscribe to changes (WebSockets)
Integrity Per-event integrity: "EVENT:0:sha256-..." hash. Don't strip or recompute manually. Integrity
HF events High-frequency event format (used by some bridges). Not common in HDS apps yet. HF events · HF series

If a piece of code seems to be reinventing one of the concepts above, stop and check whether the Pryv lib already exposes it. The right answer is almost always "use the Pryv primitive directly."

Cross-repo relationships

hds-lib-js sits at the centre of an ecosystem. Changes here ripple. Know the dependents before you change a public type.

  • data-model (@hds/data-model) — the YAML-defined items / streams / event types this library loads at runtime. The library never bundles the data-model; it fetches pack.json via service-info. Design rules (item naming, scale-hook placement, stream tree, etc.) are in data-model/AGENTS.md, and the YAML lives under data-model/definitions/.
  • hds-forms-js — React form renderers for HDSItemDef. Re-exports several types from hds-lib (e.g. appTemplates.ItemLabels, appTemplates.ItemCustomization). When you change those types, type-check hds-forms-js too.
  • app-web-auth3-hds — auth flow used by every HDS app. Treat the public API surface as a contract.
  • lib-bridge-js — base library for HDS server-side bridges; same compatibility concerns as any consumer.

Conventions enforced in this repo

These are short reminders. The detail lives in the linked source.

ESM, TS source as truth

  • "type": "module", "module": "nodenext". All imports use explicit .ts / .js extensions.
  • TypeScript source under ts/ is the source of truth. Tests run directly from source (Node 24 type stripping); npm test does not need a build.
  • The package ships compiled output from js/ (built by npm run prepare → tsc). Consumers pulling via git+https://... hit the prepare hook on install. Never publish without js/ compiled.
  • Webpack bundle in dist/ (built by npm run build) is for the browser test runner only. Do not import from dist/ in code.
  • pryv is consumed via ts/patchedPryv.ts — declaration merging (const + namespace) so pryv is both value and type namespace. Do not import pryv directly anywhere else; always go through patchedPryv.ts.

Public surface

Every value/type intended for external consumption is exported from ts/index.ts. If a consumer needs something that is not there, add the export and document it under docs/ — do not let consumers reach into deep paths.

Tests

  • tests/ — mocha + node assert. One file per concept (apptemplates.test.js, eventToShortText.test.js, itemLabels.test.js, ...). Most tests load pack.json from the deployed model.datasafe.dev over HTTP, so the test runner needs network access.
  • tests-browser/ — same suites compiled for the browser test runner. Run via backloop.dev.
  • New tests go next to similar existing ones. New behaviour without a test is not done.

Versioning

  • Bump version in package.json for every change that consumers can observe.
  • Add a ## [x.y.z] - YYYY-MM-DD block in CHANGELOG.md. Group changes under Added / Changed / Removed. Keep the wording concrete (one bullet = one observable change).
  • Consumers pin to git URLs, not npm versions, but the version + changelog is still how humans read the diff.

Gotchas

  • tsc stale output: tsc may skip re-emitting a .js file if it already exists and didn't notice an internal change. After npm run prepare / npm run build:ts, verify the relevant file in js/ actually contains your change before committing. If not, delete the stale js/<path>.js and re-run.
  • Vite cache in consumer apps: when you change a public type or export and a consumer app (Vite-based) doesn't pick it up, clear <consumer>/node_modules/.vite and restart the dev server.
  • npm-link traps: when an HDS app is npm-linked to hds-lib, both the app and any nested package (e.g. hds-forms-js's src-test-app/) must link the same hds-lib to avoid duplicate singletons (settings, model). If you see "two HDSModels" symptoms (e.g. getHDSModel() returning empty), this is the cause. Run cd _local && npm run check-links && npm run verify-live-source to diagnose. Full methodology: _claude-memory/conventions.md § Live cross-repo development — quickstart + _plans/49-local-dev-dependency-graph-done/PLAN.md.
  • exports.import MUST point at TS source (./ts/index.ts here). Vite resolves the import condition in dev mode; pointing at compiled JS causes downstream libs (hds-forms-js, hds-react-timeline) to inline a second copy of hds-lib → duplicate-singleton bug. Verify with cd _local && npm run verify-live-source.
  • Initialization order: in apps that call initBoiler(name, configDir) (server side) or pryv.Browser.AuthController (client side), do so before any getHDSModel() / HDSSettings lookup.

appTemplates — custom fields & system stream (Plan 45)

When extending appTemplates/ for templates that declare custom fields, system-stream features, or any clientData.hds*Field declarations, read ts/appTemplates/CUSTOM-FIELDS-AND-SYSTEM.md first. It covers the clientData schemas, parent-chain inheritance, sandbox prefix rule, three stream-reference modes, and the helper API (resolveStream*, streamCustomFieldToVirtualItem, loadTemplate).

When in doubt

If the answer to a question is not in any of these places, that is a documentation bug — open an issue (or PR an addition to docs/) rather than guessing.