A calm place to write long-form, and publish it to the open social web.
skypress.blog/
Reader: extract a read-context module to own the read-route spine
Every read route (author index, publication home, article, RSS)
hand-assembled the same orchestration in its frontmatter: strip the
@ from the URL param, resolve handle -> DID -> PDS, match a
publication by slug, join documents by value.site ===
publication.uri, and map each miss to an error scene. That was ~230
near-duplicate lines across four files, and the join key, the
100-document fetch bound, and the blob-ref -> logo-URL construction
were caller knowledge repeated 3-4x. Living in .astro frontmatter,
none of it was unit-testable - the colocated tests pinned the page
source with regexes instead of behaviour.
resolveAuthorContext / resolvePublicationContext /
resolveArticleContext (src/lib/reader/read-context.ts) now own that
spine behind one interface returning either a fully-shaped context
or ready-made ErrorSceneCopy; the routes keep only presentation.
Publications come back with logoUrl prebuilt so callers never touch
BlobRefJson internals, and the per-route independent fetches
(profile, publication list, documents) run in parallel where the
pages ran them serially.
The module is behaviourally tested in read-context.test.ts (mocking
only the network seam: identity.ts + records.ts); the source-pin
tests shrank to template-wiring guards. The now-unused
listReaderPublications / resolveReaderPublication wrappers are
deleted. Decision 0016 records the seam.
Side effect: RSS 404 bodies are a uniform "Not found" instead of
echoing the handle.
author
Jeremy Herve
date
(Jun 10, 2026, 10:24 AM +0200)
commit
e05e21dd
e05e21dd534ab55057f45dd8fcf5715573beb7eb
parent
a0b62c5a
a0b62c5acdcb42c4f3b24f744bb71a65b9c8fce9
+665
-338
+46
docs/decisions/0016-read-context-module.md
+46
docs/decisions/0016-read-context-module.md
···
1
+
# 0016 — Read routes delegate orchestration to the read-context module
2
+
3
+
- **Status:** Accepted
4
+
- **Date:** 2026-06-10
5
+
- **Scope:** the public read path (`src/pages/[author]/**`, `src/lib/reader/read-context.ts`)
6
+
7
+
## Context
8
+
9
+
Every read route (author index, publication home, article, RSS) hand-assembled the same
10
+
resolution spine in its frontmatter: strip the `@` from the URL param, resolve
11
+
handle → DID → PDS (Decision 0007), match a publication by slug, join documents by
12
+
`value.site === publication.uri` (Decision 0010), and map each miss to an error scene.
13
+
That was ~230 near-duplicate lines across four files, and the join key, the 100-document
14
+
fetch bound, and the blob-ref → logo-URL construction were caller knowledge repeated
15
+
3–4×. Because the orchestration lived in `.astro` frontmatter, it could only be "tested"
16
+
by regex pins against the page source (see rule 8 in AGENTS.md for why container
17
+
rendering is out).
18
+
19
+
## Decision
20
+
21
+
One deep module, `src/lib/reader/read-context.ts`, owns the spine behind three entry
22
+
points — `resolveAuthorContext`, `resolvePublicationContext`, `resolveArticleContext` —
23
+
each returning `{ ok: true, context }` or `{ ok: false, error: ErrorSceneCopy }`.
24
+
25
+
- **Pages keep only presentation.** A new read surface (AMP, embeds, …) must call the
26
+
read-context interface, not re-assemble `resolveAuthor` + slug-match + site-join.
27
+
- The module returns publications with `logoUrl` prebuilt, so callers never touch
28
+
`BlobRefJson` internals.
29
+
- The per-route independent fetches (profile, publication list, documents/record) run
30
+
in parallel inside the module; the old pages ran them serially.
31
+
- The article render pipeline (`resolveBlobImageUrls → renderBlocks →
32
+
sanitizeArticleHtml`) deliberately stays in the article page / feed builder — sealing
33
+
it behind its own interface is a separate, orthogonal deepening.
34
+
- The shallow wrappers this obsoleted (`listReaderPublications`,
35
+
`resolveReaderPublication`) were deleted; `listAllReaderPublications` remains the one
36
+
reader-side publication fetch.
37
+
38
+
## Consequences
39
+
40
+
- The orchestration is behaviourally unit-tested in `read-context.test.ts` (mocking only
41
+
the network seam: `identity.ts` + `records.ts`); the colocated `_*.meta.test.ts` source
42
+
pins shrank to template-wiring guards.
43
+
- On not-found paths the module may fetch slightly more than the old serial code did
44
+
(the parallel fetches start before the publication match is known) — accepted for the
45
+
happy-path latency win.
46
+
- RSS 404 bodies are now a uniform `Not found` instead of echoing the handle.
+11
-32
src/lib/reader/publications.test.ts
+11
-32
src/lib/reader/publications.test.ts
···
1
1
import { describe, expect, it, vi, beforeEach } from 'vitest';
2
-
import {
3
-
listReaderPublications,
4
-
listAllReaderPublications,
5
-
resolveReaderPublication,
6
-
} from './publications';
2
+
import { listAllReaderPublications } from './publications';
7
3
import { listRecords } from './records';
8
4
import { SITE_BASE } from '../publish/records';
9
5
import { THEME_PRESETS } from '../publish/themes';
···
20
16
21
17
beforeEach( () => mockedList.mockReset() );
22
18
23
-
describe( 'listReaderPublications', () => {
24
-
it( 'keeps only SkyPress-origin, slugged publications', async () => {
19
+
describe( 'listAllReaderPublications', () => {
20
+
it( 'keeps only SkyPress-origin, slugged publications as owned', async () => {
25
21
mockedList.mockResolvedValue( [
26
22
rec( 'a', `${ SITE_BASE }/@me.bsky.social/blog`, { description: ' Hi ' } ),
27
23
rec( 'b', 'https://leaflet.pub/x/y' ),
28
24
rec( 'c', `${ SITE_BASE }/@me.bsky.social` ),
29
25
] );
30
-
const pubs = await listReaderPublications( PDS, DID );
31
-
expect( pubs ).toHaveLength( 1 );
32
-
expect( pubs[ 0 ] ).toMatchObject( {
26
+
const { owned } = await listAllReaderPublications( PDS, DID );
27
+
expect( owned ).toHaveLength( 1 );
28
+
expect( owned[ 0 ] ).toMatchObject( {
33
29
uri: `at://${ DID }/site.standard.publication/a`,
34
30
slug: 'blog',
35
31
name: 'Pa',
36
32
description: 'Hi',
37
33
} );
38
34
} );
39
-
} );
40
35
41
-
describe( 'listAllReaderPublications', () => {
42
36
it( 'partitions owned SkyPress publications from foreign ones', async () => {
43
37
const icon = { ref: { $link: 'bafyicon' }, mimeType: 'image/png', size: 1 };
44
38
mockedList.mockResolvedValue( [
···
70
64
} );
71
65
} );
72
66
73
-
describe( 'resolveReaderPublication', () => {
74
-
it( 'finds the publication whose slug matches', async () => {
75
-
mockedList.mockResolvedValue( [
76
-
rec( 'a', `${ SITE_BASE }/@me.bsky.social/blog` ),
77
-
rec( 'b', `${ SITE_BASE }/@me.bsky.social/notes` ),
78
-
] );
79
-
const pub = await resolveReaderPublication( PDS, DID, 'notes' );
80
-
expect( pub?.uri ).toBe( `at://${ DID }/site.standard.publication/b` );
81
-
} );
82
-
83
-
it( 'returns null when no slug matches', async () => {
84
-
mockedList.mockResolvedValue( [ rec( 'a', `${ SITE_BASE }/@me.bsky.social/blog` ) ] );
85
-
expect( await resolveReaderPublication( PDS, DID, 'missing' ) ).toBeNull();
86
-
} );
87
-
} );
88
-
89
67
describe( 'reader basicTheme', () => {
90
68
it( 'surfaces a valid stored basicTheme', async () => {
91
69
mockedList.mockResolvedValue( [
···
93
71
basicTheme: THEME_PRESETS[ 5 ].colors, // morning
94
72
} ),
95
73
] );
96
-
const pub = await resolveReaderPublication( PDS, DID, 'blog' );
97
-
expect( pub?.basicTheme ).toEqual( THEME_PRESETS[ 5 ].colors );
74
+
const { owned } = await listAllReaderPublications( PDS, DID );
75
+
expect( owned[ 0 ].basicTheme ).toEqual( THEME_PRESETS[ 5 ].colors );
98
76
} );
99
77
100
78
it( 'sets basicTheme to null when absent or malformed', async () => {
···
102
80
rec( 'a', `${ SITE_BASE }/@me.bsky.social/plain` ),
103
81
rec( 'b', `${ SITE_BASE }/@me.bsky.social/broken`, { basicTheme: { accent: 'red' } } ),
104
82
] );
105
-
expect( ( await resolveReaderPublication( PDS, DID, 'plain' ) )?.basicTheme ).toBeNull();
106
-
expect( ( await resolveReaderPublication( PDS, DID, 'broken' ) )?.basicTheme ).toBeNull();
83
+
const { owned } = await listAllReaderPublications( PDS, DID );
84
+
expect( owned.find( ( p ) => p.slug === 'plain' )?.basicTheme ).toBeNull();
85
+
expect( owned.find( ( p ) => p.slug === 'broken' )?.basicTheme ).toBeNull();
107
86
} );
108
87
} );
-17
src/lib/reader/publications.ts
-17
src/lib/reader/publications.ts
···
116
116
return { owned, foreign };
117
117
}
118
118
119
-
/** All of a writer's SkyPress publications (newest first) — for the author index. */
120
-
export async function listReaderPublications(
121
-
pdsUrl: string,
122
-
did: string
123
-
): Promise< ReaderPublication[] > {
124
-
return ( await listAllReaderPublications( pdsUrl, did ) ).owned;
125
-
}
126
-
127
-
/** Resolve one publication by its slug (the publication + document routes), or null. */
128
-
export async function resolveReaderPublication(
129
-
pdsUrl: string,
130
-
did: string,
131
-
slug: string
132
-
): Promise< ReaderPublication | null > {
133
-
const pubs = await listReaderPublications( pdsUrl, did );
134
-
return pubs.find( ( pub ) => pub.slug === slug ) ?? null;
135
-
}
+229
src/lib/reader/read-context.test.ts
+229
src/lib/reader/read-context.test.ts
···
1
+
import { describe, expect, it, vi, beforeEach } from 'vitest';
2
+
import {
3
+
resolveAuthorContext,
4
+
resolvePublicationContext,
5
+
resolveArticleContext,
6
+
} from './read-context';
7
+
import { resolveAuthor } from './identity';
8
+
import { getRecord, listRecords } from './records';
9
+
import { buildGetBlobUrl } from '../media/blob';
10
+
import { SITE_BASE } from '../publish/records';
11
+
12
+
vi.mock( './identity', () => ( { resolveAuthor: vi.fn() } ) );
13
+
vi.mock( './records', () => ( { getRecord: vi.fn(), listRecords: vi.fn() } ) );
14
+
15
+
const mockedResolveAuthor = resolveAuthor as unknown as ReturnType< typeof vi.fn >;
16
+
const mockedGetRecord = getRecord as unknown as ReturnType< typeof vi.fn >;
17
+
const mockedListRecords = listRecords as unknown as ReturnType< typeof vi.fn >;
18
+
19
+
const PDS = 'https://pds.example';
20
+
const DID = 'did:plc:me';
21
+
const HANDLE = 'me.bsky.social';
22
+
const ICON = { $type: 'blob', ref: { $link: 'bafyicon' }, mimeType: 'image/png', size: 1 };
23
+
24
+
const PUB_URI = `at://${ DID }/site.standard.publication/a`;
25
+
26
+
function pubRecord( rkey: string, url: string, extra: Record< string, unknown > = {} ) {
27
+
return {
28
+
uri: `at://${ DID }/site.standard.publication/${ rkey }`,
29
+
cid: 'c',
30
+
value: { url, name: `P${ rkey }`, ...extra },
31
+
};
32
+
}
33
+
34
+
function docRecord( rkey: string, site: string, extra: Record< string, unknown > = {} ) {
35
+
return {
36
+
uri: `at://${ DID }/site.standard.document/${ rkey }`,
37
+
cid: 'c',
38
+
value: { title: `T${ rkey }`, site, ...extra },
39
+
};
40
+
}
41
+
42
+
/** Default happy-path PDS: one resolvable writer, two publications, two documents. */
43
+
function wirePds( {
44
+
publications = [
45
+
pubRecord( 'a', `${ SITE_BASE }/@${ HANDLE }/blog`, { icon: ICON } ),
46
+
pubRecord( 'b', `${ SITE_BASE }/@${ HANDLE }/notes` ),
47
+
pubRecord( 'f', 'https://leaflet.pub/x/y', { name: 'Leafy' } ),
48
+
],
49
+
documents = [
50
+
docRecord( 'd1', PUB_URI ),
51
+
docRecord( 'd2', `at://${ DID }/site.standard.publication/b` ),
52
+
],
53
+
profile = { displayName: ' Me ', description: 'bio' } as Record< string, unknown > | null,
54
+
article = null as ReturnType< typeof docRecord > | null,
55
+
} = {} ) {
56
+
mockedResolveAuthor.mockResolvedValue( { did: DID, pdsUrl: PDS } );
57
+
mockedListRecords.mockImplementation( async ( _pds, _did, collection ) =>
58
+
collection === 'site.standard.publication' ? publications : documents
59
+
);
60
+
mockedGetRecord.mockImplementation( async ( _pds, _did, collection ) => {
61
+
if ( collection === 'app.bsky.actor.profile' ) {
62
+
return profile ? { uri: 'at://profile', cid: 'c', value: profile } : null;
63
+
}
64
+
return article;
65
+
} );
66
+
}
67
+
68
+
beforeEach( () => {
69
+
mockedResolveAuthor.mockReset();
70
+
mockedGetRecord.mockReset();
71
+
mockedListRecords.mockReset();
72
+
} );
73
+
74
+
describe( 'resolveAuthorContext', () => {
75
+
it( 'maps a param without a leading @ to a generic 404', async () => {
76
+
const result = await resolveAuthorContext( HANDLE );
77
+
expect( result.ok ).toBe( false );
78
+
if ( ! result.ok ) {
79
+
expect( result.error.status ).toBe( 404 );
80
+
}
81
+
expect( mockedResolveAuthor ).not.toHaveBeenCalled();
82
+
} );
83
+
84
+
it( 'maps a missing param to a generic 404', async () => {
85
+
const result = await resolveAuthorContext( undefined );
86
+
expect( result.ok ).toBe( false );
87
+
} );
88
+
89
+
it( 'maps an unresolvable handle to writer-not-found', async () => {
90
+
mockedResolveAuthor.mockResolvedValue( null );
91
+
const result = await resolveAuthorContext( `@${ HANDLE }` );
92
+
expect( result.ok ).toBe( false );
93
+
if ( ! result.ok ) {
94
+
expect( result.error.status ).toBe( 404 );
95
+
expect( result.error.heading ).toContain( `@${ HANDLE }` );
96
+
}
97
+
} );
98
+
99
+
it( 'degrades to an empty context when the PDS has no profile or publications', async () => {
100
+
wirePds( { publications: [], documents: [], profile: null } );
101
+
const result = await resolveAuthorContext( `@${ HANDLE }` );
102
+
expect( result.ok ).toBe( true );
103
+
if ( ! result.ok ) {
104
+
return;
105
+
}
106
+
expect( result.context.publications ).toEqual( [] );
107
+
expect( result.context.foreign ).toEqual( [] );
108
+
expect( result.context.profile.displayName ).toBeNull();
109
+
} );
110
+
111
+
it( 'returns the author, profile, and publications with prebuilt logo URLs', async () => {
112
+
wirePds();
113
+
const result = await resolveAuthorContext( `@${ HANDLE }` );
114
+
expect( result.ok ).toBe( true );
115
+
if ( ! result.ok ) {
116
+
return;
117
+
}
118
+
const { author, profile, publications, foreign } = result.context;
119
+
expect( author ).toEqual( { handle: HANDLE, did: DID, pdsUrl: PDS } );
120
+
expect( profile.displayName ).toBe( 'Me' );
121
+
122
+
expect( publications ).toHaveLength( 2 );
123
+
expect( publications[ 0 ] ).toMatchObject( {
124
+
slug: 'blog',
125
+
logoUrl: buildGetBlobUrl( PDS, DID, 'bafyicon' ),
126
+
} );
127
+
// No icon → no logo URL; the caller never touches blob internals.
128
+
expect( publications[ 1 ].logoUrl ).toBeNull();
129
+
130
+
expect( foreign ).toHaveLength( 1 );
131
+
expect( foreign[ 0 ] ).toMatchObject( { name: 'Leafy', logoUrl: null } );
132
+
} );
133
+
} );
134
+
135
+
describe( 'resolvePublicationContext', () => {
136
+
it( 'maps a missing slug to a generic 404', async () => {
137
+
wirePds();
138
+
const result = await resolvePublicationContext( `@${ HANDLE }`, undefined );
139
+
expect( result.ok ).toBe( false );
140
+
if ( ! result.ok ) {
141
+
expect( result.error.status ).toBe( 404 );
142
+
}
143
+
} );
144
+
145
+
it( 'maps an unknown slug to publication-not-found', async () => {
146
+
wirePds();
147
+
const result = await resolvePublicationContext( `@${ HANDLE }`, 'missing' );
148
+
expect( result.ok ).toBe( false );
149
+
if ( ! result.ok ) {
150
+
expect( result.error.status ).toBe( 404 );
151
+
expect( result.error.subline ).toContain( 'missing' );
152
+
}
153
+
} );
154
+
155
+
it( 'returns the publication and only its own documents, newest-first order preserved', async () => {
156
+
wirePds();
157
+
const result = await resolvePublicationContext( `@${ HANDLE }`, 'blog' );
158
+
expect( result.ok ).toBe( true );
159
+
if ( ! result.ok ) {
160
+
return;
161
+
}
162
+
const { publication, documents } = result.context;
163
+
expect( publication ).toMatchObject( {
164
+
uri: PUB_URI,
165
+
slug: 'blog',
166
+
logoUrl: buildGetBlobUrl( PDS, DID, 'bafyicon' ),
167
+
} );
168
+
// The site-join (document.value.site === publication.uri) happens here, once.
169
+
expect( documents ).toHaveLength( 1 );
170
+
expect( documents[ 0 ] ).toMatchObject( { rkey: 'd1', value: { title: 'Td1' } } );
171
+
} );
172
+
} );
173
+
174
+
describe( 'resolveArticleContext', () => {
175
+
it( 'maps a missing rkey to a generic 404', async () => {
176
+
wirePds();
177
+
const result = await resolveArticleContext( `@${ HANDLE }`, 'blog', undefined );
178
+
expect( result.ok ).toBe( false );
179
+
} );
180
+
181
+
it( 'maps a missing record to article-not-found', async () => {
182
+
wirePds( { article: null } );
183
+
const result = await resolveArticleContext( `@${ HANDLE }`, 'blog', 'gone' );
184
+
expect( result.ok ).toBe( false );
185
+
if ( ! result.ok ) {
186
+
expect( result.error.status ).toBe( 404 );
187
+
expect( result.error.subline ).toContain( 'Pa' );
188
+
}
189
+
} );
190
+
191
+
it( 'rejects a document that belongs to another publication', async () => {
192
+
// The d2 document exists but its site points at the "notes" publication.
193
+
wirePds( { article: docRecord( 'd2', `at://${ DID }/site.standard.publication/b` ) } );
194
+
const result = await resolveArticleContext( `@${ HANDLE }`, 'blog', 'd2' );
195
+
expect( result.ok ).toBe( false );
196
+
if ( ! result.ok ) {
197
+
expect( result.error.status ).toBe( 404 );
198
+
}
199
+
} );
200
+
201
+
it( 'returns the document with its publication and author profile', async () => {
202
+
wirePds( {
203
+
article: docRecord( 'd1', PUB_URI, { textContent: 'Hello world', publishedAt: '2026-06-01T00:00:00Z' } ),
204
+
} );
205
+
const result = await resolveArticleContext( `@${ HANDLE }`, 'blog', 'd1' );
206
+
expect( result.ok ).toBe( true );
207
+
if ( ! result.ok ) {
208
+
return;
209
+
}
210
+
const { author, publication, document, profile } = result.context;
211
+
expect( author.handle ).toBe( HANDLE );
212
+
expect( publication.slug ).toBe( 'blog' );
213
+
expect( profile.displayName ).toBe( 'Me' );
214
+
expect( document ).toMatchObject( {
215
+
rkey: 'd1',
216
+
uri: `at://${ DID }/site.standard.document/d1`,
217
+
value: { title: 'Td1', textContent: 'Hello world' },
218
+
} );
219
+
} );
220
+
221
+
it( 'reports publication-not-found before article-not-found', async () => {
222
+
wirePds( { article: docRecord( 'd1', PUB_URI ) } );
223
+
const result = await resolveArticleContext( `@${ HANDLE }`, 'nope', 'd1' );
224
+
expect( result.ok ).toBe( false );
225
+
if ( ! result.ok ) {
226
+
expect( result.error.subline ).toContain( 'nope' );
227
+
}
228
+
} );
229
+
} );
+238
src/lib/reader/read-context.ts
+238
src/lib/reader/read-context.ts
···
1
+
/**
2
+
* The read-context module: one deep interface for the public read routes.
3
+
*
4
+
* Every read route used to hand-assemble the same spine — strip the `@` from the
5
+
* URL param, resolve handle → DID → PDS, match a publication by slug, join documents
6
+
* by `value.site === publication.uri`, and map each miss to an error scene. That
7
+
* orchestration (and its caller knowledge: the join key, the fetch cap, the blob-ref
8
+
* shape behind logo URLs) now lives here, once, behind three entry points:
9
+
*
10
+
* resolveAuthorContext( author ) — `/@handle`
11
+
* resolvePublicationContext( author, slug ) — `/@handle/{slug}` + rss.xml
12
+
* resolveArticleContext( author, slug, rkey ) — `/@handle/{slug}/{rkey}`
13
+
*
14
+
* Each returns `{ ok: true, context }` or `{ ok: false, error }` where `error` is
15
+
* ready-made `ErrorSceneCopy` (status + page copy), so routes keep only templates.
16
+
* All PDS fetches stay SSRF-guarded via `records.ts`/`identity.ts` underneath.
17
+
*/
18
+
import { resolveAuthor } from './identity';
19
+
import { getRecord, listRecords } from './records';
20
+
import {
21
+
listAllReaderPublications,
22
+
type ReaderPublication,
23
+
type ReaderForeignPublication,
24
+
} from './publications';
25
+
import { fetchActorProfile, type ActorProfile } from './profile';
26
+
import { buildGetBlobUrl } from '../media/blob';
27
+
import { errorScene, type ErrorSceneCopy } from './errors';
28
+
import type { BlockNode } from '../blocks/render';
29
+
30
+
const DOCUMENT_COLLECTION = 'site.standard.document';
31
+
32
+
/**
33
+
* One `listRecords` page of the writer's documents (across all their publications).
34
+
* A writer with more total documents than this could have older items missing from
35
+
* publication pages and feeds — a known, deliberate bound (Decision 0011; the feed
36
+
* additionally keeps only the newest `FEED_ITEM_LIMIT` after the site-join).
37
+
*/
38
+
const DOCUMENT_FETCH_LIMIT = 100;
39
+
40
+
export interface ReadAuthor {
41
+
handle: string;
42
+
did: string;
43
+
pdsUrl: string;
44
+
}
45
+
46
+
/** A publication with its logo already resolved to a fetchable URL (or null). */
47
+
export type PublicationView = ReaderPublication & { logoUrl: string | null };
48
+
export type ForeignPublicationView = ReaderForeignPublication & { logoUrl: string | null };
49
+
50
+
/** The slice of a `site.standard.document` value the read routes consume. */
51
+
export interface SkyDocumentValue {
52
+
title?: string;
53
+
description?: string;
54
+
textContent?: string;
55
+
publishedAt?: string;
56
+
updatedAt?: string;
57
+
site?: string;
58
+
content?: { blocks?: BlockNode[] };
59
+
/** strongRef to the companion `app.bsky.feed.post` — the target of reader actions. */
60
+
bskyPostRef?: { uri: string; cid: string };
61
+
}
62
+
63
+
export interface PublicationDocument {
64
+
uri: string;
65
+
cid: string;
66
+
rkey: string;
67
+
value: SkyDocumentValue;
68
+
}
69
+
70
+
export interface AuthorReadContext {
71
+
author: ReadAuthor;
72
+
profile: ActorProfile;
73
+
publications: PublicationView[];
74
+
foreign: ForeignPublicationView[];
75
+
}
76
+
77
+
export interface PublicationReadContext {
78
+
author: ReadAuthor;
79
+
profile: ActorProfile;
80
+
publication: PublicationView;
81
+
/** This publication's documents only (site-joined), in PDS order (newest first). */
82
+
documents: PublicationDocument[];
83
+
}
84
+
85
+
export interface ArticleReadContext {
86
+
author: ReadAuthor;
87
+
profile: ActorProfile;
88
+
publication: PublicationView;
89
+
document: PublicationDocument;
90
+
}
91
+
92
+
export type ReadContextResult< T > =
93
+
| { ok: true; context: T }
94
+
| { ok: false; error: ErrorSceneCopy };
95
+
96
+
function notFound< T >( error: ErrorSceneCopy ): ReadContextResult< T > {
97
+
return { ok: false, error };
98
+
}
99
+
100
+
/** The shared spine: validate the `@handle` param and resolve it to a DID + PDS. */
101
+
async function resolveReadAuthor(
102
+
authorParam: string | undefined
103
+
): Promise< { author: ReadAuthor } | { error: ErrorSceneCopy } > {
104
+
if ( ! authorParam || ! authorParam.startsWith( '@' ) ) {
105
+
return { error: errorScene( 'not-found' ) };
106
+
}
107
+
const handle = authorParam.slice( 1 );
108
+
const resolved = await resolveAuthor( handle );
109
+
if ( ! resolved ) {
110
+
return { error: errorScene( 'writer-not-found', { handle } ) };
111
+
}
112
+
return { author: { handle, did: resolved.did, pdsUrl: resolved.pdsUrl } };
113
+
}
114
+
115
+
function withLogoUrl< T extends { icon: ReaderPublication[ 'icon' ] } >(
116
+
author: ReadAuthor,
117
+
publication: T
118
+
): T & { logoUrl: string | null } {
119
+
return {
120
+
...publication,
121
+
logoUrl: publication.icon
122
+
? buildGetBlobUrl( author.pdsUrl, author.did, publication.icon.ref.$link )
123
+
: null,
124
+
};
125
+
}
126
+
127
+
function toPublicationDocument(
128
+
record: { uri: string; cid: string; value: SkyDocumentValue }
129
+
): PublicationDocument {
130
+
return {
131
+
uri: record.uri,
132
+
cid: record.cid,
133
+
rkey: record.uri.split( '/' ).pop() ?? '',
134
+
value: record.value,
135
+
};
136
+
}
137
+
138
+
export async function resolveAuthorContext(
139
+
authorParam: string | undefined
140
+
): Promise< ReadContextResult< AuthorReadContext > > {
141
+
const spine = await resolveReadAuthor( authorParam );
142
+
if ( 'error' in spine ) {
143
+
return notFound( spine.error );
144
+
}
145
+
const { author } = spine;
146
+
147
+
const [ profile, allPublications ] = await Promise.all( [
148
+
fetchActorProfile( author.pdsUrl, author.did ),
149
+
listAllReaderPublications( author.pdsUrl, author.did ),
150
+
] );
151
+
152
+
return {
153
+
ok: true,
154
+
context: {
155
+
author,
156
+
profile,
157
+
publications: allPublications.owned.map( ( pub ) => withLogoUrl( author, pub ) ),
158
+
foreign: allPublications.foreign.map( ( pub ) => withLogoUrl( author, pub ) ),
159
+
},
160
+
};
161
+
}
162
+
163
+
export async function resolvePublicationContext(
164
+
authorParam: string | undefined,
165
+
slug: string | undefined
166
+
): Promise< ReadContextResult< PublicationReadContext > > {
167
+
if ( ! slug ) {
168
+
return notFound( errorScene( 'not-found' ) );
169
+
}
170
+
const spine = await resolveReadAuthor( authorParam );
171
+
if ( 'error' in spine ) {
172
+
return notFound( spine.error );
173
+
}
174
+
const { author } = spine;
175
+
176
+
// The publication match, the profile, and the document page are independent
177
+
// fetches — run them together rather than serially like the old pages did.
178
+
const [ profile, allPublications, documentRecords ] = await Promise.all( [
179
+
fetchActorProfile( author.pdsUrl, author.did ),
180
+
listAllReaderPublications( author.pdsUrl, author.did ),
181
+
listRecords< SkyDocumentValue >(
182
+
author.pdsUrl,
183
+
author.did,
184
+
DOCUMENT_COLLECTION,
185
+
DOCUMENT_FETCH_LIMIT
186
+
),
187
+
] );
188
+
189
+
const matched = allPublications.owned.find( ( pub ) => pub.slug === slug );
190
+
if ( ! matched ) {
191
+
return notFound( errorScene( 'publication-not-found', { handle: author.handle, slug } ) );
192
+
}
193
+
const publication = withLogoUrl( author, matched );
194
+
195
+
const documents = documentRecords
196
+
.filter( ( record ) => record.value.site === publication.uri )
197
+
.map( toPublicationDocument );
198
+
199
+
return { ok: true, context: { author, profile, publication, documents } };
200
+
}
201
+
202
+
export async function resolveArticleContext(
203
+
authorParam: string | undefined,
204
+
slug: string | undefined,
205
+
rkey: string | undefined
206
+
): Promise< ReadContextResult< ArticleReadContext > > {
207
+
if ( ! slug || ! rkey ) {
208
+
return notFound( errorScene( 'not-found' ) );
209
+
}
210
+
const spine = await resolveReadAuthor( authorParam );
211
+
if ( 'error' in spine ) {
212
+
return notFound( spine.error );
213
+
}
214
+
const { author } = spine;
215
+
216
+
const [ profile, allPublications, record ] = await Promise.all( [
217
+
fetchActorProfile( author.pdsUrl, author.did ),
218
+
listAllReaderPublications( author.pdsUrl, author.did ),
219
+
getRecord< SkyDocumentValue >( author.pdsUrl, author.did, DOCUMENT_COLLECTION, rkey ),
220
+
] );
221
+
222
+
const matched = allPublications.owned.find( ( pub ) => pub.slug === slug );
223
+
if ( ! matched ) {
224
+
return notFound( errorScene( 'publication-not-found', { handle: author.handle, slug } ) );
225
+
}
226
+
const publication = withLogoUrl( author, matched );
227
+
228
+
// The site-join: a document renders under a publication only when it points back
229
+
// at that publication's record. A real record under another publication 404s here.
230
+
if ( ! record?.value || record.value.site !== publication.uri ) {
231
+
return notFound( errorScene( 'article-not-found', { publicationName: publication.name } ) );
232
+
}
233
+
234
+
return {
235
+
ok: true,
236
+
context: { author, profile, publication, document: toPublicationDocument( record ) },
237
+
};
238
+
}