ATP API
This API is a client for ATProtocol servers. It communicates using HTTP. It includes:
- ✔️ APIs for ATProto and Bluesky.
- ✔️ Validation and complete typescript types.
- ✔️ Session management.
- ✔️ A RichText library.
Getting started
First install the package:
yarn add @atproto/api
Then in your application:
import { BskyAgent } from '@atproto/api'
const agent = new BskyAgent({ service: 'https://example.com' })
Usage
Session management
Log into a server or create accounts using these APIs. You'll need an active session for most methods.
import { BskyAgent, AtpSessionEvent, AtpSessionData } from '@atproto/api'
const agent = new BskyAgent({
service: 'https://example.com',
persistSession: (evt: AtpSessionEvent, sess?: AtpSessionData) => {
}
})
await agent.login({identifier: 'alice@mail.com', password: 'hunter2'})
await agent.resumeSession(savedSessionData)
await agent.createAccount({
email: 'alice@mail.com',
password: 'hunter2',
handle: 'alice.example.com'
})
API calls
The agent includes methods for many common operations, including:
await agent.getTimeline(params, opts)
await agent.getAuthorFeed(params, opts)
await agent.getPostThread(params, opts)
await agent.getPost(params)
await agent.getPosts(params, opts)
await agent.getLikes(params, opts)
await agent.getRepostedBy(params, opts)
await agent.post(record)
await agent.deletePost(postUri)
await agent.like(uri, cid)
await agent.deleteLike(likeUri)
await agent.repost(uri, cid)
await agent.deleteRepost(repostUri)
await agent.uploadBlob(data, opts)
await agent.getFollows(params, opts)
await agent.getFollowers(params, opts)
await agent.follow(did)
await agent.deleteFollow(followUri)
await agent.getProfile(params, opts)
await agent.upsertProfile(updateFn)
await agent.getProfiles(params, opts)
await agent.getSuggestions(params, opts)
await agent.searchActors(params, opts)
await agent.searchActorsTypeahead(params, opts)
await agent.mute(did)
await agent.unmute(did)
await agent.listNotifications(params, opts)
await agent.countUnreadNotifications(params, opts)
await agent.updateSeenNotifications()
await agent.resolveHandle(params, opts)
await agent.updateHandle(params, opts)
await agent.createAccount(params)
await agent.login(params)
await agent.resumeSession(session)
Validation and types
The package includes a complete types system which includes validation and type-guards. For example, to validate a post record:
import { AppBskyFeedPost } from '@atproto/api'
const post = {...}
if (AppBskyFeedPost.isRecord(post)) {
const res = AppBskyFeedPost.validateRecord(post)
if (res.success) {
} else {
console.log(res.error)
}
}
Rich text
Some records (ie posts) use the app.bsky.richtext
lexicon. At the moment richtext is only used for links and mentions, but it will be extended over time to include bold, italic, and so on.
ℹ️ It is strongly recommended to use this package's RichText
library. Javascript encodes strings in utf16 while the protocol (and most other programming environments) use utf8. Converting between the two is challenging, but RichText
handles that for you.
import {RichText} from '@atproto/api'
const rt = new RichText({text: 'Hello @alice.com, check out this link: https://example.com'})
await rt.detectFacets(agent)
const postRecord = {
$type: 'app.bsky.feed.post',
text: rt.text,
facets: rt.facets,
createdAt: new Date().toISOString()
}
let markdown = ''
for (const segment of rt.segments()) {
if (segment.isLink()) {
markdown += `[${segment.text}](${segment.link?.uri})`
} else if (segment.isMention()) {
markdown += `[${segment.text}](https://my-bsky-app.com/user/${segment.mention?.did})`
} else {
markdown += segment.text
}
}
const rt2 = new RichText({text: 'Hello'})
console.log(rt2.length)
console.log(rt2.graphemeLength)
const rt3 = new RichText({text: '👨👩👧👧'})
console.log(rt3.length)
console.log(rt3.graphemeLength)
Moderation
Applying the moderation system is a challenging task, but we've done our best to simplify it for you. The Moderation API helps handle a wide range of tasks, including:
- User muting (including mutelists)
- User blocking
- Moderator labeling
For more information, see the Moderation Documentation or the associated Labels Reference.
import {moderatePost, moderateProfile} from '@atproto/api'
const postMod = moderatePost(postView, getOpts())
const profileMod = moderateProfile(profileView, getOpts())
if (postMod.content.filter) {
}
if (postMod.content.blur) {
if (postMod.content.noOverride) {
}
}
if (postMod.content.alert) {
}
if (postMod.embed.blur) {
if (postMod.embed.noOverride) {
}
}
if (postMod.embed.alert) {
}
if (postMod.avatar.blur) {
}
if (postMod.avatar.alert) {
}
function getOpts() {
return {
userDid: 'did:plc:1234...',
adultContentEnabled: true,
labels: {
porn: 'hide',
sexual: 'warn',
nudity: 'ignore',
},
labelers: [
{
labeler: {
did: '...',
displayName: 'My mod service'
},
labels: {
porn: 'hide',
sexual: 'warn',
nudity: 'ignore',
}
}
]
}
}
Advanced
Advanced API calls
The methods above are convenience wrappers. It covers most but not all available methods.
The AT Protocol identifies methods and records with reverse-DNS names. You can use them on the agent as well:
const res1 = await agent.com.atproto.repo.createRecord(
{
did: alice.did,
collection: 'app.bsky.feed.post',
record: {
$type: 'app.bsky.feed.post',
text: 'Hello, world!',
createdAt: new Date().toISOString()
}
}
)
const res2 = await agent.com.atproto.repo.listRecords({repo: alice.did, collection: 'app.bsky.feed.post'})
const res3 = await agent.app.bsky.feed.post.create({repo: alice.did}, {
text: 'Hello, world!',
createdAt: new Date().toISOString()
})
const res4 = await agent.app.bsky.feed.post.list({repo: alice.did})
Generic agent
If you want a generic AT Protocol agent without methods related to the Bluesky social lexicon, use the AtpAgent
instead of the BskyAgent
.
import { AtpAgent } from '@atproto/api'
const agent = new AtpAgent({service: 'https://example.com'})
Non-browser configuration
In non-browser environments you'll need to specify a fetch polyfill. See the example react-native polyfill here.
import { BskyAgent } from '@atproto/api'
const agent = new BskyAgent({service: 'https://example.com'})
import {AtpAgentFetchHeaders, AtpAgentFetchHandlerResponse} from '@atproto/api'
BskyAgent.configure({
async fetch(
httpUri: string,
httpMethod: string,
httpHeaders: AtpAgentFetchHeaders,
httpReqBody: any,
): Promise<AtpAgentFetchHandlerResponse> {
return {status: 200, }
}
})
License
MIT