@colixsystems/widget-sdk 0.220.0 → 0.221.1

package/README.md

@@ -84,7 +84,26 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.220.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.221.1` — 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.221.1 (contract 1.177.1)
+
+**`useFileSignature`: one failed poll no longer outlives the next answer.** `error` is the last call that failed, and a `refresh()` or `verify()` that succeeds now clears it. While `status` is `'pending'` an `error` means a poll failed: keep polling and keep showing the order. Fix only; nothing was added or removed.
+
+### What's new in 0.221.0 (contract 1.177.0)
+
+**A row's file goes in the row's record space, and `upload()` names the record per call.** A file a widget keeps in a `FILE` column belongs in that row's `record` space: exactly the people who may read the row may read the file, so a private table's attachments stay private, and a table that lets everyone read still serves them to logged-out visitors. A `public` file, by contrast, is readable by anyone holding its link whatever the table's permissions say. A row must exist before a file can be attached to it, and a create form only learns the new row's id inside its submit handler, after the hook rendered. So `upload(file, { recordId })` now takes the record per call, the way it already took `folderId`:
+
+```js
+const { create, update } = useDatastoreMutation(tableId);
+const { upload } = useFilestoreUpload({ spaceType: "record" });
+
+const row = await create({ Title: title });            // without the file
+const stored = await upload(file, { recordId: row.id }); // into that row's space
+await update(row.id, { Receipt: stored.id });
+```
+
+A per-call `recordId` wins over the hook's; outside a `record` space it is ignored. A record upload that names no record now rejects with `useFilestoreUpload: a record space needs a recordId` instead of the misleading `Sign in to upload`. A logged-out visitor cannot upload into a record space, so ask them to sign in to attach a file. `useCamera()` and `useImageEditor()` now point at `useFilestoreUpload` for the upload: their descriptions named `ctx.assets.upload`, which widget code cannot reach. Additive.
 
 ### What's new in 0.220.0 (contract 1.176.0)
 
@@ -1496,9 +1515,7 @@ const { edit } = useImageEditor();
 const shot = await capture();
 const small = await edit(shot.uri, [{ resize: { width: 800 } }], { format: "jpeg", compress: 0.8 });
 
-const fd = new FormData();
-fd.append("file", small.file);
-await ctx.assets.upload(fd);
+await upload(small.file); // upload from useFilestoreUpload()
 ```
 
 `edit(uri, actions, options?)` applies `actions` in order and resolves the SAME normalised asset shape `useCamera()` yields, so capture → edit → upload is one code path on both hosts. Actions are `{ resize: { width?, height? } }`, `{ crop: { originX, originY, width, height } }`, `{ rotate: degrees }` and `{ flip: "horizontal" | "vertical" }`; output is `{ format: "jpeg" | "png" | "webp", compress, base64? }`.
