@colixsystems/widget-sdk 0.58.0 → 0.59.0

package/README.md

@@ -52,7 +52,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.58.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.59.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.59.0
+
+**Display a stored file by id — `useFilestoreFile(fileId)` (sc-3031).** A new FILESTORE read hook that resolves ONE file id to a displayable URL. Given a file id the app stored — chiefly a datastore `FILE` column, which holds a filestore file id (a string), never bytes — it fetches the record via `ctx.filestore.files.get(id)` and returns `{ file, url, loading, error, refetch }`, where `url` is the record's `presigned_url` absolutized by the client so it renders on the web Player **and** the native Expo export alike. Drop `url` straight into `<Image source={{ uri: url }} />`. An empty id makes no round-trip (`{ file: null, url: null }`); a deleted / not-found id degrades the same way (`url` stays null, `error` carries the wire error) so a display widget shows its fallback instead of crashing. This closes the upload→store→display loop: `useFilestoreUpload(...).upload(file)` → write `file.id` into the `FILE` column → `useFilestoreFile(id).url` to show it. Requires the `files.read:*` scope. `CONTRACT.version` → `1.40.0`. Additive — one new read hook; no existing export changed signature.
 
 ### What's new in 0.58.0
 
@@ -210,6 +214,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.
+- `useFilestoreFile(fileId)` → `{ file, url, loading, error, refetch }` — resolves ONE file id (as held in a datastore `FILE` column) to a displayable `url` (its `presigned_url`, absolutized for web + native) via `ctx.filestore.files.get(id)`. Empty / deleted / not-found ids resolve to `url: null` so a display widget shows a fallback. 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.
 - `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

@@ -214,6 +214,29 @@ const HOOKS = [
     requiredContextSlice: ["filestore.files"],
     scopes: ["files.read:*"],
   },
+  {
+    name: "useFilestoreFile",
+    signature: "useFilestoreFile(fileId)",
+    description:
+      "Resolve ONE Filestore file id to a displayable URL. Given a file id " +
+      "the app stored (e.g. a datastore FILE column, which holds a filestore " +
+      "file id — never bytes), the hook fetches the record via " +
+      "ctx.filestore.files.get(id) and surfaces its `presigned_url` as `url`, " +
+      "ready to drop into <Image source={{ uri: url }} />. The URL is " +
+      "absolutized by the client so it loads on web AND native. An empty id " +
+      "collapses to { file: null, url: null } with no round-trip; a deleted / " +
+      "not-found id degrades the same way (url stays null, error carries the " +
+      "wire error) so a display widget shows its fallback instead of crashing.",
+    returnShape: {
+      file: "FilestoreFile | null",
+      url: "string | null",
+      loading: "boolean",
+      error: "Error | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["filestore.files"],
+    scopes: ["files.read:*"],
+  },
   {
     name: "useFilestoreUpload",
     signature: "useFilestoreUpload({ spaceType, folderId? })",
@@ -1864,7 +1887,11 @@ const CONTRACT = deepFreeze({
   //    resolved live by `created_at` desc with limit 1; recordId ignored). The
   //    Data Value widget reads it to show a live "latest entry". Existing
   //    bindings have no `mode` and read as static — additive, minor bump.
-  version: "1.39.0",
+  // 1.40.0: additive (sc-3031) — `useFilestoreFile(fileId)` resolves one
+  //    filestore file id (as held in a datastore FILE column) to a
+  //    displayable `url` (its presigned_url, absolutized for web + native).
+  //    New read hook, no existing behaviour changes — minor bump.
+  version: "1.40.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -214,6 +214,29 @@ const HOOKS = [
     requiredContextSlice: ["filestore.files"],
     scopes: ["files.read:*"],
   },
+  {
+    name: "useFilestoreFile",
+    signature: "useFilestoreFile(fileId)",
+    description:
+      "Resolve ONE Filestore file id to a displayable URL. Given a file id " +
+      "the app stored (e.g. a datastore FILE column, which holds a filestore " +
+      "file id — never bytes), the hook fetches the record via " +
+      "ctx.filestore.files.get(id) and surfaces its `presigned_url` as `url`, " +
+      "ready to drop into <Image source={{ uri: url }} />. The URL is " +
+      "absolutized by the client so it loads on web AND native. An empty id " +
+      "collapses to { file: null, url: null } with no round-trip; a deleted / " +
+      "not-found id degrades the same way (url stays null, error carries the " +
+      "wire error) so a display widget shows its fallback instead of crashing.",
+    returnShape: {
+      file: "FilestoreFile | null",
+      url: "string | null",
+      loading: "boolean",
+      error: "Error | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["filestore.files"],
+    scopes: ["files.read:*"],
+  },
   {
     name: "useFilestoreUpload",
     signature: "useFilestoreUpload({ spaceType, folderId? })",
@@ -1864,7 +1887,11 @@ const CONTRACT = deepFreeze({
   //    resolved live by `created_at` desc with limit 1; recordId ignored). The
   //    Data Value widget reads it to show a live "latest entry". Existing
   //    bindings have no `mode` and read as static — additive, minor bump.
-  version: "1.39.0",
+  // 1.40.0: additive (sc-3031) — `useFilestoreFile(fileId)` resolves one
+  //    filestore file id (as held in a datastore FILE column) to a
+  //    displayable `url` (its presigned_url, absolutized for web + native).
+  //    New read hook, no existing behaviour changes — minor bump.
+  version: "1.40.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -1502,6 +1502,80 @@ export function useFilestoreFiles(options) {
   return { files, loading, error, refetch };
 }
 
+/**
+ * sc-3031 — resolve ONE Filestore file id to a displayable URL. Returns
+ * `{ file, url, loading, error, refetch }`. Given a file id the app stored
+ * (e.g. a datastore FILE column, which holds a filestore file id — never
+ * bytes), the hook fetches the file record via `ctx.filestore.files.get(id)`
+ * and surfaces its `presigned_url` as `url`, ready to drop straight into an
+ * `<Image source={{ uri: url }} />`. The URL is absolutized by the filestore
+ * client, so it loads on the web Player AND the native export.
+ *
+ * An empty / null id collapses to `{ file: null, url: null }` with no network
+ * round-trip; a deleted or not-found id degrades the same way (`url` stays
+ * null and `error` carries the wire error) so a display widget shows its
+ * fallback instead of crashing.
+ */
+export function useFilestoreFile(fileId) {
+  const ctx = useWidgetContextOrThrow("useFilestoreFile");
+  if (
+    !ctx.filestore ||
+    !ctx.filestore.files ||
+    typeof ctx.filestore.files.get !== "function"
+  ) {
+    throw new Error(
+      "useFilestoreFile: host did not inject a filestore client (ctx.filestore.files.get)",
+    );
+  }
+
+  const [file, setFile] = useState(null);
+  const [loading, setLoading] = useState(Boolean(fileId));
+  const [error, setError] = useState(null);
+
+  const filesRef = useRef(ctx.filestore.files);
+  filesRef.current = ctx.filestore.files;
+  const idRef = useRef(fileId);
+  idRef.current = fileId;
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const id = idRef.current;
+    if (!id) {
+      setLoading(false);
+      setError(null);
+      setFile(null);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const row = await filesRef.current.get(id);
+      if (runRef.current !== myRun) return;
+      setFile(row || null);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(err);
+      setFile(null);
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [fileId]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  const url =
+    file && typeof file.presigned_url === "string" ? file.presigned_url : null;
+  return { file, url, loading, error, refetch };
+}
+
 /**
  * sc-1378 — upload a file into the end-user's Filestore space. Returns
  * `{ upload, uploading, error, lastUploaded }`. The widget passes the

package/dist/index.js

@@ -18,6 +18,7 @@ export {
   useAsset,
   useAssetsByTag,
   useFilestoreFiles,
+  useFilestoreFile,
   useFilestoreUpload,
   usePdfExport,
   useFilestoreFolders,

package/dist/index.native.js

@@ -18,6 +18,7 @@ export {
   useAsset,
   useAssetsByTag,
   useFilestoreFiles,
+  useFilestoreFile,
   useFilestoreUpload,
   usePdfExport,
   useFilestoreFolders,

package/package.json

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