@ewanc26/atproto 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# @ewanc26/atproto
+
+AT Protocol service layer extracted from [ewancroft.uk](https://ewancroft.uk). Handles identity resolution, record fetching, Bluesky posts, Standard.site documents, music/mood status, and more — with a built-in in-memory cache.
+
+**Key difference from the app's internal service layer:** all functions accept `did: string` as their first argument rather than reading `PUBLIC_ATPROTO_DID` from the environment.
+
+## Installation
+
+```bash
+pnpm add @ewanc26/atproto
+```
+
+Requires `@atproto/api >= 0.13.0` as a peer dependency.
+
+## What's Exported
+
+### Fetch Functions
+
+| Function | Description |
+|----------|-------------|
+| `fetchProfile(did)` | Bluesky profile including pronouns |
+| `fetchSiteInfo(did)` | `uk.ewancroft.site.info` record |
+| `fetchLinks(did)` | `blue.linkat.board` link cards |
+| `fetchMusicStatus(did)` | teal.fm music status with cascading artwork lookup |
+| `fetchKibunStatus(did)` | kibun.social mood status |
+| `fetchTangledRepos(did)` | Tangled code repositories |
+| `fetchPublications(did)` | Standard.site publications |
+| `fetchDocuments(did, pubRkey)` | Standard.site documents for a publication |
+| `fetchBlogPosts(did, pubRkey)` | Blog posts for a publication |
+| `fetchRecentDocuments(did, limit)` | Most recent documents across all publications |
+| `fetchLatestBlueskyPost(did)` | Latest non-reply Bluesky post with thread context |
+| `fetchPostFromUri(did, uri)` | Single Bluesky post by AT URI |
+| `fetchAllEngagement(uris)` | Like/repost counts via Constellation API |
+
+### Agents & Identity
+
+```typescript
+import { resolveIdentity, getPublicAgent, getPDSAgent, createAgent, withFallback, resetAgents } from '@ewanc26/atproto';
+```
+
+### Pagination
+
+```typescript
+import { fetchAllRecords, fetchAllUserRecords } from '@ewanc26/atproto';
+```
+
+### Cache
+
+```typescript
+import { cache, ATProtoCache, CACHE_TTL } from '@ewanc26/atproto';
+
+cache.clear();
+cache.delete('profile:did:plc:…');
+```
+
+### Music Artwork
+
+```typescript
+import { findArtwork, searchMusicBrainzRelease, buildCoverArtUrl } from '@ewanc26/atproto';
+// Cascading: MusicBrainz → iTunes → Deezer → Last.fm → PDS blob
+```
+
+### Media
+
+```typescript
+import { buildPdsBlobUrl, extractCidFromImageObject, extractImageUrlsFromValue } from '@ewanc26/atproto';
+```
+
+### Types
+
+All interfaces (`ProfileData`, `BlueskyPost`, `BlogPost`, `MusicStatusData`, `KibunStatusData`, `TangledRepo`, `StandardSiteDocument`, `StandardSitePublication`, `SiteInfoData`, `LinkData`, `ResolvedIdentity`, …) are exported from the package root.
+
+## Build
+
+```bash
+pnpm build   # tsc
+pnpm dev     # tsc --watch
+pnpm check   # tsc --noEmit
+```
+
+## Licence
+
+See the root [LICENSE](../../LICENSE).

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@ewanc26/atproto",
+  "version": "0.1.0",
+  "description": "AT Protocol service layer extracted from ewancroft.uk",
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": { "access": "public" },
+  "files": ["dist", "src"],
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "dev": "tsc --project tsconfig.json --watch",
+    "check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@atproto/api": ">=0.13.0"
+  },
+  "devDependencies": {
+    "@atproto/api": "^0.18.1",
+    "typescript": "^5.9.3"
+  }
+}

package/src/agents.ts

