fix: prevent storage quota errors during event logging

[mattbodle]

Background

• Partner error logs showed QuotaExceededError surfacing from the synchronous commerce event path, including eCommerce.logImpression.
• The SDK had unguarded Web Storage writes in persistence and vault storage paths, so localStorage/sessionStorage quota or blocked-storage failures could escape event logging.

What Has Changed

• Makes vault storage best-effort by catching Web Storage read/write/remove failures and returning a boolean write result.
• Guards savePersistence() localStorage writes so quota failures are logged without throwing.
• Adds offline batch queue trimming that drops oldest batches until localStorage accepts the payload, while retaining batches in memory if storage is fully unavailable.
• Adds regression tests for vault write failures, persistence write failures, and offline batch trimming behavior.
• Rebuilds dist/mparticle.js.

Verification

• npm run build:iife
• npm run build:test-bundle
• npm run test:jest
• npx karma start test/karma.config.js --browsers ChromeHeadless --single-run

Screenshots/Video

• N/A

Checklist

• Self-review completed
• Tests added or updated
• Tested locally

[cursor]

PR Summary

Medium Risk
Changes core offline batch and persistence write paths; quota recovery intentionally drops oldest queued batches, which is a deliberate data-loss tradeoff under storage pressure.

Overview
Stops Web Storage failures (quota exceeded, blocked storage, corrupt reads) from throwing into synchronous event/commerce logging paths.

Vault layer now treats reads/writes as best-effort: store() returns a StorageResult (Success / QuotaExceeded / Unavailable), and retrieve() / purge() swallow parse and access errors instead of propagating them.

Offline batch persistence routes queue saves through storeBatchesQueuedForProcessing(), which drops the oldest batches until localStorage accepts the payload when quota is exceeded, logs a warning, and keeps batches in memory (no trimming) when storage is unavailable. prepareAndUpload also guards retrieve() ?? [] so null/corrupt offline data does not break the upload loop.

Persistence wraps savePersistence localStorage setItem in try/catch and logs without throwing.

Regression tests cover vault outcomes, persistence save failures, batch trimming, unavailable storage, and null retrieve during upload.

^{Reviewed by Cursor Bugbot for commit fdbe5d6. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit fdbe5d6. Configure here.}

[cursor]

Failed offline clears duplicate events

High Severity

After batches or session events are uploaded, the SDK clears offline vaults via purge() and store([]), but those calls now swallow storage errors and callers ignore failure results. If local or session storage is not actually cleared, the next prepareAndUpload reloads the same payloads and can send duplicate analytics events.

Additional Locations (2)

• src/vault.ts#L87-L96
• src/batchUploader.ts#L415-L419

 

^{Reviewed by Cursor Bugbot for commit fdbe5d6. Configure here.}

[cursor]

Wrong warning after quota trim fails

Low Severity

When every batchVault.store attempt returns QuotaExceeded after trimming down to a single batch, the loop exits without hitting the Unavailable branch, but the code still logs that offline batch storage is unavailable. That mislabels a pure quota problem and can mislead monitoring or debugging.

 

^{Reviewed by Cursor Bugbot for commit fdbe5d6. Configure here.}

[khushi1033]

Closing in favor of #1287

[sonarqubecloud]

Quality Gate failed

Failed conditions
12.2% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud