feat: Clear Storage API (#396)

* Add API to clear storage

* Add tests

* Fix clear storage logic

* Fix public docs

* Improve tests

src/amplitude-client.js

@@ -521,6 +521,16 @@ AmplitudeClient.prototype._sendEventsIfReady = function _sendEventsIfReady() {
   return false; // an upload was scheduled, no events were uploaded
 };
 
+/**
+ * Clears any stored events and metadata. Storage is then re-created on next event sending.
+ * @constructor AmplitudeClient
+ * @public
+ * @return {boolean} True if metadata was cleared, false if none existed
+ */
+AmplitudeClient.prototype.clearStorage = function clearStorage() {
+  return this._metadataStorage.clear();
+};
+
 /**
  * Helper function to fetch values from storage
  * Storage argument allows for localStoraoge and sessionStoraoge

src/metadata-storage.js

@@ -163,6 +163,39 @@ class MetadataStorage {
       sequenceNumber: parseInt(values[Constants.SEQUENCE_NUMBER_INDEX], 32),
     };
   }
+
+  /**
+   * Clears any saved metadata storage
+   * @constructor AmplitudeClient
+   * @public
+   * @return {boolean} True if metadata was cleared, false if none existed
+   */
+  clear() {
+    let str;
+    if (this.storage === Constants.STORAGE_COOKIES) {
+      str = baseCookie.get(this.getCookieStorageKey() + '=');
+      baseCookie.set(this.getCookieStorageKey(), null, {
+        domain: this.cookieDomain,
+        secure: this.secure,
+        sameSite: this.sameSite,
+        expirationDays: 0,
+      });
+    }
+    if (!str) {
+      str = ampLocalStorage.getItem(this.storageKey);
+      ampLocalStorage.clear();
+    }
+    if (!str) {
+      try {
+        str = window.sessionStorage && window.sessionStorage.getItem(this.storageKey);
+        window.sessionStorage.clear();
+      } catch (e) {
+        utils.log.info(`window.sessionStorage unavailable. Reason: "${e}"`);
+      }
+    }
+    if (!str) false;
+    return true;
+  }
 }
 
 export default MetadataStorage;

test/amplitude-client.js

@@ -3804,4 +3804,34 @@ describe('AmplitudeClient', function () {
       });
     });
   });
+
+  describe('clearStorage', function () {
+    afterEach(() => {
+      reset();
+    });
+
+    it('should clear cookies', function () {
+      amplitude.init(apiKey, null, { storage: constants.STORAGE_COOKIES });
+      assert.isNotNull(amplitude._metadataStorage.load());
+      assert.equal(amplitude._metadataStorage.storage, constants.STORAGE_COOKIES);
+      assert.equal(amplitude.clearStorage(), true);
+      assert.isNull(amplitude._metadataStorage.load());
+    });
+
+    it('should clear localStorage', function () {
+      amplitude.init(apiKey, null, { storage: constants.STORAGE_LOCAL });
+      assert.isNotNull(amplitude._metadataStorage.load());
+      assert.equal(amplitude._metadataStorage.storage, constants.STORAGE_LOCAL);
+      assert.equal(amplitude.clearStorage(), true);
+      assert.isNull(amplitude._metadataStorage.load());
+    });
+
+    it('should clear sessionStorage', function () {
+      amplitude.init(apiKey, null, { storage: constants.STORAGE_SESSION });
+      assert.isNotNull(amplitude._metadataStorage.load());
+      assert.equal(amplitude._metadataStorage.storage, constants.STORAGE_SESSION);
+      assert.equal(amplitude.clearStorage(), true);
+      assert.isNull(amplitude._metadataStorage.load());
+    });
+  });
 });