@atcute/bluesky-threading 2.0.1 → 3.0.0

package/dist/cbor.js

@@ -1,12 +1,12 @@
 import { encode } from '@atcute/cbor';
-import { create, format } from '@atcute/cid';
+import { create, toString } from '@atcute/cid';
 // Sanity-check by requiring a $type here, this is because the records are
 // expected to be encoded with it, even though the PDS accepts record writes
 // without the field.
 export async function serializeRecordCid(record) {
     const bytes = encode(record);
     const cid = await create(0x71, bytes);
-    const serialized = format(cid);
+    const serialized = toString(cid);
     return serialized;
 }
 //# sourceMappingURL=cbor.js.map

package/dist/cbor.js.map

@@ -1 +1 @@
-{"version":3,"file":"cbor.js","sourceRoot":"","sources":["../lib/cbor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE7C,0EAA0E;AAC1E,4EAA4E;AAC5E,qBAAqB;AACrB,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,MAAyB;IACjE,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAE7B,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACtC,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAE/B,OAAO,UAAU,CAAC;AACnB,CAAC"}
+{"version":3,"file":"cbor.js","sourceRoot":"","sources":["../lib/cbor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE/C,0EAA0E;AAC1E,4EAA4E;AAC5E,qBAAqB;AACrB,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,MAAyB;IACjE,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAE7B,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACtC,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IAEjC,OAAO,UAAU,CAAC;AACnB,CAAC"}

package/lib/cbor.ts

@@ -0,0 +1,14 @@
+import { encode } from '@atcute/cbor';
+import { create, toString } from '@atcute/cid';
+
+// Sanity-check by requiring a $type here, this is because the records are
+// expected to be encoded with it, even though the PDS accepts record writes
+// without the field.
+export async function serializeRecordCid(record: { $type: string }): Promise<string> {
+	const bytes = encode(record);
+
+	const cid = await create(0x71, bytes);
+	const serialized = toString(cid);
+
+	return serialized;
+}

package/lib/index.ts

@@ -0,0 +1,417 @@
+import '@atcute/bluesky/lexicons';
+
+import { XRPCError, type XRPC } from '@atcute/client';
+import type {
+	AppBskyEmbedExternal,
+	AppBskyEmbedImages,
+	AppBskyEmbedRecord,
+	AppBskyEmbedVideo,
+	AppBskyFeedDefs,
+	AppBskyFeedPost,
+	AppBskyFeedThreadgate,
+	At,
+	Brand,
+	ComAtprotoLabelDefs,
+	ComAtprotoRepoApplyWrites,
+	ComAtprotoRepoStrongRef,
+} from '@atcute/client/lexicons';
+import * as TID from '@atcute/tid';
+
+import { serializeRecordCid } from './cbor.js';
+import { getNow } from './time.js';
+
+import type {
+	ComposedThread,
+	ComposedThreadgate,
+	PostEmbed,
+	PostMediaEmbed,
+	PostRecordEmbed,
+} from './types.js';
+
+export type * from './types.js';
+
+/**
+ * Create post records and publish them
+ * @param rpc An authenticated Bluesky RPC client
+ * @param thread Composed thread
+ * @returns An array of post records that were published
+ */
+export async function publishThread(
+	rpc: XRPC,
+	thread: Omit<ComposedThread, 'rpc'>,
+): Promise<Brand.Union<ComAtprotoRepoApplyWrites.Create>[]> {
+	const records = await createThread({ ...thread, rpc });
+
+	await rpc.call('com.atproto.repo.applyWrites', {
+		signal: thread.signal,
+		data: {
+			repo: thread.author,
+			writes: records,
+		},
+	});
+
+	return records;
+}
+
+/**
+ * Create post records without publishing, allows you to do it yourself.
+ * @param thread Composed thread
+ * @returns An array of post records
+ */
+export async function createThread(
+	thread: ComposedThread,
+): Promise<Brand.Union<ComAtprotoRepoApplyWrites.Create>[]> {
+	const rpc = thread.rpc;
+	const signal = thread.signal;
+
+	const did = thread.author;
+	const posts = thread.posts;
+	const threadgate = thread.gate;
+	const languages = thread.languages;
+
+	const writes: Brand.Union<ComAtprotoRepoApplyWrites.Create>[] = [];
+
+	const now = thread.createdAt !== undefined ? new Date(thread.createdAt) : new Date(getNow(posts.length));
+	assert(!Number.isNaN(now.getTime()), `provided createdAt value is invalid`);
+
+	let reply: AppBskyFeedPost.ReplyRef | undefined;
+	let rkey: string | undefined;
+
+	if (thread.reply) {
+		let post = thread.reply;
+
+		if (typeof post === 'string') {
+			// AT-URI being passed
+			assertXrpc(rpc, `ComposedThread.reply`);
+			post = await getPost(post);
+		}
+
+		let root: ComAtprotoRepoStrongRef.Main | undefined;
+		let ref: ComAtprotoRepoStrongRef.Main;
+
+		if ('record' in post) {
+			// AppBskyFeedDefs.PostView being passed
+
+			root = (post.record as AppBskyFeedPost.Record).reply?.root;
+			ref = { uri: post.uri, cid: post.cid };
+		} else if ('value' in post) {
+			// AppBskyEmbedRecord.ViewRecord being passed
+
+			root = (post.value as AppBskyFeedPost.Record).reply?.root;
+			ref = { uri: post.uri, cid: post.cid };
+		} else {
+			assert(false, `Unexpected end of code`);
+		}
+
+		reply = {
+			root: root ? { uri: root.uri, cid: root.cid } : ref,
+			parent: ref,
+		};
+	}
+
+	assert(!reply || !threadgate, `threadgate and reply are mutually exclusive`);
+
+	for (let idx = 0, len = posts.length; idx < len; idx++) {
+		// Get the record key for this post
+		rkey = TID.createRaw(now.getTime(), Math.floor(Math.random() * 1023));
+
+		const post = posts[idx];
+		const uri = `at://${did}/app.bsky.feed.post/${rkey}`;
+
+		// Resolve embeds
+		let embed: AppBskyFeedPost.Record['embed'];
+		if (post.embed !== undefined) {
+			embed = await resolveEmbed(post.embed);
+		}
+
+		// Get the self-labels
+		const labels = getEmbedLabels(post.embed);
+		let selfLabels: Brand.Union<ComAtprotoLabelDefs.SelfLabels> | undefined;
+
+		if (labels?.length) {
+			selfLabels = {
+				$type: 'com.atproto.label.defs#selfLabels',
+				values: labels.map((val) => ({ val })),
+			};
+		}
+
+		// Now form the record
+		const content = post.content;
+
+		const record: AppBskyFeedPost.Record = {
+			$type: 'app.bsky.feed.post',
+			createdAt: now.toISOString(),
+			text: content.text,
+			facets: content.facets,
+			reply: reply,
+			embed: embed,
+			langs: post.languages ?? languages,
+			labels: selfLabels,
+		};
+
+		writes.push({
+			$type: 'com.atproto.repo.applyWrites#create',
+			collection: 'app.bsky.feed.post',
+			rkey: rkey,
+			value: record,
+		});
+
+		// If this is the first post, and we have a threadgate set, create one now.
+		if (idx === 0 && threadgate) {
+			const threadgateRecord: AppBskyFeedThreadgate.Record = {
+				$type: 'app.bsky.feed.threadgate',
+				createdAt: now.toISOString(),
+				post: uri,
+				allow: resolveThreadgate(threadgate),
+			};
+
+			writes.push({
+				$type: 'com.atproto.repo.applyWrites#create',
+				collection: 'app.bsky.feed.threadgate',
+				rkey: rkey,
+				value: threadgateRecord,
+			});
+		}
+
+		if (idx !== len - 1) {
+			// Retrieve the next reply reference
+			const serialized = await serializeRecordCid(record);
+
+			const ref: ComAtprotoRepoStrongRef.Main = {
+				cid: serialized,
+				uri: uri,
+			};
+
+			reply = {
+				root: reply ? reply.root : ref,
+				parent: ref,
+			};
+
+			// Posts are not guaranteed to be shown in the correct order if they are
+			// all posted with the same timestamp.
+			now.setMilliseconds(now.getMilliseconds() + 1);
+		}
+	}
+
+	return writes;
+
+	async function resolveEmbed(embed: PostEmbed): Promise<AppBskyFeedPost.Record['embed'] | undefined> {
+		const { media, record } = embed;
+
+		if (media && record) {
+			return {
+				$type: 'app.bsky.embed.recordWithMedia',
+				media: await resolveMediaEmbed(media),
+				record: await resolveRecordEmbed(record),
+			};
+		} else if (media) {
+			return resolveMediaEmbed(media);
+		} else if (record) {
+			return resolveRecordEmbed(record);
+		}
+
+		return;
+
+		async function resolveMediaEmbed(
+			embed: PostMediaEmbed,
+		): Promise<Brand.Union<AppBskyEmbedExternal.Main | AppBskyEmbedImages.Main | AppBskyEmbedVideo.Main>> {
+			const type = embed.type;
+
+			if (type === 'external') {
+				const rawThumb = embed.thumbnail;
+				let thumb: At.Blob<any> | undefined;
+
+				if (rawThumb !== undefined) {
+					if (rawThumb instanceof Blob) {
+						assertXrpc(rpc, `PostExternalEmbed.thumbnail`);
+						thumb = await uploadBlob(rawThumb);
+					} else {
+						thumb = rawThumb;
+					}
+				}
+
+				return {
+					$type: 'app.bsky.embed.external',
+					external: {
+						uri: embed.uri,
+						title: embed.title,
+						description: embed.description ?? '',
+						thumb: thumb,
+					},
+				};
+			}
+
+			if (type === 'image') {
+				const images: AppBskyEmbedImages.Image[] = [];
+
+				for (const image of embed.images) {
+					const aspectRatio = image.aspectRatio;
+					const rawBlob = image.blob;
+					let blob: At.Blob<any>;
+
+					if (rawBlob instanceof Blob) {
+						assertXrpc(rpc, `PostImageEmbed.images[].blob`);
+						blob = await uploadBlob(rawBlob);
+					} else {
+						blob = rawBlob;
+					}
+
+					images.push({
+						image: blob,
+						alt: image.alt ?? '',
+						aspectRatio: aspectRatio ? { width: aspectRatio.width, height: aspectRatio.height } : undefined,
+					});
+				}
+
+				return {
+					$type: 'app.bsky.embed.images',
+					images: images,
+				};
+			}
+
+			if (type === 'video') {
+				const aspectRatio = embed.aspectRatio;
+				const rawBlob = embed.blob;
+				let blob: At.Blob<any> | undefined;
+
+				if (rawBlob instanceof Blob) {
+					assertXrpc(rpc, `PostVideoEmbed.blob`);
+					blob = await uploadBlob(rawBlob);
+				} else {
+					blob = rawBlob;
+				}
+
+				return {
+					$type: 'app.bsky.embed.video',
+					video: blob,
+					alt: embed.alt ?? '',
+					aspectRatio: aspectRatio ? { width: aspectRatio.width, height: aspectRatio.height } : undefined,
+				};
+			}
+
+			assert(false, `Unexpected end of code`);
+		}
+
+		async function resolveRecordEmbed(embed: PostRecordEmbed): Promise<Brand.Union<AppBskyEmbedRecord.Main>> {
+			const uri = embed.uri;
+			let cid = embed.cid;
+
+			if (cid === undefined) {
+				const type = embed.type;
+
+				if (type === 'quote') {
+					assertXrpc(rpc, 'PostQuoteEmbed');
+
+					const post = await getPost(uri);
+
+					cid = post.cid;
+				} else if (type === 'feed') {
+					assertXrpc(rpc, 'PostFeedEmbed');
+
+					const { data } = await rpc.get('app.bsky.feed.getFeedGenerator', {
+						signal: signal,
+						params: { feed: uri },
+					});
+
+					cid = data.view.cid;
+				} else if (type === 'list') {
+					assertXrpc(rpc, 'PostListEmbed');
+
+					const { data } = await rpc.get('app.bsky.graph.getList', {
+						signal: signal,
+						params: { list: uri, limit: 1 },
+					});
+
+					cid = data.list.cid;
+				} else if (type === 'starterpack') {
+					assertXrpc(rpc, 'PostStarterpackEmbed');
+
+					const { data } = await rpc.get('app.bsky.graph.getStarterPack', {
+						signal: signal,
+						params: { starterPack: uri },
+					});
+
+					cid = data.starterPack.cid;
+				} else {
+					assert(false, `Unexpected end of code`);
+				}
+			}
+
+			return {
+				$type: 'app.bsky.embed.record',
+				record: {
+					uri: uri,
+					cid: cid,
+				},
+			};
+		}
+	}
+
+	async function uploadBlob(blob: Blob): Promise<At.Blob> {
+		// `rpc` intentionally non-null asserted.
+		const { data } = await rpc!.call('com.atproto.repo.uploadBlob', {
+			signal: signal,
+			data: blob,
+		});
+
+		return data.blob;
+	}
+
+	async function getPost(uri: string): Promise<AppBskyFeedDefs.PostView> {
+		// `rpc` intentionally non-null asserted.
+		const { data } = await rpc!.get('app.bsky.feed.getPosts', {
+			signal: signal,
+			params: {
+				uris: [uri],
+			},
+		});
+
+		const post = data.posts[0];
+		if (!post) {
+			throw new XRPCError(400, { kind: 'NotFound', description: `Post not found: ${uri}` });
+		}
+
+		return post;
+	}
+}
+
+function resolveThreadgate(gate: ComposedThreadgate): AppBskyFeedThreadgate.Record['allow'] {
+	const rules: AppBskyFeedThreadgate.Record['allow'] = [];
+
+	if (gate.follows) {
+		rules.push({ $type: 'app.bsky.feed.threadgate#followingRule' });
+	}
+	if (gate.mentions) {
+		rules.push({ $type: 'app.bsky.feed.threadgate#mentionRule' });
+	}
+
+	for (const listUri of gate.listUris ?? []) {
+		rules.push({ $type: 'app.bsky.feed.threadgate#listRule', list: listUri });
+	}
+
+	return rules;
+}
+
+function getEmbedLabels(embed: PostEmbed | undefined): string[] | undefined {
+	const media = embed?.media;
+
+	if (media !== undefined) {
+		const type = media.type;
+
+		if (type === 'image' || type === 'external') {
+			return media.labels;
+		}
+	}
+}
+
+function assert(condition: boolean, message: string): asserts condition {
+	if (!condition) {
+		throw new Error(message);
+	}
+}
+
+function assertXrpc(rpc: XRPC | undefined, thing: string): asserts rpc {
+	if (rpc === undefined) {
+		throw new Error(`${thing} requires supplying RPC instance`);
+	}
+}

package/lib/time.ts

@@ -0,0 +1,13 @@
+let lastTimestamp: number = 0;
+
+/**
+ * Return the current time, make sure that each call never returns same value
+ * so that posts sent at the same time from different accounts don't end up
+ * colliding with each other potentially causing them to not be shown.
+ */
+export function getNow(threadSize: number): number {
+	let timestamp = Math.max(Date.now(), lastTimestamp);
+	lastTimestamp = timestamp + 2 + threadSize;
+
+	return timestamp;
+}

package/lib/types.ts

@@ -0,0 +1,202 @@
+import type { XRPC } from '@atcute/client';
+import type { AppBskyEmbedRecord, AppBskyFeedDefs, AppBskyRichtextFacet, At } from '@atcute/client/lexicons';
+
+/** Interface containing aspect ratio of the media */
+export interface MediaAspectRatio {
+	/** Media width */
+	width: number;
+	/** Media height */
+	height: number;
+}
+
+/** An embed that links to an external page */
+export interface PostExternalEmbed {
+	type: 'external';
+	/** Link to the page */
+	uri: string;
+	/** Page title */
+	title: string;
+	/** Page description */
+	description?: string;
+	/**
+	 * Page thumbnail, accepts either a Web Blob instance or a blob returned from
+	 * the `com.atproto.repo.uploadBlob` procedure. Supplying the former requires
+	 * you to also supply an authenticated RPC instance for it to be able to make
+	 * procedure calls.
+	 */
+	thumbnail?: Blob | At.Blob;
+	/** Labels to describe this external embed */
+	labels?: string[];
+}
+
+/** An image within the image embed */
+export interface ComposedImage {
+	/**
+	 * The image data, accepts either a Web Blob instance or a blob returned from
+	 * the `com.atproto.repo.uploadBlob` procedure. Supplying the former requires
+	 * you to also supply an authenticated RPC instance for it to be able to make
+	 * procedure calls.
+	 */
+	blob: Blob | At.Blob;
+	/**
+	 * Alternative text for this image, helps describe images for low-vision users
+	 * and provide context for everyone.
+	 */
+	alt?: string;
+	/**
+	 * Aspect ratio of the image, supplying this is recommended as clients makes
+	 * use of it to properly display images.
+	 */
+	aspectRatio?: MediaAspectRatio;
+}
+
+/** An embed that displays images */
+export interface PostImageEmbed {
+	type: 'image';
+	/** An array of images */
+	images: ComposedImage[];
+	/** Labels to describe this image embed */
+	labels?: string[];
+}
+
+/** An embed that displays a video */
+export interface PostVideoEmbed {
+	type: 'video';
+	/**
+	 * The video data, accepts either a Web Blob instance or a blob returned from
+	 * the `com.atproto.repo.uploadBlob` procedure. Supplying the former requires
+	 * you to also supply an authenticated RPC instance for it to be able to make
+	 * procedure calls.
+	 */
+	blob: Blob | At.Blob;
+	/**
+	 * Alternative text for this video, helps describe video for low-vision users
+	 * and provide context for everyone.
+	 */
+	alt?: string;
+	/**
+	 * Aspect ratio of the video, supplying this is recommended as clients makes
+	 * use of it to properly display the video.
+	 */
+	aspectRatio?: MediaAspectRatio;
+	/**
+	 * Labels to describe this video embed
+	 */
+	labels?: string[];
+}
+
+/** Union type of media embeds */
+export type PostMediaEmbed = PostExternalEmbed | PostImageEmbed | PostVideoEmbed;
+
+/** An embed that displays a feed card */
+export interface PostFeedEmbed {
+	type: 'feed';
+	/** AT-URI of the feed */
+	uri: At.Uri;
+	/**
+	 * CID of the feed, if not supplied, requires you to also supply an RPC
+	 * instance for it to be able to make query calls.
+	 */
+	cid?: string;
+}
+
+/** An embed that displays a user/moderation list card */
+export interface PostListEmbed {
+	type: 'list';
+	/** AT-URI of the list */
+	uri: string;
+	/**
+	 * CID of the list, if not supplied, requires you to also supply an RPC
+	 * instance for it to be able to make query calls.
+	 */
+	cid?: string;
+}
+
+/** An embed that displays a post card (quote post/repost with quote) */
+export interface PostQuoteEmbed {
+	type: 'quote';
+	/** AT-URI of the post */
+	uri: string;
+	/**
+	 * CID of the post, if not supplied, requires you to also supply an RPC
+	 * instance for it to be able to make query calls.
+	 */
+	cid?: string;
+}
+
+/** An embed that displays a starter pack card */
+export interface PostStarterpackEmbed {
+	type: 'starterpack';
+	/** AT-URI of the post */
+	uri: string;
+	/**
+	 * CID of the starter pack, if not supplied, requires you to also supply an
+	 * RPC instance for it to be able to make query calls.
+	 */
+	cid?: string;
+}
+
+/** Union type of "record" embeds */
+export type PostRecordEmbed = PostFeedEmbed | PostListEmbed | PostQuoteEmbed | PostStarterpackEmbed;
+
+/** Embed in a post, can contain media and links to other records */
+export interface PostEmbed {
+	media?: PostMediaEmbed;
+	record?: PostRecordEmbed;
+}
+
+/** The post being composed */
+export interface ComposedPost {
+	/** The language that this post is in */
+	languages?: string[];
+	/** The content of the post */
+	content: {
+		/** Post text */
+		text: string;
+		/** Decorations applied to the text */
+		facets?: AppBskyRichtextFacet.Main[];
+	};
+	/** Embed assigned to this post */
+	embed?: PostEmbed;
+}
+
+/** Reply gating options, leave this empty to deny everyone from replying */
+export interface ComposedThreadgate {
+	/** Allow replies from users you follow */
+	follows?: boolean;
+	/** Allow replies from users mentioned in the post */
+	mentions?: boolean;
+	/** Allow replies from users that are in these user lists */
+	listUris?: At.Uri[];
+}
+
+/** Base interface for the thread being composed */
+export interface ComposedThread {
+	/** An RPC instance, necessary for some options that takes action on your behalf */
+	rpc?: XRPC;
+	/** Abort signal */
+	signal?: AbortSignal;
+	/** Author of the thread */
+	author: At.DID;
+	/**
+	 * The "creation time" for this thread,
+	 * if not supplied, the current time is used
+	 */
+	createdAt?: string | number | Date;
+	/**
+	 * The post it should reply to, accepts either an AT-URI of the post, a view
+	 * of the post, or an embed view of the post. Supplying an AT-URI requires you
+	 * to also supply an PRC instance for it to be able to make query calls.
+	 */
+	reply?: string | AppBskyFeedDefs.PostView | AppBskyEmbedRecord.ViewRecord;
+	/**
+	 * Thread gating to apply on this thread, this option can't be set if this is
+	 * a reply, especially to another user's thread. Leave this undefined to allow
+	 * everyone to reply to the thread, supply an empty object to deny everyone.
+	 */
+	gate?: ComposedThreadgate;
+	/** The language that all the posts are in, can be overridden per-post */
+	languages?: string[];
+	/** An array of posts */
+	posts: ComposedPost[];
+}

package/package.json

@@ -1,14 +1,18 @@
 {
   "type": "module",
   "name": "@atcute/bluesky-threading",
-  "version": "2.0.1",
+  "version": "3.0.0",
   "description": "create Bluesky threads containing multiple posts with one write",
   "license": "MIT",
   "repository": {
-    "url": "https://codeberg.org/mary-ext/atcute"
+    "url": "https://github.com/mary-ext/atcute",
+    "directory": "packages/bluesky/threading"
   },
   "files": [
-    "dist/"
+    "dist/",
+    "lib/",
+    "!lib/**/*.bench.ts",
+    "!lib/**/*.test.ts"
   ],
   "exports": {
     ".": "./dist/index.js"
@@ -19,15 +23,15 @@
     "@atcute/client": "^2.0.0"
   },
   "dependencies": {
-    "@atcute/cbor": "^1.0.2",
-    "@atcute/cid": "^1.0.1",
-    "@atcute/tid": "^1.0.0"
+    "@atcute/cbor": "^2.0.0",
+    "@atcute/tid": "^1.0.1",
+    "@atcute/cid": "^2.0.0"
   },
   "devDependencies": {
-    "@types/bun": "^1.1.10",
-    "@atcute/bluesky": "^1.0.7",
-    "@atcute/client": "^2.0.3",
-    "@atcute/bluesky-richtext-builder": "^1.0.1"
+    "@types/bun": "^1.1.12",
+    "@atcute/bluesky": "^1.0.11",
+    "@atcute/bluesky-richtext-builder": "^1.0.2",
+    "@atcute/client": "^2.0.6"
   },
   "scripts": {
     "build": "tsc --project tsconfig.build.json",