dPack Pinning API

@dpack/pin

Client API for dPack pinning services. Conforms to the DPack Pinning API.

API

To create a client:

const {createClient} = require('@dpack/pin')
createClient('https://my-dpack-pinning-service.com', {username: 'jared', password: 'rice'}, (err, client) => {
  if (err) throw err
  // ...
})

Alternatively:

const {DPackPinningServiceClient} = require('@dpack/pin')
var client = new DPackPinningServiceClient('https://my-dpack-pinning-service.com')
client.fetchPSADoc(err => {
  if (err) throw err
  client.login('jared', 'rice', err => {
    if (err) throw err
    // ...
  })
})

All of the methods provide the response body and give an error if a non-2xx response is received. The errors will have the .statusCode and .responseBody set.

createClient(hostUrl[, login], cb)

Create a new client object. Will fetch the PSA document and run login if the creds are specified.

new DPackPinningServiceClient(hostUrl[, psaDoc])

Create a new client object. You can optionally provide the PSA document, which is useful if you've cached it from a previous session.

client.setPSADoc(psaDoc)

Manually set the PSA document (useful if you've cached it from a previous session). You can find the PSA doc on client.psaDoc.

client.setSession(token)

Manually set the session token (useful if you've cached it from a previous session). You can find the token on client.sessionToken.

client.login(username, password, cb)

Start a session. You can check client.hasSession to see if a session token has been stored.

client.logout(cb)

End the session.

client.getAccount(cb)

Get the account info for the current session. Returns

{
  email: String, the accounts email (required)
  username: String, the accounts username (required)
  diskUsage: Number, how much disk space has the user's data taken? (optional)
  diskQuota: Number, how much disk space can the user's data take? (optional)
  updatedAt: Number, the Unix timestamp of the last time the user account was updated (optional)
  createdAt: Number, the Unix timestamp of the last time the user account was updated (optional)
}

client.listDPacks(cb)

Get the dPacks pinned by the user. Returns

{
  items: [{
    url: String, dWeb url
    name: String, optional shortname assigned by the user
    title: String, optional title extracted from the dPack's manifest file
    description: String, optional description extracted from the dPack's manifest file
    additionalUrls: Array of Strings, optional list of URLs the dPack can be accessed at
  }]
}

client.addDPack({url, name, domains}, cb)

Pin a dPack. Params:

• url String, required url/key of the dPack
• name String, optional shortname for the vault
• domains Array of Strings, optional list of domain-names the dPack should be made available at

client.removeDPack(url, cb)

Unpin a dPack. Params:

• url String, required url/key of the dPack

client.getDPacks(url, cb)

Get a pinned dPack. Returns:

{
  url: String, dWeb url
  name: String, optional shortname assigned by the user
  title: String, optional title extracted from the dPack's manifest file
  description: String, optional description extracted from the dPack's manifest file
  additionalUrls: Array of Strings, optional list of URLs the dPack can be accessed at
}

client.updateDPack(url, {name, domains}, cb)

Update a pinned dPack. Params:

• url String, required url/key of the dPack
• name String, optional shortname for the vault
• domains Array of Strings, optional list of domain-names the dPack should be made available at

CLI tool

Small utility for testing endpoints:

npm i -g @dpack/pin@latest
dpack-pin https://my-dpack-pinning-service.com jared rice getDPacks 9900f9aad4d6e79e0beb1c46333852b99829e4dfcdfa9b690eeeab3c367c1b9a

The usage is:

dpack-pin [service] [username] [password] [action] [args...]