Phase 1.2: Create Helper Utilities (csapi/helpers.ts)

[Sam-Bolling]

Task

Create the CSAPI helper utility functions in src/ogc-api/csapi/helpers.ts (~50-80 lines) and their test file src/ogc-api/csapi/helpers.spec.ts (~80-120 lines).

ROADMAP Reference: Phase 1, Task 2 — Create Helper Utilities (~2-3 hours, Low complexity)

---

Files to Create

File	Action	Est. Lines	Purpose
src/ogc-api/csapi/helpers.ts	Create	~50-80	URL encoding, temporal encoding, resource type validation, parameter validation utilities
src/ogc-api/csapi/helpers.spec.ts	Create	~80-120	Unit tests for all exported helper functions

Blueprint Reference

Follow the EDR pattern established in src/ogc-api/edr/helpers.ts (25 lines) and src/ogc-api/edr/helpers.spec.ts (46 lines). The CSAPI helpers file is larger because it covers URL encoding, temporal encoding, and validation utilities for 9 resource types (vs EDR's single temporal helper).

Scope — What to Implement

Exported Utility Functions

1. URL encoding utilities — Properly encode special characters in query parameter values

   • Handle resource IDs with special characters for path segments
   • Handle encoding of array-valued parameters (e.g., id=sys1,sys2,sys3)

2. Temporal encoding utilities — ISO 8601 formatting for CSAPI temporal parameters

   • Similar to EDR's DateTimeParameterToEDRString but for CSAPI temporal fields
   • Handle phenomenonTime, resultTime, issueTime, executionTime formatting
   • Support single dates, intervals (start/end), and open-ended ranges

3. Resource type validation — Validate CSAPIResourceType values

   • Check if a string is a valid resource type (one of the 9 CSAPI types)
   • Provide clear error messages for invalid resource types

4. Parameter validation utilities — Input validation helpers

   • Basic parameter validation (e.g., limit must be positive integer)
   • Bbox validation (correct number of coordinates, valid ranges)

Important: buildResourceUrl() and buildQueryString() are private methods inside the QueryBuilder class (see Guide §6 "Helper Methods"), NOT standalone helpers. They require this.baseUrl and belong in url_builder.ts (issue #3). This file contains only standalone pure functions that do not require class instance state.

JSDoc Requirements

• Document each exported function with parameter descriptions, return type, and examples
• Add @see links to CSAPI spec sections for temporal/spatial parameter formats
• Follow the JSDoc style in src/ogc-api/edr/helpers.ts

Testing Requirements

• Create src/ogc-api/csapi/helpers.spec.ts (~80-120 lines)
• Test URL encoding with normal and special-character inputs
• Test temporal encoding with single dates, intervals, open-ended ranges, and invalid inputs
• Test resource type validation accepts all 9 valid types and rejects invalid ones
• Test parameter validation utilities accept valid inputs and reject invalid ones
• Follow test patterns from src/ogc-api/edr/helpers.spec.ts

Scope — What NOT to Touch

• ❌ Do NOT create url_builder.ts — that belongs to Phase 1.3 (issue Phase 1.3: Create Stub QueryBuilder (csapi/url_builder.ts) #3)
• ❌ Do NOT create or modify model.ts — that belongs to Phase 1.1 (issue Phase 1.1: Create Type System (csapi/model.ts) #1)
• ❌ Do NOT modify endpoint.ts — that belongs to Phase 1.4 (issue Phase 1.4: Integrate with OgcApiEndpoint #4)
• ❌ Do NOT modify index.ts exports — that belongs to Phase 1.4 (issue Phase 1.4: Integrate with OgcApiEndpoint #4)
• ❌ Do NOT implement buildResourceUrl() or buildQueryString() — those are private QueryBuilder methods (issue Phase 1.3: Create Stub QueryBuilder (csapi/url_builder.ts) #3)
• ❌ Do NOT implement extractAvailableResources() — that's a QueryBuilder constructor concern (issue Phase 1.3: Create Stub QueryBuilder (csapi/url_builder.ts) #3)
• ❌ Do NOT modify files outside the "Files to Create" table above
• ❌ Do NOT refactor existing code unless required to complete this task

Acceptance Criteria

• src/ogc-api/csapi/helpers.ts exists with all utility functions listed above
• All exported functions have complete JSDoc documentation
• Imports from model.ts (issue Phase 1.1: Create Type System (csapi/model.ts) #1) use types defined there (e.g., CSAPIResourceType)
• src/ogc-api/csapi/helpers.spec.ts exists with tests for all exported functions
• Existing tests still pass (npm test)
• No lint errors

Dependencies

Blocked by: #1 — Phase 1.1: Create Type System (helpers import CSAPI types from model.ts)
Blocks: #3 — Phase 1.3: Create Stub QueryBuilder (QueryBuilder uses temporal encoding and validation utilities from helpers)

---

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: "Helper Methods"	Lines 620-720	Complete helper method specifications — buildResourceUrl(), buildQueryString(), extractAvailableResources() with full code blocks. Note: These are private QueryBuilder methods, not standalone helpers. This file (helpers.ts) contains only standalone pure functions (URL encoding, temporal encoding, validation).
2	src/ogc-api/edr/helpers.ts	Full file (25 lines)	Upstream blueprint — the accepted pattern for a standalone helper module. Match export style and JSDoc format.
3	src/ogc-api/edr/helpers.spec.ts	Full file (46 lines)	Test blueprint — the accepted pattern for helper test files. Match describe/it structure and assertion style.

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

#	Document	What to Import
4	src/ogc-api/csapi/model.ts (created in issue #1)	CSAPIResourceType, CSAPIResourceTypes
5	src/shared/models.ts	BoundingBox, DateTimeParameter

Research References (context, not required reading)

#	Document	What It Provides
6	docs/research/upstream/url-building-analysis.md	Analysis of URL construction patterns across all upstream APIs — context for why URL building stays in QueryBuilder
7	docs/research/upstream/querybuilder-pattern-analysis.md	Analysis of QueryBuilder patterns — why helpers use composition not inheritance
8	docs/planning/ROADMAP.md Phase 1, Task 2	Lines 82-90 — task description with time estimates

Specification References (for @see links in JSDoc)

#	Document	Use
9	OGC API - Connected Systems Part 1 (23-001)	Resource type definitions for validation
10	OGC API - Connected Systems Part 2 (23-002)	Temporal parameter formats for encoding utilities
11	docs/research/standards/ogcapi-connectedsystems-1.bundled.oas31.yaml	Part 1 OpenAPI schema — resource type list
12	docs/research/standards/ogcapi-connectedsystems-2.bundled.oas31.yaml	Part 2 OpenAPI schema — query parameter definitions

Convention Quick Reference

Rule	Example
Use .js extension for relative imports	import { CSAPIResourceType } from './model.js'
Use import type for interfaces/types	import type { CSAPIResourceType } from './model.js'
Named exports for all functions	export function encodeCSAPIParameter(...) { }
HTTP mocking: globalThis.fetch = jest.fn()	Not needed for this task (no HTTP calls in helpers)
Meaningful tests only	Verify actual encoded output, validation results, error messages — not just that functions don't throw