@@ -0,0 +1,127 @@
+import { AtpAgent } from '@atproto/api';
+import type { ResolvedIdentity } from './types.js';
+import { cache } from './cache.js';
+
+export function createAgent(service: string, fetchFn?: typeof fetch): AtpAgent {
+	const wrappedFetch = fetchFn
+		? async (url: URL | RequestInfo, init?: RequestInit) => {
+				const urlStr = url instanceof URL ? url.toString() : url;
+				const response = await fetchFn(urlStr, init);
+				const headers = new Headers(response.headers);
+				if (!headers.has('content-type')) {
+					headers.set('content-type', 'application/json');
+				}
+				return new Response(response.body, {
+					status: response.status,
+					statusText: response.statusText,
+					headers
+				});
+			}
+		: undefined;
+
+	return new AtpAgent({
+		service,
+		...(wrappedFetch && { fetch: wrappedFetch })
+	});
+}
+
+export const constellationAgent = createAgent('https://constellation.microcosm.blue');
+export const defaultAgent = createAgent('https://public.api.bsky.app');
+
+let resolvedAgent: AtpAgent | null = null;
+let pdsAgent: AtpAgent | null = null;
+
+export async function resolveIdentity(
+	did: string,
+	fetchFn?: typeof fetch
+): Promise<ResolvedIdentity> {
+	const cacheKey = `identity:${did}`;
+	const cached = cache.get<ResolvedIdentity>(cacheKey);
+	if (cached) return cached;
+
+	const _fetch = fetchFn ?? globalThis.fetch;
+	const response = await _fetch(
+		`https://slingshot.microcosm.blue/xrpc/com.bad-example.identity.resolveMiniDoc?identifier=${encodeURIComponent(did)}`
+	);
+
+	if (!response.ok) {
+		throw new Error(
+			`Failed to resolve identifier via Slingshot: ${response.status} ${response.statusText}`
+		);
+	}
+
+	const rawText = await response.text();
+	let data: any;
+	try {
+		data = JSON.parse(rawText);
+	} catch (err) {
+		throw new Error('Failed to parse identity resolver response');
+	}
+
+	if (!data.did || !data.pds) {
+		throw new Error('Invalid response from identity resolver');
+	}
+
+	cache.set(cacheKey, data);
+	return data;
+}
+
+export async function getPublicAgent(did: string, fetchFn?: typeof fetch): Promise<AtpAgent> {
+	if (resolvedAgent) return resolvedAgent;
+
+	try {
+		try {
+			const response = await constellationAgent.getProfile({ actor: did });
+			if (response.success) {
+				resolvedAgent = constellationAgent;
+				return resolvedAgent;
+			}
+		} catch {
+			// fall through
+		}
+
+		const resolved = await resolveIdentity(did, fetchFn);
+		resolvedAgent = createAgent(resolved.pds, fetchFn);
+		return resolvedAgent;
+	} catch {
+		resolvedAgent = defaultAgent;
+		return resolvedAgent;
+	}
+}
+
+export async function getPDSAgent(did: string, fetchFn?: typeof fetch): Promise<AtpAgent> {
+	if (pdsAgent) return pdsAgent;
+	const resolved = await resolveIdentity(did, fetchFn);
+	pdsAgent = createAgent(resolved.pds, fetchFn);
+	return pdsAgent;
+}
+
+export async function withFallback<T>(
+	did: string,
+	operation: (agent: AtpAgent) => Promise<T>,
+	usePDSFirst = false,
+	fetchFn?: typeof fetch
+): Promise<T> {
+	const defaultAgentFn = () =>
+		fetchFn ? createAgent('https://public.api.bsky.app', fetchFn) : Promise.resolve(defaultAgent);
+
+	const agents = usePDSFirst
+		? [() => getPDSAgent(did, fetchFn), defaultAgentFn]
+		: [defaultAgentFn, () => getPDSAgent(did, fetchFn)];
+
+	let lastError: any;
+	for (const getAgent of agents) {
+		try {
+			const agent = await getAgent();
+			return await operation(agent);
+		} catch (error) {
+			lastError = error;
+		}
+	}
+	throw lastError;
+}
+
+export function resetAgents(): void {
+	resolvedAgent = null;
+	pdsAgent = null;
+}

package/src/cache.ts

