Phase 2.9: Commands Methods

[Sam-Bolling]

Task

Implement all 10 Commands methods in url_builder.ts and add Commands method tests to url_builder.spec.ts. Commands is the ninth and final Phase 2 resource type, completing all 80 QueryBuilder methods. Commands are the control equivalent of Observations — instructions sent to systems for actuation via Control Streams, with lifecycle management (status tracking, result retrieval, cancellation).

ROADMAP Reference: Phase 2, Task 9 — Commands Methods (~1.5–2 hours implementation + ~0.5 hour testing, Medium-High complexity)

---

Files to Create or Modify

File	Action	Est. Lines	Purpose
src/ogc-api/csapi/url_builder.ts	Modify	~65–90 added	Add 10 Commands methods with resource validation
src/ogc-api/csapi/url_builder.spec.ts	Modify	~40–50 added	Add Commands method tests

Blueprint Reference

Follow the Observations methods pattern from Issue #11 and Control Streams from Issue #12 (same file). Also reference the EDR pattern in src/ogc-api/edr/url_builder.ts (562 lines) for resource validation and URL construction. Commands mirrors Observations architecturally but for the control/actuation direction, and adds status tracking, result retrieval, and cancellation patterns.

Scope — What to Implement

10 Commands 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:

• getCommands(options?: CommandQueryOptions): string — GET /commands with temporal filtering (issueTime, executionTime), status filtering, cursor-based pagination, sorting

Single resource:

• getCommand(id: string, options?): string — GET /commands/{id}

CRUD operations:

• createCommand(controlStreamId: string, body: object): string — POST /controlstreams/{controlStreamId}/commands (single command)
• createCommands(controlStreamId: string, body: object): string — POST /controlstreams/{controlStreamId}/commands (bulk commands)
• updateCommand(id: string, body: object): string — PUT /commands/{id}
• deleteCommand(id: string): string — DELETE /commands/{id}

Status and result sub-resources:

• getCommandStatus(id: string): string — GET /commands/{id}/status
• updateCommandStatus(id: string, body: object): string — PATCH /commands/{id}/status (system-generated status updates)
• getCommandResult(id: string): string — GET /commands/{id}/result

Lifecycle operations:

• cancelCommand(id: string): string — POST /commands/{id}/cancel

⚠️ Implementation note: The Guide contains two cancel patterns: POST /commands/{id}/cancel (Update Operations section) and DELETE /commands/{id} (Lifecycle Endpoints section). The ROADMAP specifies "POST cancel operation". Use POST /commands/{id}/cancel for the cancelCommand method. The deleteCommand method handles DELETE /commands/{id} for actual deletion. See Documentation problem below.

Commands Query Parameters

Commands support: issueTime, executionTime, status, controlstream, id, limit, offset, cursor, f, cmdFormat, sortBy, sortOrder.

All parameters are serialised by the shared buildQueryString() helper (Issue #3). Key features:

• issueTime — primary temporal filter (when command was issued), supports instants and intervals
• executionTime — when command should be/was executed
• status — filter by command state (pending, accepted, executing, completed, failed, canceled), comma-separated
• controlstream — filter commands by control stream
• Cursor-based pagination: cursor parameter for efficient streaming of command histories
• cmdFormat — command encoding format

Note: Commands do not support bbox, datetime, phenomenonTime, or resultTime (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 2 specification sections for Commands endpoints
• Document command lifecycle patterns (status states, transitions)
• Document bulk creation for createCommands
• Follow the JSDoc style in src/ogc-api/edr/url_builder.ts and the Observations methods from Issue Phase 2.7: Observations Methods #11

Testing Requirements

• Extend src/ogc-api/csapi/url_builder.spec.ts (~40–50 lines)
• Test temporal filtering (issueTime, executionTime intervals)
• Test bulk command creation (createCommands with control stream ID)
• Test status retrieval and updates (getCommandStatus, updateCommandStatus)
• Test result retrieval (getCommandResult)
• Test cancel operation (cancelCommand produces correct URL)
• Test resource validation — calling any Commands method when commands is not in availableResources throws an error
• Follow test patterns from Observations tests (Issue Phase 2.7: Observations Methods #11) and src/ogc-api/edr/url_builder.spec.ts

Scope — What NOT to Touch

• ❌ Do NOT implement Systems, Deployments, Procedures, Sampling Features, Properties, DataStreams, Observations, or Control Streams methods — those belong to Issues Phase 2.1: Systems Methods #5–Phase 2.8: Control Streams Methods #12
• ❌ 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 any previously implemented resource methods (Issues Phase 2.1: Systems Methods #5–Phase 2.8: Control Streams Methods #12)
• ❌ 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 10 Commands methods listed above
• Each method validates resource availability before constructing a URL
• Each method uses buildResourceUrl() and buildQueryString() helpers
• createCommand and createCommands correctly route to /controlstreams/{id}/commands
• cancelCommand routes to POST /commands/{id}/cancel
• All new methods have complete JSDoc documentation with @param, @returns, @see
• url_builder.spec.ts contains Commands tests covering temporal filtering, bulk creation, status, result, cancel, and resource validation (~40–50 lines)
• Existing tests still pass (npm test)
• No lint errors
• This completes all 80 Phase 2 QueryBuilder methods across 9 resource types

Dependencies

Blocked by: Issue #1 (Type System — provides CommandQueryOptions 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), Issue #12 (Control Streams Methods — commands flow through control streams)
Blocks: Phase 3 tasks (Issues #14–#30), Phase 4 tasks (Issues #31–#33)

---

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 Commands Resource Methods (lines 1830–1922)	Full CRUD operations, status lifecycle, temporal queries, cancel, feasibility, state machine
2	docs/planning/csapi-implementation-guide.md	§6 Complete Query Parameter Support (lines 1927–2006)	All query parameters including issueTime, executionTime, cursor, cmdFormat, status
3	docs/planning/csapi-implementation-guide.md	§6 Query Parameters and Code Reuse (lines 720–900)	Temporal applicability matrix showing Commands supports executionTime + issueTime only
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 9 (lines 296–317)	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	CommandQueryOptions, CSAPIResourceType (created by Issue #1)
8	src/ogc-api/csapi/helpers.ts	Encoding helpers: encodeDateTime, encodeArray (created by Issue #2)

Research References (context, not required reading)

#	Document	What It Provides
9	docs/research/requirements/csapi-part2-requirements.md	Detailed client requirements for Commands including status tracking and feasibility
10	docs/research/requirements/csapi-query-parameters.md	Complete catalog of all CSAPI query parameters
11	docs/research/upstream/pr114-analysis.md	Patterns for command submission and status polling

Specification References (for @see links and field accuracy)

#	Document	Use
12	OGC API - Connected Systems Part 2 (23-002)	Commands resource definitions, lifecycle management, status tracking, cancel operation
13	OGC API - Connected Systems Part 2: OpenAPI Spec	Commands endpoint definitions — normative URL paths
14	OGC SWE Common 3.0 (24-014)	Format for command parameter encodings

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