@signosoft/signpad-js 0.5.2 → 0.6.0

package/README.md

@@ -59,14 +59,13 @@ Without a valid lease, the component can still render, but driver initialization
 async function fetchLease() {
   try {
     const response = await fetch(
-      "https://test.signosoft.com/api/v1/driver/leases",
+      "https://test.signosoft.com/api/v1/public/driver-leases/create",
       {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
-          licenceKey: "YOUR-LICENSE-KEY",
+          token: "YOUR-LICENSE-TOKEN",
           validityHours: 24,
-          port: 4204,
         }),
       },
     );
@@ -245,14 +244,13 @@ export class AppComponent implements AfterViewInit {
   public async fetchLease(): Promise<any> {
     try {
       const response = await fetch(
-        "https://test.signosoft.com/api/v1/driver/leases",
+        "https://test.signosoft.com/api/v1/public/driver-leases/create",
         {
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify({
-            licenceKey: "YOUR-LICENSE-KEY",
+            token: "YOUR-LICENSE-TOKEN",
             validityHours: 24,
-            port: 4204,
           }),
         },
       );
@@ -331,14 +329,13 @@ import type { SignpadConfig } from "@signosoft/signpad-js";
 async function fetchLease() {
   try {
     const response = await fetch(
-      "https://test.signosoft.com/api/v1/driver/leases",
+      "https://test.signosoft.com/api/v1/public/driver-leases/create",
       {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
-          licenceKey: "YOUR-LICENSE-KEY",
+          token: "YOUR-LICENSE-TOKEN",
           validityHours: 24,
-          port: 4204,
         }),
       },
     );
@@ -439,13 +436,12 @@ const signpadConfig = ref<SignpadConfig>({ lease: undefined });
 
 const fetchLease = async () => {
   try {
-    const response = await fetch("https://test.signosoft.com/api/v1/driver/leases", {
+    const response = await fetch("https://test.signosoft.com/api/v1/public/driver-leases/create", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
-        licenceKey: "YOUR-LICENSE-KEY",
+        token: "YOUR-LICENSE-TOKEN",
         validityHours: 24,
-        port: 4204,
       }),
     });
 
@@ -526,14 +522,13 @@ pad.config = {
 const fetchLease = async () => {
   try {
     const response = await fetch(
-      "https://test.signosoft.com/api/v1/driver/leases",
+      "https://test.signosoft.com/api/v1/public/driver-leases/create",
       {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
-          licenceKey: "YOUR-LICENSE-KEY",
+          token: "YOUR-LICENSE-TOKEN",
           validityHours: 24,
-          port: 4204,
         }),
       },
     );
@@ -676,6 +671,7 @@ The complete list of keys that can be translated is maintained in `src/i18n/en.j
 | `CONNECTION_ERROR`           | Connection error.                                   |
 | `ERROR_DISCONNECTION`        | Error during disconnection.                         |
 | `ERROR_INSTANTIATING_DRIVER` | Error instantiating driver.                         |
+| `INSUFFICIENT_TOKENS`        | Not enough tokens to sign. Reconnecting…            |
 | `INVALID_LICENSE_KEY`        | Invalid license key.                                |
 | `READY_TO_CONNECT`           | Ready to connect.                                   |
 | `SIGNPAD_DETECTED`           | Signpad detected. Click 'Connect Signpad' to begin. |
@@ -711,10 +707,28 @@ Standard event listeners triggered _after_ specific actions. Useful for observin
 | `onOk`         | `event: CustomEvent<ISignatureConfirmationData>` | Dispatched when signature is confirmed.                                                            |
 | `onClear`      | `event: CustomEvent<void>`                       | Dispatched when the canvas has been cleared.                                                       |
 | `onCancel`     | `event: CustomEvent<void>`                       | Dispatched when the user aborts the session.                                                       |
-| `onError`      | `event: CustomEvent<Error>`                      | Dispatched on critical failures (lease, driver, connection, etc.).                                 |
+| `onError`      | `event: CustomEvent<ISignpadErrorDetail>`        | Dispatched on critical failures (lease, driver, connection, billing, etc.).                        |
 
 > `actionHandlers` and `eventCallbacks` are separate hooks and can both be configured.
 
+#### 🚨 `onError` payload (`ISignpadErrorDetail`)
+
+```typescript
+{
+  category: SignpadErrorCategory; // BILLING_DENIED | NETWORK | OTHER
+  message: string; // error.message, for convenience
+  error: Error; // the original error
+}
+```
+
+`category` also drives automatic recovery:
+
+- **`BILLING_DENIED`** — the lease has run out of signing credits/tokens. Signing automatically restarts a few seconds after the error is shown.
+- **`OTHER`** — any other recoverable failure (e.g. a driver hiccup, a cancelled device picker). Signing automatically restarts the same way as `BILLING_DENIED`.
+- **`NETWORK`** — a connectivity problem (lease fetch failed, device physically disconnected, origin validation failed). The error stays shown; signing does **not** auto-restart, since retrying on a timer can't fix a network or configuration problem — the user (or your app) must retry manually, e.g. via `connect()`.
+
+> **Migration note (breaking payload shape change):** `event.detail` used to be the raw `Error`. It is now `ISignpadErrorDetail`; use `event.detail.error` for the original `Error` instance. `event.detail.message` still works unchanged.
+
 ---
 
 ### 💡 Example Implementation
@@ -923,7 +937,17 @@ The component progresses through a finite set of states, exposed via the `Signpa
 | `PROCESSING_CANCEL`            | `"processing_cancel"`            | Cancel action is being processed.                                                                                                                                   |
 | `DISCONNECTING`                | `"disconnecting"`                | Disconnect in progress.                                                                                                                                             |
 | `DISCONNECTED`                 | `"disconnected"`                 | Component is idle and disconnected.                                                                                                                                 |
-| `ERROR`                        | `"error"`                        | An unrecoverable error occurred (see `onError` callback).                                                                                                           |
+| `ERROR`                        | `"error"`                        | An error occurred (see `onError` callback). Signing automatically restarts a few seconds later unless the error's `category` is `NETWORK`.                         |
+
+### 🚨 `SignpadErrorCategory`
+
+Also importable from `@signosoft/signpad-js`, carried on the `onError` payload (see [`onError` payload](#-onerror-payload-isignpaderrordetail) above):
+
+| Value            | Value string       | Auto-restarts signing? |
+| :--------------- | :------------------ | :---------------------- |
+| `BILLING_DENIED` | `"billing_denied"` | Yes                     |
+| `NETWORK`        | `"network"`         | No                       |
+| `OTHER`          | `"other"`           | Yes                     |
 
 ---
 

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { ConnectionMode } from '@signosoft/tablet-driver';
 import { CSSResult } from 'lit';
 import { LitElement } from 'lit';
 import { TemplateResult } from 'lit-html';
@@ -176,11 +177,12 @@ declare class ConnectionManager {
     /**
      * Initiates the connection process to a physical device or a mouse fallback.
      *
-     * @param autoConnect - If true, attempts to connect without showing a device selection dialog.
+     * @param autoConnect - Connect mode: "manual" opens the browser device selection
+     *   dialog; "auto"/"hotplug" attempt already-authorized devices silently.
      * @param allowFallback - If true, enables mouse/pointer input if no physical device is found.
      * @returns A promise resolving to true if connection (or fallback) was successful.
      */
-    connect(autoConnect?: boolean, allowFallback?: boolean): Promise<boolean>;
+    connect(autoConnect?: ConnectionMode, allowFallback?: boolean): Promise<boolean>;
     /**
      * Terminates the connection with the device and cleans up the driver instance.
      * @returns Resolves when disconnection completes.
@@ -239,6 +241,20 @@ declare class ConnectionManager {
      * @returns Resolves when the driver is initialized.
      */
     initWithLease(lease: any): Promise<void>;
+    /**
+     * Called by the driver when the lease has run out of signing credits.
+     * @param detail - Driver-provided description of the denial.
+     * @returns Always false — declines the driver's own retry; signpad-js's
+     *   auto-restart (triggered by the ERROR transition below) handles recovery.
+     */
+    private handleBillingDenied;
+    /**
+     * Called by the driver when the billing check itself fails (e.g. the
+     * billing server is unreachable). Treated as a network error.
+     * @param detail - Driver-provided description of the failure.
+     * @returns Always false — see handleBillingDenied.
+     */
+    private handleBillingError;
     isFallback(deviceInfo: any | null, isDeviceConnected: boolean, includeDisconnected: boolean): boolean;
     /**
      * Normalizes device info to always include deviceName.
@@ -286,7 +302,7 @@ export declare interface IEventCallbacks {
     onOk?: (event: CustomEvent<ISignatureConfirmationData>) => void;
     onClear?: (event: CustomEvent<void>) => void;
     onCancel?: (event: CustomEvent<void>) => void;
-    onError?: (event: CustomEvent<Error>) => void;
+    onError?: (event: CustomEvent<ISignpadErrorDetail>) => void;
 }
 
 export declare interface ILanguageOptions {
@@ -358,6 +374,12 @@ export declare interface ISignatureTabletMeta {
     [key: string]: any;
 }
 
+export declare interface ISignpadErrorDetail {
+    category: SignpadErrorCategory;
+    message: string;
+    error: Error;
+}
+
 export declare interface ITranslationSet {
     [key: string]: string;
 }
@@ -520,7 +542,8 @@ export declare class SignosoftSignpad extends LitElement {
     dispatch(name: string, detail?: any): void;
     /**
      * Attempts to establish a connection with a signature tablet.
-     * @param autoConnect - If true, tries to connect without showing a device picker.
+     * @param autoConnect - Connect mode: "manual" opens the browser HID picker;
+     *   "auto"/"hotplug" silently try already-authorized devices (see `ConnectionMode`).
      * @param allowFallback - If true, enables mouse/touch signing if no device is found.
      * @returns A promise resolving to true if connection (or fallback) succeeded.
      */
@@ -560,8 +583,24 @@ export declare class SignosoftSignpad extends LitElement {
      * - if physical is not available, allow fallback as a secondary attempt
      */
     connect: () => Promise<void>;
+    /**
+     * If currently in mouse fallback, tears that session down seamlessly
+     * (no DISCONNECTED UI flash) so a physical-device connect attempt can
+     * proceed cleanly.
+     */
     private prepareForManualConnect;
+    /**
+     * First step of the manual `connect()` flow: silently retries an
+     * already-authorized device (no HID picker) using "auto" mode.
+     * `allowFallback=false` ensures we only treat a real physical reconnect as success.
+     */
     private tryAuthorizedManualConnect;
+    /**
+     * Second step of the manual `connect()` flow, run only when the silent
+     * attempt above fails: opens the browser HID picker ("manual" mode) so
+     * the user can grant access to a new device. If the user cancels or no
+     * device is selected, falls back to one more silent "auto" attempt.
+     */
     private tryInteractiveManualConnectFallback;
     /**
      * UI disconnect action: delegates to the public disconnect method.
@@ -611,6 +650,19 @@ export declare class SignosoftSignpad extends LitElement {
     private shouldScheduleImmediateRetry;
     private scheduleAutoConnectRetry;
     private clearAutoConnectQueue;
+    /**
+     * Schedules signing to restart automatically after a BILLING_DENIED/OTHER
+     * error, so the flow recovers without requiring a manual reconnect.
+     * NETWORK errors never reach this — they stay shown until the user retries.
+     * @param delayMs - How long to keep the error visible before restarting.
+     */
+    private scheduleErrorAutoRestart;
+    /**
+     * Restarts the signing session after an auto-recoverable error, respecting
+     * the connect/disconnect reentrancy lock so it never races a concurrent
+     * manual connect/disconnect or hotplug transition.
+     */
+    private restartSigningAfterError;
     private delay;
     /**
      * Disconnects current session without transitioning through DISCONNECTED UI.
@@ -657,6 +709,12 @@ export declare interface SignpadConfig {
     eventCallbacks?: IEventCallbacks;
 }
 
+export declare enum SignpadErrorCategory {
+    BILLING_DENIED = "billing_denied",
+    NETWORK = "network",
+    OTHER = "other"
+}
+
 export declare enum SignpadEventType {
     SIGN_PEN = "sign-pen",
     SIGN_OK = "sign-ok",
@@ -683,6 +741,7 @@ export declare enum SignpadMessage {
     CONNECTION_ERROR = "CONNECTION_ERROR",
     ERROR_DISCONNECTION = "ERROR_DISCONNECTION",
     ERROR_INSTANTIATING_DRIVER = "ERROR_INSTANTIATING_DRIVER",
+    INSUFFICIENT_TOKENS = "INSUFFICIENT_TOKENS",
     INVALID_LICENSE_KEY = "INVALID_LICENSE_KEY",
     READY_TO_CONNECT = "READY_TO_CONNECT",
     SIGNPAD_DETECTED = "SIGNPAD_DETECTED",
@@ -781,7 +840,15 @@ declare class StateManager {
      * @param error - Optional error object if transitioning to an ERROR state.
      * @returns void
      */
-    transitionTo(newState: SignpadState, messageKey?: string, error?: Error): void;
+    transitionTo(newState: SignpadState, messageKey?: string, error?: Error, category?: SignpadErrorCategory): void;
+    /**
+     * Heuristically classifies an error for auto-recovery decisions.
+     * Explicit categories (e.g. from billing hooks) should be passed to
+     * transitionTo directly rather than relying on this fallback.
+     * @param error - The error to classify.
+     * @returns The inferred error category.
+     */
+    private classifyError;
     /**
      * Updates the internal drawing flag. Triggers a UI update if the value changes.
      * @param started - Boolean indicating if the user has started drawing.