# Browser SDK

> Every method of @esigncomply/browser, what each one records, and the requirements an integration has to respect.

Source: https://esigncomply.com/docs/sdk/browser

`@esigncomply/browser` is headless. It renders nothing. It observes elements you built, reports ceremony events from the signer's browser straight to the Esign Comply API, and tells your code whether the ceremony can proceed. It authenticates with the short-lived session client token (`esc_ct_...`) that your server gets from `POST /v1/sessions`. It never holds a secret API key.

The steps a ceremony needs come from the session, not from this page. Read `ceremony.remainingSteps()` and satisfy what it lists. The model behind the steps is in [The ceremony](https://esigncomply.com/docs/concepts/ceremony.md).

## Install

```bash
npm install @esigncomply/browser
```

```ts
import { EsignComply, EsignComplyError } from "@esigncomply/browser";
```

The package is an ES module with type declarations and no dependencies. It exports `EsignComply` (with `attach` and `version`), the `EsignComplyError` class, the `VERSION` string and the types on this page: `Ceremony`, `AttachOptions`, `Session`, `StepResult`, `Finding`, `CompleteResult`, `Verification`, `VerificationResult`, `AccessSample`, `PresentDocumentOptions`, `ObserveAssentOptions`, `RenewalElements`, `RequiredString`, `CeremonyEventMap` and the rest.

A script-tag build is also published at the versioned path `/sdk/v1/esigncomply.js` on `esigncomply.com`. It defines one global, `EsignComply`, with the same `attach` function, `version`, and `EsignComplyError`.

```html
<script src="https://esigncomply.com/sdk/v1/esigncomply.js"></script>
```

## Attach

### EsignComply.attach

```ts
const ceremony = await EsignComply.attach({ clientToken, apiUrl });
```

| Option | Type | Required | Description |
|---|---|---|---|
| `clientToken` | string | Yes | The `client_token` of the session your server created. Starts with `esc_ct_`. Kept in memory only. |
| `apiUrl` | string | No | Regional API base, for example `https://api.eu.esigncomply.com/v1`. Pass the `api_url` field of the session your server created. Default: `https://esigncomply.com/v1`. |

`attach` reads the session ID, the test or live flag and the expiry from the token itself. It then reads the session with `GET /v1/sessions/{id}` and records `client.attached` (tag `observed`). The event carries the SDK version and the page address without query string or fragment. Unless the session uses minimal capture it also carries the viewport size, the browser language and the time zone.

It resolves with a `Ceremony` object. It rejects with an `EsignComplyError`:

| Code | When |
|---|---|
| `invalid_request` | `attach` ran outside a browser (during server rendering). Raised in the browser SDK, `status` 0. |
| `invalid_api_key` | `clientToken` is not a session client token. Secret keys never go to the browser. Raised in the browser SDK, `status` 0, `param: "clientToken"`. |
| `client_token_expired` | The session has expired. Create a new session and attach again. |
| `domain_mismatch` | The page origin is outside the registered domain (live) or the test allowlist (test). |

Any other API or network error rejects the same way. A failed attach leaves nothing behind: listeners are removed and the token is forgotten.

`EsignComply.version` is the SDK version string. `ceremony.session` is the last known session object: `object`, `id`, `status`, `livemode`, `expires_at`, `assurance_level`, `signature_method`, `capture_mode`, `minimal_capture`, `required_steps`, `completed_steps`, `remaining_steps`, `documents`, `required_strings`, `record_id`, `purpose`, `locale` and, when the API returns it, `api_url`. The SDK updates `status`, `completed_steps`, `remaining_steps` and `record_id` on it as steps are recorded.

> **EU region.** A client token does not carry the API host. Return `api_url` from your server next to the client token and pass it as `apiUrl`, or the SDK reads the session from the US host. When `apiUrl` is not passed and the session it read names an `api_url`, the SDK uses that base for the calls that follow.

## Documents

### presentDocument

```ts
await ceremony.presentDocument({
  versionId: "dv_3kT9",
  mode: "hyperlink", // "hyperlink" | "inline" | "scrollbox"
  link: document.querySelector("#tos-link"),
});
```

| Option | Type | Description |
|---|---|---|
| `versionId` | string | A version pinned on this session (`session.documents[].version_id`). |
| `mode` | `"hyperlink"`, `"inline"` or `"scrollbox"` | How the document is put in front of the signer. |
| `link` | Element | The anchor the signer follows. Required for `hyperlink`. |
| `container` | Element | The element that holds the document text. Required for `inline` and `scrollbox`. |
| `downloadControl`, `printControl` | Element | Optional. The controls that save or print the exact pinned version. |

Records `document.presented` (tag `observed`) and satisfies the step `document.presented:<version_id>`. Resolves with a `StepResult`. It rejects with `invalid_request` and rule `CR-08` when `versionId` is not a version of this session, or when the element the mode needs (`link` or `container`) is missing.

Every report carries the `mode` and the `language`: the `lang` or `hreflang` attribute of the element, or else the language of the registered version.

What the event carries depends on the mode:

| Mode | Recorded |
|---|---|
| `hyperlink` | Link text and address, whether the address is on the same site, and whether a download or print control exists. Unless capture is minimal: link visibility, underline, contrast against the surrounding text, font size, the viewport, whether the signer opened the link, and the hash of the page behind a same-origin link. |
| `inline` | Whether a download or print control exists. Unless capture is minimal: the hash of the text inside the container (`render_hash`) and the viewport. The text is taken from the element marked `data-esc-document` when the container is or holds one, otherwise from the container. |
| `scrollbox` | As `inline`, plus whether the signer scrolled to the end. |

For a `hyperlink` on the same origin, the SDK fetches the linked page and hashes the text of the element marked `data-esc-document` (see [Data attributes](#data-attributes)). It prefers the element whose attribute value is the version ID, then the first marked element. If the page does not answer with HTML within 4 seconds, or has no marked element, the link is still recorded and no hash is sent. The API compares that hash, or the inline `render_hash`, with the registered version. The hash covers the element's text content in Unicode NFC with whitespace and zero-width characters removed. In live mode a mismatch on an enforced rule rejects with [`render_mismatch`](https://esigncomply.com/docs/api/errors.md#render_mismatch) ([CR-08](https://esigncomply.com/docs/conformance.md#cr-08)).

A presentation can be reported more than once: when the link becomes visible, when the signer opens it (a click, or a middle-button click), or when a scroll box reaches its end. Each report is a new `document.presented` event. Calling `presentDocument` again with the same version, element and mode returns the same promise, so a re-render does not record twice. A call with another element for the same version replaces the earlier presentation. A presentation that failed can be tried again with the same element.

The SDK records measured events only: link opened, scroll completed. It never reports that a signer read a document.

## Consumer e-consent steps

These three steps apply when the session's `required_steps` contain `disclosure.presented`, `access.demonstrated` and `econsent.given`. The walkthrough is in [Consumer e-consent](https://esigncomply.com/docs/guides/consumer-econsent.md).

### presentDisclosure

```ts
await ceremony.presentDisclosure({ container: document.querySelector("#econsent-disclosure") });
```

Records `disclosure.presented` (tag `observed`): the hash of the disclosure text and the headings found inside the container. Unless capture is minimal, the time the disclosure was on screen is measured, and the event is sent again with that time just before the consent event. Resolves with a `StepResult`. A missing `container` rejects with `invalid_request` and rule `CR-16`. A second call with the same element returns the same promise.

### accessSample

```ts
const sample = await ceremony.accessSample(); // { format, instruction, html }
```

Fetches the sample document for the access demonstration from `GET /v1/sessions/{id}/access-sample`. The sample contains a six-digit code. Show `instruction` and render `html` in the page. This call records no event.

### demonstrateAccess

```ts
await ceremony.demonstrateAccess({ code: codeField.value });
```

Records `access.demonstrated` (tag `observed`) when the code matches the one inside the sample. A wrong code rejects with [`verification_failed`](https://esigncomply.com/docs/api/errors.md#verification_failed). Calling it before the disclosure rejects with [`step_out_of_order`](https://esigncomply.com/docs/api/errors.md#step_out_of_order).

### giveEConsent

```ts
ceremony.giveEConsent({ checkbox: document.querySelector("#econsent") });
```

Watches the consent checkbox. The promise resolves once the signer has ticked it and `econsent.given` (tag `observed`) is recorded with the control's label text, its state when the page loaded, whether the change came from a trusted user event, and its current state. Call it when the control renders, not from its change handler. If the signer unticks the box, the SDK reports that too and the step counts as outstanding again.

The tick is sent only after `disclosure.presented` and `access.demonstrated` are recorded. A box the SDK did not see being ticked (rendered checked, or ticked before the call) is reported with the signing act, inside `complete()`. A missing `checkbox` rejects with `invalid_request` and rule `CR-01`. If the API refuses the event the promise rejects, and a new call for the same control starts over.

## Notice and intent

### observeAssent

```ts
ceremony.observeAssent({
  region: document.querySelector("#assent"),   // notice text, links, checkbox, button
  checkbox: document.querySelector("#agree"),
  submit: document.querySelector("#create-account"),
});
```

| Option | Type | Required | Description |
|---|---|---|---|
| `region` | Element | Yes | The container that holds the notice text, the document links, the assent control and the button. |
| `submit` | Element | Yes | The button that performs the signing act. |
| `checkbox` | Element | No | An unchecked native checkbox, or an element with `role="checkbox"` and `aria-checked`. |
| `typedName` | input or textarea | No | An empty field for the signer's full name. |
| `canvas` | canvas | No | Only for a drawn signature. Strokes are collected as vector points. |
| `slots` | object | No | Values for the `required_strings` slots the page fills in: literal text, the element that shows it, or named parts of an element list. |

The method follows from what you pass: `canvas` gives `drawn`, `typedName` gives `typed`, `checkbox` gives `checkbox`, none of them gives button acceptance (`click`). A missing `region` rejects with `invalid_request` and rule `CR-02`. A missing `submit` rejects with `invalid_request` and rule `CR-03`.

It records two steps.

**`notice.captured` (tag `observed`), immediately.** The visible text of the region without control values, the checkbox label and its initial state, the submit label, the document links, the number of primary buttons, and slot values. Unless capture is minimal it also carries the serialized markup of the region (up to 100 KB, without scripts or form values), font size, weight and contrast of the notice text, the body font size, whether notice and button fit in one viewport, whether the notice sits above the button, the distance between them, the distance from each document link to the button, and the number of visible primary buttons outside the region. In minimal capture no snapshot is taken unless the session requires the step.

**`intent.captured` (tag `observed`), on the signer's action.**

| Control | When the event is sent | What it carries |
|---|---|---|
| Checkbox | When the signer ticks the box. An untick is reported as well. | Label text, button text, initial state, `trusted`, current state. |
| Typed name, drawn signature, button only | Once, inside `complete()`. Nothing is sent while the signer types or draws. | Control type, labels, initial state, `trusted`, the typed name, and the strokes when a `canvas` was passed and capture is not minimal. |

`trusted` is true only when every change the SDK saw on the control came from a real user event. For button acceptance it is whether the click on the button was a real user event. A box ticked by script is reported as it is, with `trusted: false`, and fails [CR-01](https://esigncomply.com/docs/conformance.md#cr-01). A control that was checked or prefilled when the page loaded is reported with that initial state. The SDK does not correct the page.

When a control is rendered checked or prefilled, or was already used when the SDK started watching it, the SDK raises a `CR-01` finding of its own on the `finding` event (`source: "sdk"`) before anyone clicks. The API still judges the rule on the event.

The button text is read when the signer clicks the button, before your page changes it to a busy label. Strokes are vector points relative to the canvas, without timing or pressure, up to 4,000 points. An element marked `data-esc-clear` inside the region clears them.

The promise resolves with the `StepResult` of the notice, or `null` when no snapshot is taken. Calling `observeAssent` again with the same elements returns the same promise. A call with other elements replaces the earlier watch. The promise is safe to leave unawaited: a failure also reaches the `error` event.

### reviewPresented

```ts
await ceremony.reviewPresented({ container: document.querySelector("#review"), correctable: true });
```

Records `review.presented` (tag `observed`) with the hash of the summary text and whether the signer can correct inputs. `correctable` defaults to true when the container holds an element marked `data-esc-correct`. Used by [CR-13](https://esigncomply.com/docs/conformance.md#cr-13).

## Verification

L2 and L3 sessions contain the step `identity.verified`. L3 sessions also contain `identity.verified:passkey`. See [L2 verification](https://esigncomply.com/docs/guides/l2-verification.md) and [L3 passkeys](https://esigncomply.com/docs/guides/l3-passkeys.md).

### verify.start

```ts
const v = await ceremony.verify.start({ method: "email_otp" }); // "email_otp" | "email_link" | "sms_otp" | "passkey"
```

Calls `POST /v1/sessions/{id}/verifications`. For the first three methods it asks Esign Comply to send a one-time code or link to the address or number on the session's signer object. The browser cannot change the destination. For `passkey` use [`verify.passkey`](#verify-passkey) instead, which also runs the browser prompt. Resolves with a `Verification`:

| Field | Description |
|---|---|
| `id` | Verification ID, for example `ver_2bQd`. |
| `method` | The method started. |
| `destination` | Masked destination, for example `d***@example.org`, or `null`. |
| `status` | `pending`. |
| `expiresAt` | Codes are valid for 10 minutes. |
| `attemptsRemaining` | Starts at 5. |
| `code` | Test mode only: present when the message was not delivered, so automation can continue. |
| `challenge` | Passkey only: the WebAuthn options the API issued. |

After `email_link` the signer confirms from the message, outside your page. The SDK then reads the session every 3 seconds, for up to 10 minutes, and emits `stepRecorded` for `identity.verified` once the link was used.

### verify.confirm

```ts
const result = await ceremony.verify.confirm({ code: "418205" });
// { id, status: "confirmed" | "failed" | "registered", attemptsRemaining }
```

Confirms the code for the verification started last, with `POST /v1/sessions/{id}/verifications/{ver_id}/confirm`. On `confirmed` the API itself records `identity.verified` (tag `observed`), and the SDK emits `stepRecorded` for it with `sequence: null`. On `failed` show `attemptsRemaining` and let the signer try again. After five wrong attempts the session ends and the call rejects with [`verification_failed`](https://esigncomply.com/docs/api/errors.md#verification_failed). `registered` occurs only in the passkey flow. Calling `confirm` before any `start` rejects in the browser with `invalid_request` and rule `CR-17`.

### verify.passkey {#verify-passkey}

```ts
const result = await ceremony.verify.passkey();
// { id, status: "confirmed" | "failed" | "registered", attemptsRemaining }
```

Runs the passkey step of an L3 session. It takes no arguments. Call it from a click handler, because browsers show the passkey prompt only in response to a user action. The signer's email or phone must already be verified in the same session.

What the call does:

1. It starts a verification with `{ "method": "passkey" }`. The API answers with `phase: "register"` and WebAuthn creation options when the signer has no passkey for this relying party, or with `phase: "authenticate"` and WebAuthn request options when one is on file.
2. It runs the platform prompt: `navigator.credentials.create()` for the register phase, `navigator.credentials.get()` for the authenticate phase.
3. It confirms the verification with the browser's response, sent as `attestation` (register) or `assertion` (authenticate).
4. If the API answers `registered`, the new passkey is on file but the step is not recorded yet. The SDK starts a second verification at once, which is the authenticate phase, and runs steps 2 and 3 again. The signer sees two prompts.

| Outcome | Result |
|---|---|
| The assertion verified | Resolves with `status: "confirmed"`. The API recorded `identity.verified` for the step `identity.verified:passkey`, and the SDK emits `stepRecorded`. |
| The API could not verify the response | Resolves with `status: "failed"` and the `attemptsRemaining` of that verification. Call `verify.passkey()` again to retry. |
| A second registration in a row | Resolves with `status: "registered"`. The SDK registers at most once per call. Call `verify.passkey()` again. |
| No passkey support in the browser, or the prompt was dismissed or did not complete | Rejects in the browser with `verification_failed`, `status` 0 and rule `CR-17`. Offer another method or let the signer try again. |
| Email or phone not verified yet in this session | Rejects with `409` [`step_out_of_order`](https://esigncomply.com/docs/api/errors.md#step_out_of_order). |
| Plan without L3 | Rejects with `403` [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable). |

When the session's `signature_method` is `passkey` and this call resolved with `confirmed`, `complete()` sends `passkey` as the signature method. The request and response bodies of both phases are in [L3 passkeys](https://esigncomply.com/docs/guides/l3-passkeys.md).

## Optional events

Call these only when the session's `required_steps` or the generated prompt ask for them. The checkbox methods behave like `giveEConsent`: they watch the control and resolve when the tick is recorded.

| Method | Event recorded | Tag | Step satisfied |
|---|---|---|---|
| `languageSelected(code)` | `language.selected` | observed | none |
| `ageAttested({ checkbox })` | `signer.age_attested` | asserted | none |
| `renewalTerms({ region, elements })` | `renewal_terms.presented` | observed | `renewal_terms.presented` |
| `renewalConsent({ checkbox, region? })` | `renewal.consent_given` | observed | `renewal_consent.captured` |
| `electronicAgreement({ checkbox })` | `electronic_agreement.given` | observed | `electronic_agreement.captured` |
| `sensitiveCaptureConsent({ checkbox })` | `sensitive_capture.consent_given` | observed | `sensitive_capture_consent.captured` |
| `acknowledge({ checkbox })` | `acknowledgment.given` | observed | `acknowledgment.captured` |
| `billingConfirm()` | `billing.confirm` | asserted | none |

All of them resolve with a `StepResult`.

- `languageSelected(code)` takes the language code the signer chose, for example `"de"`, and records it as `language`.
- The checkbox methods take `{ checkbox }`, an unchecked native checkbox or an element with `role="checkbox"`. They record the control's label text, its state when the page loaded, whether the change was a trusted user event, and the current state.
- `renewalConsent`, `electronicAgreement`, `sensitiveCaptureConsent` and `acknowledge` also record `separate_from_terms`: whether the control is a different element from the terms checkbox passed to `observeAssent`.

### renewalTerms and renewalConsent

```ts
await ceremony.renewalTerms({
  region: document.querySelector("#renewal-terms"),
  elements: {
    renewal_term: "every month",
    price: "$12.00",
    cancellation_policy: document.querySelector("#cancel-policy"),
    cancel_path: "Settings, then Billing, then Cancel plan",
  },
});
ceremony.renewalConsent({ checkbox: document.querySelector("#renewal-agree") });
```

`renewalTerms` records the text of the renewal block, the value of each element (`renewal_term`, `price`, `cancellation_policy`, `cancel_path` and the optional `minimum_purchase`, each as literal text or as the element that shows it), and whether the consent control sits in the same container. Unless capture is minimal it also measures the font size, weight and contrast of the block's text, the font size of the surrounding text, whether the block is set off by a border or a background of its own (or marked `data-esc-set-off`), and its distance to the consent control. The consent control is the checkbox passed to `renewalConsent`, or else a checkbox inside the region. A missing `region` rejects with `invalid_request` and rule `CR-10`.

`renewalConsent` records the tick of the renewal checkbox and whether that checkbox is separate from the terms checkbox. The tick is sent only after `renewal_terms.presented` is recorded. If the terms were measured against another control, the SDK sends `renewal_terms.presented` once more, measured against this checkbox. See [CR-10](https://esigncomply.com/docs/conformance.md#cr-10), [CR-21](https://esigncomply.com/docs/conformance.md#cr-21) and [CR-23](https://esigncomply.com/docs/conformance.md#cr-23).

### billingConfirm

Call `ceremony.billingConfirm()` immediately before your page submits a payment or starts billing. It is used only to order events ([CR-22](https://esigncomply.com/docs/conformance.md#cr-22)).

## Steps and strings

### remainingSteps

```ts
submitButton.disabled = ceremony.remainingSteps().some((s) => s !== "signature.applied");
```

Returns the outstanding steps in ceremony order. The ceremony is ready when only `signature.applied` is left. The list follows the page, not only the API: a checkbox that was unticked or a name field that was emptied counts as outstanding again. Subscribe to `change` to keep a button in sync.

### requiredStrings

```ts
for (const s of ceremony.requiredStrings()) {
  // { slot, block, rule, kind: "verbatim" | "elements", text?, translations?, elements?, statutory?, label, check }
}
```

Returns the wording the session's jurisdiction packs ask the page to carry. Render each `verbatim` string unchanged in the slot it names, and fill each `elements` list with your own values. Strings with `check: true` are looked for in the captured assent region ([CR-20](https://esigncomply.com/docs/conformance.md#cr-20)).

## Complete and cancel

### complete

```ts
const result = await ceremony.complete(); // { recordId, receipt, verifyUrl, status }
```

Sends the signing act. Call it from the real submit handler, after the user's own click. It takes one optional argument, `{ typedName }`, for pages that do not pass a `typedName` element to `observeAssent`.

What happens, in order:

1. Events already on their way are sent first, and every watched control reports its final state, in ceremony order.
2. If a step other than `signature.applied` is still outstanding, the SDK reads the session once more, in case a step was recorded outside the page (an emailed link). If steps are still outstanding, the call rejects in the browser with `steps_incomplete`, `missingSteps`, a rule and a `fix`. The signing act is not sent.
3. A typed-name signature without a name rejects in the browser with `steps_incomplete` and `param: "signature.typed_name"`.
4. The SDK calls `POST /v1/sessions/{id}/complete` with the method, the label and button text, the typed name and the client time, under one idempotency key per signing act.
5. A network failure or a 5xx answer retries the same request with the same key, up to two more times. If the answer is still lost, the SDK reads the session and, when a record already exists, resolves with it. The signer is never asked to act twice.

The method sent is `passkey` when the session's `signature_method` is `passkey` and `verify.passkey()` resolved with `confirmed` on this ceremony object. Otherwise it is `drawn` when a `canvas` was passed, `typed` when there is a typed name, and else the method `observeAssent` derived (`checkbox` or `click`), or the session's `signature_method` when `observeAssent` was not called.

| Field | Description |
|---|---|
| `recordId` | The record, for example `rec_Z4m8`. |
| `receipt` | Signed receipt, or `null` while the seal is pending or when the record was recovered after a lost response. |
| `verifyUrl` | Verification page for the record, or `null` when recovered. |
| `status` | `recorded` or `pending_seal` as the API answered, or `unknown` when the record was recovered. |

A double click gets the same promise. After a completed ceremony, further calls resolve with the same result. On success the SDK stops watching the page, emits `stepRecorded` for `signature.applied` with the findings and advisories the API returned, and sets `session.status` to `completed`. When the API refuses the signing act, the SDK reads the session again so that `remainingSteps()` shows the API's view, and the next try uses a new idempotency key.

> **Never.** Do not grant access or show "signed" on this result. It was delivered to the browser. Your server confirms the record with a secret key first: see [Server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md).

### cancel

```ts
await ceremony.cancel();
```

Cancels the session with `POST /v1/sessions/{id}/cancel`, for a decline control. The session moves to `cancelled`, the SDK stops watching the page, and no record is made. Resolves with nothing.

## Events

### on

```ts
const off = ceremony.on("finding", (f) => console.log(f.rule, f.message, f.fix));
off(); // unsubscribe
```

| Event | Payload | Fired when |
|---|---|---|
| `finding` | `Finding` | A conformance finding did not pass: in an event response, behind an error, or with the signing act. Includes findings the SDK raises before the API sees the event (`source: "sdk"`). |
| `stepRecorded` | `StepResult` | The API recorded a ceremony step. For `identity.verified` and `signature.applied`, which the API records itself, `sequence` is `null`. |
| `expired` | `{ sessionId }` | The token's expiry time passed, or the API answered `client_token_expired`. Create a new session. |
| `error` | `EsignComplyError` | Any method failed. The same error also rejects the caller's promise. Each error is emitted once. |
| `change` | `{ remainingSteps }` | The list `remainingSteps()` returns has changed: a step was recorded, or a watched control changed. |

`on` returns the function that unsubscribes. An exception thrown by a handler is caught and logged. It does not stop the ceremony.

### destroy

`ceremony.destroy()` removes every listener and observer and forgets the token. Call it when the component unmounts. Every method that talks to the API rejects with `session_not_active` afterwards, and no further events are emitted.

## Results

```ts
interface StepResult {
  id: string;                 // evt_91xA
  type: string;               // "document.presented"
  sequence: number | null;    // null for steps the API records itself
  tag: string;                // "observed" | "asserted"
  versionId?: string;
  status: "pass" | "warn" | "block";
  findings: Finding[];
  remainingSteps: string[];
}

interface Finding {
  rule: string;               // "CR-01"
  status: "pass" | "warn" | "block";
  state: "enforce" | "advise";
  message: string;
  fix?: string;
  measurement?: Record<string, unknown>;
  maps_to?: string[];
  event_type?: string;
  version_id?: string;
  doc_url: string;            // https://esigncomply.com/docs/conformance#cr-01
  source?: "sdk";
}
```

Findings are advisory. `state: "enforce"` can refuse a live record. `state: "advise"` is measured and stored only. Test mode never blocks. The rules are listed in [Conformance rules](https://esigncomply.com/docs/conformance.md).

## Errors

Every method rejects with one type, `EsignComplyError`, so a person or an AI coding tool can read the error and repair the page.

| Field | Description |
|---|---|
| `code` | Stable machine code from the [error reference](https://esigncomply.com/docs/api/errors.md), for example `steps_incomplete`. `network_error` when the API could not be reached. |
| `type` | Error type from the API envelope, for example `ceremony_error`. |
| `status` | HTTP status. `0` for a refusal made in the browser or a network failure. |
| `message` | What happened. `name` is always `EsignComplyError`. |
| `rule` | Conformance or pack rule that produced the error, for example `CR-01`. |
| `missingSteps` | Steps still outstanding, on `steps_incomplete` and `step_out_of_order`. |
| `findings` | The findings behind a `conformance_failed` or `render_mismatch`. |
| `fix` | Plain-language repair: the fix of the first finding that has one, or the calls that record the missing steps, or a standard fix for the code. |
| `param` | The option or request field at fault. |
| `docUrl` | Link to the conformance rule when the rule is a `CR-` rule, otherwise the link the API sent for the code. |
| `recordId` | Set when the session already has a record. |
| `retryAfter` | Seconds, from `Retry-After`. |
| `requestId` | The API request ID. |

Errors raised in the browser, before or without an API answer, have `status` 0:

| Code | Type | When |
|---|---|---|
| `invalid_request` | `invalid_request_error` | A required option or element is missing, `attach` ran outside a browser, `confirm` was called before `start`, or Web Crypto is not available on the page. |
| `invalid_api_key` | `authentication_error` | `clientToken` is not a session client token. |
| `steps_incomplete` | `ceremony_error` | `complete()` was called with steps outstanding, or without the typed name. |
| `verification_failed` | `ceremony_error` | `verify.passkey()`: no passkey support, or the prompt was dismissed. |
| `client_token_expired` | `authentication_error` | The token's expiry time has passed. |
| `session_not_active` | `conflict_error` | The ceremony was destroyed. |
| `network_error` | `api_error` | The API could not be reached. |
| `internal_error` | `api_error` | An unexpected failure inside the SDK. |

An API answer without an error body becomes `not_found` for a `404` and `internal_error` otherwise.

```ts
try {
  const result = await ceremony.complete();
  await confirmOnServer(result.recordId);
} catch (err) {
  if (err instanceof EsignComplyError) {
    if (err.code === "client_token_expired") return restartCeremony();
    if (err.code === "network_error" || err.status >= 500) {
      return showMessage("We could not confirm whether your acceptance was recorded. Please wait while we check.");
    }
    showMessage(err.message); // keep the form, do not retry automatically
  }
}
```

On `network_error` do not treat the agreement as signed. Reconcile the same session on your server before asking the signer to act again.

## Data attributes

The SDK reads these optional attributes on your own elements.

| Attribute | Where | Meaning |
|---|---|---|
| `data-esc-document` | The element that renders a document version. Optionally set its value to the version ID. | The text that is hashed and compared with `render_hash`. |
| `data-esc-download`, `data-esc-print` | Controls on the document page or inside the container. | A control that saves or prints the exact pinned version. |
| `data-esc-slot="<slot>"` | An element inside the assent region. | The text shown for a `required_strings` slot. |
| `data-esc-primary` | A custom element that acts as a primary button. | Counted with submit buttons for [CR-07](https://esigncomply.com/docs/conformance.md#cr-07). |
| `data-esc-clear` | A button inside the assent region. | Clears the strokes of a drawn signature. |
| `data-esc-correct` | An element inside the review container. | The signer can correct inputs from the review step. |
| `data-esc-set-off` | The renewal terms region. | The block is set off from the surrounding text. |

## Requirements that matter to an integrator

- **Small and self-contained.** Under 15 KB compressed, no third-party dependencies, no cookies, no local or session storage. The client token lives in memory only.
- **Direct channel.** Events go with `fetch` from the signer's browser to the regional API host, one at a time and in the order the page produced them. Each request carries the client token in the `Authorization` header and no cookies. An event that fails on the network or with a 5xx answer is sent again, up to two more times, under the same idempotency key. Never proxy SDK calls through your own server: the record would then show your server, not the signer's device.
- **Registered text only.** Inline text and same-origin link targets are hashed and compared with the registered version. Render the version fetched from Esign Comply, unmodified. Do not copy document text into your repository.
- **Controls start clear.** Every checkbox starts unchecked and every typed-name field starts empty. The SDK reports a pre-checked or prefilled control as it found it.
- **The user acts.** Never call `.click()`, set `.checked` or submit on the user's behalf. Programmatic changes are reported with `trusted: false`. A trusted event shows that a user gesture occurred in the browser. It does not establish who acted.
- **No keystrokes, no screenshots.** Only the submitted name is sent, once, with the signing act. Drawn strokes are sent only when a `canvas` is passed and are kept only when drawn capture is switched on for the domain. Apart from two page-level measurements (the body font size and a count of primary buttons outside the region), the SDK reads only the elements you name and the page behind a same-origin document link.
- **Minimal capture.** When `session.minimal_capture` is true (EU, UK and CH packs, or a profile set to `eu_minimal`), the SDK sends no markup, styles, layout, link measurements, viewport, browser language, time zone or strokes, does not fetch the page behind a document link, and does not time the disclosure. The steps and method calls stay the same.
- **Outstanding steps.** Keep the action control disabled until `remainingSteps()` contains only `signature.applied`.
- **Typed errors.** Every rejection carries the rule ID and a fix.
- **Test mode is verbose.** With a test session every recorded event, every finding that did not pass and every error is logged to the browser console with the rule ID and a documentation link.
- **Browser support.** Current Chrome, Safari, Firefox and Edge, and mobile web views. The page must be served over HTTPS or from `localhost`, because hashing uses Web Crypto.

## Content Security Policy

The SDK makes no network calls except `fetch` to the API host and a same-origin read of a linked document page. It uses no `eval` and injects no styles or scripts, so no `unsafe-inline` is needed.

```text
Content-Security-Policy: connect-src https://esigncomply.com https://api.eu.esigncomply.com
```

Keep only the host of your region if you prefer. If your policy does not already allow same-origin requests, add `'self'` so the SDK can read the document page behind a link. Without it the link is still recorded, and its target is not compared.

## Server-rendered frameworks

Importing the package during server rendering is safe: nothing at module scope touches `window` or `document`. `EsignComply.attach()` itself must run in the browser. Call it inside an effect or an event handler of a client component. In Next.js that means a file marked `"use client"`. See [React hooks](https://esigncomply.com/docs/sdk/react.md) and the [Next.js guide](https://esigncomply.com/docs/guides/nextjs.md).

## Complete example

A signup form with a checkbox and a button, at L1. The server creates the session with the [Node SDK](https://esigncomply.com/docs/sdk/node.md) and returns only the client token, the API URL and the documents.

```html
<form id="signup">
  <input id="email" type="email" autocomplete="email" required />
  <div id="assent">
    <p>
      By checking the box and clicking Create account, you agree to the
      <a id="tos-link" href="/legal/terms">Terms of Service</a> and acknowledge the
      <a id="privacy-link" href="/legal/privacy">Privacy Notice</a>.
    </p>
    <label><input id="agree" type="checkbox" /> I agree to the Terms of Service and Privacy Notice</label>
    <button id="create-account" type="submit" disabled>Create account</button>
  </div>
  <p id="message" role="alert"></p>
</form>
```

```ts
import { EsignComply, EsignComplyError } from "@esigncomply/browser";

const form = document.querySelector<HTMLFormElement>("#signup")!;
const submit = document.querySelector<HTMLButtonElement>("#create-account")!;
const message = document.querySelector<HTMLElement>("#message")!;

// Your own route. It calls esc.sessions.create() with the secret key and returns
// { clientToken, apiUrl, documents } to the browser. Nothing else.
const res = await fetch("/api/ceremony", { method: "POST" });
if (!res.ok) throw new Error("Unable to create ceremony");
const { clientToken, apiUrl, documents } = await res.json();

const ceremony = await EsignComply.attach({ clientToken, apiUrl });

await ceremony.presentDocument({ versionId: documents[0].version_id, mode: "hyperlink", link: document.querySelector("#tos-link") });
await ceremony.presentDocument({ versionId: documents[1].version_id, mode: "hyperlink", link: document.querySelector("#privacy-link") });

ceremony.observeAssent({
  region: document.querySelector("#assent"),
  checkbox: document.querySelector("#agree"),
  submit,
});

const sync = () => {
  submit.disabled = ceremony.remainingSteps().some((step) => step !== "signature.applied");
};
ceremony.on("change", sync);
ceremony.on("expired", () => {
  message.textContent = "This page has been open for a while. Reload it to continue.";
});
sync();

form.addEventListener("submit", async (event) => {
  event.preventDefault();
  try {
    const result = await ceremony.complete(); // { recordId, receipt, verifyUrl, status }
    // Your authenticated route confirms the record with the secret key before creating the account.
    const confirmed = await fetch("/api/signup/finish", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ recordId: result.recordId, email: form.email.value }),
    });
    if (!confirmed.ok) throw new Error("Not confirmed");
    location.assign("/welcome");
  } catch (err) {
    // A refusal (4xx, or one made in the browser) carries a message and a fix: keep the form.
    // Anything else is inconclusive: never proceed without a confirmed record.
    const refused = err instanceof EsignComplyError && err.code !== "network_error" && err.status < 500;
    message.textContent = refused
      ? err.message
      : "We could not confirm whether your acceptance was recorded. Please wait while we check.";
  }
});
```
