@atcute/bluesky-richtext-builder 2.0.4 → 3.0.0

package/README.md

@@ -1,19 +1,191 @@
 # @atcute/bluesky-richtext-builder
 
-builder pattern for Bluesky's rich text facets.
+fluent builder for constructing Bluesky rich text with facets.
+
+```sh
+npm install @atcute/bluesky-richtext-builder
+```
+
+Bluesky posts support rich text with mentions, links, and hashtags. these are represented as
+"facets" - byte ranges with attached features. this package provides a builder that handles the byte
+offset calculations for you.
+
+## why use a builder?
+
+Bluesky facets use byte offsets, not character positions. this matters for non-ASCII text:
+
+```ts
+// "café" is 5 bytes in UTF-8 (c=1, a=1, f=1, é=2)
+const text = 'café ☕';
+
+// the coffee emoji starts at byte 5, not character 5
+```
+
+the builder handles these calculations automatically, so you don't have to think about byte offsets.
+
+## usage
+
+### basic usage
 
 ```ts
 import RichtextBuilder from '@atcute/bluesky-richtext-builder';
 
-const { text, facets } = new RichtextBuilder()
-	.addText(`hello, `)
-	.addMention(`@user`, 'did:plc:ia76kvnndjutgedggx2ibrem')
-	.addText(`! please visit my`)
-	.addLink(`website`, 'https://example.com');
+const rt = new RichtextBuilder()
+	.addText('hello, ')
+	.addMention('@alice', 'did:plc:abc123')
+	.addText('! check out ')
+	.addLink('my website', 'https://example.com');
+
+console.log(rt.text);
+// -> "hello, @alice! check out my website"
+
+console.log(rt.facets);
+// -> [
+//   { index: { byteStart: 7, byteEnd: 13 }, features: [{ $type: 'app.bsky.richtext.facet#mention', did: '...' }] },
+//   { index: { byteStart: 25, byteEnd: 35 }, features: [{ $type: 'app.bsky.richtext.facet#link', uri: '...' }] }
+// ]
+```
+
+### creating a post
+
+use with `@atcute/client` to create a post:
+
+```sh
+npm install @atcute/client @atcute/password-session @atcute/bluesky
+```
+
+```ts
+import { Client, ok } from '@atcute/client';
+import { PasswordSession } from '@atcute/password-session';
+import RichtextBuilder from '@atcute/bluesky-richtext-builder';
+
+import type {} from '@atcute/bluesky';
+
+const session = await PasswordSession.login({
+	service: 'https://bsky.social',
+	identifier: 'you.bsky.social',
+	password: 'your-app-password',
+});
+
+const rpc = new Client({ handler: session });
+
+const rt = new RichtextBuilder()
+	.addText('hello ')
+	.addMention('@bsky.app', 'did:plc:z72i7hdynmk6r22z27h6tvur')
+	.addText('! ')
+	.addTag('#atproto', 'atproto');
+
+await ok(
+	rpc.post('com.atproto.repo.createRecord', {
+		input: {
+			repo: session.did,
+			collection: 'app.bsky.feed.post',
+			record: {
+				$type: 'app.bsky.feed.post',
+				text: rt.text,
+				facets: rt.facets,
+				createdAt: new Date().toISOString(),
+			},
+		},
+	}),
+);
+```
+
+### adding links
+
+```ts
+const rt = new RichtextBuilder()
+	.addText('read the ')
+	.addLink('documentation', 'https://atproto.com/docs')
+	.addText(' for more info');
+```
+
+the link text can be anything - it doesn't have to be the URL:
+
+```ts
+const rt = new RichtextBuilder().addLink('click here', 'https://example.com');
+```
+
+### adding mentions
+
+mentions require both the display text and the user's DID:
+
+```ts
+const rt = new RichtextBuilder().addMention('@alice.bsky.social', 'did:plc:abc123');
+```
+
+you'll typically resolve the handle to a DID first:
+
+```ts
+import {
+	CompositeHandleResolver,
+	DohJsonHandleResolver,
+	WellKnownHandleResolver,
+} from '@atcute/identity-resolver';
+
+const handleResolver = new CompositeHandleResolver({
+	methods: {
+		dns: new DohJsonHandleResolver({
+			dohUrl: 'https://mozilla.cloudflare-dns.com/dns-query',
+		}),
+		http: new WellKnownHandleResolver(),
+	},
+});
+
+const handle = 'alice.bsky.social';
+const did = await handleResolver.resolve(handle);
+
+const rt = new RichtextBuilder().addMention(`@${handle}`, did);
+```
+
+### adding hashtags
+
+```ts
+const rt = new RichtextBuilder()
+	.addText('loving ')
+	.addTag('#atproto', 'atproto')
+	.addText(' development!');
+
+// text: "loving #atproto development!"
+```
 
