ipfs
0.32.0

- Intro
- get
- put
- findprovs
- findpeer
- provide
- query
- publish
- resolve
- pin.proto
- version
- parseIpfsPath
- normalizePath
- resolvePath
- parseChunkerString
- parseRabinString

# Intro

Installable via `npm install --save ipfs`, it can also be used directly in the browser.

## Download

The source is available for download from GitHub. Alternatively, you can install using npm:

    $ npm install --save ipfs

You can then `require()` ipfs as normal:

    const ipfs = require('ipfs')

## In the Browser

Ipfs should work in any ES2015 environment out of the box.

Usage:

    <script type="text/javascript" src="index.js"></script>

The portable versions of ipfs, including `index.js` and `index.min.js`, are included in the `/dist` folder. Ipfs can also be found on unkpkg.com under

- https://unpkg.com/ipfs/dist/index.min.js
- https://unpkg.com/ipfs/dist/index.js

# get

Given a key, query the DHT for its best value.

#### Parameters

1. `key: Buffer`:
2. `callback: function (Error)?`:

#### Returns

`(Promise | void)`

# put

Write a key/value pair to the DHT.

Given a key of the form /foo/bar and a value of any form, this will write that value to the DHT with that key.

#### Parameters

1. `key: Buffer`:
2. `value: Buffer`:
3. `callback: function (Error)?`:

#### Returns

`(Promise | void)`

# findprovs

Find peers in the DHT that can provide a specific value, given a key.

#### Parameters

1. `key: CID`:
   They key to find providers for.
2. `callback: function (Error, Array<PeerInfo>)?`:

#### Returns

`(Promise<PeerInfo> | void)`

# findpeer

Query the DHT for all multiaddresses associated with a `PeerId`.

#### Parameters

1. `peer: PeerId`:
   The id of the peer to search for.
2. `callback: function (Error, Array<Multiaddr>)?`:

#### Returns

`(Promise<Array<Multiaddr>> | void)`

# provide

Announce to the network that we are providing given values.

#### Parameters

1. `keys: (CID | Array<CID>)`:
   The keys that should be announced.
2. `options: Object (={})`:
3. `options.recursive: bool (=false)`:
   Provide not only the given object but also all objects linked from it.
4. `callback: function (Error)?`:

#### Returns

`(Promise | void)`

# query

Find the closest peers to a given `PeerId`, by querying the DHT.

#### Parameters

1. `peer: PeerId`:
   The `PeerId` to run the query agains.
2. `callback: function (Error, Array<PeerId>)?`:

#### Returns

`(Promise<Array<PeerId>> | void)`

# publish

IPNS is a PKI namespace, where names are the hashes of public keys, and the private key enables publishing new (signed) values. In both publish and resolve, the default name used is the node's own PeerID, which is the hash of its public key.

#### Parameters

1. `value: String`:
   ipfs path of the object to be published.
2. `options: Object`:
   ipfs publish options.
3. `options.resolve: boolean`:
   resolve given path before publishing.
4. `options.lifetime: String`:
   time duration that the record will be valid for. This accepts durations such as "300s", "1.5h" or "2h45m". Valid time units are "ns", "ms", "s", "m", "h". Default is 24h.
5. `options.ttl: String`:
   time duration this record should be cached for (NOT IMPLEMENTED YET). This accepts durations such as "300s", "1.5h" or "2h45m". Valid time units are "ns", "ms", "s", "m", "h" (caution: experimental).
6. `options.key: String`:
   name of the key to be used or a valid PeerID, as listed by 'ipfs key list -l'.
7. `callback: function (Error)?`:

#### Returns

`(Promise | void)`

# resolve

Given a key, query the DHT for its best value.

#### Parameters

1. `name: String`:
   ipns name to resolve. Defaults to your node's peerID.
2. `options: Object`:
   ipfs resolve options.
3. `options.nocache: boolean`:
   do not use cached entries.
4. `options.recursive: boolean`:
   resolve until the result is not an IPNS name.
5. `callback: function (Error)?`:

#### Returns

`(Promise | void)`

# pin.proto

Protobuf interface from go-ipfs/pin/internal/pb/header.proto

# version

If the repo has been initialized, report the current version. Otherwise report the version that would be initialized.

#### Parameters

1. `callback: function (Error, Number)?`:

#### Returns

`undefined`

# parseIpfsPath

Break an ipfs-path down into it's hash and an array of links.

examples: b58Hash -> { hash: 'b58Hash', links: [] } b58Hash/mercury/venus -> { hash: 'b58Hash', links: ['mercury', 'venus']} /ipfs/b58Hash/links/by/name -> { hash: 'b58Hash', links: ['links', 'by', 'name'] }

#### Parameters

1. `ipfsPath: String`:
   An ipfs-path

#### Returns

`Object` { hash: base58 string, links: [string] , ?err: Error }

#### Throws

`any` on an invalid @param ipfsPath

# normalizePath

Returns a well-formed ipfs Path. The returned path will always be prefixed with /ipfs/ or /ipns/. If the received string is not a valid ipfs path, an error will be returned examples: b58Hash -> { hash: 'b58Hash', links: [] } b58Hash/mercury/venus -> { hash: 'b58Hash', links: ['mercury', 'venus']} /ipfs/b58Hash/links/by/name -> { hash: 'b58Hash', links: ['links', 'by', 'name'] }

#### Parameters

1. `pathStr: String`:
   An ipfs-path, or ipns-path or a cid

#### Returns

`String` ipfs-path or ipns-path

#### Throws

`any` on an invalid @param ipfsPath

# resolvePath

Resolve various styles of an ipfs-path to the hash of the target node. Follows links in the path.

Accepts formats:

- <base58 string>
- <base58 string>/link/to/venus
- /ipfs/<base58 string>/link/to/pluto
- multihash Buffer
- Arrays of the above

#### Parameters

1. `objectAPI: IPFS`:
   The IPFS object api
2. `callback: Function<err, res>`:
   res is Array<Buffer(hash)> if no callback is passed, returns a Promise

#### Returns

`(Promise | void)`

# parseChunkerString

Parses chunker string into options used by DAGBuilder in ipfs-unixfs-engine

#### Parameters

1. `chunker: String`:
   Chunker algorithm supported formats: "size-{size}" "rabin" "rabin-{avg}" "rabin-{min}-{avg}-{max}"

#### Returns

`Object` Chunker options for DAGBuilder

# parseRabinString

Parses rabin chunker string

#### Parameters

1. `chunker: String`:
   Chunker algorithm supported formats: "rabin" "rabin-{avg}" "rabin-{min}-{avg}-{max}"

#### Returns

`Object` rabin chunker options