@colixsystems/widget-sdk 0.168.0 → 0.169.0

package/README.md

@@ -73,7 +73,18 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.167.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.169.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.169.0 (contract 1.130.0)
+
+**Widgets can create folders and copy files, including between spaces.** Two new hooks over `ctx.filestore`:
+
+- `useFilestoreCreateFolder({ spaceType, parentFolderId? })` → `{ createFolder, creating, error, lastCreated }`. `createFolder(name, { parentFolderId? })` resolves to the new folder row; `parentFolderId` omitted or `null` places it at the space root. Refetch your `useFilestoreFolders` afterwards to show it.
+- `useFilestoreCopy()` → `{ copy, copying, error, lastCopied }`. `copy(fileId, { spaceType, folderId?, name? })` duplicates a file into any space the user may add files to — project, public, or their own personal space — and resolves to the **new** file row with its own `id` and `url`. `spaceType` names the destination and is required. The bytes are duplicated server-side, so the copy and its source are independent afterwards. A name already taken at the destination lands as `name (2).ext` and never replaces the existing file.
+
+The public space keeps its usual gate: copying into it needs the same upload access the workspace operator grants for uploads, and creating a folder there needs the right to manage that space, so an app user's public `createFolder()` is refused unless they were given it. Copying into the user's own personal space works whenever they may download the source.
+
+Refusals keep the usual shape: branch on `err.status`, with the server's code at `err.details.code`. The copy-specific codes are `FILE_COPY_NOT_PERMITTED` (the user may only view the source), `UPLOAD_NOT_PERMITTED` (the destination refuses the add), `STORAGE_QUOTA_EXCEEDED` (413) and `FILE_PROCESSING` (409, a video still being processed). Both hooks need the `files.write:*` scope and behave identically on the web Player and the native export. Needs `@colixsystems/filestore-client` 0.10.0, which adds `files.copy(id, body)`.
 
 ### What's new in 0.167.0 (contract 1.129.0)
 
