@atproto/api 0.0.8 → 0.1.0

package/src/types.ts

@@ -0,0 +1,71 @@
+/**
+ * Used by the PersistSessionHandler to indicate what change occurred
+ */
+export type AtpSessionEvent = 'create' | 'create-failed' | 'update' | 'expired'
+
+/**
+ * Used by AtpAgent to store active sessions
+ */
+export interface AtpSessionData {
+  refreshJwt: string
+  accessJwt: string
+  handle: string
+  did: string
+}
+
+/**
+ * Handler signature passed to AtpAgent to store session data
+ */
+export type AtpPersistSessionHandler = (
+  evt: AtpSessionEvent,
+  session: AtpSessionData | undefined,
+) => void | Promise<void>
+
+/**
+ * AtpAgent constructor() opts
+ */
+export interface AtpAgentOpts {
+  service: string | URL
+  persistSession?: AtpPersistSessionHandler
+}
+
+/**
+ * AtpAgent createAccount() opts
+ */
+export interface AtpAgentCreateAccountOpts {
+  email: string
+  password: string
+  handle: string
+  inviteCode?: string
+}
+
+/**
+ * AtpAgent login() opts
+ */
+export interface AtpAgentLoginOpts {
+  identifier: string
+  password: string
+}
+
+/**
+ * AtpAgent global fetch handler
+ */
+type AtpAgentFetchHeaders = Record<string, string>
+export interface AtpAgentFetchHandlerResponse {
+  status: number
+  headers: Record<string, string>
+  body: any
+}
+export type AptAgentFetchHandler = (
+  httpUri: string,
+  httpMethod: string,
+  httpHeaders: AtpAgentFetchHeaders,
+  httpReqBody: any,
+) => Promise<AtpAgentFetchHandlerResponse>
+
+/**
+ * AtpAgent global config opts
+ */
+export interface AtpAgentGlobalOpts {
+  fetch: AptAgentFetchHandler
+}

package/tests/_util.ts

@@ -0,0 +1,26 @@
+import { AtpAgentFetchHandlerResponse } from '..'
+
+export async function fetchHandler(
+  httpUri: string,
+  httpMethod: string,
+  httpHeaders: Record<string, string>,
+  httpReqBody: unknown,
+): Promise<AtpAgentFetchHandlerResponse> {
+  // The duplex field is now required for streaming bodies, but not yet reflected
+  // anywhere in docs or types. See whatwg/fetch#1438, nodejs/node#46221.
+  const reqInit: RequestInit & { duplex: string } = {
+    method: httpMethod,
+    headers: httpHeaders,
+    body: httpReqBody
+      ? new TextEncoder().encode(JSON.stringify(httpReqBody))
+      : undefined,
+    duplex: 'half',
+  }
+  const res = await fetch(httpUri, reqInit)
+  const resBody = await res.arrayBuffer()
+  return {
+    status: res.status,
+    headers: Object.fromEntries(res.headers.entries()),
+    body: resBody ? JSON.parse(new TextDecoder().decode(resBody)) : undefined,
+  }
+}

package/tests/agent.test.ts

