Phase 2.4: Sampling Features Methods

[Sam-Bolling]

Task

Implement all 8 Sampling Features methods in url_builder.ts and add Sampling Features method tests to url_builder.spec.ts. Sampling Features is the fourth Phase 2 resource type and follows the pattern established by Systems (Issue #5).

ROADMAP Reference: Phase 2, Task 4 — Sampling Features Methods (~1.5–2 hours implementation + ~0.5 hour testing, Medium complexity)

---

Files to Create or Modify

File	Action	Est. Lines	Purpose
src/ogc-api/csapi/url_builder.ts	Modify	~50–70 added	Add 8 Sampling Features methods with resource validation
src/ogc-api/csapi/url_builder.spec.ts	Modify	~30–40 added	Add Sampling Features method tests

Blueprint Reference

Follow the Systems methods pattern established in Issue #5 (same file). Also reference the EDR pattern in src/ogc-api/edr/url_builder.ts (562 lines) for resource validation, URL construction, and query parameter appending.

Scope — What to Implement

8 Sampling Features Methods

Each method validates resource availability (~2 lines), builds a URL using buildResourceUrl(), appends query parameters using buildQueryString(), and returns the constructed URL string.

Collection query:

• getSamplingFeatures(options?: SamplingFeatureQueryOptions): string — GET /samplingFeatures with pagination, spatial filtering (bbox), sorting

Single resource:

• getSamplingFeature(id: string, options?): string — GET /samplingFeatures/{id}

CRUD operations:

• createSamplingFeature(body: object): string — POST /samplingFeatures
• updateSamplingFeature(id: string, body: object): string — PUT /samplingFeatures/{id}
• deleteSamplingFeature(id: string): string — DELETE /samplingFeatures/{id}

Association links:

• getSamplingFeatureSystems(id: string, options?): string — GET /samplingFeatures/{id}/systems (systems using this sampling feature)
• getSamplingFeatureObservations(id: string, options?): string — GET /samplingFeatures/{id}/observations (Part 2 cross-reference)

History:

• getSamplingFeatureHistory(id: string, options?): string — GET /samplingFeatures/{id}/history

Sampling Features Query Parameters

Sampling Features support: bbox, system, foi, relatedSamplingFeature, id, uid, q, property filters, limit, offset, f, sortBy, sortOrder.

All parameters are serialised by the shared buildQueryString() helper (Issue #3). Note: Sampling Features support bbox but do not support datetime or any Part 2 temporal parameters (see Guide §6 temporal applicability matrix).

JSDoc Requirements

• Document each method with @param for all parameters, @returns description, and usage example
• Add @see links to OGC CSAPI Part 1 specification sections for Sampling Features endpoints
• Follow the JSDoc style in src/ogc-api/edr/url_builder.ts and the Systems methods from Issue Phase 2.1: Systems Methods #5

Testing Requirements

• Extend src/ogc-api/csapi/url_builder.spec.ts (~30–40 lines)
• Test spatial filtering (getSamplingFeatures with bbox parameter)
• Test observation retrieval (getSamplingFeatureObservations)
• Test system associations (getSamplingFeatureSystems)
• Test CRUD operations (createSamplingFeature, updateSamplingFeature, deleteSamplingFeature) produce correct URLs
• Test resource validation — calling any Sampling Features method when samplingFeatures is not in availableResources throws an error
• Follow test patterns from Systems tests (Issue Phase 2.1: Systems Methods #5) and src/ogc-api/edr/url_builder.spec.ts

Scope — What NOT to Touch

• ❌ Do NOT implement Systems, Deployments, Procedures, Properties, DataStreams, Observations, Control Streams, or Commands methods — Systems belongs to Issue Phase 2.1: Systems Methods #5, Deployments to Phase 2.2: Deployments Methods #6, Procedures to Phase 2.3: Procedures Methods #7, the rest to Issues Phase 2.5: Properties Methods #9–Phase 2.9: Commands Methods #13
• ❌ Do NOT modify model.ts — type definitions belong to Issue Phase 1.1: Create Type System (csapi/model.ts) #1
• ❌ Do NOT modify helpers.ts — helper utilities belong to Issue Phase 1.2: Create Helper Utilities (csapi/helpers.ts) #2
• ❌ Do NOT modify the constructor, buildResourceUrl(), buildQueryString(), extractAvailableResources(), or availableResources — those belong to Issue Phase 1.3: Create Stub QueryBuilder (csapi/url_builder.ts) #3
• ❌ Do NOT modify endpoint.ts, info.ts, or src/index.ts — integration belongs to Issue Phase 1.4: Integrate with OgcApiEndpoint #4
• ❌ Do NOT modify Systems, Deployments, or Procedures methods — those belong to Issues Phase 2.1: Systems Methods #5, Phase 2.2: Deployments Methods #6, Phase 2.3: Procedures Methods #7
• ❌ Do NOT modify files outside the "Files to Create or Modify" table above
• ❌ Do NOT refactor existing code unless required to complete this task

Acceptance Criteria

• url_builder.ts contains all 8 Sampling Features methods listed above
• Each method validates resource availability before constructing a URL
• Each method uses buildResourceUrl() and buildQueryString() helpers
• All new methods have complete JSDoc documentation with @param, @returns, @see
• url_builder.spec.ts contains Sampling Features tests covering spatial filtering, observation retrieval, system associations, CRUD, and resource validation (~30–40 lines)
• Existing tests still pass (npm test)
• No lint errors

Dependencies

Blocked by: Issue #1 (Type System — provides SamplingFeatureQueryOptions and resource types), Issue #2 (Helper Utilities — provides encoding helpers), Issue #3 (Stub QueryBuilder — provides constructor, buildResourceUrl, buildQueryString, availableResources), Issue #5 (Systems Methods — establishes the pattern)
Blocks: Issues #9–#13 (subsequent resource type methods)

---

Operational Constraints

⚠️ MANDATORY: Before starting work on this issue, review docs/governance/AI_OPERATIONAL_CONSTRAINTS.md.

Key constraints for this task:

• Precedence: OGC specifications → AI Collaboration Agreement → This issue description → Existing code → Conversational context
• No scope expansion: Do not infer unstated requirements or add unrequested features
• No refactoring: Do not rename, restructure, or "improve" code outside this issue's scope
• Minimal diffs: Prefer the smallest change that satisfies the acceptance criteria
• Ask when unclear: If intent is ambiguous, stop and ask for clarification

---

References

Read these documents before starting implementation. They are ordered by priority.

Primary References (must read)

#	Document	Section/Lines	What It Provides
1	docs/planning/csapi-implementation-guide.md	§6 Sampling Features Resource Methods (lines 1495–1543)	Full CRUD operations, query parameters, relationship management, spatial queries
2	docs/planning/csapi-implementation-guide.md	§6 Complete Query Parameter Support (lines 1921–2000)	All query parameters with types, applicability, encoding rules
3	docs/planning/csapi-implementation-guide.md	§6 Query Parameters and Code Reuse (lines 720–900)	Parameter distribution analysis, temporal applicability matrix showing Sampling Features has no temporal params
4	src/ogc-api/edr/url_builder.ts	Full file (562 lines)	Blueprint: method structure, resource validation, URL construction pattern
5	src/ogc-api/edr/url_builder.spec.ts	Full file	Blueprint: test patterns for URL builder methods
6	docs/planning/ROADMAP.md	Phase 2, Task 4 (lines 205–221)	Authoritative task definition, method list, test requirements

Upstream Type/Import References (files this task imports from)

#	Document	What to Import
7	src/ogc-api/csapi/model.ts	SamplingFeatureQueryOptions, CSAPIResourceType (created by Issue #1)
8	src/ogc-api/csapi/helpers.ts	Encoding helpers: encodeBBox, encodeArray (created by Issue #2)

Research References (context, not required reading)

#	Document	What It Provides
9	docs/research/requirements/csapi-part1-requirements.md	Detailed client implementation requirements for Sampling Features navigation
10	docs/research/requirements/csapi-query-parameters.md	Complete catalog of all CSAPI query parameters
11	docs/research/requirements/csapi-subresource-navigation.md	Query parameters on nested endpoints

Specification References (for @see links and field accuracy)

#	Document	Use
12	OGC API - Connected Systems Part 1 (23-001)	Sampling Features resource definitions, CRUD endpoints, query parameters
13	OGC API - Connected Systems Part 1: OpenAPI Spec	Sampling Features endpoint definitions — normative URL paths
14	SOSA/SSN Ontology	Semantic definitions for sampling feature types and relationships
15	RFC 7946 (GeoJSON)	Format for encoding Sampling Features with geometries
16	OGC API - Connected Systems Part 2 (23-002)	Context for sampling feature–observation associations crossing Part 1/Part 2 boundary

Convention Quick Reference

Rule	Example
Use .js extension for relative imports	import { X } from './file.js'
Use import type for interfaces/types	import type { Y } from './model.js'
Three-tier hierarchy: import from lower tiers only	shared → ogc-api → csapi
Named exports for types and utilities	export interface Z { ... }
as const arrays for enum-like values	export const XTypes = [...] as const
HTTP mocking: globalThis.fetch = jest.fn()	Never use nock, msw, or other libraries
Meaningful tests only	Verify behavior, not that code runs without throwing

[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 Sampling Features:

Lesson	What to Do for This Issue
L1 — Test Checklist	Use the mandatory 8-item test checklist. Sampling Features is the 4th resource type — test decay is a real risk by this point.
L2 — Query Parameters	Check the applicability table: Sampling Features supports bbox but NOT datetime, NOT parent/recursive. Test bbox, system, foi, relatedSamplingFeature specifically.
L3 — Temporal Keys	Sampling Features does NOT add new temporal keys. No changes needed to buildQueryString.
L4 — Resource String	Every method must call this.assertResourceAvailable('samplingFeatures') — 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.

[Sam-Bolling]

Resolution Summary

Commit: ba3ecc0 — feat(csapi): add SamplingFeatures methods to CSAPIQueryBuilder (#8)

What was delivered

8 SamplingFeatures methods added to CSAPIQueryBuilder:

#	Method	Type
1	getSamplingFeatures	Collection query
2	getSamplingFeature	Single resource
3	createSamplingFeature	Create (POST)
4	updateSamplingFeature	Update (PUT)
5	deleteSamplingFeature	Delete (DELETE)
6	getSamplingFeatureSystems	Nested association
7	getSamplingFeatureObservations	Nested association
8	getSamplingFeatureHistory	Nested association

Test coverage

22 tests across 7 describe blocks, covering the full Lesson 1 checklist:

• ✅ Collection query with exact toBe() URL assertion
• ✅ Every applicable query option (id, id[], q, bbox, datetime, limit, offset, f)
• ✅ Single resource retrieval with exact URL
• ✅ CRUD operations (create/update/delete) with exact URLs
• ✅ Both nested/association methods with pagination + filtering
• ✅ Resource validation failure — all 8 methods throw EndpointError
• ✅ Temporal parameter with exact toBe() assertion

Verification

• 178 CSAPI tests passing (27 model + 34 helpers + 117 url_builder)
• tsc --noEmit clean
• 82/83 endpoint tests (1 pre-existing non-CSAPI failure)

Notable finding

The uid query parameter is specified in CSAPI for SamplingFeatures but is not present in the current QueryOptions type (SamplingFeatureQueryOptions = QueryOptions). The uid test was omitted per scope constraints (modifying model.ts is outside this issue). This is a latent gap that should be addressed in a future issue when model.ts types are refined.

Running totals

• CSAPIQueryBuilder: 36 public methods across 4 resource types (Systems, Deployments, Procedures, SamplingFeatures)
• CSAPI test suite: 178 tests, 3 suites, 0 failures