# browser

Provides access to specific browser methods that asynchronously execute in the top frame (`cookie`, `localStorage`, `sessionStorage`)

```javascript
/**
 * browser.cookie.get(name)
 *
 * @param {name} - String representing the name of the cookie
 * @return {Promise} - Promise of type string
 */

const user_id = await browser.cookie.get('my_user_id');

/**
 * browser.cookie.set(name)
 *
 * @param {name} - String representing the name of the cookie
 * @param {value} - String representing the value of the cookie
 * @return {Promise} - Promise of type string
 */

browser.cookie.set('my_user_id', 'ABCX123');
browser.cookie.set('my_user_id=ABCX123; expires=Thu, 18 Dec 2013 12:00:00');

```

```javascript
/**
 * browser.localStorage.getItem(url, data)
 *
 * @param {keyName} - String containing the name of the key you want to retrieve the value of.
 * @return {Promise} - Promise of type string.
 */
browser.localStorage.getItem('foo');

/**
 * browser.localStorage.setItem(url, data)
 *
 * @param {keyName} - A string containing the name of the key you want to retrieve the value of.
 * @param {keyValue} - A string containing the value you want to give the key you are creating or updating.
 * @return {Promise} - Promise of type string.
 */
browser.localStorage.setItem('foo', 'bar');

/**
 * browser.localStorage.removeItem(keyName)
 *
 * @param {keyName} - A string containing the name of the key you want to remove.
 * @return {Promise} - Promise of undefined.
 */
browser.localStorage.removeItem('foo');

/**
 * browser.localStorage.key(index)
 *
 * @param {index} - An integer representing the number of the key you want to get the name of. This is a zero-based index.
 * @return {Promise} - Promise of type string.
 */
browser.localStorage.key(2);

/**
 * browser.localStorage.length()
 *
 * @return {Promise} - Promise of type integer.
 */
browser.localStorage.length();

/**
 * browser.localStorage.clear()
 *
 * @return {Promise} - Promise of undefined.
 */
browser.localStorage.clear();

```

```javascript
/**
 * browser.sessionStorage.getItem(url, data)
 *
 * @param {keyName} - A string containing the name of the key you want to retrieve the value of.
 * @return {Promise} - Promise of type string.
 */
browser.sessionStorage.getItem('foo');

/**
 * browser.sessionStorage.setItem(url, data)
 *
 * @param {keyName} - A string containing the name of the key you want to retrieve the value of.
 * @param {keyValue} - A string containing the value you want to give the key you are creating or updating.
 * @return {Promise} - Promise of type string.
 */
browser.sessionStorage.setItem('foo', 'bar');

/**
 * browser.sessionStorage.removeItem(keyName)
 *
 * @param {keyName} - A string containing the name of the key you want to remove.
 * @return {Promise} - Promise of undefined.
 */
browser.sessionStorage.removeItem('foo');

/**
 * browser.sessionStorage.key(index)
 *
 * @param {index} - An integer representing the number of the key you want to get the name of. This is a zero-based index.
 * @return {Promise} - Promise of type string.
 */
browser.sessionStorage.key(2);

/**
 * browser.sessionStorage.length()
 *
 * @return {Promise} - Promise of type integer.
 */
browser.sessionStorage.length();

/**
 * browser.sessionStorage.clear()
 *
 * @return {Promise} - Promise of undefined.
 */
browser.sessionStorage.clear();

```

## Properties

### Browser

### cookie

value: `BrowserCookie`

This object replaces the native document.cookie API and provides a setter/getter to set cookies on the top frame.

### localStorage

value: `BrowserLocalStorage`


### sendBeacon

value: `(url: string, body?: string) => Promise<boolean>`


### sessionStorage

value: `BrowserSessionStorage`


### BrowserCookie

This object replaces the native document.cookie API and provides a setter/getter to set cookies on the top frame.

### get

value: `(name?: string) => Promise<string>`

An asynchronous method to get a specific cookie by name. Takes a cookie name of type `string` and returns the cookie value as a `string`

### set

value: `(cookieOrName: string, value?: string) => Promise<string>`

An asynchronous method to set a cookie by name. It takes two arguments, a string of form `key=value` as [described here](https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie#write_a_new_cookie) or the name of the cookie as the first argument and the value as the second argument.

### BrowserLocalStorage

### clear

value: `() => Promise<void>`

When invoked, will empty all keys out of the storage.

### getItem

value: `(key: string) => Promise<string>`

When passed a key name, will return that key's value.

### key

value: `(index: number) => Promise<string>`

When passed a number n, this method will return the name of the nth key in the storage.

### length

value: `() => Promise<number>`

Returns an integer representing the number of data items stored in the Storage object.

### removeItem

value: `(key: string) => Promise<void>`

When passed a key name, will remove that key from the storage.

### setItem

value: `(key: string, value: any) => Promise<void>`

When passed a key name and value, will add that key to the storage, or update that key's value if it already exists.

### BrowserSessionStorage

### clear

value: `() => Promise<void>`

When invoked, will empty all keys out of the storage.

### getItem

value: `(key: string) => Promise<string>`

When passed a key name, will return that key's value.

### key

value: `(index: number) => Promise<string>`

When passed a number n, this method will return the name of the nth key in the storage.

### length

value: `() => Promise<number>`

Returns an integer representing the number of data items stored in the Storage object.

### removeItem

value: `(key: string) => Promise<void>`

When passed a key name, will remove that key from the storage.

### setItem

value: `(key: string, value: any) => Promise<void>`

When passed a key name and value, will add that key to the storage, or update that key's value if it already exists.