@colixsystems/widget-sdk 0.218.0 → 0.219.0

package/dist/index.d.ts

@@ -4567,3 +4567,237 @@ export function pressableLift(state?: {
 export function styleGroup(
   name: string,
 ): { dataSet: Record<string, string> } | undefined;
+
+/* ---------------------------------------------------------------------------
+ * Signing files with BankID, and signing rounds. All read `ctx.filestore`.
+ * Rows are snake_case verbatim.
+ * ------------------------------------------------------------------------- */
+
+/** Why a name cannot be shown on a signed document; `characters` lists what cannot be shown. */
+export interface SignatureNameRefusal {
+  reason: "empty" | "too_long" | "unsupported_characters" | "mixed_scripts";
+  characters: string[];
+}
+
+/** What a sign order answers when started, polled or cancelled. */
+export interface FileSignOrderAnswer {
+  status: "pending" | "complete" | "failed" | "cancelled";
+  signature_id?: string;
+  qr?: string | null;
+  auto_start_token?: string | null;
+  hint_code?: string | null;
+  message?: string;
+  signer_name?: string | null;
+  signed_at?: string | null;
+  name_refusal?: SignatureNameRefusal;
+}
+
+export interface FileSignatureVerdict {
+  valid: boolean;
+  checks: Record<string, boolean>;
+  reason: string | null;
+  signer_name: string | null;
+  personal_number: string | null;
+  signed_at: string | null;
+  content_status: "unchanged" | "changed" | "unavailable";
+  signed_by_others_since: number | null;
+  seal: Record<string, unknown>;
+}
+
+/**
+ * Drive a BankID signing flow for one file. Pass `existingSignatureId` for a
+ * file the user has already signed to show that state and `verify()` it
+ * without opening a new order. A null `fileId` makes every action a no-op.
+ */
+export function useFileSignature(
+  fileId: string | null | undefined,
+  existingSignatureId?: string | null,
+): {
+  status: "pending" | "complete" | "failed" | "cancelled" | null;
+  /** PNG data-URL of the animated BankID QR code while there is one to scan. */
+  qr: string | null;
+  /** Opens BankID on this device; null once the user has signed or the order has ended. */
+  autoStartToken: string | null;
+  message: string | null;
+  signerName: string | null;
+  signedAt: string | null;
+  /** Where the order stands. "sealing": signed, and being added to the document. */
+  hintCode: string | null;
+  /** Set when the order failed because the signer's name cannot be shown. */
+  nameRefusal: SignatureNameRefusal | null;
+  verdict: FileSignatureVerdict | null;
+  loading: boolean;
+  error: PermissionError | null;
+  initiate(): Promise<FileSignOrderAnswer | null>;
+  refresh(): Promise<void>;
+  /** Resolves to what became of the order, which is not always "cancelled". */
+  cancel(): Promise<FileSignOrderAnswer | undefined>;
+  verify(): Promise<FileSignatureVerdict | null>;
+};
+
+export interface FileSignatureSummary {
+  signature_id: string;
+  subject_file_id: string;
+  signer_name: string | null;
+  signed_at: string | null;
+}
+
+/** The signed-in user's own latest signature per file they have signed; other files are absent. */
+export function useFileSignatures(fileIds: string[] | null | undefined): {
+  signaturesByFileId: Record<string, FileSignatureSummary>;
+  loading: boolean;
+  error: Error | null;
+  refetch(): Promise<void>;
+};
+
+export interface FileRosterEntry {
+  app_user_id: string;
+  name: string;
+  signed: boolean;
+  signature_id: string | null;
+  signer_name: string | null;
+  signed_at: string | null;
+}
+
+/**
+ * Who is expected to sign a file, for someone who manages the file's folder:
+ * everyone who can open the folder, or the signers of the file's signing round
+ * in the order of their places on the signature page. `error` is set for a user who does not manage the folder.
+ */
+export function useFileRoster(
+  fileId: string | null | undefined,
+  options?: { limit?: number; offset?: number; enabled?: boolean },
+): {
+  roster: FileRosterEntry[];
+  total: number;
+  signedCount: number;
+  loading: boolean;
+  error: Error | null;
+  refetch(): Promise<void>;
+};
+
+/** One entry of a refused signing-round action: which signer, and why. */
+export interface SigningRefusalEntry {
+  field?: string;
+  message: string;
+  code?: string;
+  app_user_id?: string;
+  reason?: SignatureNameRefusal["reason"];
+  characters?: string[];
+}
+
+/** A refusal: the server's `code` and `message`, the refused signers, and the seconds to wait. */
+export type SigningRoundError = PermissionError & {
+  errors: SigningRefusalEntry[];
+  retryAfter: number | null;
+};
+
+export interface SigningRoundPlace {
+  position: number;
+  signed: boolean;
+  signed_at: string | null;
+}
+
+export interface SigningRoundSummary {
+  id: string;
+  status: "DRAFT" | "OPEN" | "COMPLETED";
+  signer_count: number;
+  /** For someone who manages the folder; null for a signer. */
+  signed_count: number | null;
+  /** The user's own place when they are one of the signers. */
+  my_place: SigningRoundPlace | null;
+  /** The round is open and the user's place is unsigned. Signers sign in any order. */
+  can_sign: boolean;
+}
+
+export interface FileSigningOverview {
+  file_id: string;
+  can_manage: boolean;
+  /**
+   * The user manages the folder, the file is a shared PDF and has no round.
+   * About the file and the user only: offer "prepare" when this AND
+   * `roundsEnabled` are true. Preparing can still be refused.
+   */
+  can_prepare: boolean;
+  /** Null without a round, and for a user who is neither a manager nor one of its signers. */
+  round: SigningRoundSummary | null;
+  /** "signing_round": the file cannot be changed. "signed": its content cannot be replaced. */
+  locked: "signing_round" | "signed" | null;
+}
+
+/**
+ * What the signed-in user may know about the signing round of each file, in
+ * one batched read. A file the user cannot see has no entry. `roundsEnabled`
+ * is false when the workspace cannot start signing rounds, null until known.
+ */
+export function useSigningRounds(fileIds: string[] | null | undefined): {
+  byFileId: Record<string, FileSigningOverview>;
+  roundsEnabled: boolean | null;
+  loading: boolean;
+  error: SigningRoundError | null;
+  refresh(): Promise<void>;
+};
+
+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;
+  signed?: boolean;
+  signed_at?: string | null;
+  /** The name BankID verified on this place. Managers only. */
+  signed_as?: string | null;
+}
+
+export interface SigningRound {
+  id: string;
+  file_id: string;
+  status: "DRAFT" | "OPEN" | "COMPLETED" | "CANCELLED";
+  prepared_size_bytes: number;
+  original_version: number | null;
+  created_by_id?: string | null;
+  created_at: string;
+  updated_at: string;
+  confirmed_at: string | null;
+  completed_at: string | null;
+  cancelled_at: string | null;
+  /** When an unconfirmed draft stops being usable; null once confirmed. */
+  expires_at: string | null;
+  signers: SigningRoundSigner[];
+}
+
+export interface SigningRoundPreparedFile {
+  url: string;
+  sha256: string;
+  expires_at: string;
+  size_bytes: number;
+}
+
+/**
+ * One file's current signing round and the actions of someone who manages the
+ * file's folder. `confirm()` opens the round for the document `preparedFile()`
+ * last returned and rejects with code `PREVIEW_REQUIRED` without it. A refused
+ * action sets `error` and rejects with it; code `SIGNING_ROUNDS_NOT_ENABLED`
+ * means the workspace cannot start signing rounds.
+ *
+ * One action runs at a time: while `busy` is true another one rejects at once
+ * with code `ACTION_IN_PROGRESS` and is not queued. `round` is never a
+ * cancelled round; `cancel()` resolves to the round it ended. When `fileId`
+ * or the signed-in user changes, `round` is null and `loading` true until the
+ * new answer arrives.
+ */
+export function useSigningRound(fileId: string | null | undefined): {
+  round: SigningRound | null;
+  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>;
+  preparedFile(): Promise<SigningRoundPreparedFile>;
+  /** Resolves to the OPEN round. */
+  confirm(): Promise<SigningRound>;
+  /** Resolves to the round it ended, with status "CANCELLED". */
+  cancel(): Promise<SigningRound>;
+  /** An action is running; another one is refused with `ACTION_IN_PROGRESS`. */
+  busy: boolean;
+};

package/dist/index.js

@@ -48,7 +48,6 @@ export {
   useFilestoreCreateFolder,
   useFilestoreCopy,
   useFilestoreDelete,
-  useFileSignature,
   useFileSignatures,
   useFileRoster,
   useFolderPermissions,
@@ -131,6 +130,7 @@ export {
   useInactiveUsers,
 } 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 { 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

@@ -48,7 +48,6 @@ export {
   useFilestoreCreateFolder,
   useFilestoreCopy,
   useFilestoreDelete,
-  useFileSignature,
   useFileSignatures,
   useFileRoster,
   useFolderPermissions,
@@ -129,6 +128,7 @@ export {
   useInactiveUsers,
 } 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 { useOnlineMembers, useOnlineVisibility } from "./presence.native.js";
 // sc-6607 — see the note on the web mirror in ./index.js.
 export { Overlay } from "./overlay.native.js";