@textile/hub > Buckets

Buckets class

Buckets a client wrapper for interacting with the Textile Buckets API.

Signature:

export declare class Buckets extends GrpcAuthentication

Extends: GrpcAuthentication

Example 1

Initialize the Bucket API and open an existing bucket (or create if new).

import { Buckets, UserAuth } from '@textile/hub'

const getOrCreate = async (auth: UserAuth, bucketName: string) => {
  const buckets = Buckets.withUserAuth(auth)
  // Automatically scopes future calls on `buckets` to the Thread containing the bucket
  const { root, threadID } = await buckets.getOrCreate(bucketName)
  if (!root) throw new Error('bucket not created')
  const bucketKey = root.key
  return { buckets, bucketKey }
}

Example 2

Print the links for the bucket

import { Buckets } from '@textile/hub'

// This method requires that you run "getOrCreate" or have specified "withThread"
async function logLinks (buckets: Buckets, bucketKey: string) {
  const links = await buckets.links(bucketKey)
  console.log(links)
}

Example 3

Find an existing Bucket

import { Buckets } from '@textile/hub'

// This method requires that you already specify the Thread containing
// the bucket with buckets.withThread(<thread name>).
const exists = async (buckets: Buckets, bucketName: string) => {
    const roots = await buckets.list();
    return roots.find((bucket) => bucket.name === bucketName)
}

Example 4

Push an folder in node.js

import fs from 'fs'
import util from 'util'
import glob from 'glob'
import { Buckets } from '@textile/hub'

const globDir = util.promisify(glob)

// expects an already setup buckets session using getOrCreate or withThread
const exists = async (buckets: Buckets, bucketKey: string, dir: string) => {
  const files = await globDir('<dir glob options>')
  return await Promise.all(files.map(async (file) => {
    const filePath = dir + '/' + file
    var content = fs.createReadStream(filePath, { highWaterMark: 1024 * 1024 * 3 });
    const upload = {
      path: file,
      content
    }
    return await buckets.pushPath(bucketKey, file, upload)
  }))
}

Methods

MethodModifiersDescription
archive(key, options, skipAutomaticVerifiedDeal)(BETA) (Experimental) Store a snapshot of the bucket on Filecoin.
archives(key)(BETA) archives returns the curent and historical archives for a Bucket.
archiveWatch(key, callback)(BETA) archiveWatch watches status events from a Filecoin bucket archive.
copyAuth(auth, options)staticCopies the full scope and authentication from one API instance to this one. This will copy any existing authentication and authorization info, including:- Information created withKeyInfo and withUserAuth.- Any token generated from getToken or getTokenChallenge.- If you scoped the instance to a specific thread using withThread
create(name, options)Creates a new bucket.
defaultArchiveConfig(key)(BETA) (Experimental) Get the current default ArchiveConfig for the specified Bucket.
existing(threadID)Existing lists all remote buckets in the thread or in all threads.
getOrCreate(name, options)Open a new / existing bucket by bucket name and ThreadID (create not required) Replaces open command in older versions.
getOrInit(name, threadName, encrypted, threadID)(Deprecated) Open a new / existing bucket by bucket name and ThreadID (create not required)
getToken(identity)Obtain a token for interacting with the remote API. When your app is creating new private-key based users to interact with the API using User Group keys, you must first create a new token for each new user. Tokens do not change after you create them.
getTokenChallenge(publicKey, callback)Obtain a token for interacting with the remote API. When your app is creating new private-key based users to interact with the API using User Group keys, you must first create a new token for each new user. Tokens do not change after you create them. This callback method will require you to handle challenge signing.
init(name, encrypted)(Deprecated) Creates a new bucket.
links(key, path)Returns a list of bucket links.
list()Returns a list of all bucket roots.
listIpfsPath(path)listIpfsPath returns items at a particular path in a UnixFS path living in the IPFS network.
listPath(key, path, depth)Returns information about a bucket path.
listPathFlat(key, path, dirs, depth)listPathRecursive returns a nested object of all paths (and info) in a bucket
movePath(key, fromPath, toPath)Move a file or subpath to a new path.
open(name, threadName, encrypted, threadID)(Deprecated) Open a new / existing bucket by bucket name and ThreadID (create not required)
pullIpfsPath(path, options)pullIpfsPath pulls the path from a remote UnixFS dag, writing it to writer if it's a file.
pullPath(key, path, options)Pulls the bucket path, returning the bytes of the given file.
pullPathAccessRoles(key, path)List the access roles per path in a Bucket
pushPath(key, path, input, options)Pushes a file to a bucket path.
pushPathAccessRoles(key, path, roles)Push new access roles per path in a Bucket
pushPaths(key, input, options)Pushes an iterable of files to a bucket.
remove(key)Removes an entire bucket. Files and directories will be unpinned (cannot be undone).
removePath(key, path, options)Returns information about a bucket path (cannot be undone).
root(key)Returns the bucket root CID
setDefaultArchiveConfig(key, config)(BETA) (Experimental) Set the default ArchiveConfig for the specified Bucket.
setPath(key, path, cid)Pushes a file to a bucket path.
setToken(token)Obtain a token for interacting with the remote API. When your app is creating new private-key based users to interact with the API using User Group keys, you must first create a new token for each new user. Tokens do not change after you create them.
withKeyInfo(key, options)staticCreates a new API client instance for accessing the gRPC API using key & secret based authentication. This method is recommended for admin or insecure implementations where the non-signing keys or key with secret can be embedded directly in an app.
withThread(threadID)Scope future API calls to a specific thread. For both Buckets and Threads, many API calls require knowledge about which thread you are making requests against. Use withThread to declare your target thread before making those API calls.
withUserAuth(auth, options)staticCreates a new API client instance for accessing the gRPC API using User Group key authentication. This method is recommended for public apps where API secrets need to remain hidden from end users.
← Users classClient class →