@pinata/sdk 1.1.25 → 1.2.0

package/.babelrc

@@ -1,4 +1,5 @@
 {
-  "presets": [["@babel/env", { "modules": "commonjs" }]],
-  "plugins": ["add-module-exports"]
-}
+  "presets": [["@babel/env", { "modules": "commonjs" , "useBuiltIns": "usage"}]  ],
+  "plugins": ["add-module-exports", "@babel/plugin-transform-runtime"]
+}
+

package/.nvmrc

@@ -1 +1 @@
-v6.10
+v10.24

package/README.md

@@ -36,7 +36,6 @@ Once you've set up your instance, using the Pinata SDK is easy. Simply call your
 
 * Pinning
   * [hashMetadata](#hashMetadata-anchor)
-  * [hashPinPolicy](#hashPinPolicy-anchor)
   * [pinByHash](#pinByHash-anchor)
   * [pinFileToIPFS](#pinFileToIPFS-anchor)
   * [pinFromFS](#pinFromFS-anchor)
@@ -48,6 +47,7 @@ Once you've set up your instance, using the Pinata SDK is easy. Simply call your
 * Data
   * [testAuthentication](#testAuthentication-anchor)
   * [pinList](#pinList-anchor)
+  * [getFilesByCount](#getFilesByCount-anchor)
   * [userPinnedDataTotal](#userPinnedDataTotal-anchor)
 <br />
 
@@ -102,46 +102,6 @@ pinata.hashMetadata('yourHashHere', metadata).then((result) => {
 });
 ```
 
-
-<a name="hashPinPolicy-anchor"></a>
-### `hashPinPolicy`
-Allows the user to change the pin policy for an individual piece of content.
-Changes made via this endpoint only affect the content for the hash passed in. They do not affect a user's account level pin policy.
-
-To read more about pin policies, please check out the [Regions and Replications Documentation](https://pinata.cloud/documentation#RegionsAndReplications).
-
-##### `pinata.hashPinPolicy(ipfsPinHash, newPinPolicy)`
-##### Params
-* `ipfsPinHash` - A string for a valid IPFS Hash that you have pinned on Pinata.
-* `newPinPolicy` A JSON object with a new [Pin Policy](#pinPolicies-anchor) for the hash.
-
-#### Response
-If the operation is successful, you will receive back an "OK" REST 200 status.
-
-##### Example Code
-```javascript
-const newPinPolicy = {
-    regions: [
-            {
-                id: 'FRA1',
-                desiredReplicationCount: 2
-            },
-            {
-                id: 'NYC1',
-                desiredReplicationCount: 2
-            }
-        ]
-    }
-};
-pinata.hashPinPolicy('yourHashHere', newPinPolicy).then((result) => {
-    //handle results here
-    console.log(result);
-}).catch((err) => {
-    //handle error here
-    console.log(err);
-});
-```
-
 <a name="pinByHash-anchor"></a>
 ### `pinByHash`
 Adds a hash to Pinata's pin queue to be pinned asynchronously. For the synchronous version of this operation see: [pinHashToIPFS](#pinHashToIPFS-anchor)
@@ -153,7 +113,6 @@ Adds a hash to Pinata's pin queue to be pinned asynchronously. For the synchrono
   * `pinataMetadata` (optional): A JSON object with [optional metadata](#metadata-anchor) for the hash being pinned
   * `pinataOptions`
      * `hostNodes` (optional): An array of [multiaddresses for nodes](#hostNode-anchor) that are currently hosting the content to be pinned
-     * `customPinPolicy` A JSON object with a new [Pin Policy](#pinPolicies-anchor) for the hash.
 #### Response
 ```
 {
@@ -177,19 +136,7 @@ const options = {
         hostNodes: [
             '/ip4/hostNode1ExternalIP/tcp/4001/ipfs/hostNode1PeerId',
             '/ip4/hostNode2ExternalIP/tcp/4001/ipfs/hostNode2PeerId'
-        ],
-        customPinPolicy: {
-            regions: [
-                {
-                    id: 'FRA1',
-                    desiredReplicationCount: 1
-                },
-                {
-                    id: 'NYC1',
-                    desiredReplicationCount: 2
-                }
-            ]
-        }
+        ]
     }
 };
 pinata.pinByHash('yourHashHere', options).then((result) => {
@@ -414,45 +361,6 @@ pinata.unpin(hashToUnpin).then((result) => {
 });
 ```
 
-<a name="userPinPolicy-anchor"></a>
-### `userPinPolicy`
-This allows the sender to change the pin policy their account.
-
-Following a successful call of this endpoint, the new pin policy provided will be utilized for every new piece of content pinned to IPFS via Pinata.
-
-To read more about pin policies, please check out the [Regions and Replications Documentation](https://pinata.cloud/documentation#RegionsAndReplications).
-
-##### `pinata.userPinPolicy(newPinPolicy)`
-##### Params
-* `newPinPolicy` A JSON object with a new [Pin Policy](#pinPolicies-anchor) for the hash.
-
-#### Response
-If the operation is successful, you will receive back an "OK" REST 200 status.
-
-##### Example Code
-```javascript
-const newPinPolicy = {
-    regions: [
-            {
-                id: 'FRA1',
-                desiredReplicationCount: 2
-            },
-            {
-                id: 'NYC1',
-                desiredReplicationCount: 2
-            }
-        ]
-    }
-};
-pinata.userPinPolicy(newPinPolicy).then((result) => {
-    //handle results here
-    console.log(result);
-}).catch((err) => {
-    //handle error here
-    console.log(err);
-});
-```
-
 <a name="testAuthentication-anchor"></a>
 ### `testAuthentication`
 Tests that you can authenticate with Pinata correctly
@@ -481,7 +389,7 @@ pinata.testAuthentication().then((result) => {
 
 <a name="pinList-anchor"></a>
 ### `pinList`
-Retrieve pin records for your Pinata account
+Retrieve pin records for your Pinata account. In order to get the next page you have to manipulate `pageLimit` and `pageOffset` filter to get the next page. This method no longer return the total count of pins. We highly encourage you to use the auto-pagination method [getFilesByCount](#getFilesByCount-anchor).
 
 ##### `pinata.pinList(filters)`
 ##### Params
@@ -555,14 +463,73 @@ As an example, the following filter would only find records whose name contains
 }
 ```
 
+Our libraries support auto-pagination. This feature easily handles fetching large lists of resources without having to manually paginate results and perform subsequent requests.
 
- 
-#### Response
+To use the auto-pagination feature in Node 10+, simply iterate over a "list" call with the parameters you need in a for await loop.
+
+<a name="getFilesByCount-anchor"></a>
+### `getFilesByCount-anchor`
+This method support auto-pagination. This feature easily handles fetching large lists of pin records for your Pinata account without having to manually paginate results and perform subsequent requests. To use the auto-pagination feature in Node 10+.
+
+##### `pinata.getFilesByCount(filters, count)`
+##### Params
+* `filters` (optional): An object that can consist of the following optional query parameters:
+  * `hashContains` (optional): A string of alphanumeric characters that desires hashes must contain
+  * `pinStart` (optional): The earliest date the content is allowed to have been pinned. Must be a valid [ISO_8601](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) date. 
+  * `pinEnd` (optional): The earliest date the content is allowed to have been pinned. Must be a valid [ISO_8601](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) date. 
+  * `unpinStart` (optional): The earlist date the content is allowed to have been unpinned. Must be a valid [ISO_8601](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) date. 
+  * `unpinEnd` (optional): The latest date the content is allowed to have been unpinned. Must be a valid [ISO_8601](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) date. 
+  * `pinSizeMin` (optional): The minimum byte size that pin record you're looking for can have
+  * `pinSizeMax` (optional): The maximum byte size that pin record you're looking for can have
+  * `status` (optional): Filter pins using one of the following options
+    * `'all'` (Records for both pinned and unpinned content will be returned)
+    * `'pinned'` (Only records for pinned content will be returned)
+    * `'unpinned'` (Only records for unpinned content will be returned)  
+  * `metadata` (optional): A JSON object that can be used to find records for content that had optional metadata included when it was added to Pinata. The metadata object is formatted as follows:
+* `count` (optional): A Number that specifies how many pins you want. if no number is provided then it will pull all the pins based on your filter
+
+##### Metadata filter object formatting
 ```
 {
-    count: (this is the total number of pin records that exist for the query filters you passed in),
-    rows: [
-        {
+    name: 'exampleName',
+    keyvalues: {
+        testKeyValue: {
+            value: 'exampleFilterValue',
+            op: 'exampleFilterOperation'
+        },
+        testKeyValue2: {
+            value: 'exampleFilterValue2',
+            op: 'exampleFilterOperation2'
+        }
+    }
+}
+```
+Filter explanations:
+* `name` (optional): If provided, any records returned must have a name that contains the string provided for the 'name'.
+* `keyvalues` (optional): Each keyvalue provided in this object have both a `value` and `op`
+  * `value` (required): This is the value which will be filtered on
+  * `op` (required): This is the filter operation that will be applied to the `value` that was provided. Valid op values are:
+     * `'gt'` (greater than the value provided)
+     * `'gte'` (greater than or equal to the value provided)
+     * `'lt'` (less than the value provided)
+     * `'lte'` (less than or equal to the value provided)
+     * `'ne'` (not equal to the value provided)
+     * `'eq'` (equal to the value provided)
+     * `'between'` (between the two values provided) - NOTE - This also requires a `secondValue` be provided as seen in the example below
+     * `'notBetween'` (not between the two values provided) - NOTE - This also requires a `secondValue` be provided as seen in the example below
+     * `'like'` (like the value provided)
+     * `'notLike'` (not like the value provided)
+     * `'iLike'` (case insensitive version of `like`)
+     * `'notILike'` (case insensitive version of `notLike`)
+     * `'regexp'` (filter the value provided based on a provided regular expression)
+     * `'iRegexp'` (case insensitive version of regexp)
+  
+```
+
+#### Response
+```
+[
+    {
             id: (the id of your pin instance record),
             ipfs_pin_hash: (the IPFS multi-hash for the content you pinned),
             size: (this is how large (in bytes) the content pinned is),
@@ -584,11 +551,15 @@ As an example, the following filter would only find records whose name contains
         .
         .
         .
-    ]
-}
+]
+
 ```
 ##### Example Code
+
 ```javascript
+const pinataSDK = require('@pinata/sdk');
+const pinata = pinataSDK('yourPinataApiKey', 'yourPinataSecretApiKey');
+
 const metadataFilter = {
     name: 'exampleName',
     keyvalues: {
@@ -609,13 +580,17 @@ const filters = {
     pageOffset: 0,
     metadata: metadataFilter
 };
-pinata.pinList(filters).then((result) => {
-    //handle results here
-    console.log(result);
-}).catch((err) => {
-    //handle error here
-    console.log(err);
-});
+
+ // more reference at [for await ...](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of)
+ for await (const item of pinata.getFilesByCount(filters, 35)) {
+    // ...(item) perform any task with the current item in the array of 35
+ }
+
+
+for await (const item of pinata.getFilesByCount(filters)) {
+    // ...(item) perform any task with the current item the array is determined by all your pins
+ }
+
 ```
 
 <a name="userPinnedDataTotal-anchor"></a>
@@ -724,26 +699,13 @@ The options object can consist of the following values:
 * wrapWithDirectory (optional) - Tells IPFS to wrap your content in a directory to preserve the content's original name. See [this blog post](https://flyingzumwalt.gitbooks.io/decentralized-web-primer/content/files-on-ipfs/lessons/wrap-directories-around-content.html) for more details on what this does. Valid options are:
   * `true`
   * `false`
-* customPinPolicy (optional) - a custom [Pin Policy](#pinPolicies-anchor) for the piece of content being pinned. Providing a custom pin policy as part of a request means that the content being pinned will be replicated differently from the user's default pin policy found under the [Account](https://pinata.cloud/account) page.
 
   
 ##### Example pinataOptions object
 ```
 {
     cidVersion: 1,
-    wrapWithDirectory: true,
-    customPinPolicy: {
-        regions: [
-            {
-                id: 'FRA1',
-                desiredReplicationCount: 2
-            },
-            {
-                id: 'NYC1',
-                desiredReplicationCount: 2
-            }
-        ]
-    }
+    wrapWithDirectory: true
 }
 ```