-text;
-// ^? `hello, @user! please visit my website`
+### custom facet features
+
+use `addDecoratedText()` for custom facet features:
+
+```ts
+import type { FacetFeature } from '@atcute/bluesky-richtext-builder';
+
+const feature: FacetFeature = {
+	$type: 'app.bsky.richtext.facet#link',
+	uri: 'https://example.com',
+};
+
+const rt = new RichtextBuilder().addDecoratedText('custom link', feature);
+```
+
+### getting the result
+
+there are multiple ways to get the composed rich text:
+
+```ts
+const rt = new RichtextBuilder().addText('hello ').addTag('#world', 'world');
+
+// via getters
+const text = rt.text;
+const facets = rt.facets;
+
+// via build() method
+const { text, facets } = rt.build();
+```
+
+### cloning the builder
+
+clone a builder to create variations:
+
+```ts
+const base = new RichtextBuilder().addText('hello ');
 
-facets;
-// ^? [{ index: { byteStart: 7, byteEnd: 12 }, ... }, { index: { byteStart: 30, byteEnd: 37 }, ... }];
+const withMention = base.clone().addMention('@alice', 'did:plc:abc');
+const withLink = base.clone().addLink('world', 'https://example.com');
 ```

package/dist/index.d.ts

@@ -23,37 +23,38 @@ declare class RichtextBuilder {
     clone(): RichtextBuilder;
     /**
      * Add plain text to the rich text
-     * @param substr The plain text
+     * @param text The plain text
      * @returns The builder instance, for chaining
      */
-    addText(substr: string): this;
+    addText(text: string): this;
     /**
      * Add decorated text to the rich text
-     * @param substr The text itself
+     * @param text The text itself
      * @param feature Feature to imbue on the text
      * @returns The builder instance, for chaining
      */
-    addDecoratedText(substr: string, feature: FacetFeature): this;
+    addDecoratedText(text: string, feature: FacetFeature): this;
     /**
      * Add link to the rich text
-     * @param substr Text of the link
+     * @param text Text of the link
      * @param uri Valid URL, for example: https://example.com
      * @returns The builder instance, for chaining
      */
-    addLink(substr: string, uri: GenericUri): this;
+    addLink(text: string, uri: GenericUri): this;
     /**
-     * Mentions a user in rich text
-     * @param substr Text of the mention, this is usually in the form of `@handle`
+     * Mention a user in rich text
+     * @param text Text of the mention, usually in the form of `@handle`
      * @param did Valid DID, for example: did:plc:ia76kvnndjutgedggx2ibrem
      * @returns The builder instance, for chaining
      */
-    addMention(substr: string, did: Did): this;
+    addMention(text: string, did: Did): this;
     /**
      * Add inline hashtag to the rich text
+     * @param text Text to display
      * @param tag The tag, without the pound prefix
-     * @returns THe builder instance, for chaining
+     * @returns The builder instance, for chaining
      */
-    addTag(tag: string): this;
+    addTag(text: string, tag: string): this;
 }
 export default RichtextBuilder;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAExD,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAExD,uEAAuE;AACvE,MAAM,MAAM,KAAK,GAAG,oBAAoB,CAAC,IAAI,CAAC;AAC9C,gDAAgD;AAChD,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;AAI1D,0BAA0B;AAC1B,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,EAAE,CAAC;CAChB;AAED,kDAAkD;AAClD,cAAM,eAAe;;IAMpB,8BAA8B;IAC9B,IAAI,IAAI,IAAI,MAAM,CASjB;IAED,gCAAgC;IAChC,IAAI,MAAM,IAAI,KAAK,EAAE,CASpB;IAED,sCAAsC;IACtC,KAAK,IAAI,aAAa;IAOtB,uCAAuC;IACvC,KAAK,IAAI,eAAe;IAOxB;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAO7B;;;;;OAKG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI;IAyB7D;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI;IAI9C;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,IAAI;IAI1C;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAGzB;AAED,eAAe,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGxD,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAExD,uEAAuE;AACvE,MAAM,MAAM,KAAK,GAAG,oBAAoB,CAAC,IAAI,CAAC;AAC9C,gDAAgD;AAChD,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;AAE1D,0BAA0B;AAC1B,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,EAAE,CAAC;CAChB;AAED,kDAAkD;AAClD,cAAM,eAAe;;IAMpB,8BAA8B;IAC9B,IAAI,IAAI,IAAI,MAAM,CASjB;IAED,gCAAgC;IAChC,IAAI,MAAM,IAAI,KAAK,EAAE,CASpB;IAED,sCAAsC;IACtC,KAAK,IAAI,aAAa,CAKrB;IAED,uCAAuC;IACvC,KAAK,IAAI,eAAe,CAKvB;IAED;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAK1B;IAED;;;;;OAKG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI,CAyB1D;IAED;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI,CAE3C;IAED;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,IAAI,CAEvC;IAED;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAEtC;CACD;AAED,eAAe,eAAe,CAAC"}

