@colixsystems/widget-sdk 0.240.0 → 0.243.0

package/README.md

@@ -84,7 +84,39 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.240.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.243.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.243.0 (contract 1.197.0)
+
+**`bankIdAppUrl(autoStartToken)` opens BankID on this device** (from 0.243.0). The link a signing or identification widget opens from its "Open BankID on this device" button: `Linking.openURL(bankIdAppUrl(autoStartToken))`. It is the same link the built-in Files and Identification widgets and the signing page use. For BankID on another device, show the order's `qr` with `<Image>`.
+
+`useFileSignature` does not poll by itself: while `status` is `"pending"`, call `refresh()` every 2 seconds, and render each answer's `qr`. It signs a file of any type in a shared space; outside a signing round the signature is kept beside the file, and in a round the signature is added to the PDF, which is then sealed. A `verify()` verdict reads as: `valid` (the BankID signature), `content_status` (`unchanged`, `changed` or `unavailable`), `signed_by_others_since` (later signatures in a round) and `seal.status` (`valid`, `invalid`, `certificate_revoked`, `unavailable`, or `not_applicable` for a signature kept beside the file). `useFileSignatures` is described as what it is: the signed-in user's own signatures.
+
+```jsx
+import { Button, Image, Linking, bankIdAppUrl, useFileSignature } from "@colixsystems/widget-sdk";
+
+const { status, qr, autoStartToken, initiate, refresh } = useFileSignature(fileId);
+useEffect(() => {
+  if (status !== "pending") return undefined;
+  const timer = setInterval(refresh, 2000);
+  return () => clearInterval(timer);
+}, [status, refresh]);
+// bankIdAppUrl exists from 0.243.0; a widget that must load on an older SDK
+// reads it as sdk.bankIdAppUrl from `import * as sdk` and builds the same link itself.
+// autoStartToken && <Button title="Open BankID on this device" onPress={() => Linking.openURL(bankIdAppUrl(autoStartToken))} />
+// qr && <Image source={{ uri: qr }} style={{ width: 200, height: 200 }} />
+```
+
+### What's new in 0.241.0 (contract 1.195.0)
+
+**A signing round can include people without an account in the app.** `useSigningRound(fileId).prepare(signers)` takes, beside account ids, `{ name, email }` entries, mixed in the order of the places on the signature page. When the round is confirmed, each of those people is emailed a personal BankID signing link that is valid for 24 hours. Anyone who holds the link can sign, so tell the person sending the document before they send it. In the round a manager sees each place's `id`, `kind` (`"app_user"` or `"email"`), `email`, `signed_as` (the name BankID verified, which can differ from the name you entered) and, for an email place, `link`: `{ status, sent_at, expires_at, used_at, links_sent, can_resend }`, where `status` is `"sending"`, `"sent"`, `"delivery_failed"`, `"expired"`, `"used"` or `"cancelled"`. `resendLink(signerId, { email })` replaces the place's link with a new one (the old link stops working), sent to a corrected address when you pass one. Offer it only where `link.can_resend` is true. A refused signer's `errors` entry now carries `index`, its position in the list you sent, so you can mark the right entry. A new link sent too soon is refused with `SIGNING_LINK_RESEND_TOO_SOON` and a `retryAfter` in seconds. A list of account ids alone works exactly as before. **One type changes:** `SigningRoundSigner.app_user_id` widens from `string` to `string | null`, because an email place has no account; TypeScript code that read it as a string must check for null. `resendLink` needs `@colixsystems/filestore-client@0.14.0`; with an older client it is refused with code `NOT_SUPPORTED`.
+
+```jsx
+const { round, prepare, resendLink } = useSigningRound(fileId);
+await prepare(["user_1", { name: "Bo Ek", email: "bo@example.se" }]);
+// later, for an email place whose link.can_resend is true:
+await resendLink(place.id, { email: "bo.ek@example.se" });
+```
 
 ### What's new in 0.240.0 (contract 1.194.0)
 

package/dist/bankid-app.js

@@ -0,0 +1,6 @@
+// The one BankID app launch link: widgets, the Player's login and the signing
+// page. Imports nothing, so every host and the exported app share it as it is.
+
+/** The URL that opens the BankID app on this device for the order of `autoStartToken`. */
+export const bankIdAppUrl = (autoStartToken) =>
+  `bankid:///?autostarttoken=${encodeURIComponent(autoStartToken)}&redirect=null`;

package/dist/contract.cjs

