Navel Piercing Madness

    web3.storage
    TypeScript icon, indicating that this package has built-in type declarations

    4.2.0 • Public • Published


    web3.storage

    The JavaScript API client for https://web3.storage

    Getting started

    Install the package using npm

    npm install web3.storage

    Usage

    The code below shows how you create a new web3.storage api client, and use it to put your files to web3, and get them back again.

    Sign in to https://web3.storage, create an API token, and use it in place of API_TOKEN when creating your instance of the client.

    import { Web3Storage } from 'web3.storage'
    
    // Construct with token and endpoint
    const client = new Web3Storage({ token: API_TOKEN })
    
    const fileInput = document.querySelector('input[type="file"]')
    
    // Pack files into a CAR and send to web3.storage
    const rootCid = await client.put(fileInput.files) // Promise<CIDString>
    
    // Get info on the Filecoin deals that the CID is stored in
    const info = await client.status(rootCid) // Promise<Status | undefined>
    
    // Fetch and verify files from web3.storage
    const res = await client.get(rootCid) // Promise<Web3Response | null>
    const files = await res.files() // Promise<Web3File[]>
    for (const file of files) {
      console.log(`${file.cid} ${file.name} ${file.size}`)
    }

    Mutability

    ❗️Experimental this API may not work, may change, and may be removed in a future version.

    Mutability in Web3.Storage is maintained through IPNS records.

    ⚠️ Name records are not yet published to or updated from the IPFS network. Working with name records simply updates the Web3.Storage cache of data.

    Create and Publish

    import { Web3Storage } from 'web3.storage'
    import * as Name from 'web3.storage/name'
    
    const client = new Web3Storage({ token: API_TOKEN })
    const name = await Name.create()
    
    console.log('Name:', name.toString())
    // e.g. k51qzi5uqu5di9agapykyjh3tqrf7i14a7fjq46oo0f6dxiimj62knq13059lt
    
    // The value to publish
    const value = '/ipfs/bafkreiem4twkqzsq2aj4shbycd4yvoj2cx72vezicletlhi7dijjciqpui'
    const revision = await Name.v0(name, value)
    
    await Name.publish(client, revision, name.key)

    ⚠️ Note: revisions live for 1 year after creation by default.

    Resolve

    import { Web3Storage } from 'web3.storage'
    import * as Name from 'web3.storage/name'
    
    const client = new Web3Storage({ token: API_TOKEN })
    const name = Name.parse('k51qzi5uqu5di9agapykyjh3tqrf7i14a7fjq46oo0f6dxiimj62knq13059lt')
    
    const revision = await Name.resolve(client, name)
    
    console.log('Resolved value:', revision.value)
    // e.g. /ipfs/bafkreiem4twkqzsq2aj4shbycd4yvoj2cx72vezicletlhi7dijjciqpui

    Update

    Updating records involves creating a new revision from the previous one.

    import { Web3Storage } from 'web3.storage'
    import * as Name from 'web3.storage/name'
    
    const client = new Web3Storage({ token: API_TOKEN })
    const name = await Name.create()
    
    const value = '/ipfs/bafkreiem4twkqzsq2aj4shbycd4yvoj2cx72vezicletlhi7dijjciqpui'
    const revision = await Name.v0(name, value)
    
    await Name.publish(client, revision, name.key)
    
    // ...later
    
    const nextValue = '/ipfs/bafybeiauyddeo2axgargy56kwxirquxaxso3nobtjtjvoqu552oqciudrm'
    // Make a revision to the current record (increments sequence number and sets value)
    const nextRevision = await Name.increment(revision, nextValue)
    
    await Name.publish(client, nextRevision, name.key)

    Signing Key Management

    The private key used to sign IPNS records should be saved if a revision needs to be created in the future.

    import * as Name from 'web3.storage/name'
    import fs from 'fs'
    
    // Creates a new "writable" name with a new signing key
    const name = await Name.create()
    
    // Store the signing key to a file for use later
    await fs.promises.writeFile('priv.key', name.key.bytes)
    
    // ...later
    
    const bytes = await fs.promises.readFile('priv.key')
    const name = await Name.from(bytes)
    
    console.log('Name:', name.toString())
    // e.g. k51qzi5uqu5di9agapykyjh3tqrf7i14a7fjq46oo0f6dxiimj62knq13059lt

    Revision Serialization/Deserialization

    The current revision for a name may need to be serialized to be stored on disk or transmitted and then deserialized later. Note that revisions are not IPNS records - they carry similar data, but are not signed.

    import * as Name from 'web3.storage/name'
    import fs from 'fs'
    
    const { Revision } = Name
    const name = await Name.create()
    const value = '/ipfs/bafkreiem4twkqzsq2aj4shbycd4yvoj2cx72vezicletlhi7dijjciqpui'
    const revision = await Name.v0(name, value)
    
    // Store the record to a file for use later
    // Note: Revision.encode does NOT encode signing key data
    await fs.promises.writeFile('ipns.revision', Revision.encode(rev))
    
    // ...later
    
    const bytes = await fs.promises.readFile('ipns.revision')
    const revision = Revision.decode(bytes)

    Testing

    Run npm test to test the ESM code, CJS, and in the browser via playwright-test. 100% test coverage is required by the hundreds module.

    To test in individual environments, you'll need two terminal windows open. In the first, start up the mock API by running npm run mock:api. In the second, you can then run npm run test:web, npm run test:esm or npm run test:cjs.

    Tests are written in mocha and use a mock API server to assert functionality. When adding a new method to the client, add a test/<method>.spec.js test suite to go with it.

    The mock api is built with smoke file-based mock server. You add a files to the test/mocks/api directory, and the file name determines which API enpoint you are mocking. You can provide a .json for a static response, or a .js file to add some logic to the mock.

    • post_car.js handles POST /car requests.
    • get_car#@cid.js handes GET /car/:cid requests. The cid part of the path is provided to the mock as params.cid.

    Add more mocks as required.

    Keywords

    none

    Install

    npm i web3.storage

    DownloadsWeekly Downloads

    2,714

    Version

    4.2.0

    License

    (Apache-2.0 OR MIT)

    Unpacked Size

    1.22 MB

    Total Files

    29

    Last publish

    Collaborators

    • olizilla
    • ipfsbot