@@ -0,0 +1,391 @@
+import { defaultFetchHandler } from '@atproto/xrpc'
+import {
+  CloseFn,
+  runTestServer,
+  TestServerInfo,
+} from '@atproto/pds/tests/_util'
+import {
+  AtpAgent,
+  AtpAgentFetchHandlerResponse,
+  AtpSessionEvent,
+  AtpSessionData,
+} from '..'
+
+describe('agent', () => {
+  let server: TestServerInfo
+  let close: CloseFn
+
+  beforeAll(async () => {
+    server = await runTestServer({
+      dbPostgresSchema: 'session',
+    })
+    close = server.close
+  })
+
+  afterAll(async () => {
+    await close()
+  })
+
+  it('creates a new session on account creation.', async () => {
+    const events: string[] = []
+    const sessions: (AtpSessionData | undefined)[] = []
+    const persistSession = (evt: AtpSessionEvent, sess?: AtpSessionData) => {
+      events.push(evt)
+      sessions.push(sess)
+    }
+
+    const agent = new AtpAgent({ service: server.url, persistSession })
+
+    const res = await agent.createAccount({
+      handle: 'user1.test',
+      email: 'user1@test.com',
+      password: 'password',
+    })
+
+    expect(agent.hasSession).toEqual(true)
+    expect(agent.session?.accessJwt).toEqual(res.data.accessJwt)
+    expect(agent.session?.refreshJwt).toEqual(res.data.refreshJwt)
+    expect(agent.session?.handle).toEqual(res.data.handle)
+    expect(agent.session?.did).toEqual(res.data.did)
+
+    const { data: sessionInfo } = await agent.api.com.atproto.session.get({})
+    expect(sessionInfo).toEqual({
+      did: res.data.did,
+      handle: res.data.handle,
+    })
+
+    expect(events.length).toEqual(1)
+    expect(events[0]).toEqual('create')
+    expect(sessions.length).toEqual(1)
+    expect(sessions[0]?.accessJwt).toEqual(agent.session?.accessJwt)
+  })
+
+  it('creates a new session on login.', async () => {
+    const events: string[] = []
+    const sessions: (AtpSessionData | undefined)[] = []
+    const persistSession = (evt: AtpSessionEvent, sess?: AtpSessionData) => {
+      events.push(evt)
+      sessions.push(sess)
+    }
+
+    const agent1 = new AtpAgent({ service: server.url, persistSession })
+
+    await agent1.createAccount({
+      handle: 'user2.test',
+      email: 'user2@test.com',
+      password: 'password',
+    })
+
+    const agent2 = new AtpAgent({ service: server.url, persistSession })
+    const res1 = await agent2.login({
+      identifier: 'user2.test',
+      password: 'password',
+    })
+
+    expect(agent2.hasSession).toEqual(true)
+    expect(agent2.session?.accessJwt).toEqual(res1.data.accessJwt)
+    expect(agent2.session?.refreshJwt).toEqual(res1.data.refreshJwt)
+    expect(agent2.session?.handle).toEqual(res1.data.handle)
+    expect(agent2.session?.did).toEqual(res1.data.did)
+
+    const { data: sessionInfo } = await agent2.api.com.atproto.session.get({})
+    expect(sessionInfo).toEqual({
+      did: res1.data.did,
+      handle: res1.data.handle,
+    })
+
+    expect(events.length).toEqual(2)
+    expect(events[0]).toEqual('create')
+    expect(events[1]).toEqual('create')
+    expect(sessions.length).toEqual(2)
+    expect(sessions[0]?.accessJwt).toEqual(agent1.session?.accessJwt)
+    expect(sessions[1]?.accessJwt).toEqual(agent2.session?.accessJwt)
+  })
+
+  it('resumes an existing session.', async () => {
+    const events: string[] = []
+    const sessions: (AtpSessionData | undefined)[] = []
+    const persistSession = (evt: AtpSessionEvent, sess?: AtpSessionData) => {
+      events.push(evt)
+      sessions.push(sess)
+    }
+
+    const agent1 = new AtpAgent({ service: server.url, persistSession })
+
+    await agent1.createAccount({
+      handle: 'user3.test',
+      email: 'user3@test.com',
+      password: 'password',
+    })
+    if (!agent1.session) {
+      throw new Error('No session created')
+    }
+
+    const agent2 = new AtpAgent({ service: server.url, persistSession })
+    const res1 = await agent2.resumeSession(agent1.session)
+
+    expect(agent2.hasSession).toEqual(true)
+    expect(agent2.session?.handle).toEqual(res1.data.handle)
+    expect(agent2.session?.did).toEqual(res1.data.did)
+
+    const { data: sessionInfo } = await agent2.api.com.atproto.session.get({})
+    expect(sessionInfo).toEqual({
+      did: res1.data.did,
+      handle: res1.data.handle,
+    })
+
+    expect(events.length).toEqual(2)
+    expect(events[0]).toEqual('create')
+    expect(events[1]).toEqual('create')
+    expect(sessions.length).toEqual(2)
+    expect(sessions[0]?.accessJwt).toEqual(agent1.session?.accessJwt)
+    expect(sessions[1]?.accessJwt).toEqual(agent2.session?.accessJwt)
+  })
+
+  it('refreshes existing session.', async () => {
+    const events: string[] = []
+    const sessions: (AtpSessionData | undefined)[] = []
+    const persistSession = (evt: AtpSessionEvent, sess?: AtpSessionData) => {
+      events.push(evt)
+      sessions.push(sess)
+    }
+
+    const agent = new AtpAgent({ service: server.url, persistSession })
+
+    // create an account and a session with it
+    await agent.createAccount({
+      handle: 'user4.test',
+      email: 'user4@test.com',
+      password: 'password',
+    })
+    if (!agent.session) {
+      throw new Error('No session created')
+    }
+    const session1 = agent.session
+    const origAccessJwt = session1.accessJwt
+
+    // wait 1 second so that a token refresh will issue a new access token
+    // (if the timestamp, which has 1 second resolution, is the same -- then the access token won't change)
+    await new Promise((r) => setTimeout(r, 1000))
+
+    // patch the fetch handler to fake an expired token error on the next request
+    const tokenExpiredFetchHandler = async function (
+      httpUri: string,
+      httpMethod: string,
+      httpHeaders: Record<string, string>,
+      httpReqBody: unknown,
+    ): Promise<AtpAgentFetchHandlerResponse> {
+      if (httpHeaders.authorization === `Bearer ${origAccessJwt}`) {
+        return {
+          status: 400,
+          headers: {},
+          body: { error: 'ExpiredToken' },
+        }
+      }
+      return defaultFetchHandler(httpUri, httpMethod, httpHeaders, httpReqBody)
+    }
+
+    // put the agent through the auth flow
+    AtpAgent.configure({ fetch: tokenExpiredFetchHandler })
+    const res1 = await agent.api.app.bsky.feed.getTimeline()
+    AtpAgent.configure({ fetch: defaultFetchHandler })
+
+    expect(res1.success).toEqual(true)
+    expect(agent.hasSession).toEqual(true)
+    expect(agent.session?.accessJwt).not.toEqual(session1.accessJwt)
+    expect(agent.session?.refreshJwt).not.toEqual(session1.refreshJwt)
+    expect(agent.session?.handle).toEqual(session1.handle)
+    expect(agent.session?.did).toEqual(session1.did)
+
+    expect(events.length).toEqual(2)
+    expect(events[0]).toEqual('create')
+    expect(events[1]).toEqual('update')
+    expect(sessions.length).toEqual(2)
+    expect(sessions[0]?.accessJwt).toEqual(origAccessJwt)
+    expect(sessions[1]?.accessJwt).toEqual(agent.session?.accessJwt)
+  })
+
+  it('dedupes session refreshes.', async () => {
+    const events: string[] = []
+    const sessions: (AtpSessionData | undefined)[] = []
+    const persistSession = (evt: AtpSessionEvent, sess?: AtpSessionData) => {
+      events.push(evt)
+      sessions.push(sess)
+    }
+
+    const agent = new AtpAgent({ service: server.url, persistSession })
+
+    // create an account and a session with it
+    await agent.createAccount({
+      handle: 'user5.test',
+      email: 'user5@test.com',
+      password: 'password',
+    })
+    if (!agent.session) {
+      throw new Error('No session created')
+    }
+    const session1 = agent.session
+    const origAccessJwt = session1.accessJwt
+
+    // wait 1 second so that a token refresh will issue a new access token
+    // (if the timestamp, which has 1 second resolution, is the same -- then the access token won't change)
+    await new Promise((r) => setTimeout(r, 1000))
+
+    // patch the fetch handler to fake an expired token error on the next request
+    let expiredCalls = 0
+    let refreshCalls = 0
+    const tokenExpiredFetchHandler = async function (
+      httpUri: string,
+      httpMethod: string,
+      httpHeaders: Record<string, string>,
+      httpReqBody: unknown,
+    ): Promise<AtpAgentFetchHandlerResponse> {
+      if (httpHeaders.authorization === `Bearer ${origAccessJwt}`) {
+        expiredCalls++
+        return {
+          status: 400,
+          headers: {},
+          body: { error: 'ExpiredToken' },
+        }
+      }
+      if (httpUri.includes('com.atproto.session.refresh')) {
+        refreshCalls++
+      }
+      return defaultFetchHandler(httpUri, httpMethod, httpHeaders, httpReqBody)
+    }
+
+    // put the agent through the auth flow
+    AtpAgent.configure({ fetch: tokenExpiredFetchHandler })
+    const [res1, res2, res3] = await Promise.all([
+      agent.api.app.bsky.feed.getTimeline(),
+      agent.api.app.bsky.feed.getTimeline(),
+      agent.api.app.bsky.feed.getTimeline(),
+    ])
+    AtpAgent.configure({ fetch: defaultFetchHandler })
+
+    expect(expiredCalls).toEqual(3)
+    expect(refreshCalls).toEqual(1)
+    expect(res1.success).toEqual(true)
+    expect(res2.success).toEqual(true)
+    expect(res3.success).toEqual(true)
+    expect(agent.hasSession).toEqual(true)
+    expect(agent.session?.accessJwt).not.toEqual(session1.accessJwt)
+    expect(agent.session?.refreshJwt).not.toEqual(session1.refreshJwt)
+    expect(agent.session?.handle).toEqual(session1.handle)
+    expect(agent.session?.did).toEqual(session1.did)
+
+    expect(events.length).toEqual(2)
+    expect(events[0]).toEqual('create')
+    expect(events[1]).toEqual('update')
+    expect(sessions.length).toEqual(2)
+    expect(sessions[0]?.accessJwt).toEqual(origAccessJwt)
+    expect(sessions[1]?.accessJwt).toEqual(agent.session?.accessJwt)
+  })
+
+  it('persists an empty session on login and resumeSession failures', async () => {
+    const events: string[] = []
+    const sessions: (AtpSessionData | undefined)[] = []
+    const persistSession = (evt: AtpSessionEvent, sess?: AtpSessionData) => {
+      events.push(evt)
+      sessions.push(sess)
+    }
+
+    const agent = new AtpAgent({ service: server.url, persistSession })
+
+    try {
+      await agent.login({
+        identifier: 'baduser.test',
+        password: 'password',
+      })
+    } catch (_e: any) {
+      // ignore
+    }
+    expect(agent.hasSession).toEqual(false)
+
+    try {
+      await agent.resumeSession({
+        accessJwt: 'bad',
+        refreshJwt: 'bad',
+        did: 'bad',
+        handle: 'bad',
+      })
+    } catch (_e: any) {
+      // ignore
+    }
+    expect(agent.hasSession).toEqual(false)
+
+    expect(events.length).toEqual(2)
+    expect(events[0]).toEqual('create-failed')
+    expect(events[1]).toEqual('create-failed')
+    expect(sessions.length).toEqual(2)
+    expect(typeof sessions[0]).toEqual('undefined')
+    expect(typeof sessions[1]).toEqual('undefined')
+  })
+
+  it('does not modify or persist the session on a failed refresh', async () => {
+    const events: string[] = []
+    const sessions: (AtpSessionData | undefined)[] = []
+    const persistSession = (evt: AtpSessionEvent, sess?: AtpSessionData) => {
+      events.push(evt)
+      sessions.push(sess)
+    }
+
+    const agent = new AtpAgent({ service: server.url, persistSession })
+
+    // create an account and a session with it
+    await agent.createAccount({
+      handle: 'user6.test',
+      email: 'user6@test.com',
+      password: 'password',
+    })
+    if (!agent.session) {
+      throw new Error('No session created')
+    }
+    const session1 = agent.session
+    const origAccessJwt = session1.accessJwt
+
+    // patch the fetch handler to fake an expired token error on the next request
+    const tokenExpiredFetchHandler = async function (
+      httpUri: string,
+      httpMethod: string,
+      httpHeaders: Record<string, string>,
+      httpReqBody: unknown,
+    ): Promise<AtpAgentFetchHandlerResponse> {
+      if (httpHeaders.authorization === `Bearer ${origAccessJwt}`) {
+        return {
+          status: 400,
+          headers: {},
+          body: { error: 'ExpiredToken' },
+        }
+      }
+      if (httpUri.includes('com.atproto.session.refresh')) {
+        return {
+          status: 500,
+          headers: {},
+          body: undefined,
+        }
+      }
+      return defaultFetchHandler(httpUri, httpMethod, httpHeaders, httpReqBody)
+    }
+
+    // put the agent through the auth flow
+    AtpAgent.configure({ fetch: tokenExpiredFetchHandler })
+    try {
+      await agent.api.app.bsky.feed.getTimeline()
+      throw new Error('Should have failed')
+    } catch (e: any) {
+      // the original error passes through
+      expect(e.status).toEqual(400)
+      expect(e.error).toEqual('ExpiredToken')
+    }
+    AtpAgent.configure({ fetch: defaultFetchHandler })
+
+    // still has session because it wasn't invalidated
+    expect(agent.hasSession).toEqual(true)
+
+    expect(events.length).toEqual(1)
+    expect(events[0]).toEqual('create')
+    expect(sessions.length).toEqual(1)
+    expect(sessions[0]?.accessJwt).toEqual(origAccessJwt)
+  })
+})

package/tests/errors.test.ts

@@ -3,22 +3,18 @@ import {
   runTestServer,
   TestServerInfo,
 } from '@atproto/pds/tests/_util'
-import {
-  sessionClient,
-  SessionServiceClient,
-  ComAtprotoAccountCreate,
-} from '..'
+import { AtpAgent, ComAtprotoAccountCreate } from '..'
 
 describe('errors', () => {
   let server: TestServerInfo
-  let client: SessionServiceClient
+  let client: AtpAgent
   let close: CloseFn
 
   beforeAll(async () => {
     server = await runTestServer({
       dbPostgresSchema: 'known_errors',
     })
-    client = sessionClient.service(server.url)
+    client = new AtpAgent({ service: server.url })
     close = server.close
   })
 
@@ -27,7 +23,7 @@ describe('errors', () => {
   })
 
   it('constructs the correct error instance', async () => {
-    const res = client.com.atproto.account.create({
+    const res = client.api.com.atproto.account.create({
       handle: 'admin',
       email: 'admin@test.com',
       password: 'password',