{"id":14956128,"url":"https://github.com/ipfs/js-kubo-rpc-client","last_synced_at":"2025-04-05T05:04:44.792Z","repository":{"id":56855916,"uuid":"526346597","full_name":"ipfs/js-kubo-rpc-client","owner":"ipfs","description":"A client library for the Kubo RPC API","archived":false,"fork":false,"pushed_at":"2024-10-29T10:07:41.000Z","size":20705,"stargazers_count":35,"open_issues_count":28,"forks_count":7,"subscribers_count":15,"default_branch":"main","last_synced_at":"2024-10-29T12:11:38.162Z","etag":null,"topics":["http-client","ipfs","kubo","rpc-client"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/kubo-rpc-client","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ipfs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-18T19:24:23.000Z","updated_at":"2024-10-16T09:40:59.000Z","dependencies_parsed_at":"2024-03-21T15:58:54.395Z","dependency_job_id":"82149b03-73a3-434a-bd70-a334efe3d4ce","html_url":"https://github.com/ipfs/js-kubo-rpc-client","commit_stats":{"total_commits":355,"total_committers":33,"mean_commits":"10.757575757575758","dds":0.4197183098591549,"last_synced_commit":"8a3f783528e99f51abc4f9c1f29e9a196720ec5c"},"previous_names":[],"tags_count":111,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fjs-kubo-rpc-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fjs-kubo-rpc-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fjs-kubo-rpc-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fjs-kubo-rpc-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ipfs","download_url":"https://codeload.github.com/ipfs/js-kubo-rpc-client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238748587,"owners_count":19523995,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["http-client","ipfs","kubo","rpc-client"],"created_at":"2024-09-24T13:12:21.482Z","updated_at":"2025-02-16T16:18:00.414Z","avatar_url":"https://github.com/ipfs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kubo-rpc-client \u003c!-- omit in toc --\u003e\n\n[![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech)\n[![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech)\n[![codecov](https://img.shields.io/codecov/c/github/ipfs/js-kubo-rpc-client.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-kubo-rpc-client)\n[![CI](https://img.shields.io/github/actions/workflow/status/ipfs/js-kubo-rpc-client/js-test-and-release.yml?branch=main\\\u0026style=flat-square)](https://github.com/ipfs/js-kubo-rpc-client/actions/workflows/js-test-and-release.yml?query=branch%3Amain)\n\n\u003e A client library for the Kubo RPC API\n\n## Table of contents \u003c!-- omit in toc --\u003e\n\n- [Install](#install)\n  - [Browser `\u003cscript\u003e` tag](#browser-script-tag)\n- [Kubo RPC Client](#kubo-rpc-client)\n- [Getting Started](#getting-started)\n  - [Next Steps](#next-steps)\n- [Usage](#usage)\n    - [`create([options])`](#createoptions)\n    - [Parameters](#parameters)\n    - [Options](#options)\n    - [Returns](#returns)\n    - [Example](#example)\n  - [API](#api)\n  - [Additional Options](#additional-options)\n  - [Instance Utils](#instance-utils)\n  - [Static Types and Utils](#static-types-and-utils)\n    - [Glob source](#glob-source)\n      - [`globSource(path, pattern, [options])`](#globsourcepath-pattern-options)\n      - [Example](#example-1)\n    - [URL source](#url-source)\n      - [`urlSource(url)`](#urlsourceurl)\n      - [Example](#example-2)\n  - [Running the daemon with the right port](#running-the-daemon-with-the-right-port)\n  - [Importing the module and usage](#importing-the-module-and-usage)\n  - [In a web browser](#in-a-web-browser)\n  - [Custom Headers](#custom-headers)\n  - [Global Timeouts](#global-timeouts)\n- [Development](#development)\n  - [Testing](#testing)\n- [Historical context](#historical-context)\n- [License](#license)\n- [Contribute](#contribute)\n\n## Install\n\n```console\n$ npm i kubo-rpc-client\n```\n\n### Browser `\u003cscript\u003e` tag\n\nLoading this module through a script tag will make it's exports available as `KuboRpcClient` in the global namespace.\n\n```html\n\u003cscript src=\"https://unpkg.com/kubo-rpc-client/dist/index.min.js\"\u003e\u003c/script\u003e\n```\n\n## Kubo RPC Client\n\n\u003ch3 align=\"center\"\u003eJavaScript client library for the Kubo RPC API\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://app.element.io/#/room/#ipfs-chatter:ipfs.io\"\u003e\u003cimg src=\"https://img.shields.io/badge/matrix-%23ipfs%3Amatrix.org-blue.svg?style=flat\" /\u003e \u003c/a\u003e\n  \u003ca href=\"https://discord.gg/ipfs\"\u003e\u003cimg src=\"https://img.shields.io/discord/806902334369824788?color=blueviolet\u0026label=discord\u0026style=flat\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/ipfs/team-mgmt/blob/master/MGMT_JS_CORE_DEV.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/team-mgmt-blue.svg?style=flat\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://codecov.io/gh/ipfs/js-kubo-rpc-client\"\u003e\u003cimg src=\"https://img.shields.io/codecov/c/github/ipfs/js-kubo-rpc-client/master.svg?style=flat-square\"\u003e\u003c/a\u003e\n   \u003ca href=\"https://bundlephobia.com/result?p=kubo-rpc-client\"\u003e\u003cimg src=\"https://flat.badgen.net/bundlephobia/minzip/kubo-rpc-client\"\u003e\u003c/a\u003e\n  \u003cbr\u003e\n  \u003ca href=\"https://github.com/feross/standard\"\u003e\u003cimg src=\"https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/RichardLitt/standard-readme\"\u003e\u003cimg src=\"https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square\" /\u003e\u003c/a\u003e\n  \u003ca href=\"\"\u003e\u003cimg src=\"https://img.shields.io/badge/npm-%3E%3D3.0.0-orange.svg?style=flat-square\" /\u003e\u003c/a\u003e\n  \u003ca href=\"\"\u003e\u003cimg src=\"https://img.shields.io/badge/Node.js-%3E%3D10.0.0-orange.svg?style=flat-square\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/kubo-rpc-client\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/kubo-rpc-client.svg\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.jsdelivr.com/package/npm/kubo-rpc-client\"\u003e\u003cimg src=\"https://data.jsdelivr.com/v1/package/npm/kubo-rpc-client/badge\"/\u003e\u003c/a\u003e\n  \u003cbr\u003e\n\u003c/p\u003e\n\n## Getting Started\n\nWe've come a long way, but this project is still in Alpha, lots of development is happening, APIs might change, beware of 🐉..\n\n```bash\nnpm install --save kubo-rpc-client\n```\n\nBoth the Current and Active LTS versions of Node.js are supported. Please see [nodejs.org](https://nodejs.org/) for what these currently are.\n\n### Next Steps\n\n\u003c!-- TODO: currently useless\n- Read the [docs](https://ipfs.github.io/js-kubo-rpc-client)\n--\u003e\n\n- Look into the [examples](https://github.com/ipfs-examples/js-ipfs-examples) to learn how to spawn an RPC client or a full IPFS node in Node.js and in the Browser\n- Consult the [Core API docs](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) to see what you can do with an IPFS node\n- Check out \u003chttps://docs.ipfs.tech\u003e for tips, how-tos and more\n- Head over to \u003chttps://proto.school\u003e to take interactive tutorials that cover core IPFS APIs\n- See \u003chttps://blog.ipfs.tech\u003e for news and more\n- Need help? Please ask 'How do I?' questions on \u003chttps://discuss.ipfs.tech\u003e\n\n## Usage\n\n#### `create([options])`\n\n\u003e create an instance of the HTTP API client\n\n#### Parameters\n\nNone\n\n#### Options\n\n`options` can be a `String`, a `URL` or a `Multiaddr` which will be interpreted as the address of the IPFS node we wish to use the API of.\n\nAlternatively it can be an object which may have the following keys:\n\n| Name     | Type                                                                 | Default                                          | Description                                                                                                    |\n| -------- | -------------------------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |\n| url      | `String` or `URL` or `Multiaddr`                                     | `'http://localhost:5001/api/v0'`                 | A URL that resolves to a running instance of the IPFS [HTTP RPC API](https://docs.ipfs.io/reference/http/api/) |\n| protocol | `String`                                                             | `'http'`                                         | The protocol to used (ignored if url is specified)                                                             |\n| host     | `String`                                                             | `'localhost'`                                    | The host to used (ignored if url is specified)                                                                 |\n| port     | `number`                                                             | `5001`                                           | The port to used (ignored if url is specified)                                                                 |\n| path     | `String`                                                             | `'api/v0'`                                       | The path to used (ignored if url is specified)                                                                 |\n| agent    | [http.Agent](https://nodejs.org/api/http.html#http_class_http_agent) | `http.Agent({ keepAlive: true, maxSockets: 6 })` | An `http.Agent` used to control client behaviour (node.js only)                                                |\n\n#### Returns\n\n| Type     | Description                                                                                               |\n| -------- | --------------------------------------------------------------------------------------------------------- |\n| `Object` | An object that conforms to the [IPFS Core API](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) |\n\n#### Example\n\n```JavaScript\nimport { create } from 'kubo-rpc-client'\n\n// connect to the default API address http://localhost:5001\nconst client = create()\n\n// connect to a different API\nconst client = create({ url: \"http://127.0.0.1:5002/api/v0\" });\n\n// connect using a URL\nconst client = create(new URL('http://127.0.0.1:5002'))\n\n// call Core API methods\nconst { cid } = await client.add('Hello world!')\n```\n\nDo you use Kubo's [**`API.Authorizations`**](https://github.com/ipfs/kubo/blob/master/docs/config.md#apiauthorizations)? Check the [Custom Headers](#custom-headers) section.\n\n### API\n\n`kubo-rpc-client` will not implement the [IPFS Core API](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api). Please see \u003chttps://github.com/ipfs/kubo/issues/9125\u003e for more information.\n\n### Additional Options\n\nAll core API methods take *additional* `options` specific to the HTTP API:\n\n- `headers` - An object or [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) instance that can be used to set custom HTTP headers. Note that this option can also be [configured globally](#custom-headers) via the constructor options.\n- `searchParams` - An object or [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) instance that can be used to add additional query parameters to the query string sent with each request.\n\n### Instance Utils\n\n- `ipfs.getEndpointConfig()`\n\nCall this on your client instance to return an object containing the `host`, `port`, `protocol` and `api-path`.\n\n### Static Types and Utils\n\nAside from the default export, `kubo-rpc-client` exports various types and utilities that are included in the bundle:\n\n- [`multiaddr`](https://www.npmjs.com/package/multiaddr)\n- [`multibase`](https://www.npmjs.com/package/multibase)\n- [`multicodec`](https://www.npmjs.com/package/multicodec)\n- [`multihash`](https://www.npmjs.com/package/multihashes)\n- [`CID`](https://www.npmjs.com/package/cids)\n- [`globSource`](https://github.com/ipfs/js-ipfs-utils/blob/master/src/files/glob-source.js) (not available in the browser)\n- [`urlSource`](https://github.com/ipfs/js-ipfs-utils/blob/master/src/files/url-source.js)\n\nThese can be accessed like this, for example:\n\n```js\nimport { CID } from 'kubo-rpc-client'\n```\n\n#### Glob source\n\nA utility to allow files on the file system to be easily added to IPFS.\n\n##### `globSource(path, pattern, [options])`\n\n- `path`: A path to a single file or directory to glob from\n- `pattern`: A pattern to match files under `path`\n- `options`: Optional options\n- `options.hidden`: Hidden/dot files (files or folders starting with a `.`, for example, `.git/`) are not included by default. To add them, use the option `{ hidden: true }`.\n\nReturns an async iterable that yields `{ path, content }` objects suitable for passing to `ipfs.add`.\n\n##### Example\n\n```js\nimport { create, globSource } from 'ipfs'\n\nconst ipfs = await create()\n\nfor await (const file of ipfs.addAll(globSource('./docs', '**/*'))) {\n  console.log(file)\n}\n/*\n{\n  path: 'docs/assets/anchor.js',\n  cid: CID('QmVHxRocoWgUChLEvfEyDuuD6qJ4PhdDL2dTLcpUy3dSC2'),\n  size: 15347\n}\n{\n  path: 'docs/assets/bass-addons.css',\n  cid: CID('QmPiLWKd6yseMWDTgHegb8T7wVS7zWGYgyvfj7dGNt2viQ'),\n  size: 232\n}\n...\n*/\n```\n\n#### URL source\n\nA utility to allow content from the internet to be easily added to IPFS.\n\n##### `urlSource(url)`\n\n- `url`: A string URL or [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) instance to send HTTP GET request to\n\nReturns an async iterable that yields `{ path, content }` objects suitable for passing to `ipfs.add`.\n\n##### Example\n\n```js\nimport { create, urlSource } from 'kubo-rpc-client'\nconst ipfs = create()\n\nconst file = await ipfs.add(urlSource('https://ipfs.io/images/ipfs-logo.svg'))\nconsole.log(file)\n\n/*\n{\n  path: 'ipfs-logo.svg',\n  cid: CID('QmTqZhR6f7jzdhLgPArDPnsbZpvvgxzCZycXK7ywkLxSyU'),\n  size: 3243\n}\n*/\n```\n\n### Running the daemon with the right port\n\nTo interact with the API, you need to have a local daemon running. It needs to be open on the right port. `5001` is the default, and is used in the examples below, but it can be set to whatever you need.\n\n```sh\n# Show the ipfs config API port to check it is correct\n\u003e ipfs config Addresses.API\n/ip4/127.0.0.1/tcp/5001\n# Set it if it does not match the above output\n\u003e ipfs config Addresses.API /ip4/127.0.0.1/tcp/5001\n# Restart the daemon after changing the config\n\n# Run the daemon\n\u003e ipfs daemon\n```\n\n### Importing the module and usage\n\n```javascript\nimport { create } from 'kubo-rpc-client'\n\n// connect to ipfs daemon API server\nconst ipfs = create('http://localhost:5001') // (the default in Node.js)\n\n// or connect with multiaddr\nconst ipfs = create('/ip4/127.0.0.1/tcp/5001')\n\n// or using options\nconst ipfs = create({ host: 'localhost', port: '5001', protocol: 'http' })\n\n// or specifying a specific API path\nconst ipfs = create({ host: '1.1.1.1', port: '80', apiPath: '/ipfs/api/v0' })\n```\n\n### In a web browser\n\n**through Browserify**\n\nSame as in Node.js, you just have to [browserify](http://browserify.org) the code before serving it. See the browserify repo for how to do that.\n\nSee the example in the [examples folder](https://github.com/ipfs-examples/js-ipfs-examples/tree/master/examples) to get a boilerplate.\n\n**through webpack**\n\nSee the example in the [examples folder](https://github.com/ipfs-examples/js-ipfs-examples/tree/master/examples/http-client-bundle-webpack) to get an idea on how to use `kubo-rpc-client` with webpack.\n\n**from CDN**\n\nInstead of a local installation (and browserification) you may request a remote copy of IPFS API from [jsDelivr](https://www.jsdelivr.com/package/npm/ipfs).\n\nTo always request the latest version, use one of the following examples:\n\n```html\n\u003c!-- loading the minified version using jsDelivr --\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/kubo-rpc-client/dist/index.min.js\"\u003e\u003c/script\u003e\n```\n\nFor maximum security you may also decide to:\n\n- reference a specific version of IPFS API (to prevent unexpected breaking changes when a newer latest version is published)\n- [generate a SRI hash](https://www.srihash.org/) of that version and use it to ensure integrity. Learn more also at the [jsdelivr website](https://www.jsdelivr.com/using-sri-with-dynamic-files)\n- set the [CORS settings attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes) to make anonymous requests to CDN\n\nExample:\n\n```html\n\u003cscript\n  src=\"https://www.jsdelivr.com/package/npm/kubo-rpc-client\"\n  integrity=\"sha384-5bXRcW9kyxxnSMbOoHzraqa7Z0PQWIao+cgeg327zit1hz5LZCEbIMx/LWKPReuB\"\n  crossorigin=\"anonymous\"\n\u003e\u003c/script\u003e\n```\n\nCDN-based IPFS API provides the `KuboRpcClient` object of the global `window` object. Example:\n\n```js\nconst ipfs = window.KuboRpcClient.create({ host: 'localhost', port: 5001 })\n```\n\nIf you omit the host and port, the client will parse `window.host`, and use this information. This also works, and can be useful if you want to write apps that can be run from multiple different gateways:\n\n```js\nconst ipfs = window.KuboRpcClient.create()\n```\n\n### Custom Headers\n\nIf you wish to send custom headers with each request made by this library, for example, the `Authorization` header. This can be useful if your Kubo node has keys defined in [`API.Authorizations`](https://github.com/ipfs/kubo/blob/master/docs/config.md#apiauthorizations).\n\nIf you're using `bearer:token`, where `token` is `abc123`:\n\n```js\nconst ipfs = create({\n  host: 'localhost',\n  port: 5001,\n  protocol: 'http',\n  headers: {\n    authorization: 'Bearer abc123'\n  }\n})\n```\n\nIf you're using `basic:user:password`, where `user:password` is `alice:secret`:\n\n```js\nconst ipfs = create({\n  host: 'localhost',\n  port: 5001,\n  protocol: 'http',\n  headers: {\n    // For Node.js, using:\n    //    Buffer.from('alice:secret').toString('base64')\n    // is preferred over using `btoa`.\n    authorization: 'Basic ' + btoa('alice:secret')\n  }\n})\n```\n\n### Global Timeouts\n\nTo set a global timeout for *all* requests pass a value for the `timeout` option:\n\n```js\n// Timeout after 10 seconds\nconst ipfs = create({ timeout: 10000 })\n// Timeout after 2 minutes\nconst ipfs = create({ timeout: '2m' })\n// see https://www.npmjs.com/package/parse-duration for valid string values\n```\n\n## Development\n\n### Testing\n\nWe run tests by executing `npm test` in a terminal window. This will run both Node.js and Browser tests, both in Chrome and PhantomJS. To ensure that the module conforms with the [`interface-ipfs-core`](https://github.com/ipfs/js-ipfs/tree/master/packages/interface-ipfs-core) spec, we run the batch of tests provided by the interface module, which can be found [here](https://github.com/ipfs/js-ipfs/tree/master/packages/interface-ipfs-core/src).\n\n## Historical context\n\nThis module started as a direct mapping from the go-ipfs cli to a JavaScript implementation, although this was useful and familiar to a lot of developers that were coming to IPFS for the first time, it also created some confusion on how to operate the core of IPFS and have access to the full capacity of the protocol. After much consideration, we decided to create `interface-ipfs-core` with the goal of standardizing the interface of a core implementation of IPFS, and keep the utility functions the IPFS community learned to use and love, such as reading files from disk and storing them directly to IPFS.\n\n## License\n\nLicensed under either of\n\n- Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / \u003chttp://www.apache.org/licenses/LICENSE-2.0\u003e)\n- MIT ([LICENSE-MIT](LICENSE-MIT) / \u003chttp://opensource.org/licenses/MIT\u003e)\n\n## Contribute\n\nContributions welcome! Please check out [the issues](https://github.com/ipfs/js-kubo-rpc-client/issues).\n\nAlso see our [contributing document](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md) for more information on how we work, and about contributing in general.\n\nPlease be aware that all interactions related to this repo are subject to the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).\n\nUnless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.\n\n[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs%2Fjs-kubo-rpc-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fipfs%2Fjs-kubo-rpc-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs%2Fjs-kubo-rpc-client/lists"}