@@ -1712,12 +1729,10 @@ When you take the `useCanWrite`-only route, omit the USER column for a guest (`i
 
 **Dismissing the picker resolves `null`, not an error.** Backing out is the most common outcome, so it is deliberately not a rejection — your happy path needs no `try/catch`. A genuine failure (permission refused, no host broker) rejects with a structured `CameraError` (new named export) carrying a stable `.code` (`PERMISSION_DENIED` / `UNSUPPORTED` / `INTERNAL`).
 
-**One upload path on both hosts.** The resolved asset is normalised to `{ uri, name, mimeType, width, height, size, file }`, where `uri` is directly displayable (`<Image source={{ uri }} />`) and `file` is already the right upload part for the platform — a browser `File` on web, expo-file-system's `File` on native. (Never React Native's legacy `{ uri, name, type }` part: the native host streams the file off disk, and Expo's fetch rejects that part outright anyway. Do not branch on the part's type — an expo-file-system `File` is NOT `instanceof Blob` at runtime.) So the same three lines work everywhere:
+**One upload path on both hosts.** The resolved asset is normalised to `{ uri, name, mimeType, width, height, size, file }`, where `uri` is directly displayable (`<Image source={{ uri }} />`) and `file` is already the right upload part for the platform — a browser `File` on web, expo-file-system's `File` on native. (Never React Native's legacy `{ uri, name, type }` part: the native host streams the file off disk, and Expo's fetch rejects that part outright anyway. Do not branch on the part's type — an expo-file-system `File` is NOT `instanceof Blob` at runtime.) So the same line works everywhere:
 
 ```js
-const fd = new FormData();
-fd.append("file", asset.file);
-await ctx.assets.upload(fd);
+await upload(asset.file); // upload from useFilestoreUpload()
 ```
 
 `options` (`{ allowsEditing, quality }`) are **hints**: the Expo export applies both, the web camera applies `quality` only — so never depend on a cropped result. `reset()` clears the asset and releases it (on web that revokes the blob URL, which otherwise leaks for the life of the document). **Gate your camera button on `supported`** — a host that brokers no camera reports `false` rather than throwing. The web Player brokers it via `getUserMedia` — a live preview with a shutter — on every web host: it is the only camera a DESKTOP browser will open, and a phone reaches the same preview rather than its own camera app. It falls back to a file input (`capture="environment"`) only where getUserMedia is absent up front: an insecure origin or an older browser. Once the permission prompt has been shown the user gesture is spent, so a camera that then fails to open rejects (`PERMISSION_DENIED` if refused, `UNSUPPORTED` if there is no usable device) rather than falling back to a file dialog the browser would refuse to open. The Expo export uses `expo-image-picker`, whose config plugin declares the camera and photo-library permissions the runtime needs.

package/dist/contract.cjs

@@ -1369,7 +1369,7 @@ const HOOKS = [
       "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?, compress?, fileName? })` " +
+      "ctx.filestore.files.upload. `upload(file, { folderId?, recordId?, compress?, fileName? })` " +
       "resolves to the created file row or throws the wire error. `file` must be a BLOB — a browser File on web, " +
       "expo-file-system's File on native (what FilePicker / useCamera / useImageEditor hand back); Expo's fetch rejects " +
       "React Native's legacy { uri, name, type } part with \"Unsupported FormDataPart implementation\". The stored name " +
@@ -1387,13 +1387,20 @@ const HOOKS = [
       "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 " +
-      "anyone browsing (product, catalogue, gallery, cover images), " +
-      "'project' for content restricted to signed-in workspace users, " +
-      "'personal' for a file private to the uploading app user.",
+      "'project', which is unreadable by a logged-out visitor. A file that " +
+      "belongs to a datastore row — anything stored in a FILE column — goes " +
+      "in that row's 'record' space, so exactly the people who may read the " +
+      "row may read the file (logged-out visitors too, when the table lets " +
+      "everyone read). A file can only be attached to a row that exists: " +
+      "create the row, call upload(file, { recordId: row.id }) — the per-call " +
+      "recordId names the row the hook could not know at render — then write " +
+      "the returned id into the FILE column with update(). A logged-out " +
+      "visitor cannot upload into a record space. For a file that belongs to " +
+      "no row: 'public' for content the app shows to anyone browsing, " +
+      "'project' for signed-in workspace users only, 'personal' for a file " +
+      "private to the uploading app user.",
     returnShape: {
-      upload: "(file, { folderId?, compress?, fileName? }) => Promise<FilestoreFile>",
+      upload: "(file, { folderId?, recordId?, compress?, fileName? }) => Promise<FilestoreFile>",
       uploading: "boolean",
       error: "Error | null",
       lastUploaded: "FilestoreFile | null",
@@ -1552,7 +1559,10 @@ const HOOKS = [
       "be cancelled. cancel() resolves to what became of the order, which is " +
       "then still pending or already complete: read status after it, never " +
       "assume 'cancelled'. nameRefusal is set when the order failed because " +
-      "the signer's name cannot be shown on the document. Reads " +
+      "the signer's name cannot be shown on the document. error is the last " +
+      "call that failed, and a refresh() or verify() that succeeds clears it: " +
+      "while status is 'pending' an error means one poll failed, so keep " +
+      "polling and keep showing the order. Reads " +
       "ctx.filestore.signatures.{initiate,status,cancel,verify}.",
     returnShape: {
       status: "'pending' | 'complete' | 'failed' | 'cancelled' | null",
@@ -2818,8 +2828,8 @@ const HOOKS = [
       "common case and is deliberately NOT an error, so no try/catch is needed on the happy path. They reject with a " +
       "CameraError whose .code is one of PERMISSION_DENIED | UNSUPPORTED | INTERNAL. `asset.file` is already the right " +
       "upload part for the host — a BLOB on both (a File on web, expo-file-system's File on native), because Expo's fetch " +
-      "implements the web FormData spec and rejects React Native's legacy { uri, name, type } part outright: append it to a FormData as `file` and pass " +
-      "that to ctx.assets.upload(fd) — one code path on both platforms. reset() clears the asset and releases it. Check " +
+      "implements the web FormData spec and rejects React Native's legacy { uri, name, type } part outright: pass it " +
+      "straight to upload(asset.file) from useFilestoreUpload — one code path on both platforms. reset() clears the asset and releases it. Check " +
       "`supported` before rendering a camera button. options: { allowsEditing, quality } are HINTS the host honours where it " +
       "can — the Expo export applies both, the web camera applies quality only, so never depend on a cropped result. " +
       "Behaviour is otherwise identical on web (a getUserMedia preview on EVERY host, phones included; a file input " +
@@ -2885,7 +2895,7 @@ const HOOKS = [
       "Editing is IMPERATIVE — call edit() from an event handler, never during render. " +
       "edit(uri, actions, options?) applies `actions` IN ORDER and resolves the SAME normalised asset shape useCamera() " +
       "yields — { uri, name, mimeType, width, height, size, base64?, file } — so capture -> edit -> upload is ONE code path: " +
-      "append result.file to a FormData as `file` and pass it to ctx.assets.upload(fd). " +
+      "pass result.file to upload() from useFilestoreUpload. " +
       "Each action entry carries exactly one of { resize: { width?, height? } } (aspect preserved when only one is given), " +
       "{ crop: { originX, originY, width, height } }, { rotate: degrees } (positive is clockwise), or " +
       "{ flip: \"horizontal\" | \"vertical\" }. A crop rect must lie INSIDE the surface the earlier actions produced, and " +
@@ -3022,7 +3032,7 @@ const PRIMITIVES = [
   },
   // sc-1378 — `<FilePicker accept onPick>` lets a widget surface a native
   // file-picker on the web Player so end users can upload files to the
-  // backend (paired with useFilestoreUpload or useAssets.upload). Web wraps
+  // backend (paired with useFilestoreUpload). Web wraps
   // a hidden DOM `<input type="file">`; native renders a disabled trigger
   // and exposes `FilePicker.isSupported = false` until a vetted Expo
   // picker pin lands.
@@ -5856,7 +5866,15 @@ const CONTRACT = deepFreeze({
   //    a widget never receives it. `account`'s photo actions are now
   //    optional members, and `user.email` is documented as nullable: an
   //    account without an email has none.
-  version: "1.176.0",
+  // 1.177.0: additive (sc-10937) — `useFilestoreUpload().upload(file,
+  //    { recordId })` names the record per call, so a widget can create a row
+  //    and attach to it in one handler. A FILE column's file goes in its
+  //    row's record space; useCamera / useImageEditor point at
+  //    useFilestoreUpload, since widget code cannot reach ctx.assets.
+  // 1.177.1: fix (sc-10410) — a `refresh()` or `verify()` that succeeds
+  //    clears `useFileSignature`'s `error`; it used to keep one failed poll's
+  //    error for the rest of the order.
+  version: "1.177.1",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1369,7 +1369,7 @@ const HOOKS = [
       "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?, compress?, fileName? })` " +
+      "ctx.filestore.files.upload. `upload(file, { folderId?, recordId?, compress?, fileName? })` " +
       "resolves to the created file row or throws the wire error. `file` must be a BLOB — a browser File on web, " +
       "expo-file-system's File on native (what FilePicker / useCamera / useImageEditor hand back); Expo's fetch rejects " +
       "React Native's legacy { uri, name, type } part with \"Unsupported FormDataPart implementation\". The stored name " +
@@ -1387,13 +1387,20 @@ const HOOKS = [
       "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 " +
-      "anyone browsing (product, catalogue, gallery, cover images), " +
-      "'project' for content restricted to signed-in workspace users, " +
-      "'personal' for a file private to the uploading app user.",
+      "'project', which is unreadable by a logged-out visitor. A file that " +
+      "belongs to a datastore row — anything stored in a FILE column — goes " +
+      "in that row's 'record' space, so exactly the people who may read the " +
+      "row may read the file (logged-out visitors too, when the table lets " +
+      "everyone read). A file can only be attached to a row that exists: " +
+      "create the row, call upload(file, { recordId: row.id }) — the per-call " +
+      "recordId names the row the hook could not know at render — then write " +
+      "the returned id into the FILE column with update(). A logged-out " +
+      "visitor cannot upload into a record space. For a file that belongs to " +
+      "no row: 'public' for content the app shows to anyone browsing, " +
+      "'project' for signed-in workspace users only, 'personal' for a file " +
+      "private to the uploading app user.",
     returnShape: {
-      upload: "(file, { folderId?, compress?, fileName? }) => Promise<FilestoreFile>",
+      upload: "(file, { folderId?, recordId?, compress?, fileName? }) => Promise<FilestoreFile>",
       uploading: "boolean",
       error: "Error | null",
       lastUploaded: "FilestoreFile | null",
@@ -1552,7 +1559,10 @@ const HOOKS = [
       "be cancelled. cancel() resolves to what became of the order, which is " +
       "then still pending or already complete: read status after it, never " +
       "assume 'cancelled'. nameRefusal is set when the order failed because " +
-      "the signer's name cannot be shown on the document. Reads " +
+      "the signer's name cannot be shown on the document. error is the last " +
+      "call that failed, and a refresh() or verify() that succeeds clears it: " +
+      "while status is 'pending' an error means one poll failed, so keep " +
+      "polling and keep showing the order. Reads " +
       "ctx.filestore.signatures.{initiate,status,cancel,verify}.",
     returnShape: {
       status: "'pending' | 'complete' | 'failed' | 'cancelled' | null",
@@ -2818,8 +2828,8 @@ const HOOKS = [
       "common case and is deliberately NOT an error, so no try/catch is needed on the happy path. They reject with a " +
       "CameraError whose .code is one of PERMISSION_DENIED | UNSUPPORTED | INTERNAL. `asset.file` is already the right " +
       "upload part for the host — a BLOB on both (a File on web, expo-file-system's File on native), because Expo's fetch " +
-      "implements the web FormData spec and rejects React Native's legacy { uri, name, type } part outright: append it to a FormData as `file` and pass " +
-      "that to ctx.assets.upload(fd) — one code path on both platforms. reset() clears the asset and releases it. Check " +
+      "implements the web FormData spec and rejects React Native's legacy { uri, name, type } part outright: pass it " +
+      "straight to upload(asset.file) from useFilestoreUpload — one code path on both platforms. reset() clears the asset and releases it. Check " +
       "`supported` before rendering a camera button. options: { allowsEditing, quality } are HINTS the host honours where it " +
       "can — the Expo export applies both, the web camera applies quality only, so never depend on a cropped result. " +
       "Behaviour is otherwise identical on web (a getUserMedia preview on EVERY host, phones included; a file input " +
@@ -2885,7 +2895,7 @@ const HOOKS = [
       "Editing is IMPERATIVE — call edit() from an event handler, never during render. " +
       "edit(uri, actions, options?) applies `actions` IN ORDER and resolves the SAME normalised asset shape useCamera() " +
       "yields — { uri, name, mimeType, width, height, size, base64?, file } — so capture -> edit -> upload is ONE code path: " +
-      "append result.file to a FormData as `file` and pass it to ctx.assets.upload(fd). " +
+      "pass result.file to upload() from useFilestoreUpload. " +
       "Each action entry carries exactly one of { resize: { width?, height? } } (aspect preserved when only one is given), " +
       "{ crop: { originX, originY, width, height } }, { rotate: degrees } (positive is clockwise), or " +
       "{ flip: \"horizontal\" | \"vertical\" }. A crop rect must lie INSIDE the surface the earlier actions produced, and " +
@@ -3022,7 +3032,7 @@ const PRIMITIVES = [
   },
   // sc-1378 — `<FilePicker accept onPick>` lets a widget surface a native
   // file-picker on the web Player so end users can upload files to the
-  // backend (paired with useFilestoreUpload or useAssets.upload). Web wraps
+  // backend (paired with useFilestoreUpload). Web wraps
   // a hidden DOM `<input type="file">`; native renders a disabled trigger
   // and exposes `FilePicker.isSupported = false` until a vetted Expo
   // picker pin lands.
@@ -5852,7 +5862,15 @@ const CONTRACT = deepFreeze({
   //    a widget never receives it. `account`'s photo actions are now
   //    optional members, and `user.email` is documented as nullable: an
   //    account without an email has none.
-  version: "1.176.0",
+  // 1.177.0: additive (sc-10937) — `useFilestoreUpload().upload(file,
+  //    { recordId })` names the record per call, so a widget can create a row
+  //    and attach to it in one handler. A FILE column's file goes in its
+  //    row's record space; useCamera / useImageEditor point at
+  //    useFilestoreUpload, since widget code cannot reach ctx.assets.
+  // 1.177.1: fix (sc-10410) — a `refresh()` or `verify()` that succeeds
+  //    clears `useFileSignature`'s `error`; it used to keep one failed poll's
+  //    error for the rest of the order.
+  version: "1.177.1",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -4700,7 +4700,10 @@ export function useFilestoreFile(fileId) {
  * same way the read hooks do (tenant for PROJECT, app user for PERSONAL, the
  * record for RECORD) and posts a multipart FormData to `ctx.filestore.files.upload`.
  *
- * `upload(file, { folderId?, fileName? })` takes a browser `File` on the web
+ * sc-10937: `upload(file, { recordId })` names the record per call, so a
+ * widget can create a row and attach to it in the same handler.
+ *
+ * `upload(file, { folderId?, recordId?, fileName? })` takes a browser `File` on the web
  * Player and expo-file-system's `File` on the Expo export, as `<FilePicker>`,
  * `useCamera()` and `useImageEditor()` all hand back. Never React Native's
  * legacy `{ uri, name, type }` part: the native host streams the file off
@@ -4734,7 +4737,8 @@ export function useFilestoreUpload(options) {
     folderId: defaultFolderId = null,
     compress: defaultCompress = true,
   } = options || {};
-  const ownerId = _filestoreOwnerId(ctx, spaceType, recordId);
+  const isRecordSpace = String(spaceType || "project").toUpperCase() === "RECORD";
+  const defaultOwnerId = _filestoreOwnerId(ctx, spaceType, recordId);
 
   const [uploading, setUploading] = useState(false);
   const [error, setError] = useState(null);
@@ -4746,19 +4750,25 @@ export function useFilestoreUpload(options) {
   const upload = useCallback(
     async (file, overrides) => {
       if (!file) throw new Error("useFilestoreUpload: file is required");
+      const hasOverride = (key) =>
+        Boolean(overrides) && Object.prototype.hasOwnProperty.call(overrides, key);
+      const ownerId =
+        isRecordSpace && hasOverride("recordId")
+          ? overrides.recordId || null
+          : defaultOwnerId;
+      if (isRecordSpace && !ownerId) {
+        // Not "Sign in": the widget forgot which row to attach to.
+        const err = new Error("useFilestoreUpload: a record space needs a recordId");
+        setError(err);
+        throw err;
+      }
       if (!ownerId) {
         const err = new Error("Sign in to upload");
         setError(err);
         throw err;
       }
-      const folderId =
-        overrides && Object.prototype.hasOwnProperty.call(overrides, "folderId")
-          ? overrides.folderId
-          : defaultFolderId;
-      const compress =
-        overrides && Object.prototype.hasOwnProperty.call(overrides, "compress")
-          ? overrides.compress
-          : defaultCompress;
+      const folderId = hasOverride("folderId") ? overrides.folderId : defaultFolderId;
+      const compress = hasOverride("compress") ? overrides.compress : defaultCompress;
       const form = new FormData();
       form.append("space_type", String(spaceType || "project").toUpperCase());
       form.append("owner_id", ownerId);
@@ -4800,7 +4810,7 @@ export function useFilestoreUpload(options) {
         throw err;
       }
     },
-    [ownerId, defaultFolderId, defaultCompress, spaceType],
+    [defaultOwnerId, isRecordSpace, defaultFolderId, defaultCompress, spaceType],
   );
 
   return { upload, uploading, error, lastUploaded };

package/dist/index.d.ts

@@ -2452,7 +2452,7 @@ export interface CameraAsset {
   /**
    * Ready-to-upload part — a Blob on both hosts: a `File` on web,
    * expo-file-system's `File` on native. Expo's fetch rejects any other shape.
-   * Append it to a FormData and hand that to `ctx.assets.upload(...)`.
+   * Pass it to `upload(file)` from `useFilestoreUpload`.
    */
   file: unknown;
 }

package/dist/signing-hooks.js

@@ -40,7 +40,9 @@ const userIdOf = (ctx) => (ctx.user && ctx.user.id) || "";
  * with `hintCode: "sealing"`. `hintCode` is where the order stands;
  * `nameRefusal` (`{ reason, characters }`) is set when it failed because the
  * signer's name cannot be shown. `autoStartToken` is set only while opening
- * BankID can still help. Reads
+ * BankID can still help. `error` is the last call that failed; a `refresh()`
+ * or `verify()` that succeeds clears it, so one failed poll does not outlive
+ * the next answer. Reads
  * `ctx.filestore.signatures.{initiate,status,cancel,verify}`. When `fileId` is
  * null/empty the hook collapses to a no-op.
  *
@@ -128,7 +130,8 @@ export function useFileSignature(fileId, existingSignatureId = null) {
       const res = await sigRef.current.status(id);
       // A cancel or a new order since this poll was sent: its answer is old news.
       if (answersRef.current !== asked) return;
-      apply(forScope, (base) => ({ order: signOrderStateAfterAnswer(base.order, res) }));
+      // An answer means the order can be reached again: an earlier failure is over.
+      apply(forScope, (base) => ({ order: signOrderStateAfterAnswer(base.order, res), error: null }));
     } catch (err) {
       if (answersRef.current !== asked) return;
       apply(forScope, () => ({ error: toPermissionError(err) }));
@@ -156,7 +159,7 @@ export function useFileSignature(fileId, existingSignatureId = null) {
     if (!id) return null;
     try {
       const v = await sigRef.current.verify(id);
-      apply(forScope, () => ({ verdict: v }));
+      apply(forScope, () => ({ verdict: v, error: null }));
       return v;
     } catch (err) {
       const refusal = toPermissionError(err);

package/package.json

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

package/src/contract.js

@@ -1369,7 +1369,7 @@ const HOOKS = [
       "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?, compress?, fileName? })` " +
+      "ctx.filestore.files.upload. `upload(file, { folderId?, recordId?, compress?, fileName? })` " +
       "resolves to the created file row or throws the wire error. `file` must be a BLOB — a browser File on web, " +
       "expo-file-system's File on native (what FilePicker / useCamera / useImageEditor hand back); Expo's fetch rejects " +
       "React Native's legacy { uri, name, type } part with \"Unsupported FormDataPart implementation\". The stored name " +
@@ -1387,13 +1387,20 @@ const HOOKS = [
       "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 " +
-      "anyone browsing (product, catalogue, gallery, cover images), " +
-      "'project' for content restricted to signed-in workspace users, " +
-      "'personal' for a file private to the uploading app user.",
+      "'project', which is unreadable by a logged-out visitor. A file that " +
+      "belongs to a datastore row — anything stored in a FILE column — goes " +
+      "in that row's 'record' space, so exactly the people who may read the " +
+      "row may read the file (logged-out visitors too, when the table lets " +
+      "everyone read). A file can only be attached to a row that exists: " +
+      "create the row, call upload(file, { recordId: row.id }) — the per-call " +
+      "recordId names the row the hook could not know at render — then write " +
+      "the returned id into the FILE column with update(). A logged-out " +
+      "visitor cannot upload into a record space. For a file that belongs to " +
+      "no row: 'public' for content the app shows to anyone browsing, " +
+      "'project' for signed-in workspace users only, 'personal' for a file " +
+      "private to the uploading app user.",
     returnShape: {
-      upload: "(file, { folderId?, compress?, fileName? }) => Promise<FilestoreFile>",
+      upload: "(file, { folderId?, recordId?, compress?, fileName? }) => Promise<FilestoreFile>",
       uploading: "boolean",
       error: "Error | null",
       lastUploaded: "FilestoreFile | null",
@@ -1552,7 +1559,10 @@ const HOOKS = [
       "be cancelled. cancel() resolves to what became of the order, which is " +
       "then still pending or already complete: read status after it, never " +
       "assume 'cancelled'. nameRefusal is set when the order failed because " +
-      "the signer's name cannot be shown on the document. Reads " +
+      "the signer's name cannot be shown on the document. error is the last " +
+      "call that failed, and a refresh() or verify() that succeeds clears it: " +
+      "while status is 'pending' an error means one poll failed, so keep " +
+      "polling and keep showing the order. Reads " +
       "ctx.filestore.signatures.{initiate,status,cancel,verify}.",
     returnShape: {
       status: "'pending' | 'complete' | 'failed' | 'cancelled' | null",
@@ -2818,8 +2828,8 @@ const HOOKS = [
       "common case and is deliberately NOT an error, so no try/catch is needed on the happy path. They reject with a " +
       "CameraError whose .code is one of PERMISSION_DENIED | UNSUPPORTED | INTERNAL. `asset.file` is already the right " +
       "upload part for the host — a BLOB on both (a File on web, expo-file-system's File on native), because Expo's fetch " +
-      "implements the web FormData spec and rejects React Native's legacy { uri, name, type } part outright: append it to a FormData as `file` and pass " +
-      "that to ctx.assets.upload(fd) — one code path on both platforms. reset() clears the asset and releases it. Check " +
+      "implements the web FormData spec and rejects React Native's legacy { uri, name, type } part outright: pass it " +
+      "straight to upload(asset.file) from useFilestoreUpload — one code path on both platforms. reset() clears the asset and releases it. Check " +
       "`supported` before rendering a camera button. options: { allowsEditing, quality } are HINTS the host honours where it " +
       "can — the Expo export applies both, the web camera applies quality only, so never depend on a cropped result. " +
       "Behaviour is otherwise identical on web (a getUserMedia preview on EVERY host, phones included; a file input " +
@@ -2885,7 +2895,7 @@ const HOOKS = [
       "Editing is IMPERATIVE — call edit() from an event handler, never during render. " +
       "edit(uri, actions, options?) applies `actions` IN ORDER and resolves the SAME normalised asset shape useCamera() " +
       "yields — { uri, name, mimeType, width, height, size, base64?, file } — so capture -> edit -> upload is ONE code path: " +
-      "append result.file to a FormData as `file` and pass it to ctx.assets.upload(fd). " +
+      "pass result.file to upload() from useFilestoreUpload. " +
       "Each action entry carries exactly one of { resize: { width?, height? } } (aspect preserved when only one is given), " +
       "{ crop: { originX, originY, width, height } }, { rotate: degrees } (positive is clockwise), or " +
       "{ flip: \"horizontal\" | \"vertical\" }. A crop rect must lie INSIDE the surface the earlier actions produced, and " +
@@ -3022,7 +3032,7 @@ const PRIMITIVES = [
   },
   // sc-1378 — `<FilePicker accept onPick>` lets a widget surface a native
   // file-picker on the web Player so end users can upload files to the
-  // backend (paired with useFilestoreUpload or useAssets.upload). Web wraps
+  // backend (paired with useFilestoreUpload). Web wraps
   // a hidden DOM `<input type="file">`; native renders a disabled trigger
   // and exposes `FilePicker.isSupported = false` until a vetted Expo
   // picker pin lands.
@@ -5852,7 +5862,15 @@ const CONTRACT = deepFreeze({
   //    a widget never receives it. `account`'s photo actions are now
   //    optional members, and `user.email` is documented as nullable: an
   //    account without an email has none.
-  version: "1.176.0",
+  // 1.177.0: additive (sc-10937) — `useFilestoreUpload().upload(file,
+  //    { recordId })` names the record per call, so a widget can create a row
+  //    and attach to it in one handler. A FILE column's file goes in its
+  //    row's record space; useCamera / useImageEditor point at
+  //    useFilestoreUpload, since widget code cannot reach ctx.assets.
+  // 1.177.1: fix (sc-10410) — a `refresh()` or `verify()` that succeeds
+  //    clears `useFileSignature`'s `error`; it used to keep one failed poll's
+  //    error for the rest of the order.
+  version: "1.177.1",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,