feat: wallet support for frontend apps and API server methods (#43)

* feat(wip): removed signer from viewMethods by dropping NAJ account.ViewFunction (#35) * feat(wip): removed signer from viewMethods by dropping accounts.ViewFunction * chore: fixed docs and removed comments * chore: fixed linting issues * fix: removed the use of Buffer as it won't work in browser environments * fix: put try/catch for btoa * chore(release): 1.1.0-beta.1 # [1.1.0-beta.1](v1.0.1...v1.1.0-beta.1) (2024-07-24) ### Features * **wip:** removed signer from viewMethods by dropping NAJ account.ViewFunction ([#35](#35)) ([a57edc4](a57edc4)) * feat: remove near-api-js account object dependency from change functions (#38) * refactor: remove dependency on near-api-js account and connection objects from change functions * test: update tests to use new network initialization * chore: squash * docs: amend docs to use new initailaization * docs: update docs to use the new signer object and fix broken links * build(lint): fix linting errors * chore: squash * refactor: convert signer to account because signer is icky * chore(release): 1.1.0-beta.2 # [1.1.0-beta.2](v1.1.0-beta.1...v1.1.0-beta.2) (2024-07-25) ### Features * remove near-api-js account object dependency from change functions ([#38](#38)) ([134e463](134e463)) * fix: required deposit fix when available storage is higher than needed (#40) * fix: required deposit fix when available storage is higher than needed * chore: fixed lint error * chore(release): 1.1.0-beta.3 # [1.1.0-beta.3](v1.1.0-beta.2...v1.1.0-beta.3) (2024-07-30) ### Bug Fixes * required deposit fix when available storage is higher than needed ([#40](#40)) ([99f9e8d](99f9e8d)) * feat: adding api server support for read methods (#33) * feat: adding api server support for read methods * feat(wip): added more args to get and introduced keys method * chore: fixed merge issues * feat: added index() function and docs for all api server changes * docs: fix docs build * chore(release): 1.1.0-beta.4 # [1.1.0-beta.4](v1.1.0-beta.3...v1.1.0-beta.4) (2024-08-01) ### Features * adding api server support for read methods ([#33](#33)) ([dc53b30](dc53b30)) * feat: aded transformActions utility and exposed all utils (#42) feat: added transformActions utility and exposed all utils * chore(release): 1.1.0-beta.5 # [1.1.0-beta.5](v1.1.0-beta.4...v1.1.0-beta.5) (2024-08-05) ### Features * aded transformActions utility and exposed all utils ([#42](#42)) ([bfc9072](bfc9072)) --------- Co-authored-by: nearbuilder <tech@nearbuilders.org> Co-authored-by: Kieran O'Neill <hello@kieranoneill.com>
NEARBuilders · Aug 19, 2024 · 83bb3a6 · 83bb3a6
1 parent b8bb3cb
commit 83bb3a6
Show file tree

Hide file tree

Showing 76 changed files with 1,955 additions and 556 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,38 @@
+# [1.1.0-beta.5](https://github.com/NEARBuilders/near-social-js/compare/v1.1.0-beta.4...v1.1.0-beta.5) (2024-08-05)
+
+
+### Features
+
+* aded transformActions utility and exposed all utils ([#42](https://github.com/NEARBuilders/near-social-js/issues/42)) ([bfc9072](https://github.com/NEARBuilders/near-social-js/commit/bfc90720035d9e686469e95bf25ef0cc17c79c4b))
+
+# [1.1.0-beta.4](https://github.com/NEARBuilders/near-social-js/compare/v1.1.0-beta.3...v1.1.0-beta.4) (2024-08-01)
+
+
+### Features
+
+* adding api server support for read methods ([#33](https://github.com/NEARBuilders/near-social-js/issues/33)) ([dc53b30](https://github.com/NEARBuilders/near-social-js/commit/dc53b30af3ade611a4e8d29316dfc56f77dc8791))
+
+# [1.1.0-beta.3](https://github.com/NEARBuilders/near-social-js/compare/v1.1.0-beta.2...v1.1.0-beta.3) (2024-07-30)
+
+
+### Bug Fixes
+
+* required deposit fix when available storage is higher than needed ([#40](https://github.com/NEARBuilders/near-social-js/issues/40)) ([99f9e8d](https://github.com/NEARBuilders/near-social-js/commit/99f9e8de55d5410ff34f553348d978fe075e6fbf))
+
+# [1.1.0-beta.2](https://github.com/NEARBuilders/near-social-js/compare/v1.1.0-beta.1...v1.1.0-beta.2) (2024-07-25)
+
+
+### Features
+
+* remove near-api-js account object dependency from change functions ([#38](https://github.com/NEARBuilders/near-social-js/issues/38)) ([134e463](https://github.com/NEARBuilders/near-social-js/commit/134e4638341febdaf945fe8412479172421332d3))
+
+# [1.1.0-beta.1](https://github.com/NEARBuilders/near-social-js/compare/v1.0.1...v1.1.0-beta.1) (2024-07-24)
+
+
+### Features
+
+* **wip:** removed signer from viewMethods by dropping NAJ account.ViewFunction ([#35](https://github.com/NEARBuilders/near-social-js/issues/35)) ([a57edc4](https://github.com/NEARBuilders/near-social-js/commit/a57edc42bee279abc1f3925acd130cba29cd239a))
+
 ## [1.0.1](https://github.com/NEARBuilders/near-social-js/compare/v1.0.0...v1.0.1) (2024-07-05)
 
 

diff --git a/README.md b/README.md
@@ -16,8 +16,7 @@
     <img alt="GitHub Pre-release" src="https://img.shields.io/github/v/release/NEARBuilders/near-social-js?include_prereleases&label=pre-release&logo=github">
   </a>
   <a href="https://github.com/NEARBuilders/near-social-js/releases">
-    <img alt="GitHub Pre-release Date - Published At" src="https://img.shields.io/github/release-date-pre/NEARBuilders/near-social-js?label=pre-release%20date&logo=github
-">
+    <img alt="GitHub Pre-release Date - Published At" src="https://img.shields.io/github/release-date-pre/NEARBuilders/near-social-js?label=pre-release%20date&logo=github">
   </a>
 </p>
 

diff --git a/docs/advanced/fetching-indexed-data.mdx b/docs/advanced/fetching-indexed-data.mdx
@@ -0,0 +1,160 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import TOCInline from '@theme/TOCInline';
+
+# Fetching Indexed Data
+
+## Overview
+
+The `index` function in the Social SDK allows you to retrieve 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, supporting various filtering, ordering, and pagination options.
+
+:::note
+
+The `index` function is only available through the API server and does not have an RPC version.
+
+:::
+
+## Function Signature
+
+```typescript
+public async index({
+  action,
+  key,
+  accountId,
+  order,
+  limit,
+  from,
+}: IIndexOptions): Promise<Record<string, unknown>>
+```
+
+### Parameters
+
+- `action`: The index_type from the standard (e.g., 'like' in the path 'index/like').
+- `key`: Can be either a string or an object:
+    - If string: The inner indexed value from the standard.
+    - If object: Can include properties like type, path, and blockHeight.
+- `accountId` (optional): A string or array of account IDs to filter values.
+- `order` (optional): The order of results. Either 'asc' or 'desc'. Default is 'asc'.
+- `limit` (optional): The number of values to return. Default is 100.
+- `from` (optional): The starting point for fetching results. Defaults to 0 or Max depending on order.
+
+### Return Value
+
+A promise that resolves to an array of matched indexed values, ordered by blockHeight.
+
+## Usage Examples
+
+### Basic Usage
+
+<Tabs
+  defaultValue="javascript-via-package-manager"
+  values={[
+    { label: 'JavaScript (via package manager)', value: 'javascript-via-package-manager' },
+    { label: 'JavaScript (via CDN)', value: 'javascript-via-cdn' },
+    { label: 'TypeScript', value: 'typescript' },
+  ]}>
+  <TabItem value="javascript-via-package-manager">
+
+    ```js
+    const { Social } = require('@builddao/near-social-js');
+
+    const social = new Social();
+    const result = await social.index({
+      action: 'like',
+      key: 'post-123',
+    });
+
+    console.log(result);
+    ```
+
+  </TabItem>
+  <TabItem value="javascript-via-cdn">
+
+    ```js
+    var social = new NEARSocialSDK();
+
+    social.index({
+      action: 'like',
+      key: 'post-123',
+    }).then((result) => {
+      console.log(result);
+    });
+    ```
+
+  </TabItem>
+  <TabItem value="typescript">
+
+    ```typescript
+    import { Social } from '@builddao/near-social-js';
+
+    const social = new Social();
+    const result = await social.index({
+      action: 'like',
+      key: 'post-123',
+    });
+
+    console.log(result);
+    ```
+
+  </TabItem>
+</Tabs>
+
+### Advanced Usage
+
+You can use additional options to customize the behavior of the `index` function:
+
+```typescript
+const result = await social.index({
+  action: 'follow',
+  key: 'alice.near',
+  accountId: ['bob.near', 'charlie.near'],
+  order: 'desc',
+  limit: '50',
+  from: 100,
+});
+```
+
+This example retrieves the last 50 'follow' actions for 'alice.near', starting from the 100th most recent entry, and only includes actions by 'bob.near' and 'charlie.near'.
+
+## Use Cases
+
+The `index` function is particularly useful for:
+
+1. Fetching all 'like' actions for a specific post:
+   ```typescript
+   const likes = await social.index({
+     action: 'like',
+     key: {
+       type: 'social',
+       path: 'efiz.near/post/main',
+       blockHeight: 124692995,//blockHeight of the post
+     },
+   });
+   ```
+
+2. Retrieving recent 'follow' actions for a user:
+   ```typescript
+   const result = await social.index({
+     action: 'graph',
+     key: 'follow',
+     order: 'desc',
+     accountId: 'alice.near',
+     limit: '10',
+   });
+   ```
+
+3. Querying custom indexed data based on application-specific schemas:
+   ```typescript
+   const customData = await social.index({
+     action: 'custom-action',
+     key: 'app-specific-key',
+   });
+   ```
+
+By leveraging the `index` function, you can build efficient and scalable features in your NEAR Social applications, such as activity feeds, trending content algorithms, or custom data aggregations.
+
+:::tip
+
+Combine the `index` function with `get` and `keys` for comprehensive data retrieval strategies in your application.
+
+:::
diff --git a/docs/advanced/granting-write-permission.mdx b/docs/advanced/granting-write-permission.mdx
@@ -32,20 +32,17 @@ Accounts can grant write permission to other accounts for a set of keys.
     ```js
     const { Social } = require('@builddao/near-social-js');
 
-    const grantee = await nearConnection.account('alice.near');
-    const granter = await nearConnection.account('bob.near');
-    const accessKeys = await granter.getAccessKeys();
     const social = new Social();
     const transaction = await social.grantWritePermission({
-      blockHash: accessKeys[0].block_hash,
-      granteeAccountId: grantee.accountId,
+      account: {
+        accountID: 'bob.near',
+        publicKey: 'ed25519:H9k5eiU4xXS3M4z8HzKJSLaZdqGdGwBG49o7orNC4eZW',
+      },
+      granteeAccountId: 'alice.near',
       keys: [
         'alice.near/profile/name',
         'alice.near/profile/image/url',
       ],
-      nonce: BigInt(accessKeys[0].nonce + 1), // the nonce to be used for the transaction, must be greater than the access key nonce
-      publicKey: accessKeys[0].public_key,
-      signer: granter,
     });
 
     // ...sign the returned transaction and post to the network
@@ -56,41 +53,22 @@ Accounts can grant write permission to other accounts for a set of keys.
   <TabItem value="javascript-via-cdn">
 
     ```js
-    var accessKeys;
-    var grantee;
-    var granter;
-    var social;
-
-    nearConnection.account('alice.near')
-      .then((_granter) => {
-        granter = _granter;
-
-        return nearConnection.account('bob.near');
-      })
-      .then((_grantee) => {
-        grantee = _grantee;
-
-        return granter.getAccessKeys();
-      })
-      .then((_accessKeys) => {
-        accessKeys = _accessKeys;
-        social = new NEARSocialSDK();
-
-        return social.grantWritePermission({
-          blockHash: accessKeys[0].block_hash,
-          granteeAccountId: grantee.accountId,
-          keys: [
-            'alice.near/profile/name',
-            'alice.near/profile/image/url',
-          ],
-          nonce: BigInt(accessKeys[0].nonce + 1), // the nonce to be used for the transaction, must be greater than the access key nonce
-          publicKey: accessKeys[0].public_key,
-          signer: granter,
-        });
-      })
-      .then((transaction) => {
-        // ...sign the returned transaction and post to the network
-      });
+    var social = new NEARSocialSDK();
+
+    social.grantWritePermission({
+      account: {
+        accountID: 'bob.near',
+        publicKey: 'ed25519:H9k5eiU4xXS3M4z8HzKJSLaZdqGdGwBG49o7orNC4eZW',
+      },
+      granteeAccountId: 'alice.near',
+      keys: [
+        'alice.near/profile/name',
+        'alice.near/profile/image/url'
+      ]
+    })
+    .then((transaction) => {
+      // ...sign the returned transaction and post to the network
+    });
     ```
 
   </TabItem>
@@ -99,20 +77,17 @@ Accounts can grant write permission to other accounts for a set of keys.
     ```typescript
     import { Social } from '@builddao/near-social-js';
 
-    const grantee = await nearConnection.account('alice.near');
-    const granter = await nearConnection.account('bob.near');
-    const accessKeys = await granter.getAccessKeys();
     const social = new Social();
     const transaction = await social.grantWritePermission({
-      blockHash: accessKeys[0].block_hash,
-      granteeAccountId: grantee.accountId,
+      account: {
+        accountID: 'bob.near',
+        publicKey: 'ed25519:H9k5eiU4xXS3M4z8HzKJSLaZdqGdGwBG49o7orNC4eZW',
+      },
+      granteeAccountId: 'alice.near',
       keys: [
         'alice.near/profile/name',
         'alice.near/profile/image/url',
       ],
-      nonce: BigInt(accessKeys[0].nonce + 1), // the nonce to be used for the transaction, must be greater than the access key nonce
-      publicKey: accessKeys[0].public_key,
-      signer: granter,
     });
 
     // ...sign the returned transaction and post to the network
@@ -124,12 +99,12 @@ Accounts can grant write permission to other accounts for a set of keys.
 
 :::caution
 
-If the grantee account ID or the account ID in each key is not a valid account ID then a [`InvalidAccountIdError`](../../api-reference/errors#invalidaccountiderror) is thrown.
+If the grantee account ID or the account ID in each key is not a valid account ID then a [`InvalidAccountIdError`](../api-reference/errors#invalidaccountiderror) is thrown.
 
 :::
 
 :::caution
 
-If a key does is not owned by the granter, then a [`KeyNotAllowedError`](../../api-reference/errors#keynotallowederror) is thrown.
+If a key does is not owned by the granter, then a [`KeyNotAllowedError`](../api-reference/errors#keynotallowederror) is thrown.
 
 :::
diff --git a/docs/advanced/index.md b/docs/advanced/index.md
@@ -1,6 +1,7 @@
 # Advanced
 
 * [Reading Data](advanced/reading-data)
+* [Fetching Indexed Data](advanced/fetching-indexed-data)
 * [Storing Data](advanced/storing-data)
 * [Granting Write Permission](advanced/granting-write-permission)
 * [Storage Deposit/Withdrawal](advanced/storage-deposit-withdraw)