@@ -1624,10 +1624,30 @@ const HOOKS = [
     signature: "useFileSignature(fileId, existingSignatureId)",
     optionalArgs: ["existingSignatureId"],
     description:
-      "Drive a BankID signing flow for one Filestore file. initiate() opens a " +
-      "sign order (the backend hashes the bytes + binds the digest), refresh() " +
-      "polls (fresh QR while pending — render with the Image primitive), " +
-      "cancel() aborts, verify() returns the offline verdict. Pass " +
+      "Drive a BankID signing flow for one Filestore file of ANY type in a " +
+      "shared (project or public) space; a personal file is refused with " +
+      "NOT_SIGNABLE. Outside a signing round the signature is kept beside " +
+      "the file and the file is not changed; a PDF in an open signing round " +
+      "gets the signature added to the document itself, which is then " +
+      "sealed against changes (see useSigningRounds). initiate() opens a " +
+      "sign order (the backend hashes the bytes + binds the digest). The " +
+      "hook does NOT poll by itself: while status is 'pending' call " +
+      "refresh() every 2 seconds (a setInterval in an effect, cleared when " +
+      "status leaves 'pending' or the widget unmounts); each answer carries " +
+      "a fresh qr frame. Offer both ways to sign: BankID on THIS device is a " +
+      "button whose onPress calls Linking.openURL(bankIdAppUrl(autoStartToken)), " +
+      "shown only while autoStartToken is set; BankID on ANOTHER device is " +
+      "the qr rendered with the Image primitive, replaced by each poll's " +
+      "frame. cancel() aborts, verify() returns the offline verdict: valid " +
+      "is the BankID signature itself; content_status 'unchanged' means the " +
+      "file still holds what was signed, 'changed' that it was altered " +
+      "since, 'unavailable' that it could not be checked now; " +
+      "signed_by_others_since counts later signatures in a round's PDF; " +
+      "seal.status is 'valid' (protected against changes), 'invalid' or " +
+      "'certificate_revoked' (do not rely on the copy), 'unavailable' (try " +
+      "later) or 'not_applicable' (a signature kept beside the file). Say " +
+      "each in plain words and never show a green mark when any of them " +
+      "failed. Pass " +
       "existingSignatureId for an already-signed file to seed the complete " +
       "state + verify() without re-signing. autoStartToken is set only while " +
       "opening BankID can still help (null once the user has signed or the " +
@@ -1644,19 +1664,21 @@ const HOOKS = [
       "ctx.filestore.signatures.{initiate,status,cancel,verify}.",
     returnShape: {
       status: "'pending' | 'complete' | 'failed' | 'cancelled' | null",
-      qr: "string | null  // PNG data-URL of the animated BankID QR",
-      autoStartToken: "string | null",
+      qr: "string | null  // PNG data-URL of the animated BankID QR; render with <Image>, refresh() every 2 s while pending for the next frame",
+      autoStartToken: "string | null  // BankID on this device: a button calling Linking.openURL(bankIdAppUrl(autoStartToken))",
       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",
+      verdict:
+        "{ valid, checks, content_status: 'unchanged' | 'changed' | 'unavailable', signed_by_others_since: number | null, " +
+        "seal: { status: 'valid' | 'invalid' | 'certificate_revoked' | 'unavailable' | 'not_applicable', sealed_at, certificate_revoked_at, ... }, ... } | null",
       loading: "boolean",
       error: "PermissionError | null  // { code, message, retryable }",
       initiate: "() => Promise<{ signature_id, qr, auto_start_token, status, hint_code?, message? }>",
-      refresh: "() => Promise<void>",
+      refresh: "() => Promise<void>  // the hook never polls by itself",
       cancel: "() => Promise<{ status, hint_code?, message?, signer_name?, signed_at? } | undefined>",
       verify: "() => Promise<verdict>",
     },
@@ -1667,10 +1689,14 @@ const HOOKS = [
     name: "useFileSignatures",
     signature: "useFileSignatures(fileIds)",
     description:
-      "Batch 'is this file signed?' lookup for a set of file ids. Returns a map " +
-      "of each signed, accessible file id to its latest signature; unsigned " +
-      "files are absent. Lets a file browser mark already-signed files in one " +
-      "request. Reads ctx.filestore.signatures.list and unwraps { data, meta }.",
+      "Batch 'have I signed this file?' lookup for a set of file ids. Returns " +
+      "a map of each file the SIGNED-IN USER has signed (and can still see) " +
+      "to their own latest signature; a file only others have signed, or " +
+      "nobody has, is absent, so it never tells who else signed. Pass a " +
+      "file's signature_id to useFileSignature(fileId, signatureId) to show " +
+      "and verify it. Who has signed is useFileRoster(), for someone who " +
+      "manages the folder. Reads ctx.filestore.signatures.list and unwraps " +
+      "{ data, meta }.",
     returnShape: {
       signaturesByFileId:
         "{ [fileId]: { signature_id, signer_name, signed_at } }",
@@ -1709,8 +1735,10 @@ const HOOKS = [
     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 " +
+      "in a list, in one batched request. A signing round fixes a PDF in the " +
+      "project space and a list of signers (other file types are signed one " +
+      "person at a time with useFileSignature() and no round): 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, " +
@@ -1719,7 +1747,8 @@ const HOOKS = [
       "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, " +
+      "for them. Each signature is added to the PDF itself and the document " +
+      "is sealed against changes. 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 " +
@@ -1747,15 +1776,27 @@ const HOOKS = [
     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 " +
+      "manages the file's folder. prepare(signers) drafts a round for those " +
+      "people, their places on the signature page in the order given: each " +
+      "entry is an account id from useFileRoster() (or { app_user_id }), or " +
+      "{ name, email } for someone without an account, who is emailed a " +
+      "personal BankID signing link valid for 24 hours once the round is " +
+      "confirmed (anyone holding that link can sign, so say so before " +
+      "sending); 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 " +
+      "round (status 'CANCELLED'); round is then null. " +
+      "resendLink(signerId, { email }) replaces an email place's link with " +
+      "a new one (the old one stops working), sent to the corrected email " +
+      "when given, and resolves to the round; offer it only where the " +
+      "place's link.can_resend is true. A manager sees each place's id, kind " +
+      "('app_user' | 'email'), email, signed_as (the name BankID verified) " +
+      "and link ({ status: 'sending' | 'sent' | 'delivery_failed' | " +
+      "'expired' | 'used' | 'cancelled', sent_at, expires_at, used_at, " +
+      "links_sent, can_resend }, null for an account place). 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 " +
@@ -1763,27 +1804,40 @@ const HOOKS = [
       "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 " +
+      "one entry per refused signer ({ index, app_user_id, message, reason, " +
+      "characters }; index is the entry's place in the list sent), " +
+      "retryAfter is the seconds to wait. resendLink is refused with " +
+      "SIGNING_LINK_RESEND_TOO_SOON (with retryAfter), " +
+      "SIGNING_LINK_RESEND_IN_PROGRESS, SIGNING_LINK_LIMIT_REACHED, " +
+      "SIGNING_LINK_BUDGET_EXCEEDED, SIGNING_LINK_PLATFORM_LIMIT, " +
+      "INVALID_EMAIL, DUPLICATE_SIGNER, SIGNING_ROUND_NOT_OPEN, " +
+      "SIGNING_ROUND_CLOSED or ALREADY_SIGNED, and by the hook itself with " +
+      "NOT_SUPPORTED when the host's filestore client cannot send links. 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 " +
+      "start one, and when it is false say that document signing is not " +
+      "turned on for this workspace and that the platform turns it on. " +
+      "Rounds take PDFs in the project space only (NOT_A_PDF otherwise). A " +
+      "signer signs their place with useFileSignature(fileId), the same " +
+      "BankID flow as any file. 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",
+        "signers: { name, position, app_user_id?, signed?, signed_at?, signed_as?, id?, kind?: 'app_user' | 'email', email?, " +
+        "link?: { status: 'sending' | 'sent' | 'delivery_failed' | 'expired' | 'used' | 'cancelled', sent_at, expires_at, used_at, links_sent, can_resend } | null }[] } | null",
       loading: "boolean",
       error: "PermissionError | null  // { code, message, retryable, errors, retryAfter }",
       refresh: "() => Promise<void>",
-      prepare: "(signerIds: string[]) => Promise<round>  // status 'DRAFT'",
+      prepare: "(signers: (string | { app_user_id } | { name, email })[]) => 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'",
+      resendLink: "(signerId: string, options?: { email?: string }) => Promise<round>  // a new link for an email place",
       busy: "boolean  // an action is running; another one is refused with ACTION_IN_PROGRESS",
     },
     requiredContextSlice: ["filestore.signingRounds"],
@@ -2598,8 +2652,9 @@ const HOOKS = [
       "with the Image primitive) and the hook then POLLS to completion itself " +
       "(pollIntervalMs, default 1000; pass 0 to drive refresh() yourself); " +
       "cancel() aborts; reset() clears the flow. autoStartToken opens the " +
-      "provider app on the SAME device (bankid:///?autostarttoken=<token>" +
-      "&redirect=null). On complete, `identity` is { provider, name, given_name, " +
+      "provider app on the SAME device: Linking.openURL(bankIdAppUrl(" +
+      "autoStartToken)) opens bankid:///?autostarttoken=<token>&redirect=null. " +
+      "On complete, `identity` is { provider, name, given_name, " +
       "surname, personal_number_masked, subject_hash, identified_at } — there is " +
       "NO raw personal number by design: write personal_number_masked " +
       "(\"19900101-****\") and, if you need to trace the proof, identificationId. " +
@@ -3892,7 +3947,7 @@ const WIDGET_CONTEXT_SHAPE = {
       "{ 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: { 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) }, " +
+      "signingRounds: { overview(fileIds), list(fileId, query), get(roundId), prepare(fileId, signers), preparedFile(roundId), confirm(roundId, preparedSha256), cancel(roundId), resendLink(roundId, signerId, { email }) }, " +
       "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,
@@ -6092,7 +6147,15 @@ const CONTRACT = deepFreeze({
   //    `sectionRef` propertySchema type gives the author a section picker.
   // 1.194.0: more permissive (sc-11945) — a datastoreTemplate takes 100
   //    tables, 200 columns, 100 rows per table, 20000 cells and 32 roles.
-  version: "1.194.0",
+  // 1.195.0: additive (sc-11879) — `useSigningRound().prepare` takes
+  //    `{ name, email }` entries for signers without an account, and
+  //    `resendLink(signerId, { email })` sends such a signer a new link.
+  //    The manager's places carry id, kind, email and link.
+  // 1.197.0: additive (sc-12063) — new export `bankIdAppUrl(autoStartToken)`,
+  //    the link that opens BankID on this device. Signing hooks document
+  //    polling, the two ways to start BankID and how to read a verdict;
+  //    useFileSignatures is described as the caller's own signatures.
+  version: "1.197.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1624,10 +1624,30 @@ const HOOKS = [
     signature: "useFileSignature(fileId, existingSignatureId)",
     optionalArgs: ["existingSignatureId"],
     description:
-      "Drive a BankID signing flow for one Filestore file. initiate() opens a " +
-      "sign order (the backend hashes the bytes + binds the digest), refresh() " +
-      "polls (fresh QR while pending — render with the Image primitive), " +
-      "cancel() aborts, verify() returns the offline verdict. Pass " +
+      "Drive a BankID signing flow for one Filestore file of ANY type in a " +
+      "shared (project or public) space; a personal file is refused with " +
+      "NOT_SIGNABLE. Outside a signing round the signature is kept beside " +
+      "the file and the file is not changed; a PDF in an open signing round " +
+      "gets the signature added to the document itself, which is then " +
+      "sealed against changes (see useSigningRounds). initiate() opens a " +
+      "sign order (the backend hashes the bytes + binds the digest). The " +
+      "hook does NOT poll by itself: while status is 'pending' call " +
+      "refresh() every 2 seconds (a setInterval in an effect, cleared when " +
+      "status leaves 'pending' or the widget unmounts); each answer carries " +
+      "a fresh qr frame. Offer both ways to sign: BankID on THIS device is a " +
+      "button whose onPress calls Linking.openURL(bankIdAppUrl(autoStartToken)), " +
+      "shown only while autoStartToken is set; BankID on ANOTHER device is " +
+      "the qr rendered with the Image primitive, replaced by each poll's " +
+      "frame. cancel() aborts, verify() returns the offline verdict: valid " +
+      "is the BankID signature itself; content_status 'unchanged' means the " +
+      "file still holds what was signed, 'changed' that it was altered " +
+      "since, 'unavailable' that it could not be checked now; " +
+      "signed_by_others_since counts later signatures in a round's PDF; " +
+      "seal.status is 'valid' (protected against changes), 'invalid' or " +
+      "'certificate_revoked' (do not rely on the copy), 'unavailable' (try " +
+      "later) or 'not_applicable' (a signature kept beside the file). Say " +
+      "each in plain words and never show a green mark when any of them " +
+      "failed. Pass " +
       "existingSignatureId for an already-signed file to seed the complete " +
       "state + verify() without re-signing. autoStartToken is set only while " +
       "opening BankID can still help (null once the user has signed or the " +
@@ -1644,19 +1664,21 @@ const HOOKS = [
       "ctx.filestore.signatures.{initiate,status,cancel,verify}.",
     returnShape: {
       status: "'pending' | 'complete' | 'failed' | 'cancelled' | null",
-      qr: "string | null  // PNG data-URL of the animated BankID QR",
-      autoStartToken: "string | null",
+      qr: "string | null  // PNG data-URL of the animated BankID QR; render with <Image>, refresh() every 2 s while pending for the next frame",
+      autoStartToken: "string | null  // BankID on this device: a button calling Linking.openURL(bankIdAppUrl(autoStartToken))",
       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",
+      verdict:
+        "{ valid, checks, content_status: 'unchanged' | 'changed' | 'unavailable', signed_by_others_since: number | null, " +
+        "seal: { status: 'valid' | 'invalid' | 'certificate_revoked' | 'unavailable' | 'not_applicable', sealed_at, certificate_revoked_at, ... }, ... } | null",
       loading: "boolean",
       error: "PermissionError | null  // { code, message, retryable }",
       initiate: "() => Promise<{ signature_id, qr, auto_start_token, status, hint_code?, message? }>",
-      refresh: "() => Promise<void>",
+      refresh: "() => Promise<void>  // the hook never polls by itself",
       cancel: "() => Promise<{ status, hint_code?, message?, signer_name?, signed_at? } | undefined>",
       verify: "() => Promise<verdict>",
     },
@@ -1667,10 +1689,14 @@ const HOOKS = [
     name: "useFileSignatures",
     signature: "useFileSignatures(fileIds)",
     description:
-      "Batch 'is this file signed?' lookup for a set of file ids. Returns a map " +
-      "of each signed, accessible file id to its latest signature; unsigned " +
-      "files are absent. Lets a file browser mark already-signed files in one " +
-      "request. Reads ctx.filestore.signatures.list and unwraps { data, meta }.",
+      "Batch 'have I signed this file?' lookup for a set of file ids. Returns " +
+      "a map of each file the SIGNED-IN USER has signed (and can still see) " +
+      "to their own latest signature; a file only others have signed, or " +
+      "nobody has, is absent, so it never tells who else signed. Pass a " +
+      "file's signature_id to useFileSignature(fileId, signatureId) to show " +
+      "and verify it. Who has signed is useFileRoster(), for someone who " +
+      "manages the folder. Reads ctx.filestore.signatures.list and unwraps " +
+      "{ data, meta }.",
     returnShape: {
       signaturesByFileId:
         "{ [fileId]: { signature_id, signer_name, signed_at } }",
@@ -1709,8 +1735,10 @@ const HOOKS = [
     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 " +
+      "in a list, in one batched request. A signing round fixes a PDF in the " +
+      "project space and a list of signers (other file types are signed one " +
+      "person at a time with useFileSignature() and no round): 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, " +
@@ -1719,7 +1747,8 @@ const HOOKS = [
       "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, " +
+      "for them. Each signature is added to the PDF itself and the document " +
+      "is sealed against changes. 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 " +
@@ -1747,15 +1776,27 @@ const HOOKS = [
     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 " +
+      "manages the file's folder. prepare(signers) drafts a round for those " +
+      "people, their places on the signature page in the order given: each " +
+      "entry is an account id from useFileRoster() (or { app_user_id }), or " +
+      "{ name, email } for someone without an account, who is emailed a " +
+      "personal BankID signing link valid for 24 hours once the round is " +
+      "confirmed (anyone holding that link can sign, so say so before " +
+      "sending); 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 " +
+      "round (status 'CANCELLED'); round is then null. " +
+      "resendLink(signerId, { email }) replaces an email place's link with " +
+      "a new one (the old one stops working), sent to the corrected email " +
+      "when given, and resolves to the round; offer it only where the " +
+      "place's link.can_resend is true. A manager sees each place's id, kind " +
+      "('app_user' | 'email'), email, signed_as (the name BankID verified) " +
+      "and link ({ status: 'sending' | 'sent' | 'delivery_failed' | " +
+      "'expired' | 'used' | 'cancelled', sent_at, expires_at, used_at, " +
+      "links_sent, can_resend }, null for an account place). 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 " +
@@ -1763,27 +1804,40 @@ const HOOKS = [
       "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 " +
+      "one entry per refused signer ({ index, app_user_id, message, reason, " +
+      "characters }; index is the entry's place in the list sent), " +
+      "retryAfter is the seconds to wait. resendLink is refused with " +
+      "SIGNING_LINK_RESEND_TOO_SOON (with retryAfter), " +
+      "SIGNING_LINK_RESEND_IN_PROGRESS, SIGNING_LINK_LIMIT_REACHED, " +
+      "SIGNING_LINK_BUDGET_EXCEEDED, SIGNING_LINK_PLATFORM_LIMIT, " +
+      "INVALID_EMAIL, DUPLICATE_SIGNER, SIGNING_ROUND_NOT_OPEN, " +
+      "SIGNING_ROUND_CLOSED or ALREADY_SIGNED, and by the hook itself with " +
+      "NOT_SUPPORTED when the host's filestore client cannot send links. 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 " +
+      "start one, and when it is false say that document signing is not " +
+      "turned on for this workspace and that the platform turns it on. " +
+      "Rounds take PDFs in the project space only (NOT_A_PDF otherwise). A " +
+      "signer signs their place with useFileSignature(fileId), the same " +
+      "BankID flow as any file. 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",
+        "signers: { name, position, app_user_id?, signed?, signed_at?, signed_as?, id?, kind?: 'app_user' | 'email', email?, " +
+        "link?: { status: 'sending' | 'sent' | 'delivery_failed' | 'expired' | 'used' | 'cancelled', sent_at, expires_at, used_at, links_sent, can_resend } | null }[] } | null",
       loading: "boolean",
       error: "PermissionError | null  // { code, message, retryable, errors, retryAfter }",
       refresh: "() => Promise<void>",
-      prepare: "(signerIds: string[]) => Promise<round>  // status 'DRAFT'",
+      prepare: "(signers: (string | { app_user_id } | { name, email })[]) => 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'",
+      resendLink: "(signerId: string, options?: { email?: string }) => Promise<round>  // a new link for an email place",
       busy: "boolean  // an action is running; another one is refused with ACTION_IN_PROGRESS",
     },
     requiredContextSlice: ["filestore.signingRounds"],
@@ -2598,8 +2652,9 @@ const HOOKS = [
       "with the Image primitive) and the hook then POLLS to completion itself " +
       "(pollIntervalMs, default 1000; pass 0 to drive refresh() yourself); " +
       "cancel() aborts; reset() clears the flow. autoStartToken opens the " +
-      "provider app on the SAME device (bankid:///?autostarttoken=<token>" +
-      "&redirect=null). On complete, `identity` is { provider, name, given_name, " +
+      "provider app on the SAME device: Linking.openURL(bankIdAppUrl(" +
+      "autoStartToken)) opens bankid:///?autostarttoken=<token>&redirect=null. " +
+      "On complete, `identity` is { provider, name, given_name, " +
       "surname, personal_number_masked, subject_hash, identified_at } — there is " +
       "NO raw personal number by design: write personal_number_masked " +
       "(\"19900101-****\") and, if you need to trace the proof, identificationId. " +
@@ -3888,7 +3943,7 @@ const WIDGET_CONTEXT_SHAPE = {
       "{ 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: { 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) }, " +
+      "signingRounds: { overview(fileIds), list(fileId, query), get(roundId), prepare(fileId, signers), preparedFile(roundId), confirm(roundId, preparedSha256), cancel(roundId), resendLink(roundId, signerId, { email }) }, " +
       "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,
@@ -6088,7 +6143,15 @@ const CONTRACT = deepFreeze({
   //    `sectionRef` propertySchema type gives the author a section picker.
   // 1.194.0: more permissive (sc-11945) — a datastoreTemplate takes 100
   //    tables, 200 columns, 100 rows per table, 20000 cells and 32 roles.
-  version: "1.194.0",
+  // 1.195.0: additive (sc-11879) — `useSigningRound().prepare` takes
+  //    `{ name, email }` entries for signers without an account, and
+  //    `resendLink(signerId, { email })` sends such a signer a new link.
+  //    The manager's places carry id, kind, email and link.
+  // 1.197.0: additive (sc-12063) — new export `bankIdAppUrl(autoStartToken)`,
+  //    the link that opens BankID on this device. Signing hooks document
+  //    polling, the two ways to start BankID and how to read a verdict;
+  //    useFileSignatures is described as the caller's own signatures.
+  version: "1.197.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -5065,6 +5065,13 @@ export function useFileSignature(
   verify(): Promise<FileSignatureVerdict | null>;
 };
 
+/**
+ * The link that opens the BankID app on this device for a pending order:
+ * `Linking.openURL(bankIdAppUrl(autoStartToken))` from a button. For BankID
+ * on another device, show the order's `qr` instead.
+ */
+export function bankIdAppUrl(autoStartToken: string): string;
+
 export interface FileSignatureSummary {
   signature_id: string;
   subject_file_id: string;
@@ -5111,6 +5118,9 @@ export interface SigningRefusalEntry {
   field?: string;
   message: string;
   code?: string;
+  /** The entry's place in the list of signers that was sent. */
+  index?: number;
+  /** Set when the entry names an account. */
   app_user_id?: string;
   reason?: SignatureNameRefusal["reason"];
   characters?: string[];
@@ -5171,14 +5181,43 @@ export function useSigningRounds(fileIds: string[] | null | undefined): {
 export interface SigningRoundSigner {
   name: string;
   position: number;
-  /** Present for every place when the user manages the folder; otherwise for their own place only. */
-  app_user_id?: string;
+  /**
+   * Present for every place when the user manages the folder; otherwise for
+   * their own place only. Null for a place held by someone without an account.
+   */
+  app_user_id?: string | null;
   signed?: boolean;
   signed_at?: string | null;
   /** The name BankID verified on this place. Managers only. */
   signed_as?: string | null;
+  /** The place, as `resendLink` names it. Managers only. */
+  id?: string;
+  /** Who holds the place: an account, or someone signing through an emailed link. Managers only. */
+  kind?: "app_user" | "email";
+  /** An email place's address; null once the round has closed. Managers only. */
+  email?: string | null;
+  /** An email place's current link; null for an account place. Managers only. */
+  link?: SigningRoundSignerLink | null;
+}
+
+export interface SigningRoundSignerLink {
+  status: "sending" | "sent" | "delivery_failed" | "expired" | "used" | "cancelled";
+  sent_at: string | null;
+  expires_at: string | null;
+  used_at: string | null;
+  links_sent: number;
+  /** A new link may be sent now. */
+  can_resend: boolean;
 }
 
+/**
+ * One signer to prepare, in the order of the places: an account id (or
+ * `{ app_user_id }`), or someone without an account, who is emailed a
+ * personal signing link valid for 24 hours when the round is confirmed.
+ * Anyone holding that link can sign.
+ */
+export type SigningRoundSignerInput = string | { app_user_id: string } | { name: string; email: string };
+
 export interface SigningRound {
   id: string;
   file_id: string;
@@ -5221,13 +5260,25 @@ export function useSigningRound(fileId: string | null | undefined): {
   loading: boolean;
   error: SigningRoundError | null;
   refresh(): Promise<void>;
-  /** `signerIds` in the order their places appear on the signature page. Resolves to the DRAFT. */
-  prepare(signerIds: string[]): Promise<SigningRound>;
+  /** `signers` in the order their places appear on the signature page. Resolves to the DRAFT. */
+  prepare(signers: SigningRoundSignerInput[]): Promise<SigningRound>;
   preparedFile(): Promise<SigningRoundPreparedFile>;
   /** Resolves to the OPEN round. */
   confirm(): Promise<SigningRound>;
   /** Resolves to the round it ended, with status "CANCELLED". */
   cancel(): Promise<SigningRound>;
+  /**
+   * Replace an email place's link with a new one, sent to `email` when given
+   * (a corrected address). Offer it only where `link.can_resend` is true.
+   * Resolves to the round. Refusals: `SIGNING_LINK_RESEND_TOO_SOON` (with
+   * `retryAfter`), `SIGNING_LINK_RESEND_IN_PROGRESS`,
+   * `SIGNING_LINK_LIMIT_REACHED`, `SIGNING_LINK_BUDGET_EXCEEDED`,
+   * `SIGNING_LINK_PLATFORM_LIMIT`, `INVALID_EMAIL`, `DUPLICATE_SIGNER`,
+   * `SIGNING_ROUND_NOT_OPEN`, `SIGNING_ROUND_CLOSED`, `ALREADY_SIGNED`, and
+   * the hook's own `NOT_SUPPORTED` when the host's filestore client predates
+   * sending links.
+   */
+  resendLink(signerId: string, options?: { email?: string }): Promise<SigningRound>;
   /** An action is running; another one is refused with `ACTION_IN_PROGRESS`. */
   busy: boolean;
 };

package/dist/index.js

@@ -135,6 +135,7 @@ export {
 } from "./stats-hooks.js";
 // sc-11025 — one source, bound to how each platform says the app is in front.
 export { useFileSignature, useSigningRounds, useSigningRound } from "./signing-hooks.js";
+export { bankIdAppUrl } from "./bankid-app.js";
 export { useOnlineMembers, useOnlineVisibility } from "./presence.js";
 // sc-6607 — `<Overlay>` is one shared component (./overlay-view.js) bound to
 // each platform's primitives, so a widget's modal escapes its container box

package/dist/index.native.js

@@ -133,6 +133,7 @@ export {
 } from "./stats-hooks.js";
 // sc-11025 — see the note on the web mirror in ./index.js.
 export { useFileSignature, useSigningRounds, useSigningRound } from "./signing-hooks.js";
+export { bankIdAppUrl } from "./bankid-app.js";
 export { useOnlineMembers, useOnlineVisibility } from "./presence.native.js";
 // sc-6607 — see the note on the web mirror in ./index.js.
 export { Overlay } from "./overlay.native.js";

package/dist/signing-hooks.js

@@ -15,11 +15,13 @@ import {
   indexOverview,
   readRefusalDetail,
   reportedRoundId,
+  resendLinkOptions,
   roundChangedUnderneath,
   signOrderStateAfterAnswer,
   signOrderStateAfterCancel,
   signOrderStateAfterInitiate,
   signedOrderState,
+  signerListForPrepare,
   uniqueFileIds,
 } from "./signing-state.js";
 
@@ -209,6 +211,10 @@ const previewRequired = () =>
 const actionInProgress = () =>
   localRefusal("ACTION_IN_PROGRESS", "Another change to this signing round is still in progress. Try again in a moment.");
 const noFile = () => localRefusal("VALIDATION", "Choose a document first.");
+const noResend = () =>
+  localRefusal("NOT_SUPPORTED", "Sending a new link is not available in this version of the app.");
+const badSignerList = () =>
+  localRefusal("VALIDATION", "Each signer needs to be a person in the app, or a name and an email address.");
 
 function signingRoundsClientOrThrow(ctx, hookName) {
   const rounds = ctx.filestore && ctx.filestore.signingRounds;
@@ -289,19 +295,24 @@ export function useSigningRounds(fileIds) {
 /**
  * One file's current signing round and the actions of whoever manages the
  * file's folder. Returns `{ round, loading, error, refresh, prepare,
- * preparedFile, confirm, cancel, busy }`.
+ * preparedFile, confirm, cancel, resendLink, busy }`.
  *
- * `prepare(signerIds)` drafts a round for those people, in the order their
- * places appear on the signature page; `preparedFile()` answers `{ url,
- * sha256, expires_at, size_bytes }` for the draft's document; `confirm()`
- * opens the round for the document that `preparedFile()` last returned, so it
- * needs no argument; `cancel()` ends a draft or an open round and resolves to
- * the cancelled round. One action runs at a time: while `busy` is true another
- * one is refused with code `ACTION_IN_PROGRESS`, never queued. A refused
- * action sets `error` and rejects with it: `code` and `message` come from the
- * server, `errors` has one entry per refused signer, `retryAfter` is the
- * seconds to wait. When the refusal means the round is no longer what was
- * shown, the round is read again.
+ * `prepare(signers)` drafts a round for those people, in the order their
+ * places appear on the signature page: each is an account id (or
+ * `{ app_user_id }`), or `{ name, email }` for someone without an account,
+ * who is emailed a 24-hour signing link once the round is confirmed;
+ * `preparedFile()` answers `{ url, sha256, expires_at, size_bytes }` for the
+ * draft's document; `confirm()` opens the round for the document that
+ * `preparedFile()` last returned, so it needs no argument; `cancel()` ends a
+ * draft or an open round and resolves to the cancelled round;
+ * `resendLink(signerId, { email })` replaces an email place's link with a new
+ * one, sent to the corrected address when given. One action runs at a time:
+ * while `busy` is true another one is refused with code `ACTION_IN_PROGRESS`,
+ * never queued. A refused action sets `error` and rejects with it: `code` and
+ * `message` come from the server, `errors` has one entry per refused signer
+ * (with `index`, its place in the list sent), `retryAfter` is the seconds to
+ * wait. When the refusal means the round is no longer what was shown, the
+ * round is read again.
  */
 export function useSigningRound(fileId) {
   const ctx = useWidgetContextOrThrow("useSigningRound");
@@ -395,10 +406,12 @@ export function useSigningRound(fileId) {
   );
 
   const prepare = useCallback(
-    (signerIds) =>
+    (signers) =>
       run(async (rounds, _round, forFile) => {
         if (!forFile) throw noFile();
-        const draft = await rounds.prepare(forFile, signerIds);
+        const list = signerListForPrepare(signers);
+        if (!list) throw badSignerList();
+        const draft = await rounds.prepare(forFile, list);
         return { value: draft, round: draft };
       }),
     [run],
@@ -438,6 +451,18 @@ export function useSigningRound(fileId) {
     [run],
   );
 
+  const resendLink = useCallback(
+    (signerId, options) =>
+      run(async (rounds, round) => {
+        if (!round) throw noRound();
+        // A filestore client older than 0.14.0 has no resendLink.
+        if (typeof rounds.resendLink !== "function") throw noResend();
+        const resent = await rounds.resendLink(round.id, signerId, resendLinkOptions(options));
+        return { value: resent, round: resent };
+      }),
+    [run],
+  );
+
   return {
     round: current.round,
     loading: Boolean(fileId) && (!current.settled || reading),
@@ -447,6 +472,7 @@ export function useSigningRound(fileId) {
     preparedFile,
     confirm,
     cancel,
+    resendLink,
     busy,
   };
 }

package/dist/signing-state.js

@@ -71,8 +71,9 @@ export function signOrderStateAfterCancel(previous, answer) {
 
 /**
  * The parts of a refusal a widget shows beside its message, as the filestore
- * client put them on its error: one entry per refused signer (`app_user_id`,
- * `message`, and for a name `reason` and `characters`), and how many seconds
+ * client put them on its error: one entry per refused signer (`index`, its
+ * place in the list that was sent, `app_user_id` for an account, `message`,
+ * and for a name `reason` and `characters`), and how many seconds
  * to wait before trying again. An error from anywhere else has neither.
  */
 export function readRefusalDetail(err) {
@@ -81,6 +82,39 @@ export function readRefusalDetail(err) {
   return { errors, retryAfter: typeof wait === "number" && Number.isFinite(wait) && wait >= 0 ? wait : null };
 }
 
+const nonEmptyString = (value) => typeof value === "string" && value.trim() !== "";
+const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+/** One prepare entry as the filestore client takes it, or null when it is neither form. */
+function signerForPrepare(signer) {
+  if (nonEmptyString(signer)) return signer;
+  if (!isObject(signer)) return null;
+  const keys = Object.keys(signer).sort().join(",");
+  if (keys === "app_user_id" && nonEmptyString(signer.app_user_id)) return signer.app_user_id;
+  if (keys === "email,name" && nonEmptyString(signer.name) && nonEmptyString(signer.email)) {
+    return { name: signer.name.trim(), email: signer.email.trim() };
+  }
+  return null;
+}
+
+/**
+ * The signers of a prepare, in their order, as the filestore client takes
+ * them: an account as its id (a list of ids alone keeps the request older
+ * servers read), someone without an account as `{ name, email }` trimmed.
+ * Null when an entry is neither an id, `{ app_user_id }` nor `{ name, email }`.
+ */
+export function signerListForPrepare(signers) {
+  if (!Array.isArray(signers)) return null;
+  const list = signers.map(signerForPrepare);
+  return list.includes(null) ? null : list;
+}
+
+/** The body of a new link: a corrected `email` when one is given, otherwise nothing. */
+export function resendLinkOptions(options) {
+  const email = isObject(options) && typeof options.email === "string" ? options.email.trim() : "";
+  return email ? { email } : {};
+}
+
 // The round is no longer what the widget is showing: read it again.
 const ROUND_CHANGED_CODES = new Set([
   "SIGNING_ROUND_EXPIRED",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.240.0",
+  "version": "0.243.0",
   "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

@@ -1624,10 +1624,30 @@ const HOOKS = [
     signature: "useFileSignature(fileId, existingSignatureId)",
     optionalArgs: ["existingSignatureId"],
     description:
-      "Drive a BankID signing flow for one Filestore file. initiate() opens a " +
-      "sign order (the backend hashes the bytes + binds the digest), refresh() " +
-      "polls (fresh QR while pending — render with the Image primitive), " +
-      "cancel() aborts, verify() returns the offline verdict. Pass " +
+      "Drive a BankID signing flow for one Filestore file of ANY type in a " +
+      "shared (project or public) space; a personal file is refused with " +
+      "NOT_SIGNABLE. Outside a signing round the signature is kept beside " +
+      "the file and the file is not changed; a PDF in an open signing round " +
+      "gets the signature added to the document itself, which is then " +
+      "sealed against changes (see useSigningRounds). initiate() opens a " +
+      "sign order (the backend hashes the bytes + binds the digest). The " +
+      "hook does NOT poll by itself: while status is 'pending' call " +
+      "refresh() every 2 seconds (a setInterval in an effect, cleared when " +
+      "status leaves 'pending' or the widget unmounts); each answer carries " +
+      "a fresh qr frame. Offer both ways to sign: BankID on THIS device is a " +
+      "button whose onPress calls Linking.openURL(bankIdAppUrl(autoStartToken)), " +
+      "shown only while autoStartToken is set; BankID on ANOTHER device is " +
+      "the qr rendered with the Image primitive, replaced by each poll's " +
+      "frame. cancel() aborts, verify() returns the offline verdict: valid " +
+      "is the BankID signature itself; content_status 'unchanged' means the " +
+      "file still holds what was signed, 'changed' that it was altered " +
+      "since, 'unavailable' that it could not be checked now; " +
+      "signed_by_others_since counts later signatures in a round's PDF; " +
+      "seal.status is 'valid' (protected against changes), 'invalid' or " +
+      "'certificate_revoked' (do not rely on the copy), 'unavailable' (try " +
+      "later) or 'not_applicable' (a signature kept beside the file). Say " +
+      "each in plain words and never show a green mark when any of them " +
+      "failed. Pass " +
       "existingSignatureId for an already-signed file to seed the complete " +
       "state + verify() without re-signing. autoStartToken is set only while " +
       "opening BankID can still help (null once the user has signed or the " +
@@ -1644,19 +1664,21 @@ const HOOKS = [
       "ctx.filestore.signatures.{initiate,status,cancel,verify}.",
     returnShape: {
       status: "'pending' | 'complete' | 'failed' | 'cancelled' | null",
-      qr: "string | null  // PNG data-URL of the animated BankID QR",
-      autoStartToken: "string | null",
+      qr: "string | null  // PNG data-URL of the animated BankID QR; render with <Image>, refresh() every 2 s while pending for the next frame",
+      autoStartToken: "string | null  // BankID on this device: a button calling Linking.openURL(bankIdAppUrl(autoStartToken))",
       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",
+      verdict:
+        "{ valid, checks, content_status: 'unchanged' | 'changed' | 'unavailable', signed_by_others_since: number | null, " +
+        "seal: { status: 'valid' | 'invalid' | 'certificate_revoked' | 'unavailable' | 'not_applicable', sealed_at, certificate_revoked_at, ... }, ... } | null",
       loading: "boolean",
       error: "PermissionError | null  // { code, message, retryable }",
       initiate: "() => Promise<{ signature_id, qr, auto_start_token, status, hint_code?, message? }>",
-      refresh: "() => Promise<void>",
+      refresh: "() => Promise<void>  // the hook never polls by itself",
       cancel: "() => Promise<{ status, hint_code?, message?, signer_name?, signed_at? } | undefined>",
       verify: "() => Promise<verdict>",
     },
@@ -1667,10 +1689,14 @@ const HOOKS = [
     name: "useFileSignatures",
     signature: "useFileSignatures(fileIds)",
     description:
-      "Batch 'is this file signed?' lookup for a set of file ids. Returns a map " +
-      "of each signed, accessible file id to its latest signature; unsigned " +
-      "files are absent. Lets a file browser mark already-signed files in one " +
-      "request. Reads ctx.filestore.signatures.list and unwraps { data, meta }.",
+      "Batch 'have I signed this file?' lookup for a set of file ids. Returns " +
+      "a map of each file the SIGNED-IN USER has signed (and can still see) " +
+      "to their own latest signature; a file only others have signed, or " +
+      "nobody has, is absent, so it never tells who else signed. Pass a " +
+      "file's signature_id to useFileSignature(fileId, signatureId) to show " +
+      "and verify it. Who has signed is useFileRoster(), for someone who " +
+      "manages the folder. Reads ctx.filestore.signatures.list and unwraps " +
+      "{ data, meta }.",
     returnShape: {
       signaturesByFileId:
         "{ [fileId]: { signature_id, signer_name, signed_at } }",
@@ -1709,8 +1735,10 @@ const HOOKS = [
     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 " +
+      "in a list, in one batched request. A signing round fixes a PDF in the " +
+      "project space and a list of signers (other file types are signed one " +
+      "person at a time with useFileSignature() and no round): 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, " +
@@ -1719,7 +1747,8 @@ const HOOKS = [
       "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, " +
+      "for them. Each signature is added to the PDF itself and the document " +
+      "is sealed against changes. 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 " +
@@ -1747,15 +1776,27 @@ const HOOKS = [
     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 " +
+      "manages the file's folder. prepare(signers) drafts a round for those " +
+      "people, their places on the signature page in the order given: each " +
+      "entry is an account id from useFileRoster() (or { app_user_id }), or " +
+      "{ name, email } for someone without an account, who is emailed a " +
+      "personal BankID signing link valid for 24 hours once the round is " +
+      "confirmed (anyone holding that link can sign, so say so before " +
+      "sending); 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 " +
+      "round (status 'CANCELLED'); round is then null. " +
+      "resendLink(signerId, { email }) replaces an email place's link with " +
+      "a new one (the old one stops working), sent to the corrected email " +
+      "when given, and resolves to the round; offer it only where the " +
+      "place's link.can_resend is true. A manager sees each place's id, kind " +
+      "('app_user' | 'email'), email, signed_as (the name BankID verified) " +
+      "and link ({ status: 'sending' | 'sent' | 'delivery_failed' | " +
+      "'expired' | 'used' | 'cancelled', sent_at, expires_at, used_at, " +
+      "links_sent, can_resend }, null for an account place). 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 " +
@@ -1763,27 +1804,40 @@ const HOOKS = [
       "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 " +
+      "one entry per refused signer ({ index, app_user_id, message, reason, " +
+      "characters }; index is the entry's place in the list sent), " +
+      "retryAfter is the seconds to wait. resendLink is refused with " +
+      "SIGNING_LINK_RESEND_TOO_SOON (with retryAfter), " +
+      "SIGNING_LINK_RESEND_IN_PROGRESS, SIGNING_LINK_LIMIT_REACHED, " +
+      "SIGNING_LINK_BUDGET_EXCEEDED, SIGNING_LINK_PLATFORM_LIMIT, " +
+      "INVALID_EMAIL, DUPLICATE_SIGNER, SIGNING_ROUND_NOT_OPEN, " +
+      "SIGNING_ROUND_CLOSED or ALREADY_SIGNED, and by the hook itself with " +
+      "NOT_SUPPORTED when the host's filestore client cannot send links. 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 " +
+      "start one, and when it is false say that document signing is not " +
+      "turned on for this workspace and that the platform turns it on. " +
+      "Rounds take PDFs in the project space only (NOT_A_PDF otherwise). A " +
+      "signer signs their place with useFileSignature(fileId), the same " +
+      "BankID flow as any file. 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",
+        "signers: { name, position, app_user_id?, signed?, signed_at?, signed_as?, id?, kind?: 'app_user' | 'email', email?, " +
+        "link?: { status: 'sending' | 'sent' | 'delivery_failed' | 'expired' | 'used' | 'cancelled', sent_at, expires_at, used_at, links_sent, can_resend } | null }[] } | null",
       loading: "boolean",
       error: "PermissionError | null  // { code, message, retryable, errors, retryAfter }",
       refresh: "() => Promise<void>",
-      prepare: "(signerIds: string[]) => Promise<round>  // status 'DRAFT'",
+      prepare: "(signers: (string | { app_user_id } | { name, email })[]) => 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'",
+      resendLink: "(signerId: string, options?: { email?: string }) => Promise<round>  // a new link for an email place",
       busy: "boolean  // an action is running; another one is refused with ACTION_IN_PROGRESS",
     },
     requiredContextSlice: ["filestore.signingRounds"],
@@ -2598,8 +2652,9 @@ const HOOKS = [
       "with the Image primitive) and the hook then POLLS to completion itself " +
       "(pollIntervalMs, default 1000; pass 0 to drive refresh() yourself); " +
       "cancel() aborts; reset() clears the flow. autoStartToken opens the " +
-      "provider app on the SAME device (bankid:///?autostarttoken=<token>" +
-      "&redirect=null). On complete, `identity` is { provider, name, given_name, " +
+      "provider app on the SAME device: Linking.openURL(bankIdAppUrl(" +
+      "autoStartToken)) opens bankid:///?autostarttoken=<token>&redirect=null. " +
+      "On complete, `identity` is { provider, name, given_name, " +
       "surname, personal_number_masked, subject_hash, identified_at } — there is " +
       "NO raw personal number by design: write personal_number_masked " +
       "(\"19900101-****\") and, if you need to trace the proof, identificationId. " +
@@ -3888,7 +3943,7 @@ const WIDGET_CONTEXT_SHAPE = {
       "{ 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: { 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) }, " +
+      "signingRounds: { overview(fileIds), list(fileId, query), get(roundId), prepare(fileId, signers), preparedFile(roundId), confirm(roundId, preparedSha256), cancel(roundId), resendLink(roundId, signerId, { email }) }, " +
       "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,
@@ -6088,7 +6143,15 @@ const CONTRACT = deepFreeze({
   //    `sectionRef` propertySchema type gives the author a section picker.
   // 1.194.0: more permissive (sc-11945) — a datastoreTemplate takes 100
   //    tables, 200 columns, 100 rows per table, 20000 cells and 32 roles.
-  version: "1.194.0",
+  // 1.195.0: additive (sc-11879) — `useSigningRound().prepare` takes
+  //    `{ name, email }` entries for signers without an account, and
+  //    `resendLink(signerId, { email })` sends such a signer a new link.
+  //    The manager's places carry id, kind, email and link.
+  // 1.197.0: additive (sc-12063) — new export `bankIdAppUrl(autoStartToken)`,
+  //    the link that opens BankID on this device. Signing hooks document
+  //    polling, the two ways to start BankID and how to read a verdict;
+  //    useFileSignatures is described as the caller's own signatures.
+  version: "1.197.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,