Documentation / /
Web APIs

Library API

Beaker’s Library API is an experimental API for managing the user’s collection of Dat archives. Learn more about Beaker’s Library

To use this API, include the following in your dat.json manifest file:

{
  "experimental": {
    "apis": ["library"]
  }
}

Permissions

The user must grant permission for your app to use this API.

If you only wish to add and remove items to/from the Library, consider using requestAdd() and requestRemove() so that the user can review each addition and removal individually.

Methods

experimental.library.add(url, opts?)

Add an archive to the user’s Library.

  • url String. The URL of the archive to add to the Library.
  • opts.duration Number. How long the archive should stay in the Library, in minutes. Useful for “temporary seeding.”
  • returns Promise<UserSettings>

Example:

var userSettings = await experimental.library.add(datUrl)
userSettings.isSaved // true
userSettings.expiresAt // a timestamp or undefined

experimental.library.remove(url)

Remove an archive from the user’s Library.

  • url String. The URL of the archive to remove.
  • returns Promise<UserSettings>

Example:

var userSettings = await experimental.library.remove(datUrl)
userSettings.isSaved // false
userSettings.expiresAt // a timestamp or undefined

experimental.library.requestAdd(url, opts?)

Request to add an archive to the user’s Library. Will prompt the user for confirmation.

  • url String. The URL of the archive to add to the Library.
  • opts.duration Number. How long the archive should stay in the Library, in minutes. Useful for “temporary seeding.”
  • returns Promise<UserSettings>

Example:

var userSettings = await experimental.library.requestAdd(datUrl)
userSettings.isSaved // true
userSettings.expiresAt // a timestamp or undefined

experimental.library.requestRemove(url)

Request to remove an archive from the user’s Library. Will prompt the user for confirmation.

  • url String. The URL of the archive to remove.
  • returns Promise<UserSettings>

Example:

var userSettings = await experimental.library.requestRemove(datUrl)
userSettings.isSaved // false
userSettings.expiresAt // a timestamp or undefined

experimental.library.get(url)

Get the settings for the given archive.

  • url String. The URL of the archive.
  • returns Promise<UserSettings>

Example:

var userSettings = await experimental.library.get(datUrl)
userSettings.isSaved // true/false
userSettings.expiresAt // a timestamp or undefined

experimental.library.list(query?)

List the archives saved to the user’s Library.

  • query.inMemory Boolean. Filter by whether the archives are loaded.
  • query.isSaved Boolean. Filter by whether the archives are saved or just in the cache.
  • query.isNetworked Boolean. Filter by whether the archives are being swarmed on the network.
  • query.isOwner Boolean. Filter by whether the archive is owned by the user.
  • returns Promise<Array<ArchiveInfo>>

Example:

var archives = await experimental.library.list({isSaved: true})

Each object returned in the array will have the following properties:

{
  url: string
  title: string
  description: string
  size: number
  mtime: number
  isOwner: boolean
  userSettings: {
    isSaved: boolean
    expiresAt: number
  }
  peers: number
}

Events

Event: "added"

An archive has been added to the Library.

  • event.url String. The URL of the archive added.

Example:

experimental.library.addEventListener('added', ({url}) => {
  console.log(url, 'was added to the Library')
})

Event: "removed"

An archive has been removed from the Library.

  • event.url String. The URL of the archive removed.

Example:

experimental.library.addEventListener('removed', ({url}) => {
  console.log(url, 'was removed from the Library')
})

Event: "updated"

An archive has recently had its metadata updated.

  • event.url String. The URL of the archive updated.
  • event.title String. The archive title.
  • event.description String. The archive description.
  • event.size Number. The archive size, in bytes.
  • event.mtime Number. The timestamp of the most recent modification.
  • event.isOwner Boolean. Does the user own the archive?

Example:

experimental.library.addEventListener('updated', ({url}) => {
  console.log(url, 'was recently updated')
})

Event: "network-changed"

An archive has recently had its network conditions change.

  • event.url String. The URL of the archive updated.
  • event.connections Number. The number of active connections.

Example:

experimental.library.addEventListener('updated', ({url, connections}) => {
  console.log(url, 'has', connections, 'current peers')
})