@atlasnpm/atlas-api-helper 0.2.6 → 0.2.7

package/README.md

@@ -8,22 +8,179 @@ npm install @atlasnpm/atlas-api-helper
 
 ## Usage
 
+### Using Typed Components (Recommended)
+
+The client now supports typed component interfaces that provide IDE autocomplete and type checking:
+
 ```ts
-import { AtlasHttpClient } from "@atlasnpm/atlas-api-helper";
+import { AtlasHttpClient, EntityComponents, TaskComponents } from "@atlasnpm/atlas-api-helper";
 
 const client = new AtlasHttpClient({
   baseUrl: "http://localhost:8000",
   token: "my-api-token",
 });
 
-// Basic entity operations
-const entities = await client.listEntities();
-console.log("Entities", entities);
+// Create entity with typed components
+const entityComponents: EntityComponents = {
+  telemetry: {
+    latitude: 40.7128,
+    longitude: -74.0060,
+    altitude_m: 120,
+    speed_m_s: 8.2,
+    heading_deg: 165,
+  },
+  health: {
+    battery_percent: 85,
+  },
+  communications: {
+    link_state: "connected",
+  },
+  task_catalog: {
+    supported_tasks: ["move_to_location", "survey_grid"],
+  },
+};
+
+await client.createEntity("drone-01", "asset", "Demo Drone", "drone", entityComponents);
+
+// Create task with typed components
+const taskComponents: TaskComponents = {
+  parameters: {
+    latitude: 40.123,
+    longitude: -74.456,
+    altitude_m: 120,
+  },
+  progress: {
+    percent: 0,
+    status_detail: "Pending",
+  },
+};
+
+await client.createTask("task-1", taskComponents, { entity_id: "drone-01" });
+```
+
+### Using Raw Objects (Legacy)
+
+Raw component objects are still supported for backwards compatibility:
+
+```ts
+import { AtlasHttpClient } from "@atlasnpm/atlas-api-helper";
+
+const client = new AtlasHttpClient({
+  baseUrl: "http://localhost:8000",
+  token: "my-api-token",
+});
 
+// Basic entity operations with raw objects
 await client.createEntity("asset-1", "asset", "Surveyor One", "drone", {
   telemetry: { latitude: 40.7, longitude: -74.0 },
 });
 await client.createTask("survey-1", { parameters: { latitude: 40.7, longitude: -74.0 } });
+```
+
+## Typed Component Reference
+
+### Entity Components
+
+The `EntityComponents` interface accepts the following typed component fields:
+
+| Component | Type | Description |
+|-----------|------|-------------|
+| `telemetry` | `TelemetryComponent` | Position and motion data |
+| `geometry` | `GeometryComponent` | GeoJSON geometry for geoentities |
+| `task_catalog` | `TaskCatalogComponent` | Supported task identifiers |
+| `media_refs` | `MediaRefItem[]` | References to media objects |
+| `mil_view` | `MilViewComponent` | Military tactical classification |
+| `health` | `HealthComponent` | Health and vital statistics |
+| `sensor_refs` | `SensorRefItem[]` | Sensor configurations |
+| `communications` | `CommunicationsComponent` | Network link status |
+| `task_queue` | `TaskQueueComponent` | Current and queued work items |
+| `custom_*` | `unknown` | Custom components (must be prefixed with `custom_`) |
+
+#### TelemetryComponent
+
+```ts
+const telemetry: TelemetryComponent = {
+  latitude: 40.7128,      // degrees (WGS84)
+  longitude: -74.0060,    // degrees (WGS84)
+  altitude_m: 120,        // meters above sea level
+  speed_m_s: 8.2,         // horizontal speed in m/s
+  heading_deg: 165,       // heading (0=N, 90=E)
+};
+```
+
+#### GeometryComponent
+
+```ts
+// Point
+const point: GeometryComponent = { type: "Point", coordinates: [-74.0060, 40.7128] };
+
+// LineString
+const line: GeometryComponent = { type: "LineString", coordinates: [[-74.0060, 40.7128], [-74.0070, 40.7138]] };
+
+// Polygon
+const polygon: GeometryComponent = { type: "Polygon", coordinates: [[[-74.0060, 40.7128], [-74.0070, 40.7128], [-74.0060, 40.7128]]] };
+```
+
+### Task Components
+
+The `TaskComponents` interface accepts:
+
+| Component | Type | Description |
+|-----------|------|-------------|
+| `parameters` | `TaskParametersComponent` | Command parameters for task execution |
+| `progress` | `TaskProgressComponent` | Runtime telemetry about execution |
+
+```ts
+const taskComponents: TaskComponents = {
+  parameters: {
+    latitude: 40.123,
+    longitude: -74.456,
+    altitude_m: 120,
+  },
+  progress: {
+    percent: 65,
+    updated_at: "2025-11-25T08:45:00Z",
+    status_detail: "En route to destination",
+  },
+};
+```
+
+### Custom Components
+
+Custom components must be prefixed with `custom_`:
+
+```ts
+const components: EntityComponents = {
+  telemetry: { latitude: 40.7128 },
+  custom_weather: { wind_speed: 12, gusts: 18 },  // Custom component
+};
+```
+
+### Component Validation
+
+The client validates component keys before transmission. Unknown component keys that don't start with `custom_` will throw an error:
+
+```ts
+// This will throw an error
+await client.createEntity("test", "asset", "Test", "drone", {
+  unknown_component: { foo: "bar" },  // Error: Unknown component 'unknown_component'
+});
+
+// This works
+await client.createEntity("test", "asset", "Test", "drone", {
+  custom_mydata: { foo: "bar" },  // OK: prefixed with custom_
+});
+```
+
+## Complete Example
+
+```ts
+import { AtlasHttpClient } from "@atlasnpm/atlas-api-helper";
+
+const client = new AtlasHttpClient({
+  baseUrl: "http://localhost:8000",
+  token: "my-api-token",
+});
 
 // Entity telemetry updates
 const entity = await client.getEntityByAlias("drone-1");

package/dist/index.cjs

@@ -20,10 +20,58 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  AtlasHttpClient: () => AtlasHttpClient
+  AtlasHttpClient: () => AtlasHttpClient,
+  componentsToRecord: () => componentsToRecord,
+  validateEntityComponents: () => validateEntityComponents
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/types/components.ts
+var KNOWN_ENTITY_COMPONENTS = /* @__PURE__ */ new Set([
+  "telemetry",
+  "geometry",
+  "task_catalog",
+  "media_refs",
+  "mil_view",
+  "health",
+  "sensor_refs",
+  "communications",
+  "task_queue"
+]);
+function validateEntityComponents(components) {
+  for (const key of Object.keys(components)) {
+    if (!KNOWN_ENTITY_COMPONENTS.has(key) && !key.startsWith("custom_")) {
+      throw new Error(
+        `Unknown component '${key}' in entity components. Custom components must be prefixed with 'custom_'`
+      );
+    }
+  }
+}
+function stripNulls(obj) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === null || value === void 0) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      result[key] = value.map(
+        (item) => typeof item === "object" && item !== null ? stripNulls(item) : item
+      );
+    } else if (typeof value === "object") {
+      result[key] = stripNulls(value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function componentsToRecord(components) {
+  if (components === void 0) {
+    return void 0;
+  }
+  return stripNulls(components);
+}
+
 // src/httpClient.ts
 var AtlasHttpClient = class {
   baseUrl;
@@ -106,7 +154,10 @@ var AtlasHttpClient = class {
       alias,
       subtype
     };
-    if (components !== void 0) payload.components = components;
+    if (components !== void 0) {
+      validateEntityComponents(components);
+      payload.components = componentsToRecord(components);
+    }
     return this.request("POST", "/entities", payload);
   }
   updateEntity(entityId, components, options) {
@@ -114,7 +165,10 @@ var AtlasHttpClient = class {
       throw new Error("AtlasHttpClient.updateEntity requires a components payload or subtype.");
     }
     const payload = {};
-    if (components !== void 0) payload.components = components;
+    if (components !== void 0) {
+      validateEntityComponents(components);
+      payload.components = componentsToRecord(components);
+    }
     if (options?.subtype !== void 0) payload.subtype = options.subtype;
     return this.request("PATCH", `/entities/${entityId}`, payload);
   }
@@ -143,7 +197,7 @@ var AtlasHttpClient = class {
       status: options?.status || "pending"
     };
     if (options?.entity_id !== void 0) payload.entity_id = options.entity_id;
-    if (components !== void 0) payload.components = components;
+    if (components !== void 0) payload.components = componentsToRecord(components);
     if (options?.extra !== void 0) payload.extra = options.extra;
     return this.request("POST", "/tasks", payload);
   }
@@ -154,7 +208,7 @@ var AtlasHttpClient = class {
       );
     }
     const payload = {};
-    if (components !== void 0) payload.components = components;
+    if (components !== void 0) payload.components = componentsToRecord(components);
     if (options?.status !== void 0) payload.status = options.status;
     if (options?.entity_id !== void 0) payload.entity_id = options.entity_id;
     if (options?.extra !== void 0) payload.extra = options.extra;
@@ -267,5 +321,7 @@ var AtlasHttpClient = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  AtlasHttpClient
+  AtlasHttpClient,
+  componentsToRecord,
+  validateEntityComponents
 });

package/dist/index.d.cts

@@ -1,3 +1,184 @@
+/**
+ * Typed component interfaces for Atlas Command entities, tasks, and objects.
+ *
+ * These interfaces provide type safety and validation for component data
+ * before it is transmitted to the Atlas Command API.
+ */
+/**
+ * Position and motion data for entities.
+ */
+interface TelemetryComponent {
+    /** Latitude in degrees (WGS84) */
+    latitude?: number;
+    /** Longitude in degrees (WGS84) */
+    longitude?: number;
+    /** Altitude in meters above sea level */
+    altitude_m?: number;
+    /** Horizontal speed in meters/second */
+    speed_m_s?: number;
+    /** Heading in degrees (0=N, 90=E, etc.) */
+    heading_deg?: number;
+}
+/**
+ * GeoJSON geometry for geoentities.
+ */
+interface GeometryComponent {
+    /** GeoJSON geometry type */
+    type: "Point" | "LineString" | "Polygon";
+    /** GeoJSON coordinates ([lon, lat] for Point) */
+    coordinates: number[] | number[][] | number[][][];
+}
+/**
+ * Lists supported task identifiers for an asset.
+ */
+interface TaskCatalogComponent {
+    /** Task identifiers the asset can accept */
+    supported_tasks: string[];
+}
+/**
+ * A reference to a media object.
+ */
+interface MediaRefItem {
+    /** Object ID in object storage */
+    object_id: string;
+    /** Role of the media reference */
+    role: "camera_feed" | "thumbnail";
+}
+/**
+ * Military tactical classification component.
+ */
+interface MilViewComponent {
+    /** Tactical classification */
+    classification: "friendly" | "hostile" | "neutral" | "unknown" | "civilian";
+    /** ISO 8601 timestamp of last observation */
+    last_seen?: string;
+}
+/**
+ * Health and vital statistics for entities.
+ */
+interface HealthComponent {
+    /** Battery percentage (0-100) */
+    battery_percent?: number;
+}
+/**
+ * A reference to a sensor with FOV/orientation metadata.
+ */
+interface SensorRefItem {
+    /** Unique sensor identifier */
+    sensor_id: string;
+    /** Sensor type (e.g., 'radar') */
+    type: string;
+    /** Vertical field of view in degrees */
+    vertical_fov?: number;
+    /** Horizontal field of view in degrees */
+    horizontal_fov?: number;
+    /** Vertical orientation in degrees relative to level */
+    vertical_orientation?: number;
+    /** Horizontal orientation in degrees relative to front */
+    horizontal_orientation?: number;
+}
+/**
+ * Network link status component.
+ */
+interface CommunicationsComponent {
+    /** Network link state */
+    link_state: "connected" | "disconnected" | "degraded" | "unknown";
+}
+/**
+ * Current and queued work items for an entity.
+ */
+interface TaskQueueComponent {
+    /** Current task ID (null if idle) */
+    current_task_id: string | null;
+    /** Ordered list of queued task IDs */
+    queued_task_ids: string[];
+}
+/**
+ * All supported entity components with optional fields.
+ * Custom components (prefixed with custom_) are allowed via index signature.
+ */
+interface EntityComponents {
+    telemetry?: TelemetryComponent;
+    geometry?: GeometryComponent;
+    task_catalog?: TaskCatalogComponent;
+    media_refs?: MediaRefItem[];
+    mil_view?: MilViewComponent;
+    health?: HealthComponent;
+    sensor_refs?: SensorRefItem[];
+    communications?: CommunicationsComponent;
+    task_queue?: TaskQueueComponent;
+    /** Custom components must be prefixed with custom_ */
+    [key: `custom_${string}`]: unknown;
+}
+/**
+ * Command parameters for task execution.
+ */
+interface TaskParametersComponent {
+    latitude?: number;
+    longitude?: number;
+    altitude_m?: number;
+    /** Allow any additional parameters */
+    [key: string]: unknown;
+}
+/**
+ * Runtime telemetry about task execution.
+ */
+interface TaskProgressComponent {
+    /** Progress percentage (0-100) */
+    percent?: number;
+    /** ISO 8601 timestamp of last update */
+    updated_at?: string;
+    /** Human-readable status detail */
+    status_detail?: string;
+}
+/**
+ * All supported task components.
+ */
+interface TaskComponents {
+    parameters?: TaskParametersComponent;
+    progress?: TaskProgressComponent;
+    /** Allow any additional components */
+    [key: string]: unknown;
+}
+/**
+ * A reference from an object to an entity or task.
+ */
+interface ObjectReferenceItem {
+    entity_id?: string;
+    task_id?: string;
+}
+/**
+ * Metadata for stored objects (JSON blob fields).
+ */
+interface ObjectMetadata {
+    /** Storage bucket name */
+    bucket?: string;
+    /** File size in bytes */
+    size_bytes?: number;
+    /** Hints about object usage */
+    usage_hints?: string[];
+    /** Entities/tasks that reference this object */
+    referenced_by?: ObjectReferenceItem[];
+    /** Hash/checksum of object content */
+    checksum?: string;
+    /** ISO 8601 expiry timestamp */
+    expiry_time?: string;
+    /** Custom fields */
+    [key: `custom_${string}`]: unknown;
+}
+/**
+ * Validates that component keys are either known or prefixed with custom_.
+ */
+declare function validateEntityComponents(components: Record<string, unknown>): void;
+/**
+ * Convert typed components to a plain object for API transmission.
+ * Strips null and undefined values.
+ *
+ * @param components - Typed component object or raw record
+ * @returns Plain object suitable for JSON serialization
+ */
+declare function componentsToRecord(components: EntityComponents | TaskComponents | Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+
 interface FetchImplementation {
     (input: RequestInfo, init?: RequestInit): Promise<Response>;
 }
@@ -19,8 +200,8 @@ declare class AtlasHttpClient {
     listEntities(limit?: number, offset?: number): Promise<unknown>;
     getEntity(entityId: string): Promise<unknown>;
     getEntityByAlias(alias: string): Promise<unknown>;
-    createEntity(entityId: string, entityType: string, alias: string, subtype: string, components?: JsonRecord): Promise<unknown>;
-    updateEntity(entityId: string, components?: JsonRecord, options?: {
+    createEntity(entityId: string, entityType: string, alias: string, subtype: string, components?: EntityComponents | JsonRecord): Promise<unknown>;
+    updateEntity(entityId: string, components?: EntityComponents | JsonRecord, options?: {
         subtype?: string;
     }): Promise<unknown>;
     deleteEntity(entityId: string): Promise<unknown>;
@@ -33,12 +214,12 @@ declare class AtlasHttpClient {
     }): Promise<unknown>;
     listTasks(limit?: number, status?: string): Promise<unknown>;
     getTask(taskId: string): Promise<unknown>;
-    createTask(taskId: string, components?: JsonRecord, options?: {
+    createTask(taskId: string, components?: TaskComponents | JsonRecord, options?: {
         status?: string;
         entity_id?: string;
         extra?: JsonRecord;
     }): Promise<unknown>;
-    updateTask(taskId: string, components?: JsonRecord, options?: {
+    updateTask(taskId: string, components?: TaskComponents | JsonRecord, options?: {
         status?: string;
         entity_id?: string;
         extra?: JsonRecord;
@@ -217,4 +398,4 @@ interface FullDatasetOptions {
     object_limit?: number;
 }
 
-export { type Asset, AtlasHttpClient, type ChangedSinceOptions, type ClientOptions, type Command, type CommandDefinition, type Entity, type Event, type EventType, type FetchImplementation, type FullDatasetOptions, type GeoFeature, type JsonRecord, type Model, type ObjectCreate, type ObjectReference, type ObjectUpdate, type Sensor, type StoredObject, type Task, type TaskComplete, type TaskFail, type TaskStart, type TaskStatusUpdate, type Telemetry, type Track, type TrackTelemetry };
+export { type Asset, AtlasHttpClient, type ChangedSinceOptions, type ClientOptions, type Command, type CommandDefinition, type CommunicationsComponent, type Entity, type EntityComponents, type Event, type EventType, type FetchImplementation, type FullDatasetOptions, type GeoFeature, type GeometryComponent, type HealthComponent, type JsonRecord, type MediaRefItem, type MilViewComponent, type Model, type ObjectCreate, type ObjectMetadata, type ObjectReference, type ObjectReferenceItem, type ObjectUpdate, type Sensor, type SensorRefItem, type StoredObject, type Task, type TaskCatalogComponent, type TaskComplete, type TaskComponents, type TaskFail, type TaskParametersComponent, type TaskProgressComponent, type TaskQueueComponent, type TaskStart, type TaskStatusUpdate, type Telemetry, type TelemetryComponent, type Track, type TrackTelemetry, componentsToRecord, validateEntityComponents };

package/dist/index.d.ts

@@ -1,3 +1,184 @@
+/**
+ * Typed component interfaces for Atlas Command entities, tasks, and objects.
+ *
+ * These interfaces provide type safety and validation for component data
+ * before it is transmitted to the Atlas Command API.
+ */
+/**
+ * Position and motion data for entities.
+ */
+interface TelemetryComponent {
+    /** Latitude in degrees (WGS84) */
+    latitude?: number;
+    /** Longitude in degrees (WGS84) */
+    longitude?: number;
+    /** Altitude in meters above sea level */
+    altitude_m?: number;
+    /** Horizontal speed in meters/second */
+    speed_m_s?: number;
+    /** Heading in degrees (0=N, 90=E, etc.) */
+    heading_deg?: number;
+}
+/**
+ * GeoJSON geometry for geoentities.
+ */
+interface GeometryComponent {
+    /** GeoJSON geometry type */
+    type: "Point" | "LineString" | "Polygon";
+    /** GeoJSON coordinates ([lon, lat] for Point) */
+    coordinates: number[] | number[][] | number[][][];
+}
+/**
+ * Lists supported task identifiers for an asset.
+ */
+interface TaskCatalogComponent {
+    /** Task identifiers the asset can accept */
+    supported_tasks: string[];
+}
+/**
+ * A reference to a media object.
+ */
+interface MediaRefItem {
+    /** Object ID in object storage */
+    object_id: string;
+    /** Role of the media reference */
+    role: "camera_feed" | "thumbnail";
+}
+/**
+ * Military tactical classification component.
+ */
+interface MilViewComponent {
+    /** Tactical classification */
+    classification: "friendly" | "hostile" | "neutral" | "unknown" | "civilian";
+    /** ISO 8601 timestamp of last observation */
+    last_seen?: string;
+}
+/**
+ * Health and vital statistics for entities.
+ */
+interface HealthComponent {
+    /** Battery percentage (0-100) */
+    battery_percent?: number;
+}
+/**
+ * A reference to a sensor with FOV/orientation metadata.
+ */
+interface SensorRefItem {
+    /** Unique sensor identifier */
+    sensor_id: string;
+    /** Sensor type (e.g., 'radar') */
+    type: string;
+    /** Vertical field of view in degrees */
+    vertical_fov?: number;
+    /** Horizontal field of view in degrees */
+    horizontal_fov?: number;
+    /** Vertical orientation in degrees relative to level */
+    vertical_orientation?: number;
+    /** Horizontal orientation in degrees relative to front */
+    horizontal_orientation?: number;
+}
+/**
+ * Network link status component.
+ */
+interface CommunicationsComponent {
+    /** Network link state */
+    link_state: "connected" | "disconnected" | "degraded" | "unknown";
+}
+/**
+ * Current and queued work items for an entity.
+ */
+interface TaskQueueComponent {
+    /** Current task ID (null if idle) */
+    current_task_id: string | null;
+    /** Ordered list of queued task IDs */
+    queued_task_ids: string[];
+}
+/**
+ * All supported entity components with optional fields.
+ * Custom components (prefixed with custom_) are allowed via index signature.
+ */
+interface EntityComponents {
+    telemetry?: TelemetryComponent;
+    geometry?: GeometryComponent;
+    task_catalog?: TaskCatalogComponent;
+    media_refs?: MediaRefItem[];
+    mil_view?: MilViewComponent;
+    health?: HealthComponent;
+    sensor_refs?: SensorRefItem[];
+    communications?: CommunicationsComponent;
+    task_queue?: TaskQueueComponent;
+    /** Custom components must be prefixed with custom_ */
+    [key: `custom_${string}`]: unknown;
+}
+/**
+ * Command parameters for task execution.
+ */
+interface TaskParametersComponent {
+    latitude?: number;
+    longitude?: number;
+    altitude_m?: number;
+    /** Allow any additional parameters */
+    [key: string]: unknown;
+}
+/**
+ * Runtime telemetry about task execution.
+ */
+interface TaskProgressComponent {
+    /** Progress percentage (0-100) */
+    percent?: number;
+    /** ISO 8601 timestamp of last update */
+    updated_at?: string;
+    /** Human-readable status detail */
+    status_detail?: string;
+}
+/**
+ * All supported task components.
+ */
+interface TaskComponents {
+    parameters?: TaskParametersComponent;
+    progress?: TaskProgressComponent;
+    /** Allow any additional components */
+    [key: string]: unknown;
+}
+/**
+ * A reference from an object to an entity or task.
+ */
+interface ObjectReferenceItem {
+    entity_id?: string;
+    task_id?: string;
+}
+/**
+ * Metadata for stored objects (JSON blob fields).
+ */
+interface ObjectMetadata {
+    /** Storage bucket name */
+    bucket?: string;
+    /** File size in bytes */
+    size_bytes?: number;
+    /** Hints about object usage */
+    usage_hints?: string[];
+    /** Entities/tasks that reference this object */
+    referenced_by?: ObjectReferenceItem[];
+    /** Hash/checksum of object content */
+    checksum?: string;
+    /** ISO 8601 expiry timestamp */
+    expiry_time?: string;
+    /** Custom fields */
+    [key: `custom_${string}`]: unknown;
+}
+/**
+ * Validates that component keys are either known or prefixed with custom_.
+ */
+declare function validateEntityComponents(components: Record<string, unknown>): void;
+/**
+ * Convert typed components to a plain object for API transmission.
+ * Strips null and undefined values.
+ *
+ * @param components - Typed component object or raw record
+ * @returns Plain object suitable for JSON serialization
+ */
+declare function componentsToRecord(components: EntityComponents | TaskComponents | Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+
 interface FetchImplementation {
     (input: RequestInfo, init?: RequestInit): Promise<Response>;
 }
@@ -19,8 +200,8 @@ declare class AtlasHttpClient {
     listEntities(limit?: number, offset?: number): Promise<unknown>;
     getEntity(entityId: string): Promise<unknown>;
     getEntityByAlias(alias: string): Promise<unknown>;
-    createEntity(entityId: string, entityType: string, alias: string, subtype: string, components?: JsonRecord): Promise<unknown>;
-    updateEntity(entityId: string, components?: JsonRecord, options?: {
+    createEntity(entityId: string, entityType: string, alias: string, subtype: string, components?: EntityComponents | JsonRecord): Promise<unknown>;
+    updateEntity(entityId: string, components?: EntityComponents | JsonRecord, options?: {
         subtype?: string;
     }): Promise<unknown>;
     deleteEntity(entityId: string): Promise<unknown>;
@@ -33,12 +214,12 @@ declare class AtlasHttpClient {
     }): Promise<unknown>;
     listTasks(limit?: number, status?: string): Promise<unknown>;
     getTask(taskId: string): Promise<unknown>;
-    createTask(taskId: string, components?: JsonRecord, options?: {
+    createTask(taskId: string, components?: TaskComponents | JsonRecord, options?: {
         status?: string;
         entity_id?: string;
         extra?: JsonRecord;
     }): Promise<unknown>;
-    updateTask(taskId: string, components?: JsonRecord, options?: {
+    updateTask(taskId: string, components?: TaskComponents | JsonRecord, options?: {
         status?: string;
         entity_id?: string;
         extra?: JsonRecord;
@@ -217,4 +398,4 @@ interface FullDatasetOptions {
     object_limit?: number;
 }
 
-export { type Asset, AtlasHttpClient, type ChangedSinceOptions, type ClientOptions, type Command, type CommandDefinition, type Entity, type Event, type EventType, type FetchImplementation, type FullDatasetOptions, type GeoFeature, type JsonRecord, type Model, type ObjectCreate, type ObjectReference, type ObjectUpdate, type Sensor, type StoredObject, type Task, type TaskComplete, type TaskFail, type TaskStart, type TaskStatusUpdate, type Telemetry, type Track, type TrackTelemetry };
+export { type Asset, AtlasHttpClient, type ChangedSinceOptions, type ClientOptions, type Command, type CommandDefinition, type CommunicationsComponent, type Entity, type EntityComponents, type Event, type EventType, type FetchImplementation, type FullDatasetOptions, type GeoFeature, type GeometryComponent, type HealthComponent, type JsonRecord, type MediaRefItem, type MilViewComponent, type Model, type ObjectCreate, type ObjectMetadata, type ObjectReference, type ObjectReferenceItem, type ObjectUpdate, type Sensor, type SensorRefItem, type StoredObject, type Task, type TaskCatalogComponent, type TaskComplete, type TaskComponents, type TaskFail, type TaskParametersComponent, type TaskProgressComponent, type TaskQueueComponent, type TaskStart, type TaskStatusUpdate, type Telemetry, type TelemetryComponent, type Track, type TrackTelemetry, componentsToRecord, validateEntityComponents };

package/dist/index.js

@@ -1,3 +1,49 @@
+// src/types/components.ts
+var KNOWN_ENTITY_COMPONENTS = /* @__PURE__ */ new Set([
+  "telemetry",
+  "geometry",
+  "task_catalog",
+  "media_refs",
+  "mil_view",
+  "health",
+  "sensor_refs",
+  "communications",
+  "task_queue"
+]);
+function validateEntityComponents(components) {
+  for (const key of Object.keys(components)) {
+    if (!KNOWN_ENTITY_COMPONENTS.has(key) && !key.startsWith("custom_")) {
+      throw new Error(
+        `Unknown component '${key}' in entity components. Custom components must be prefixed with 'custom_'`
+      );
+    }
+  }
+}
+function stripNulls(obj) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === null || value === void 0) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      result[key] = value.map(
+        (item) => typeof item === "object" && item !== null ? stripNulls(item) : item
+      );
+    } else if (typeof value === "object") {
+      result[key] = stripNulls(value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function componentsToRecord(components) {
+  if (components === void 0) {
+    return void 0;
+  }
+  return stripNulls(components);
+}
+
 // src/httpClient.ts
 var AtlasHttpClient = class {
   baseUrl;
@@ -80,7 +126,10 @@ var AtlasHttpClient = class {
       alias,
       subtype
     };
-    if (components !== void 0) payload.components = components;
+    if (components !== void 0) {
+      validateEntityComponents(components);
+      payload.components = componentsToRecord(components);
+    }
     return this.request("POST", "/entities", payload);
   }
   updateEntity(entityId, components, options) {
@@ -88,7 +137,10 @@ var AtlasHttpClient = class {
       throw new Error("AtlasHttpClient.updateEntity requires a components payload or subtype.");
     }
     const payload = {};
-    if (components !== void 0) payload.components = components;
+    if (components !== void 0) {
+      validateEntityComponents(components);
+      payload.components = componentsToRecord(components);
+    }
     if (options?.subtype !== void 0) payload.subtype = options.subtype;
     return this.request("PATCH", `/entities/${entityId}`, payload);
   }
@@ -117,7 +169,7 @@ var AtlasHttpClient = class {
       status: options?.status || "pending"
     };
     if (options?.entity_id !== void 0) payload.entity_id = options.entity_id;
-    if (components !== void 0) payload.components = components;
+    if (components !== void 0) payload.components = componentsToRecord(components);
     if (options?.extra !== void 0) payload.extra = options.extra;
     return this.request("POST", "/tasks", payload);
   }
@@ -128,7 +180,7 @@ var AtlasHttpClient = class {
       );
     }
     const payload = {};
-    if (components !== void 0) payload.components = components;
+    if (components !== void 0) payload.components = componentsToRecord(components);
     if (options?.status !== void 0) payload.status = options.status;
     if (options?.entity_id !== void 0) payload.entity_id = options.entity_id;
     if (options?.extra !== void 0) payload.extra = options.extra;
@@ -240,5 +292,7 @@ var AtlasHttpClient = class {
   }
 };
 export {
-  AtlasHttpClient
+  AtlasHttpClient,
+  componentsToRecord,
+  validateEntityComponents
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlasnpm/atlas-api-helper",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "type": "module",
   "description": "HTTP client for the Atlas Command REST API.",
   "license": "MIT",