Phase 2.7: Observations Methods

[Sam-Bolling]

Task

Implement all 9 Observations methods in url_builder.ts and add Observations method tests to url_builder.spec.ts.

Resolution (commit b9cd3df)

All acceptance criteria met:

• url_builder.ts contains all 9 Observations methods (8 new + createObservation from Issue Phase 2.6: DataStreams Methods #10)
• Each method validates resource availability before constructing a URL
• Each method uses buildResourceUrl() and buildQueryString() helpers
• createObservation (Issue Phase 2.6: DataStreams Methods #10) already correctly routes to /datastreams/{id}/observations
• All new methods have complete JSDoc documentation with @param, @returns, @see
• url_builder.spec.ts contains 17 new Observations tests covering temporal filtering, resultTime=latest, cursor pagination, obsFormat encoding, CRUD, associations (singular sub-paths), history, and resource validation
• Existing tests still pass — 262 total (245 prior + 17 new)
• No TypeScript errors (npx tsc --noEmit)

Methods added: getObservations, getObservation, updateObservation, deleteObservation, getObservationDatastream (singular), getObservationSamplingFeature (singular), getObservationSystem (singular), getObservationHistory

Design note: Association endpoints use singular sub-paths (/datastream, /samplingFeature, /system) because each observation belongs to exactly one parent — unlike DataStreams which use plural forms for many-to-many associations.

[Sam-Bolling]

⚠️ Required Pre-Reading: Lessons Learned

MANDATORY: Before starting work on this issue, read docs/governance/phase-2-lessons-learned.md.

This document contains actionable guardrails derived from real mistakes made in Phase 1–2.2. All 7 lessons apply to this issue. Key callouts for Observations:

Lesson	What to Do for This Issue
L1 — Test Checklist	Use the mandatory 8-item test checklist. Observations has temporal parameters — each one needs an exact toBe() assertion on the serialized ISO 8601 string, not toContain().
L2 — Query Parameters	Check the applicability table: Observations supports phenomenonTime, resultTime, foi, cursor but NOT bbox, NOT offset, NOT uid, NOT q. This is a significantly different parameter set from Part 1 resources.
L3 — Temporal Keys	⚠️ CRITICAL for this issue. Observations introduces phenomenonTime and resultTime. Verify that both are present in the buildQueryString temporal condition. If either is missing, flag it as a comment — do not modify buildQueryString yourself.
L4 — Resource String	Every method must call this.assertResourceAvailable('observations') — grep to verify after implementation.
L5 — Files	All work in url_builder.ts + url_builder.spec.ts only. No new files.
L6 — Review Findings	Note any unexpected behavior as a comment on this issue.
L7 — DRY	Do not copy-paste method bodies. Call shared helpers.