@colixsystems/widget-sdk 0.218.0 → 0.219.1

package/src/contract.js

@@ -942,13 +942,14 @@ const HOOKS = [
     name: "useFill",
     signature: "useFill()",
     description:
-      "Returns true when the host has sized this widget to fill its layout " +
-      'slot\'s available height — a page-grid tile whose author chose "Fill ' +
-      'tile height", or a widget type that fills by default (containers and ' +
-      "media). When true, a widget that has a meaningful filled form (Image, " +
-      "Chart, Map, Video) should switch from its intrinsic height to a stretch " +
-      'style (flex: 1 / height: "100%"); widgets with no useful filled form ' +
-      "may ignore it. Defaults to false wherever the host has not opted the " +
+      "Returns true when the host has sized this widget to fill a box of " +
+      "definite height — a widget in the section a fit-to-screen page " +
+      "stretches to the bottom of the screen, or a widget given a fixed slot " +
+      "height. When true, a widget that has a meaningful filled form (Image, " +
+      "Chart, Map, Video, a chat or feed that scrolls its own content) should " +
+      "switch from its intrinsic height to a stretch style (flex: 1 / " +
+      'height: "100%") and scroll inside it; widgets with no useful filled ' +
+      "form may ignore it. Defaults to false wherever the host has not opted the " +
       "widget into filling, so calling it is always safe. The SAME value is " +
       "injected by the web Player and the native export (widget-parity skill), so a " +
       "widget's fill behaviour is identical on both platforms.",
@@ -1511,7 +1512,15 @@ const HOOKS = [
       "polls (fresh QR while pending — render with the Image primitive), " +
       "cancel() aborts, verify() returns the offline verdict. Pass " +
       "existingSignatureId for an already-signed file to seed the complete " +
-      "state + verify() without re-signing. Reads " +
+      "state + verify() without re-signing. autoStartToken is set only while " +
+      "opening BankID can still help (null once the user has signed or the " +
+      "order has ended). hintCode says where the order " +
+      "stands; 'sealing' means the user has signed and the signature is being " +
+      "added to the document, so there is nothing to scan and it can no longer " +
+      "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 " +
       "ctx.filestore.signatures.{initiate,status,cancel,verify}.",
     returnShape: {
       status: "'pending' | 'complete' | 'failed' | 'cancelled' | null",
@@ -1520,12 +1529,15 @@ const HOOKS = [
       message: "string | null",
       signerName: "string | null",
       signedAt: "string | null",
+      hintCode: "string | null  // where the order stands, e.g. 'sealing'",
+      nameRefusal:
+        "{ reason: 'empty' | 'too_long' | 'unsupported_characters' | 'mixed_scripts', characters: string[] } | null",
       verdict: "{ valid, checks, content_status, signed_by_others_since, seal, ... } | null",
       loading: "boolean",
       error: "PermissionError | null  // { code, message, retryable }",
-      initiate: "() => Promise<{ signature_id, qr, auto_start_token, status }>",
+      initiate: "() => Promise<{ signature_id, qr, auto_start_token, status, hint_code?, message? }>",
       refresh: "() => Promise<void>",
-      cancel: "() => Promise<void>",
+      cancel: "() => Promise<{ status, hint_code?, message?, signer_name?, signed_at? } | undefined>",
       verify: "() => Promise<verdict>",
     },
     requiredContextSlice: ["filestore.signatures"],
@@ -1572,6 +1584,91 @@ const HOOKS = [
     requiredContextSlice: ["filestore.signatures"],
     scopes: ["files.read:*"],
   },
+  {
+    name: "useSigningRounds",
+    signature: "useSigningRounds(fileIds)",
+    description:
+      "What the signed-in user may know about the signing round of each file " +
+      "in a list, in one batched request. A signing round fixes a PDF and a " +
+      "list of signers: it is prepared and confirmed by someone who manages " +
+      "the file's folder, then each signer signs once with useFileSignature(), " +
+      "in any order (there are no turns; the list only orders the places on " +
+      "the signature page). byFileId maps a file id to { file_id, can_manage, " +
+      "can_prepare, round, locked }; a file the user cannot see is absent. " +
+      "round is null when there is none, and for a user who is neither a " +
+      "manager nor one of its signers; a signer sees it once it is confirmed, " +
+      "with their own place (my_place) and can_sign (the round is open and " +
+      "their place is unsigned), and signed_count is null " +
+      "for them. locked is 'signing_round' while the file cannot be changed, " +
+      "'signed' once its content cannot be replaced. roundsEnabled is false " +
+      "when the workspace cannot start signing rounds (offer no way to start " +
+      "one), and null until the first answer. can_prepare is about the file " +
+      "and the user, roundsEnabled is about the workspace: offer 'prepare' " +
+      "only when both are true. Ids are matched without regard to case. " +
+      "Refetches only when the set of ids or the signed-in user changes; " +
+      "until the new answer arrives loading is true and byFileId is empty. " +
+      "Reads ctx.filestore.signingRounds.overview.",
+    returnShape: {
+      byFileId:
+        "{ [fileId]: { file_id, can_manage: boolean, can_prepare: boolean, " +
+        "round: { id, status: 'DRAFT' | 'OPEN' | 'COMPLETED', signer_count, signed_count: number | null, " +
+        "my_place: { position, signed, signed_at } | null, can_sign: boolean } | null, " +
+        "locked: 'signing_round' | 'signed' | null } }",
+      roundsEnabled: "boolean | null",
+      loading: "boolean",
+      error: "PermissionError | null  // { code, message, retryable, errors, retryAfter }",
+      refresh: "() => Promise<void>",
+    },
+    requiredContextSlice: ["filestore.signingRounds"],
+    scopes: ["files.read:*"],
+  },
+  {
+    name: "useSigningRound",
+    signature: "useSigningRound(fileId)",
+    description:
+      "One file's current signing round, and the actions of someone who " +
+      "manages the file's folder. prepare(signerIds) drafts a round for those " +
+      "users, their places on the signature page in the order given (take the " +
+      "ids from useFileRoster()); it can take " +
+      "up to a minute. preparedFile() returns a five-minute link to the " +
+      "prepared document; show it to the user before confirming. confirm() " +
+      "opens the round for exactly the document preparedFile() last returned, " +
+      "and rejects with code PREVIEW_REQUIRED when it was not called first. " +
+      "cancel() ends a draft or an open round and resolves to the cancelled " +
+      "round (status 'CANCELLED'); round is then null. ONE ACTION RUNS AT A " +
+      "TIME: while busy is true any other action is refused at once with code " +
+      "ACTION_IN_PROGRESS (it is not queued), so disable your buttons on busy. " +
+      "round is the full round as the " +
+      "user may see it: a manager sees every signer's progress, a signer sees " +
+      "every signer's name and position and their own progress only, anyone " +
+      "else sees null. A refused action sets error and rejects with it: code " +
+      "and message come from the server (show message as it is), errors has " +
+      "one entry per refused signer ({ app_user_id, message, reason, " +
+      "characters }), retryAfter is the seconds to wait. The hook's own " +
+      "refusals (PREVIEW_REQUIRED, ACTION_IN_PROGRESS, NO_SIGNING_ROUND) carry " +
+      "a message that can be shown the same way. When a refusal means the " +
+      "round is no longer what was shown (it expired, was closed, or the " +
+      "document changed) the hook reads the round again by itself. Code " +
+      "SIGNING_ROUNDS_NOT_ENABLED means the workspace cannot start signing " +
+      "rounds; check roundsEnabled from useSigningRounds() before offering to " +
+      "start one. When fileId or the signed-in user changes, round is null " +
+      "and loading true until the new answer. Reads ctx.filestore.signingRounds.",
+    returnShape: {
+      round:
+        "{ id, file_id, status: 'DRAFT' | 'OPEN' | 'COMPLETED', created_at, confirmed_at, completed_at, expires_at, " +
+        "signers: { name, position, app_user_id?, signed?, signed_at?, signed_as? }[] } | null",
+      loading: "boolean",
+      error: "PermissionError | null  // { code, message, retryable, errors, retryAfter }",
+      refresh: "() => Promise<void>",
+      prepare: "(signerIds: string[]) => Promise<round>  // status 'DRAFT'",
+      preparedFile: "() => Promise<{ url, sha256, expires_at, size_bytes }>",
+      confirm: "() => Promise<round>  // status 'OPEN'",
+      cancel: "() => Promise<round>  // the round it ended, status 'CANCELLED'",
+      busy: "boolean  // an action is running; another one is refused with ACTION_IN_PROGRESS",
+    },
+    requiredContextSlice: ["filestore.signingRounds"],
+    scopes: ["files.write:*"],
+  },
   {
     name: "useFolderPermissions",
     signature: "useFolderPermissions(folderId, { enabled })",
@@ -3449,15 +3546,16 @@ const WIDGET_CONTEXT_SHAPE = {
     },
   },
   // REQ-LAY-08 — optional host layout hint backing useFill(). True when the
-  // host sized this widget to fill its layout slot's available height (a
-  // page-grid tile set to "Fill tile height", or a default-fill widget type).
+  // host sized this widget to fill a box of definite height (a fit-to-screen
+  // page's stretched section, or a fixed slot height).
   // Optional: a host that never fills a widget simply omits it and useFill()
   // returns false, so existing hosts need no change.
   fill: {
     description:
       "Optional host layout hint (boolean). True when the host sized this " +
-      "widget to fill its layout slot's available height (page-grid tile " +
-      "fill). Backs useFill(); defaults to false when absent.",
+      "widget to fill a box of definite height (a fit-to-screen page's " +
+      "stretched section, or a fixed slot height). Backs useFill(); defaults " +
+      "to false when absent.",
     required: false,
     fields: {},
   },
@@ -3588,10 +3686,12 @@ const WIDGET_CONTEXT_SHAPE = {
       "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), 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() + useFilestoreCreateFolder() + useFilestoreCopy() + useFileSignature(). Optional — a host without an end-user filestore omits it and those hooks throw a clear error.",
+      "signatures: { list(fileIds), roster(fileId, query), initiate(fileId), status(id), cancel(id), verify(id) }, " +
+      "signingRounds: { overview(fileIds), list(fileId, query), get(roundId), prepare(fileId, signerIds), preparedFile(roundId), confirm(roundId, preparedSha256), cancel(roundId) }, " +
+      "objectUrl(token), fetchObject(token) }. " +
+      "Backs useFilestoreFiles() + useFilestoreFolders() + useFilestoreCreateFolder() + useFilestoreCopy() + useFileSignature() + useFileSignatures() + useFileRoster() + useSigningRounds() + useSigningRound(). 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" },
+    fields: { files: "object", folders: "object", shares: "object", signatures: "object", signingRounds: "object" },
   },
   renderer: {
     description:
@@ -5703,7 +5803,12 @@ const CONTRACT = deepFreeze({
   //    binds no widget style fields: the component reads it on both hosts,
   //    which a scope now states as `sdkComponents`.
   //    Additive: an unthemed chip is the muted pill widgets drew by hand.
-  version: "1.174.0",
+  // 1.175.0: additive (sc-10410) — `useSigningRounds(fileIds)` and
+  //    `useSigningRound(fileId)` read and run PDF signing rounds through the
+  //    new `ctx.filestore.signingRounds`. `useFileSignature` also returns
+  //    `hintCode` and `nameRefusal`, and its `cancel()` resolves to what
+  //    became of the order instead of always reporting "cancelled".
+  version: "1.175.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,