@colixsystems/widget-sdk 0.240.0 → 0.241.0

package/README.md

@@ -84,7 +84,18 @@ 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.241.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.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/contract.cjs

@@ -1747,15 +1747,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,8 +1775,15 @@ 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 " +
@@ -1776,14 +1795,16 @@ const HOOKS = [
     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"],
@@ -3892,7 +3913,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 +6113,11 @@ 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.
+  version: "1.195.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1747,15 +1747,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,8 +1775,15 @@ 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 " +
@@ -1776,14 +1795,16 @@ const HOOKS = [
     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"],
@@ -3888,7 +3909,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 +6109,11 @@ 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.
+  version: "1.195.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -5111,6 +5111,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 +5174,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 +5253,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/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.241.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

@@ -1747,15 +1747,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,8 +1775,15 @@ 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 " +
@@ -1776,14 +1795,16 @@ const HOOKS = [
     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"],
@@ -3888,7 +3909,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 +6109,11 @@ 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.
+  version: "1.195.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,