@sinoia/hubdoc-tools 1.5.1 → 1.6.0

package/cli.js

@@ -13297,9 +13297,9 @@ var require_groupBy = __commonJS({
         } else {
           duration = elementOrOptions.duration, element = elementOrOptions.element, connector = elementOrOptions.connector;
         }
-        var groups = /* @__PURE__ */ new Map();
+        var groups2 = /* @__PURE__ */ new Map();
         var notify = function(cb) {
-          groups.forEach(cb);
+          groups2.forEach(cb);
           cb(subscriber);
         };
         var handleError = function(err) {
@@ -13312,9 +13312,9 @@ var require_groupBy = __commonJS({
         var groupBySourceSubscriber = new OperatorSubscriber_1.OperatorSubscriber(subscriber, function(value2) {
           try {
             var key_1 = keySelector(value2);
-            var group_1 = groups.get(key_1);
+            var group_1 = groups2.get(key_1);
             if (!group_1) {
-              groups.set(key_1, group_1 = connector ? connector() : new Subject_1.Subject());
+              groups2.set(key_1, group_1 = connector ? connector() : new Subject_1.Subject());
               var grouped = createGroupedObservable(key_1, group_1);
               subscriber.next(grouped);
               if (duration) {
@@ -13322,7 +13322,7 @@ var require_groupBy = __commonJS({
                   group_1.complete();
                   durationSubscriber_1 === null || durationSubscriber_1 === void 0 ? void 0 : durationSubscriber_1.unsubscribe();
                 }, void 0, void 0, function() {
-                  return groups.delete(key_1);
+                  return groups2.delete(key_1);
                 });
                 groupBySourceSubscriber.add(innerFrom_1.innerFrom(duration(grouped)).subscribe(durationSubscriber_1));
               }
@@ -13336,7 +13336,7 @@ var require_groupBy = __commonJS({
             return consumer.complete();
           });
         }, handleError, function() {
-          return groups.clear();
+          return groups2.clear();
         }, function() {
           teardownAttempted = true;
           return activeGroups === 0;
@@ -71642,8 +71642,8 @@ function estimateDataURLDecodedBytes(url2) {
         pad++;
       }
     }
-    const groups = Math.floor(effectiveLen / 4);
-    const bytes = groups * 3 - (pad || 0);
+    const groups2 = Math.floor(effectiveLen / 4);
+    const bytes = groups2 * 3 - (pad || 0);
     return bytes > 0 ? bytes : 0;
   }
   return Buffer.byteLength(body, "utf8");
@@ -75269,6 +75269,12 @@ var GroupsApi = class extends BaseAPI {
     return GroupsApiFp(this.configuration).apiV1GroupsPost(contentType, groupMutation, options).then((request) => request(this.axios, this.basePath));
   }
 };
+var ApiV1GroupsIdPatchContentTypeEnum = {
+  ApplicationJson: "application/json"
+};
+var ApiV1GroupsPostContentTypeEnum = {
+  ApplicationJson: "application/json"
+};
 
 // packages/api-client/src/api/permissions-api.ts
 var PermissionsApiAxiosParamCreator = function(configuration) {
@@ -77133,20 +77139,20 @@ var PermissionManager = class {
     console.log(import_chalk5.default.gray("\u{1F4E5} Pre-loading users and groups cache..."));
     try {
       const usersResponse = await this.usersApi.apiV1UsersGet(void 0, void 0, 100);
-      const users = usersResponse.data;
-      users.forEach((user) => {
+      const users2 = usersResponse.data;
+      users2.forEach((user) => {
         if (user.email_address) {
           this.userCache.set(user.email_address.toLowerCase(), user);
         }
       });
       const groupsResponse = await this.groupsApi.apiV1GroupsGet(void 0, void 0, 100);
-      const groups = groupsResponse.data;
-      groups.forEach((group) => {
+      const groups2 = groupsResponse.data;
+      groups2.forEach((group) => {
         if (group.name) {
           this.groupCache.set(group.name.toLowerCase(), group);
         }
       });
-      console.log(import_chalk5.default.gray(`\u{1F4E6} Cached ${users.length} users and ${groups.length} groups`));
+      console.log(import_chalk5.default.gray(`\u{1F4E6} Cached ${users2.length} users and ${groups2.length} groups`));
     } catch (error) {
       console.warn(import_chalk5.default.yellow(`\u26A0\uFE0F  Warning: Failed to preload cache: ${error.message}`));
     }
@@ -77168,9 +77174,9 @@ var PermissionManager = class {
         1,
         { "q[email_address_eq]": normalizedEmail }
       );
-      const users = response.data;
-      if (users.length > 0) {
-        const user = users[0];
+      const users2 = response.data;
+      if (users2.length > 0) {
+        const user = users2[0];
         this.userCache.set(normalizedEmail, user);
         return user.id;
       }
@@ -77199,9 +77205,9 @@ var PermissionManager = class {
         1,
         { "q[name_eq]": trimmedName }
       );
-      const groups = response.data;
-      if (groups.length > 0) {
-        const group = groups[0];
+      const groups2 = response.data;
+      if (groups2.length > 0) {
+        const group = groups2[0];
         this.groupCache.set(normalizedName, group);
         return group.id;
       }
@@ -77215,12 +77221,12 @@ var PermissionManager = class {
   /**
    * Résout les permissions (emails et noms de groupes) vers des IDs
    */
-  async resolvePermissions(permissions) {
+  async resolvePermissions(permissions2) {
     const userIds = [];
     const groupIds = [];
     const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-    if (permissions.users && permissions.users.length > 0) {
-      for (const emailOrId of permissions.users) {
+    if (permissions2.users && permissions2.users.length > 0) {
+      for (const emailOrId of permissions2.users) {
         if (uuidRegex.test(emailOrId)) {
           userIds.push(emailOrId);
         } else {
@@ -77231,8 +77237,8 @@ var PermissionManager = class {
         }
       }
     }
-    if (permissions.groups && permissions.groups.length > 0) {
-      for (const nameOrId of permissions.groups) {
+    if (permissions2.groups && permissions2.groups.length > 0) {
+      for (const nameOrId of permissions2.groups) {
         if (uuidRegex.test(nameOrId)) {
           groupIds.push(nameOrId);
         } else {
@@ -77248,9 +77254,9 @@ var PermissionManager = class {
   /**
    * Assigne les permissions à un document
    */
-  async assignDocumentPermissions(documentId, permissions, level) {
+  async assignDocumentPermissions(documentId, permissions2, level) {
     try {
-      const { userIds, groupIds } = await this.resolvePermissions(permissions);
+      const { userIds, groupIds } = await this.resolvePermissions(permissions2);
       if (userIds.length === 0 && groupIds.length === 0) {
         console.warn(import_chalk5.default.yellow(`\u26A0\uFE0F  No valid permissions to assign for document ${documentId}`));
         return;
@@ -84571,7 +84577,7 @@ var CsvManager = class {
       })).on("data", (data) => {
         try {
           const permissionsStr = data["Permissions (users:r:email1,email2 | users:w:admin | groups:Group Name)"] || data["Permissions (users:r:email1@ex.com,email2@ex.com | users:w:admin@ex.com | groups:GroupName)"] || data["Permissions"] || data.Permissions || data.permissions || "";
-          const permissions = this.parsePermissions(permissionsStr);
+          const permissions2 = this.parsePermissions(permissionsStr);
           const cleanValue = (value2) => {
             if (value2 === void 0 || value2 === null) return void 0;
             const trimmed = String(value2).trim();
@@ -84584,7 +84590,7 @@ var CsvManager = class {
             metadata: this.parseMetadata(
               data["Metadata (key: value, parent.child: value)"] || data["Metadata (JSON)"] || data.Metadata || data.metadata
             ),
-            permissions,
+            permissions: permissions2,
             autoClassify: this.parseBoolean(data["Auto Classify"] || data.autoClassify),
             status: data["Status"] || data.status || "pending",
             progress: parseFloat(data["Progress (%)"] || data.progress || "0"),
@@ -84753,18 +84759,18 @@ var CsvManager = class {
           }
         } else if (type === "groups") {
           if (parts2.length === 2) {
-            const groups = parts2[1].split(",").map((g) => g.trim()).filter((g) => g);
-            if (groups.length > 0) {
-              readPermissions.groups = [...readPermissions.groups || [], ...groups];
+            const groups2 = parts2[1].split(",").map((g) => g.trim()).filter((g) => g);
+            if (groups2.length > 0) {
+              readPermissions.groups = [...readPermissions.groups || [], ...groups2];
             }
           } else if (parts2.length === 3) {
             const level = parts2[1];
-            const groups = parts2[2].split(",").map((g) => g.trim()).filter((g) => g);
-            if (groups.length > 0) {
+            const groups2 = parts2[2].split(",").map((g) => g.trim()).filter((g) => g);
+            if (groups2.length > 0) {
               if (level === "w") {
-                writePermissions.groups = [...writePermissions.groups || [], ...groups];
+                writePermissions.groups = [...writePermissions.groups || [], ...groups2];
               } else {
-                readPermissions.groups = [...readPermissions.groups || [], ...groups];
+                readPermissions.groups = [...readPermissions.groups || [], ...groups2];
               }
             }
           }
@@ -84915,20 +84921,20 @@ var CsvManager = class {
    * Serialize permissions in new format:
    * users:r:email1@ex.com,email2@ex.com | users:w:admin@ex.com | groups:Group Name | groups:w:Admin Group
    */
-  serializePermissions(permissions) {
-    if (!permissions) return "";
+  serializePermissions(permissions2) {
+    if (!permissions2) return "";
     const parts2 = [];
-    if (permissions.read?.users && permissions.read.users.length > 0) {
-      parts2.push(`users:r:${permissions.read.users.join(",")}`);
+    if (permissions2.read?.users && permissions2.read.users.length > 0) {
+      parts2.push(`users:r:${permissions2.read.users.join(",")}`);
     }
-    if (permissions.read?.groups && permissions.read.groups.length > 0) {
-      parts2.push(`groups:${permissions.read.groups.join(",")}`);
+    if (permissions2.read?.groups && permissions2.read.groups.length > 0) {
+      parts2.push(`groups:${permissions2.read.groups.join(",")}`);
     }
-    if (permissions.write?.users && permissions.write.users.length > 0) {
-      parts2.push(`users:w:${permissions.write.users.join(",")}`);
+    if (permissions2.write?.users && permissions2.write.users.length > 0) {
+      parts2.push(`users:w:${permissions2.write.users.join(",")}`);
     }
-    if (permissions.write?.groups && permissions.write.groups.length > 0) {
-      parts2.push(`groups:w:${permissions.write.groups.join(",")}`);
+    if (permissions2.write?.groups && permissions2.write.groups.length > 0) {
+      parts2.push(`groups:w:${permissions2.write.groups.join(",")}`);
     }
     return parts2.join(" | ");
   }
@@ -85861,7 +85867,7 @@ var CsvManager2 = class {
       })).on("data", (data) => {
         try {
           const permissionsStr = data["Permissions (users:r:email1,email2 | users:w:admin | groups:Group Name)"] || data["Permissions (users:r:email1@ex.com,email2@ex.com | users:w:admin@ex.com | groups:GroupName)"] || data["Permissions"] || data.Permissions || data.permissions || "";
-          const permissions = this.parsePermissions(permissionsStr);
+          const permissions2 = this.parsePermissions(permissionsStr);
           const cleanValue = (value2) => {
             if (value2 === void 0 || value2 === null) return void 0;
             const trimmed = String(value2).trim();
@@ -85874,7 +85880,7 @@ var CsvManager2 = class {
             metadata: this.parseMetadata(
               data["Metadata (key: value, parent.child: value)"] || data["Metadata (JSON)"] || data.Metadata || data.metadata
             ),
-            permissions,
+            permissions: permissions2,
             autoClassify: this.parseBoolean(data["Auto Classify"] || data.autoClassify),
             status: data["Status"] || data.status || "pending",
             progress: parseFloat(data["Progress (%)"] || data.progress || "0"),
@@ -86043,18 +86049,18 @@ var CsvManager2 = class {
           }
         } else if (type === "groups") {
           if (parts2.length === 2) {
-            const groups = parts2[1].split(",").map((g) => g.trim()).filter((g) => g);
-            if (groups.length > 0) {
-              readPermissions.groups = [...readPermissions.groups || [], ...groups];
+            const groups2 = parts2[1].split(",").map((g) => g.trim()).filter((g) => g);
+            if (groups2.length > 0) {
+              readPermissions.groups = [...readPermissions.groups || [], ...groups2];
             }
           } else if (parts2.length === 3) {
             const level = parts2[1];
-            const groups = parts2[2].split(",").map((g) => g.trim()).filter((g) => g);
-            if (groups.length > 0) {
+            const groups2 = parts2[2].split(",").map((g) => g.trim()).filter((g) => g);
+            if (groups2.length > 0) {
               if (level === "w") {
-                writePermissions.groups = [...writePermissions.groups || [], ...groups];
+                writePermissions.groups = [...writePermissions.groups || [], ...groups2];
               } else {
-                readPermissions.groups = [...readPermissions.groups || [], ...groups];
+                readPermissions.groups = [...readPermissions.groups || [], ...groups2];
               }
             }
           }
@@ -86205,20 +86211,20 @@ var CsvManager2 = class {
    * Serialize permissions in new format:
    * users:r:email1@ex.com,email2@ex.com | users:w:admin@ex.com | groups:Group Name | groups:w:Admin Group
    */
-  serializePermissions(permissions) {
-    if (!permissions) return "";
+  serializePermissions(permissions2) {
+    if (!permissions2) return "";
     const parts2 = [];
-    if (permissions.read?.users && permissions.read.users.length > 0) {
-      parts2.push(`users:r:${permissions.read.users.join(",")}`);
+    if (permissions2.read?.users && permissions2.read.users.length > 0) {
+      parts2.push(`users:r:${permissions2.read.users.join(",")}`);
     }
-    if (permissions.read?.groups && permissions.read.groups.length > 0) {
-      parts2.push(`groups:${permissions.read.groups.join(",")}`);
+    if (permissions2.read?.groups && permissions2.read.groups.length > 0) {
+      parts2.push(`groups:${permissions2.read.groups.join(",")}`);
     }
-    if (permissions.write?.users && permissions.write.users.length > 0) {
-      parts2.push(`users:w:${permissions.write.users.join(",")}`);
+    if (permissions2.write?.users && permissions2.write.users.length > 0) {
+      parts2.push(`users:w:${permissions2.write.users.join(",")}`);
     }
-    if (permissions.write?.groups && permissions.write.groups.length > 0) {
-      parts2.push(`groups:w:${permissions.write.groups.join(",")}`);
+    if (permissions2.write?.groups && permissions2.write.groups.length > 0) {
+      parts2.push(`groups:w:${permissions2.write.groups.join(",")}`);
     }
     return parts2.join(" | ");
   }
@@ -86746,13 +86752,13 @@ var PluginImportService = class {
    * Group mappings by connection ID
    */
   groupMappingsByConnection(mappings) {
-    return mappings.reduce((groups, mapping) => {
+    return mappings.reduce((groups2, mapping) => {
       const { connectionId } = mapping;
-      if (!groups[connectionId]) {
-        groups[connectionId] = [];
+      if (!groups2[connectionId]) {
+        groups2[connectionId] = [];
       }
-      groups[connectionId].push(mapping);
-      return groups;
+      groups2[connectionId].push(mapping);
+      return groups2;
     }, {});
   }
   /**
@@ -87400,6 +87406,8 @@ async function buildApiContext(out) {
     documents: new DocumentsApi(configuration, baseUrl, axiosInstance),
     chunkedUploads: new ChunkedUploadsApi(configuration, baseUrl, axiosInstance),
     users: new UsersApi(configuration, baseUrl, axiosInstance),
+    groups: new GroupsApi(configuration, baseUrl, axiosInstance),
+    permissions: new PermissionsApi(configuration, baseUrl, axiosInstance),
     baseUrl,
     token: token2,
     tokenSource: resolved.source
@@ -89008,10 +89016,437 @@ async function handleTemplatesShow(idOrKey, opts) {
   }
 }
 
+// apps/cli/cli/handlers/user-handlers.ts
+var USER_COLUMNS = [
+  { header: "ID", key: "id" },
+  { header: "Email", key: "email_address" },
+  { header: "Name", key: "display_name" },
+  { header: "Role", key: "role" },
+  { header: "External", key: "external_id", maxWidth: 24 }
+];
+function matchesQuery(user, q) {
+  const needle = q.toLowerCase();
+  const haystack = [
+    user.email_address,
+    user.first_name,
+    user.last_name,
+    user.display_name,
+    user.external_id
+  ].filter(Boolean).join(" ").toLowerCase();
+  return haystack.includes(needle);
+}
+async function handleUsersList(opts) {
+  const out = output(opts);
+  const ctx = await buildApiContext(out);
+  try {
+    const res = await ctx.users.apiV1UsersGet(
+      void 0,
+      void 0,
+      opts.limit ? Number(opts.limit) : void 0
+    );
+    let items = res.data ?? [];
+    if (opts.q) items = items.filter((u) => matchesQuery(u, opts.q));
+    if (items.length === 50 && !opts.q) {
+      out.note("server may have capped result at 50 (see corex#460) \u2014 refine with --q to filter");
+    }
+    out.list(items, USER_COLUMNS);
+  } catch (err) {
+    out.fail(err);
+  }
+}
+async function handleUsersShow(idOrEmail, opts) {
+  const out = output(opts);
+  const ctx = await buildApiContext(out);
+  const looksLikeEmail = idOrEmail.includes("@");
+  let found;
+  try {
+    if (!looksLikeEmail) {
+      const res2 = await ctx.users.apiV1UsersIdGet(idOrEmail);
+      out.show(res2.data, { title: `User ${idOrEmail}` });
+      return;
+    }
+    const res = await ctx.users.apiV1UsersGet();
+    const items = res.data ?? [];
+    found = items.find((u) => (u.email_address || "").toLowerCase() === idOrEmail.toLowerCase());
+  } catch (err) {
+    out.fail(err);
+    return;
+  }
+  if (!found) {
+    out.fail(
+      new Error(
+        `User '${idOrEmail}' not found in the first 50 results. This is likely due to corex#460 (users API server-side filter is broken). Use the UUID directly if you have it.`
+      )
+    );
+  }
+  out.show(found, { title: `User ${idOrEmail}` });
+}
+
+// apps/cli/cli/handlers/group-handlers.ts
+var GROUP_COLUMNS = [
+  { header: "ID", key: "id" },
+  { header: "Name", key: "name" },
+  { header: "Description", key: "description", maxWidth: 40 },
+  { header: "External", key: "external_id", maxWidth: 24 },
+  { header: "Updated", key: "updated_at" }
+];
+async function handleGroupsList(opts) {
+  const out = output(opts);
+  const ctx = await buildApiContext(out);
+  try {
+    const res = await ctx.groups.apiV1GroupsGet(
+      void 0,
+      void 0,
+      opts.limit ? Number(opts.limit) : void 0,
+      opts.page ? Number(opts.page) : void 0
+    );
+    let items = res.data ?? [];
+    if (opts.q) {
+      const needle = opts.q.toLowerCase();
+      items = items.filter(
+        (g) => (g.name || "").toLowerCase().includes(needle) || (g.description || "").toLowerCase().includes(needle)
+      );
+    }
+    out.list(items, GROUP_COLUMNS);
+  } catch (err) {
+    out.fail(err);
+  }
+}
+async function handleGroupsShow(id, opts) {
+  const out = output(opts);
+  const ctx = await buildApiContext(out);
+  try {
+    const res = await ctx.groups.apiV1GroupsIdGet(id);
+    out.show(res.data, { title: `Group ${id}` });
+  } catch (err) {
+    out.fail(err);
+  }
+}
+async function handleGroupsCreate(opts) {
+  const out = output(opts);
+  const ctx = await buildApiContext(out);
+  const mutation = { name: opts.name };
+  if (opts.description !== void 0) mutation.description = opts.description;
+  if (opts.externalId !== void 0) mutation.external_id = opts.externalId;
+  try {
+    const res = await ctx.groups.apiV1GroupsPost(
+      ApiV1GroupsPostContentTypeEnum.ApplicationJson,
+      mutation
+    );
+    out.ok(`Group created (id=${res.data.id})`, res.data);
+  } catch (err) {
+    out.fail(err);
+  }
+}
+async function handleGroupsUpdate(id, opts) {
+  const out = output(opts);
+  const ctx = await buildApiContext(out);
+  if (opts.name === void 0 && opts.description === void 0 && opts.externalId === void 0) {
+    out.fail(new Error("No fields to update"));
+  }
+  let nameValue = opts.name;
+  if (nameValue === void 0) {
+    try {
+      const cur = await ctx.groups.apiV1GroupsIdGet(id);
+      nameValue = cur.data.name;
+    } catch (err) {
+      out.fail(err);
+      return;
+    }
+  }
+  const mutation = { name: nameValue };
+  if (opts.description !== void 0) mutation.description = opts.description;
+  if (opts.externalId !== void 0) mutation.external_id = opts.externalId;
+  try {
+    const res = await ctx.groups.apiV1GroupsIdPatch(
+      id,
+      ApiV1GroupsIdPatchContentTypeEnum.ApplicationJson,
+      mutation
+    );
+    out.ok(`Group ${id} updated`, res.data);
+  } catch (err) {
+    out.fail(err);
+  }
+}
+async function handleGroupsDelete(id, opts) {
+  const out = output(opts);
+  const ctx = await buildApiContext(out);
+  if (!opts.yes && !opts.json) {
+    const { confirm } = await lib_default.prompt([
+      {
+        type: "confirm",
+        name: "confirm",
+        message: `Delete group ${id}? This removes all its members and permissions.`,
+        default: false
+      }
+    ]);
+    if (!confirm) {
+      out.note("Aborted");
+      return;
+    }
+  } else if (!opts.yes && opts.json) {
+    out.fail(new Error("Refusing to delete without --yes in --json mode"));
+  }
+  try {
+    await ctx.groups.apiV1GroupsIdDelete(id);
+    out.ok(`Group ${id} deleted`);
+  } catch (err) {
+    out.fail(err);
+  }
+}
+
+// apps/cli/cli/handlers/group-member-handlers.ts
+var MEMBER_COLUMNS = [
+  { header: "Membership ID", key: "id" },
+  { header: "Member ID", key: "member_id" },
+  { header: "Type", key: "member_type" },
+  { header: "External", key: "user_external_id", maxWidth: 24 },
+  { header: "Role", key: "role" }
+];
+function membersBase(groupId) {
+  return `/api/v1/groups/${encodeURIComponent(groupId)}/members`;
+}
+async function handleGroupMembersList(opts) {
+  const out = output(opts);
+  const ctx = await buildApiContext(out);
+  try {
+    const res = await ctx.axios.get(membersBase(opts.group));
+    out.list(res.data ?? [], MEMBER_COLUMNS);
+  } catch (err) {
+    out.fail(err);
+  }
+}
+async function resolveExternalId(ctx, out, opts) {
+  if (opts.userExternalId) return opts.userExternalId;
+  if (opts.userId) {
+    let ext2;
+    try {
+      const res = await ctx.users.apiV1UsersIdGet(opts.userId);
+      ext2 = res.data?.external_id;
+    } catch (err) {
+      out.fail(err);
+      return "";
+    }
+    if (!ext2) {
+      out.fail(
+        new Error(
+          `User ${opts.userId} has no external_id \u2014 server requires it to create a membership.`
+        )
+      );
+    }
+    return ext2;
+  }
+  if (opts.userEmail) {
+    let found;
+    try {
+      const res = await ctx.users.apiV1UsersGet();
+      const items = res.data ?? [];
+      found = items.find(
+        (u) => (u.email_address || "").toLowerCase() === opts.userEmail.toLowerCase()
+      );
+    } catch (err) {
+      out.fail(err);
+      return "";
+    }
+    if (!found) {
+      out.fail(
+        new Error(
+          `User '${opts.userEmail}' not found in the first 50 results. Server-side email filter is currently broken (corex#460). Look up the UUID via the web UI and pass --user-id, or pass --user-external-id directly.`
+        )
+      );
+    }
+    if (!found.external_id) {
+      out.fail(
+        new Error(
+          `User '${opts.userEmail}' has no external_id \u2014 server requires it to create a membership.`
+        )
+      );
+    }
+    return found.external_id;
+  }
+  out.fail(
+    new Error("Pass one of --user-external-id, --user-id, or --user-email to identify the user.")
+  );
+  return "";
+}
+async function handleGroupMembersAdd(opts) {
+  const out = output(opts);
+  const ctx = await buildApiContext(out);
+  const externalId = await resolveExternalId(ctx, out, opts);
+  try {
+    const res = await ctx.axios.post(membersBase(opts.group), { user_external_id: externalId });
+    out.ok(`Membership created (id=${res.data.id})`, res.data);
+  } catch (err) {
+    out.fail(err);
+  }
+}
+async function handleGroupMembersRemove(membershipId, opts) {
+  const out = output(opts);
+  const ctx = await buildApiContext(out);
+  if (!opts.yes && !opts.json) {
+    const { confirm } = await lib_default.prompt([
+      {
+        type: "confirm",
+        name: "confirm",
+        message: `Remove membership ${membershipId} from group ${opts.group}?`,
+        default: false
+      }
+    ]);
+    if (!confirm) {
+      out.note("Aborted");
+      return;
+    }
+  } else if (!opts.yes && opts.json) {
+    out.fail(new Error("Refusing to remove without --yes in --json mode"));
+  }
+  try {
+    await ctx.axios.delete(`${membersBase(opts.group)}/${encodeURIComponent(membershipId)}`);
+    out.ok(`Membership ${membershipId} removed`);
+  } catch (err) {
+    out.fail(err);
+  }
+}
+
+// apps/cli/cli/handlers/permission-handlers.ts
+var PERM_COLUMNS = [
+  { header: "ID", key: "id" },
+  { header: "Actor", key: "actor_type", format: (v, row) => `${v}:${row.actor?.display_name ?? row.actor_id?.substring(0, 8)}` },
+  { header: "Level", key: "level" },
+  { header: "On", key: "permissible_type", format: (v) => v?.replace(/^Documents::/, "") ?? "" },
+  { header: "Resource ID", key: "permissible_id" },
+  { header: "Updated", key: "updated_at" }
+];
+var VALID_LEVELS = /* @__PURE__ */ new Set(["read", "write", "admin", "owner", "forbidden"]);
+var PERMISSIBLE_ALIASES = {
+  workspace: "Documents::Workspace",
+  folder: "Documents::Folder",
+  file: "Documents::File",
+  share_link: "Documents::ShareLink"
+};
+var ACTOR_ALIASES = {
+  user: "User",
+  group: "Group",
+  contact: "Contact"
+};
+function normalizePermissibleType(input, out) {
+  const lower = input.toLowerCase();
+  if (PERMISSIBLE_ALIASES[lower]) return PERMISSIBLE_ALIASES[lower];
+  if (input.startsWith("Documents::")) return input;
+  out.fail(
+    new Error(
+      `Invalid --on-type: '${input}'. Use workspace/folder/file/share_link or a fully-qualified Documents::\u2026 class name.`
+    )
+  );
+  return "";
+}
+function normalizeActorType(input, out) {
+  const lower = input.toLowerCase();
+  if (ACTOR_ALIASES[lower]) return ACTOR_ALIASES[lower];
+  if (["User", "Group", "Contact"].includes(input)) return input;
+  out.fail(new Error(`Invalid --to-type: '${input}'. Use user/group/contact.`));
+  return "";
+}
+async function handlePermissionsList(opts) {
+  const out = output(opts);
+  const ctx = await buildApiContext(out);
+  if (!opts.on) {
+    out.fail(
+      new Error(
+        "--on=<resource-id> is required (the server rejects listing without permissible_id/type)."
+      )
+    );
+  }
+  const onType = opts.onType ? normalizePermissibleType(opts.onType, out) : "Documents::Workspace";
+  try {
+    const res = await ctx.axios.get("/api/v1/permissions", {
+      params: {
+        permissible_id: opts.on,
+        permissible_type: onType
+      }
+    });
+    let items = res.data ?? [];
+    if (opts.to) items = items.filter((p) => p.actor_id === opts.to);
+    if (opts.toType) {
+      const norm = normalizeActorType(opts.toType, out);
+      items = items.filter((p) => p.actor_type === norm);
+    }
+    if (opts.level) items = items.filter((p) => p.level === opts.level);
+    out.list(items, PERM_COLUMNS);
+  } catch (err) {
+    out.fail(err);
+  }
+}
+async function handlePermissionsGrant(opts) {
+  const out = output(opts);
+  const ctx = await buildApiContext(out);
+  if (!VALID_LEVELS.has(opts.level)) {
+    out.fail(
+      new Error(
+        `Invalid --level: '${opts.level}'. Expected one of: ${[...VALID_LEVELS].join(", ")}`
+      )
+    );
+  }
+  const actorType = normalizeActorType(opts.toType, out);
+  const permissibleType = normalizePermissibleType(opts.onType, out);
+  try {
+    const body = {
+      actor_id: opts.to,
+      actor_type: actorType,
+      permissible_id: opts.on,
+      permissible_type: permissibleType,
+      level: opts.level
+    };
+    if (opts.temporary) body.temporary = true;
+    const res = await ctx.axios.post("/api/v1/permissions", body);
+    out.ok(
+      `Permission granted (${actorType} \u2192 ${opts.level} on ${permissibleType})`,
+      res.data
+    );
+  } catch (err) {
+    out.fail(err);
+  }
+}
+async function handlePermissionsRevoke(id, opts) {
+  const out = output(opts);
+  const ctx = await buildApiContext(out);
+  if (!opts.yes && !opts.json) {
+    const { confirm } = await lib_default.prompt([
+      {
+        type: "confirm",
+        name: "confirm",
+        message: `Revoke permission ${id}?`,
+        default: false
+      }
+    ]);
+    if (!confirm) {
+      out.note("Aborted");
+      return;
+    }
+  } else if (!opts.yes && opts.json) {
+    out.fail(new Error("Refusing to revoke without --yes in --json mode"));
+  }
+  try {
+    await ctx.permissions.apiV1PermissionsIdDelete(id);
+    out.ok(`Permission ${id} revoked`);
+  } catch (err) {
+    out.fail(err);
+  }
+}
+async function handlePermissionsShow(id, opts) {
+  const out = output(opts);
+  const ctx = await buildApiContext(out);
+  try {
+    const res = await ctx.permissions.apiV1PermissionsIdGet(id);
+    out.show(res.data, { title: `Permission ${id}` });
+  } catch (err) {
+    out.fail(err);
+  }
+}
+
 // apps/cli/cli.ts
 var getVersion = () => {
   try {
-    if (true) return "1.5.1";
+    if (true) return "1.6.0";
   } catch {
   }
   for (const candidate of [
@@ -89241,6 +89676,52 @@ templates.command("ls").description("List active templates").action(async (optio
 templates.command("show <id-or-key>").description("Show a template (full default_parts + page_settings)").action(async (idOrKey, options) => {
   await handleTemplatesShow(idOrKey, withGlobals(options));
 });
+var users = program2.command("users").description("Look up users (read-only)");
+users.command("ls").description("List users (currently capped at ~50 by corex#460)").option("--q <string>", "Filter results client-side by name/email/external_id").option("--limit <n>", "Server-side per_page (currently ignored, see corex#460)").action(async (options) => {
+  await handleUsersList(withGlobals(options));
+});
+users.command("show <id-or-email>").description("Show a user by UUID or email (email lookup is capped, see corex#460)").action(async (id, options) => {
+  await handleUsersShow(id, withGlobals(options));
+});
+var groups = program2.command("groups").description("Manage groups and members");
+groups.command("ls").description("List groups").option("--q <string>", "Filter by name/description (client-side)").option("--limit <n>").option("--page <n>").action(async (options) => {
+  await handleGroupsList(withGlobals(options));
+});
+groups.command("show <id>").description("Show a group by id").action(async (id, options) => {
+  await handleGroupsShow(id, withGlobals(options));
+});
+groups.command("create").description("Create a new group").requiredOption("--name <name>", "Group name (must be unique)").option("--description <text>").option("--external-id <id>", "External system identifier").action(async (options) => {
+  await handleGroupsCreate(withGlobals(options));
+});
+groups.command("update <id>").description("Update group fields").option("--name <name>").option("--description <text>").option("--external-id <id>").action(async (id, options) => {
+  await handleGroupsUpdate(id, withGlobals(options));
+});
+groups.command("delete <id>").description("Delete a group (cascades to memberships and permissions)").option("--yes", "Skip the interactive confirmation").action(async (id, options) => {
+  await handleGroupsDelete(id, withGlobals(options));
+});
+var members = groups.command("members").description("Manage the membership of a group");
+members.command("ls").description("List members of a group").requiredOption("--group <id>", "Parent group id").action(async (options) => {
+  await handleGroupMembersList(withGlobals(options));
+});
+members.command("add").description("Add a user to a group").requiredOption("--group <id>", "Parent group id").option("--user-external-id <ext>", "External id of the user (the API requires this)").option("--user-id <uuid>", "User UUID \u2014 looked up via GET /users/:id to extract external_id").option("--user-email <email>", "User email \u2014 best-effort lookup, blocked by corex#460 beyond 50 users").action(async (options) => {
+  await handleGroupMembersAdd(withGlobals(options));
+});
+members.command("remove <membership-id>").description("Remove a membership by its id (from `members ls`)").requiredOption("--group <id>", "Parent group id").option("--yes", "Skip the interactive confirmation").action(async (id, options) => {
+  await handleGroupMembersRemove(id, withGlobals(options));
+});
+var permissions = program2.command("permissions").description("Manage ACL: grant / list / revoke permissions on documents resources");
+permissions.command("ls").description("List permissions on a specific resource").requiredOption("--on <resource-id>", "Permissible resource UUID").option("--on-type <type>", "workspace | folder | file | share_link", "workspace").option("--to <actor-id>", "Filter by actor id (client-side)").option("--to-type <type>", "Filter by actor type (user | group | contact)").option("--level <level>", "Filter by level (read|write|admin|owner|forbidden)").action(async (options) => {
+  await handlePermissionsList(withGlobals(options));
+});
+permissions.command("show <id>").description("Show a permission by id").action(async (id, options) => {
+  await handlePermissionsShow(id, withGlobals(options));
+});
+permissions.command("grant").description("Grant a permission on a resource to a user or group").requiredOption("--to <actor-id>", "Actor UUID (user/group/contact)").requiredOption("--to-type <type>", "user | group | contact").requiredOption("--on <resource-id>", "Permissible resource UUID").requiredOption("--on-type <type>", "workspace | folder | file | share_link").requiredOption("--level <level>", "read | write | admin | owner | forbidden").option("--temporary", "Mark as temporary (auto-expiring per server policy)").action(async (options) => {
+  await handlePermissionsGrant(withGlobals(options));
+});
+permissions.command("revoke <id>").description("Revoke a permission by id").option("--yes", "Skip the interactive confirmation").action(async (id, options) => {
+  await handlePermissionsRevoke(id, withGlobals(options));
+});
 program2.parse();
 /*! Bundled license information:
 

package/docs/llm-usage.md

@@ -291,12 +291,82 @@ Response shape (passed through unchanged in `--json` mode):
 Errors: `{"error": "q is required", "code": "http_400"}` if the query is
 empty (caught client-side too, before any HTTP call).
 
+### Users / Groups / Permissions (actors + ACL)
+
+These cover the actors model (who) and the ACL model (what they can do on
+what). All read+write, except `users` which is read-only.
+
+```bash
+# Users (capped at ~50 by corex#460 server-side; filter client-side via --q)
+hubdoc users ls [--q="alice"] [--limit=N] --json
+hubdoc users show <id-or-email> --json
+
+# Groups
+hubdoc groups ls [--q="..."] [--limit=N] [--page=N] --json
+hubdoc groups show <id> --json
+hubdoc groups create --name="..." [--description="..."] [--external-id=ID] --json
+hubdoc groups update <id> [--name=...] [--description=...] [--external-id=...] --json
+hubdoc groups delete <id> --yes --json
+
+# Group members (nested under `groups`)
+hubdoc groups members ls --group=<group-id> --json
+hubdoc groups members add --group=<group-id> \
+    [--user-external-id=EXT | --user-id=UUID | --user-email=EMAIL] --json
+hubdoc groups members remove <membership-id> --group=<group-id> --yes --json
+
+# Permissions (ACL: actor × permissible × level)
+hubdoc permissions ls --on=<resource-id> --on-type=workspace|folder|file|share_link \
+    [--to=<actor-id>] [--to-type=user|group|contact] [--level=read|write|admin|owner|forbidden] --json
+hubdoc permissions show <id> --json
+hubdoc permissions grant \
+    --to=<actor-id> --to-type=user|group|contact \
+    --on=<resource-id> --on-type=workspace|folder|file|share_link \
+    --level=read|write|admin|owner|forbidden \
+    [--temporary] --json
+hubdoc permissions revoke <id> --yes --json
+```
+
+`--on-type` and `--to-type` accept short aliases (`workspace`, `group`, …)
+or the fully-qualified class names (`Documents::Workspace`, `Group`, …).
+
+> ⚠️ `users` commands are partially blocked by [corex#460](https://code.plugandwork.net/sinoia/corex/-/issues/460) — `GET /api/v1/users` ignores `per_page`/`page`/`q` server-side and caps silently at 50. `users ls --q` and `users show <email>` work best-effort on those 50 rows. Use UUIDs directly when possible. `groups members add --user-email` is subject to the same limitation.
+
+#### End-to-end example: create a team and share a workspace with it
+
+Reproduces the real operation that motivated this section:
+
+```bash
+# 1. Workspace + group
+WS=$(hubdoc workspaces create --name="Informations techniques" --json | jq -r '.data.id')
+GRP=$(hubdoc groups create --name="sysadmins" --description="System admins" --json | jq -r '.data.id')
+
+# 2. Add members (auto-resolves external_id from email when possible)
+for email in \
+    olivier.dirrenberger@sinoia.fr \
+    benoit.nicolaeff@plugandwork.fr \
+    gaetan.marquet@plugandwork.fr ; do
+  hubdoc groups members add --group="$GRP" --user-email="$email" --json
+done
+
+# 3. Upload a sensitive file into the workspace
+FILE=$(hubdoc files upload ./creds.txt --workspace="$WS" --json | jq -r '.data.id')
+
+# 4. Grant admin permission to the group on the whole workspace
+hubdoc permissions grant \
+    --to="$GRP" --to-type=group \
+    --on="$WS" --on-type=workspace \
+    --level=admin --json
+
+# 5. Audit
+hubdoc permissions ls --on="$WS" --on-type=workspace --json \
+    | jq '.[] | {actor: .actor.display_name, level}'
+```
+
 ## Out of scope (planned)
 
 - `hubdoc templates create|update|delete` — depends on corex#417 backend
   extension (the controller is read-only today). The CLI will follow once
   the API is in place.
-- `hubdoc permissions ...` — to be scoped if/when demand confirms.
 - JSON-API for PAT management (`hubdoc auth tokens ls/revoke`) — the
   Corex PAT controller is Inertia/web-only today.
 - `/api/v1/me` — not yet shipped; `whoami` falls back to JWT decode.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sinoia/hubdoc-tools",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Professional command-line tool for HubDoc document management and bulk import/export",
   "main": "cli.js",
   "bin": {