@atproto/api 0.1.3 → 0.2.1

package/src/rich-text/rich-text.ts

@@ -0,0 +1,401 @@
+/*
+= Rich Text Manipulation
+
+When we sanitize rich text, we have to update the entity indices as the
+text is modified. This can be modeled as inserts() and deletes() of the
+rich text string. The possible scenarios are outlined below, along with
+their expected behaviors.
+
+NOTE: Slices are start inclusive, end exclusive
+
+== richTextInsert()
+
+Target string:
+
+   0 1 2 3 4 5 6 7 8 910   // string indices
+   h e l l o   w o r l d   // string value
+       ^-------^           // target slice {start: 2, end: 7}
+
+Scenarios:
+
+A: ^                       // insert "test" at 0
+B:        ^                // insert "test" at 4
+C:                 ^       // insert "test" at 8
+
+A = before           -> move both by num added
+B = inner            -> move end by num added
+C = after            -> noop
+
+Results:
+
+A: 0 1 2 3 4 5 6 7 8 910   // string indices
+   t e s t h e l l o   w   // string value
+               ^-------^   // target slice {start: 6, end: 11}
+
+B: 0 1 2 3 4 5 6 7 8 910   // string indices
+   h e l l t e s t o   w   // string value
+       ^---------------^   // target slice {start: 2, end: 11}
+
+C: 0 1 2 3 4 5 6 7 8 910   // string indices
+   h e l l o   w o t e s   // string value
+       ^-------^           // target slice {start: 2, end: 7}
+
+== richTextDelete()
+
+Target string:
+
+   0 1 2 3 4 5 6 7 8 910   // string indices
+   h e l l o   w o r l d   // string value
+       ^-------^           // target slice {start: 2, end: 7}
+
+Scenarios:
+
+A: ^---------------^       // remove slice {start: 0, end: 9}
+B:               ^-----^   // remove slice {start: 7, end: 11}
+C:         ^-----------^   // remove slice {start: 4, end: 11}
+D:       ^-^               // remove slice {start: 3, end: 5}
+E:   ^-----^               // remove slice {start: 1, end: 5}
+F: ^-^                     // remove slice {start: 0, end: 2}
+
+A = entirely outer   -> delete slice
+B = entirely after   -> noop
+C = partially after  -> move end to remove-start
+D = entirely inner   -> move end by num removed
+E = partially before -> move start to remove-start index, move end by num removed
+F = entirely before  -> move both by num removed
+
+Results:
+
+A: 0 1 2 3 4 5 6 7 8 910   // string indices
+   l d                     // string value
+                           // target slice (deleted)
+
+B: 0 1 2 3 4 5 6 7 8 910   // string indices
+   h e l l o   w           // string value
+       ^-------^           // target slice {start: 2, end: 7}
+
+C: 0 1 2 3 4 5 6 7 8 910   // string indices
+   h e l l                 // string value
+       ^-^                 // target slice {start: 2, end: 4}
+
+D: 0 1 2 3 4 5 6 7 8 910   // string indices
+   h e l   w o r l d       // string value
+       ^---^               // target slice {start: 2, end: 5}
+
+E: 0 1 2 3 4 5 6 7 8 910   // string indices
+   h   w o r l d           // string value
+     ^-^                   // target slice {start: 1, end: 3}
+
+F: 0 1 2 3 4 5 6 7 8 910   // string indices
+   l l o   w o r l d       // string value
+   ^-------^               // target slice {start: 0, end: 5}
+ */
+
+import { AtpAgent } from '../agent'
+import { AppBskyFeedPost, AppBskyRichtextFacet } from '../client'
+import { UnicodeString } from './unicode'
+import { sanitizeRichText } from './sanitization'
+import { detectFacets } from './detection'
+
+export type Facet = AppBskyRichtextFacet.Main
+export type FacetLink = AppBskyRichtextFacet.Link
+export type FacetMention = AppBskyRichtextFacet.Mention
+export type Entity = AppBskyFeedPost.Entity
+
+export interface RichTextProps {
+  text: string
+  facets?: Facet[]
+  /**
+   * @deprecated Use facets instead
+   */
+  entities?: Entity[]
+}
+
+export interface RichTextOpts {
+  cleanNewlines?: boolean
+}
+
+export class RichTextSegment {
+  constructor(public text: string, public facet?: Facet) {}
+
+  get link(): FacetLink | undefined {
+    const link = this.facet?.features.find(AppBskyRichtextFacet.isLink)
+    if (AppBskyRichtextFacet.isLink(link)) {
+      return link
+    }
+    return undefined
+  }
+
+  isLink() {
+    return !!this.link
+  }
+
+  get mention(): FacetMention | undefined {
+    const mention = this.facet?.features.find(AppBskyRichtextFacet.isMention)
+    if (AppBskyRichtextFacet.isMention(mention)) {
+      return mention
+    }
+    return undefined
+  }
+
+  isMention() {
+    return !!this.mention
+  }
+}
+
+export class RichText {
+  unicodeText: UnicodeString
+  facets?: Facet[]
+
+  constructor(props: RichTextProps, opts?: RichTextOpts) {
+    this.unicodeText = new UnicodeString(props.text)
+    this.facets = props.facets
+    if (!this.facets?.length && props.entities?.length) {
+      this.facets = entitiesToFacets(this.unicodeText, props.entities)
+    }
+    if (this.facets) {
+      this.facets.sort(facetSort)
+    }
+    if (opts?.cleanNewlines) {
+      sanitizeRichText(this, { cleanNewlines: true }).copyInto(this)
+    }
+  }
+
+  get text() {
+    return this.unicodeText.toString()
+  }
+
+  get length() {
+    return this.unicodeText.length
+  }
+
+  get graphemeLength() {
+    return this.unicodeText.graphemeLength
+  }
+
+  clone() {
+    return new RichText({
+      text: this.unicodeText.utf16,
+      facets: cloneDeep(this.facets),
+    })
+  }
+
+  copyInto(target: RichText) {
+    target.unicodeText = this.unicodeText
+    target.facets = cloneDeep(this.facets)
+  }
+
+  *segments(): Generator<RichTextSegment, void, void> {
+    const facets = this.facets || []
+    if (!facets.length) {
+      yield new RichTextSegment(this.unicodeText.utf16)
+      return
+    }
+
+    let textCursor = 0
+    let facetCursor = 0
+    do {
+      const currFacet = facets[facetCursor]
+      if (textCursor < currFacet.index.byteStart) {
+        yield new RichTextSegment(
+          this.unicodeText.slice(textCursor, currFacet.index.byteStart),
+        )
+      } else if (textCursor > currFacet.index.byteStart) {
+        facetCursor++
+        continue
+      }
+      if (currFacet.index.byteStart < currFacet.index.byteEnd) {
+        const subtext = this.unicodeText.slice(
+          currFacet.index.byteStart,
+          currFacet.index.byteEnd,
+        )
+        if (!subtext.trim()) {
+          // dont empty string entities
+          yield new RichTextSegment(subtext)
+        } else {
+          yield new RichTextSegment(subtext, currFacet)
+        }
+      }
+      textCursor = currFacet.index.byteEnd
+      facetCursor++
+    } while (facetCursor < facets.length)
+    if (textCursor < this.unicodeText.length) {
+      yield new RichTextSegment(
+        this.unicodeText.slice(textCursor, this.unicodeText.length),
+      )
+    }
+  }
+
+  insert(insertIndex: number, insertText: string) {
+    this.unicodeText = new UnicodeString(
+      this.unicodeText.slice(0, insertIndex) +
+        insertText +
+        this.unicodeText.slice(insertIndex),
+    )
+
+    if (!this.facets?.length) {
+      return this
+    }
+
+    const numCharsAdded = insertText.length
+    for (const ent of this.facets) {
+      // see comment at top of file for labels of each scenario
+      // scenario A (before)
+      if (insertIndex <= ent.index.byteStart) {
+        // move both by num added
+        ent.index.byteStart += numCharsAdded
+        ent.index.byteEnd += numCharsAdded
+      }
+      // scenario B (inner)
+      else if (
+        insertIndex >= ent.index.byteStart &&
+        insertIndex < ent.index.byteEnd
+      ) {
+        // move end by num added
+        ent.index.byteEnd += numCharsAdded
+      }
+      // scenario C (after)
+      // noop
+    }
+    return this
+  }
+
+  delete(removeStartIndex: number, removeEndIndex: number) {
+    this.unicodeText = new UnicodeString(
+      this.unicodeText.slice(0, removeStartIndex) +
+        this.unicodeText.slice(removeEndIndex),
+    )
+
+    if (!this.facets?.length) {
+      return this
+    }
+
+    const numCharsRemoved = removeEndIndex - removeStartIndex
+    for (const ent of this.facets) {
+      // see comment at top of file for labels of each scenario
+      // scenario A (entirely outer)
+      if (
+        removeStartIndex <= ent.index.byteStart &&
+        removeEndIndex >= ent.index.byteEnd
+      ) {
+        // delete slice (will get removed in final pass)
+        ent.index.byteStart = 0
+        ent.index.byteEnd = 0
+      }
+      // scenario B (entirely after)
+      else if (removeStartIndex > ent.index.byteEnd) {
+        // noop
+      }
+      // scenario C (partially after)
+      else if (
+        removeStartIndex > ent.index.byteStart &&
+        removeStartIndex <= ent.index.byteEnd &&
+        removeEndIndex > ent.index.byteEnd
+      ) {
+        // move end to remove start
+        ent.index.byteEnd = removeStartIndex
+      }
+      // scenario D (entirely inner)
+      else if (
+        removeStartIndex >= ent.index.byteStart &&
+        removeEndIndex <= ent.index.byteEnd
+      ) {
+        // move end by num removed
+        ent.index.byteEnd -= numCharsRemoved
+      }
+      // scenario E (partially before)
+      else if (
+        removeStartIndex < ent.index.byteStart &&
+        removeEndIndex >= ent.index.byteStart &&
+        removeEndIndex <= ent.index.byteEnd
+      ) {
+        // move start to remove-start index, move end by num removed
+        ent.index.byteStart = removeStartIndex
+        ent.index.byteEnd -= numCharsRemoved
+      }
+      // scenario F (entirely before)
+      else if (removeEndIndex < ent.index.byteStart) {
+        // move both by num removed
+        ent.index.byteStart -= numCharsRemoved
+        ent.index.byteEnd -= numCharsRemoved
+      }
+    }
+
+    // filter out any facets that were made irrelevant
+    this.facets = this.facets.filter(
+      (ent) => ent.index.byteStart < ent.index.byteEnd,
+    )
+    return this
+  }
+
+  /**
+   * Detects facets such as links and mentions
+   * Note: Overwrites the existing facets with auto-detected facets
+   */
+  async detectFacets(agent: AtpAgent) {
+    this.facets = detectFacets(this.unicodeText)
+    if (this.facets) {
+      for (const facet of this.facets) {
+        for (const feature of facet.features) {
+          if (AppBskyRichtextFacet.isMention(feature)) {
+            const did = await agent
+              .resolveHandle({ handle: feature.did })
+              .catch((_) => undefined)
+              .then((res) => res?.data.did)
+            feature.did = did || ''
+          }
+        }
+      }
+      this.facets.sort(facetSort)
+    }
+  }
+
+  /**
+   * Detects facets such as links and mentions but does not resolve them
+   * Will produce invalid facets! For instance, mentions will not have their DIDs set.
+   * Note: Overwrites the existing facets with auto-detected facets
+   */
+  detectFacetsWithoutResolution() {
+    this.facets = detectFacets(this.unicodeText)
+    if (this.facets) {
+      this.facets.sort(facetSort)
+    }
+  }
+}
+
+const facetSort = (a, b) => a.index.byteStart - b.index.byteStart
+
+function entitiesToFacets(text: UnicodeString, entities: Entity[]): Facet[] {
+  const facets: Facet[] = []
+  for (const ent of entities) {
+    if (ent.type === 'link') {
+      facets.push({
+        $type: 'app.bsky.richtext.facet',
+        index: {
+          byteStart: text.utf16IndexToUtf8Index(ent.index.start),
+          byteEnd: text.utf16IndexToUtf8Index(ent.index.end),
+        },
+        features: [{ $type: 'app.bsky.richtext.facet#link', uri: ent.value }],
+      })
+    } else if (ent.type === 'mention') {
+      facets.push({
+        $type: 'app.bsky.richtext.facet',
+        index: {
+          byteStart: text.utf16IndexToUtf8Index(ent.index.start),
+          byteEnd: text.utf16IndexToUtf8Index(ent.index.end),
+        },
+        features: [
+          { $type: 'app.bsky.richtext.facet#mention', did: ent.value },
+        ],
+      })
+    }
+  }
+  return facets
+}
+
+function cloneDeep<T>(v: T): T {
+  if (typeof v === 'undefined') {
+    return v
+  }
+  return JSON.parse(JSON.stringify(v))
+}

