@atlasnpm/atlas-api-helper 0.2.4 → 0.2.6

package/README.md

@@ -1,7 +1,5 @@
 # Atlas Command HTTP Client (TypeScript)
 
-`@atlasnpm/atlas-api-helper` has been updated to version 0.2.1 with a comprehensive HTTP client for the Atlas Command REST API. This version now includes full API parity with the Python `atlas_asset_ws_client` package.
-
 ## Installation
 
 ```bash
@@ -22,13 +20,12 @@ const client = new AtlasHttpClient({
 const entities = await client.listEntities();
 console.log("Entities", entities);
 
-await client.createTask({
-  task_id: "survey-1",
-  status: "pending",
-  components: { parameters: { latitude: 40.7, longitude: -74.0 } },
+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 } });
 
-// New API methods (version 0.2.1)
+// Entity telemetry updates
 const entity = await client.getEntityByAlias("drone-1");
 await client.updateEntityTelemetry("drone-1", {
   latitude: 40.7128,
@@ -39,8 +36,18 @@ await client.updateEntityTelemetry("drone-1", {
 });
 
 // Task lifecycle management
-await client.startTask("task-1", { started_by: "operator-1" });
-await client.completeTask("task-1", { result: { data: "success" } });
+await client.startTask("task-1");
+await client.completeTask("task-1");
+await client.failTask("task-2", "Calibration failed", { code: "CAL-01" });
+
+// Object upload + reference helpers
+const stored = await client.createObject(videoBlob, "mission-video", "mission_video", [
+  { entity_id: "asset-1" },
+]);
+await client.addObjectReference(stored["object_id"] as string, undefined, "task-1");
+await client.updateObject("mission-video", ["mission_video"], [
+  { task_id: "task-1" },
+]);
 
 // Query capabilities
 const changes = await client.getChangedSince("2023-01-01T00:00:00Z", 10);
@@ -55,36 +62,33 @@ const fullData = await client.getFullDataset({
 
 The client now exposes comprehensive helpers for every HTTP endpoint, matching the Python client:
 
-### Entities
 - `listEntities(limit?, offset?)` - List all entities with pagination
 - `getEntity(entityId)` - Get a specific entity by ID
 - `getEntityByAlias(alias)` - Get entity by alias (NEW in 0.2.1)
-- `createEntity(body)` - Create a new entity
-- `updateEntity(entityId, body)` - Update an existing entity
+- `createEntity(entityId, entityType, alias, subtype, components?)` - Create a new entity
+- `updateEntity(entityId, components)` - Update an existing entity (components payload required)
 - `deleteEntity(entityId)` - Delete an entity
 - `updateEntityTelemetry(entityId, telemetry)` - Update entity telemetry with specific parameters (NEW in 0.2.1)
 
-### Tasks
 - `listTasks(limit?, status?)` - List tasks with optional status filter
 - `getTask(taskId)` - Get a specific task
-- `createTask(body)` - Create a new task
-- `updateTask(taskId, body)` - Update an existing task
+- `createTask(taskId, components?)` - Create a new task
+- `updateTask(taskId, components)` - Update an existing task (components payload required)
 - `deleteTask(taskId)` - Delete a task
 - `getTasksByEntity(entityId, limit?, status?)` - Get tasks by entity
-- `startTask(taskId, started_by?)` - Start a task (NEW in 0.2.1)
-- `completeTask(taskId, result?)` - Complete a task (NEW in 0.2.1)
-- `failTask(taskId, error_message?, error_details?)` - Fail a task (NEW in 0.2.1)
+- `startTask(taskId)` - Start a task (NEW in 0.2.1)
+- `completeTask(taskId)` - Complete a task (NEW in 0.2.1)
+- `failTask(taskId, errorMessage?, errorDetails?)` - Fail a task (NEW in 0.2.1)
 
-### Objects
 - `listObjects(limit?, offset?, contentType?)` - List objects with filters
 - `getObject(objectId)` - Get a specific object
-- `createObject(body)` - Create a new object
-- `updateObject(objectId, body)` - Update an existing object
+- `createObject(file, objectId, usageHint?, referencedBy?)` - Upload an object and optionally assign references
+- `updateObject(objectId, usageHints?, referencedBy?)` - Update metadata and references (at least one of `usageHints` or `referencedBy` is required)
 - `deleteObject(objectId)` - Delete an object
 - `getObjectsByEntity(entityId, limit?)` - Get objects by entity
 - `getObjectsByTask(taskId, limit?)` - Get objects by task
-- `addObjectReference(objectId, entity_id?, task_id?)` - Add object reference
-- `removeObjectReference(objectId, entity_id?, task_id?)` - Remove object reference
+- `addObjectReference(objectId, entityId?, taskId?)` - Add object reference
+- `removeObjectReference(objectId, entityId?, taskId?)` - Remove object reference
 - `findOrphanedObjects(limit?)` - Find orphaned objects
 - `getObjectReferences(objectId)` - Get object references
 - `validateObjectReferences(objectId)` - Validate object references
@@ -133,18 +137,6 @@ npm run test
 
 The build produces both ESM and CJS bundles plus `.d.ts` type definitions via `tsup`.
 
-## Version 0.2.1 Changes
-
-This update brings the TypeScript client to full feature parity with the Python `atlas_asset_ws_client` package:
-
-- ✅ Added `getEntityByAlias` method
-- ✅ Added `updateEntityTelemetry` with specific telemetry parameters
-- ✅ Added task lifecycle methods: `startTask`, `completeTask`, `failTask`
-- ✅ Added query methods: `getChangedSince`, `getFullDataset`
-- ✅ Enhanced type system with comprehensive interfaces
-- ✅ Updated to match Python API signatures and behavior
-- ✅ Version bump to 0.2.1 to match Python package
-
 ## Publishing
 
-Publishing is handled by `.github/workflows/publish-controller-websocket-client.yml`. The artifact now contains the comprehensive HTTP client described above. Ensure the `@atlasnpm` scope and automation token are set up as documented in the workflow README before triggering a release.
+Publishing is handled by `.github/workflows/publish-atlas-api-helper.yml`. The artifact now contains the comprehensive HTTP client described above. Ensure the `@atlasnpm` scope and automation token are set up as documented in the workflow README before triggering a release.

package/dist/index.cjs

@@ -44,6 +44,13 @@ var AtlasHttpClient = class {
     }
     return headers;
   }
+  multipartHeaders() {
+    const headers = {};
+    if (this.token) {
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+    return headers;
+  }
   async request(method, path, body, params) {
     const url = new URL(`${this.baseUrl}${path}`);
     if (params) {
@@ -66,6 +73,22 @@ var AtlasHttpClient = class {
     }
     return await response.json();
   }
+  async multipartRequest(path, formData) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    const response = await this.fetchImpl(url.toString(), {
+      method: "POST",
+      headers: this.multipartHeaders(),
+      body: formData
+    });
+    if (!response.ok) {
+      const detail = await response.text();
+      throw new Error(`HTTP ${response.status}: ${detail}`);
+    }
+    if (response.status === 204) {
+      return void 0;
+    }
+    return await response.json();
+  }
   // Entities ------------------------------------------------------------------
   listEntities(limit = 100, offset = 0) {
     return this.request("GET", "/entities", null, { limit, offset });
@@ -76,17 +99,36 @@ var AtlasHttpClient = class {
   getEntityByAlias(alias) {
     return this.request("GET", `/entities/alias/${alias}`);
   }
-  createEntity(body) {
-    return this.request("POST", "/entities", body);
-  }
-  updateEntity(entityId, body) {
-    return this.request("PATCH", `/entities/${entityId}`, body);
+  createEntity(entityId, entityType, alias, subtype, components) {
+    const payload = {
+      entity_id: entityId,
+      entity_type: entityType,
+      alias,
+      subtype
+    };
+    if (components !== void 0) payload.components = components;
+    return this.request("POST", "/entities", payload);
+  }
+  updateEntity(entityId, components, options) {
+    if (components === void 0 && options?.subtype === void 0) {
+      throw new Error("AtlasHttpClient.updateEntity requires a components payload or subtype.");
+    }
+    const payload = {};
+    if (components !== void 0) payload.components = components;
+    if (options?.subtype !== void 0) payload.subtype = options.subtype;
+    return this.request("PATCH", `/entities/${entityId}`, payload);
   }
   deleteEntity(entityId) {
     return this.request("DELETE", `/entities/${entityId}`);
   }
-  updateEntityTelemetry(entityId, body) {
-    return this.request("PATCH", `/entities/${entityId}/telemetry`, body);
+  updateEntityTelemetry(entityId, options) {
+    const payload = {};
+    if (options.latitude !== void 0) payload.latitude = options.latitude;
+    if (options.longitude !== void 0) payload.longitude = options.longitude;
+    if (options.altitude_m !== void 0) payload.altitude_m = options.altitude_m;
+    if (options.speed_m_s !== void 0) payload.speed_m_s = options.speed_m_s;
+    if (options.heading_deg !== void 0) payload.heading_deg = options.heading_deg;
+    return this.request("PATCH", `/entities/${entityId}/telemetry`, payload);
   }
   // Tasks ---------------------------------------------------------------------
   listTasks(limit = 25, status) {
@@ -95,11 +137,28 @@ var AtlasHttpClient = class {
   getTask(taskId) {
     return this.request("GET", `/tasks/${taskId}`);
   }
-  createTask(body) {
-    return this.request("POST", "/tasks", body);
-  }
-  updateTask(taskId, body) {
-    return this.request("PATCH", `/tasks/${taskId}`, body);
+  createTask(taskId, components, options) {
+    const payload = {
+      task_id: taskId,
+      status: options?.status || "pending"
+    };
+    if (options?.entity_id !== void 0) payload.entity_id = options.entity_id;
+    if (components !== void 0) payload.components = components;
+    if (options?.extra !== void 0) payload.extra = options.extra;
+    return this.request("POST", "/tasks", payload);
+  }
+  updateTask(taskId, components, options) {
+    if (components === void 0 && options === void 0) {
+      throw new Error(
+        "AtlasHttpClient.updateTask requires a components payload or options."
+      );
+    }
+    const payload = {};
+    if (components !== void 0) payload.components = 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;
+    return this.request("PATCH", `/tasks/${taskId}`, payload);
   }
   deleteTask(taskId) {
     return this.request("DELETE", `/tasks/${taskId}`);
@@ -107,27 +166,56 @@ var AtlasHttpClient = class {
   getTasksByEntity(entityId, limit = 25, status) {
     return this.request("GET", `/entities/${entityId}/tasks`, null, { limit, status });
   }
-  startTask(taskId, body = {}) {
-    return this.request("POST", `/tasks/${taskId}/start`, body);
+  startTask(taskId) {
+    return this.request("POST", `/tasks/${taskId}/start`, {});
   }
-  completeTask(taskId, body = {}) {
-    return this.request("POST", `/tasks/${taskId}/complete`, body);
+  completeTask(taskId) {
+    return this.request("POST", `/tasks/${taskId}/complete`, {});
   }
-  failTask(taskId, body = {}) {
-    return this.request("POST", `/tasks/${taskId}/fail`, body);
+  failTask(taskId, errorMessage, errorDetails) {
+    const payload = {};
+    if (errorMessage !== void 0) payload.error_message = errorMessage;
+    if (errorDetails !== void 0) payload.error_details = errorDetails;
+    return this.request("POST", `/tasks/${taskId}/fail`, payload);
   }
   // Objects -------------------------------------------------------------------
-  listObjects(limit = 100, offset = 0, contentType) {
-    return this.request("GET", "/objects", null, { limit, offset, content_type: contentType });
+  listObjects(limit = 100, offset = 0, contentType, type) {
+    return this.request("GET", "/objects", null, { limit, offset, content_type: contentType, type });
   }
   getObject(objectId) {
     return this.request("GET", `/objects/${objectId}`);
   }
-  createObject(body) {
-    return this.request("POST", "/objects", body);
+  async createObject(file, objectId, usageHint, referencedBy) {
+    const formData = new FormData();
+    formData.append("object_id", objectId);
+    const filename = file.name ?? "upload.bin";
+    formData.append("file", file, filename);
+    if (usageHint) {
+      formData.append("usage_hint", usageHint);
+    }
+    const stored = await this.multipartRequest("/objects/upload", formData);
+    const storedObjectId = stored["object_id"];
+    if (referencedBy && storedObjectId !== void 0) {
+      for (const reference of referencedBy) {
+        await this.addObjectReference(storedObjectId, reference.entity_id, reference.task_id);
+      }
+    } else if (referencedBy && storedObjectId === void 0) {
+      throw new Error(
+        "AtlasHttpClient.createObject expected the upload response to include an object_id before attaching references."
+      );
+    }
+    return stored;
   }
-  updateObject(objectId, body) {
-    return this.request("PATCH", `/objects/${objectId}`, body);
+  updateObject(objectId, usageHints, referencedBy) {
+    if (usageHints === void 0 && referencedBy === void 0) {
+      throw new Error(
+        "AtlasHttpClient.updateObject requires usageHints or referencedBy to make an update."
+      );
+    }
+    const payload = {};
+    if (usageHints !== void 0) payload.usage_hints = usageHints;
+    if (referencedBy !== void 0) payload.referenced_by = referencedBy;
+    return this.request("PATCH", `/objects/${objectId}`, payload);
   }
   deleteObject(objectId) {
     return this.request("DELETE", `/objects/${objectId}`);
@@ -138,11 +226,17 @@ var AtlasHttpClient = class {
   getObjectsByTask(taskId, limit = 50) {
     return this.request("GET", `/tasks/${taskId}/objects`, null, { limit });
   }
-  addObjectReference(objectId, body) {
-    return this.request("POST", `/objects/${objectId}/references`, body);
-  }
-  removeObjectReference(objectId, body) {
-    return this.request("DELETE", `/objects/${objectId}/references`, body);
+  addObjectReference(objectId, entityId, taskId) {
+    const payload = {};
+    if (entityId !== void 0) payload.entity_id = entityId;
+    if (taskId !== void 0) payload.task_id = taskId;
+    return this.request("POST", `/objects/${objectId}/references`, payload);
+  }
+  removeObjectReference(objectId, entityId, taskId) {
+    const payload = {};
+    if (entityId !== void 0) payload.entity_id = entityId;
+    if (taskId !== void 0) payload.task_id = taskId;
+    return this.request("DELETE", `/objects/${objectId}/references`, payload);
   }
   findOrphanedObjects(limit = 100) {
     return this.request("GET", "/objects/orphaned", null, { limit });

package/dist/index.d.cts

@@ -13,14 +13,18 @@ declare class AtlasHttpClient {
     private readonly fetchImpl;
     constructor(options: ClientOptions);
     private headers;
+    private multipartHeaders;
     private request;
+    private multipartRequest;
     listEntities(limit?: number, offset?: number): Promise<unknown>;
     getEntity(entityId: string): Promise<unknown>;
     getEntityByAlias(alias: string): Promise<unknown>;
-    createEntity(body: JsonRecord): Promise<unknown>;
-    updateEntity(entityId: string, body: JsonRecord): Promise<unknown>;
+    createEntity(entityId: string, entityType: string, alias: string, subtype: string, components?: JsonRecord): Promise<unknown>;
+    updateEntity(entityId: string, components?: JsonRecord, options?: {
+        subtype?: string;
+    }): Promise<unknown>;
     deleteEntity(entityId: string): Promise<unknown>;
-    updateEntityTelemetry(entityId: string, body: {
+    updateEntityTelemetry(entityId: string, options: {
         latitude?: number;
         longitude?: number;
         altitude_m?: number;
@@ -29,35 +33,36 @@ declare class AtlasHttpClient {
     }): Promise<unknown>;
     listTasks(limit?: number, status?: string): Promise<unknown>;
     getTask(taskId: string): Promise<unknown>;
-    createTask(body: JsonRecord): Promise<unknown>;
-    updateTask(taskId: string, body: JsonRecord): Promise<unknown>;
-    deleteTask(taskId: string): Promise<unknown>;
-    getTasksByEntity(entityId: string, limit?: number, status?: string): Promise<unknown>;
-    startTask(taskId: string, body?: {
-        started_by?: string;
-    }): Promise<unknown>;
-    completeTask(taskId: string, body?: {
-        result?: JsonRecord;
+    createTask(taskId: string, components?: JsonRecord, options?: {
+        status?: string;
+        entity_id?: string;
+        extra?: JsonRecord;
     }): Promise<unknown>;
-    failTask(taskId: string, body?: {
-        error_message?: string;
-        error_details?: JsonRecord;
+    updateTask(taskId: string, components?: JsonRecord, options?: {
+        status?: string;
+        entity_id?: string;
+        extra?: JsonRecord;
     }): Promise<unknown>;
-    listObjects(limit?: number, offset?: number, contentType?: string): Promise<unknown>;
+    deleteTask(taskId: string): Promise<unknown>;
+    getTasksByEntity(entityId: string, limit?: number, status?: string): Promise<unknown>;
+    startTask(taskId: string): Promise<unknown>;
+    completeTask(taskId: string): Promise<unknown>;
+    failTask(taskId: string, errorMessage?: string, errorDetails?: JsonRecord): Promise<unknown>;
+    listObjects(limit?: number, offset?: number, contentType?: string, type?: string): Promise<unknown>;
     getObject(objectId: string): Promise<unknown>;
-    createObject(body: JsonRecord): Promise<unknown>;
-    updateObject(objectId: string, body: JsonRecord): Promise<unknown>;
-    deleteObject(objectId: string): Promise<unknown>;
-    getObjectsByEntity(entityId: string, limit?: number): Promise<unknown>;
-    getObjectsByTask(taskId: string, limit?: number): Promise<unknown>;
-    addObjectReference(objectId: string, body: {
+    createObject(file: Blob | File, objectId: string, usageHint?: string, referencedBy?: Array<{
         entity_id?: string;
         task_id?: string;
-    }): Promise<unknown>;
-    removeObjectReference(objectId: string, body: {
+    }>): Promise<JsonRecord>;
+    updateObject(objectId: string, usageHints?: string[], referencedBy?: Array<{
         entity_id?: string;
         task_id?: string;
-    }): Promise<unknown>;
+    }>): Promise<unknown>;
+    deleteObject(objectId: string): Promise<unknown>;
+    getObjectsByEntity(entityId: string, limit?: number): Promise<unknown>;
+    getObjectsByTask(taskId: string, limit?: number): Promise<unknown>;
+    addObjectReference(objectId: string, entityId?: string, taskId?: string): Promise<unknown>;
+    removeObjectReference(objectId: string, entityId?: string, taskId?: string): Promise<unknown>;
     findOrphanedObjects(limit?: number): Promise<unknown>;
     getObjectReferences(objectId: string): Promise<unknown>;
     validateObjectReferences(objectId: string): Promise<unknown>;
@@ -72,9 +77,10 @@ declare class AtlasHttpClient {
 
 interface Entity {
     entity_id: string;
+    type: string;
+    subtype?: string;
+    alias?: string;
     json: {
-        type: "asset" | "track" | "geofeature" | string;
-        alias?: string;
         components?: Record<string, unknown>;
         [key: string]: unknown;
     };
@@ -83,8 +89,9 @@ interface Entity {
 }
 interface Task {
     task_id: string;
+    status: string;
+    entity_id?: string;
     json: {
-        status: string;
         components?: Record<string, unknown>;
         [key: string]: unknown;
     };
@@ -93,6 +100,9 @@ interface Task {
 }
 interface StoredObject {
     object_id: string;
+    path?: string;
+    content_type?: string;
+    type?: string;
     json: Record<string, unknown>;
     created_at?: string;
     updated_at?: string;
@@ -182,6 +192,7 @@ interface ObjectCreate {
     bucket?: string;
     size_bytes?: number;
     content_type?: string;
+    type?: string;
     usage_hints?: string[];
     referenced_by?: ObjectReference[];
     extra?: Record<string, unknown>;
@@ -191,6 +202,7 @@ interface ObjectUpdate {
     bucket?: string;
     size_bytes?: number;
     content_type?: string;
+    type?: string;
     usage_hints?: string[];
     referenced_by?: ObjectReference[];
     extra?: Record<string, unknown>;

package/dist/index.d.ts

@@ -13,14 +13,18 @@ declare class AtlasHttpClient {
     private readonly fetchImpl;
     constructor(options: ClientOptions);
     private headers;
+    private multipartHeaders;
     private request;
+    private multipartRequest;
     listEntities(limit?: number, offset?: number): Promise<unknown>;
     getEntity(entityId: string): Promise<unknown>;
     getEntityByAlias(alias: string): Promise<unknown>;
-    createEntity(body: JsonRecord): Promise<unknown>;
-    updateEntity(entityId: string, body: JsonRecord): Promise<unknown>;
+    createEntity(entityId: string, entityType: string, alias: string, subtype: string, components?: JsonRecord): Promise<unknown>;
+    updateEntity(entityId: string, components?: JsonRecord, options?: {
+        subtype?: string;
+    }): Promise<unknown>;
     deleteEntity(entityId: string): Promise<unknown>;
-    updateEntityTelemetry(entityId: string, body: {
+    updateEntityTelemetry(entityId: string, options: {
         latitude?: number;
         longitude?: number;
         altitude_m?: number;
@@ -29,35 +33,36 @@ declare class AtlasHttpClient {
     }): Promise<unknown>;
     listTasks(limit?: number, status?: string): Promise<unknown>;
     getTask(taskId: string): Promise<unknown>;
-    createTask(body: JsonRecord): Promise<unknown>;
-    updateTask(taskId: string, body: JsonRecord): Promise<unknown>;
-    deleteTask(taskId: string): Promise<unknown>;
-    getTasksByEntity(entityId: string, limit?: number, status?: string): Promise<unknown>;
-    startTask(taskId: string, body?: {
-        started_by?: string;
-    }): Promise<unknown>;
-    completeTask(taskId: string, body?: {
-        result?: JsonRecord;
+    createTask(taskId: string, components?: JsonRecord, options?: {
+        status?: string;
+        entity_id?: string;
+        extra?: JsonRecord;
     }): Promise<unknown>;
-    failTask(taskId: string, body?: {
-        error_message?: string;
-        error_details?: JsonRecord;
+    updateTask(taskId: string, components?: JsonRecord, options?: {
+        status?: string;
+        entity_id?: string;
+        extra?: JsonRecord;
     }): Promise<unknown>;
-    listObjects(limit?: number, offset?: number, contentType?: string): Promise<unknown>;
+    deleteTask(taskId: string): Promise<unknown>;
+    getTasksByEntity(entityId: string, limit?: number, status?: string): Promise<unknown>;
+    startTask(taskId: string): Promise<unknown>;
+    completeTask(taskId: string): Promise<unknown>;
+    failTask(taskId: string, errorMessage?: string, errorDetails?: JsonRecord): Promise<unknown>;
+    listObjects(limit?: number, offset?: number, contentType?: string, type?: string): Promise<unknown>;
     getObject(objectId: string): Promise<unknown>;
-    createObject(body: JsonRecord): Promise<unknown>;
-    updateObject(objectId: string, body: JsonRecord): Promise<unknown>;
-    deleteObject(objectId: string): Promise<unknown>;
-    getObjectsByEntity(entityId: string, limit?: number): Promise<unknown>;
-    getObjectsByTask(taskId: string, limit?: number): Promise<unknown>;
-    addObjectReference(objectId: string, body: {
+    createObject(file: Blob | File, objectId: string, usageHint?: string, referencedBy?: Array<{
         entity_id?: string;
         task_id?: string;
-    }): Promise<unknown>;
-    removeObjectReference(objectId: string, body: {
+    }>): Promise<JsonRecord>;
+    updateObject(objectId: string, usageHints?: string[], referencedBy?: Array<{
         entity_id?: string;
         task_id?: string;
-    }): Promise<unknown>;
+    }>): Promise<unknown>;
+    deleteObject(objectId: string): Promise<unknown>;
+    getObjectsByEntity(entityId: string, limit?: number): Promise<unknown>;
+    getObjectsByTask(taskId: string, limit?: number): Promise<unknown>;
+    addObjectReference(objectId: string, entityId?: string, taskId?: string): Promise<unknown>;
+    removeObjectReference(objectId: string, entityId?: string, taskId?: string): Promise<unknown>;
     findOrphanedObjects(limit?: number): Promise<unknown>;
     getObjectReferences(objectId: string): Promise<unknown>;
     validateObjectReferences(objectId: string): Promise<unknown>;
@@ -72,9 +77,10 @@ declare class AtlasHttpClient {
 
 interface Entity {
     entity_id: string;
+    type: string;
+    subtype?: string;
+    alias?: string;
     json: {
-        type: "asset" | "track" | "geofeature" | string;
-        alias?: string;
         components?: Record<string, unknown>;
         [key: string]: unknown;
     };
@@ -83,8 +89,9 @@ interface Entity {
 }
 interface Task {
     task_id: string;
+    status: string;
+    entity_id?: string;
     json: {
-        status: string;
         components?: Record<string, unknown>;
         [key: string]: unknown;
     };
@@ -93,6 +100,9 @@ interface Task {
 }
 interface StoredObject {
     object_id: string;
+    path?: string;
+    content_type?: string;
+    type?: string;
     json: Record<string, unknown>;
     created_at?: string;
     updated_at?: string;
@@ -182,6 +192,7 @@ interface ObjectCreate {
     bucket?: string;
     size_bytes?: number;
     content_type?: string;
+    type?: string;
     usage_hints?: string[];
     referenced_by?: ObjectReference[];
     extra?: Record<string, unknown>;
@@ -191,6 +202,7 @@ interface ObjectUpdate {
     bucket?: string;
     size_bytes?: number;
     content_type?: string;
+    type?: string;
     usage_hints?: string[];
     referenced_by?: ObjectReference[];
     extra?: Record<string, unknown>;

package/dist/index.js

@@ -18,6 +18,13 @@ var AtlasHttpClient = class {
     }
     return headers;
   }
+  multipartHeaders() {
+    const headers = {};
+    if (this.token) {
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+    return headers;
+  }
   async request(method, path, body, params) {
     const url = new URL(`${this.baseUrl}${path}`);
     if (params) {
@@ -40,6 +47,22 @@ var AtlasHttpClient = class {
     }
     return await response.json();
   }
+  async multipartRequest(path, formData) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    const response = await this.fetchImpl(url.toString(), {
+      method: "POST",
+      headers: this.multipartHeaders(),
+      body: formData
+    });
+    if (!response.ok) {
+      const detail = await response.text();
+      throw new Error(`HTTP ${response.status}: ${detail}`);
+    }
+    if (response.status === 204) {
+      return void 0;
+    }
+    return await response.json();
+  }
   // Entities ------------------------------------------------------------------
   listEntities(limit = 100, offset = 0) {
     return this.request("GET", "/entities", null, { limit, offset });
@@ -50,17 +73,36 @@ var AtlasHttpClient = class {
   getEntityByAlias(alias) {
     return this.request("GET", `/entities/alias/${alias}`);
   }
-  createEntity(body) {
-    return this.request("POST", "/entities", body);
-  }
-  updateEntity(entityId, body) {
-    return this.request("PATCH", `/entities/${entityId}`, body);
+  createEntity(entityId, entityType, alias, subtype, components) {
+    const payload = {
+      entity_id: entityId,
+      entity_type: entityType,
+      alias,
+      subtype
+    };
+    if (components !== void 0) payload.components = components;
+    return this.request("POST", "/entities", payload);
+  }
+  updateEntity(entityId, components, options) {
+    if (components === void 0 && options?.subtype === void 0) {
+      throw new Error("AtlasHttpClient.updateEntity requires a components payload or subtype.");
+    }
+    const payload = {};
+    if (components !== void 0) payload.components = components;
+    if (options?.subtype !== void 0) payload.subtype = options.subtype;
+    return this.request("PATCH", `/entities/${entityId}`, payload);
   }
   deleteEntity(entityId) {
     return this.request("DELETE", `/entities/${entityId}`);
   }
-  updateEntityTelemetry(entityId, body) {
-    return this.request("PATCH", `/entities/${entityId}/telemetry`, body);
+  updateEntityTelemetry(entityId, options) {
+    const payload = {};
+    if (options.latitude !== void 0) payload.latitude = options.latitude;
+    if (options.longitude !== void 0) payload.longitude = options.longitude;
+    if (options.altitude_m !== void 0) payload.altitude_m = options.altitude_m;
+    if (options.speed_m_s !== void 0) payload.speed_m_s = options.speed_m_s;
+    if (options.heading_deg !== void 0) payload.heading_deg = options.heading_deg;
+    return this.request("PATCH", `/entities/${entityId}/telemetry`, payload);
   }
   // Tasks ---------------------------------------------------------------------
   listTasks(limit = 25, status) {
@@ -69,11 +111,28 @@ var AtlasHttpClient = class {
   getTask(taskId) {
     return this.request("GET", `/tasks/${taskId}`);
   }
-  createTask(body) {
-    return this.request("POST", "/tasks", body);
-  }
-  updateTask(taskId, body) {
-    return this.request("PATCH", `/tasks/${taskId}`, body);
+  createTask(taskId, components, options) {
+    const payload = {
+      task_id: taskId,
+      status: options?.status || "pending"
+    };
+    if (options?.entity_id !== void 0) payload.entity_id = options.entity_id;
+    if (components !== void 0) payload.components = components;
+    if (options?.extra !== void 0) payload.extra = options.extra;
+    return this.request("POST", "/tasks", payload);
+  }
+  updateTask(taskId, components, options) {
+    if (components === void 0 && options === void 0) {
+      throw new Error(
+        "AtlasHttpClient.updateTask requires a components payload or options."
+      );
+    }
+    const payload = {};
+    if (components !== void 0) payload.components = 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;
+    return this.request("PATCH", `/tasks/${taskId}`, payload);
   }
   deleteTask(taskId) {
     return this.request("DELETE", `/tasks/${taskId}`);
@@ -81,27 +140,56 @@ var AtlasHttpClient = class {
   getTasksByEntity(entityId, limit = 25, status) {
     return this.request("GET", `/entities/${entityId}/tasks`, null, { limit, status });
   }
-  startTask(taskId, body = {}) {
-    return this.request("POST", `/tasks/${taskId}/start`, body);
+  startTask(taskId) {
+    return this.request("POST", `/tasks/${taskId}/start`, {});
   }
-  completeTask(taskId, body = {}) {
-    return this.request("POST", `/tasks/${taskId}/complete`, body);
+  completeTask(taskId) {
+    return this.request("POST", `/tasks/${taskId}/complete`, {});
   }
-  failTask(taskId, body = {}) {
-    return this.request("POST", `/tasks/${taskId}/fail`, body);
+  failTask(taskId, errorMessage, errorDetails) {
+    const payload = {};
+    if (errorMessage !== void 0) payload.error_message = errorMessage;
+    if (errorDetails !== void 0) payload.error_details = errorDetails;
+    return this.request("POST", `/tasks/${taskId}/fail`, payload);
   }
   // Objects -------------------------------------------------------------------
-  listObjects(limit = 100, offset = 0, contentType) {
-    return this.request("GET", "/objects", null, { limit, offset, content_type: contentType });
+  listObjects(limit = 100, offset = 0, contentType, type) {
+    return this.request("GET", "/objects", null, { limit, offset, content_type: contentType, type });
   }
   getObject(objectId) {
     return this.request("GET", `/objects/${objectId}`);
   }
-  createObject(body) {
-    return this.request("POST", "/objects", body);
+  async createObject(file, objectId, usageHint, referencedBy) {
+    const formData = new FormData();
+    formData.append("object_id", objectId);
+    const filename = file.name ?? "upload.bin";
+    formData.append("file", file, filename);
+    if (usageHint) {
+      formData.append("usage_hint", usageHint);
+    }
+    const stored = await this.multipartRequest("/objects/upload", formData);
+    const storedObjectId = stored["object_id"];
+    if (referencedBy && storedObjectId !== void 0) {
+      for (const reference of referencedBy) {
+        await this.addObjectReference(storedObjectId, reference.entity_id, reference.task_id);
+      }
+    } else if (referencedBy && storedObjectId === void 0) {
+      throw new Error(
+        "AtlasHttpClient.createObject expected the upload response to include an object_id before attaching references."
+      );
+    }
+    return stored;
   }
-  updateObject(objectId, body) {
-    return this.request("PATCH", `/objects/${objectId}`, body);
+  updateObject(objectId, usageHints, referencedBy) {
+    if (usageHints === void 0 && referencedBy === void 0) {
+      throw new Error(
+        "AtlasHttpClient.updateObject requires usageHints or referencedBy to make an update."
+      );
+    }
+    const payload = {};
+    if (usageHints !== void 0) payload.usage_hints = usageHints;
+    if (referencedBy !== void 0) payload.referenced_by = referencedBy;
+    return this.request("PATCH", `/objects/${objectId}`, payload);
   }
   deleteObject(objectId) {
     return this.request("DELETE", `/objects/${objectId}`);
@@ -112,11 +200,17 @@ var AtlasHttpClient = class {
   getObjectsByTask(taskId, limit = 50) {
     return this.request("GET", `/tasks/${taskId}/objects`, null, { limit });
   }
-  addObjectReference(objectId, body) {
-    return this.request("POST", `/objects/${objectId}/references`, body);
-  }
-  removeObjectReference(objectId, body) {
-    return this.request("DELETE", `/objects/${objectId}/references`, body);
+  addObjectReference(objectId, entityId, taskId) {
+    const payload = {};
+    if (entityId !== void 0) payload.entity_id = entityId;
+    if (taskId !== void 0) payload.task_id = taskId;
+    return this.request("POST", `/objects/${objectId}/references`, payload);
+  }
+  removeObjectReference(objectId, entityId, taskId) {
+    const payload = {};
+    if (entityId !== void 0) payload.entity_id = entityId;
+    if (taskId !== void 0) payload.task_id = taskId;
+    return this.request("DELETE", `/objects/${objectId}/references`, payload);
   }
   findOrphanedObjects(limit = 100) {
     return this.request("GET", "/objects/orphaned", null, { limit });

package/package.json

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