package/dist/index.js

@@ -1,4 +1,4 @@
-const encoder = new TextEncoder();
+import { getUtf8Length } from '@atcute/uint8array';
 /** Builder for constructing Bluesky rich texts */
 class RichtextBuilder {
     // Even-numbered are substrings, odd-numbered are facets
@@ -38,65 +38,67 @@ class RichtextBuilder {
     }
     /**
      * Add plain text to the rich text
-     * @param substr The plain text
+     * @param text The plain text
      * @returns The builder instance, for chaining
      */
-    addText(substr) {
+    addText(text) {
         const segments = this.#segments;
-        segments[segments.length - 1] += substr;
+        segments[segments.length - 1] += text;
         return this;
     }
     /**
      * Add decorated text to the rich text
-     * @param substr The text itself
+     * @param text The text itself
      * @param feature Feature to imbue on the text
      * @returns The builder instance, for chaining
      */
-    addDecoratedText(substr, feature) {
+    addDecoratedText(text, feature) {
         const segments = this.#segments;
         const last = segments.length - 1;
         // Calculate the starting index
         let start = 0;
-        start += encoder.encode(segments[last]).byteLength;
+        start += getUtf8Length(segments[last]);
         if (last !== 0) {
             start += segments[last - 1].index.byteEnd;
         }
+        const byteLength = getUtf8Length(text);
         const facet = {
             index: {
                 byteStart: start,
-                byteEnd: start + encoder.encode(substr).byteLength,
+                byteEnd: start + byteLength,
             },
             features: [feature],
         };
-        segments[last] += substr;
+        segments[last] += text;
         segments.push(facet, '');
         return this;
     }
     /**
      * Add link to the rich text
-     * @param substr Text of the link
+     * @param text Text of the link
      * @param uri Valid URL, for example: https://example.com
      * @returns The builder instance, for chaining
      */
-    addLink(substr, uri) {
-        return this.addDecoratedText(substr, { $type: 'app.bsky.richtext.facet#link', uri: uri });
+    addLink(text, uri) {
+        return this.addDecoratedText(text, { $type: 'app.bsky.richtext.facet#link', uri: uri });
     }
     /**
-     * Mentions a user in rich text
-     * @param substr Text of the mention, this is usually in the form of `@handle`
+     * Mention a user in rich text
+     * @param text Text of the mention, usually in the form of `@handle`
      * @param did Valid DID, for example: did:plc:ia76kvnndjutgedggx2ibrem
      * @returns The builder instance, for chaining
      */
-    addMention(substr, did) {
-        return this.addDecoratedText(substr, { $type: 'app.bsky.richtext.facet#mention', did: did });
+    addMention(text, did) {
+        return this.addDecoratedText(text, { $type: 'app.bsky.richtext.facet#mention', did: did });
     }
     /**
      * Add inline hashtag to the rich text
+     * @param text Text to display
      * @param tag The tag, without the pound prefix
-     * @returns THe builder instance, for chaining
+     * @returns The builder instance, for chaining
      */
-    addTag(tag) {
-        return this.addDecoratedText('#' + tag, { $type: 'app.bsky.richtext.facet#tag', tag: tag });
+    addTag(text, tag) {
+        return this.addDecoratedText(text, { $type: 'app.bsky.richtext.facet#tag', tag: tag });
     }
 }
 export default RichtextBuilder;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"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"}

package/lib/index.ts

@@ -1,5 +1,6 @@
 import type { AppBskyRichtextFacet } from '@atcute/bluesky';
 import type { Did, GenericUri } from '@atcute/lexicons';
+import { getUtf8Length } from '@atcute/uint8array';
 
 type UnwrapArray<T> = T extends (infer V)[] ? V : never;
 
@@ -8,8 +9,6 @@ export type Facet = AppBskyRichtextFacet.Main;
 /** Feature union type from Facet['features'] */
 export type FacetFeature = UnwrapArray<Facet['features']>;
 
-const encoder = new TextEncoder();
-
 /** Resulting rich text */
 export interface BakedRichtext {
 	text: string;
@@ -65,74 +64,77 @@ class RichtextBuilder {
 
 	/**
 	 * Add plain text to the rich text
-	 * @param substr The plain text
+	 * @param text The plain text
 	 * @returns The builder instance, for chaining
 	 */
-	addText(substr: string): this {
+	addText(text: string): this {
 		const segments = this.#segments;
-		segments[segments.length - 1] += substr;
+		segments[segments.length - 1] += text;
 
 		return this;
 	}
 
 	/**
 	 * Add decorated text to the rich text
-	 * @param substr The text itself
+	 * @param text The text itself
 	 * @param feature Feature to imbue on the text
 	 * @returns The builder instance, for chaining
 	 */
-	addDecoratedText(substr: string, feature: FacetFeature): this {
+	addDecoratedText(text: string, feature: FacetFeature): this {
 		const segments = this.#segments;
 		const last = segments.length - 1;
 
 		// Calculate the starting index
 		let start = 0;
 
-		start += encoder.encode(segments[last] as string).byteLength;
+		start += getUtf8Length(segments[last] as string);
 		if (last !== 0) {
 			start += (segments[last - 1] as Facet).index.byteEnd;
 		}
 
+		const byteLength = getUtf8Length(text);
+
 		const facet: Facet = {
 			index: {
 				byteStart: start,
-				byteEnd: start + encoder.encode(substr).byteLength,
+				byteEnd: start + byteLength,
 			},
 			features: [feature],
 		};
 
-		segments[last] += substr;
+		segments[last] += text;
 		segments.push(facet, '');
 		return this;
 	}
 
 	/**
 	 * Add link to the rich text
-	 * @param substr Text of the link
+	 * @param text Text of the link
 	 * @param uri Valid URL, for example: https://example.com
 	 * @returns The builder instance, for chaining
 	 */
-	addLink(substr: string, uri: GenericUri): this {
-		return this.addDecoratedText(substr, { $type: 'app.bsky.richtext.facet#link', uri: uri });
+	addLink(text: string, uri: GenericUri): this {
+		return this.addDecoratedText(text, { $type: 'app.bsky.richtext.facet#link', uri: uri });
 	}
 
 	/**
-	 * Mentions a user in rich text
-	 * @param substr Text of the mention, this is usually in the form of `@handle`
+	 * Mention a user in rich text
+	 * @param text Text of the mention, usually in the form of `@handle`
 	 * @param did Valid DID, for example: did:plc:ia76kvnndjutgedggx2ibrem
 	 * @returns The builder instance, for chaining
 	 */
-	addMention(substr: string, did: Did): this {
-		return this.addDecoratedText(substr, { $type: 'app.bsky.richtext.facet#mention', did: did });
+	addMention(text: string, did: Did): this {
+		return this.addDecoratedText(text, { $type: 'app.bsky.richtext.facet#mention', did: did });
 	}
 
 	/**
 	 * Add inline hashtag to the rich text
+	 * @param text Text to display
 	 * @param tag The tag, without the pound prefix
-	 * @returns THe builder instance, for chaining
+	 * @returns The builder instance, for chaining
 	 */
-	addTag(tag: string): this {
-		return this.addDecoratedText('#' + tag, { $type: 'app.bsky.richtext.facet#tag', tag: tag });
+	addTag(text: string, tag: string): this {
+		return this.addDecoratedText(text, { $type: 'app.bsky.richtext.facet#tag', tag: tag });
 	}
 }
 

package/package.json

@@ -1,7 +1,6 @@
 {
-  "type": "module",
   "name": "@atcute/bluesky-richtext-builder",
-  "version": "2.0.4",
+  "version": "3.0.0",
   "description": "builder pattern for Bluesky's rich text facets",
   "license": "0BSD",
   "repository": {
@@ -14,20 +13,21 @@
     "!lib/**/*.bench.ts",
     "!lib/**/*.test.ts"
   ],
+  "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": "./dist/index.js"
   },
-  "sideEffects": false,
-  "dependencies": {
-    "@atcute/bluesky": "^3.2.5",
-    "@atcute/lexicons": "^1.2.2"
+  "publishConfig": {
+    "access": "public"
   },
-  "devDependencies": {
-    "@types/bun": "^1.2.21"
+  "dependencies": {
+    "@atcute/bluesky": "^3.2.21",
+    "@atcute/lexicons": "^1.2.9",
+    "@atcute/uint8array": "^1.1.1"
   },
   "scripts": {
-    "build": "tsc --project tsconfig.build.json",
-    "test": "bun test --coverage",
+    "build": "tsgo --project tsconfig.build.json",
     "prepublish": "rm -rf dist; pnpm run build"
   }
 }