Version Packages (#149)

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

packages/auth/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @thirdweb-dev/auth
 
+## 2.0.4
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @thirdweb-dev/sdk@3.0.4
+
 ## 2.0.3
 
 ### Patch Changes

packages/auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdweb-dev/auth",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "exports": {
     "./package.json": "./package.json",
     "./express": {

packages/cli/CHANGELOG.md

@@ -1,5 +1,14 @@
 # thirdweb
 
+## 0.7.15
+
+### Patch Changes
+
+- [#148](https://github.com/thirdweb-dev/js/pull/148) [`964add6`](https://github.com/thirdweb-dev/js/commit/964add6f205577298b8f4b9ce7298e5bf09e88e7) Thanks [@joaquim-verges](https://github.com/joaquim-verges)! - Fix deploy/release CLI uploads
+
+- Updated dependencies []:
+  - @thirdweb-dev/sdk@3.0.4
+
 ## 0.7.14
 
 ### Patch Changes

packages/cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "thirdweb",
   "main": "dist/cli/index.js",
-  "version": "0.7.14",
+  "version": "0.7.15",
   "repository": "https://github.com/thirdweb-dev/js/tree/main/packages/cli",
   "author": "thirdweb eng <[email protected]>",
   "license": "Apache-2.0",

packages/cli/src/common/processor.ts

@@ -1,4 +1,4 @@
-import { THIRDWEB_URL, cliVersion } from "../constants/urls";
+import { cliVersion, THIRDWEB_URL } from "../constants/urls";
 import build from "../core/builder/build";
 import detect from "../core/detection/detect";
 import { execute } from "../core/helpers/exec";
@@ -142,10 +142,9 @@ export async function processProject(
     const metadataURIs = await Promise.all(
       selectedContracts.map(async (c) => {
         logger.debug(`Uploading ${c.name}...`);
-        const hash = await storage.upload(c.metadata, {
+        return await storage.upload(JSON.parse(c.metadata), {
           uploadWithoutDirectory: true,
         });
-        return `ipfs://${hash}`;
       }),
     );
 
@@ -173,15 +172,13 @@ export async function processProject(
     let combinedURIs: string[] = [];
     if (combinedContents.length === 1) {
       // use upload single if only one contract to get a clean IPFS hash
-      const metadataUri = await storage.upload(
-        JSON.stringify(combinedContents[0]),
-        { uploadWithoutDirectory: true },
-      );
+      const metadataUri = await storage.upload(combinedContents[0], {
+        uploadWithoutDirectory: true,
+      });
       combinedURIs.push(metadataUri);
     } else {
       // otherwise upload batch
-      const uris = await storage.uploadBatch(combinedContents);
-      combinedURIs = uris;
+      combinedURIs = await storage.uploadBatch(combinedContents);
     }
 
     loader.succeed("Upload successful");

packages/react/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @thirdweb-dev/react
 
+## 3.0.4
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @thirdweb-dev/sdk@3.0.4
+
 ## 3.0.3
 
 ### Patch Changes

packages/react/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdweb-dev/react",
-  "version": "3.0.3",
+  "version": "3.0.4",
   "repository": "https://github.com/thirdweb-dev/js/tree/main/packages/react",
   "author": "thirdweb eng <[email protected]>",
   "license": "Apache-2.0",

packages/sdk/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @thirdweb-dev/sdk
 
+## 3.0.4
+
+### Patch Changes
+
+- Updated dependencies [[`964add6`](https://github.com/thirdweb-dev/js/commit/964add6f205577298b8f4b9ce7298e5bf09e88e7)]:
+  - @thirdweb-dev/storage@1.0.1
+
 ## 3.0.3
 
 ### Patch Changes

packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdweb-dev/sdk",
-  "version": "3.0.3",
+  "version": "3.0.4",
   "description": "The main thirdweb SDK.",
   "repository": "https://github.com/thirdweb-dev/js/tree/main/packages/sdk",
   "license": "Apache-2.0",

packages/solana/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @thirdweb-dev/solana
 
+## 0.2.12
+
+### Patch Changes
+
+- Updated dependencies [[`964add6`](https://github.com/thirdweb-dev/js/commit/964add6f205577298b8f4b9ce7298e5bf09e88e7)]:
+  - @thirdweb-dev/storage@1.0.1
+
 ## 0.2.11
 
 ### Patch Changes

packages/solana/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdweb-dev/solana",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "description": "thirdweb Solana SDK",
   "main": "dist/thirdweb-dev-solana.cjs.js",
   "module": "dist/thirdweb-dev-solana.esm.js",

packages/storage/.gitignore

@@ -0,0 +1,3 @@
+docs/
+temp/
+etc/

packages/storage/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @thirdweb-dev/storage
 
+## 1.0.1
+
+### Patch Changes
+
+- [#148](https://github.com/thirdweb-dev/js/pull/148) [`964add6`](https://github.com/thirdweb-dev/js/commit/964add6f205577298b8f4b9ce7298e5bf09e88e7) Thanks [@joaquim-verges](https://github.com/joaquim-verges)! - Fix deploy/release CLI uploads
+
 ## 1.0.0
 
 ### Major Changes

packages/storage/config/api-extractor.json

@@ -0,0 +1,342 @@
+/**
+ * Config file for API Extractor.  For more info, please visit: https://api-extractor.com
+ */
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  /**
+   * Optionally specifies another JSON config file that this file extends from.  This provides a way for
+   * standard settings to be shared across multiple projects.
+   *
+   * If the path starts with "./" or "../", the path is resolved relative to the folder of the file that contains
+   * the "extends" field.  Otherwise, the first path segment is interpreted as an NPM package name, and will be
+   * resolved using NodeJS require().
+   *
+   * SUPPORTED TOKENS: none
+   * DEFAULT VALUE: ""
+   */
+  // "extends": "./shared/api-extractor-base.json"
+  // "extends": "my-package/include/api-extractor-base.json"
+  /**
+   * Determines the "<projectFolder>" token that can be used with other config file settings.  The project folder
+   * typically contains the tsconfig.json and package.json config files, but the path is user-defined.
+   *
+   * The path is resolved relative to the folder of the config file that contains the setting.
+   *
+   * The default value for "projectFolder" is the token "<lookup>", which means the folder is determined by traversing
+   * parent folders, starting from the folder containing api-extractor.json, and stopping at the first folder
+   * that contains a tsconfig.json file.  If a tsconfig.json file cannot be found in this way, then an error
+   * will be reported.
+   *
+   * SUPPORTED TOKENS: <lookup>
+   * DEFAULT VALUE: "<lookup>"
+   */
+  // "projectFolder": "..",
+  /**
+   * (REQUIRED) Specifies the .d.ts file to be used as the starting point for analysis.  API Extractor
+   * analyzes the symbols exported by this module.
+   *
+   * The file extension must be ".d.ts" and not ".ts".
+   *
+   * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+   * prepend a folder token such as "<projectFolder>".
+   *
+   * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+   */
+  "mainEntryPointFilePath": "<projectFolder>/dist/thirdweb-dev-storage.cjs.d.ts",
+  /**
+   * A list of NPM package names whose exports should be treated as part of this package.
+   *
+   * For example, suppose that Webpack is used to generate a distributed bundle for the project "library1",
+   * and another NPM package "library2" is embedded in this bundle.  Some types from library2 may become part
+   * of the exported API for library1, but by default API Extractor would generate a .d.ts rollup that explicitly
+   * imports library2.  To avoid this, we can specify:
+   *
+   *   "bundledPackages": [ "library2" ],
+   *
+   * This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been
+   * local files for library1.
+   */
+  "bundledPackages": [],
+  /**
+   * Determines how the TypeScript compiler engine will be invoked by API Extractor.
+   */
+  "compiler": {
+    /**
+     * Specifies the path to the tsconfig.json file to be used by API Extractor when analyzing the project.
+     *
+     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+     * prepend a folder token such as "<projectFolder>".
+     *
+     * Note: This setting will be ignored if "overrideTsconfig" is used.
+     *
+     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+     * DEFAULT VALUE: "<projectFolder>/tsconfig.json"
+     */
+    // "tsconfigFilePath": "<projectFolder>/tsconfig.json",
+    /**
+     * Provides a compiler configuration that will be used instead of reading the tsconfig.json file from disk.
+     * The object must conform to the TypeScript tsconfig schema:
+     *
+     * http://json.schemastore.org/tsconfig
+     *
+     * If omitted, then the tsconfig.json file will be read from the "projectFolder".
+     *
+     * DEFAULT VALUE: no overrideTsconfig section
+     */
+    // "overrideTsconfig": {
+    //   . . .
+    // }
+    /**
+     * This option causes the compiler to be invoked with the --skipLibCheck option. This option is not recommended
+     * and may cause API Extractor to produce incomplete or incorrect declarations, but it may be required when
+     * dependencies contain declarations that are incompatible with the TypeScript engine that API Extractor uses
+     * for its analysis.  Where possible, the underlying issue should be fixed rather than relying on skipLibCheck.
+     *
+     * DEFAULT VALUE: false
+     */
+    // "skipLibCheck": true,
+  },
+  /**
+   * Configures how the API report file (*.api.md) will be generated.
+   */
+  "apiReport": {
+    /**
+     * (REQUIRED) Whether to generate an API report.
+     */
+    "enabled": true
+    /**
+     * The filename for the API report files.  It will be combined with "reportFolder" or "reportTempFolder" to produce
+     * a full file path.
+     *
+     * The file extension should be ".api.md", and the string should not contain a path separator such as "\" or "/".
+     *
+     * SUPPORTED TOKENS: <packageName>, <unscopedPackageName>
+     * DEFAULT VALUE: "<unscopedPackageName>.api.md"
+     */
+    // "reportFileName": "<unscopedPackageName>.api.md",
+    /**
+     * Specifies the folder where the API report file is written.  The file name portion is determined by
+     * the "reportFileName" setting.
+     *
+     * The API report file is normally tracked by Git.  Changes to it can be used to trigger a branch policy,
+     * e.g. for an API review.
+     *
+     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+     * prepend a folder token such as "<projectFolder>".
+     *
+     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+     * DEFAULT VALUE: "<projectFolder>/etc/"
+     */
+    // "reportFolder": "<projectFolder>/etc/",
+    /**
+     * Specifies the folder where the temporary report file is written.  The file name portion is determined by
+     * the "reportFileName" setting.
+     *
+     * After the temporary file is written to disk, it is compared with the file in the "reportFolder".
+     * If they are different, a production build will fail.
+     *
+     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+     * prepend a folder token such as "<projectFolder>".
+     *
+     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+     * DEFAULT VALUE: "<projectFolder>/temp/"
+     */
+    // "reportTempFolder": "<projectFolder>/temp/"
+  },
+  /**
+   * Configures how the doc model file (*.api.json) will be generated.
+   */
+  "docModel": {
+    /**
+     * (REQUIRED) Whether to generate a doc model file.
+     */
+    "enabled": true
+    /**
+     * The output path for the doc model file.  The file extension should be ".api.json".
+     *
+     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+     * prepend a folder token such as "<projectFolder>".
+     *
+     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+     * DEFAULT VALUE: "<projectFolder>/temp/<unscopedPackageName>.api.json"
+     */
+    // "apiJsonFilePath": "<projectFolder>/temp/<unscopedPackageName>.api.json"
+  },
+  /**
+   * Configures how the .d.ts rollup file will be generated.
+   */
+  "dtsRollup": {
+    /**
+     * (REQUIRED) Whether to generate the .d.ts rollup file.
+     */
+    "enabled": false,
+    /**
+     * Specifies the output path for a .d.ts rollup file to be generated without any trimming.
+     * This file will include all declarations that are exported by the main entry point.
+     *
+     * If the path is an empty string, then this file will not be written.
+     *
+     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+     * prepend a folder token such as "<projectFolder>".
+     *
+     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+     * DEFAULT VALUE: "<projectFolder>/dist/<unscopedPackageName>.d.ts"
+     */
+    "untrimmedFilePath": "<projectFolder>/lib/<unscopedPackageName>.d.ts"
+    /**
+     * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.
+     * This file will include only declarations that are marked as "@public" or "@beta".
+     *
+     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+     * prepend a folder token such as "<projectFolder>".
+     *
+     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+     * DEFAULT VALUE: ""
+     */
+    // "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-beta.d.ts",
+    /**
+     * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "public" release.
+     * This file will include only declarations that are marked as "@public".
+     *
+     * If the path is an empty string, then this file will not be written.
+     *
+     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+     * prepend a folder token such as "<projectFolder>".
+     *
+     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+     * DEFAULT VALUE: ""
+     */
+    // "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts",
+    /**
+     * When a declaration is trimmed, by default it will be replaced by a code comment such as
+     * "Excluded from this release type: exampleMember".  Set "omitTrimmingComments" to true to remove the
+     * declaration completely.
+     *
+     * DEFAULT VALUE: false
+     */
+    // "omitTrimmingComments": true
+  },
+  /**
+   * Configures how the tsdoc-metadata.json file will be generated.
+   */
+  "tsdocMetadata": {
+    /**
+     * Whether to generate the tsdoc-metadata.json file.
+     *
+     * DEFAULT VALUE: true
+     */
+    // "enabled": true,
+    /**
+     * Specifies where the TSDoc metadata file should be written.
+     *
+     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+     * prepend a folder token such as "<projectFolder>".
+     *
+     * The default value is "<lookup>", which causes the path to be automatically inferred from the "tsdocMetadata",
+     * "typings" or "main" fields of the project's package.json.  If none of these fields are set, the lookup
+     * falls back to "tsdoc-metadata.json" in the package folder.
+     *
+     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+     * DEFAULT VALUE: "<lookup>"
+     */
+    // "tsdocMetadataFilePath": "<projectFolder>/dist/tsdoc-metadata.json"
+  },
+  /**
+   * Specifies what type of newlines API Extractor should use when writing output files.  By default, the output files
+   * will be written with Windows-style newlines.  To use POSIX-style newlines, specify "lf" instead.
+   * To use the OS's default newline kind, specify "os".
+   *
+   * DEFAULT VALUE: "crlf"
+   */
+  // "newlineKind": "crlf",
+  /**
+   * Configures how API Extractor reports error and warning messages produced during analysis.
+   *
+   * There are three sources of messages:  compiler messages, API Extractor messages, and TSDoc messages.
+   */
+  "messages": {
+    /**
+     * Configures handling of diagnostic messages reported by the TypeScript compiler engine while analyzing
+     * the input .d.ts files.
+     *
+     * TypeScript message identifiers start with "TS" followed by an integer.  For example: "TS2551"
+     *
+     * DEFAULT VALUE:  A single "default" entry with logLevel=warning.
+     */
+    "compilerMessageReporting": {
+      /**
+       * Configures the default routing for messages that don't match an explicit rule in this table.
+       */
+      "default": {
+        /**
+         * Specifies whether the message should be written to the the tool's output log.  Note that
+         * the "addToApiReportFile" property may supersede this option.
+         *
+         * Possible values: "error", "warning", "none"
+         *
+         * Errors cause the build to fail and return a nonzero exit code.  Warnings cause a production build fail
+         * and return a nonzero exit code.  For a non-production build (e.g. when "api-extractor run" includes
+         * the "--local" option), the warning is displayed but the build will not fail.
+         *
+         * DEFAULT VALUE: "warning"
+         */
+        "logLevel": "warning"
+        /**
+         * When addToApiReportFile is true:  If API Extractor is configured to write an API report file (.api.md),
+         * then the message will be written inside that file; otherwise, the message is instead logged according to
+         * the "logLevel" option.
+         *
+         * DEFAULT VALUE: false
+         */
+        // "addToApiReportFile": false
+      }
+      // "TS2551": {
+      //   "logLevel": "warning",
+      //   "addToApiReportFile": true
+      // },
+      //
+      // . . .
+    },
+    /**
+     * Configures handling of messages reported by API Extractor during its analysis.
+     *
+     * API Extractor message identifiers start with "ae-".  For example: "ae-extra-release-tag"
+     *
+     * DEFAULT VALUE: See api-extractor-defaults.json for the complete table of extractorMessageReporting mappings
+     */
+    "extractorMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+        // "addToApiReportFile": false
+      },
+      "ae-wrong-input-file-type": {
+        "logLevel": "warning"
+      }
+      // "ae-extra-release-tag": {
+      //   "logLevel": "warning",
+      //   "addToApiReportFile": true
+      // },
+      //
+      // . . .
+    },
+    /**
+     * Configures handling of messages reported by the TSDoc parser when analyzing code comments.
+     *
+     * TSDoc message identifiers start with "tsdoc-".  For example: "tsdoc-link-tag-unescaped-text"
+     *
+     * DEFAULT VALUE:  A single "default" entry with logLevel=warning.
+     */
+    "tsdocMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+        // "addToApiReportFile": false
+      }
+      // "tsdoc-link-tag-unescaped-text": {
+      //   "logLevel": "warning",
+      //   "addToApiReportFile": true
+      // },
+      //
+      // . . .
+    }
+  }
+}

packages/storage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdweb-dev/storage",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "main": "dist/thirdweb-dev-storage.cjs.js",
   "module": "dist/thirdweb-dev-storage.esm.js",
   "repository": "https://github.com/thirdweb-dev/js/tree/main/packages/storage",
@@ -10,6 +10,7 @@
     "format": "prettier --write 'src/**/*'",
     "lint": "eslint src/",
     "fix": "eslint src/ --fix",
+    "generate-docs": "api-extractor run --local && api-documenter markdown -i ./temp -o ./docs",
     "clean": "rm -rf dist/",
     "build": "tsc && preconstruct build",
     "test": "ts-mocha 'test/**/*.ts' --paths -t 120000 -r esm -p tsconfig.testing.json"
@@ -20,6 +21,8 @@
   "devDependencies": {
     "@babel/preset-env": "^7.18.10",
     "@babel/preset-typescript": "^7.18.6",
+    "@microsoft/api-documenter": "^7.19.13",
+    "@microsoft/api-extractor": "^7.31.1",
     "@preconstruct/cli": "^2.2.1",
     "@types/chai": "^4.3.3",
     "@types/mocha": "^9.1.1",
@@ -34,9 +37,10 @@
     "typescript": "^4.7.4"
   },
   "dependencies": {
+    "@microsoft/tsdoc": "^0.14.2",
     "cross-fetch": "^3.1.5",
     "form-data": "^4.0.0",
     "uuid": "^9.0.0",
     "zod": "^3.11.6"
   }
-}
+}

packages/storage/src/common/urls.ts

@@ -22,6 +22,9 @@ export const TW_IPFS_SERVER_URL = "https://upload.nftlabs.co";
  */
 export const PINATA_IPFS_URL = `https://api.pinata.cloud/pinning/pinFileToIPFS`;
 
+/**
+ * @internal
+ */
 export function prepareGatewayUrls(gatewayUrls?: GatewayUrls): GatewayUrls {
   const allGatewayUrls = {
     ...gatewayUrls,

packages/storage/src/common/utils.ts

@@ -7,24 +7,39 @@ import {
   JsonObject,
 } from "../types";
 
+/**
+ * @internal
+ */
 export function isBrowser() {
   return typeof window !== "undefined";
 }
 
+/**
+ * @internal
+ */
 export function isFileInstance(data: any): data is File {
   return global.File && data instanceof File;
 }
 
+/**
+ * @internal
+ */
 export function isBufferInstance(data: any): data is Buffer {
   return global.Buffer && data instanceof Buffer;
 }
 
+/**
+ * @internal
+ */
 export function isBufferOrStringWithName(
   data: any,
 ): data is BufferOrStringWithName {
   return data && data.name && data.data;
 }
 
+/**
+ * @internal
+ */
 export function replaceGatewayUrlWithScheme(
   uri: string,
   gatewayUrls: GatewayUrls,
@@ -40,6 +55,9 @@ export function replaceGatewayUrlWithScheme(
   return uri;
 }
 
+/**
+ * @internal
+ */
 export function replaceSchemeWithGatewayUrl(
   uri: string,
   gatewayUrls: GatewayUrls,
@@ -61,6 +79,9 @@ export function replaceSchemeWithGatewayUrl(
   return uri.replace(scheme, schemeGatewayUrls[index]);
 }
 
+/**
+ * @internal
+ */
 export function replaceObjectGatewayUrlsWithSchemes(
   data: Exclude<Json, FileOrBuffer>,
   gatewayUrls: GatewayUrls,
@@ -101,6 +122,9 @@ export function replaceObjectGatewayUrlsWithSchemes(
   return data;
 }
 
+/**
+ * @internal
+ */
 export function replaceObjectSchemesWithGatewayUrls(
   data: Exclude<Json, FileOrBuffer>,
   gatewayUrls: GatewayUrls,
@@ -140,6 +164,9 @@ export function replaceObjectSchemesWithGatewayUrls(
   return data;
 }
 
+/**
+ * @internal
+ */
 export function extractObjectFiles(
   data: Json,
   files: FileOrBuffer[] = [],
@@ -168,6 +195,9 @@ export function extractObjectFiles(
   return files;
 }
 
+/**
+ * @internal
+ */
 export function replaceObjectFilesWithUris(data: Json, uris: string[]): Json {
   const { success: isFileOrBuffer } = FileOrBufferSchema.safeParse(data);
   if (isFileOrBuffer) {

packages/storage/src/core/downloaders/storage-downloader.ts

@@ -3,6 +3,30 @@ import { replaceSchemeWithGatewayUrl } from "../../common/utils";
 import { GatewayUrls, IStorageDownloader } from "../../types";
 import fetch from "cross-fetch";
 
+/**
+ * Default downloader used - handles downloading from all schemes specified in the gateway URLs configuration.
+ *
+ * @example
+ * ```jsx
+ * // Can instantiate the downloader with the default gateway URLs
+ * const downloader = new StorageDownloader();
+ * const storage = new ThirdwebStorage(undefined, downloader);
+ *
+ * // Or optionally, can specify your own mapping of URLs
+ * const gatewayUrls = {
+ *   // We define a mapping of schemes to gateway URLs
+ *   "ipfs://": [
+ *     "https://gateway.ipfscdn.io/ipfs/",
+ *     "https://cloudflare-ipfs.com/ipfs/",
+ *     "https://ipfs.io/ipfs/",
+ *   ],
+ * };
+ * const downloader = new StorageDownloader(gatewayUrls);
+ * const storage = new ThirdwebStorage(undefined, downloader);
+ * ```
+ *
+ * @public
+ */
 export class StorageDownloader implements IStorageDownloader {
   public gatewayUrls: GatewayUrls;
 

packages/storage/src/core/storage.ts

@@ -16,6 +16,26 @@ import {
 import { StorageDownloader } from "./downloaders/storage-downloader";
 import { IpfsUploader } from "./uploaders/ipfs-uploader";
 
+/**
+ * Upload and download files from decentralized storage systems.
+ *
+ * @example
+ * ```jsx
+ * // Create a default storage class without any configuration
+ * const storage = new ThirdwebStorage();
+ *
+ * // Upload any file or JSON object
+ * const uri = await storage.upload(data);
+ * const result = await storage.download(uri);
+ *
+ * // Or configure a custom uploader and downloader
+ * const downloader = new StorageDownloader();
+ * const uploader = new IpfsUploader();
+ * const storage = new ThirdwebStorage(uploader, downloader)
+ * ```
+ *
+ * @public
+ */
 export class ThirdwebStorage<T extends UploadOptions = IpfsUploadBatchOptions> {
   private uploader: IStorageUploader<T>;
   private downloader: IStorageDownloader;
@@ -28,10 +48,35 @@ export class ThirdwebStorage<T extends UploadOptions = IpfsUploadBatchOptions> {
     this.downloader = downloader;
   }
 
+  /**
+   * Downloads arbitrary data from any URL scheme.
+   *
+   * @param url - The URL of the data to download
+   * @returns The response object fetched from the resolved URL
+   *
+   * @example
+   * ```jsx
+   * const uri = "ipfs://example";
+   * const data = await storage.download(uri);
+   * ```
+   */
   async download(url: string): Promise<Response> {
     return this.downloader.download(url);
   }
 
+  /**
+   * Downloads JSON data from any URL scheme.
+   * Resolves any URLs with schemes to retrievable gateway URLs.
+   *
+   * @param url - The URL of the JSON data to download
+   * @returns The JSON data fetched from the resolved URL
+   *
+   * @example
+   * ```jsx
+   * const uri = "ipfs://example"
+   * const json = await storage.downloadJSON(uri);
+   * ```
+   */
   async downloadJSON<TJSON = any>(url: string): Promise<TJSON> {
     const res = await this.download(url);
 
@@ -43,6 +88,25 @@ export class ThirdwebStorage<T extends UploadOptions = IpfsUploadBatchOptions> {
     ) as TJSON;
   }
 
+  /**
+   * Upload arbitrary file or JSON data using the configured decentralized storage system.
+   * Automatically uploads any file data within JSON objects and replaces them with hashes.
+   *
+   * @param data - Arbitrary file or JSON data to upload
+   * @param options - Options to pass through to the storage uploader class
+   * @returns - The URI of the uploaded data
+   *
+   * @example
+   * ```jsx
+   * // Upload file data
+   * const file = readFileSync("../file.jpg");
+   * const fileUri = await storage.upload(file);
+   *
+   * // Or upload a JSON object
+   * const json = { name: "JSON", image: file };
+   * const jsonUri = await storage.upload(json);
+   * ```
+   */
   async upload(data: Json | FileOrBuffer, options?: T): Promise<string> {
     const [uri] = await this.uploadBatch(
       [data] as Json[] | FileOrBuffer[],
@@ -51,6 +115,31 @@ export class ThirdwebStorage<T extends UploadOptions = IpfsUploadBatchOptions> {
     return uri;
   }
 
+  /**
+   * Batch upload arbitrary file or JSON data using the configured decentralized storage system.
+   * Automatically uploads any file data within JSON objects and replaces them with hashes.
+   *
+   * @param data - Array of arbitrary file or JSON data to upload
+   * @param options - Options to pass through to the storage uploader class
+   * @returns - The URIs of the uploaded data
+   *
+   * @example
+   * ```jsx
+   * // Upload an array of file data
+   * const files = [
+   *  readFileSync("../file1.jpg"),
+   *  readFileSync("../file2.jpg"),
+   * ];
+   * const fileUris = await storage.uploadBatch(files);
+   *
+   * // Upload an array of JSON objects
+   * const objects = [
+   *  { name: "JSON 1", image: files[0] },
+   *  { name: "JSON 2", image: files[1] },
+   * ];
+   * const jsonUris = await storage.uploadBatch(objects);
+   * ```
+   */
   async uploadBatch(
     data: Json[] | FileOrBuffer[],
     options?: T,
@@ -69,7 +158,12 @@ export class ThirdwebStorage<T extends UploadOptions = IpfsUploadBatchOptions> {
     // Otherwise it is an array of JSON objects, so we have to prepare it first
     const metadata = (
       await this.uploadAndReplaceFilesWithHashes(data as Json[], options)
-    ).map((item) => JSON.stringify(item));
+    ).map((item) => {
+      if (typeof item === "string") {
+        return item;
+      }
+      return JSON.stringify(item);
+    });
 
     return this.uploader.uploadBatch(metadata, options);
   }

packages/storage/src/core/uploaders/ipfs-uploader.ts

@@ -18,6 +18,35 @@ import {
 import fetch from "cross-fetch";
 import FormData from "form-data";
 
+/**
+ * Default uploader used - handles uploading arbitrary data to IPFS
+ *
+ * @example
+ * ```jsx
+ * // Can instantiate the uploader with default configuration
+ * const uploader = new StorageUploader();
+ * const storage = new ThirdwebStorage(uploader);
+ *
+ * // Or optionally, can pass configuration
+ * const gatewayUrls = {
+ *   // We define a mapping of schemes to gateway URLs
+ *   "ipfs://": [
+ *     "https://gateway.ipfscdn.io/ipfs/",
+ *     "https://cloudflare-ipfs.com/ipfs/",
+ *     "https://ipfs.io/ipfs/",
+ *   ],
+ * };
+ * const options = {
+ *   // Define cutom gateway URLs
+ *   gatewayUrls,
+ *   // Upload objects with resolvable URLs
+ *   uploadWithGatewayUrl: true,
+ * }
+ * const storage = new ThirdwebStorage(options);
+ * ```
+ *
+ * @public
+ */
 export class IpfsUploader implements IStorageUploader<IpfsUploadBatchOptions> {
   public gatewayUrls: GatewayUrls;
   public uploadWithGatewayUrl: boolean;

packages/storage/src/types/data.ts

@@ -14,6 +14,9 @@ const FileOrBufferUnionSchema = isBrowser()
   ? (z.instanceof(File) as z.ZodType<InstanceType<typeof File>>)
   : (z.instanceof(Buffer) as z.ZodTypeAny); // @fixme, this is a hack to make browser happy for now
 
+/**
+ * @internal
+ */
 export const FileOrBufferSchema = z.union([
   FileOrBufferUnionSchema,
   z.object({
@@ -22,20 +25,35 @@ export const FileOrBufferSchema = z.union([
   }),
 ]);
 
+/**
+ * @internal
+ */
 export const FileOrBufferOrStringSchema = z.union([
   FileOrBufferSchema,
   z.string(),
 ]);
 
+/**
+ * @internal
+ */
 export type FileOrBuffer = File | Buffer | BufferOrStringWithName;
 
+/**
+ * @internal
+ */
 export type BufferOrStringWithName = {
   data: Buffer | string;
   name: string;
 };
 
+/**
+ * @internal
+ */
 export type FileOrBufferOrString = FileOrBuffer | string;
 
+/**
+ * @internal
+ */
 export const JsonSchema: z.ZodType<Json> = z.lazy(() =>
   z.union([
     JsonLiteralSchema,
@@ -45,8 +63,17 @@ export const JsonSchema: z.ZodType<Json> = z.lazy(() =>
   ]),
 );
 
+/**
+ * @internal
+ */
 export const JsonObjectSchema = z.record(z.string(), JsonSchema);
 
+/**
+ * @internal
+ */
 export type Json = JsonLiteral | FileOrBuffer | JsonObject | Json[];
 
+/**
+ * @internal
+ */
 export type JsonObject = { [key: string]: Json };

packages/storage/src/types/download.ts

@@ -1,10 +1,28 @@
+/**
+ * @public
+ */
 export interface IStorageDownloader {
+  /**
+   * Gateway URLs used to replace schemes on download
+   */
   gatewayUrls: GatewayUrls;
+  /**
+   * Download arbitrary data from any URL scheme
+   *
+   * @param url - The URL to download data from
+   * @returns The response object of the fetch
+   */
   download(url: string): Promise<Response>;
 }
 
+/**
+ * @public
+ */
 export type GatewayUrls = {
   [key: string]: string[];
 };
 
+/**
+ * @internal
+ */
 export type MemoryStorage = Record<string, Record<string, any>>;

packages/storage/src/types/upload.ts

@@ -1,14 +1,36 @@
 import { FileOrBufferOrString } from "./data";
 import { GatewayUrls } from "./download";
 
+/**
+ * @public
+ */
 export type UploadOptions = { [key: string]: any };
 
+/**
+ * @public
+ */
 export interface IStorageUploader<T extends UploadOptions> {
+  /**
+   * If specified, will be used to replace any gateway URLs with schemes on upload
+   */
   gatewayUrls?: GatewayUrls;
+  /**
+   * If specified, will upload objects with gateway URLs instead of schemes
+   */
   uploadWithGatewayUrl?: boolean;
+  /**
+   * Upload an array of arbitrary file data or JSON strings
+   *
+   * @param data - Array of arbitrary file data or JSON strings to upload
+   * @param options - Options to pass through to the uploader
+   * @returns Array of uploaded file URIs
+   */
   uploadBatch(data: FileOrBufferOrString[], options?: T): Promise<string[]>;
 }
 
+/**
+ * @public
+ */
 export type UploadProgressEvent = {
   /**
    * The number of bytes uploaded.
@@ -21,16 +43,44 @@ export type UploadProgressEvent = {
   total: number;
 };
 
+/**
+ * @public
+ */
 export type IpfsUploaderOptions = {
+  /**
+   * Mapping of URL schemes to gateway URLs to resolve to
+   */
   gatewayUrls?: GatewayUrls;
+  /**
+   * Whether or not to replace any URLs with schemes with resolved URLs before upload
+   */
   uploadWithGatewayUrl?: boolean;
 };
 
+/**
+ * @public
+ */
 export type IpfsUploadBatchOptions = {
+  /**
+   * If specified, will rewrite file names to numbers for use on-chain.
+   * Useful to use with NFT contracts that map token IDs to files.
+   */
   rewriteFileNames?: {
+    /**
+     * The start number to replace file names with
+     */
     fileStartNumber: number;
   };
+  /**
+   * If specified, any URLs with schemes will be replaced with resolved URLs before upload
+   */
   uploadWithGatewayUrl?: boolean;
+  /**
+   * Callback that gets triggered when file upload progresses
+   */
   onProgress?: (event: UploadProgressEvent) => void;
+  /**
+   * If specified, will upload a single file without wrapping it in a directory
+   */
   uploadWithoutDirectory?: boolean;
 };