@colixsystems/widget-sdk 0.99.0 → 0.100.0

package/README.md

@@ -99,6 +99,20 @@ Host-integration surface only: no author-facing hook, prop, primitive, or manife
 
 Host-integration surface only: no author-facing hook, prop, primitive, or manifest field changed. `CONTRACT.version` → `1.66.0`.
 
+### What's new in 0.100.0 (contract 1.74.0)
+
+**Opt out of image compression on upload — `useFilestoreUpload({ compress })` (sc-5402).** A file uploaded through `POST /api/v1/filestore/files` now has its raster images compressed to WebP again (EXIF-stripped, longest edge capped at 4096 px), which is the right default for anything the app renders. When the ORIGINAL bytes matter — a document archive, a photo the user re-downloads, anything with an exact-bytes requirement — pass `compress: false`, either on the hook or per call:
+
+```js
+const { upload } = useFilestoreUpload({ spaceType: 'personal', compress: false });
+// …or per upload, which wins over the hook default:
+await upload(file, { compress: false });
+```
+
+Only raster images are ever compressed. SVG keeps its vector, and video, audio, and documents are stored verbatim under both values — an upload is never queued for background transcoding. The opt-out is the only value put on the wire, so the backend stays the single source of the default.
+
+`CONTRACT.version` → `1.74.0`. Additive — existing callers are byte-for-byte unchanged on the wire.
+
 ### What's new in 0.98.0 (contract 1.70.0)
 
 **Three new hooks close the biggest gaps in the write-gating and query-authoring surface (sc-5206).**
