@pinata/sdk 1.1.20 → 1.1.24

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@pinata/sdk",
-  "version": "1.1.20",
+  "version": "1.1.24",
   "description": "Official SDK for the Pinata IPFS platform",
   "main": "lib/pinata-sdk.js",
+  "types": "types/index.d.ts",
   "scripts": {
-    "build": "webpack --env dev && webpack --env build && npm run test",
+    "build": "webpack --env dev && webpack --env build && npm run test && tsc",
     "coverage": "jest --coverage",
     "dev": "webpack --progress --colors --watch --env dev",
     "html": "open coverage/index.html",
@@ -37,6 +38,7 @@
     "@babel/core": "^7.8.4",
     "@babel/preset-env": "^7.9.0",
     "@babel/register": "^7.8.3",
+    "@types/node": "^15.6.1",
     "acorn": "^7.1.0",
     "babel-eslint": "^10.0.3",
     "babel-loader": "^8.0.6",
@@ -45,6 +47,7 @@
     "eslint": "^6.8.0",
     "eslint-loader": "^3.0.3",
     "jest": "^25.1.0",
+    "typescript": "^4.2.3",
     "uglifyjs-webpack-plugin": "^2.2.0",
     "webpack": "^4.41.6",
     "webpack-cli": "^3.3.11",

package/src/commands/data/pinList/pinList.js

@@ -4,6 +4,13 @@ import { validateApiKeys } from '../../../util/validators';
 import { handleError } from '../../../util/errorResponse';
 import queryBuilder from './queryBuilder';
 
+/**
+ * Pin List
+ * @param {string} pinataApiKey
+ * @param {string} pinataSecretApiKey
+ * @param {string} filters
+ * @returns {Promise<unknown>}
+ */
 export default function pinList(pinataApiKey, pinataSecretApiKey, filters) {
     validateApiKeys(pinataApiKey, pinataSecretApiKey);
 

package/src/commands/data/pinList/queryBuilder.js

@@ -1,3 +1,8 @@
+/**
+ * Validate and return data
+ * @param {*} dateToValidate
+ * @returns {*}
+ */
 function validateAndReturnDate(dateToValidate) {
     let dateParsed = new Date(Date.parse(dateToValidate));
 
@@ -12,6 +17,12 @@ function validateAndReturnDate(dateToValidate) {
     }
 }
 
+/**
+ * Query Builder
+ * @param {string} baseUrl
+ * @param {*} filters
+ * @returns {string}
+ */
 export default function queryBuilder(baseUrl, filters) {
     if (!baseUrl) {
         throw new Error('no baseUrl provided');

package/src/commands/data/testAuthentication.js

@@ -3,6 +3,12 @@ import { baseUrl } from './../../constants';
 import {validateApiKeys} from '../../util/validators';
 import { handleError } from '../../util/errorResponse';
 
+/**
+ * Test Authentication
+ * @param {string} pinataApiKey
+ * @param {string} pinataSecretApiKey
+ * @returns {Promise<unknown>}
+ */
 export default function testAuthentication(pinataApiKey, pinataSecretApiKey) {
     validateApiKeys(pinataApiKey, pinataSecretApiKey);
 

package/src/commands/data/userPinnedDataTotal.js

@@ -3,6 +3,12 @@ import { baseUrl } from './../../constants';
 import { validateApiKeys } from '../../util/validators';
 import { handleError } from '../../util/errorResponse';
 
+/**
+ * User Pinned Data Total
+ * @param {string} pinataApiKey
+ * @param {string} pinataSecretApiKey
+ * @returns {Promise<unknown>}
+ */
 export default function userPinnedDataTotal(pinataApiKey, pinataSecretApiKey) {
     validateApiKeys(pinataApiKey, pinataSecretApiKey);
 

package/src/commands/pinning/hashMetadata.js

@@ -4,6 +4,14 @@ import { validateApiKeys, validateMetadata } from '../../util/validators';
 import isIPFS from 'is-ipfs';
 import { handleError } from '../../util/errorResponse';
 
+/**
+ * Hash Meta Data
+ * @param {string} pinataApiKey
+ * @param {string} pinataSecretApiKey
+ * @param {*} ipfsPinHash
+ * @param {*} metadata
+ * @returns {Promise<unknown>}
+ */
 export default function hashMetadata(pinataApiKey, pinataSecretApiKey, ipfsPinHash, metadata) {
     validateApiKeys(pinataApiKey, pinataSecretApiKey);
 

package/src/commands/pinning/hashPinPolicy.js

@@ -4,6 +4,14 @@ import { validateApiKeys, validatePinPolicyStructure } from '../../util/validato
 import isIPFS from 'is-ipfs';
 import { handleError } from '../../util/errorResponse';
 
+/**
+ * Hash Pin Policy
+ * @param {string} pinataApiKey
+ * @param {string} pinataSecretApiKey
+ * @param {*} ipfsPinHash
+ * @param {*} newPinPolicy
+ * @returns {Promise<unknown>}
+ */
 export default function hashPinPolicy(pinataApiKey, pinataSecretApiKey, ipfsPinHash, newPinPolicy) {
     validateApiKeys(pinataApiKey, pinataSecretApiKey);
     validatePinPolicyStructure(newPinPolicy);

package/src/commands/pinning/pinByHash.js

@@ -4,6 +4,14 @@ import { validateApiKeys, validateMetadata } from '../../util/validators';
 import isIPFS from 'is-ipfs';
 import { handleError } from '../../util/errorResponse';
 
+/**
+ * Pin By Hash
+ * @param {string} pinataApiKey
+ * @param {string} pinataSecretApiKey
+ * @param {*} hashToPin
+ * @param {*} options
+ * @returns {Promise<unknown>}
+ */
 export default function pinByHash(pinataApiKey, pinataSecretApiKey, hashToPin, options) {
     validateApiKeys(pinataApiKey, pinataSecretApiKey);
 

package/src/commands/pinning/pinFileToIPFS.js

@@ -5,6 +5,14 @@ import stream from 'stream';
 import {validateApiKeys, validateMetadata, validatePinataOptions} from '../../util/validators';
 import { handleError } from '../../util/errorResponse';
 
+/**
+ * Pin File to IPFS
+ * @param {string} pinataApiKey
+ * @param {string} pinataSecretApiKey
+ * @param {*} readStream
+ * @param {*} options
+ * @returns {Promise<unknown>}
+ */
 export default function pinFileToIPFS(pinataApiKey, pinataSecretApiKey, readStream, options) {
     validateApiKeys(pinataApiKey, pinataSecretApiKey);
 
@@ -16,8 +24,8 @@ export default function pinFileToIPFS(pinataApiKey, pinataSecretApiKey, readStre
 
         const endpoint = `${baseUrl}/pinning/pinFileToIPFS`;
 
-        if (!(readStream instanceof stream.Readable)) {
-            reject(new Error('readStream is not a readable stream'));
+        if (!(readStream instanceof stream.Readable || readStream instanceof NodeFormData)) {
+            reject(new Error('readStream is not a readable stream or form data'));
         }
 
         if (options) {
@@ -33,7 +41,7 @@ export default function pinFileToIPFS(pinataApiKey, pinataSecretApiKey, readStre
 
         axios.post(
             endpoint,
-            data,
+            readStream instanceof NodeFormData ? readStream : data,
             {
                 withCredentials: true,
                 maxContentLength: 'Infinity', //this is needed to prevent axios from erroring out with large files

package/src/commands/pinning/pinFromFS.js

@@ -7,6 +7,14 @@ import { handleError } from '../../util/errorResponse';
 const fs = require('fs');
 const recursive = require('recursive-fs');
 
+/**
+ * PinFromFS
+ * @param {string} pinataApiKey
+ * @param {string} pinataSecretApiKey
+ * @param {string} sourcePath
+ * @param {*} options
+ * @returns {Promise<unknown>}
+ */
 export default function pinFromFS(pinataApiKey, pinataSecretApiKey, sourcePath, options) {
     validateApiKeys(pinataApiKey, pinataSecretApiKey);
 

package/src/commands/pinning/pinJSONToIPFS.js

@@ -3,6 +3,14 @@ import { baseUrl } from './../../constants';
 import { validateApiKeys, validateMetadata, validatePinataOptions } from '../../util/validators';
 import { handleError } from '../../util/errorResponse';
 
+/**
+ * Pin JSON to IPFS
+ * @param {string} pinataApiKey
+ * @param {string} pinataSecretApiKey
+ * @param {*} body
+ * @param {*} options
+ * @returns {Promise<unknown>}
+ */
 export default function pinJSONToIPFS(pinataApiKey, pinataSecretApiKey, body, options) {
     validateApiKeys(pinataApiKey, pinataSecretApiKey);
 

package/src/commands/pinning/pinJobs/pinJobs.js

@@ -4,6 +4,13 @@ import { validateApiKeys } from '../../../util/validators';
 import queryBuilder from './queryBuilder';
 import { handleError } from '../../../util/errorResponse';
 
+/**
+ * Pin Jobs
+ * @param {string} pinataApiKey
+ * @param {string} pinataSecretApiKey
+ * @param {*} filters
+ * @returns {Promise<unknown>}
+ */
 export default function pinJobs(pinataApiKey, pinataSecretApiKey, filters) {
     validateApiKeys(pinataApiKey, pinataSecretApiKey);
 

package/src/commands/pinning/pinJobs/queryBuilder.js

@@ -1,5 +1,11 @@
 import isIPFS from 'is-ipfs';
 
+/**
+ * Query Buidler
+ * @param {string} baseUrl
+ * @param {*} filters
+ * @returns {*}
+ */
 export default function queryBuilder(baseUrl, filters) {
     if (!baseUrl) {
         throw new Error('no baseUrl provided');

package/src/commands/pinning/unpin.js

@@ -4,6 +4,13 @@ import { validateApiKeys } from '../../util/validators';
 import isIPFS from 'is-ipfs';
 import { handleError } from '../../util/errorResponse';
 
+/**
+ * Unpin
+ * @param {string} pinataApiKey
+ * @param {string} pinataSecretApiKey
+ * @param {string} hashToUnpin
+ * @returns {Promise<unknown>}
+ */
 export default function unpin(pinataApiKey, pinataSecretApiKey, hashToUnpin) {
     validateApiKeys(pinataApiKey, pinataSecretApiKey);
 

package/src/commands/pinning/userPinPolicy.js

@@ -3,6 +3,13 @@ import { baseUrl } from './../../constants';
 import { validateApiKeys, validatePinPolicyStructure } from '../../util/validators';
 import { handleError } from '../../util/errorResponse';
 
+/**
+ * User Pin Policy
+ * @param {string} pinataApiKey
+ * @param {string} pinataSecretApiKey
+ * @param {*} newPinPolicy
+ * @returns {Promise<unknown>}
+ */
 export default function userPinPolicy(pinataApiKey, pinataSecretApiKey, newPinPolicy) {
     validateApiKeys(pinataApiKey, pinataSecretApiKey);
     validatePinPolicyStructure(newPinPolicy);

package/src/index.js

@@ -11,6 +11,233 @@ import testAuthentication from './commands/data/testAuthentication';
 import pinList from './commands/data/pinList/pinList';
 import userPinnedDataTotal from './commands/data/userPinnedDataTotal';
 
+// OPTIONS
+
+/**
+ * @typedef {Record<string, string | number | null>} PinataMetadata
+ */
+
+/**
+ * @typedef PinataMetadataFilter
+ * @property {string} [name]
+ * @property {Record<string, {value: string, op: string}>} keyvalues
+ */
+
+/**
+ * @typedef {{id: string, desiredReplicationCount: number}} PinataPinPolicyItem
+ */
+
+/**
+ * @typedef PinataPinByHashOptions
+ * @property {string[]} [hostNodes]
+ * @property {{regions: PinataPinPolicyItem[]}} [customPinPolicy]
+ */
+
+/**
+ * @typedef PinataPinByHashPinOptions
+ * @property {PinataMetadata} [pinataMetadata]
+ * @property {PinataPinByHashOptions} [pinataOptions]
+ */
+
+/**
+ * @typedef PinataOptions
+ * @property {0 | 1} [cidVersion]
+ * @property {boolean} [wrapWithDirectory]
+ * @property {{regions: PinataPinPolicyItem[]}} [customPinPolicy]
+ */
+
+/**
+ * @typedef PinataPinOptions
+ * @property {PinataMetadata} [pinataMetadata]
+ * @property {PinataOptions} [pinataOptions]
+ */
+
+/**
+ * @typedef PinataPinJobsFilterOptions
+ * @property {'ASC' | 'DESC'} sort
+ * @property {string} [status]
+ * @property {string} [ipfs_pin_hash]
+ * @property {number} [limit]
+ * @property {number} [offset]
+ */
+
+/**
+ * @typedef PinataPinListFilterOptions
+ * @property {string} [hashContains]
+ * @property {string} [pinStart]
+ * @property {string} [pinEnd]
+ * @property {string} [unpinStart]
+ * @property {string} [unpinEnd]
+ * @property {number} [pinSizeMin]
+ * @property {number} [pinSizeMax]
+ * @property {string} [status]
+ * @property {number} [pageLimit]
+ * @property {number} [pageOffset]
+ * @property {PinataMetadataFilter} [metadata]
+ */
+
+// RESPONSES
+
+/**
+ * @typedef PinataPinByHashResponse
+ * @property {number | string} id
+ * @property {string} ipfsHash
+ * @property {string} status
+ * @property {string} name
+ */
+
+/**
+ * @typedef PinataPinResponse
+ * @property {string} IpfsHash
+ * @property {number} PinSize
+ * @property {string} Timestamp
+ */
+
+/**
+ * @typedef PinataPinJobsResponseRow
+ * @property {number | string} id
+ * @property {string} ipfs_pin_hash
+ * @property {string} date_queued
+ * @property {string | undefined | null} name
+ * @property {string} status
+ */
+
+/**
+ * @typedef PinataPinJobsResponse
+ * @property {number} count
+ * @property {PinataPinJobsResponseRow[]} rows
+ */
+
+/**
+ * @typedef PinataPinListResponseRow
+ * @property {number | string} id
+ * @property {string} ipfs_pin_hash
+ * @property {number} size
+ * @property {string | number} user_id
+ * @property {string} date_pinned
+ * @property {string} date_unpinned
+ * @property {PinataMetadata} metadata
+ */
+
+/**
+ * @typedef PinataPinListResponse
+ * @property {number} count
+ * @property {PinataPinListResponseRow[]} rows
+ */
+
+// METHODS
+
+/**
+ * Hash meta data
+ * @callback hashMetadata
+ * @param {string} ipfsPinHash
+ * @param {PinataMetadata} metadata
+ * @returns {Promise<any>}
+ */
+
+/**
+ * Hash pin policy
+ * @callback hashPinPolicy
+ * @param {string} ipfsPinHash
+ * @param {{regions: PinataPinPolicyItem[]}} newPinPolicy
+ * @returns {Promise<any>}
+ */
+
+/**
+ * Pin by hash
+ * @callback pinByHash
+ * @param {string} hashToPin
+ * @param {PinataPinByHashPinOptions} [options]
+ * @returns {Promise<PinataPinByHashResponse>}
+ */
+
+/**
+ * Pin file to IPFS
+ * @callback pinFileToIPFS
+ * @param {ReadStream} readableStream
+ * @param {PinataPinOptions} [options]
+ * @returns {Promise<PinataPinResponse>}
+ */
+
+/**
+ * Pin from FS
+ * @callback pinFromFS
+ * @param {string} sourcePath
+ * @param {PinataPinOptions} [options]
+ * @returns {Promise<PinataPinResponse>}
+ */
+
+/**
+ * Pin Jobs
+ * @callback pinJobs
+ * @param {PinataPinJobsFilterOptions} [filters]
+ * @returns {Promise<PinataPinJobsResponse>}
+ */
+
+/**
+ * Pin JSON to IPFS
+ * @callback pinJSONToIPFS
+ * @param {Object} body
+ * @param {PinataPinOptions} [options]
+ * @returns {Promise<PinataPinResponse>}
+ */
+
+/**
+ * Unpin
+ * @callback unpin
+ * @param {string} hashToUnpin
+ * @returns {Promise<any>}
+ */
+
+/**
+ * User Pin Policy
+ * @callback userPinPolicy
+ * @param {{regions: PinataPinPolicyItem[]}} newPinPolicy
+ * @returns {Promise<any>}
+ */
+
+/**
+ * Test Authentication
+ * @callback testAuthentication
+ * @returns {Promise<{authenticated: boolean}>}
+ */
+
+/**
+ * Pin List
+ * @callback pinList
+ * @param {PinataPinListFilterOptions} [filters]
+ * @returns {Promise<PinataPinListResponse>}
+ */
+
+/**
+ * User Pinned Data Total
+ * @callback userPinnedDataTotal
+ * @returns {Promise<number>}
+ */
+
+/**
+ * @typedef PinataClient
+ * @property {pinByHash} pinByHash
+ * @property {hashMetadata} hashMetadata
+ * @property {hashPinPolicy} hashPinPolicy
+ * @property {pinFileToIPFS} pinFileToIPFS
+ * @property {pinFromFS} pinFromFS
+ * @property {pinJSONToIPFS} pinJSONToIPFS
+ * @property {pinJobs} pinJobs
+ * @property {unpin} unpin
+ * @property {userPinPolicy} userPinPolicy
+ * @property {testAuthentication} testAuthentication
+ * @property {pinList} pinList
+ * @property {userPinnedDataTotal} userPinnedDataTotal
+ */
+
+/**
+ * Pinata Client
+ *
+ * @param {string} pinataApiKey
+ * @param {string} pinataSecretApiKey
+ * @returns {PinataClient}
+ */
 export default function pinataClient(pinataApiKey, pinataSecretApiKey) {
     let client = {};
 

package/src/util/validators.js

@@ -1,5 +1,10 @@
 import isIPFS from 'is-ipfs';
 
+/**
+ * Validate API Keys
+ * @param {string} pinataApiKey
+ * @param {string} pinataSecretApiKey
+ */
 export function validateApiKeys(pinataApiKey, pinataSecretApiKey) {
     if (!pinataApiKey || pinataApiKey === '') {
         throw new Error('No pinataApiKey provided! Please provide your pinata api key as an argument when you start this script');
@@ -9,6 +14,10 @@ export function validateApiKeys(pinataApiKey, pinataSecretApiKey) {
     }
 }
 
+/**
+ * Validate host Nodes
+ * @param {*} hostNodes
+ */
 export function validateHostNodes(hostNodes) {
     if (!Array.isArray(hostNodes)) {
         throw new Error('host_nodes value must be an array');
@@ -20,6 +29,10 @@ export function validateHostNodes(hostNodes) {
     });
 }
 
+/**
+ * Validate MetaData
+ * @param {*} metadata
+ */
 export function validateMetadata(metadata) {
     if (metadata.name) {
         if (!(typeof metadata.name === 'string' || metadata.name instanceof String)) {
@@ -47,6 +60,10 @@ export function validateMetadata(metadata) {
     }
 }
 
+/**
+ * Validate Pin Policy Structure
+ * @param {*} pinPolicy
+ */
 export function validatePinPolicyStructure(pinPolicy) {
     //this function takes in a pin policy and checks the JSON structure to make sure it's valid
     if (!pinPolicy) {
@@ -69,6 +86,10 @@ export function validatePinPolicyStructure(pinPolicy) {
     }
 }
 
+/**
+ * Validate Pinata Options
+ * @param {*} options
+ */
 export function validatePinataOptions(options) {
     if (typeof options !== 'object') {
         throw new Error('options must be an object');

package/test/commands/pinning/pinFileToIPFS.test.js

@@ -1,20 +1,23 @@
 import axios from 'axios';
 import pinFileToIPFS from'../../../src/commands/pinning/pinFileToIPFS';
 import fs from 'fs';
+import NodeFormData from 'form-data';
 jest.mock('axios');
 
 //common values
 const nonStream = 'test';
 const validStream = fs.createReadStream('./pinata.png');
+const validFormData = new NodeFormData();
+validFormData.append('file', validStream, {filepath: 'test/filepath'});
 
 
-test('non-readableStream is passed in', () => {
-    expect(pinFileToIPFS('test', 'test', nonStream)).rejects.toEqual(Error('readStream is not a readable stream'));
+test('non-readableStream and non-formData is passed in', () => {
+    expect(pinFileToIPFS('test', 'test', nonStream)).rejects.toEqual(Error('readStream is not a readable stream or form data'));
 
     return undefined;
 });
 
-test('200 status is returned', () => {
+test('200 status is returned with valid stream', () => {
     const goodStatus = {
         status: 200,
         data: 'testData'
@@ -24,6 +27,16 @@ test('200 status is returned', () => {
     expect(pinFileToIPFS('test', 'test', validStream)).resolves.toEqual(goodStatus.data);
 });
 
+test('200 status is returned with valid form data', () => {
+    const goodStatus = {
+        status: 200,
+        data: 'testData'
+    };
+    axios.post.mockResolvedValue(goodStatus);
+    expect.assertions(1);
+    expect(pinFileToIPFS('test', 'test', validFormData)).resolves.toEqual(goodStatus.data);
+});
+
 test('Result other than 200 status is returned', () => {
     const badStatus = {
         status: 700

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "include": [
+    "src/**/*.js"
+  ],
+  "compilerOptions": {
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "allowJs": true,
+    "outDir": "types",
+    "target": "es5",
+    "module": "commonjs",
+    "lib": ["es2017", "es7", "es6", "dom"],
+    "strict": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  },
+  "exclude": [
+    "node_modules",
+    "lib",
+    "test",
+    "coverage"
+  ]
+}

package/types/commands/data/pinList/pinList.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Pin List
+ * @param {string} pinataApiKey
+ * @param {string} pinataSecretApiKey
+ * @param {string} filters
+ * @returns {Promise<unknown>}
+ */
+export default function pinList(pinataApiKey: string, pinataSecretApiKey: string, filters: string): Promise<unknown>;

package/types/commands/data/pinList/queryBuilder.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Query Builder
+ * @param {string} baseUrl
+ * @param {*} filters
+ * @returns {string}
+ */
+export default function queryBuilder(baseUrl: string, filters: any): string;

package/types/commands/data/testAuthentication.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Test Authentication
+ * @param {string} pinataApiKey
+ * @param {string} pinataSecretApiKey
+ * @returns {Promise<unknown>}
+ */
+export default function testAuthentication(pinataApiKey: string, pinataSecretApiKey: string): Promise<unknown>;

package/types/commands/data/userPinnedDataTotal.d.ts

@@ -0,0 +1,7 @@
+/**
+ * User Pinned Data Total
+ * @param {string} pinataApiKey
+ * @param {string} pinataSecretApiKey
+ * @returns {Promise<unknown>}
+ */
+export default function userPinnedDataTotal(pinataApiKey: string, pinataSecretApiKey: string): Promise<unknown>;

package/types/commands/pinning/hashMetadata.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Hash Meta Data
+ * @param {string} pinataApiKey
+ * @param {string} pinataSecretApiKey
+ * @param {*} ipfsPinHash
+ * @param {*} metadata
+ * @returns {Promise<unknown>}
+ */
+export default function hashMetadata(pinataApiKey: string, pinataSecretApiKey: string, ipfsPinHash: any, metadata: any): Promise<unknown>;

package/types/commands/pinning/hashPinPolicy.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Hash Pin Policy
+ * @param {string} pinataApiKey
+ * @param {string} pinataSecretApiKey
+ * @param {*} ipfsPinHash
+ * @param {*} newPinPolicy
+ * @returns {Promise<unknown>}
+ */
+export default function hashPinPolicy(pinataApiKey: string, pinataSecretApiKey: string, ipfsPinHash: any, newPinPolicy: any): Promise<unknown>;