API reference

01 / Module surface

Exports

// These imports compile against the approved 0.5.0 beta release.
import SavyScan, { create, version } from "@savyscan/web-sdk";
import "@savyscan/web-sdk/styles.css";

// 0.5.0-beta.7 source also provides a named SavyScanError export.
const ErrorType = SavyScan.SavyScanError;

02 / Configuration

create(options)

Creates an SDK-owned root under document.body by default. Call it after the body exists, or provide a valid mount target. The option set below is shared by 0.4.0 and 0.5.0-beta.7; validation descriptions refer to the beta.

Privacy-safe diagnostics

onDiagnostic(event) {
  // Closed schema: no pixels, text, references, filenames, URLs,
  // device identifiers, wall-clock timestamps, or host metadata.
  telemetry.record(event);
}

Every event includes schemaVersion, sdkVersion, name, session-relative elapsedMs rounded to 100 ms, and pageCount. Applicable events may add only captureMode, automaticCapture, cameraAvailable, completed, errorCode, or recoverable. Callback failures are ignored and cannot interrupt scanning.

Advanced automatic-capture controls

03 / Instance

Methods

open(options?)

Shows the scanner, locks body scrolling, makes background siblings inert, and begins asynchronous OpenCV and camera setup. It returns void, throws after destruction, and is a no-op for valid options if already open.

scanner.open({
  referenceLabel: "Purchase Order",
  referenceNumber: "5C.143430",
  returnFocusElement: launchButton,
});

The 0.5.0-beta.7 source validates open(options) before it mutates session state. References may be strings or finite numbers, returnFocusElement is an element or null, and a session-only maxPages must be a positive safe integer. The deprecated purchaseOrderNumber input remains accepted for backward compatibility.

close({ completed = false }?)

Stops the camera, clears pages and canvases, revokes SDK-owned object URLs, hides the interface, and restores page state. Consumers normally call close(); completed close is primarily the SDK’s internal success path.

destroy()

Idempotently closes if necessary, removes listeners, clears resources, and removes an SDK-owned root. The instance cannot reopen.

04 / Completion value

Result

type SavyScanResult = {
  pdfBlob: Blob;       // application/pdf
  previewBlob: Blob;   // image/jpeg — first corrected page
  pageCount: number;
};

previewBlob is not a PDF preview. It is the first corrected page as JPEG, useful when a mobile browser cannot render the PDF Blob inline.

05 / Event order

Callbacks

06 / Appearance

Labels and theme

Supported labels are title (default “SavyScan”) and cameraPlaceholder (default “Camera preview will appear here.”).

07 / 0.5.0-beta.7 contract

Structured validation and errors

The 0.5.0 beta source validates create(options) and open(options) synchronously, before UI, camera, or session side effects. It rejects unknown top-level and nested keys instead of coercing or silently ignoring them. Reported operational failures use the same error type through onError; camera capability errors may be delivered before open() returns.

{
  name: "SavyScanError",
  code: "CONFIG_INVALID_VALUE",
  message: "maxPages must be at least 1.",
  field: "maxPages",
  recoverable: false
}

Use code and field for program flow; messages may improve between releases. recoverable means the same instance can continue or retry. The optional underlying cause is deliberately omitted by toJSON(), and configured values or URLs are not copied into error messages.