@@ -0,0 +1,63 @@
+import type { CacheEntry } from './types.js';
+
+/**
+ * Cache TTL values in milliseconds (production defaults).
+ * All functions that previously read PUBLIC_ATPROTO_DID from the environment
+ * now accept `did: string` as their first argument.
+ */
+export const CACHE_TTL = {
+	PROFILE: 60 * 60 * 1000,
+	SITE_INFO: 120 * 60 * 1000,
+	LINKS: 60 * 60 * 1000,
+	MUSIC_STATUS: 10 * 60 * 1000,
+	KIBUN_STATUS: 15 * 60 * 1000,
+	TANGLED_REPOS: 60 * 60 * 1000,
+	BLOG_POSTS: 30 * 60 * 1000,
+	PUBLICATIONS: 60 * 60 * 1000,
+	INDIVIDUAL_POST: 60 * 60 * 1000,
+	IDENTITY: 24 * 60 * 60 * 1000
+} as const;
+
+export class ATProtoCache {
+	private cache = new Map<string, CacheEntry<any>>();
+
+	private getTTL(key: string): number {
+		if (key.startsWith('profile:')) return CACHE_TTL.PROFILE;
+		if (key.startsWith('siteinfo:')) return CACHE_TTL.SITE_INFO;
+		if (key.startsWith('links:')) return CACHE_TTL.LINKS;
+		if (key.startsWith('music-status:')) return CACHE_TTL.MUSIC_STATUS;
+		if (key.startsWith('kibun-status:')) return CACHE_TTL.KIBUN_STATUS;
+		if (key.startsWith('tangled:')) return CACHE_TTL.TANGLED_REPOS;
+		if (key.startsWith('blog-posts:') || key.startsWith('blogposts:')) return CACHE_TTL.BLOG_POSTS;
+		if (key.startsWith('publications:') || key.startsWith('standard-site:publications:'))
+			return CACHE_TTL.PUBLICATIONS;
+		if (key.startsWith('post:') || key.startsWith('blueskypost:')) return CACHE_TTL.INDIVIDUAL_POST;
+		if (key.startsWith('identity:')) return CACHE_TTL.IDENTITY;
+		return 30 * 60 * 1000;
+	}
+
+	get<T>(key: string): T | null {
+		const entry = this.cache.get(key);
+		if (!entry) return null;
+		const ttl = this.getTTL(key);
+		if (Date.now() - entry.timestamp > ttl) {
+			this.cache.delete(key);
+			return null;
+		}
+		return entry.data;
+	}
+
+	set<T>(key: string, data: T): void {
+		this.cache.set(key, { data, timestamp: Date.now() });
+	}
+
+	delete(key: string): void {
+		this.cache.delete(key);
+	}
+
+	clear(): void {
+		this.cache.clear();
+	}
+}
+
+export const cache = new ATProtoCache();

package/src/documents.ts

