···
+
import { useEffect, useState } from "react";
+
import { useDidResolution } from "./useDidResolution";
+
import { usePdsEndpoint } from "./usePdsEndpoint";
+
import { createAtprotoClient, SLINGSHOT_BASE_URL } from "../utils/atproto-client";
+
* Extended blob reference that includes CDN URL from appview responses.
+
export interface BlobWithCdn {
+
ref: { $link: string };
+
/** CDN URL from Bluesky appview (e.g., https://cdn.bsky.app/img/avatar/plain/did:plc:xxx/bafkreixxx@jpeg) */
+
* Appview getProfile response structure.
+
interface AppviewProfileResponse {
+
[key: string]: unknown;
+
* Appview getPostThread response structure.
+
interface AppviewPostThreadResponse<T = unknown> {
+
aspectRatio?: { width: number; height: number };
+
aspectRatio?: { width: number; height: number };
+
* Options for {@link useBlueskyAppview}.
+
export interface UseBlueskyAppviewOptions {
+
/** DID or handle of the actor. */
+
/** NSID collection (e.g., "app.bsky.feed.post"). */
+
/** Record key within the collection. */
+
/** Override for the Bluesky appview service URL. Defaults to public.api.bsky.app. */
+
appviewService?: string;
+
/** If true, skip the appview and go straight to Slingshot/PDS fallback. */
+
* Result returned from {@link useBlueskyAppview}.
+
export interface UseBlueskyAppviewResult<T = unknown> {
+
/** The fetched record value. */
+
/** Indicates whether a fetch is in progress. */
+
/** Error encountered during fetch. */
+
/** Source from which the record was successfully fetched. */
+
source?: "appview" | "slingshot" | "pds";
+
export const DEFAULT_APPVIEW_SERVICE = "https://public.api.bsky.app";
+
* Maps Bluesky collection NSIDs to their corresponding appview API endpoints.
+
* Only includes endpoints that can fetch individual records (not list endpoints).
+
const BLUESKY_COLLECTION_TO_ENDPOINT: Record<string, string> = {
+
"app.bsky.actor.profile": "app.bsky.actor.getProfile",
+
"app.bsky.feed.post": "app.bsky.feed.getPostThread",
+
* React hook that fetches a Bluesky record with a three-tier fallback strategy:
+
* 1. Try the Bluesky appview API endpoint (e.g., getProfile, getPostThread)
+
* 2. Fall back to Slingshot's getRecord
+
* 3. As a last resort, query the actor's PDS directly
+
* The hook automatically handles DID resolution and determines the appropriate API endpoint
+
* based on the collection type. The `source` field in the result indicates which tier
+
* successfully returned the record.
+
* // Fetch a Bluesky post with automatic fallback
+
* import { useBlueskyAppview } from 'atproto-ui';
+
* import type { FeedPostRecord } from 'atproto-ui';
+
* function MyPost({ did, rkey }: { did: string; rkey: string }) {
+
* const { record, loading, error, source } = useBlueskyAppview<FeedPostRecord>({
+
* collection: 'app.bsky.feed.post',
+
* if (loading) return <p>Loading post...</p>;
+
* if (error) return <p>Error: {error.message}</p>;
+
* if (!record) return <p>No post found</p>;
+
* <small>Fetched from: {source}</small>
+
* // Fetch a Bluesky profile
+
* import { useBlueskyAppview } from 'atproto-ui';
+
* import type { ProfileRecord } from 'atproto-ui';
+
* function MyProfile({ handle }: { handle: string }) {
+
* const { record, loading, error } = useBlueskyAppview<ProfileRecord>({
+
* did: handle, // Handles are automatically resolved to DIDs
+
* collection: 'app.bsky.actor.profile',
+
* if (loading) return <p>Loading profile...</p>;
+
* if (!record) return null;
+
* <h2>{record.displayName}</h2>
+
* <p>{record.description}</p>
+
* // Skip the appview and go directly to Slingshot/PDS
+
* const { record } = useBlueskyAppview({
+
* did: 'did:plc:example',
+
* collection: 'app.bsky.feed.post',
+
* skipAppview: true, // Bypasses Bluesky API, starts with Slingshot
+
* @param options - Configuration object with did, collection, rkey, and optional overrides.
+
* @returns {UseBlueskyAppviewResult<T>} Object containing the record, loading state, error, and source.
+
export function useBlueskyAppview<T = unknown>({
+
}: UseBlueskyAppviewOptions): UseBlueskyAppviewResult<T> {
+
} = useDidResolution(handleOrDid);
+
loading: resolvingEndpoint,
+
} = usePdsEndpoint(did);
+
const [record, setRecord] = useState<T | undefined>();
+
const [loading, setLoading] = useState(false);
+
const [error, setError] = useState<Error | undefined>();
+
const [source, setSource] = useState<"appview" | "slingshot" | "pds" | undefined>();
+
const assign = (next: Partial<UseBlueskyAppviewResult<T>>) => {
+
setRecord(next.record);
+
setLoading(next.loading ?? false);
+
setSource(next.source);
+
// Early returns for missing inputs or resolution errors
+
if (!handleOrDid || !collection || !rkey) {
+
assign({ loading: false, error: didError, source: undefined });
+
assign({ loading: false, error: endpointError, source: undefined });
+
if (resolvingDid || resolvingEndpoint || !did || !pdsEndpoint) {
+
assign({ loading: true, error: undefined, source: undefined });
+
assign({ loading: true, error: undefined, source: undefined });
+
let lastError: Error | undefined;
+
// Tier 1: Try Bluesky appview API
+
if (!skipAppview && BLUESKY_COLLECTION_TO_ENDPOINT[collection]) {
+
const result = await fetchFromAppview<T>(
+
appviewService ?? DEFAULT_APPVIEW_SERVICE,
+
if (!cancelled && result) {
+
lastError = err as Error;
+
// Continue to next tier
+
// Tier 2: Try Slingshot getRecord
+
const result = await fetchFromSlingshot<T>(did, collection, rkey);
+
if (!cancelled && result) {
+
lastError = err as Error;
+
// Continue to next tier
+
// Tier 3: Try PDS directly
+
const result = await fetchFromPds<T>(
+
if (!cancelled && result) {
+
lastError = err as Error;
+
new Error("Failed to fetch record from all sources"),
+
* Attempts to fetch a record from the Bluesky appview API.
+
* Different collections map to different endpoints with varying response structures.
+
async function fetchFromAppview<T>(
+
appviewService: string,
+
): Promise<T | undefined> {
+
const { rpc } = await createAtprotoClient({ service: appviewService });
+
const endpoint = BLUESKY_COLLECTION_TO_ENDPOINT[collection];
+
throw new Error(`No appview endpoint mapped for collection ${collection}`);
+
const atUri = `at://${did}/${collection}/${rkey}`;
+
// Handle different appview endpoints
+
if (endpoint === "app.bsky.actor.getProfile") {
+
const res = await (rpc as unknown as { get: (nsid: string, opts: { params: Record<string, unknown> }) => Promise<{ ok: boolean; data: AppviewProfileResponse }> }).get(endpoint, {
+
params: { actor: did },
+
if (!res.ok) throw new Error("Appview profile request failed");
+
// The appview returns avatar/banner as CDN URLs like:
+
// https://cdn.bsky.app/img/avatar/plain/{did}/{cid}@jpeg
+
// We need to extract the CID and convert to ProfileRecord format
+
const profile = res.data;
+
const avatarCid = extractCidFromCdnUrl(profile.avatar);
+
const bannerCid = extractCidFromCdnUrl(profile.banner);
+
// Convert hydrated profile to ProfileRecord format
+
// Store the CDN URL directly so components can use it without re-fetching
+
const record: Record<string, unknown> = {
+
displayName: profile.displayName,
+
description: profile.description,
+
createdAt: profile.createdAt,
+
if (profile.avatar && avatarCid) {
+
const avatarBlob: BlobWithCdn = {
+
ref: { $link: avatarCid },
+
mimeType: "image/jpeg",
+
cdnUrl: profile.avatar,
+
record.avatar = avatarBlob;
+
if (profile.banner && bannerCid) {
+
const bannerBlob: BlobWithCdn = {
+
ref: { $link: bannerCid },
+
mimeType: "image/jpeg",
+
cdnUrl: profile.banner,
+
record.banner = bannerBlob;
+
if (endpoint === "app.bsky.feed.getPostThread") {
+
const res = await (rpc as unknown as { get: (nsid: string, opts: { params: Record<string, unknown> }) => Promise<{ ok: boolean; data: AppviewPostThreadResponse<T> }> }).get(endpoint, {
+
params: { uri: atUri, depth: 0 },
+
if (!res.ok) throw new Error("Appview post thread request failed");
+
const post = res.data.thread?.post;
+
if (!post?.record) return undefined;
+
const record = post.record as Record<string, unknown>;
+
const appviewEmbed = post.embed;
+
// If the appview includes embedded images with CDN URLs, inject them into the record
+
if (appviewEmbed && record.embed) {
+
const recordEmbed = record.embed as { $type?: string; images?: Array<Record<string, unknown>>; media?: Record<string, unknown> };
+
// Handle direct image embeds
+
if (appviewEmbed.$type === "app.bsky.embed.images#view" && appviewEmbed.images) {
+
if (recordEmbed.images && Array.isArray(recordEmbed.images)) {
+
recordEmbed.images = recordEmbed.images.map((img: Record<string, unknown>, idx: number) => {
+
const appviewImg = appviewEmbed.images?.[idx];
+
if (appviewImg?.fullsize) {
+
const cid = extractCidFromCdnUrl(appviewImg.fullsize);
+
const imageObj = img.image as { ref?: { $link?: string } } | undefined;
+
...(img.image as Record<string, unknown> || {}),
+
cdnUrl: appviewImg.fullsize,
+
ref: { $link: cid || imageObj?.ref?.$link },
+
// Handle recordWithMedia embeds
+
if (appviewEmbed.$type === "app.bsky.embed.recordWithMedia#view" && appviewEmbed.media) {
+
const mediaImages = appviewEmbed.media.images;
+
const mediaEmbedImages = (recordEmbed.media as { images?: Array<Record<string, unknown>> } | undefined)?.images;
+
if (mediaImages && mediaEmbedImages && Array.isArray(mediaEmbedImages)) {
+
(recordEmbed.media as { images: Array<Record<string, unknown>> }).images = mediaEmbedImages.map((img: Record<string, unknown>, idx: number) => {
+
const appviewImg = mediaImages[idx];
+
if (appviewImg?.fullsize) {
+
const cid = extractCidFromCdnUrl(appviewImg.fullsize);
+
const imageObj = img.image as { ref?: { $link?: string } } | undefined;
+
...(img.image as Record<string, unknown> || {}),
+
cdnUrl: appviewImg.fullsize,
+
ref: { $link: cid || imageObj?.ref?.$link },
+
// For other endpoints, we might not have a clean way to extract the specific record
+
// Fall through to let the caller try the next tier
+
throw new Error(`Appview endpoint ${endpoint} not fully implemented`);
+
* Attempts to fetch a record from Slingshot's getRecord endpoint.
+
async function fetchFromSlingshot<T>(
+
): Promise<T | undefined> {
+
const res = await callGetRecord<T>(SLINGSHOT_BASE_URL, did, collection, rkey);
+
if (!res.ok) throw new Error("Slingshot getRecord failed");
+
* Attempts to fetch a record directly from the actor's PDS.
+
async function fetchFromPds<T>(
+
): Promise<T | undefined> {
+
const res = await callGetRecord<T>(pdsEndpoint, did, collection, rkey);
+
if (!res.ok) throw new Error("PDS getRecord failed");
+
* Extracts and validates CID from Bluesky CDN URL.
+
* Format: https://cdn.bsky.app/img/{type}/plain/{did}/{cid}@{format}
+
* @throws Error if URL format is invalid or CID extraction fails
+
function extractCidFromCdnUrl(url: string | undefined): string | undefined {
+
if (!url) return undefined;
+
// Match pattern: /did:plc:xxxxx/CIDHERE@format or /did:web:xxxxx/CIDHERE@format
+
const match = url.match(/\/did:[^/]+\/([^@/]+)@/);
+
const cid = match?.[1];
+
console.warn(`Failed to extract CID from CDN URL: ${url}`);
+
// Basic CID validation - should start with common CID prefixes
+
if (!cid.startsWith("bafk") && !cid.startsWith("bafyb") && !cid.startsWith("Qm")) {
+
console.warn(`Extracted string does not appear to be a valid CID: ${cid} from URL: ${url}`);
+
console.error(`Error extracting CID from CDN URL: ${url}`, err);
+
* Shared RPC utility for making appview API calls with proper typing.
+
export async function callAppviewRpc<TResponse>(
+
params: Record<string, unknown>,
+
): Promise<{ ok: boolean; data: TResponse }> {
+
const { rpc } = await createAtprotoClient({ service });
+
return await (rpc as unknown as {
+
get: (nsid: string, opts: { params: Record<string, unknown> }) => Promise<{ ok: boolean; data: TResponse }>;
+
}).get(nsid, { params });
+
* Shared RPC utility for making getRecord calls (Slingshot or PDS).
+
export async function callGetRecord<T>(
+
): Promise<{ ok: boolean; data: { value: T } }> {
+
const { rpc } = await createAtprotoClient({ service });
+
return await (rpc as unknown as {
+
get: (nsid: string, opts: { params: Record<string, unknown> }) => Promise<{ ok: boolean; data: { value: T } }>;
+
}).get("com.atproto.repo.getRecord", {
+
params: { repo: did, collection, rkey },
+
* Shared RPC utility for making listRecords calls.
+
export async function callListRecords<T>(
+
records: Array<{ uri: string; rkey?: string; value: T }>;
+
const { rpc } = await createAtprotoClient({ service });
+
return await (rpc as unknown as {
+
opts: { params: Record<string, unknown> },
+
records: Array<{ uri: string; rkey?: string; value: T }>;
+
}).get("com.atproto.repo.listRecords", {
nekomimi.pet