@colixsystems/widget-sdk 0.34.0 → 0.35.0

package/README.md

@@ -47,7 +47,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.34.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.35.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.35.0
+
+**Folder-ACL + signer-roster hooks (REQ-FSH / REQ-SIGN).** Two admin/MANAGE-gated hooks reading the existing `ctx.filestore`:
+- `useFileRoster(fileId, { limit?, offset?, enabled? })` → `{ roster, total, signedCount, loading, error, refetch }` — the signer roster for one file: the folder audience (every member of an open project folder, or the granted users/groups of a restricted one), each annotated `signed` with `signer_name` / `signed_at`. Reads `ctx.filestore.signatures.roster` (new `@colixsystems/filestore-client` **0.5.0** method); the host 403s a non-manager, so use `error` to hide the panel for non-admins.
+- `useFolderPermissions(folderId, { enabled? })` → `{ grants, loading, busy, error, refetch, grant, revoke, setVisibility }` — manage a folder's permissions (the Filestore ACL): `grant(subjectType, subjectId, 'VIEW'|'DOWNLOAD'|'MANAGE')`, `revoke(shareId)`, `setVisibility('INHERIT'|'RESTRICTED')`. Pair the user/group picker with `useUsers` / `useGroups`.
+
+Also: `useFileSignatures(fileIds)` is now **self-scoped** (the caller's own signatures only) — the backend tightened; the hook's shape is unchanged. **`CONTRACT.version` → `1.25.0`** (additive: two new hooks; the underlying `filestore-client` → `0.5.0`, shares folder-scoped).
 
 ### What's new in 0.34.0
 

package/dist/contract.cjs

@@ -236,6 +236,51 @@ const HOOKS = [
     requiredContextSlice: ["filestore.signatures"],
     scopes: ["files.read:*"],
   },
+  {
+    name: "useFileRoster",
+    signature: "useFileRoster(fileId, { limit?, offset?, enabled? }?)",
+    description:
+      "MANAGE-gated signer roster for one Filestore file: the people expected " +
+      "to be able to sign it (the file's folder audience) each annotated " +
+      "signed/not-signed, plus a distinct signed_count. Reads " +
+      "ctx.filestore.signatures.roster and unwraps { data, meta }. The host 403s " +
+      "a caller who can see the file but does not MANAGE its folder — surface " +
+      "that as 'not an admin here' via `error`.",
+    returnShape: {
+      roster:
+        "{ app_user_id, name, signed, signature_id, signer_name, signed_at }[]",
+      total: "number",
+      signedCount: "number",
+      loading: "boolean",
+      error: "Error | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["filestore.signatures"],
+    scopes: ["files.read:*"],
+  },
+  {
+    name: "useFolderPermissions",
+    signature: "useFolderPermissions(folderId, { enabled? }?)",
+    description:
+      "Manage a folder's permissions (the Filestore ACL — folder-scoped). Lists " +
+      "the folder's grants and exposes grant(subjectType, subjectId, permission) " +
+      "/ revoke(shareId) / setVisibility('INHERIT' | 'RESTRICTED') — all MANAGE " +
+      "actions the host enforces. Reads ctx.filestore.shares + ctx.filestore." +
+      "folders; pair the user/group picker with useUsers / useGroups.",
+    returnShape: {
+      grants:
+        "{ id, folder_id, subject_type, subject_id, permission, created_at }[]",
+      loading: "boolean",
+      busy: "boolean",
+      error: "Error | null",
+      refetch: "() => Promise<void>",
+      grant: "(subjectType, subjectId, permission) => Promise<share>",
+      revoke: "(shareId) => Promise<void>",
+      setVisibility: "(visibility) => Promise<folder>",
+    },
+    requiredContextSlice: ["filestore.shares", "filestore.folders"],
+    scopes: ["files.read:*", "files.write:*"],
+  },
   {
     name: "useDatastoreQuery",
     signature: "useDatastoreQuery(tableId, options?)",
@@ -867,7 +912,7 @@ const WIDGET_CONTEXT_SHAPE = {
       "signatures: { initiate(fileId), status(id), cancel(id), verify(id) }, objectUrl(token), fetchObject(token) }. " +
       "Backs useFilestoreFiles() + useFilestoreFolders() + useFileSignature(). Optional — a host without an end-user filestore omits it and those hooks throw a clear error.",
     required: false,
-    fields: { files: "object", folders: "object", signatures: "object" },
+    fields: { files: "object", folders: "object", shares: "object", signatures: "object" },
   },
   renderer: {
     description:
@@ -1394,7 +1439,15 @@ const CONTRACT = deepFreeze({
   //    (animated-QR poll). Self-service + JWT-gated — no requestedScopes entry.
   //    No existing hook, primitive, or field changed shape — minor bump on the
   //    pre-1.0 channel.
-  version: "1.24.0",
+  //
+  // 1.25.0: additive (REQ-FSH / REQ-SIGN) — new `useFileRoster(fileId)`
+  //    (MANAGE-gated signer roster: the folder audience annotated
+  //    signed/not-signed) and `useFolderPermissions(folderId)` (manage the
+  //    folder ACL: list grants + grant/revoke a VIEW/DOWNLOAD/MANAGE tier +
+  //    setVisibility). Both read the existing `ctx.filestore`; the underlying
+  //    `filestore-client` 0.5.0 made shares folder-scoped + added
+  //    `signatures.roster`. No existing hook changed.
+  version: "1.25.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/contract.js

@@ -236,6 +236,51 @@ const HOOKS = [
     requiredContextSlice: ["filestore.signatures"],
     scopes: ["files.read:*"],
   },
+  {
+    name: "useFileRoster",
+    signature: "useFileRoster(fileId, { limit?, offset?, enabled? }?)",
+    description:
+      "MANAGE-gated signer roster for one Filestore file: the people expected " +
+      "to be able to sign it (the file's folder audience) each annotated " +
+      "signed/not-signed, plus a distinct signed_count. Reads " +
+      "ctx.filestore.signatures.roster and unwraps { data, meta }. The host 403s " +
+      "a caller who can see the file but does not MANAGE its folder — surface " +
+      "that as 'not an admin here' via `error`.",
+    returnShape: {
+      roster:
+        "{ app_user_id, name, signed, signature_id, signer_name, signed_at }[]",
+      total: "number",
+      signedCount: "number",
+      loading: "boolean",
+      error: "Error | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["filestore.signatures"],
+    scopes: ["files.read:*"],
+  },
+  {
+    name: "useFolderPermissions",
+    signature: "useFolderPermissions(folderId, { enabled? }?)",
+    description:
+      "Manage a folder's permissions (the Filestore ACL — folder-scoped). Lists " +
+      "the folder's grants and exposes grant(subjectType, subjectId, permission) " +
+      "/ revoke(shareId) / setVisibility('INHERIT' | 'RESTRICTED') — all MANAGE " +
+      "actions the host enforces. Reads ctx.filestore.shares + ctx.filestore." +
+      "folders; pair the user/group picker with useUsers / useGroups.",
+    returnShape: {
+      grants:
+        "{ id, folder_id, subject_type, subject_id, permission, created_at }[]",
+      loading: "boolean",
+      busy: "boolean",
+      error: "Error | null",
+      refetch: "() => Promise<void>",
+      grant: "(subjectType, subjectId, permission) => Promise<share>",
+      revoke: "(shareId) => Promise<void>",
+      setVisibility: "(visibility) => Promise<folder>",
+    },
+    requiredContextSlice: ["filestore.shares", "filestore.folders"],
+    scopes: ["files.read:*", "files.write:*"],
+  },
   {
     name: "useDatastoreQuery",
     signature: "useDatastoreQuery(tableId, options?)",
@@ -867,7 +912,7 @@ const WIDGET_CONTEXT_SHAPE = {
       "signatures: { initiate(fileId), status(id), cancel(id), verify(id) }, objectUrl(token), fetchObject(token) }. " +
       "Backs useFilestoreFiles() + useFilestoreFolders() + useFileSignature(). Optional — a host without an end-user filestore omits it and those hooks throw a clear error.",
     required: false,
-    fields: { files: "object", folders: "object", signatures: "object" },
+    fields: { files: "object", folders: "object", shares: "object", signatures: "object" },
   },
   renderer: {
     description:
@@ -1394,7 +1439,15 @@ const CONTRACT = deepFreeze({
   //    (animated-QR poll). Self-service + JWT-gated — no requestedScopes entry.
   //    No existing hook, primitive, or field changed shape — minor bump on the
   //    pre-1.0 channel.
-  version: "1.24.0",
+  //
+  // 1.25.0: additive (REQ-FSH / REQ-SIGN) — new `useFileRoster(fileId)`
+  //    (MANAGE-gated signer roster: the folder audience annotated
+  //    signed/not-signed) and `useFolderPermissions(folderId)` (manage the
+  //    folder ACL: list grants + grant/revoke a VIEW/DOWNLOAD/MANAGE tier +
+  //    setVisibility). Both read the existing `ctx.filestore`; the underlying
+  //    `filestore-client` 0.5.0 made shares folder-scoped + added
+  //    `signatures.roster`. No existing hook changed.
+  version: "1.25.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/hooks.js

@@ -1503,6 +1503,193 @@ export function useFileSignatures(fileIds) {
   return { signaturesByFileId, loading, error, refetch };
 }
 
+/**
+ * REQ-SIGN: MANAGE-gated signer roster for one file — the people expected to be
+ * able to sign it (the file's folder audience) each annotated signed/not-signed.
+ * Reads ctx.filestore.signatures.roster. The host backend 403s a caller who can
+ * see the file but doesn't manage its folder, so `error` (a ForbiddenError) is
+ * the "you're not an admin here" signal the widget hides on. Returns
+ * { roster, total, signedCount, loading, error, refetch }. `roster` items are
+ * { app_user_id, name, signed, signature_id, signer_name, signed_at }.
+ */
+export function useFileRoster(fileId, options = {}) {
+  const ctx = useWidgetContextOrThrow("useFileRoster");
+  if (
+    !ctx.filestore ||
+    !ctx.filestore.signatures ||
+    typeof ctx.filestore.signatures.roster !== "function"
+  ) {
+    throw new Error(
+      "useFileRoster: host did not inject a filestore client (ctx.filestore.signatures.roster)",
+    );
+  }
+  const { limit = 50, offset = 0, enabled = true } = options;
+  const [roster, setRoster] = useState([]);
+  const [total, setTotal] = useState(0);
+  const [signedCount, setSignedCount] = useState(0);
+  const [loading, setLoading] = useState(Boolean(fileId) && enabled);
+  const [error, setError] = useState(null);
+
+  const sigRef = useRef(ctx.filestore.signatures);
+  sigRef.current = ctx.filestore.signatures;
+  const argsRef = useRef({ fileId, limit, offset, enabled });
+  argsRef.current = { fileId, limit, offset, enabled };
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const { fileId: fid, limit: lim, offset: off, enabled: en } = argsRef.current;
+    if (!fid || !en) {
+      setLoading(false);
+      setError(null);
+      setRoster([]);
+      setTotal(0);
+      setSignedCount(0);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await sigRef.current.roster(fid, { limit: lim, offset: off });
+      if (runRef.current !== myRun) return;
+      const rows = res && Array.isArray(res.data) ? res.data : [];
+      const meta = (res && res.meta) || {};
+      setRoster(rows);
+      setTotal(typeof meta.total === "number" ? meta.total : rows.length);
+      setSignedCount(typeof meta.signed_count === "number" ? meta.signed_count : 0);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(err);
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [fileId, limit, offset, enabled]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  return { roster, total, signedCount, loading, error, refetch };
+}
+
+/**
+ * REQ-FSH: folder-permission management for one folder (the Filestore ACL).
+ * Reads ctx.filestore.shares + ctx.filestore.folders. Lists the folder's grants
+ * and exposes grant / revoke / setVisibility mutations — all MANAGE actions the
+ * host backend enforces (a non-manager's mutation rejects). Pair the user/group
+ * picker with useUsers / useGroups. Returns { grants, loading, busy, error,
+ * refetch, grant, revoke, setVisibility }.
+ */
+export function useFolderPermissions(folderId, options = {}) {
+  const ctx = useWidgetContextOrThrow("useFolderPermissions");
+  if (
+    !ctx.filestore ||
+    !ctx.filestore.shares ||
+    typeof ctx.filestore.shares.list !== "function" ||
+    !ctx.filestore.folders ||
+    typeof ctx.filestore.folders.update !== "function"
+  ) {
+    throw new Error(
+      "useFolderPermissions: host did not inject a filestore client (ctx.filestore.shares / ctx.filestore.folders)",
+    );
+  }
+  const { enabled = true } = options;
+  const [grants, setGrants] = useState([]);
+  const [loading, setLoading] = useState(Boolean(folderId) && enabled);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState(null);
+
+  const sharesRef = useRef(ctx.filestore.shares);
+  sharesRef.current = ctx.filestore.shares;
+  const foldersRef = useRef(ctx.filestore.folders);
+  foldersRef.current = ctx.filestore.folders;
+  const idRef = useRef({ folderId, enabled });
+  idRef.current = { folderId, enabled };
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const { folderId: fid, enabled: en } = idRef.current;
+    if (!fid || !en) {
+      setLoading(false);
+      setError(null);
+      setGrants([]);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await sharesRef.current.list({ folder_id: fid });
+      if (runRef.current !== myRun) return;
+      setGrants(res && Array.isArray(res.data) ? res.data : []);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(err);
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [folderId, enabled]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  const grant = useCallback(
+    async (subjectType, subjectId, permission) => {
+      const { folderId: fid } = idRef.current;
+      setBusy(true);
+      try {
+        const row = await sharesRef.current.create({
+          folder_id: fid,
+          subject_type: subjectType,
+          subject_id: subjectId,
+          permission,
+        });
+        await doFetch();
+        return row;
+      } finally {
+        setBusy(false);
+      }
+    },
+    [doFetch],
+  );
+
+  const revoke = useCallback(
+    async (shareId) => {
+      setBusy(true);
+      try {
+        await sharesRef.current.remove(shareId);
+        await doFetch();
+      } finally {
+        setBusy(false);
+      }
+    },
+    [doFetch],
+  );
+
+  const setVisibility = useCallback(async (visibility) => {
+    const { folderId: fid } = idRef.current;
+    setBusy(true);
+    try {
+      return await foldersRef.current.update(fid, { visibility });
+    } finally {
+      setBusy(false);
+    }
+  }, []);
+
+  return { grants, loading, busy, error, refetch, grant, revoke, setVisibility };
+}
+
 /* ============================================================================
  * DIRECTORY CLIENT — ctx.directory (@colixsystems/directory-client)
  *

package/dist/index.js

@@ -19,6 +19,8 @@ export {
   useFilestoreFolders,
   useFileSignature,
   useFileSignatures,
+  useFileRoster,
+  useFolderPermissions,
   useDatastoreMutation,
   useDirectory,
   useUsers,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",