API for interacting with Dat Profile Sites.
MIT License
A "Profile Site" is a dat-site which
Profile Sites are used to identify users and create social feeds.
var DatProfileSite = require('dat-profile-site')
// create a profile-site instance
// =
var bob = new DatProfileSite(bobsUrl)
// profile data
// =
await bob.getProfile() // => {name:, description:, image:}
await bob.setProfile({name:, description:, image:})
// social relationships
// =
await bob.follow(alicesUrl)
await bob.unfollow(alicesUrl)
await bob.listFollowing() // => [{url:, name:, description:, image:, downloaded:}, ...]
await bob.listKnownFollowers() // => [{url:, name:, description:, image:}, ...]
await bob.listFriends() => [{url:, name:, description:, image:}, ...]
await bob.isFollowing(alicesUrl) // => true
await bob.isFriendsWith(alicesUrl) // => true
// posting to the feed
// =
await bob.broadcast({
text: 'Hello, world!'
})
await bob.broadcast({
text: 'Check out my cat!',
image: '/fluffy.png'
})
await bob.broadcast({
text: 'Check out my cats!',
image: ['/fluffy.png', '/jojo.png']
})
// reading the feed
// =
// bob's broadcasts
await bob.listBroadcasts({
// time slice: between 1-2 hours ago
after: (Date.now() - 1000 * 60 * 60 * 2),
before: (Date.now() - 1000 * 60 * 60 * 1)
limit: 100, // max num of posts
metaOnly: false, // dont read files, just list entries
type: 'comment' // filter by broadcast type
})
// bob + followed's broadcasts
await bob.listFeed({
// same opts as .listBroadcasts()
})
// events
// =
var events = bob.createActivityStream()
events.addEventListener('new-broadcast', ({author, path, ctime, rtime}) => ...)
events.addEventListener('profile-downloaded', ({profile}) => ...)
Get the profile information.
await profile.getProfile() /* => {
name: String?,
description: String?,
image: String?
} */
Update the profile information. If an attribute is left undefined, no change to the attr is made.
profile.setProfile({
name: String?,
description: String?,
image: String?
})
Add a user to this profile's follows.
Remove a user from this profile's follows.
List of users followed by this profile.
await profile.listFollowing({
timeout: Number, amount of ms to wait until giving up on a profile-download (default 5000)
}) /* => [
DatProfileSite {
url: String
profile: {
name: String?, the user name (not globally unique)
description: String?, a short bio
image: String?, path of the profile image
downloaded: Boolean, has the profile been downloaded?
}
}
...
] */
List of users following this profile.
Note: It's not possible to list all users following this profile, because the network is decentralized and does not provide global knowledge. This method (currently) is equivalent to listFriends
but may in the future include more users.
await profile.listKnownFollowers() /* => [
DatProfileSite {
url: String
profile: {
name: String?
description: String?
image: String?
}
}
...
] */
List of users following this profile, which are also followed by this profile.
await profile.listFriends() /* => [
DatProfileSite {
url: String
profile: {
name: String?
description: String?
image: String?
}
}
...
] */
Is the profile following the given URL?
await profile.isFollowing(String) // => Boolean
Is the profile following the given URL, and followed by the given URL?
await profile.isFriendsWith(String) // => Boolean
Post a new broadcast.
await profile.broadcast({
text: String?, the text of the broadcast
image: [String] | String | undefined, a URL or URLs
video: [String] | String | undefined, a URL or URLs
audio: [String] | String | undefined, a URL or URLs
})
List broadcasts authored by the profile.
await profile.listBroadcasts({
after: Date | Number | undefined, a date or epoch number
before: Date | Number | undefined, a date or epoch number
limit: Number?, the max number of posts to return. Default 20.
reverse: Boolean?, if true will provide oldest first
metaOnly: Boolean?, provide file-entry descriptors instead of reading content
type: String?, a filter on the type of broadcast. Does not work with 'metaOnly==true'.
timeout: Number?, the timeout for each operation. Default 5000. (Note: There are multiple operations.)
}) => /* [
{
author: DatProfileSite, the broadcast author
authorProfile: Object, the profile of the author (same content as getProfile())
name: String, the file path
ctime: Number, creation time
mtime: Number, modification time
content: {
"@type": String, the broadcast type (eg 'Comment')
text: String, the text of the broadcast
image: [String] | String | undefined, a URL or URLs
video: [String] | String | undefined, a URL or URLs
audio: [String] | String | undefined, a URL or URLs
}
}
] */
List broadcasts authored by the profile and its followed profiles.
await profile.listFeed({
after: Date | Number | undefined, a date or epoch number
before: Date | Number | undefined, a date or epoch number
limit: Number?, the max number of posts to return. Default 20.
reverse: Boolean?, if true will provide oldest first
metaOnly: Boolean?, provide file-entry descriptors instead of reading content
type: String?, a filter on the type of broadcast. Does not work with 'metaOnly==true'.
timeout: Number?, the timeout for each operation. Default 5000. (Note: There are multiple operations.)
}) => /* [
{
author: DatProfileSite, the broadcast author
authorProfile: Object, the profile of the author (same content as getProfile())
name: String, the file path
ctime: Number, creation time
mtime: Number, modification time
content: {
"@type": String, the broadcast type (eg 'Comment')
text: String, the text of the broadcast
image: [String] | String | undefined, a URL or URLs
video: [String] | String | undefined, a URL or URLs
audio: [String] | String | undefined, a URL or URLs
}
}
] */
Read the given broadcast object. Will throw with InvalidBroadcastFileError
if the file does not conform to the format or schema.
await profile.getBroadcast(String) /* => {
name: String, the file path
ctime: Number, creation time
mtime: Number, modification time
content {
'@context': 'http://schema.org',
'@type': 'Comment',
text: String?, the text of the broadcast
image: [String] | String | undefined, a URL or URLs
video: [String] | String | undefined, a URL or URLs
audio: [String] | String | undefined, a URL or URLs
}
}*/
Emitted when a new broadcast has been received from the profile or one of the followed profiles. Will not be emitted for broadcasts which were not created in the past 24 hours.
events.addEventListener('new-broadcast', event => {
/*
event.author: String, the url of the author
event.path: String, the path of the new broadcast
event.ctime: Number, the timestamp of the creation of the broadcast
event.rtime: Number, the timestamp of the when the broadcast was received
*/
})
Emitted when an undownloaded profile is first discovered on the network and downloaded.
events.addEventListener('profile-downloaded', event => {
/*
event.profile: String, the url of the profile
*/
})
This page specifies the required file paths, formats, and schemas to conform to the Profile Site Protocol. Conformance allows feed applications to consume the target site and render their content correctly.
./image.png
are not supported.The profile data of the site provides a name, short biography, and image.
/profile.json
Format | Spec |
---|---|
json-ld | http://json-ld.org/ |
Type | Spec | Implemented Attributes |
---|---|---|
person | https://schema.org/Person | name, image, description, follows |
// /profile.json
{
"@context": "http://schema.org",
"@type": "Person",
"name": "Alice Roberts",
"image": "/profile.jpg",
"description": "Finally trying out this 'Dat' thing!",
"follows": [
{"url": "dat://.../"},
{"url": "dat://.../"},
{"url": "dat://.../"}
]
}
"Broadcasts" are content which should be visible to all audiences, and requires no context to be displayed. Broadcasts are conceptually similar to tweets.
A site may have many broadcasts.
Files that match this pattern will be placed in the broadcast feed. Any other files will be ignored; related files (such as images or videos) can be placed in the broadcasts folder.
/broadcasts/{timestamp}.json
The timestamp
is a Unix epoch number.
Example path for "A comment posted at Sat Mar 25 2017 16:51:18."
/broadcasts/1490478678636.json
Format | Spec |
---|---|
json-ld | http://json-ld.org/ |
Type | Spec | Implemented Attributes |
---|---|---|
comment | https://schema.org/Comment | text, image, video, audio |
// /broadcasts/1490478678636.json
{
"@context": "http://schema.org",
"@type": "Comment",
"text": "Hello, world!"
}
// /broadcasts/1490478678637.json
{
"@context": "http://schema.org",
"@type": "Comment",
"text": "Check out my awesome cat!",
"image": "/pics/cat.jpeg"
}