fix(entities): correct issues found during live testing

- entity-copy: page through the source with the API's page param instead
  of skip (which the entity data API ignores), fixing an infinite loop
  that re-inserted records without end; cap --qty at 10000
- entity-data: drop --order/--order-by (the data query ignores order)
- entity-list: add working --order/--order-by built as the [field, dir]
  tuple the SDK expects, validated against orderable fields
- entity-create/entity-edit: remove --description; the entity API has no
  description field, so it was a silent no-op (also drops the stray
  payload_decoder: null it gated)
- fix invalid 'integer' type in help examples (valid type is 'int')
- regenerate man-page snapshot for the help text changes

Author: mateuscardosodeveloper

src/commands/entities/entity-copy.ts

@@ -53,16 +53,14 @@ async function entityCopy(options: IOptions) {
   const resources = new Resources({ token: config.profileToken, region: config.profileRegion });
   const pageSize = options.qty ?? DEFAULT_PAGE;
   let total = 0;
-  let page = 0;
+  let page = 1;
 
   // Loop until the source is exhausted (page returns fewer than pageSize records).
   while (true) {
-    const batch = await resources.entities
-      .getEntityData(fromId, { amount: pageSize, skip: page * pageSize })
-      .catch((error: unknown) => {
-        const message = error instanceof Error ? error.message : String(error);
-        return failWith(`Failed to read source entity ${fromId}: ${message}`, "read_failed", useJSON);
-      });
+    const batch = await resources.entities.getEntityData(fromId, { amount: pageSize, page }).catch((error: unknown) => {
+      const message = error instanceof Error ? error.message : String(error);
+      return failWith(`Failed to read source entity ${fromId}: ${message}`, "read_failed", useJSON);
+    });
 
     if (!batch || batch.length === 0) {
       break;

src/commands/entities/entity-create.test.ts

@@ -94,11 +94,10 @@ describe("entityCreate", () => {
     );
   });
 
-  test("interactive path uses prompts for description / tags / schema-paste", async () => {
+  test("interactive path uses prompts for tags / schema-paste", async () => {
     requireOrFailMock.mockResolvedValue("interactive-entity");
     resourcesInstance.entities.create.mockResolvedValue({ id: "id-2" });
     prompts.inject([
-      "An optional description",                                  // description
       "env:prod,team:platform",                                   // tags
       JSON.stringify({ email: { type: "string", required: true } }), // schema paste
     ]);

src/commands/entities/entity-create.ts

@@ -35,7 +35,7 @@ function parseTagsCSV(input: string): TagsObj[] {
 /**
  * @description Loads the entity definition from `--schema <file>` or
  * `--schema-json '<inline>'`. Accepts two shapes:
- *   1. A full envelope: `{ name, schema: {...}, tags?, description? }`
+ *   1. A full envelope: `{ name, schema: {...}, tags? }`
  *   2. A bare schema map: `{ field_name: {type: "string", ...}, ... }`
  *      — wrapped into `{ schema: <parsed> }` so the API receives the columns.
  *      Detected when none of the values look like an EntityCreateInfo field
@@ -60,7 +60,7 @@ function loadSchemaPayload(options: IOptions): EntityCreateInfo | undefined {
   // whole object is the schema. This matches `--add-field`'s bare-map shape
   // and avoids silently dropping schema columns when callers omit the
   // envelope.
-  const envelopeKeys = ["name", "schema", "tags", "description", "payload_decoder"] as const;
+  const envelopeKeys = ["name", "schema", "tags", "payload_decoder"] as const;
   const isEnvelope = envelopeKeys.some((key) => key in parsed);
   if (!isEnvelope) {
     return { schema: parsed } as unknown as EntityCreateInfo;
@@ -89,18 +89,15 @@ async function entityCreate(nameArg: string | undefined, options: IOptions) {
       failWith("Schema payload is missing required field: name.", "missing_name", Boolean(options.json));
     }
   } else {
-    // Interactive: prompt for name → description → tags → paste schema JSON.
+    // Interactive: prompt for name → tags → paste schema JSON.
     const name = await requireOrFail(nameArg, "name", {
       silent: options.silent,
       json: options.json,
       promptMessage: "Entity name:",
     });
-    let description: string | undefined;
     let tags: TagsObj[] | undefined;
     let schema: EntityCreateInfo["schema"] | undefined;
     if (!options.silent) {
-      const descAnswer = await prompts({ type: "text", name: "description", message: "Description (optional):" });
-      description = descAnswer.description ? String(descAnswer.description) : undefined;
       const tagAnswer = await prompts({ type: "text", name: "tags", message: "Tags as key:value,key2:value2 (optional):" });
       tags = tagAnswer.tags ? parseTagsCSV(String(tagAnswer.tags)) : undefined;
       const schemaAnswer = await prompts({
@@ -117,12 +114,7 @@ async function entityCreate(nameArg: string | undefined, options: IOptions) {
         }
       }
     }
-    payload = { name, ...(description ? { payload_decoder: null } : {}), ...(tags ? { tags } : {}), ...(schema ? { schema } : {}) };
-    // `description` lives on EntityInfo but not EntityCreateInfo per SDK types;
-    // keep it on the payload anyway since the API accepts it.
-    if (description) {
-      (payload as Record<string, unknown>).description = description;
-    }
+    payload = { name, ...(tags ? { tags } : {}), ...(schema ? { schema } : {}) };
   }
 
   const created = await resources.entities.create(payload).catch((error: unknown) => {

src/commands/entities/entity-data.test.ts

@@ -60,22 +60,19 @@ describe("entityData", () => {
     expect(resourcesInstance.entities.getEntityData).toHaveBeenCalledWith("ent1", {});
   });
 
-  test("read mode applies --qty / --skip / --order-by / --order / -q filters", async () => {
+  test("read mode applies --qty / --skip / -q filters", async () => {
     resourcesInstance.entities.getEntityData.mockResolvedValue([]);
 
     const { entityData } = await import("./entity-data.js");
     await entityData("ent1", {
       qty: 50,
       skip: 10,
-      orderBy: "created_at",
-      order: "desc",
       query: ["status=active", "tier=gold"],
     } as never);
 
     expect(resourcesInstance.entities.getEntityData).toHaveBeenCalledWith("ent1", {
       amount: 50,
       skip: 10,
-      order: "created_at,desc",
       filter: { status: "active", tier: "gold" },
     });
   });

src/commands/entities/entity-data.ts

@@ -9,8 +9,6 @@ interface IOptions {
   environment?: string;
   qty?: number;
   skip?: number;
-  orderBy?: string;
-  order?: "asc" | "desc";
   query?: string[];
   json?: boolean;
   stringify?: boolean;
@@ -134,9 +132,6 @@ async function entityData(idArg: string | undefined, options: IOptions) {
       if (options.skip !== undefined) {
         queryParams.skip = options.skip;
       }
-      if (options.orderBy) {
-        queryParams.order = `${options.orderBy},${options.order ?? "asc"}`;
-      }
       const filter = parseQueryFilters(options.query);
       if (filter) {
         queryParams.filter = filter;
@@ -175,12 +170,10 @@ async function entityData(idArg: string | undefined, options: IOptions) {
 
     case "edit": {
       const payload = parseJSON<unknown>(options.edit as string, "--edit", useJSON);
-      const result = await resources.entities
-        .editEntityData(id, payload as never)
-        .catch((error: unknown) => {
-          const message = error instanceof Error ? error.message : String(error);
-          return failWith(`Failed to edit entity ${id} data: ${message}`, "edit_failed", useJSON);
-        });
+      const result = await resources.entities.editEntityData(id, payload as never).catch((error: unknown) => {
+        const message = error instanceof Error ? error.message : String(error);
+        return failWith(`Failed to edit entity ${id} data: ${message}`, "edit_failed", useJSON);
+      });
       if (useJSON) {
         process.stdout.write(`${JSON.stringify({ id, edited: true, result })}\n`);
         return;
@@ -196,7 +189,10 @@ async function entityData(idArg: string | undefined, options: IOptions) {
       if (raw.trim().startsWith("[")) {
         ids = parseJSON<string[]>(raw, "--delete", useJSON);
       } else {
-        ids = raw.split(",").map((s) => s.trim()).filter(Boolean);
+        ids = raw
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean);
       }
       if (ids.length === 0) {
         failWith("--delete requires at least one record id.", "empty_ids", useJSON);
@@ -206,12 +202,10 @@ async function entityData(idArg: string | undefined, options: IOptions) {
         infoMSG("Cancelled. No changes made.");
         return;
       }
-      const result = await resources.entities
-        .deleteEntityData(id, { ids })
-        .catch((error: unknown) => {
-          const message = error instanceof Error ? error.message : String(error);
-          return failWith(`Failed to delete entity ${id} records: ${message}`, "delete_failed", useJSON);
-        });
+      const result = await resources.entities.deleteEntityData(id, { ids }).catch((error: unknown) => {
+        const message = error instanceof Error ? error.message : String(error);
+        return failWith(`Failed to delete entity ${id} records: ${message}`, "delete_failed", useJSON);
+      });
       if (useJSON) {
         process.stdout.write(`${JSON.stringify({ id, deleted: ids.length, result })}\n`);
         return;
@@ -243,12 +237,10 @@ async function entityData(idArg: string | undefined, options: IOptions) {
       // data (verified live against the TagoIO API). Counting via the data
       // endpoint keeps `--count` consistent with what `entity-data` itself
       // returns. The page-size cap (10000) matches `entity-copy`'s default.
-      const data = await resources.entities
-        .getEntityData(id, { amount: 10000 })
-        .catch((error: unknown) => {
-          const message = error instanceof Error ? error.message : String(error);
-          return failWith(`Failed to count entity ${id}: ${message}`, "count_failed", useJSON);
-        });
+      const data = await resources.entities.getEntityData(id, { amount: 10000 }).catch((error: unknown) => {
+        const message = error instanceof Error ? error.message : String(error);
+        return failWith(`Failed to count entity ${id}: ${message}`, "count_failed", useJSON);
+      });
       const count = Array.isArray(data) ? data.length : 0;
       if (useJSON || options.stringify) {
         writeJSON({ id, count }, options);

src/commands/entities/entity-edit.test.ts

@@ -59,15 +59,14 @@ describe("entityEdit", () => {
     expect(resourcesInstance.entities.edit).toHaveBeenCalledWith("ent1", { name: "renamed" });
   });
 
-  test("merges --name and --description into a single patch", async () => {
+  test("builds the patch from --name", async () => {
     resourcesInstance.entities.edit.mockResolvedValue({ message: "ok" });
 
     const { entityEdit } = await import("./entity-edit.js");
-    await entityEdit("ent1", { name: "renamed", description: "new desc" } as never);
+    await entityEdit("ent1", { name: "renamed" } as never);
 
     expect(resourcesInstance.entities.edit).toHaveBeenCalledWith("ent1", {
       name: "renamed",
-      description: "new desc",
     });
   });
 
@@ -87,7 +86,7 @@ describe("entityEdit", () => {
     await expect(entityEdit(undefined, { silent: true, name: "x" } as never)).rejects.toThrow(/Missing required input: id/);
   });
 
-  test("no-op edit (no --name or --description) errors actionably", async () => {
+  test("no-op edit (no --name) errors actionably", async () => {
     const { entityEdit } = await import("./entity-edit.js");
     await expect(entityEdit("ent1", {} as never)).rejects.toThrow(/Nothing to update/);
   });

src/commands/entities/entity-edit.ts

@@ -7,7 +7,6 @@ import { pickEntityIDFromTagoIO } from "../../prompt/pick-entity-id-from-tagoio.
 interface IOptions {
   environment?: string;
   name?: string;
-  description?: string;
   silent?: boolean;
   json?: boolean;
 }
@@ -36,19 +35,16 @@ async function entityEdit(idArg: string | undefined, options: IOptions) {
   }
 
   // Build the patch from only the flags the user set. Empty patch = no-op.
-  const patch: Partial<EntityCreateInfo> & { description?: string } = {};
+  const patch: Partial<EntityCreateInfo> = {};
   if (options.name !== undefined) {
     patch.name = options.name;
   }
-  if (options.description !== undefined) {
-    patch.description = options.description;
-  }
 
   if (Object.keys(patch).length === 0) {
-    failWith("Nothing to update — pass at least one of --name or --description.", "noop_edit", Boolean(options.json));
+    failWith("Nothing to update — pass --name.", "noop_edit", Boolean(options.json));
   }
 
-  await resources.entities.edit(id, patch as Partial<EntityCreateInfo>).catch((error: unknown) => {
+  await resources.entities.edit(id, patch).catch((error: unknown) => {
     const message = error instanceof Error ? error.message : String(error);
     failWith(`Failed to edit entity ${id}: ${message}`, "edit_failed", Boolean(options.json));
   });

src/commands/entities/entity-info.test.ts

@@ -106,7 +106,6 @@ describe("entityInfo", () => {
     resourcesInstance.entities.info.mockResolvedValue({
       id: "ent1",
       name: "Entity One",
-      description: "desc",
       schema: { email: { type: "string" } },
       index: { email_idx: { fields: ["email"] } },
       created_at: null,

src/commands/entities/entity-info.ts

@@ -61,7 +61,6 @@ async function entityInfo(idArg: string | undefined, options: IOptions) {
   const meta: Record<string, unknown> = {
     id: info.id,
     name: info.name,
-    description: (info as { description?: string }).description ?? "",
     created_at: info.created_at,
     updated_at: info.updated_at,
   };

src/commands/entities/entity-list.test.ts

@@ -97,6 +97,34 @@ describe("entityList", () => {
     );
   });
 
+  test("--order-by + --order builds the [field, direction] tuple the SDK expects", async () => {
+    getEnvironmentConfigMock.mockReturnValue(makeEnvironmentConfig());
+    resourcesInstance.entities.list.mockResolvedValue([]);
+
+    const { entityList } = await import("./entity-list.js");
+    await entityList({ tagkey: [], tagvalue: [], orderBy: "created_at", order: "desc" } as never);
+
+    expect(resourcesInstance.entities.list).toHaveBeenCalledWith(expect.objectContaining({ orderBy: ["created_at", "desc"] }));
+  });
+
+  test("--order-by defaults to asc when --order is omitted", async () => {
+    getEnvironmentConfigMock.mockReturnValue(makeEnvironmentConfig());
+    resourcesInstance.entities.list.mockResolvedValue([]);
+
+    const { entityList } = await import("./entity-list.js");
+    await entityList({ tagkey: [], tagvalue: [], orderBy: "name" } as never);
+
+    expect(resourcesInstance.entities.list).toHaveBeenCalledWith(expect.objectContaining({ orderBy: ["name", "asc"] }));
+  });
+
+  test("rejects an --order-by field that is not orderable", async () => {
+    getEnvironmentConfigMock.mockReturnValue(makeEnvironmentConfig());
+
+    const { entityList } = await import("./entity-list.js");
+    await expect(entityList({ tagkey: [], tagvalue: [], orderBy: "email" } as never)).rejects.toThrow(/Cannot order by "email"/);
+    expect(resourcesInstance.entities.list).not.toHaveBeenCalled();
+  });
+
   test("routes a SDK failure through errorHandler with an actionable message", async () => {
     getEnvironmentConfigMock.mockReturnValue(makeEnvironmentConfig());
     resourcesInstance.entities.list.mockRejectedValue(new Error("Authorization Denied"));