@leadping/consent 1.0.3 → 1.0.5

package/dist/esm/capture.d.ts

@@ -5,7 +5,17 @@ export declare class ConsentCapture {
     private static active?;
     private readonly browser;
     private readonly buffer;
-    private readonly transport;
+    private readonly deadline;
+    private transport?;
+    /** Resolves when the service session is available and validated. Recording starts before this. */
+    readonly ready: Promise<void>;
+    /** Allocated as soon as the session is ready; this does not assert that submission is saved. */
+    get sessionId(): string | undefined;
+    /** The server-selected duration limit, available after ready resolves. */
+    get maxReplaySeconds(): number | undefined;
+    private session?;
+    private readonly observedDisclosure;
+    private disposed;
     private readonly pending;
     private head;
     private queuedBytes;

package/dist/esm/capture.js

@@ -1,6 +1,8 @@
 import { record } from 'rrweb';
 import { EventBuffer } from './event-buffer.js';
 import { CaptureTransport } from './transport.js';
+import { ReplayDeadline } from './replay-deadline.js';
+import { ReplayLimitExceededError } from './replay-limit-exceeded-error.js';
 /** One form recording per document, matching rrweb's document-level recorder. */
 export class ConsentCapture {
     options;
@@ -18,7 +20,17 @@ export class ConsentCapture {
         maxTouchPoints: navigator.maxTouchPoints,
     };
     buffer = new EventBuffer();
+    deadline = new ReplayDeadline();
     transport;
+    /** Resolves when the service session is available and validated. Recording starts before this. */
+    ready;
+    /** Allocated as soon as the session is ready; this does not assert that submission is saved. */
+    get sessionId() { return this.session?.sessionId; }
+    /** The server-selected duration limit, available after ready resolves. */
+    get maxReplaySeconds() { return this.session?.maxReplaySeconds; }
+    session;
+    observedDisclosure;
+    disposed = false;
     pending = [];
     head = 0;
     queuedBytes = 0;
@@ -36,15 +48,24 @@ export class ConsentCapture {
         const url = new URL(options.apiUrl);
         if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash)
             throw new Error('Capture API requires an HTTPS URL without credentials.');
-        if (!/^[0-9a-f-]{36}$/i.test(options.session.sessionId) || options.session.form.origin !== location.origin ||
-            !options.form.contains(options.checkbox) || !options.form.contains(options.disclosure) ||
-            options.checkbox.type !== 'checkbox' || options.checkbox.checked || options.checkbox.defaultChecked ||
-            options.disclosure.textContent !== options.session.form.disclosure)
-            throw new Error('Form does not match the approved disclosure and unchecked consent control.');
-        const remaining = Date.parse(options.session.expiresAt) - Date.now();
-        if (!Number.isFinite(remaining) || remaining <= 0 || remaining > 60 * 60 * 1000)
-            throw new Error('Invalid or expired capture session.');
-        this.transport = new CaptureTransport(url.href.replace(/\/$/, '') + '/consent/sessions/' + options.session.sessionId, options.session.uploadToken);
+        if (!options.form.contains(options.checkbox) || !options.form.contains(options.disclosure) ||
+            options.checkbox.type !== 'checkbox' || options.checkbox.checked || options.checkbox.defaultChecked)
+            throw new Error('Form requires an unchecked consent control and disclosure.');
+        this.observedDisclosure = options.disclosure.textContent ?? '';
+        this.ready = Promise.resolve().then(() => typeof options.session === 'function' ? options.session() : options.session)
+            .then(session => {
+            if (this.disposed || this.failure)
+                throw this.failure ?? new Error('Recorder is disposed.');
+            if (!/^[0-9a-f-]{36}$/i.test(session.sessionId) || session.form.origin !== location.origin ||
+                session.form.disclosure !== this.observedDisclosure)
+                throw new Error('Form does not match the approved disclosure.');
+            this.deadline.configure(session.expiresAt, session.maxReplaySeconds);
+            this.session = session;
+            this.transport = new CaptureTransport(url.href.replace(/\/$/, '') + '/consent/sessions/' + session.sessionId, session.uploadToken);
+            if (!this.stopped)
+                this.expiry = setTimeout(() => this.fail(new ReplayLimitExceededError()), this.deadline.remainingMilliseconds);
+        });
+        void this.ready.then(this.backgroundFlush).catch(error => this.fail(error));
         ConsentCapture.active = this;
         try {
             this.stopRecording = record({
@@ -69,11 +90,10 @@ export class ConsentCapture {
             options.checkbox.addEventListener('change', this.consentChanged);
             document.addEventListener('visibilitychange', this.visibilityChanged);
             this.interval = setInterval(this.backgroundFlush, 3000);
-            this.expiry = setTimeout(() => this.fail(new Error('Capture session expired.')), remaining);
-            record.addCustomEvent('leadping.disclosure', { formId: options.session.form.id });
+            record.addCustomEvent('leadping.disclosure', { disclosure: this.observedDisclosure });
         }
         catch (error) {
-            this.stop();
+            this.dispose();
             throw error;
         }
     }
@@ -86,6 +106,9 @@ export class ConsentCapture {
         if (this.failure)
             throw this.failure;
         this.seal();
+        await this.ready;
+        if (this.failure || this.disposed)
+            throw this.failure ?? new Error('Recorder is disposed.');
         while (this.head < this.pending.length || this.sending) {
             this.sending ??= this.send();
             await this.sending;
@@ -93,22 +116,32 @@ export class ConsentCapture {
         if (this.failure)
             throw this.failure;
     }
-    dispose() { this.stop(); this.transport.dispose(); }
+    dispose() { this.disposed = true; this.stop(); this.transport?.dispose(); }
     async finishCore(recipient) {
         if (this.stopped || this.failure)
             throw this.failure ?? new Error('Recorder is stopped.');
+        try {
+            this.deadline.assertWithinLimit();
+        }
+        catch (error) {
+            this.fail(error);
+            throw error;
+        }
         const observedDisclosure = this.options.disclosure.textContent ?? '';
-        if (observedDisclosure !== this.options.session.form.disclosure)
+        if (observedDisclosure !== this.observedDisclosure)
             throw new Error('The disclosure changed during capture. Start a new approved form session.');
         const accepted = this.options.checkbox.checked;
         record.addCustomEvent('leadping.submit', { accepted });
         this.stop();
+        this.options.onProgress?.('uploading');
         await this.flush();
-        await this.transport.put('/submission', JSON.stringify({
+        this.deadline.assertWithinLimit();
+        this.options.onProgress?.('submitting');
+        await this.transport.put(this.options.issueCertificate ? '/submission/certificate' : '/submission', JSON.stringify({
             lastBatchNumber: this.buffer.lastBatchNumber, lastEventNumber: this.buffer.lastEventNumber,
             accepted, observedDisclosure, recipient, browser: this.browser,
         }));
-        return { sessionId: this.options.session.sessionId, uploadToken: this.options.session.uploadToken };
+        return { sessionId: this.session.sessionId, uploadToken: this.session.uploadToken };
     }
     emit = (event) => {
         if (this.stopped || this.failure)
@@ -129,7 +162,7 @@ export class ConsentCapture {
         const batch = this.buffer.seal();
         if (!batch)
             return;
-        // UTF-16 string budget including queued/retrying batches. One in-flight compressed copy is additional.
+        // UTF-16 string budget including queued/retrying batches. Up to three compressed copies are additional.
         if (this.queuedBytes + batch.body.length * 2 > 2 * 1024 * 1024)
             throw new Error('Recording upload backlog exceeded 2 MiB.');
         this.pending.push(batch);
@@ -139,19 +172,25 @@ export class ConsentCapture {
         // Defer so this.sending is assigned before this function can finish.
         await Promise.resolve();
         try {
-            while (this.head < this.pending.length) {
-                const batch = this.pending[this.head];
-                await this.transport.put('/batches/' + batch.number, batch.body);
-                this.queuedBytes -= batch.body.length * 2;
-                this.pending[this.head] = undefined;
-                this.head++;
-                if (this.head === this.pending.length) {
-                    this.pending.length = 0;
-                    this.head = 0;
+            // Batches are immutable and individually numbered. Completion order need not match
+            // recording order; submission still waits for every durable acknowledgment.
+            await Promise.all(Array.from({ length: 3 }, async () => {
+                while (!this.failure && !this.disposed && this.head < this.pending.length) {
+                    const index = this.head++;
+                    const batch = this.pending[index];
+                    await this.transport.put('/batches/' + batch.number, batch.body);
+                    this.queuedBytes -= batch.body.length * 2;
+                    this.pending[index] = undefined;
                 }
+            }));
+            // A concurrent flush may append after the last worker exits but before this continuation.
+            if (this.head === this.pending.length) {
+                this.pending.length = 0;
+                this.head = 0;
             }
         }
         catch (error) {
+            this.transport?.dispose();
             this.fail(error instanceof Error ? error : new Error('Capture upload failed.'));
             throw this.failure;
         }
@@ -159,7 +198,12 @@ export class ConsentCapture {
             this.sending = undefined;
         }
     }
-    consentChanged = () => record.addCustomEvent('leadping.consent', { accepted: this.options.checkbox.checked });
+    consentChanged = () => {
+        record.addCustomEvent('leadping.consent', { accepted: this.options.checkbox.checked });
+        // Start draining while the visitor moves from consenting to submitting.
+        if (this.options.checkbox.checked)
+            this.backgroundFlush();
+    };
     visibilityChanged = () => { if (document.visibilityState === 'hidden')
         this.backgroundFlush(); };
     backgroundFlush = () => { void this.flush().catch(error => this.fail(error)); };

package/dist/esm/embed.d.ts

@@ -1,3 +1,4 @@
 export { ConsentCapture } from './capture.js';
+export { ReplayLimitExceededError } from './replay-limit-exceeded-error.js';
 /** Attach the Leadping-hosted capture and submission flow to a form. */
 export declare function attach(script: HTMLScriptElement): Promise<void>;

package/dist/esm/embed.js

@@ -1,5 +1,8 @@
+import { CaptureRejectedError } from './capture-rejected-error.js';
 import { ConsentCapture } from './capture.js';
+import { ReplayLimitExceededError } from './replay-limit-exceeded-error.js';
 export { ConsentCapture } from './capture.js';
+export { ReplayLimitExceededError } from './replay-limit-exceeded-error.js';
 /** Attach the Leadping-hosted capture and submission flow to a form. */
 export async function attach(script) {
     const domainId = script.dataset.domainId;
@@ -17,11 +20,10 @@ export async function attach(script) {
     status.setAttribute('role', 'status');
     form.append(status);
     let capture;
-    let ready = false;
     let submitted = false;
     const fail = (error) => {
-        ready = false;
-        status.textContent = 'Unable to complete consent capture. Please reload to start again.';
+        status.textContent = error instanceof ReplayLimitExceededError ? error.message
+            : 'Unable to complete consent capture. Please reload to start again.';
         form.dispatchEvent(new CustomEvent('leadping:error', { detail: error }));
     };
     const origin = new URL(script.dataset.apiUrl ?? 'https://consent.leadping.ai');
@@ -32,26 +34,41 @@ export async function attach(script) {
     if (portal.protocol !== 'https:' || portal.username || portal.password || portal.search || portal.hash || portal.pathname !== '/')
         throw new Error('Leadping requires an HTTPS portal origin.');
     const endpoint = `${origin.origin}/api/consent`;
+    const progress = (stage) => {
+        form.dispatchEvent(new CustomEvent('leadping:progress', { detail: { stage } }));
+    };
     const post = async (path, body) => {
-        const response = await fetch(endpoint + path, {
-            method: 'POST', headers: { 'Content-Type': 'application/json' },
-            credentials: 'omit', redirect: 'error', body: JSON.stringify(body),
-            signal: AbortSignal.timeout(30000),
-        });
-        if (!response.ok)
-            throw new Error(`Leadping request failed (${response.status}).`);
-        return response;
+        const attempts = path.endsWith('/sessions') ? 5 : 1;
+        for (let attempt = 0; attempt < attempts; attempt++) {
+            try {
+                const response = await fetch(endpoint + path, {
+                    method: 'POST', headers: { 'Content-Type': 'application/json' },
+                    credentials: 'omit', redirect: 'error', body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(attempts > 1 ? 15000 : 30000),
+                });
+                if (response.ok)
+                    return response;
+                if (response.status < 500 && response.status !== 408 && response.status !== 429)
+                    throw new CaptureRejectedError(`Leadping request failed (${response.status}).`);
+                throw new Error(`Leadping request failed (${response.status}).`);
+            }
+            catch (error) {
+                if (error instanceof CaptureRejectedError || attempt === attempts - 1)
+                    throw error;
+            }
+            await new Promise(resolve => setTimeout(resolve, 500 * 2 ** attempt));
+        }
+        throw new Error('Leadping session could not be started.');
     };
     form.addEventListener('submit', async (event) => {
         event.preventDefault();
-        if (!ready || submitted || !capture || !form.reportValidity())
+        if (submitted || !capture || !form.reportValidity())
             return;
         if (!(checkbox instanceof HTMLInputElement) || !checkbox.checked) {
             status.textContent = 'Please check the consent box before submitting.';
             return;
         }
         submitted = true;
-        ready = false;
         status.textContent = 'Submitting…';
         const values = new FormData(form);
         const recipient = {};
@@ -60,15 +77,11 @@ export async function attach(script) {
             if (typeof value === 'string' && value)
                 recipient[key] = value;
         }
-        let issuingCertificate = false;
         try {
             const consentCapture = await capture.finish(recipient);
-            issuingCertificate = true;
-            const certificate = await (await post('/certificates', consentCapture)).json();
-            if (!/^[0-9a-f-]{36}$/i.test(certificate.certificateId))
-                throw new Error('Invalid certificate response.');
+            const certificate = { certificateId: consentCapture.sessionId };
             const certificateUrl = `${portal.origin}/${certificate.certificateId}`;
-            status.textContent = `Certificate received: ${certificate.certificateId}. `;
+            status.textContent = `Submission saved. Certificate: ${certificate.certificateId}. `;
             const link = document.createElement('a');
             link.href = certificateUrl;
             link.textContent = 'View certificate and replay';
@@ -79,8 +92,8 @@ export async function attach(script) {
         }
         catch (error) {
             fail(error);
-            if (issuingCertificate)
-                status.textContent = 'Certificate issuance could not be confirmed. Please check before starting another recording.';
+            if (!(error instanceof ReplayLimitExceededError))
+                status.textContent = 'Submission could not be confirmed. Keep the certificate ID and check before starting another recording.';
         }
         finally {
             capture.dispose();
@@ -90,13 +103,29 @@ export async function attach(script) {
     try {
         if (!(disclosure instanceof HTMLElement) || !(checkbox instanceof HTMLInputElement))
             throw new Error('Add data-leadping-disclosure and data-leadping-consent inside the form.');
-        const session = await (await post(`/domains/${encodeURIComponent(domainId)}/sessions`, { pageUrl: location.href, disclosure: disclosure.textContent ?? '' })).json();
-        checkbox.checked = false;
-        capture = new ConsentCapture({ apiUrl: origin.origin + '/api', session, form, disclosure, checkbox, onError: fail });
-        window.addEventListener('pagehide', () => { ready = false; capture?.dispose(); }, { once: true });
-        ready = true;
-        status.textContent = '';
-        form.dispatchEvent(new CustomEvent('leadping:ready'));
+        const pageUrl = location.href;
+        const observedDisclosure = disclosure.textContent ?? '';
+        capture = new ConsentCapture({ apiUrl: origin.origin + '/api',
+            session: async () => (await post(`/domains/${encodeURIComponent(domainId)}/sessions`, { pageUrl, disclosure: observedDisclosure })).json(),
+            form, disclosure, checkbox, issueCertificate: true, onError: fail, onProgress: stage => {
+                status.textContent = stage === 'uploading' ? 'Saving recording…' : 'Saving submission and requesting certificate…';
+                progress(stage);
+            } });
+        window.addEventListener('pagehide', () => { capture?.dispose(); }, { once: true });
+        await capture.ready;
+        const certificateId = capture.sessionId;
+        const certificateUrl = `${portal.origin}/${certificateId}`;
+        for (const [name, value] of Object.entries({ leadping_certificate_id: certificateId, leadping_certificate_url: certificateUrl })) {
+            const input = document.createElement('input');
+            input.type = 'hidden';
+            input.name = name;
+            input.value = value;
+            form.append(input);
+        }
+        if (!submitted)
+            status.textContent = '';
+        form.dispatchEvent(new CustomEvent('leadping:ready', { detail: { certificateId, certificateUrl,
+                maxReplaySeconds: capture.maxReplaySeconds } }));
     }
     catch (error) {
         capture?.dispose();

package/dist/esm/event-buffer.js

@@ -42,7 +42,7 @@ export class EventBuffer {
     seal() {
         if (this.events.length === 0)
             return;
-        if (this.nextBatch >= 256)
+        if (this.nextBatch >= 1024)
             throw new Error('Recording exceeded the session batch limit.');
         const first = this.nextEvent - this.events.length;
         const body = `{"firstEventNumber":${first},"events":[${this.events.join(',')}]}`;

package/dist/esm/index.d.ts

@@ -1,2 +1,3 @@
 export { ConsentCapture } from './capture.js';
+export { ReplayLimitExceededError } from './replay-limit-exceeded-error.js';
 export type { CaptureOptions, CaptureReference, CaptureSession, ConsentForm, Recipient } from './types.js';

package/dist/esm/index.js

@@ -1 +1,2 @@
 export { ConsentCapture } from './capture.js';
+export { ReplayLimitExceededError } from './replay-limit-exceeded-error.js';

package/dist/esm/replay-deadline.d.ts

@@ -0,0 +1,10 @@
+/** Checks elapsed time even when a suspended tab has not run its expiry timer. */
+export declare class ReplayDeadline {
+    private readonly startedAt;
+    private readonly startedTick;
+    private expiresAt;
+    private maximumMs;
+    configure(expiresAt: string, maxReplaySeconds: number): void;
+    get remainingMilliseconds(): number;
+    assertWithinLimit(): void;
+}

package/dist/esm/replay-deadline.js

@@ -0,0 +1,23 @@
+import { ReplayLimitExceededError } from './replay-limit-exceeded-error.js';
+/** Checks elapsed time even when a suspended tab has not run its expiry timer. */
+export class ReplayDeadline {
+    startedAt = Date.now();
+    startedTick = performance.now();
+    expiresAt = Infinity;
+    maximumMs = 1800_000;
+    configure(expiresAt, maxReplaySeconds) {
+        const deadline = Date.parse(expiresAt);
+        if (!Number.isFinite(deadline) || !Number.isInteger(maxReplaySeconds) || maxReplaySeconds < 1 || maxReplaySeconds > 1800)
+            throw new Error('Invalid recording time limit.');
+        this.expiresAt = deadline;
+        this.maximumMs = maxReplaySeconds * 1000;
+        this.assertWithinLimit();
+    }
+    get remainingMilliseconds() {
+        return Math.min(this.expiresAt - Date.now(), this.maximumMs - (Date.now() - this.startedAt), this.maximumMs - (performance.now() - this.startedTick));
+    }
+    assertWithinLimit() {
+        if (this.remainingMilliseconds <= 0)
+            throw new ReplayLimitExceededError();
+    }
+}

package/dist/esm/replay-limit-exceeded-error.d.ts

@@ -0,0 +1,5 @@
+/** The recording cannot support this submission because its allotted time has elapsed. */
+export declare class ReplayLimitExceededError extends Error {
+    readonly code = "replay_limit_exceeded";
+    constructor();
+}

package/dist/esm/replay-limit-exceeded-error.js

@@ -0,0 +1,8 @@
+/** The recording cannot support this submission because its allotted time has elapsed. */
+export class ReplayLimitExceededError extends Error {
+    code = 'replay_limit_exceeded';
+    constructor() {
+        super("The recording time limit was reached. This submission wasn't captured. Start a new recording and submit again.");
+        this.name = 'ReplayLimitExceededError';
+    }
+}

package/dist/esm/transport.d.ts

@@ -1,4 +1,4 @@
-/** Serial, bounded retry transport. A resolved request means durable server acknowledgment. */
+/** Bounded retry transport. A resolved request means durable server acknowledgment. */
 export declare class CaptureTransport {
     private readonly baseUrl;
     private readonly token;

package/dist/esm/transport.js

@@ -1,5 +1,6 @@
 import { CaptureRejectedError } from './capture-rejected-error.js';
-/** Serial, bounded retry transport. A resolved request means durable server acknowledgment. */
+import { ReplayLimitExceededError } from './replay-limit-exceeded-error.js';
+/** Bounded retry transport. A resolved request means durable server acknowledgment. */
 export class CaptureTransport {
     baseUrl;
     token;
@@ -26,11 +27,13 @@ export class CaptureTransport {
                 });
                 if (response.ok)
                     return;
+                if (response.status === 410)
+                    throw new ReplayLimitExceededError();
                 if (response.status < 500 && response.status !== 408 && response.status !== 429)
                     throw new CaptureRejectedError(`Capture rejected (${response.status}).`);
             }
             catch (error) {
-                if (error instanceof CaptureRejectedError || this.abort.signal.aborted)
+                if (error instanceof CaptureRejectedError || error instanceof ReplayLimitExceededError || this.abort.signal.aborted)
                     throw error;
             }
             if (attempt === 4)

package/dist/esm/types.d.ts

@@ -12,6 +12,8 @@ export interface CaptureSession {
     sessionId: string;
     uploadToken: string;
     expiresAt: string;
+    /** Maximum elapsed recording time including idle time, supplied by the service. */
+    maxReplaySeconds: number;
     form: ConsentForm;
 }
 export interface Recipient {
@@ -27,12 +29,17 @@ export interface CaptureReference {
 export interface CaptureOptions {
     /** Absolute HTTPS API origin; no credentials or query string. */
     apiUrl: string;
-    session: CaptureSession;
+    /** A session or a factory that obtains one. Capture starts immediately while the factory is pending. */
+    session: CaptureSession | (() => Promise<CaptureSession>);
     form: HTMLFormElement;
     disclosure: HTMLElement;
     checkbox: HTMLInputElement;
+    /** For public domain sessions, durably request a certificate with the final submission. */
+    issueCertificate?: boolean;
     /** Called on terminal capture failures; never includes captured values. */
     onError?: (error: Error) => void;
+    /** Submission stages; no captured values or upload credentials are included. */
+    onProgress?: (stage: 'uploading' | 'submitting') => void;
 }
 export interface SealedBatch {
     number: number;