@@ -1593,7 +1604,7 @@ Also: `useFileSignatures(fileIds)` is now **self-scoped** (the caller's own sign
 **Filestore browsing + BankID file signing for widgets (REQ-FS / REQ-SIGN).** Three new hooks read a newly-injected `ctx.filestore` (the `@colixsystems/filestore-client`, now constructed by both the web and native hosts):
 - `useFilestoreFiles({ spaceType, folderId?, q?, type? })` → `{ files, loading, error, refetch }` — browses the end-user's Filestore space. The hook resolves `owner_id` from the host context (tenant for a project space, the app user for a personal space), so the widget only picks the space. Every row carries a ready-to-render `url` (its absolutized `presigned_url`), so a gallery renders `files.map(f => f.url)` directly — no per-row `useFilestoreFile` call. Every row ALSO carries `urls` — the size ladder `{ thumbnail, card, large, hero }` at 128 / 512 / 1024 / 2048px longest edge — so a thumbnail grid should render `f.urls.thumbnail` rather than pulling the full-size original for every tile.
 - `useFilestoreFile(fileId)` → `{ file, url, urls, loading, error, refetch }` — resolves ONE file id to a displayable `url` (its `presigned_url`, absolutized for web + native) via `ctx.filestore.files.get(id)`. **Read the top-level `url`** — the returned `file` is `null` until the fetch resolves (and for an empty id), so `file.url` throws on the first render; it is correct only after a null check. **Never compose a file URL yourself** — the bytes are served only from a server-signed token URL, so a hand-built path like `/api/files/<id>` can never resolve (the linter's `no-host-api-url` rule flags it, including the `${location.origin}/api/files/…` form). A datastore `FILE` column holds — and reads back as — that **bare file-id string**; it is NOT hydrated into an object the way a `RELATION` (`{ id, label }`) or `USER` (`{ id, name }`) column is, so pass the value straight to the hook (no `{ id }` / `{ url }` unwrapping guard). Empty / deleted / not-found ids resolve to `url: null` so a display widget shows a fallback. When you render `url` in an `<Image>` that fills its container, size it with `aspectRatio` (e.g. `{ width: "100%", aspectRatio: 1 }`) or pixels — never a percentage `height`, which React Native collapses to 0 against a content-sized parent, so the image loads but is invisible. Requires `files.read:*`.
-- `useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })` → `{ folders, loading, error, refetch }` — the folder-navigation companion to `useFilestoreFiles`; pass `enabled:false` to suspend fetching.
+- `useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })` → `{ folders, loading, error, refetch }` — the folder-navigation companion to `useFilestoreFiles`; pass `enabled:false` to suspend fetching. (Folder creation and file copy arrived later, in 0.169.0 — see above.)
 - `useFilestoreUpload({ spaceType, folderId?, compress? })` → `{ upload, uploading, error, lastUploaded }` — POSTs a multipart upload to `ctx.filestore.files.upload`. Resolves `owner_id` from the host context (like the read hooks) so the widget only picks the space + destination folder. Uploaded images are compressed to WebP by the backend; pass `compress: false` (on the hook, or per `upload(file, { compress })`) to store the file byte-for-byte — use it whenever the original matters. Pair with the `<FilePicker>` primitive for the visible trigger. Requires the `files.write:*` scope.
 - `useFileSignature(fileId)` → `{ status, qr, signerName, verdict, initiate, refresh, cancel, verify, … }` — drives a BankID signing flow for a file (the backend hashes the bytes server-side, binds the digest into the signature, and verifies the proof offline).
 

package/dist/contract.cjs

@@ -1217,6 +1217,56 @@ const HOOKS = [
     requiredContextSlice: ["filestore.folders"],
     scopes: ["files.read:*"],
   },
+  {
+    name: "useFilestoreCreateFolder",
+    signature: "useFilestoreCreateFolder({ spaceType, parentFolderId })",
+    optionalArgs: ["parentFolderId"],
+    description:
+      "Create a folder in the end-user's Filestore space. The widget passes the " +
+      "SPACE (`{ spaceType, parentFolderId? }`); the hook resolves owner_id from " +
+      "the host context and posts `{ name, space_type, owner_id, parent_folder_id }` " +
+      "through ctx.filestore.folders.create. `createFolder(name, { parentFolderId? })` " +
+      "resolves to the created folder row or throws the wire error: 422 for an " +
+      "invalid name, 404 for a parent that is not in this space, 403/404 when the " +
+      "caller may not add a folder there (the server's FOLDER_CREATE_NOT_PERMITTED " +
+      "is at `err.details.code`). In the public space only managers of that space " +
+      "may create folders. Refetch useFilestoreFolders afterwards to show it.",
+    returnShape: {
+      createFolder: "(name, { parentFolderId? }) => Promise<FilestoreFolder>",
+      creating: "boolean",
+      error: "Error | null",
+      lastCreated: "FilestoreFolder | null",
+    },
+    requiredContextSlice: ["filestore.folders"],
+    scopes: ["files.write:*"],
+  },
+  {
+    name: "useFilestoreCopy",
+    signature: "useFilestoreCopy()",
+    description:
+      "Copy a Filestore file into any space and folder the caller may add files " +
+      "to, including ACROSS spaces (project, public, and the signed-in user's " +
+      "personal space). `copy(fileId, { spaceType, folderId?, name? })` names the " +
+      "DESTINATION (spaceType is required); the hook resolves its owner_id from " +
+      "the host context and posts through ctx.filestore.files.copy. Resolves to " +
+      "the NEW file row (its own id and url) — the source is untouched and the " +
+      "bytes are duplicated, so later changes to one never affect the other. A " +
+      "name already taken at the destination lands as \"name (2).ext\" instead of " +
+      "replacing it. Copying INTO public needs the same operator upload grant as " +
+      "uploading there. Errors (code at `err.details.code`): 404 source not visible; " +
+      "403 FILE_COPY_NOT_PERMITTED when the caller may only view the source; " +
+      "403/404 UPLOAD_NOT_PERMITTED when the destination refuses the add; 413 " +
+      "STORAGE_QUOTA_EXCEEDED when the destination space is full; 409 " +
+      "FILE_PROCESSING while a video is still being processed.",
+    returnShape: {
+      copy: "(fileId, { spaceType, folderId?, name? }) => Promise<FilestoreFile>",
+      copying: "boolean",
+      error: "Error | null",
+      lastCopied: "FilestoreFile | null",
+    },
+    requiredContextSlice: ["filestore.files"],
+    scopes: ["files.write:*"],
+  },
   {
     name: "useFileSignature",
     signature: "useFileSignature(fileId, existingSignatureId)",
@@ -2692,10 +2742,10 @@ const WIDGET_CONTEXT_SHAPE = {
   filestore: {
     description:
       "Injected @colixsystems/filestore-client instance — the end-user file archive (project / personal / public spaces) + BankID file signing. " +
-      "{ files: { list(query) -> Promise<{ data, meta }>, get(id), upload(formData), update(id, body), remove(id), preview(id) }, " +
+      "{ files: { list(query) -> Promise<{ data, meta }>, get(id), upload(formData), update(id, body), copy(id, body), remove(id), preview(id) }, " +
       "folders: { list, create, update, remove }, shares: { ... }, trash: { ... }, " +
       "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.",
+      "Backs useFilestoreFiles() + useFilestoreFolders() + useFilestoreCreateFolder() + useFilestoreCopy() + 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", shares: "object", signatures: "object" },
   },
@@ -4553,7 +4603,11 @@ const CONTRACT = deepFreeze({
   // it removed every `<...>`, so an AI reply lost `Promise<void>`. The
   // emphasis grammar now follows CommonMark flanking rules, so `created_at`
   // keeps its underscore and `2 * 4` keeps its asterisk.
-  version: "1.129.0",
+  // 1.130.0: additive (sc-9057) — `useFilestoreCreateFolder` and
+  // `useFilestoreCopy`. Widgets can now create Filestore folders and copy a
+  // file into another folder or space (project / public / personal); the
+  // filestore client gains `files.copy`.
+  version: "1.130.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1217,6 +1217,56 @@ const HOOKS = [
     requiredContextSlice: ["filestore.folders"],
     scopes: ["files.read:*"],
   },
+  {
+    name: "useFilestoreCreateFolder",
+    signature: "useFilestoreCreateFolder({ spaceType, parentFolderId })",
+    optionalArgs: ["parentFolderId"],
+    description:
+      "Create a folder in the end-user's Filestore space. The widget passes the " +
+      "SPACE (`{ spaceType, parentFolderId? }`); the hook resolves owner_id from " +
+      "the host context and posts `{ name, space_type, owner_id, parent_folder_id }` " +
+      "through ctx.filestore.folders.create. `createFolder(name, { parentFolderId? })` " +
+      "resolves to the created folder row or throws the wire error: 422 for an " +
+      "invalid name, 404 for a parent that is not in this space, 403/404 when the " +
+      "caller may not add a folder there (the server's FOLDER_CREATE_NOT_PERMITTED " +
+      "is at `err.details.code`). In the public space only managers of that space " +
+      "may create folders. Refetch useFilestoreFolders afterwards to show it.",
+    returnShape: {
+      createFolder: "(name, { parentFolderId? }) => Promise<FilestoreFolder>",
+      creating: "boolean",
+      error: "Error | null",
+      lastCreated: "FilestoreFolder | null",
+    },
+    requiredContextSlice: ["filestore.folders"],
+    scopes: ["files.write:*"],
+  },
+  {
+    name: "useFilestoreCopy",
+    signature: "useFilestoreCopy()",
+    description:
+      "Copy a Filestore file into any space and folder the caller may add files " +
+      "to, including ACROSS spaces (project, public, and the signed-in user's " +
+      "personal space). `copy(fileId, { spaceType, folderId?, name? })` names the " +
+      "DESTINATION (spaceType is required); the hook resolves its owner_id from " +
+      "the host context and posts through ctx.filestore.files.copy. Resolves to " +
+      "the NEW file row (its own id and url) — the source is untouched and the " +
+      "bytes are duplicated, so later changes to one never affect the other. A " +
+      "name already taken at the destination lands as \"name (2).ext\" instead of " +
+      "replacing it. Copying INTO public needs the same operator upload grant as " +
+      "uploading there. Errors (code at `err.details.code`): 404 source not visible; " +
+      "403 FILE_COPY_NOT_PERMITTED when the caller may only view the source; " +
+      "403/404 UPLOAD_NOT_PERMITTED when the destination refuses the add; 413 " +
+      "STORAGE_QUOTA_EXCEEDED when the destination space is full; 409 " +
+      "FILE_PROCESSING while a video is still being processed.",
+    returnShape: {
+      copy: "(fileId, { spaceType, folderId?, name? }) => Promise<FilestoreFile>",
+      copying: "boolean",
+      error: "Error | null",
+      lastCopied: "FilestoreFile | null",
+    },
+    requiredContextSlice: ["filestore.files"],
+    scopes: ["files.write:*"],
+  },
   {
     name: "useFileSignature",
     signature: "useFileSignature(fileId, existingSignatureId)",
@@ -2688,10 +2738,10 @@ const WIDGET_CONTEXT_SHAPE = {
   filestore: {
     description:
       "Injected @colixsystems/filestore-client instance — the end-user file archive (project / personal / public spaces) + BankID file signing. " +
-      "{ files: { list(query) -> Promise<{ data, meta }>, get(id), upload(formData), update(id, body), remove(id), preview(id) }, " +
+      "{ files: { list(query) -> Promise<{ data, meta }>, get(id), upload(formData), update(id, body), copy(id, body), remove(id), preview(id) }, " +
       "folders: { list, create, update, remove }, shares: { ... }, trash: { ... }, " +
       "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.",
+      "Backs useFilestoreFiles() + useFilestoreFolders() + useFilestoreCreateFolder() + useFilestoreCopy() + 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", shares: "object", signatures: "object" },
   },
@@ -4549,7 +4599,11 @@ const CONTRACT = deepFreeze({
   // it removed every `<...>`, so an AI reply lost `Promise<void>`. The
   // emphasis grammar now follows CommonMark flanking rules, so `created_at`
   // keeps its underscore and `2 * 4` keeps its asterisk.
-  version: "1.129.0",
+  // 1.130.0: additive (sc-9057) — `useFilestoreCreateFolder` and
+  // `useFilestoreCopy`. Widgets can now create Filestore folders and copy a
+  // file into another folder or space (project / public / personal); the
+  // filestore client gains `files.copy`.
+  version: "1.130.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -3850,7 +3850,8 @@ export function useAssetsByTag(tag, options) {
  * FILESTORE CLIENT — ctx.filestore (@colixsystems/filestore-client)
  *
  * The end-user file archive (project / personal spaces) + BankID file signing.
- * Covers: useFilestoreFiles, useFileSignature.
+ * Covers: useFilestoreFiles, useFilestoreFolders, useFilestoreCreateFolder,
+ * useFilestoreCopy, useFilestoreUpload, useFileSignature.
  * ==========================================================================*/
 
 // Resolve the owner_id a filestore query needs from the host context: a PROJECT
@@ -4302,6 +4303,153 @@ export function useFilestoreFolders(options) {
   return { folders, loading, error, refetch };
 }
 
+/**
+ * Create a folder in the end-user's Filestore space. Returns `{ createFolder,
+ * creating, error, lastCreated }`. The widget passes the SPACE (`{ spaceType,
+ * parentFolderId? }`); the hook resolves owner_id from the host context and
+ * posts `{ name, space_type, owner_id, parent_folder_id }` through
+ * `ctx.filestore.folders.create`.
+ *
+ * `createFolder(name, { parentFolderId? })` resolves to the created folder row
+ * or throws the wire error: 422 for an invalid name, 404 for a parent that is
+ * not in this space, and 403/404 when the caller may not add a folder there
+ * (403 when they can see the position). The server's
+ * `FOLDER_CREATE_NOT_PERMITTED` is at `err.details.code`.
+ */
+export function useFilestoreCreateFolder(options) {
+  const ctx = useWidgetContextOrThrow("useFilestoreCreateFolder");
+  if (
+    !ctx.filestore ||
+    !ctx.filestore.folders ||
+    typeof ctx.filestore.folders.create !== "function"
+  ) {
+    throw new Error(
+      "useFilestoreCreateFolder: host did not inject a filestore client (ctx.filestore.folders.create)",
+    );
+  }
+  const { spaceType = "project", parentFolderId: defaultParentId = null } =
+    options || {};
+  const ownerId = _filestoreOwnerId(ctx, spaceType);
+
+  const [creating, setCreating] = useState(false);
+  const [error, setError] = useState(null);
+  const [lastCreated, setLastCreated] = useState(null);
+
+  const foldersRef = useRef(ctx.filestore.folders);
+  foldersRef.current = ctx.filestore.folders;
+
+  const createFolder = useCallback(
+    async (name, overrides) => {
+      if (typeof name !== "string" || name.trim().length === 0) {
+        throw new Error("useFilestoreCreateFolder: name is required");
+      }
+      if (!ownerId) {
+        const err = new Error("Sign in to create a folder");
+        setError(err);
+        throw err;
+      }
+      const parentFolderId =
+        overrides &&
+        Object.prototype.hasOwnProperty.call(overrides, "parentFolderId")
+          ? overrides.parentFolderId
+          : defaultParentId;
+      const body = {
+        name: name.trim(),
+        space_type: String(spaceType || "project").toUpperCase(),
+        owner_id: ownerId,
+      };
+      if (parentFolderId) body.parent_folder_id = parentFolderId;
+      setCreating(true);
+      setError(null);
+      try {
+        const created = await foldersRef.current.create(body);
+        setLastCreated(created || null);
+        setCreating(false);
+        return created;
+      } catch (err) {
+        setError(err);
+        setCreating(false);
+        throw err;
+      }
+    },
+    [ownerId, defaultParentId, spaceType],
+  );
+
+  return { createFolder, creating, error, lastCreated };
+}
+
+/**
+ * Copy a Filestore file into any space and folder the caller may add files
+ * to — including ACROSS spaces (project, public, the user's personal space).
+ * Returns `{ copy, copying, error, lastCopied }`.
+ *
+ * `copy(fileId, { spaceType, folderId?, name? })` names the DESTINATION;
+ * `spaceType` is required. The hook resolves the destination owner_id the same
+ * way the upload hook does and posts through `ctx.filestore.files.copy`. It
+ * resolves to the NEW file row (its own id and url); the source is untouched.
+ * A name already taken at the destination lands as "name (2).ext" rather than
+ * replacing that file.
+ *
+ * Errors: 404 when the source is not visible, 403 `FILE_COPY_NOT_PERMITTED`
+ * when it is view-only, 403/404 `UPLOAD_NOT_PERMITTED` when the destination
+ * refuses the add, 413 `STORAGE_QUOTA_EXCEEDED` when the destination space is
+ * full, 409 `FILE_PROCESSING` while a video is still being processed. The code
+ * is at `err.details.code`.
+ */
+export function useFilestoreCopy() {
+  const ctx = useWidgetContextOrThrow("useFilestoreCopy");
+  if (
+    !ctx.filestore ||
+    !ctx.filestore.files ||
+    typeof ctx.filestore.files.copy !== "function"
+  ) {
+    throw new Error(
+      "useFilestoreCopy: host did not inject a filestore client (ctx.filestore.files.copy)",
+    );
+  }
+
+  const [copying, setCopying] = useState(false);
+  const [error, setError] = useState(null);
+  const [lastCopied, setLastCopied] = useState(null);
+
+  const ctxRef = useRef(ctx);
+  ctxRef.current = ctx;
+
+  const copy = useCallback(async (fileId, destination) => {
+    if (!fileId) throw new Error("useFilestoreCopy: fileId is required");
+    const { spaceType, folderId, name } = destination || {};
+    if (!spaceType) {
+      throw new Error("useFilestoreCopy: destination spaceType is required");
+    }
+    const ownerId = _filestoreOwnerId(ctxRef.current, spaceType);
+    if (!ownerId) {
+      const err = new Error("Sign in to copy files");
+      setError(err);
+      throw err;
+    }
+    const body = {
+      space_type: String(spaceType).toUpperCase(),
+      owner_id: ownerId,
+    };
+    if (folderId) body.folder_id = folderId;
+    if (name) body.name = name;
+    setCopying(true);
+    setError(null);
+    try {
+      const created = await ctxRef.current.filestore.files.copy(fileId, body);
+      setLastCopied(created || null);
+      setCopying(false);
+      return created;
+    } catch (err) {
+      setError(err);
+      setCopying(false);
+      throw err;
+    }
+  }, []);
+
+  return { copy, copying, error, lastCopied };
+}
+
 /**
  * Drive a BankID signing flow for one Filestore file. Returns
  * `{ status, qr, autoStartToken, message, signerName, signedAt, verdict,

package/dist/index.js

@@ -44,6 +44,8 @@ export {
   useFilestoreUpload,
   usePdfExport,
   useFilestoreFolders,
+  useFilestoreCreateFolder,
+  useFilestoreCopy,
   useFileSignature,
   useFileSignatures,
   useFileRoster,

package/dist/index.native.js

@@ -44,6 +44,8 @@ export {
   useFilestoreUpload,
   usePdfExport,
   useFilestoreFolders,
+  useFilestoreCreateFolder,
+  useFilestoreCopy,
   useFileSignature,
   useFileSignatures,
   useFileRoster,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.168.0",
+  "version": "0.169.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",