@@ -640,7 +654,7 @@ Also: `useFileSignatures(fileIds)` is now **self-scoped** (the caller's own sign
 - `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.
 - `useFilestoreFile(fileId)` → `{ file, url, 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.
-- `useFilestoreUpload({ spaceType, folderId? })` → `{ 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. Pair with the `<FilePicker>` primitive for the visible trigger. Requires the `files.write:*` scope.
+- `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).
 
 `CONTRACT.version` → `1.20.0` (additive — no existing hook changed).

package/dist/contract.cjs

@@ -786,16 +786,21 @@ const HOOKS = [
   },
   {
     name: "useFilestoreUpload",
-    signature: "useFilestoreUpload({ spaceType, folderId? })",
+    signature: "useFilestoreUpload({ spaceType, folderId?, compress? })",
     description:
       "Upload a file into the end-user's Filestore space. The widget passes " +
       "the SPACE (`{ spaceType, folderId? }`); the hook resolves owner_id " +
       "from the host context, builds a multipart FormData with the " +
       "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? })` resolves " +
-      "to the created file row or throws the wire error; a 404 means the " +
-      "destination folder denied a write (REQ-FSH canWrite gate). " +
+      "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). " +
+      "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 " +
+      "ORIGINAL matters (a document archive, a photo the user re-downloads, " +
+      "anything with an exact-bytes requirement). " +
       "ALWAYS pass spaceType explicitly — omitting it falls back to " +
       "'project', which is unreadable by a logged-out visitor. Choose it by " +
       "who must SEE the file: 'public' for content the app displays to " +
@@ -803,7 +808,7 @@ const HOOKS = [
       "'project' for content restricted to signed-in workspace users, " +
       "'personal' for a file private to the uploading app user.",
     returnShape: {
-      upload: "(file, { folderId? }) => Promise<FilestoreFile>",
+      upload: "(file, { folderId?, compress? }) => Promise<FilestoreFile>",
       uploading: "boolean",
       error: "Error | null",
       lastUploaded: "FilestoreFile | null",
@@ -3199,7 +3204,12 @@ const CONTRACT = deepFreeze({
   //    `ctx.datastore.myPermissions` client method as a write-permission
   //    FLOOR, replacing the previous prompt-only "read useUser().groupIds /
   //    .roles" guidance. No existing export changed signature.
-  version: "1.73.0",
+  // 1.74.0: additive (sc-5402) — `useFilestoreUpload` accepts `compress`, on
+  //    the hook options and per `upload(file, { compress })`. Uploaded images
+  //    are compressed to WebP by default; `compress: false` stores the file
+  //    byte-for-byte. Existing callers are unaffected — the field is only sent
+  //    when the opt-out is chosen.
+  version: "1.74.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -786,16 +786,21 @@ const HOOKS = [
   },
   {
     name: "useFilestoreUpload",
-    signature: "useFilestoreUpload({ spaceType, folderId? })",
+    signature: "useFilestoreUpload({ spaceType, folderId?, compress? })",
     description:
       "Upload a file into the end-user's Filestore space. The widget passes " +
       "the SPACE (`{ spaceType, folderId? }`); the hook resolves owner_id " +
       "from the host context, builds a multipart FormData with the " +
       "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? })` resolves " +
-      "to the created file row or throws the wire error; a 404 means the " +
-      "destination folder denied a write (REQ-FSH canWrite gate). " +
+      "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). " +
+      "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 " +
+      "ORIGINAL matters (a document archive, a photo the user re-downloads, " +
+      "anything with an exact-bytes requirement). " +
       "ALWAYS pass spaceType explicitly — omitting it falls back to " +
       "'project', which is unreadable by a logged-out visitor. Choose it by " +
       "who must SEE the file: 'public' for content the app displays to " +
@@ -803,7 +808,7 @@ const HOOKS = [
       "'project' for content restricted to signed-in workspace users, " +
       "'personal' for a file private to the uploading app user.",
     returnShape: {
-      upload: "(file, { folderId? }) => Promise<FilestoreFile>",
+      upload: "(file, { folderId?, compress? }) => Promise<FilestoreFile>",
       uploading: "boolean",
       error: "Error | null",
       lastUploaded: "FilestoreFile | null",
@@ -3199,7 +3204,12 @@ const CONTRACT = deepFreeze({
   //    `ctx.datastore.myPermissions` client method as a write-permission
   //    FLOOR, replacing the previous prompt-only "read useUser().groupIds /
   //    .roles" guidance. No existing export changed signature.
-  version: "1.73.0",
+  // 1.74.0: additive (sc-5402) — `useFilestoreUpload` accepts `compress`, on
+  //    the hook options and per `upload(file, { compress })`. Uploaded images
+  //    are compressed to WebP by default; `compress: false` stores the file
+  //    byte-for-byte. Existing callers are unaffected — the field is only sent
+  //    when the opt-out is chosen.
+  version: "1.74.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -2801,7 +2801,11 @@ export function useFilestoreUpload(options) {
       "useFilestoreUpload: host did not inject a filestore client (ctx.filestore.files.upload)",
     );
   }
-  const { spaceType = "project", folderId: defaultFolderId = null } = options || {};
+  const {
+    spaceType = "project",
+    folderId: defaultFolderId = null,
+    compress: defaultCompress = true,
+  } = options || {};
   const ownerId = _filestoreOwnerId(ctx, spaceType);
 
   const [uploading, setUploading] = useState(false);
@@ -2823,10 +2827,17 @@ export function useFilestoreUpload(options) {
         overrides && Object.prototype.hasOwnProperty.call(overrides, "folderId")
           ? overrides.folderId
           : defaultFolderId;
+      const compress =
+        overrides && Object.prototype.hasOwnProperty.call(overrides, "compress")
+          ? overrides.compress
+          : defaultCompress;
       const form = new FormData();
       form.append("space_type", String(spaceType || "project").toUpperCase());
       form.append("owner_id", ownerId);
       if (folderId) form.append("folder_id", folderId);
+      // sc-5402: only the opt-out is sent, so the backend stays the single
+      // source of the default (it compresses images to WebP).
+      if (compress === false) form.append("compress", "false");
       form.append("file", file);
       setUploading(true);
       setError(null);
@@ -2841,7 +2852,7 @@ export function useFilestoreUpload(options) {
         throw err;
       }
     },
-    [ownerId, defaultFolderId, spaceType],
+    [ownerId, defaultFolderId, defaultCompress, spaceType],
   );
 
   return { upload, uploading, error, lastUploaded };

package/package.json

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