import TOCInline from '@theme/TOCInline';

# Social

<TOCInline
  maxHeadingLevel={4}
  toc={toc}
/>

## Constructors

### `constructor(options)`

> Initializes the SDK with the social contract.

#### Parameters

| Name    | Type                                           | Required | Default | Description                                                                                                               |
|---------|------------------------------------------------|----------|---------|---------------------------------------------------------------------------------------------------------------------------|
| options | [`INewSocialOptions`](types#inewsocialoptions) | no       | -       | Options that initialize the SDK such as the social contract account ID and the network ID or custom RPC provider details. |

#### Returns

| Type               | Description          |
|--------------------|----------------------|
| [`Social`](social) | The initialized SDK. |

## Methods

### `get(options)`

> Reads the data for given set of keys.
> The key path pattern corresponds to the path of data to return. A string can contain wildcards.
> For example:
> * `alice.near/profile/**` - will match the entire profile data of account `alice.near`.
> * `alice.near/profile/*` - will match all the fields of the profile, but not the nested objects.
> * `alice.near/profile/name` - will match only the name field of the profile.
> * `*/widget/*` - will match all the widgets of all the accounts.

#### Parameters

| Name    | Type                               | Required | Default | Description                                         |
|---------|------------------------------------|----------|---------|-----------------------------------------------------|
| options | [`IGetOptions`](types#igetoptions) | yes      | -       | Options that include the set of keys. |

#### Returns

| Type              | Description                                                                                                                                                   |
|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Promise<object>` | A promise that resolves to an object with the top-level properties referencing the keys and the nested properties/objects referencing the corresponding path. |

### `keys(options)`
> Retrieves a list of keys that match specified criteria.
> This function is useful for querying the data structure without necessarily reading all the associated values.
> For example:
> * `alice.near/profile/**` - will match all keys under the profile of account `alice.near`.
> * `*/post/*` - will match all post keys for all accounts.
> * `bob.near/widget/***` - will match all widget keys and their nested keys for account `bob.near`.

#### Parameters
| Name    | Type                                 | Required | Default | Description                                         |
|---------|--------------------------------------|----------|---------|-----------------------------------------------------|
| options | [`IKeysOptions`](types#ikeysoptions) | yes      | -       | Options that specify the criteria for key retrieval. |

#### Returns
| Type              | Description                                                                                                   |
|-------------------|---------------------------------------------------------------------------------------------------------------|
| `Promise<object>` | A promise that resolves to an object containing the matching keys and their metadata, ordered by block height. |

### `index(options)`
> Retrieves indexed values based on specified criteria from the Social API server.
> This function is crucial for efficient lookups of social interactions or custom indexed data.
> For example:
> * Fetching all 'like' actions for a specific post.
> * Retrieving recent 'follow' actions for a user.
> * Querying custom indexed data based on application-specific schemas.

#### Parameters
| Name    | Type                                   | Required | Default | Description                                         |
|---------|----------------------------------------|----------|---------|-----------------------------------------------------|
| options | [`IIndexOptions`](types#iindexoptions) | yes      | -       | Options that specify the criteria for index retrieval. |

#### Returns
| Type              | Description                                                                                                   |
|-------------------|---------------------------------------------------------------------------------------------------------------|
| `Promise<object>` | A promise that resolves to an array of matched indexed values, ordered by block height. |

### `getVersion()`

> Gets the current version of the social contract.

#### Returns

| Type              | Description                                                     |
|-------------------|-----------------------------------------------------------------|
| `Promise<string>` | a promise that resolves to the current version of the contract. |

### `grantWritePermission(options)`

> Grants permission for a set of keys and an account (a grantee).

#### Parameters

| Name    | Type                                                                 | Required | Default | Description                                                      |
|---------|----------------------------------------------------------------------|----------|---------|------------------------------------------------------------------|
| options | [`IGrantWritePermissionOptions`](types#igrantwritepermissionoptions) | yes      | -       | Options that include the set of keys and the grantee account ID. |

#### Returns

| Type                                                                                                          | Description                                                                                                                                          |
|---------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`Promise<Transaction>`](https://near.github.io/near-api-js/classes/near_api_js.transaction.Transaction.html) | A promise that resolves to an unsigned transaction that contains the function call to grant the grantee account write permission to the set of keys. |

### `isWritePermissionGranted(options)`

> Checks if an account, specified in `options.granteeAccountId`, has been granted write access for a key.

#### Parameters

| Name    | Type                                                                         | Required | Default | Description                                              |
|---------|------------------------------------------------------------------------------|----------|---------|----------------------------------------------------------|
| options | [`IIsWritePermissionGrantedOptions`](types#iiswritepermissiongrantedoptions) | yes      | -       | Options that include the key and the grantee account ID. |

#### Returns

| Type               | Description                                                                                              |
|--------------------|----------------------------------------------------------------------------------------------------------|
| `Promise<boolean>` | A promise that resolves to true, if the grantee account ID has write access for the given key, or false. |

### `set(options)`

> Stores data to the social contract. The top level properties must be account IDs under which the nested properties/objects are stored.
>
> The signer's public key should have permission to write under the specified account keys.

:::note

Accounts that match the signer's account ID automatically have write permission granted.

:::

#### Parameters

| Name    | Type                               | Required | Default | Description                                                                 |
|---------|------------------------------------|----------|---------|-----------------------------------------------------------------------------|
| options | [`ISetOptions`](types#isetoptions) | yes      | -       | Options that include the data to set, the signer's account and key details. |

#### Returns

| Type                                                                                                          | Description                                                                                                      |
|---------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| [`Promise<Transaction>`](https://near.github.io/near-api-js/classes/near_api_js.transaction.Transaction.html) | A promise that resolves to an unsigned transaction that contains the function call to update the specified data. |


### `storageDeposit(options)`

> Deposit NEAR to the social DB contract to cover storage costs for a given `account_id` or the signer if `account_id` is not provided. Optionally, you can choose to pay only the bare minimum deposit for registering the account in the Social DB contract without any additional storage fees.
>

:::note

The signer account must have sufficient NEAR balance to cover the deposit.

:::

#### Parameters

| Name    | Type                                                       | Required | Default | Description                                                                     |
|---------|------------------------------------------------------------|----------|---------|---------------------------------------------------------------------------------|
| options | [`IStorageDepositOptions`](types#istorage-deposit-options) | yes      | -       | Options that include the deposit details, the signer's account and key details. |

#### Returns

| Type                                                                                                          | Description                                                                                                         |
|---------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| [`Promise<Transaction>`](https://near.github.io/near-api-js/classes/near_api_js.transaction.Transaction.html) | A promise that resolves to an unsigned transaction that contains the function call to deposit the specified amount. |


### `storageWithdraw(options)`

> Withdraw NEAR from the social DB contract for covering storage. If the `amount` is not specified, all available NEAR is withdrawn.
>

:::note

The signer account must have sufficient NEAR balance available for withdrawal.

:::

#### Parameters

| Name    | Type                                                         | Required | Default | Description                                                                        |
|---------|--------------------------------------------------------------|----------|---------|------------------------------------------------------------------------------------|
| options | [`IStorageWithdrawOptions`](types#istorage-withdraw-options) | yes      | -       | Options that include the withdrawal details, the signer's account and key details. |

#### Returns

| Type                                                                                                          | Description                                                                                                          |
|---------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| [`Promise<Transaction>`](https://near.github.io/near-api-js/classes/near_api_js.transaction.Transaction.html) | A promise that resolves to an unsigned transaction that contains the function call to withdraw the specified amount. |