@atlasnpm/atlas-api-helper 0.2.4

package/README.md

@@ -0,0 +1,150 @@
+# 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
+npm install @atlasnpm/atlas-api-helper
+```
+
+## Usage
+
+```ts
+import { AtlasHttpClient } 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);
+
+await client.createTask({
+  task_id: "survey-1",
+  status: "pending",
+  components: { parameters: { latitude: 40.7, longitude: -74.0 } },
+});
+
+// New API methods (version 0.2.1)
+const entity = await client.getEntityByAlias("drone-1");
+await client.updateEntityTelemetry("drone-1", {
+  latitude: 40.7128,
+  longitude: -74.0060,
+  altitude_m: 100,
+  speed_m_s: 15,
+  heading_deg: 90,
+});
+
+// Task lifecycle management
+await client.startTask("task-1", { started_by: "operator-1" });
+await client.completeTask("task-1", { result: { data: "success" } });
+
+// Query capabilities
+const changes = await client.getChangedSince("2023-01-01T00:00:00Z", 10);
+const fullData = await client.getFullDataset({
+  entityLimit: 50,
+  taskLimit: 25,
+  objectLimit: 100,
+});
+```
+
+## API Surface
+
+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
+- `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
+- `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)
+
+### 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
+- `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
+- `findOrphanedObjects(limit?)` - Find orphaned objects
+- `getObjectReferences(objectId)` - Get object references
+- `validateObjectReferences(objectId)` - Validate object references
+- `cleanupObjectReferences(objectId)` - Cleanup object references
+
+### Queries
+- `getChangedSince(since, limitPerType?)` - Get changes since timestamp (NEW in 0.2.1)
+- `getFullDataset(options?)` - Get full dataset with limits (NEW in 0.2.1)
+
+## Type System
+
+The package now includes comprehensive TypeScript types for all entities and operations:
+
+```ts
+import {
+  Entity,
+  Task,
+  Telemetry,
+  TaskStart,
+  TaskComplete,
+  TaskFail,
+  // ... and many more
+} from "@atlasnpm/atlas-api-helper";
+```
+
+## Custom Fetch / Testing
+
+Pass a custom `fetchImpl` when constructing the client to inject your own transport (e.g., `node-fetch`, `cross-fetch`, or a mocked implementation for unit tests):
+
+```ts
+const client = new AtlasHttpClient({
+  baseUrl: "https://atlas.example.com",
+  fetchImpl: myCustomFetch,
+});
+```
+
+See `tests/httpClient.test.ts` for examples using mocked fetch functions.
+
+## Building & Testing
+
+```bash
+npm install
+npm run build
+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.

package/dist/index.cjs

@@ -0,0 +1,177 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AtlasHttpClient: () => AtlasHttpClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/httpClient.ts
+var AtlasHttpClient = class {
+  baseUrl;
+  token;
+  fetchImpl;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.token = options.token;
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    if (!this.fetchImpl) {
+      throw new Error("fetch is not available; provide fetchImpl");
+    }
+  }
+  headers() {
+    const headers = { "Content-Type": "application/json" };
+    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) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value === void 0 || value === null) continue;
+        url.searchParams.set(key, String(value));
+      }
+    }
+    const response = await this.fetchImpl(url.toString(), {
+      method,
+      headers: this.headers(),
+      body: body ? JSON.stringify(body) : void 0
+    });
+    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 });
+  }
+  getEntity(entityId) {
+    return this.request("GET", `/entities/${entityId}`);
+  }
+  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);
+  }
+  deleteEntity(entityId) {
+    return this.request("DELETE", `/entities/${entityId}`);
+  }
+  updateEntityTelemetry(entityId, body) {
+    return this.request("PATCH", `/entities/${entityId}/telemetry`, body);
+  }
+  // Tasks ---------------------------------------------------------------------
+  listTasks(limit = 25, status) {
+    return this.request("GET", "/tasks", null, { limit, status });
+  }
+  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);
+  }
+  deleteTask(taskId) {
+    return this.request("DELETE", `/tasks/${taskId}`);
+  }
+  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);
+  }
+  completeTask(taskId, body = {}) {
+    return this.request("POST", `/tasks/${taskId}/complete`, body);
+  }
+  failTask(taskId, body = {}) {
+    return this.request("POST", `/tasks/${taskId}/fail`, body);
+  }
+  // Objects -------------------------------------------------------------------
+  listObjects(limit = 100, offset = 0, contentType) {
+    return this.request("GET", "/objects", null, { limit, offset, content_type: contentType });
+  }
+  getObject(objectId) {
+    return this.request("GET", `/objects/${objectId}`);
+  }
+  createObject(body) {
+    return this.request("POST", "/objects", body);
+  }
+  updateObject(objectId, body) {
+    return this.request("PATCH", `/objects/${objectId}`, body);
+  }
+  deleteObject(objectId) {
+    return this.request("DELETE", `/objects/${objectId}`);
+  }
+  getObjectsByEntity(entityId, limit = 50) {
+    return this.request("GET", `/entities/${entityId}/objects`, null, { limit });
+  }
+  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);
+  }
+  findOrphanedObjects(limit = 100) {
+    return this.request("GET", "/objects/orphaned", null, { limit });
+  }
+  getObjectReferences(objectId) {
+    return this.request("GET", `/objects/${objectId}/references/info`);
+  }
+  validateObjectReferences(objectId) {
+    return this.request("GET", `/objects/${objectId}/references/validate`);
+  }
+  cleanupObjectReferences(objectId) {
+    return this.request("POST", `/objects/${objectId}/references/cleanup`, {});
+  }
+  // Queries -------------------------------------------------------------------
+  getChangedSince(since, limitPerType) {
+    return this.request("GET", "/queries/changed-since", null, {
+      since,
+      limit_per_type: limitPerType
+    });
+  }
+  getFullDataset(options) {
+    return this.request("GET", "/queries/full", null, {
+      entity_limit: options?.entityLimit,
+      task_limit: options?.taskLimit,
+      object_limit: options?.objectLimit
+    });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AtlasHttpClient
+});

package/dist/index.d.cts

@@ -0,0 +1,208 @@
+interface FetchImplementation {
+    (input: RequestInfo, init?: RequestInit): Promise<Response>;
+}
+interface ClientOptions {
+    baseUrl: string;
+    token?: string;
+    fetchImpl?: FetchImplementation;
+}
+type JsonRecord = Record<string, unknown>;
+declare class AtlasHttpClient {
+    private readonly baseUrl;
+    private readonly token?;
+    private readonly fetchImpl;
+    constructor(options: ClientOptions);
+    private headers;
+    private request;
+    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>;
+    deleteEntity(entityId: string): Promise<unknown>;
+    updateEntityTelemetry(entityId: string, body: {
+        latitude?: number;
+        longitude?: number;
+        altitude_m?: number;
+        speed_m_s?: number;
+        heading_deg?: number;
+    }): 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;
+    }): Promise<unknown>;
+    failTask(taskId: string, body?: {
+        error_message?: string;
+        error_details?: JsonRecord;
+    }): Promise<unknown>;
+    listObjects(limit?: number, offset?: number, contentType?: 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: {
+        entity_id?: string;
+        task_id?: string;
+    }): Promise<unknown>;
+    removeObjectReference(objectId: string, body: {
+        entity_id?: string;
+        task_id?: string;
+    }): Promise<unknown>;
+    findOrphanedObjects(limit?: number): Promise<unknown>;
+    getObjectReferences(objectId: string): Promise<unknown>;
+    validateObjectReferences(objectId: string): Promise<unknown>;
+    cleanupObjectReferences(objectId: string): Promise<unknown>;
+    getChangedSince(since: string, limitPerType?: number): Promise<unknown>;
+    getFullDataset(options?: {
+        entityLimit?: number;
+        taskLimit?: number;
+        objectLimit?: number;
+    }): Promise<unknown>;
+}
+
+interface Entity {
+    entity_id: string;
+    json: {
+        type: "asset" | "track" | "geofeature" | string;
+        alias?: string;
+        components?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+    created_at?: string;
+    updated_at?: string;
+}
+interface Task {
+    task_id: string;
+    json: {
+        status: string;
+        components?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+    created_at?: string;
+    updated_at?: string;
+}
+interface StoredObject {
+    object_id: string;
+    json: Record<string, unknown>;
+    created_at?: string;
+    updated_at?: string;
+}
+type Asset = Entity;
+type Track = Entity;
+type GeoFeature = Entity;
+type Command = Task;
+interface Model {
+    id: string | number;
+    name?: string;
+    asset_type?: string;
+    capabilities?: Record<string, unknown>;
+    heartbeat_interval?: number;
+    location_update_frequency?: number;
+    settings_schema?: Record<string, unknown>;
+    default_settings?: Record<string, unknown>;
+    created_at?: string;
+    updated_at?: string;
+    [key: string]: unknown;
+}
+interface CommandDefinition {
+    id: number;
+    name?: string;
+    parameters_schema?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface EventType {
+    id: number;
+    name?: string;
+    [key: string]: unknown;
+}
+interface Event {
+    id: number;
+    asset_id?: string;
+    event_type_id?: number;
+    timestamp?: string;
+    payload?: Record<string, unknown>;
+    entity?: string;
+    [key: string]: unknown;
+}
+interface Sensor {
+    id: number;
+    asset_id?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+interface TrackTelemetry {
+    track_id: string;
+    timestamp: string;
+    latitude?: number | string;
+    longitude?: number | string;
+    altitude?: number;
+    sensor_id?: number;
+    [key: string]: unknown;
+}
+interface Telemetry {
+    latitude?: number;
+    longitude?: number;
+    altitude_m?: number;
+    speed_m_s?: number;
+    heading_deg?: number;
+    [key: string]: unknown;
+}
+interface TaskStatusUpdate {
+    status?: string;
+    components?: Record<string, unknown>;
+    extra?: Record<string, unknown>;
+}
+interface TaskStart {
+    started_by?: string;
+}
+interface TaskComplete {
+    result?: Record<string, unknown>;
+}
+interface TaskFail {
+    error_message?: string;
+    error_details?: Record<string, unknown>;
+}
+interface ObjectReference {
+    entity_id?: string;
+    task_id?: string;
+}
+interface ObjectCreate {
+    object_id: string;
+    path?: string;
+    bucket?: string;
+    size_bytes?: number;
+    content_type?: string;
+    usage_hints?: string[];
+    referenced_by?: ObjectReference[];
+    extra?: Record<string, unknown>;
+}
+interface ObjectUpdate {
+    path?: string;
+    bucket?: string;
+    size_bytes?: number;
+    content_type?: string;
+    usage_hints?: string[];
+    referenced_by?: ObjectReference[];
+    extra?: Record<string, unknown>;
+}
+interface ChangedSinceOptions {
+    since: string;
+    limit_per_type?: number;
+}
+interface FullDatasetOptions {
+    entity_limit?: number;
+    task_limit?: number;
+    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 };

package/dist/index.d.ts

@@ -0,0 +1,208 @@
+interface FetchImplementation {
+    (input: RequestInfo, init?: RequestInit): Promise<Response>;
+}
+interface ClientOptions {
+    baseUrl: string;
+    token?: string;
+    fetchImpl?: FetchImplementation;
+}
+type JsonRecord = Record<string, unknown>;
+declare class AtlasHttpClient {
+    private readonly baseUrl;
+    private readonly token?;
+    private readonly fetchImpl;
+    constructor(options: ClientOptions);
+    private headers;
+    private request;
+    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>;
+    deleteEntity(entityId: string): Promise<unknown>;
+    updateEntityTelemetry(entityId: string, body: {
+        latitude?: number;
+        longitude?: number;
+        altitude_m?: number;
+        speed_m_s?: number;
+        heading_deg?: number;
+    }): 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;
+    }): Promise<unknown>;
+    failTask(taskId: string, body?: {
+        error_message?: string;
+        error_details?: JsonRecord;
+    }): Promise<unknown>;
+    listObjects(limit?: number, offset?: number, contentType?: 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: {
+        entity_id?: string;
+        task_id?: string;
+    }): Promise<unknown>;
+    removeObjectReference(objectId: string, body: {
+        entity_id?: string;
+        task_id?: string;
+    }): Promise<unknown>;
+    findOrphanedObjects(limit?: number): Promise<unknown>;
+    getObjectReferences(objectId: string): Promise<unknown>;
+    validateObjectReferences(objectId: string): Promise<unknown>;
+    cleanupObjectReferences(objectId: string): Promise<unknown>;
+    getChangedSince(since: string, limitPerType?: number): Promise<unknown>;
+    getFullDataset(options?: {
+        entityLimit?: number;
+        taskLimit?: number;
+        objectLimit?: number;
+    }): Promise<unknown>;
+}
+
+interface Entity {
+    entity_id: string;
+    json: {
+        type: "asset" | "track" | "geofeature" | string;
+        alias?: string;
+        components?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+    created_at?: string;
+    updated_at?: string;
+}
+interface Task {
+    task_id: string;
+    json: {
+        status: string;
+        components?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+    created_at?: string;
+    updated_at?: string;
+}
+interface StoredObject {
+    object_id: string;
+    json: Record<string, unknown>;
+    created_at?: string;
+    updated_at?: string;
+}
+type Asset = Entity;
+type Track = Entity;
+type GeoFeature = Entity;
+type Command = Task;
+interface Model {
+    id: string | number;
+    name?: string;
+    asset_type?: string;
+    capabilities?: Record<string, unknown>;
+    heartbeat_interval?: number;
+    location_update_frequency?: number;
+    settings_schema?: Record<string, unknown>;
+    default_settings?: Record<string, unknown>;
+    created_at?: string;
+    updated_at?: string;
+    [key: string]: unknown;
+}
+interface CommandDefinition {
+    id: number;
+    name?: string;
+    parameters_schema?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface EventType {
+    id: number;
+    name?: string;
+    [key: string]: unknown;
+}
+interface Event {
+    id: number;
+    asset_id?: string;
+    event_type_id?: number;
+    timestamp?: string;
+    payload?: Record<string, unknown>;
+    entity?: string;
+    [key: string]: unknown;
+}
+interface Sensor {
+    id: number;
+    asset_id?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+interface TrackTelemetry {
+    track_id: string;
+    timestamp: string;
+    latitude?: number | string;
+    longitude?: number | string;
+    altitude?: number;
+    sensor_id?: number;
+    [key: string]: unknown;
+}
+interface Telemetry {
+    latitude?: number;
+    longitude?: number;
+    altitude_m?: number;
+    speed_m_s?: number;
+    heading_deg?: number;
+    [key: string]: unknown;
+}
+interface TaskStatusUpdate {
+    status?: string;
+    components?: Record<string, unknown>;
+    extra?: Record<string, unknown>;
+}
+interface TaskStart {
+    started_by?: string;
+}
+interface TaskComplete {
+    result?: Record<string, unknown>;
+}
+interface TaskFail {
+    error_message?: string;
+    error_details?: Record<string, unknown>;
+}
+interface ObjectReference {
+    entity_id?: string;
+    task_id?: string;
+}
+interface ObjectCreate {
+    object_id: string;
+    path?: string;
+    bucket?: string;
+    size_bytes?: number;
+    content_type?: string;
+    usage_hints?: string[];
+    referenced_by?: ObjectReference[];
+    extra?: Record<string, unknown>;
+}
+interface ObjectUpdate {
+    path?: string;
+    bucket?: string;
+    size_bytes?: number;
+    content_type?: string;
+    usage_hints?: string[];
+    referenced_by?: ObjectReference[];
+    extra?: Record<string, unknown>;
+}
+interface ChangedSinceOptions {
+    since: string;
+    limit_per_type?: number;
+}
+interface FullDatasetOptions {
+    entity_limit?: number;
+    task_limit?: number;
+    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 };

package/dist/index.js

@@ -0,0 +1,150 @@
+// src/httpClient.ts
+var AtlasHttpClient = class {
+  baseUrl;
+  token;
+  fetchImpl;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.token = options.token;
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    if (!this.fetchImpl) {
+      throw new Error("fetch is not available; provide fetchImpl");
+    }
+  }
+  headers() {
+    const headers = { "Content-Type": "application/json" };
+    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) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value === void 0 || value === null) continue;
+        url.searchParams.set(key, String(value));
+      }
+    }
+    const response = await this.fetchImpl(url.toString(), {
+      method,
+      headers: this.headers(),
+      body: body ? JSON.stringify(body) : void 0
+    });
+    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 });
+  }
+  getEntity(entityId) {
+    return this.request("GET", `/entities/${entityId}`);
+  }
+  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);
+  }
+  deleteEntity(entityId) {
+    return this.request("DELETE", `/entities/${entityId}`);
+  }
+  updateEntityTelemetry(entityId, body) {
+    return this.request("PATCH", `/entities/${entityId}/telemetry`, body);
+  }
+  // Tasks ---------------------------------------------------------------------
+  listTasks(limit = 25, status) {
+    return this.request("GET", "/tasks", null, { limit, status });
+  }
+  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);
+  }
+  deleteTask(taskId) {
+    return this.request("DELETE", `/tasks/${taskId}`);
+  }
+  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);
+  }
+  completeTask(taskId, body = {}) {
+    return this.request("POST", `/tasks/${taskId}/complete`, body);
+  }
+  failTask(taskId, body = {}) {
+    return this.request("POST", `/tasks/${taskId}/fail`, body);
+  }
+  // Objects -------------------------------------------------------------------
+  listObjects(limit = 100, offset = 0, contentType) {
+    return this.request("GET", "/objects", null, { limit, offset, content_type: contentType });
+  }
+  getObject(objectId) {
+    return this.request("GET", `/objects/${objectId}`);
+  }
+  createObject(body) {
+    return this.request("POST", "/objects", body);
+  }
+  updateObject(objectId, body) {
+    return this.request("PATCH", `/objects/${objectId}`, body);
+  }
+  deleteObject(objectId) {
+    return this.request("DELETE", `/objects/${objectId}`);
+  }
+  getObjectsByEntity(entityId, limit = 50) {
+    return this.request("GET", `/entities/${entityId}/objects`, null, { limit });
+  }
+  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);
+  }
+  findOrphanedObjects(limit = 100) {
+    return this.request("GET", "/objects/orphaned", null, { limit });
+  }
+  getObjectReferences(objectId) {
+    return this.request("GET", `/objects/${objectId}/references/info`);
+  }
+  validateObjectReferences(objectId) {
+    return this.request("GET", `/objects/${objectId}/references/validate`);
+  }
+  cleanupObjectReferences(objectId) {
+    return this.request("POST", `/objects/${objectId}/references/cleanup`, {});
+  }
+  // Queries -------------------------------------------------------------------
+  getChangedSince(since, limitPerType) {
+    return this.request("GET", "/queries/changed-since", null, {
+      since,
+      limit_per_type: limitPerType
+    });
+  }
+  getFullDataset(options) {
+    return this.request("GET", "/queries/full", null, {
+      entity_limit: options?.entityLimit,
+      task_limit: options?.taskLimit,
+      object_limit: options?.objectLimit
+    });
+  }
+};
+export {
+  AtlasHttpClient
+};

package/index.d.ts

@@ -0,0 +1 @@
+export * from "./dist/index";

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@atlasnpm/atlas-api-helper",
+  "version": "0.2.4",
+  "type": "module",
+  "description": "HTTP client for the Atlas Command REST API.",
+  "license": "MIT",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "index.d.ts"
+  ],
+  "scripts": {
+    "build": "npx tsup",
+    "test": "vitest run",
+    "prepare": "node ./scripts/prepare.mjs"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.4.5",
+    "vitest": "^1.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}