@colixsystems/widget-sdk 0.121.0 → 0.122.0

package/README.md

@@ -70,7 +70,18 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.119.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.122.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.122.0 (contract 1.94.0)
+
+**A refused filestore upload now says it is a PERMISSION problem (sc-6977).** `useFilestoreUpload` and `usePdfExport` relay whatever the destination decides, and that decision used to arrive as a bare `404 "Space not found"` no matter who asked. sc-5395 chose that masking for one good reason — an **anonymous** prober must not be able to enumerate which workspaces have opened their public space — but it applied to every caller, so a signed-in author uploading a cover image hit a dead end with nothing to act on.
+
+The refusal now splits along what the caller can already see:
+
+- **403** when the caller can READ the destination (the response body carries `code: "UPLOAD_NOT_PERMITTED"`, which the client puts on `err.details.code` — `err.code` is the client's own `"FORBIDDEN"`, so branch on `err.status`). The common case is a `public` space, which is world-readable but upload-**deny-by-default**: the workspace operator has to switch upload access on (Studio → File library → the space → upload access). Naming that discloses nothing the caller could not already see.
+- **404 `"Space not found"`** wherever saying more would leak: an anonymous caller, or a position hidden from this one (a restricted folder, a foreign `owner_id`, another tenant). A masked refusal carries no `code`.
+
+No hook signature moved, so nothing has to change to keep working — but a widget that branched on `404` alone should accept **both**, which is what the built-in Files widget now does. Folder creation and a folder move report the same split (`FOLDER_CREATE_NOT_PERMITTED` / `FOLDER_MOVE_NOT_PERMITTED`).
 
 ### What's new in 0.121.0 (contract 1.93.0)
 

package/dist/contract.cjs

@@ -896,8 +896,14 @@ const HOOKS = [
       "snake_case fields the backend reads verbatim (`space_type`, " +
       "`owner_id`, `folder_id`, plus the binary `file`), and POSTs through " +
       "ctx.filestore.files.upload. `upload(file, { folderId?, compress? })` " +
-      "resolves to the created file row or throws the wire error; a 404 " +
-      "means the destination folder denied a write (REQ-FSH canWrite gate). " +
+      "resolves to the created file row or throws the wire error. Branch " +
+      "on `err.status`: 403 means the destination denied the add and says " +
+      "so, because the caller can see that position — for a public space " +
+      "that means an operator has not switched upload access on yet; 404 " +
+      "means the position is hidden from the caller (or it is anonymous), " +
+      "so the refusal states no reason. Treat both as \"you can't upload " +
+      "here\". The server's `UPLOAD_NOT_PERMITTED` is at " +
+      "`err.details.code`; `err.code` is the client's own \"FORBIDDEN\". " +
       "Uploaded images are compressed to WebP by the backend; pass " +
       "`compress: false` (on the hook or per upload) to store the file " +
       "byte-for-byte as the user provided it — use that whenever the " +
@@ -927,8 +933,10 @@ const HOOKS = [
       "(`{ spaceType, folderId? }`); the hook resolves owner_id from the host " +
       "context and POSTs JSON through ctx.filestore.files.exportPdf. " +
       "`exportToPdf(html, { fileName?, folderId? })` resolves to the created " +
-      "file row (mime_type `application/pdf`) or throws the wire error; a 404 " +
-      "means the destination folder denied a write, a 413 that the rendered " +
+      "file row (mime_type `application/pdf`) or throws the wire error; " +
+      "`err.status` 403/404 means the destination denied the add (403 " +
+      "when the caller can see the position, 404 when it cannot), a 413 " +
+      "that the rendered " +
       "PDF exceeded the size cap. The HTML is rendered by the host's PDF " +
       "service (headless Chromium) — the SAME server-side pipeline on the web " +
       "Player and the native export, so no browser-only PDF library is used.",
@@ -3603,7 +3611,17 @@ const CONTRACT = deepFreeze({
   //    JOINED to the page refuses it. An app that colours its rail or bar
   //    explicitly is untouched; an app that themed NOTHING moves from
   //    `#ffffff` to the `#f8fafc` its page already was.
-  version: "1.93.0",
+  // 1.94.0: behavioural (sc-6977) -- a filestore destination that refuses an
+  //    ADD now answers 403 with `code: UPLOAD_NOT_PERMITTED` when the caller
+  //    can already READ that position, and keeps the bare 404 only where
+  //    saying more would disclose something: an anonymous caller (sc-5395's
+  //    guarantee that a prober cannot enumerate which workspaces opened their
+  //    public space) or a position hidden from the caller. Affects
+  //    `useFilestoreUpload` and `usePdfExport`; no signature moved, but a
+  //    widget that branched on 404 alone should accept both, and the actionable
+  //    case -- a public space whose upload access is still off -- is now
+  //    distinguishable instead of arriving as a bare "Space not found".
+  version: "1.94.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -896,8 +896,14 @@ const HOOKS = [
       "snake_case fields the backend reads verbatim (`space_type`, " +
       "`owner_id`, `folder_id`, plus the binary `file`), and POSTs through " +
       "ctx.filestore.files.upload. `upload(file, { folderId?, compress? })` " +
-      "resolves to the created file row or throws the wire error; a 404 " +
-      "means the destination folder denied a write (REQ-FSH canWrite gate). " +
+      "resolves to the created file row or throws the wire error. Branch " +
+      "on `err.status`: 403 means the destination denied the add and says " +
+      "so, because the caller can see that position — for a public space " +
+      "that means an operator has not switched upload access on yet; 404 " +
+      "means the position is hidden from the caller (or it is anonymous), " +
+      "so the refusal states no reason. Treat both as \"you can't upload " +
+      "here\". The server's `UPLOAD_NOT_PERMITTED` is at " +
+      "`err.details.code`; `err.code` is the client's own \"FORBIDDEN\". " +
       "Uploaded images are compressed to WebP by the backend; pass " +
       "`compress: false` (on the hook or per upload) to store the file " +
       "byte-for-byte as the user provided it — use that whenever the " +
@@ -927,8 +933,10 @@ const HOOKS = [
       "(`{ spaceType, folderId? }`); the hook resolves owner_id from the host " +
       "context and POSTs JSON through ctx.filestore.files.exportPdf. " +
       "`exportToPdf(html, { fileName?, folderId? })` resolves to the created " +
-      "file row (mime_type `application/pdf`) or throws the wire error; a 404 " +
-      "means the destination folder denied a write, a 413 that the rendered " +
+      "file row (mime_type `application/pdf`) or throws the wire error; " +
+      "`err.status` 403/404 means the destination denied the add (403 " +
+      "when the caller can see the position, 404 when it cannot), a 413 " +
+      "that the rendered " +
       "PDF exceeded the size cap. The HTML is rendered by the host's PDF " +
       "service (headless Chromium) — the SAME server-side pipeline on the web " +
       "Player and the native export, so no browser-only PDF library is used.",
@@ -3603,7 +3611,17 @@ const CONTRACT = deepFreeze({
   //    JOINED to the page refuses it. An app that colours its rail or bar
   //    explicitly is untouched; an app that themed NOTHING moves from
   //    `#ffffff` to the `#f8fafc` its page already was.
-  version: "1.93.0",
+  // 1.94.0: behavioural (sc-6977) -- a filestore destination that refuses an
+  //    ADD now answers 403 with `code: UPLOAD_NOT_PERMITTED` when the caller
+  //    can already READ that position, and keeps the bare 404 only where
+  //    saying more would disclose something: an anonymous caller (sc-5395's
+  //    guarantee that a prober cannot enumerate which workspaces opened their
+  //    public space) or a position hidden from the caller. Affects
+  //    `useFilestoreUpload` and `usePdfExport`; no signature moved, but a
+  //    widget that branched on 404 alone should accept both, and the actionable
+  //    case -- a public space whose upload access is still off -- is now
+  //    distinguishable instead of arriving as a bare "Space not found".
+  version: "1.94.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -3203,9 +3203,14 @@ export function useFilestoreFile(fileId) {
  * on web). FormData serialises both verbatim, so the same hook code path
  * feeds the multipart on both platforms.
  *
- * A 404 from the backend means the destination folder denied a write —
- * the widget should surface a friendly "you can't upload here" message
- * rather than the raw error.
+ * The destination can refuse the add two ways (sc-6977). BRANCH ON
+ * `err.status`: 403 means the caller may know why — most often a public space
+ * whose upload access an operator has not switched on — and 404 means the
+ * position is hidden from it (or it is anonymous), so the refusal states no
+ * reason. Treat both as "you can't upload here" rather than showing the raw
+ * error. NOT `err.status === 403 && err.code === "UPLOAD_NOT_PERMITTED"`:
+ * `err.code` is the CLIENT's taxonomy ("FORBIDDEN"), and the server's
+ * `UPLOAD_NOT_PERMITTED` arrives at `err.details.code`.
  */
 export function useFilestoreUpload(options) {
   const ctx = useWidgetContextOrThrow("useFilestoreUpload");
@@ -3291,8 +3296,10 @@ export function useFilestoreUpload(options) {
  * so the capability behaves identically on both platforms (no browser-only PDF
  * library is involved).
  *
- * A 404 means the destination folder denied a write; a 413 means the rendered
- * PDF exceeded the size cap.
+ * A 403 or 404 means the destination denied the add — 403 when the caller can
+ * see that position, 404 when it cannot; a 413 means the rendered PDF exceeded
+ * the size cap. Branch on `err.status`; the server's `UPLOAD_NOT_PERMITTED` is
+ * at `err.details.code`, not `err.code` (which is the client's "FORBIDDEN").
  */
 export function usePdfExport(options) {
   const ctx = useWidgetContextOrThrow("usePdfExport");

package/package.json

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