package/src/rich-text/sanitization.ts

@@ -0,0 +1,40 @@
+import { RichText } from './rich-text'
+import { UnicodeString } from './unicode'
+
+const EXCESS_SPACE_RE = /[\r\n]([\u00AD\u2060\u200D\u200C\u200B\s]*[\r\n]){2,}/
+const REPLACEMENT_STR = '\n\n'
+
+export function sanitizeRichText(
+  richText: RichText,
+  opts: { cleanNewlines?: boolean },
+) {
+  if (opts.cleanNewlines) {
+    richText = clean(richText, EXCESS_SPACE_RE, REPLACEMENT_STR)
+  }
+  return richText
+}
+
+function clean(
+  richText: RichText,
+  targetRegexp: RegExp,
+  replacementString: string,
+): RichText {
+  richText = richText.clone()
+
+  let match = richText.unicodeText.utf16.match(targetRegexp)
+  while (match && typeof match.index !== 'undefined') {
+    const oldText = richText.unicodeText
+    const removeStartIndex = richText.unicodeText.utf16IndexToUtf8Index(
+      match.index,
+    )
+    const removeEndIndex = removeStartIndex + new UnicodeString(match[0]).length
+    richText.delete(removeStartIndex, removeEndIndex)
+    if (richText.unicodeText.utf16 === oldText.utf16) {
+      break // sanity check
+    }
+    richText.insert(removeStartIndex, replacementString)
+    match = richText.unicodeText.utf16.match(targetRegexp)
+  }
+
+  return richText
+}