@@ -0,0 +1,247 @@
+import { cache } from './cache.js';
+import { withFallback, resolveIdentity } from './agents.js';
+import { buildPdsBlobUrl } from './media.js';
+import type {
+	StandardSitePublication,
+	StandardSitePublicationsData,
+	StandardSiteDocument,
+	StandardSiteDocumentsData,
+	StandardSiteBasicTheme,
+	StandardSiteThemeColor,
+	BlogPost
+} from './types.js';
+
+interface DocumentRecord {
+	site: string;
+	path?: string;
+	title: string;
+	description?: string;
+	coverImage?: unknown;
+	content?: unknown;
+	textContent?: string;
+	bskyPostRef?: { uri: string; cid: string };
+	tags?: string[];
+	publishedAt: string;
+	updatedAt?: string;
+}
+
+interface PublicationRecord {
+	url: string;
+	name: string;
+	description?: string;
+	icon?: unknown;
+	basicTheme?: {
+		background: StandardSiteThemeColor;
+		foreground: StandardSiteThemeColor;
+		accent: StandardSiteThemeColor;
+		accentForeground: StandardSiteThemeColor;
+	};
+	preferences?: { showInDiscover?: boolean };
+}
+
+async function getBlobUrl(
+	did: string,
+	blob: any,
+	fetchFn?: typeof fetch
+): Promise<string | undefined> {
+	try {
+		const cid = blob.ref?.$link || blob.cid;
+		if (!cid) return undefined;
+		const resolved = await resolveIdentity(did, fetchFn);
+		return buildPdsBlobUrl(resolved.pds, did, cid);
+	} catch {
+		return undefined;
+	}
+}
+
+function resolveViewUrl(
+	site: string,
+	path: string | undefined,
+	publicationUrl: string | undefined,
+	rkey: string
+): string {
+	const docPath = path || `/${rkey}`;
+	const normalizedPath = docPath.startsWith('/') ? docPath : `/${docPath}`;
+
+	if (site.startsWith('at://')) {
+		if (!publicationUrl) return `${site}${normalizedPath}`;
+		const baseUrl = publicationUrl.startsWith('http') ? publicationUrl : `https://${publicationUrl}`;
+		return `${baseUrl.replace(/\/$/, '')}${normalizedPath}`;
+	} else {
+		const baseUrl = site.startsWith('http') ? site : `https://${site}`;
+		return `${baseUrl.replace(/\/$/, '')}${normalizedPath}`;
+	}
+}
+
+export async function fetchPublications(
+	did: string,
+	fetchFn?: typeof fetch
+): Promise<StandardSitePublicationsData> {
+	const cacheKey = `standard-site:publications:${did}`;
+	const cached = cache.get<StandardSitePublicationsData>(cacheKey);
+	if (cached) return cached;
+
+	const publications: StandardSitePublication[] = [];
+
+	try {
+		const publicationsRecords = await withFallback(
+			did,
+			async (agent) => {
+				const response = await agent.com.atproto.repo.listRecords({
+					repo: did,
+					collection: 'site.standard.publication',
+					limit: 100
+				});
+				return response.data.records;
+			},
+			true,
+			fetchFn
+		);
+
+		for (const pubRecord of publicationsRecords) {
+			const pubValue = pubRecord.value as unknown as PublicationRecord;
+			const rkey = pubRecord.uri.split('/').pop() || '';
+
+			let basicTheme: StandardSiteBasicTheme | undefined;
+			if (pubValue.basicTheme) {
+				basicTheme = {
+					background: pubValue.basicTheme.background,
+					foreground: pubValue.basicTheme.foreground,
+					accent: pubValue.basicTheme.accent,
+					accentForeground: pubValue.basicTheme.accentForeground
+				};
+			}
+
+			publications.push({
+				name: pubValue.name,
+				rkey,
+				uri: pubRecord.uri,
+				url: pubValue.url,
+				description: pubValue.description,
+				icon: pubValue.icon ? await getBlobUrl(did, pubValue.icon, fetchFn) : undefined,
+				basicTheme,
+				preferences: pubValue.preferences
+			});
+		}
+
+		const data: StandardSitePublicationsData = { publications };
+		cache.set(cacheKey, data);
+		return data;
+	} catch {
+		return { publications: [] };
+	}
+}
+
+export async function fetchDocuments(
+	did: string,
+	fetchFn?: typeof fetch
+): Promise<StandardSiteDocumentsData> {
+	const cacheKey = `standard-site:documents:${did}`;
+	const cached = cache.get<StandardSiteDocumentsData>(cacheKey);
+	if (cached) return cached;
+
+	const documents: StandardSiteDocument[] = [];
+
+	try {
+		const publicationsData = await fetchPublications(did, fetchFn);
+		const publicationsMap = new Map<string, StandardSitePublication>();
+		for (const pub of publicationsData.publications) {
+			publicationsMap.set(pub.uri, pub);
+		}
+
+		const documentsRecords = await withFallback(
+			did,
+			async (agent) => {
+				const response = await agent.com.atproto.repo.listRecords({
+					repo: did,
+					collection: 'site.standard.document',
+					limit: 100
+				});
+				return response.data.records;
+			},
+			true,
+			fetchFn
+		);
+
+		for (const docRecord of documentsRecords) {
+			const docValue = docRecord.value as unknown as DocumentRecord;
+			const rkey = docRecord.uri.split('/').pop() || '';
+
+			const site = docValue.site;
+			let publication: StandardSitePublication | undefined;
+			let publicationRkey: string | undefined;
+			let pubUrl: string | undefined;
+
+			if (site.startsWith('at://')) {
+				publication = publicationsMap.get(site);
+				publicationRkey = site.split('/').pop();
+				pubUrl = publication?.url;
+			} else {
+				pubUrl = site;
+			}
+
+			const url = resolveViewUrl(site, docValue.path, pubUrl, rkey);
+			const coverImage = docValue.coverImage
+				? await getBlobUrl(did, docValue.coverImage, fetchFn)
+				: undefined;
+
+			documents.push({
+				title: docValue.title,
+				rkey,
+				uri: docRecord.uri,
+				url,
+				site,
+				path: docValue.path,
+				description: docValue.description,
+				coverImage,
+				content: docValue.content,
+				textContent: docValue.textContent,
+				bskyPostRef: docValue.bskyPostRef,
+				tags: docValue.tags,
+				publishedAt: docValue.publishedAt,
+				updatedAt: docValue.updatedAt,
+				publicationName: publication?.name,
+				publicationRkey
+			});
+		}
+
+		documents.sort((a, b) => new Date(b.publishedAt).getTime() - new Date(a.publishedAt).getTime());
+
+		const data: StandardSiteDocumentsData = { documents };
+		cache.set(cacheKey, data);
+		return data;
+	} catch {
+		return { documents: [] };
+	}
+}
+
+export async function fetchRecentDocuments(
+	did: string,
+	limit = 5,
+	fetchFn?: typeof fetch
+): Promise<StandardSiteDocument[]> {
+	const { documents } = await fetchDocuments(did, fetchFn);
+	return documents.slice(0, limit);
+}
+
+export async function fetchBlogPosts(
+	did: string,
+	fetchFn?: typeof fetch
+): Promise<{ posts: BlogPost[] }> {
+	const { documents } = await fetchDocuments(did, fetchFn);
+	const posts: BlogPost[] = documents.map((doc) => ({
+		title: doc.title,
+		url: doc.url,
+		createdAt: doc.publishedAt,
+		platform: 'standard.site' as const,
+		description: doc.description,
+		rkey: doc.rkey,
+		publicationName: doc.publicationName,
+		publicationRkey: doc.publicationRkey,
+		tags: doc.tags,
+		coverImage: doc.coverImage,
+		textContent: doc.textContent,
+		updatedAt: doc.updatedAt
+	}));
+	return { posts };
+}

package/src/engagement.ts

@@ -0,0 +1,56 @@
+import { cache } from './cache.js';
+
+export type EngagementType = 'app.bsky.feed.like' | 'app.bsky.feed.repost';
+
+interface EngagementResponse {
+	dids: string[];
+	cursor?: string;
+}
+
+export async function fetchEngagementFromConstellation(
+	uri: string,
+	type: EngagementType,
+	cursor?: string
+): Promise<EngagementResponse> {
+	const cacheKey = `engagement:${type}:${uri}:${cursor || 'initial'}`;
+	const cached = cache.get<EngagementResponse>(cacheKey);
+	if (cached) return cached;
+
+	const url = new URL('https://constellation.microcosm.blue/links/distinct-dids');
+	url.searchParams.append('target', uri);
+	url.searchParams.append('collection', type);
+	url.searchParams.append('path', '');
+	url.searchParams.append('limit', '100');
+	if (cursor) url.searchParams.append('cursor', cursor);
+
+	const response = await fetch(url);
+	if (!response.ok) {
+		throw new Error(`Constellation HTTP error! Status: ${response.status}`);
+	}
+
+	const data = await response.json();
+	const result: EngagementResponse = {
+		dids: data.dids || [],
+		cursor: data.cursor
+	};
+
+	cache.set(cacheKey, result);
+	return result;
+}
+
+export async function fetchAllEngagement(uri: string, type: EngagementType): Promise<string[]> {
+	const allDids: Set<string> = new Set();
+	let cursor: string | undefined = undefined;
+
+	try {
+		do {
+			const response = await fetchEngagementFromConstellation(uri, type, cursor);
+			response.dids.forEach((did) => allDids.add(did));
+			cursor = response.cursor;
+		} while (cursor);
+	} catch {
+		// return what we have
+	}
+
+	return Array.from(allDids);
+}