package/src/rich-text/unicode.ts

@@ -0,0 +1,47 @@
+/**
+ * Javascript uses utf16-encoded strings while most environments and specs
+ * have standardized around utf8 (including JSON).
+ *
+ * After some lengthy debated we decided that richtext facets need to use
+ * utf8 indices. This means we need tools to convert indices between utf8
+ * and utf16, and that's precisely what this library handles.
+ */
+
+import { graphemeLen } from '@atproto/common-web'
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+export class UnicodeString {
+  utf16: string
+  utf8: Uint8Array
+  private _graphemeLen?: number | undefined
+
+  constructor(utf16: string) {
+    this.utf16 = utf16
+    this.utf8 = encoder.encode(utf16)
+  }
+
+  get length() {
+    return this.utf8.byteLength
+  }
+
+  get graphemeLength() {
+    if (!this._graphemeLen) {
+      this._graphemeLen = graphemeLen(this.utf16)
+    }
+    return this._graphemeLen
+  }
+
+  slice(start?: number, end?: number): string {
+    return decoder.decode(this.utf8.slice(start, end))
+  }
+
+  utf16IndexToUtf8Index(i: number) {
+    return encoder.encode(this.utf16.slice(0, i)).byteLength
+  }
+
+  toString() {
+    return this.utf16
+  }
+}

package/src/types.ts

@@ -56,7 +56,7 @@ export interface AtpAgentFetchHandlerResponse {
   headers: Record<string, string>
   body: any
 }
-export type AptAgentFetchHandler = (
+export type AtpAgentFetchHandler = (
   httpUri: string,
   httpMethod: string,
   httpHeaders: AtpAgentFetchHeaders,
@@ -67,5 +67,5 @@ export type AptAgentFetchHandler = (
  * AtpAgent global config opts
  */
 export interface AtpAgentGlobalOpts {
-  fetch: AptAgentFetchHandler
+  fetch: AtpAgentFetchHandler
 }

package/tests/agent.test.ts

@@ -17,7 +17,7 @@ describe('agent', () => {
 
   beforeAll(async () => {
     server = await runTestServer({
-      dbPostgresSchema: 'session',
+      dbPostgresSchema: 'api_agent',
     })
     close = server.close
   })
@@ -48,7 +48,9 @@ describe('agent', () => {
     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({})
+    const { data: sessionInfo } = await agent.api.com.atproto.server.getSession(
+      {},
+    )
     expect(sessionInfo).toEqual({
       did: res.data.did,
       handle: res.data.handle,
@@ -88,7 +90,8 @@ describe('agent', () => {
     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({})
+    const { data: sessionInfo } =
+      await agent2.api.com.atproto.server.getSession({})
     expect(sessionInfo).toEqual({
       did: res1.data.did,
       handle: res1.data.handle,
@@ -128,7 +131,8 @@ describe('agent', () => {
     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({})
+    const { data: sessionInfo } =
+      await agent2.api.com.atproto.server.getSession({})
     expect(sessionInfo).toEqual({
       did: res1.data.did,
       handle: res1.data.handle,
@@ -248,7 +252,7 @@ describe('agent', () => {
           body: { error: 'ExpiredToken' },
         }
       }
-      if (httpUri.includes('com.atproto.session.refresh')) {
+      if (httpUri.includes('com.atproto.server.refreshSession')) {
         refreshCalls++
       }
       return defaultFetchHandler(httpUri, httpMethod, httpHeaders, httpReqBody)
@@ -358,7 +362,7 @@ describe('agent', () => {
           body: { error: 'ExpiredToken' },
         }
       }
-      if (httpUri.includes('com.atproto.session.refresh')) {
+      if (httpUri.includes('com.atproto.server.refreshSession')) {
         return {
           status: 500,
           headers: {},

package/tests/bsky-agent.test.ts

@@ -0,0 +1,140 @@
+import {
+  CloseFn,
+  runTestServer,
+  TestServerInfo,
+} from '@atproto/pds/tests/_util'
+import { BskyAgent, ComAtprotoRepoPutRecord, AppBskyActorProfile } from '..'
+
+describe('agent', () => {
+  let server: TestServerInfo
+  let close: CloseFn
+
+  beforeAll(async () => {
+    server = await runTestServer({
+      dbPostgresSchema: 'bsky_agent',
+    })
+    close = server.close
+  })
+
+  afterAll(async () => {
+    await close()
+  })
+
+  it('upsertProfile correctly creates and updates profiles.', async () => {
+    const agent = new BskyAgent({ service: server.url })
+
+    await agent.createAccount({
+      handle: 'user1.test',
+      email: 'user1@test.com',
+      password: 'password',
+    })
+
+    const profile1 = await agent.getProfile({ actor: agent.session?.did || '' })
+    expect(profile1.data.displayName).toBeFalsy()
+
+    await agent.upsertProfile((existing) => {
+      expect(existing).toBeFalsy()
+      return {
+        displayName: 'Bob',
+      }
+    })
+
+    const profile2 = await agent.getProfile({ actor: agent.session?.did || '' })
+    expect(profile2.data.displayName).toBe('Bob')
+
+    await agent.upsertProfile((existing) => {
+      expect(existing).toBeTruthy()
+      return {
+        displayName: existing?.displayName?.toUpperCase(),
+      }
+    })
+
+    const profile3 = await agent.getProfile({ actor: agent.session?.did || '' })
+    expect(profile3.data.displayName).toBe('BOB')
+  })
+
+  it('upsertProfile correctly handles CAS failures.', async () => {
+    const agent = new BskyAgent({ service: server.url })
+
+    await agent.createAccount({
+      handle: 'user2.test',
+      email: 'user2@test.com',
+      password: 'password',
+    })
+
+    const profile1 = await agent.getProfile({ actor: agent.session?.did || '' })
+    expect(profile1.data.displayName).toBeFalsy()
+
+    let hasConflicted = false
+    let ranTwice = false
+    await agent.upsertProfile(async (existing) => {
+      if (!hasConflicted) {
+        await agent.com.atproto.repo.putRecord({
+          repo: agent.session?.did || '',
+          collection: 'app.bsky.actor.profile',
+          rkey: 'self',
+          record: {
+            $type: 'app.bsky.actor.profile',
+            displayName: String(Math.random()),
+          },
+        })
+        hasConflicted = true
+      } else {
+        ranTwice = true
+      }
+      return {
+        displayName: 'Bob',
+      }
+    })
+    expect(ranTwice).toBe(true)
+
+    const profile2 = await agent.getProfile({ actor: agent.session?.did || '' })
+    expect(profile2.data.displayName).toBe('Bob')
+  })
+
+  it('upsertProfile wont endlessly retry CAS failures.', async () => {
+    const agent = new BskyAgent({ service: server.url })
+
+    await agent.createAccount({
+      handle: 'user3.test',
+      email: 'user3@test.com',
+      password: 'password',
+    })
+
+    const profile1 = await agent.getProfile({ actor: agent.session?.did || '' })
+    expect(profile1.data.displayName).toBeFalsy()
+
+    const p = agent.upsertProfile(async (existing) => {
+      await agent.com.atproto.repo.putRecord({
+        repo: agent.session?.did || '',
+        collection: 'app.bsky.actor.profile',
+        rkey: 'self',
+        record: {
+          $type: 'app.bsky.actor.profile',
+          displayName: String(Math.random()),
+        },
+      })
+      return {
+        displayName: 'Bob',
+      }
+    })
+    await expect(p).rejects.toThrow(ComAtprotoRepoPutRecord.InvalidSwapError)
+  })
+
+  it('upsertProfile validates the record.', async () => {
+    const agent = new BskyAgent({ service: server.url })
+
+    await agent.createAccount({
+      handle: 'user4.test',
+      email: 'user4@test.com',
+      password: 'password',
+    })
+
+    const p = agent.upsertProfile((existing) => {
+      return {
+        displayName: { string: 'Bob' },
+      } as unknown as AppBskyActorProfile.Record
+    })
+    await expect(p).rejects.toThrow('Record/displayName must be a string')
+  })
+})