+8

.env.example

··· 1 1 + # Required: Your AT Protocol DID 2 2 + PUBLIC_ATPROTO_DID=did:plc:revjuqmkvrw6fnkxppqtszpv 3 3 + 4 4 + # Optional: Custom PDS endpoint (will be auto-resolved if not provided) 5 5 + # PUBLIC_ATPROTO_PDS=https://cortinarius.us-west.host.bsky.network 6 6 + 7 7 + # Optional: Cache TTL in milliseconds (default: 300000 = 5 minutes) 8 8 + # PUBLIC_CACHE_TTL=300000

+628

API.md

··· 1 1 + # API Reference 2 2 + 3 3 + Complete API documentation for svelte-standard-site. 4 4 + 5 5 + ## Table of Contents 6 6 + 7 7 + - [SiteStandardClient](#sitestandardclient) 8 8 + - [Types](#types) 9 9 + - [Utility Functions](#utility-functions) 10 10 + - [Components](#components) 11 11 + - [Configuration](#configuration) 12 12 + 13 13 + ## SiteStandardClient 14 14 + 15 15 + The main client class for interacting with site.standard.\* records. 16 16 + 17 17 + ### Constructor 18 18 + 19 19 + ```typescript 20 20 + constructor(config: SiteStandardConfig) 21 21 + ``` 22 22 + 23 23 + Creates a new instance of the client. 24 24 + 25 25 + **Parameters:** 26 26 + 27 27 + - `config` (SiteStandardConfig): Configuration object 28 28 + 29 29 + **Example:** 30 30 + 31 31 + ```typescript 32 32 + import { createClient } from 'svelte-standard-site'; 33 33 + 34 34 + const client = createClient({ 35 35 + did: 'did:plc:revjuqmkvrw6fnkxppqtszpv', 36 36 + pds: 'https://cortinarius.us-west.host.bsky.network', // optional 37 37 + cacheTTL: 300000 // optional, in ms 38 38 + }); 39 39 + ``` 40 40 + 41 41 + ### Methods 42 42 + 43 43 + #### `fetchPublication` 44 44 + 45 45 + ```typescript 46 46 + async fetchPublication( 47 47 + rkey: string, 48 48 + fetchFn?: typeof fetch 49 49 + ): Promise<AtProtoRecord<Publication> | null> 50 50 + ``` 51 51 + 52 52 + Fetches a single publication by its record key. 53 53 + 54 54 + **Parameters:** 55 55 + 56 56 + - `rkey` (string): The record key (TID) of the publication 57 57 + - `fetchFn` (typeof fetch, optional): Custom fetch function for SSR 58 58 + 59 59 + **Returns:** Promise resolving to the publication record or null if not found 60 60 + 61 61 + **Example:** 62 62 + 63 63 + ```typescript 64 64 + const pub = await client.fetchPublication('3lwafzkjqm25s'); 65 65 + if (pub) { 66 66 + console.log(pub.value.name); 67 67 + } 68 68 + ``` 69 69 + 70 70 + #### `fetchAllPublications` 71 71 + 72 72 + ```typescript 73 73 + async fetchAllPublications( 74 74 + fetchFn?: typeof fetch 75 75 + ): Promise<AtProtoRecord<Publication>[]> 76 76 + ``` 77 77 + 78 78 + Fetches all publications for the configured DID with automatic pagination. 79 79 + 80 80 + **Parameters:** 81 81 + 82 82 + - `fetchFn` (typeof fetch, optional): Custom fetch function for SSR 83 83 + 84 84 + **Returns:** Promise resolving to an array of publication records 85 85 + 86 86 + **Example:** 87 87 + 88 88 + ```typescript 89 89 + const publications = await client.fetchAllPublications(fetch); 90 90 + console.log(`Found ${publications.length} publications`); 91 91 + ``` 92 92 + 93 93 + #### `fetchDocument` 94 94 + 95 95 + ```typescript 96 96 + async fetchDocument( 97 97 + rkey: string, 98 98 + fetchFn?: typeof fetch 99 99 + ): Promise<AtProtoRecord<Document> | null> 100 100 + ``` 101 101 + 102 102 + Fetches a single document by its record key. 103 103 + 104 104 + **Parameters:** 105 105 + 106 106 + - `rkey` (string): The record key (TID) of the document 107 107 + - `fetchFn` (typeof fetch, optional): Custom fetch function for SSR 108 108 + 109 109 + **Returns:** Promise resolving to the document record or null if not found 110 110 + 111 111 + **Example:** 112 112 + 113 113 + ```typescript 114 114 + const doc = await client.fetchDocument('3lxbm5kqrs2s'); 115 115 + if (doc) { 116 116 + console.log(doc.value.title); 117 117 + } 118 118 + ``` 119 119 + 120 120 + #### `fetchAllDocuments` 121 121 + 122 122 + ```typescript 123 123 + async fetchAllDocuments( 124 124 + fetchFn?: typeof fetch 125 125 + ): Promise<AtProtoRecord<Document>[]> 126 126 + ``` 127 127 + 128 128 + Fetches all documents for the configured DID with automatic pagination. Results are sorted by `publishedAt` (newest first). 129 129 + 130 130 + **Parameters:** 131 131 + 132 132 + - `fetchFn` (typeof fetch, optional): Custom fetch function for SSR 133 133 + 134 134 + **Returns:** Promise resolving to an array of document records 135 135 + 136 136 + **Example:** 137 137 + 138 138 + ```typescript 139 139 + const documents = await client.fetchAllDocuments(fetch); 140 140 + documents.forEach((doc) => { 141 141 + console.log(doc.value.title, new Date(doc.value.publishedAt)); 142 142 + }); 143 143 + ``` 144 144 + 145 145 + #### `fetchDocumentsByPublication` 146 146 + 147 147 + ```typescript 148 148 + async fetchDocumentsByPublication( 149 149 + publicationUri: string, 150 150 + fetchFn?: typeof fetch 151 151 + ): Promise<AtProtoRecord<Document>[]> 152 152 + ``` 153 153 + 154 154 + Fetches all documents that belong to a specific publication. 155 155 + 156 156 + **Parameters:** 157 157 + 158 158 + - `publicationUri` (string): AT URI of the publication 159 159 + - `fetchFn` (typeof fetch, optional): Custom fetch function for SSR 160 160 + 161 161 + **Returns:** Promise resolving to an array of document records 162 162 + 163 163 + **Example:** 164 164 + 165 165 + ```typescript 166 166 + const docs = await client.fetchDocumentsByPublication( 167 167 + 'at://did:plc:xxx/site.standard.publication/3lwafzkjqm25s' 168 168 + ); 169 169 + ``` 170 170 + 171 171 + #### `fetchByAtUri` 172 172 + 173 173 + ```typescript 174 174 + async fetchByAtUri<T = Publication | Document>( 175 175 + atUri: string, 176 176 + fetchFn?: typeof fetch 177 177 + ): Promise<AtProtoRecord<T> | null> 178 178 + ``` 179 179 + 180 180 + Fetches a record by its full AT URI. 181 181 + 182 182 + **Parameters:** 183 183 + 184 184 + - `atUri` (string): Full AT URI of the record 185 185 + - `fetchFn` (typeof fetch, optional): Custom fetch function for SSR 186 186 + 187 187 + **Returns:** Promise resolving to the record or null if not found 188 188 + 189 189 + **Example:** 190 190 + 191 191 + ```typescript 192 192 + const record = await client.fetchByAtUri( 193 193 + 'at://did:plc:xxx/site.standard.publication/3lwafzkjqm25s' 194 194 + ); 195 195 + ``` 196 196 + 197 197 + #### `clearCache` 198 198 + 199 199 + ```typescript 200 200 + clearCache(): void 201 201 + ``` 202 202 + 203 203 + Clears all cached data. 204 204 + 205 205 + **Example:** 206 206 + 207 207 + ```typescript 208 208 + client.clearCache(); 209 209 + ``` 210 210 + 211 211 + #### `getPDS` 212 212 + 213 213 + ```typescript 214 214 + async getPDS(fetchFn?: typeof fetch): Promise<string> 215 215 + ``` 216 216 + 217 217 + Gets the resolved PDS endpoint for the configured DID. 218 218 + 219 219 + **Returns:** Promise resolving to the PDS URL 220 220 + 221 221 + **Example:** 222 222 + 223 223 + ```typescript 224 224 + const pds = await client.getPDS(); 225 225 + console.log('Using PDS:', pds); 226 226 + ``` 227 227 + 228 228 + ## Types 229 229 + 230 230 + ### SiteStandardConfig 231 231 + 232 232 + Configuration object for the client. 233 233 + 234 234 + ```typescript 235 235 + interface SiteStandardConfig { 236 236 + /** The DID to fetch records from */ 237 237 + did: string; 238 238 + /** Optional custom PDS endpoint */ 239 239 + pds?: string; 240 240 + /** Cache TTL in milliseconds (default: 5 minutes) */ 241 241 + cacheTTL?: number; 242 242 + } 243 243 + ``` 244 244 + 245 245 + ### Publication 246 246 + 247 247 + Represents a site.standard.publication record. 248 248 + 249 249 + ```typescript 250 250 + interface Publication { 251 251 + $type: 'site.standard.publication'; 252 252 + url: string; 253 253 + name: string; 254 254 + icon?: AtProtoBlob; 255 255 + description?: string; 256 256 + basicTheme?: BasicTheme; 257 257 + preferences?: PublicationPreferences; 258 258 + } 259 259 + ``` 260 260 + 261 261 + ### Document 262 262 + 263 263 + Represents a site.standard.document record. 264 264 + 265 265 + ```typescript 266 266 + interface Document { 267 267 + $type: 'site.standard.document'; 268 268 + site: string; // AT URI or HTTPS URL 269 269 + title: string; 270 270 + path?: string; 271 271 + description?: string; 272 272 + coverImage?: AtProtoBlob; 273 273 + content?: any; 274 274 + textContent?: string; 275 275 + bskyPostRef?: StrongRef; 276 276 + tags?: string[]; 277 277 + publishedAt: string; // ISO 8601 datetime 278 278 + updatedAt?: string; // ISO 8601 datetime 279 279 + } 280 280 + ``` 281 281 + 282 282 + ### AtProtoRecord 283 283 + 284 284 + Generic wrapper for AT Protocol records. 285 285 + 286 286 + ```typescript 287 287 + interface AtProtoRecord<T> { 288 288 + uri: string; // AT URI of the record 289 289 + cid: string; // Content identifier 290 290 + value: T; // The actual record value 291 291 + } 292 292 + ``` 293 293 + 294 294 + ### AtProtoBlob 295 295 + 296 296 + Represents a blob (file) in AT Protocol. 297 297 + 298 298 + ```typescript 299 299 + interface AtProtoBlob { 300 300 + $type: 'blob'; 301 301 + ref: { 302 302 + $link: string; // CID or full URL after enhancement 303 303 + }; 304 304 + mimeType: string; 305 305 + size: number; 306 306 + } 307 307 + ``` 308 308 + 309 309 + ### BasicTheme 310 310 + 311 311 + Theme configuration for a publication. 312 312 + 313 313 + ```typescript 314 314 + interface BasicTheme { 315 315 + $type: 'site.standard.theme.basic'; 316 316 + accentColor?: string; // Hex color 317 317 + backgroundColor?: string; // Hex color 318 318 + textColor?: string; // Hex color 319 319 + } 320 320 + ``` 321 321 + 322 322 + ### StrongRef 323 323 + 324 324 + Reference to another AT Protocol record. 325 325 + 326 326 + ```typescript 327 327 + interface StrongRef { 328 328 + uri: string; // AT URI 329 329 + cid: string; // Content identifier 330 330 + } 331 331 + ``` 332 332 + 333 333 + ### ResolvedIdentity 334 334 + 335 335 + Result of DID resolution. 336 336 + 337 337 + ```typescript 338 338 + interface ResolvedIdentity { 339 339 + did: string; 340 340 + pds: string; // PDS endpoint URL 341 341 + handle?: string; // User handle 342 342 + } 343 343 + ``` 344 344 + 345 345 + ## Utility Functions 346 346 + 347 347 + ### AT URI Utilities 348 348 + 349 349 + #### `parseAtUri` 350 350 + 351 351 + ```typescript 352 352 + function parseAtUri(atUri: string): ParsedAtUri | null; 353 353 + ``` 354 354 + 355 355 + Parses an AT URI into its components. 356 356 + 357 357 + **Example:** 358 358 + 359 359 + ```typescript 360 360 + import { parseAtUri } from 'svelte-standard-site'; 361 361 + 362 362 + const parsed = parseAtUri('at://did:plc:xxx/site.standard.publication/rkey'); 363 363 + // { did: 'did:plc:xxx', collection: 'site.standard.publication', rkey: 'rkey' } 364 364 + ``` 365 365 + 366 366 + #### `atUriToHttps` 367 367 + 368 368 + ```typescript 369 369 + function atUriToHttps(atUri: string, pdsEndpoint: string): string | null; 370 370 + ``` 371 371 + 372 372 + Converts an AT URI to an HTTPS URL for the getRecord XRPC endpoint. 373 373 + 374 374 + **Example:** 375 375 + 376 376 + ```typescript 377 377 + import { atUriToHttps } from 'svelte-standard-site'; 378 378 + 379 379 + const url = atUriToHttps( 380 380 + 'at://did:plc:xxx/site.standard.publication/rkey', 381 381 + 'https://pds.example.com' 382 382 + ); 383 383 + ``` 384 384 + 385 385 + #### `buildAtUri` 386 386 + 387 387 + ```typescript 388 388 + function buildAtUri(did: string, collection: string, rkey: string): string; 389 389 + ``` 390 390 + 391 391 + Constructs an AT URI from components. 392 392 + 393 393 + **Example:** 394 394 + 395 395 + ```typescript 396 396 + import { buildAtUri } from 'svelte-standard-site'; 397 397 + 398 398 + const uri = buildAtUri('did:plc:xxx', 'site.standard.publication', 'rkey'); 399 399 + // 'at://did:plc:xxx/site.standard.publication/rkey' 400 400 + ``` 401 401 + 402 402 + #### `extractRkey` 403 403 + 404 404 + ```typescript 405 405 + function extractRkey(atUri: string): string | null; 406 406 + ``` 407 407 + 408 408 + Extracts the record key from an AT URI. 409 409 + 410 410 + **Example:** 411 411 + 412 412 + ```typescript 413 413 + import { extractRkey } from 'svelte-standard-site'; 414 414 + 415 415 + const rkey = extractRkey('at://did:plc:xxx/site.standard.publication/3lwafzkjqm25s'); 416 416 + // '3lwafzkjqm25s' 417 417 + ``` 418 418 + 419 419 + #### `isAtUri` 420 420 + 421 421 + ```typescript 422 422 + function isAtUri(uri: string): boolean; 423 423 + ``` 424 424 + 425 425 + Validates if a string is a valid AT URI. 426 426 + 427 427 + **Example:** 428 428 + 429 429 + ```typescript 430 430 + import { isAtUri } from 'svelte-standard-site'; 431 431 + 432 432 + console.log(isAtUri('at://did:plc:xxx/collection/rkey')); // true 433 433 + console.log(isAtUri('https://example.com')); // false 434 434 + ``` 435 435 + 436 436 + ### Agent Utilities 437 437 + 438 438 + #### `resolveIdentity` 439 439 + 440 440 + ```typescript 441 441 + async function resolveIdentity(did: string, fetchFn?: typeof fetch): Promise<ResolvedIdentity>; 442 442 + ``` 443 443 + 444 444 + Resolves a DID to its PDS endpoint using Slingshot. 445 445 + 446 446 + **Example:** 447 447 + 448 448 + ```typescript 449 449 + import { resolveIdentity } from 'svelte-standard-site'; 450 450 + 451 451 + const identity = await resolveIdentity('did:plc:xxx'); 452 452 + console.log(identity.pds); // 'https://...' 453 453 + ``` 454 454 + 455 455 + #### `buildPdsBlobUrl` 456 456 + 457 457 + ```typescript 458 458 + function buildPdsBlobUrl(pds: string, did: string, cid: string): string; 459 459 + ``` 460 460 + 461 461 + Constructs a blob URL for retrieving files from a PDS. 462 462 + 463 463 + **Example:** 464 464 + 465 465 + ```typescript 466 466 + import { buildPdsBlobUrl } from 'svelte-standard-site'; 467 467 + 468 468 + const url = buildPdsBlobUrl('https://pds.example.com', 'did:plc:xxx', 'bafyrei...'); 469 469 + ``` 470 470 + 471 471 + ### Cache 472 472 + 473 473 + #### `cache` 474 474 + 475 475 + Global cache instance used by the library. 476 476 + 477 477 + ```typescript 478 478 + const cache: Cache; 479 479 + ``` 480 480 + 481 481 + **Methods:** 482 482 + 483 483 + - `get<T>(key: string): T | null` - Get cached value 484 484 + - `set<T>(key: string, value: T, ttl?: number): void` - Set cached value 485 485 + - `delete(key: string): void` - Delete cached value 486 486 + - `clear(): void` - Clear all cached values 487 487 + - `setDefaultTTL(ttl: number): void` - Set default TTL 488 488 + 489 489 + **Example:** 490 490 + 491 491 + ```typescript 492 492 + import { cache } from 'svelte-standard-site'; 493 493 + 494 494 + // Manual cache manipulation 495 495 + const data = cache.get('my-key'); 496 496 + cache.set('my-key', { some: 'data' }, 60000); 497 497 + cache.clear(); 498 498 + ``` 499 499 + 500 500 + ## Components 501 501 + 502 502 + ### PublicationCard 503 503 + 504 504 + Displays a publication card with icon, name, description, and link. 505 505 + 506 506 + **Props:** 507 507 + 508 508 + ```typescript 509 509 + interface Props { 510 510 + publication: AtProtoRecord<Publication>; 511 511 + class?: string; 512 512 + } 513 513 + ``` 514 514 + 515 515 + **Example:** 516 516 + 517 517 + ```svelte 518 518 + <script> 519 519 + import { PublicationCard } from 'svelte-standard-site'; 520 520 + 521 521 + export let data; 522 522 + </script> 523 523 + 524 524 + <PublicationCard publication={data.publication} class="my-custom-class" /> 525 525 + ``` 526 526 + 527 527 + **Styling:** 528 528 + 529 529 + The component uses scoped CSS but exposes the following classes for customization: 530 530 + 531 531 + - `.publication-card` 532 532 + - `.publication-header` 533 533 + - `.publication-icon` 534 534 + - `.publication-info` 535 535 + - `.publication-name` 536 536 + - `.publication-description` 537 537 + - `.publication-link` 538 538 + 539 539 + ### DocumentCard 540 540 + 541 541 + Displays a document card with cover image, title, description, metadata, and tags. 542 542 + 543 543 + **Props:** 544 544 + 545 545 + ```typescript 546 546 + interface Props { 547 547 + document: AtProtoRecord<Document>; 548 548 + class?: string; 549 549 + showCover?: boolean; 550 550 + } 551 551 + ``` 552 552 + 553 553 + **Example:** 554 554 + 555 555 + ```svelte 556 556 + <script> 557 557 + import { DocumentCard } from 'svelte-standard-site'; 558 558 + 559 559 + export let data; 560 560 + </script> 561 561 + 562 562 + <DocumentCard document={data.document} showCover={true} class="my-custom-class" /> 563 563 + ``` 564 564 + 565 565 + **Styling:** 566 566 + 567 567 + The component uses scoped CSS but exposes the following classes: 568 568 + 569 569 + - `.document-card` 570 570 + - `.document-content` 571 571 + - `.document-cover` 572 572 + - `.document-body` 573 573 + - `.document-title` 574 574 + - `.document-description` 575 575 + - `.document-meta` 576 576 + - `.document-date` 577 577 + - `.document-updated` 578 578 + - `.document-tags` 579 579 + - `.tag` 580 580 + 581 581 + ## Configuration 582 582 + 583 583 + ### Environment Variables 584 584 + 585 585 + #### `getConfigFromEnv` 586 586 + 587 587 + ```typescript 588 588 + function getConfigFromEnv(): SiteStandardConfig | null; 589 589 + ``` 590 590 + 591 591 + Reads configuration from environment variables. 592 592 + 593 593 + **Environment Variables:** 594 594 + 595 595 + - `PUBLIC_ATPROTO_DID` (required): The DID to fetch records from 596 596 + - `PUBLIC_ATPROTO_PDS` (optional): Custom PDS endpoint 597 597 + - `PUBLIC_CACHE_TTL` (optional): Cache TTL in milliseconds 598 598 + 599 599 + **Example:** 600 600 + 601 601 + ```typescript 602 602 + import { getConfigFromEnv } from 'svelte-standard-site/config/env'; 603 603 + 604 604 + const config = getConfigFromEnv(); 605 605 + if (config) { 606 606 + const client = createClient(config); 607 607 + } 608 608 + ``` 609 609 + 610 610 + #### `validateEnv` 611 611 + 612 612 + ```typescript 613 613 + function validateEnv(): void; 614 614 + ``` 615 615 + 616 616 + Validates that required environment variables are set. Throws an error if validation fails. 617 617 + 618 618 + **Example:** 619 619 + 620 620 + ```typescript 621 621 + import { validateEnv } from 'svelte-standard-site/config/env'; 622 622 + 623 623 + try { 624 624 + validateEnv(); 625 625 + } catch (error) { 626 626 + console.error('Missing required environment variables'); 627 627 + } 628 628 + ```

+203

CONTRIBUTING.md

··· 1 1 + # Contributing to svelte-standard-site 2 2 + 3 3 + Thank you for your interest in contributing! This document provides guidelines and information for contributors. 4 4 + 5 5 + ## Getting Started 6 6 + 7 7 + ### Prerequisites 8 8 + 9 9 + - Node.js 18 or higher 10 10 + - pnpm 8 or higher 11 11 + 12 12 + ### Setup 13 13 + 14 14 + 1. Fork and clone the repository: 15 15 + 16 16 + ```bash 17 17 + git clone https://github.com/your-username/svelte-standard-site.git 18 18 + cd svelte-standard-site 19 19 + ``` 20 20 + 21 21 + 2. Install dependencies: 22 22 + 23 23 + ```bash 24 24 + pnpm install 25 25 + ``` 26 26 + 27 27 + 3. Create a `.env` file: 28 28 + 29 29 + ```bash 30 30 + cp .env.example .env 31 31 + # Edit .env and add your PUBLIC_ATPROTO_DID 32 32 + ``` 33 33 + 34 34 + 4. Start the development server: 35 35 + 36 36 + ```bash 37 37 + pnpm dev 38 38 + ``` 39 39 + 40 40 + ## Development Workflow 41 41 + 42 42 + ### Project Structure 43 43 + 44 44 + ``` 45 45 + src/ 46 46 + ├── lib/ # Library source code 47 47 + │ ├── client.ts # Main client implementation 48 48 + │ ├── types.ts # TypeScript type definitions 49 49 + │ ├── index.ts # Public API exports 50 50 + │ ├── components/ # Reusable Svelte components 51 51 + │ │ ├── PublicationCard.svelte 52 52 + │ │ └── DocumentCard.svelte 53 53 + │ ├── config/ # Configuration utilities 54 54 + │ │ └── env.ts # Environment variable handling 55 55 + │ └── utils/ # Utility functions 56 56 + │ ├── agents.ts # AT Protocol agent utilities 57 57 + │ ├── at-uri.ts # AT URI parsing utilities 58 58 + │ └── cache.ts # Caching implementation 59 59 + └── routes/ # Demo/showcase pages 60 60 + ├── +page.svelte 61 61 + └── +page.server.ts 62 62 + ``` 63 63 + 64 64 + ### Commands 65 65 + 66 66 + - `pnpm dev` - Start development server 67 67 + - `pnpm build` - Build the library 68 68 + - `pnpm check` - Run type checking 69 69 + - `pnpm format` - Format code with Prettier 70 70 + - `pnpm lint` - Check code formatting 71 71 + - `pnpm prepack` - Prepare package for publishing 72 72 + 73 73 + ## Making Changes 74 74 + 75 75 + ### Code Style 76 76 + 77 77 + - We use Prettier for code formatting 78 78 + - Run `pnpm format` before committing 79 79 + - TypeScript strict mode is enabled 80 80 + - Follow the existing code structure and patterns 81 81 + 82 82 + ### Commit Messages 83 83 + 84 84 + We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: 85 85 + 86 86 + - `feat:` - New features 87 87 + - `fix:` - Bug fixes 88 88 + - `docs:` - Documentation changes 89 89 + - `style:` - Code style changes (formatting, etc.) 90 90 + - `refactor:` - Code refactoring 91 91 + - `test:` - Test additions or changes 92 92 + - `chore:` - Build process or tooling changes 93 93 + 94 94 + Example: 95 95 + 96 96 + ``` 97 97 + feat: add support for custom PDS endpoints 98 98 + fix: resolve caching issue with blob URLs 99 99 + docs: update README with new examples 100 100 + ``` 101 101 + 102 102 + ### Pull Request Process 103 103 + 104 104 + 1. Create a new branch: 105 105 + 106 106 + ```bash 107 107 + git checkout -b feat/your-feature-name 108 108 + ``` 109 109 + 110 110 + 2. Make your changes and commit them: 111 111 + 112 112 + ```bash 113 113 + git add . 114 114 + git commit -m "feat: add your feature" 115 115 + ``` 116 116 + 117 117 + 3. Push to your fork: 118 118 + 119 119 + ```bash 120 120 + git push origin feat/your-feature-name 121 121 + ``` 122 122 + 123 123 + 4. Open a Pull Request on GitHub 124 124 + 125 125 + 5. Ensure: 126 126 + - Code passes type checking (`pnpm check`) 127 127 + - Code is properly formatted (`pnpm format`) 128 128 + - Documentation is updated if needed 129 129 + - Examples are added for new features 130 130 + 131 131 + ## What to Contribute 132 132 + 133 133 + ### Good First Issues 134 134 + 135 135 + Look for issues labeled `good first issue` for beginner-friendly tasks. 136 136 + 137 137 + ### Areas for Contribution 138 138 + 139 139 + - **Bug Fixes**: Report and fix bugs 140 140 + - **Features**: Implement new features (discuss in an issue first) 141 141 + - **Documentation**: Improve or expand documentation 142 142 + - **Examples**: Add new usage examples 143 143 + - **Components**: Create new reusable components 144 144 + - **Tests**: Add or improve test coverage 145 145 + - **Performance**: Optimize existing code 146 146 + 147 147 + ## Reporting Bugs 148 148 + 149 149 + When reporting bugs, please include: 150 150 + 151 151 + 1. A clear description of the issue 152 152 + 2. Steps to reproduce 153 153 + 3. Expected behavior 154 154 + 4. Actual behavior 155 155 + 5. Environment details (Node version, OS, etc.) 156 156 + 6. Code samples if applicable 157 157 + 158 158 + ## Feature Requests 159 159 + 160 160 + For feature requests: 161 161 + 162 162 + 1. Check if the feature already exists or is planned 163 163 + 2. Open an issue describing: 164 164 + - The problem you're trying to solve 165 165 + - Your proposed solution 166 166 + - Any alternatives you've considered 167 167 + - Examples of the desired behavior 168 168 + 169 169 + ## Code of Conduct 170 170 + 171 171 + ### Our Pledge 172 172 + 173 173 + We are committed to providing a friendly, safe, and welcoming environment for all contributors. 174 174 + 175 175 + ### Expected Behavior 176 176 + 177 177 + - Be respectful and inclusive 178 178 + - Welcome newcomers 179 179 + - Accept constructive criticism gracefully 180 180 + - Focus on what's best for the community 181 181 + - Show empathy towards others 182 182 + 183 183 + ### Unacceptable Behavior 184 184 + 185 185 + - Harassment of any kind 186 186 + - Discriminatory language or actions 187 187 + - Personal attacks 188 188 + - Publishing others' private information 189 189 + - Other conduct which could reasonably be considered inappropriate 190 190 + 191 191 + ## Questions? 192 192 + 193 193 + Feel free to: 194 194 + 195 195 + - Open an issue for questions 196 196 + - Start a discussion in GitHub Discussions 197 197 + - Reach out to maintainers 198 198 + 199 199 + ## License 200 200 + 201 201 + By contributing, you agree that your contributions will be licensed under the MIT License. 202 202 + 203 203 + Thank you for contributing to svelte-standard-site! 🎉

+448

EXAMPLES.md

··· 1 1 + # Usage Examples 2 2 + 3 3 + This document provides comprehensive examples of using the svelte-standard-site library. 4 4 + 5 5 + ## Basic Setup 6 6 + 7 7 + ### 1. Install the Package 8 8 + 9 9 + ```bash 10 10 + pnpm add svelte-standard-site 11 11 + ``` 12 12 + 13 13 + ### 2. Configure Environment Variables 14 14 + 15 15 + Create a `.env` file: 16 16 + 17 17 + ```env 18 18 + PUBLIC_ATPROTO_DID=did:plc:revjuqmkvrw6fnkxppqtszpv 19 19 + ``` 20 20 + 21 21 + ## Example 1: Simple Blog List 22 22 + 23 23 + Fetch and display all documents as blog posts. 24 24 + 25 25 + ```typescript 26 26 + // src/routes/blog/+page.server.ts 27 27 + import { createClient } from 'svelte-standard-site'; 28 28 + import { PUBLIC_ATPROTO_DID } from '$env/static/public'; 29 29 + import type { PageServerLoad } from './$types'; 30 30 + 31 31 + export const load: PageServerLoad = async ({ fetch }) => { 32 32 + const client = createClient({ did: PUBLIC_ATPROTO_DID }); 33 33 + const documents = await client.fetchAllDocuments(fetch); 34 34 + 35 35 + return { 36 36 + posts: documents 37 37 + }; 38 38 + }; 39 39 + ``` 40 40 + 41 41 + ```svelte 42 42 + <!-- src/routes/blog/+page.svelte --> 43 43 + <script lang="ts"> 44 44 + import { DocumentCard } from 'svelte-standard-site'; 45 45 + import type { PageData } from './$types'; 46 46 + 47 47 + const { data }: { data: PageData } = $props(); 48 48 + </script> 49 49 + 50 50 + <div class="container"> 51 51 + <h1>Blog Posts</h1> 52 52 + <div class="posts"> 53 53 + {#each data.posts as post} 54 54 + <DocumentCard document={post} /> 55 55 + {/each} 56 56 + </div> 57 57 + </div> 58 58 + ``` 59 59 + 60 60 + ## Example 2: Single Post Page 61 61 + 62 62 + Display a single document by its record key (slug). 63 63 + 64 64 + ```typescript 65 65 + // src/routes/blog/[slug]/+page.server.ts 66 66 + import { createClient } from 'svelte-standard-site'; 67 67 + import { PUBLIC_ATPROTO_DID } from '$env/static/public'; 68 68 + import { error } from '@sveltejs/kit'; 69 69 + import type { PageServerLoad } from './$types'; 70 70 + 71 71 + export const load: PageServerLoad = async ({ params, fetch }) => { 72 72 + const client = createClient({ did: PUBLIC_ATPROTO_DID }); 73 73 + const document = await client.fetchDocument(params.slug, fetch); 74 74 + 75 75 + if (!document) { 76 76 + throw error(404, 'Post not found'); 77 77 + } 78 78 + 79 79 + return { 80 80 + post: document 81 81 + }; 82 82 + }; 83 83 + ``` 84 84 + 85 85 + ```svelte 86 86 + <!-- src/routes/blog/[slug]/+page.svelte --> 87 87 + <script lang="ts"> 88 88 + import type { PageData } from './$types'; 89 89 + 90 90 + const { data }: { data: PageData } = $props(); 91 91 + const post = data.post.value; 92 92 + </script> 93 93 + 94 94 + <article> 95 95 + {#if post.coverImage} 96 96 + <img src={post.coverImage.ref.$link} alt={post.title} /> 97 97 + {/if} 98 98 + 99 99 + <h1>{post.title}</h1> 100 100 + 101 101 + <div class="meta"> 102 102 + <time>{new Date(post.publishedAt).toLocaleDateString()}</time> 103 103 + {#if post.tags} 104 104 + <div class="tags"> 105 105 + {#each post.tags as tag} 106 106 + <span class="tag">{tag}</span> 107 107 + {/each} 108 108 + </div> 109 109 + {/if} 110 110 + </div> 111 111 + 112 112 + {#if post.description} 113 113 + <p class="description">{post.description}</p> 114 114 + {/if} 115 115 + 116 116 + {#if post.textContent} 117 117 + <div class="content"> 118 118 + {post.textContent} 119 119 + </div> 120 120 + {/if} 121 121 + </article> 122 122 + ``` 123 123 + 124 124 + ## Example 3: Publication-Filtered Posts 125 125 + 126 126 + Display documents from a specific publication. 127 127 + 128 128 + ```typescript 129 129 + // src/routes/publications/[pubkey]/+page.server.ts 130 130 + import { createClient, buildAtUri } from 'svelte-standard-site'; 131 131 + import { PUBLIC_ATPROTO_DID } from '$env/static/public'; 132 132 + import { error } from '@sveltejs/kit'; 133 133 + import type { PageServerLoad } from './$types'; 134 134 + 135 135 + export const load: PageServerLoad = async ({ params, fetch }) => { 136 136 + const client = createClient({ did: PUBLIC_ATPROTO_DID }); 137 137 + 138 138 + // Fetch the publication 139 139 + const publication = await client.fetchPublication(params.pubkey, fetch); 140 140 + if (!publication) { 141 141 + throw error(404, 'Publication not found'); 142 142 + } 143 143 + 144 144 + // Fetch documents for this publication 145 145 + const publicationUri = buildAtUri(PUBLIC_ATPROTO_DID, 'site.standard.publication', params.pubkey); 146 146 + const documents = await client.fetchDocumentsByPublication(publicationUri, fetch); 147 147 + 148 148 + return { 149 149 + publication, 150 150 + documents 151 151 + }; 152 152 + }; 153 153 + ``` 154 154 + 155 155 + ```svelte 156 156 + <!-- src/routes/publications/[pubkey]/+page.svelte --> 157 157 + <script lang="ts"> 158 158 + import { PublicationCard, DocumentCard } from 'svelte-standard-site'; 159 159 + import type { PageData } from './$types'; 160 160 + 161 161 + const { data }: { data: PageData } = $props(); 162 162 + </script> 163 163 + 164 164 + <div class="publication-page"> 165 165 + <PublicationCard publication={data.publication} /> 166 166 + 167 167 + <h2>Posts in this Publication</h2> 168 168 + <div class="documents"> 169 169 + {#each data.documents as doc} 170 170 + <DocumentCard document={doc} /> 171 171 + {/each} 172 172 + </div> 173 173 + </div> 174 174 + ``` 175 175 + 176 176 + ## Example 4: Using AT URIs 177 177 + 178 178 + Fetch a record using its full AT URI. 179 179 + 180 180 + ```typescript 181 181 + import { createClient } from 'svelte-standard-site'; 182 182 + 183 183 + const client = createClient({ did: 'did:plc:revjuqmkvrw6fnkxppqtszpv' }); 184 184 + 185 185 + // Fetch using AT URI 186 186 + const publication = await client.fetchByAtUri( 187 187 + 'at://did:plc:revjuqmkvrw6fnkxppqtszpv/site.standard.publication/3lwafzkjqm25s' 188 188 + ); 189 189 + 190 190 + console.log(publication?.value.name); 191 191 + ``` 192 192 + 193 193 + ## Example 5: Manual Configuration 194 194 + 195 195 + Configure the client without environment variables. 196 196 + 197 197 + ```typescript 198 198 + import { createClient } from 'svelte-standard-site'; 199 199 + 200 200 + const client = createClient({ 201 201 + did: 'did:plc:revjuqmkvrw6fnkxppqtszpv', 202 202 + pds: 'https://cortinarius.us-west.host.bsky.network', 203 203 + cacheTTL: 600000 // 10 minutes 204 204 + }); 205 205 + ``` 206 206 + 207 207 + ## Example 6: Custom Publication Listing 208 208 + 209 209 + Create a custom component to display publications. 210 210 + 211 211 + ```svelte 212 212 + <script lang="ts"> 213 213 + import type { AtProtoRecord, Publication } from 'svelte-standard-site'; 214 214 + 215 215 + interface Props { 216 216 + publications: AtProtoRecord<Publication>[]; 217 217 + } 218 218 + 219 219 + const { publications }: Props = $props(); 220 220 + </script> 221 221 + 222 222 + <div class="publications-grid"> 223 223 + {#each publications as pub} 224 224 + <a href="/pub/{pub.uri.split('/').pop()}" class="pub-card"> 225 225 + {#if pub.value.icon} 226 226 + <img src={pub.value.icon.ref.$link} alt={pub.value.name} /> 227 227 + {/if} 228 228 + <h3>{pub.value.name}</h3> 229 229 + <p>{pub.value.description}</p> 230 230 + </a> 231 231 + {/each} 232 232 + </div> 233 233 + 234 234 + <style> 235 235 + .publications-grid { 236 236 + display: grid; 237 237 + grid-template-columns: repeat(auto-fill, minmax(250px, 1fr)); 238 238 + gap: 1.5rem; 239 239 + } 240 240 + 241 241 + .pub-card { 242 242 + padding: 1.5rem; 243 243 + border: 1px solid #e5e7eb; 244 244 + border-radius: 0.5rem; 245 245 + text-decoration: none; 246 246 + color: inherit; 247 247 + transition: all 0.2s; 248 248 + } 249 249 + 250 250 + .pub-card:hover { 251 251 + border-color: #3b82f6; 252 252 + box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1); 253 253 + } 254 254 + 255 255 + .pub-card img { 256 256 + width: 100%; 257 257 + height: 150px; 258 258 + object-fit: cover; 259 259 + border-radius: 0.375rem; 260 260 + margin-bottom: 1rem; 261 261 + } 262 262 + 263 263 + .pub-card h3 { 264 264 + font-size: 1.25rem; 265 265 + font-weight: 600; 266 266 + margin-bottom: 0.5rem; 267 267 + } 268 268 + 269 269 + .pub-card p { 270 270 + font-size: 0.875rem; 271 271 + color: #6b7280; 272 272 + } 273 273 + </style> 274 274 + ``` 275 275 + 276 276 + ## Example 7: Search and Filter 277 277 + 278 278 + Implement search and tag filtering. 279 279 + 280 280 + ```typescript 281 281 + // src/routes/search/+page.server.ts 282 282 + import { createClient } from 'svelte-standard-site'; 283 283 + import { PUBLIC_ATPROTO_DID } from '$env/static/public'; 284 284 + import type { PageServerLoad } from './$types'; 285 285 + 286 286 + export const load: PageServerLoad = async ({ url, fetch }) => { 287 287 + const client = createClient({ did: PUBLIC_ATPROTO_DID }); 288 288 + const documents = await client.fetchAllDocuments(fetch); 289 289 + 290 290 + const query = url.searchParams.get('q')?.toLowerCase() || ''; 291 291 + const tag = url.searchParams.get('tag') || ''; 292 292 + 293 293 + const filtered = documents.filter((doc) => { 294 294 + const matchesQuery = 295 295 + !query || 296 296 + doc.value.title.toLowerCase().includes(query) || 297 297 + doc.value.description?.toLowerCase().includes(query) || 298 298 + doc.value.textContent?.toLowerCase().includes(query); 299 299 + 300 300 + const matchesTag = !tag || doc.value.tags?.includes(tag); 301 301 + 302 302 + return matchesQuery && matchesTag; 303 303 + }); 304 304 + 305 305 + // Get all unique tags 306 306 + const allTags = new Set<string>(); 307 307 + documents.forEach((doc) => { 308 308 + doc.value.tags?.forEach((t) => allTags.add(t)); 309 309 + }); 310 310 + 311 311 + return { 312 312 + documents: filtered, 313 313 + tags: Array.from(allTags).sort(), 314 314 + query, 315 315 + selectedTag: tag 316 316 + }; 317 317 + }; 318 318 + ``` 319 319 + 320 320 + ## Example 8: RSS Feed 321 321 + 322 322 + Generate an RSS feed from documents. 323 323 + 324 324 + ```typescript 325 325 + // src/routes/rss.xml/+server.ts 326 326 + import { createClient } from 'svelte-standard-site'; 327 327 + import { PUBLIC_ATPROTO_DID } from '$env/static/public'; 328 328 + import type { RequestHandler } from './$types'; 329 329 + 330 330 + export const GET: RequestHandler = async ({ fetch }) => { 331 331 + const client = createClient({ did: PUBLIC_ATPROTO_DID }); 332 332 + const documents = await client.fetchAllDocuments(fetch); 333 333 + 334 334 + const rss = `<?xml version="1.0" encoding="UTF-8"?> 335 335 + <rss version="2.0"> 336 336 + <channel> 337 337 + <title>My Blog</title> 338 338 + <link>https://example.com</link> 339 339 + <description>Blog posts from AT Protocol</description> 340 340 + ${documents 341 341 + .map( 342 342 + (doc) => ` 343 343 + <item> 344 344 + <title>${escapeXml(doc.value.title)}</title> 345 345 + <description>${escapeXml(doc.value.description || '')}</description> 346 346 + <pubDate>${new Date(doc.value.publishedAt).toUTCString()}</pubDate> 347 347 + <guid>${doc.uri}</guid> 348 348 + </item>` 349 349 + ) 350 350 + .join('')} 351 351 + </channel> 352 352 + </rss>`; 353 353 + 354 354 + return new Response(rss, { 355 355 + headers: { 356 356 + 'Content-Type': 'application/xml' 357 357 + } 358 358 + }); 359 359 + }; 360 360 + 361 361 + function escapeXml(str: string): string { 362 362 + return str 363 363 + .replace(/&/g, '&amp;') 364 364 + .replace(/</g, '&lt;') 365 365 + .replace(/>/g, '&gt;') 366 366 + .replace(/"/g, '&quot;') 367 367 + .replace(/'/g, '&apos;'); 368 368 + } 369 369 + ``` 370 370 + 371 371 + ## Example 9: Sitemap Generation 372 372 + 373 373 + Generate a sitemap from documents. 374 374 + 375 375 + ```typescript 376 376 + // src/routes/sitemap.xml/+server.ts 377 377 + import { createClient } from 'svelte-standard-site'; 378 378 + import { PUBLIC_ATPROTO_DID } from '$env/static/public'; 379 379 + import type { RequestHandler } from './$types'; 380 380 + 381 381 + export const GET: RequestHandler = async ({ fetch }) => { 382 382 + const client = createClient({ did: PUBLIC_ATPROTO_DID }); 383 383 + const documents = await client.fetchAllDocuments(fetch); 384 384 + 385 385 + const sitemap = `<?xml version="1.0" encoding="UTF-8"?> 386 386 + <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"> 387 387 + <url> 388 388 + <loc>https://example.com</loc> 389 389 + <changefreq>daily</changefreq> 390 390 + <priority>1.0</priority> 391 391 + </url> 392 392 + ${documents 393 393 + .map((doc) => { 394 394 + const slug = doc.uri.split('/').pop(); 395 395 + return ` 396 396 + <url> 397 397 + <loc>https://example.com/blog/${slug}</loc> 398 398 + <lastmod>${new Date(doc.value.updatedAt || doc.value.publishedAt).toISOString()}</lastmod> 399 399 + <changefreq>weekly</changefreq> 400 400 + <priority>0.8</priority> 401 401 + </url>`; 402 402 + }) 403 403 + .join('')} 404 404 + </urlset>`; 405 405 + 406 406 + return new Response(sitemap, { 407 407 + headers: { 408 408 + 'Content-Type': 'application/xml' 409 409 + } 410 410 + }); 411 411 + }; 412 412 + ``` 413 413 + 414 414 + ## Example 10: Client-Side Usage 415 415 + 416 416 + Use the client in browser context (not recommended for production due to CORS, but useful for prototyping). 417 417 + 418 418 + ```svelte 419 419 + <script lang="ts"> 420 420 + import { createClient } from 'svelte-standard-site'; 421 421 + import { onMount } from 'svelte'; 422 422 + 423 423 + let documents = $state([]); 424 424 + let loading = $state(true); 425 425 + 426 426 + onMount(async () => { 427 427 + const client = createClient({ did: 'did:plc:revjuqmkvrw6fnkxppqtszpv' }); 428 428 + documents = await client.fetchAllDocuments(); 429 429 + loading = false; 430 430 + }); 431 431 + </script> 432 432 + 433 433 + {#if loading} 434 434 + <p>Loading...</p> 435 435 + {:else} 436 436 + {#each documents as doc} 437 437 + <div>{doc.value.title}</div> 438 438 + {/each} 439 439 + {/if} 440 440 + ``` 441 441 + 442 442 + ## Best Practices 443 443 + 444 444 + 1. **Always use SSR**: Fetch data in `+page.server.ts` or `+layout.server.ts` for better performance and SEO 445 445 + 2. **Pass fetch function**: Always pass SvelteKit's `fetch` to client methods for proper SSR hydration 446 446 + 3. **Handle errors**: Wrap client calls in try-catch and provide user-friendly error messages 447 447 + 4. **Use caching**: The built-in cache reduces API calls, but you can adjust TTL as needed 448 448 + 5. **Type safety**: Import and use TypeScript types for better developer experience

+303 -31

README.md

··· 1 1 - # Svelte library 1 1 + # svelte-standard-site 2 2 3 3 - Everything you need to build a Svelte library, powered by [`sv`](https://npmjs.com/package/sv). 3 3 + A SvelteKit library for fetching and working with `site.standard.*` records from the AT Protocol. 4 4 5 5 - Read more about creating a library [in the docs](https://svelte.dev/docs/kit/packaging). 5 5 + ## Features 6 6 7 7 - ## Creating a project 7 7 + - 🔄 **Automatic PDS Resolution** - Resolves DIDs to their Personal Data Server endpoints 8 8 + - 📦 **Type-Safe** - Full TypeScript support with complete type definitions 9 9 + - 🚀 **SSR Ready** - Works seamlessly with SvelteKit's server-side rendering 10 10 + - 💾 **Built-in Caching** - Reduces API calls with intelligent caching 11 11 + - 🎯 **Simple API** - Easy to use, set it and forget it configuration 12 12 + - 🔗 **AT URI Support** - Parse and convert AT URIs to HTTPS URLs 8 13 9 9 - If you're seeing this, you've probably already done this step. Congrats! 14 14 + ## Installation 10 15 11 11 - ```sh 12 12 - # create a new project in the current directory 13 13 - npx sv create 16 16 + ```bash 17 17 + pnpm add svelte-standard-site 18 18 + # or 19 19 + npm install svelte-standard-site 20 20 + # or 21 21 + yarn add svelte-standard-site 22 22 + ``` 14 23 15 15 - # create a new project in my-app 16 16 - npx sv create my-app 24 24 + ## Quick Start 25 25 + 26 26 + ### 1. Configure Environment Variables 27 27 + 28 28 + Create a `.env` file in your project root: 29 29 + 30 30 + ```env 31 31 + PUBLIC_ATPROTO_DID=did:plc:your-did-here 32 32 + # Optional: specify a custom PDS endpoint 33 33 + PUBLIC_ATPROTO_PDS=https://your-pds.example.com 34 34 + # Optional: cache TTL in milliseconds (default: 300000 = 5 minutes) 35 35 + PUBLIC_CACHE_TTL=300000 17 36 ``` 18 37 19 19 - ## Developing 38 38 + ### 2. Create a Client 20 39 21 21 - Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server: 40 40 + ```typescript 41 41 + import { createClient } from 'svelte-standard-site'; 22 42 23 23 - ```sh 24 24 - npm run dev 43 43 + const client = createClient({ 44 44 + did: 'did:plc:revjuqmkvrw6fnkxppqtszpv' 45 45 + }); 46 46 + 47 47 + // Fetch a single publication 48 48 + const publication = await client.fetchPublication('3lwafzkjqm25s'); 49 49 + 50 50 + // Fetch all publications 51 51 + const publications = await client.fetchAllPublications(); 52 52 + 53 53 + // Fetch all documents 54 54 + const documents = await client.fetchAllDocuments(); 55 55 + 56 56 + // Fetch documents for a specific publication 57 57 + const pubDocs = await client.fetchDocumentsByPublication( 58 58 + 'at://did:plc:revjuqmkvrw6fnkxppqtszpv/site.standard.publication/3lwafzkjqm25s' 59 59 + ); 60 60 + ``` 61 61 + 62 62 + ### 3. Use in SvelteKit Load Functions 63 63 + 64 64 + ```typescript 65 65 + // src/routes/+page.server.ts 66 66 + import { createClient } from 'svelte-standard-site'; 67 67 + import { getConfigFromEnv } from 'svelte-standard-site/config/env'; 68 68 + import type { PageServerLoad } from './$types'; 69 69 + 70 70 + export const load: PageServerLoad = async ({ fetch }) => { 71 71 + const config = getConfigFromEnv(); 72 72 + if (!config) { 73 73 + throw new Error('Missing configuration'); 74 74 + } 75 75 + 76 76 + const client = createClient(config); 77 77 + 78 78 + const [publications, documents] = await Promise.all([ 79 79 + client.fetchAllPublications(fetch), 80 80 + client.fetchAllDocuments(fetch) 81 81 + ]); 25 82 26 26 - # or start the server and open the app in a new browser tab 27 27 - npm run dev -- --open 83 83 + return { 84 84 + publications, 85 85 + documents 86 86 + }; 87 87 + }; 28 88 ``` 29 89 30 30 - Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app. 90 90 + ```svelte 91 91 + <!-- src/routes/+page.svelte --> 92 92 + <script lang="ts"> 93 93 + import type { PageData } from './$types'; 31 94 32 32 - ## Building 95 95 + const { data }: { data: PageData } = $props(); 96 96 + </script> 33 97 34 34 - To build your library: 98 98 + <h1>Publications</h1> 99 99 + {#each data.publications as pub} 100 100 + <article> 101 101 + <h2>{pub.value.name}</h2> 102 102 + <p>{pub.value.description}</p> 103 103 + <a href={pub.value.url}>Visit</a> 104 104 + </article> 105 105 + {/each} 35 106 36 36 - ```sh 37 37 - npm pack 107 107 + <h1>Documents</h1> 108 108 + {#each data.documents as doc} 109 109 + <article> 110 110 + <h2>{doc.value.title}</h2> 111 111 + <p>{doc.value.description}</p> 112 112 + <time>{new Date(doc.value.publishedAt).toLocaleDateString()}</time> 113 113 + </article> 114 114 + {/each} 38 115 ``` 39 116 40 40 - To create a production version of your showcase app: 117 117 + ## API Reference 118 118 + 119 119 + ### `SiteStandardClient` 120 120 + 121 121 + The main client for interacting with site.standard records. 122 122 + 123 123 + #### Constructor 41 124 42 42 - ```sh 43 43 - npm run build 125 125 + ```typescript 126 126 + new SiteStandardClient(config: SiteStandardConfig) 44 127 ``` 45 128 46 46 - You can preview the production build with `npm run preview`. 129 129 + #### Methods 130 130 + 131 131 + - `fetchPublication(rkey: string, fetchFn?: typeof fetch): Promise<AtProtoRecord<Publication> | null>` 132 132 + - Fetch a single publication by record key 133 133 + 134 134 + - `fetchAllPublications(fetchFn?: typeof fetch): Promise<AtProtoRecord<Publication>[]>` 135 135 + - Fetch all publications for the configured DID 136 136 + 137 137 + - `fetchDocument(rkey: string, fetchFn?: typeof fetch): Promise<AtProtoRecord<Document> | null>` 138 138 + - Fetch a single document by record key 139 139 + 140 140 + - `fetchAllDocuments(fetchFn?: typeof fetch): Promise<AtProtoRecord<Document>[]>` 141 141 + - Fetch all documents for the configured DID, sorted by publishedAt (newest first) 142 142 + 143 143 + - `fetchDocumentsByPublication(publicationUri: string, fetchFn?: typeof fetch): Promise<AtProtoRecord<Document>[]>` 144 144 + - Fetch all documents belonging to a specific publication 47 145 48 48 - > To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment. 146 146 + - `fetchByAtUri<T>(atUri: string, fetchFn?: typeof fetch): Promise<AtProtoRecord<T> | null>` 147 147 + - Fetch any record by its AT URI 49 148 50 50 - ## Publishing 149 149 + - `clearCache(): void` 150 150 + - Clear all cached data 51 151 52 52 - Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)). 152 152 + - `getPDS(fetchFn?: typeof fetch): Promise<string>` 153 153 + - Get the resolved PDS endpoint 53 154 54 54 - To publish your library to [npm](https://www.npmjs.com): 155 155 + ### Types 55 156 56 56 - ```sh 57 57 - npm publish 157 157 + ```typescript 158 158 + interface Publication { 159 159 + $type: 'site.standard.publication'; 160 160 + url: string; 161 161 + name: string; 162 162 + icon?: AtProtoBlob; 163 163 + description?: string; 164 164 + basicTheme?: BasicTheme; 165 165 + preferences?: PublicationPreferences; 166 166 + } 167 167 + 168 168 + interface Document { 169 169 + $type: 'site.standard.document'; 170 170 + site: string; // AT URI or HTTPS URL 171 171 + title: string; 172 172 + path?: string; 173 173 + description?: string; 174 174 + coverImage?: AtProtoBlob; 175 175 + content?: any; 176 176 + textContent?: string; 177 177 + bskyPostRef?: StrongRef; 178 178 + tags?: string[]; 179 179 + publishedAt: string; 180 180 + updatedAt?: string; 181 181 + } 182 182 + 183 183 + interface AtProtoRecord<T> { 184 184 + uri: string; 185 185 + cid: string; 186 186 + value: T; 187 187 + } 58 188 ``` 189 189 + 190 190 + ### Utility Functions 191 191 + 192 192 + #### AT URI Utilities 193 193 + 194 194 + ```typescript 195 195 + import { parseAtUri, atUriToHttps, buildAtUri, isAtUri } from 'svelte-standard-site'; 196 196 + 197 197 + // Parse an AT URI 198 198 + const parsed = parseAtUri('at://did:plc:xxx/site.standard.publication/rkey'); 199 199 + // Returns: { did: 'did:plc:xxx', collection: 'site.standard.publication', rkey: 'rkey' } 200 200 + 201 201 + // Convert AT URI to HTTPS URL 202 202 + const url = atUriToHttps( 203 203 + 'at://did:plc:xxx/site.standard.publication/rkey', 204 204 + 'https://pds.example.com' 205 205 + ); 206 206 + // Returns: 'https://pds.example.com/xrpc/com.atproto.repo.getRecord?repo=...' 207 207 + 208 208 + // Build an AT URI 209 209 + const uri = buildAtUri('did:plc:xxx', 'site.standard.publication', 'rkey'); 210 210 + // Returns: 'at://did:plc:xxx/site.standard.publication/rkey' 211 211 + 212 212 + // Validate AT URI 213 213 + const valid = isAtUri('at://did:plc:xxx/site.standard.publication/rkey'); 214 214 + // Returns: true 215 215 + ``` 216 216 + 217 217 + #### PDS Resolution 218 218 + 219 219 + ```typescript 220 220 + import { resolveIdentity, buildPdsBlobUrl } from 'svelte-standard-site'; 221 221 + 222 222 + // Resolve a DID to its PDS 223 223 + const identity = await resolveIdentity('did:plc:xxx'); 224 224 + // Returns: { did: 'did:plc:xxx', pds: 'https://...', handle?: 'user.bsky.social' } 225 225 + 226 226 + // Build a blob URL 227 227 + const blobUrl = buildPdsBlobUrl('https://pds.example.com', 'did:plc:xxx', 'bafyrei...'); 228 228 + // Returns: 'https://pds.example.com/xrpc/com.atproto.sync.getBlob?did=...&cid=...' 229 229 + ``` 230 230 + 231 231 + ## Configuration 232 232 + 233 233 + ### From Environment Variables 234 234 + 235 235 + ```typescript 236 236 + import { getConfigFromEnv, validateEnv } from 'svelte-standard-site/config/env'; 237 237 + 238 238 + // Get config (returns null if missing) 239 239 + const config = getConfigFromEnv(); 240 240 + 241 241 + // Validate config (throws if missing) 242 242 + validateEnv(); 243 243 + ``` 244 244 + 245 245 + ### Manual Configuration 246 246 + 247 247 + ```typescript 248 248 + import { createClient } from 'svelte-standard-site'; 249 249 + 250 250 + const client = createClient({ 251 251 + did: 'did:plc:revjuqmkvrw6fnkxppqtszpv', 252 252 + pds: 'https://cortinarius.us-west.host.bsky.network', // optional 253 253 + cacheTTL: 300000 // optional, in milliseconds 254 254 + }); 255 255 + ``` 256 256 + 257 257 + ## Caching 258 258 + 259 259 + The library includes built-in caching to reduce API calls: 260 260 + 261 261 + - Default TTL: 5 minutes (300,000ms) 262 262 + - Configurable via `cacheTTL` option or `PUBLIC_CACHE_TTL` env var 263 263 + - Cache can be cleared manually with `client.clearCache()` 264 264 + 265 265 + ## AT URI Structure 266 266 + 267 267 + AT URIs follow this format: 268 268 + 269 269 + ``` 270 270 + at://did:plc:revjuqmkvrw6fnkxppqtszpv/site.standard.publication/3lwafzkjqm25s 271 271 + └─────────┬─────────┘ └──────────┬──────────┘ └────┬────┘ 272 272 + DID Collection Record Key 273 273 + ``` 274 274 + 275 275 + The library automatically converts these to HTTPS URLs for API calls: 276 276 + 277 277 + ``` 278 278 + https://cortinarius.us-west.host.bsky.network/xrpc/com.atproto.repo.getRecord?repo=did:plc:revjuqmkvrw6fnkxppqtszpv&collection=site.standard.publication&rkey=3lwafzkjqm25s 279 279 + ``` 280 280 + 281 281 + ## Example: Building a Blog 282 282 + 283 283 + ```typescript 284 284 + // src/routes/blog/+page.server.ts 285 285 + import { createClient } from 'svelte-standard-site'; 286 286 + import { PUBLIC_ATPROTO_DID } from '$env/static/public'; 287 287 + 288 288 + export const load = async ({ fetch }) => { 289 289 + const client = createClient({ did: PUBLIC_ATPROTO_DID }); 290 290 + const documents = await client.fetchAllDocuments(fetch); 291 291 + 292 292 + return { 293 293 + posts: documents.map((doc) => ({ 294 294 + title: doc.value.title, 295 295 + description: doc.value.description, 296 296 + publishedAt: doc.value.publishedAt, 297 297 + slug: doc.uri.split('/').pop(), 298 298 + tags: doc.value.tags || [] 299 299 + })) 300 300 + }; 301 301 + }; 302 302 + ``` 303 303 + 304 304 + ```typescript 305 305 + // src/routes/blog/[slug]/+page.server.ts 306 306 + import { createClient } from 'svelte-standard-site'; 307 307 + import { PUBLIC_ATPROTO_DID } from '$env/static/public'; 308 308 + import { error } from '@sveltejs/kit'; 309 309 + 310 310 + export const load = async ({ params, fetch }) => { 311 311 + const client = createClient({ did: PUBLIC_ATPROTO_DID }); 312 312 + const document = await client.fetchDocument(params.slug, fetch); 313 313 + 314 314 + if (!document) { 315 315 + throw error(404, 'Post not found'); 316 316 + } 317 317 + 318 318 + return { 319 319 + post: document.value 320 320 + }; 321 321 + }; 322 322 + ``` 323 323 + 324 324 + ## License 325 325 + 326 326 + MIT 327 327 + 328 328 + ## Contributing 329 329 + 330 330 + Contributions are welcome! Please feel free to submit a Pull Request.

+30 -2

package.json

··· 1 1 { 2 2 "name": "svelte-standard-site", 3 3 "version": "0.0.1", 4 4 + "description": "A SvelteKit library for fetching site.standard.* records from the AT Protocol", 5 5 + "license": "AGPL-3.0", 6 6 + "author": { 7 7 + "name": "Ewan Croft", 8 8 + "url": "https://github.com/ewanc26" 9 9 + }, 4 10 "scripts": { 5 11 "dev": "vite dev", 6 12 "build": "vite build && npm run prepack", ··· 27 33 ".": { 28 34 "types": "./dist/index.d.ts", 29 35 "svelte": "./dist/index.js" 36 36 + }, 37 37 + "./config/env": { 38 38 + "types": "./dist/config/env.d.ts", 39 39 + "default": "./dist/config/env.js" 30 40 } 31 41 }, 32 42 "peerDependencies": { ··· 50 60 "vite": "^7.2.6" 51 61 }, 52 62 "keywords": [ 53 53 - "svelte" 54 54 - ] 63 63 + "svelte", 64 64 + "sveltekit", 65 65 + "atproto", 66 66 + "at-protocol", 67 67 + "bluesky", 68 68 + "site-standard", 69 69 + "blog", 70 70 + "cms" 71 71 + ], 72 72 + "repository": { 73 73 + "type": "git", 74 74 + "url": "git+https://github.com/ewanc26/svelte-standard-site.git" 75 75 + }, 76 76 + "homepage": "https://github.com/ewanc26/svelte-standard-site#readme", 77 77 + "bugs": { 78 78 + "url": "https://github.com/ewanc26/svelte-standard-site/issues" 79 79 + }, 80 80 + "dependencies": { 81 81 + "@atproto/api": "^0.18.16" 82 82 + } 55 83 }

+113

pnpm-lock.yaml

··· 7 7 importers: 8 8 9 9 .: 10 10 + dependencies: 11 11 + '@atproto/api': 12 12 + specifier: ^0.18.16 13 13 + version: 0.18.16 10 14 devDependencies: 11 15 '@sveltejs/adapter-auto': 12 16 specifier: ^7.0.0 ··· 55 59 version: 7.3.1(jiti@2.6.1)(lightningcss@1.30.2) 56 60 57 61 packages: 62 62 + 63 63 + '@atproto/api@0.18.16': 64 64 + resolution: {integrity: sha512-tRGKSWr83pP5CQpSboePU21pE+GqLDYy1XHae4HH4hjaT0pr5V8wNgu70kbKB0B02GVUumeDRpJnlHKD+eMzLg==} 65 65 + 66 66 + '@atproto/common-web@0.4.12': 67 67 + resolution: {integrity: sha512-3aCJemqM/fkHQrVPbTCHCdiVstKFI+2LkFLvUhO6XZP0EqUZa/rg/CIZBKTFUWu9I5iYiaEiXL9VwcDRpEevSw==} 68 68 + 69 69 + '@atproto/lex-data@0.0.8': 70 70 + resolution: {integrity: sha512-1Y5tz7BkS7380QuLNXaE8GW8Xba+mRWugt8BKM4BUFYjjUZdmirU8lr72iM4XlEBrzRu8Cfvj+MbsbYaZv+IgA==} 71 71 + 72 72 + '@atproto/lex-json@0.0.8': 73 73 + resolution: {integrity: sha512-w1Qmkae1QhmNz+i1Zm3xr3jp0UPPRENmdlpU0qIrdxWDo9W4Mzkeyc3eSoa+Zs+zN8xkRSQw7RLZte/B7Ipdwg==} 74 74 + 75 75 + '@atproto/lexicon@0.6.0': 76 76 + resolution: {integrity: sha512-5veb8aD+J5M0qszLJ+73KSFsFrJBgAY/nM1TSAJvGY7fNc9ZAT+PSUlmIyrdye9YznAZ07yktalls/TwNV7cHQ==} 77 77 + 78 78 + '@atproto/syntax@0.4.2': 79 79 + resolution: {integrity: sha512-X9XSRPinBy/0VQ677j8VXlBsYSsUXaiqxWVpGGxJYsAhugdQRb0jqaVKJFtm6RskeNkV6y9xclSUi9UYG/COrA==} 80 80 + 81 81 + '@atproto/xrpc@0.7.7': 82 82 + resolution: {integrity: sha512-K1ZyO/BU8JNtXX5dmPp7b5UrkLMMqpsIa/Lrj5D3Su+j1Xwq1m6QJ2XJ1AgjEjkI1v4Muzm7klianLE6XGxtmA==} 58 83 59 84 '@esbuild/aix-ppc64@0.27.2': 60 85 resolution: {integrity: sha512-GZMB+a0mOMZs4MpDbj8RJp4cw+w1WV5NYD6xzgvzUJ5Ek2jerwfO2eADyI6ExDSUED+1X8aMbegahsJi+8mgpw==} ··· 521 546 resolution: {integrity: sha512-COROpnaoap1E2F000S62r6A60uHZnmlvomhfyT2DlTcrY1OrBKn2UhH7qn5wTC9zMvD0AY7csdPSNwKP+7WiQw==} 522 547 engines: {node: '>= 0.4'} 523 548 549 549 + await-lock@2.2.2: 550 550 + resolution: {integrity: sha512-aDczADvlvTGajTDjcjpJMqRkOF6Qdz3YbPZm/PyW6tKPkx2hlYBzxMhEywM/tU72HrVZjgl5VCdRuMlA7pZ8Gw==} 551 551 + 524 552 axobject-query@4.1.0: 525 553 resolution: {integrity: sha512-qIj0G9wZbMGNLjLmg1PT6v2mE9AH2zlnADJD/2tC6E00hgmhUOfEB6greHPAfLRSufHqROIUTkw6E+M3lH0PTQ==} 526 554 engines: {node: '>= 0.4'} ··· 595 623 is-reference@3.0.3: 596 624 resolution: {integrity: sha512-ixkJoqQvAP88E6wLydLGGqCJsrFUnqoH6HnaczB8XmDH1oaWU+xxdptvikTgaEhtZ53Ky6YXiBuUI2WXLMCwjw==} 597 625 626 626 + iso-datestring-validator@2.2.2: 627 627 + resolution: {integrity: sha512-yLEMkBbLZTlVQqOnQ4FiMujR6T4DEcCb1xizmvXS+OxuhwcbtynoosRzdMA69zZCShCNAbi+gJ71FxZBBXx1SA==} 628 628 + 598 629 jiti@2.6.1: 599 630 resolution: {integrity: sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==} 600 631 hasBin: true ··· 686 717 mrmime@2.0.1: 687 718 resolution: {integrity: sha512-Y3wQdFg2Va6etvQ5I82yUhGdsKrcYox6p7FfL1LbK2J4V01F9TGlepTIhnK24t7koZibmg82KGglhA1XK5IsLQ==} 688 719 engines: {node: '>=10'} 720 720 + 721 721 + multiformats@9.9.0: 722 722 + resolution: {integrity: sha512-HoMUjhH9T8DDBNT+6xzkrd9ga/XiBI4xLr58LJACwK6G3HTOPeMz4nB4KJs33L2BelrIJa7P0VuNaVF3hMYfjg==} 689 723 690 724 nanoid@3.3.11: 691 725 resolution: {integrity: sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==} ··· 849 883 resolution: {integrity: sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==} 850 884 engines: {node: '>=12.0.0'} 851 885 886 886 + tlds@1.261.0: 887 887 + resolution: {integrity: sha512-QXqwfEl9ddlGBaRFXIvNKK6OhipSiLXuRuLJX5DErz0o0Q0rYxulWLdFryTkV5PkdZct5iMInwYEGe/eR++1AA==} 888 888 + hasBin: true 889 889 + 852 890 totalist@3.0.1: 853 891 resolution: {integrity: sha512-sf4i37nQ2LBx4m3wB74y+ubopq6W/dIzXg0FDGjsYnZHVa1Da8FH853wlL2gtUhg+xJXjfk3kUZS3BRoQeoQBQ==} 854 892 engines: {node: '>=6'} 855 893 894 894 + tslib@2.8.1: 895 895 + resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==} 896 896 + 856 897 typescript@5.9.3: 857 898 resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==} 858 899 engines: {node: '>=14.17'} 859 900 hasBin: true 860 901 902 902 + uint8arrays@3.0.0: 903 903 + resolution: {integrity: sha512-HRCx0q6O9Bfbp+HHSfQQKD7wU70+lydKVt4EghkdOvlK/NlrF90z+eXV34mUd48rNvVJXwkrMSPpCATkct8fJA==} 904 904 + 905 905 + unicode-segmenter@0.14.5: 906 906 + resolution: {integrity: sha512-jHGmj2LUuqDcX3hqY12Ql+uhUTn8huuxNZGq7GvtF6bSybzH3aFgedYu/KTzQStEgt1Ra2F3HxadNXsNjb3m3g==} 907 907 + 861 908 util-deprecate@1.0.2: 862 909 resolution: {integrity: sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==} 863 910 ··· 912 959 zimmerframe@1.1.4: 913 960 resolution: {integrity: sha512-B58NGBEoc8Y9MWWCQGl/gq9xBCe4IiKM0a2x7GZdQKOW5Exr8S1W24J6OgM1njK8xCRGvAJIL/MxXHf6SkmQKQ==} 914 961 962 962 + zod@3.25.76: 963 963 + resolution: {integrity: sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==} 964 964 + 915 965 snapshots: 916 966 967 967 + '@atproto/api@0.18.16': 968 968 + dependencies: 969 969 + '@atproto/common-web': 0.4.12 970 970 + '@atproto/lexicon': 0.6.0 971 971 + '@atproto/syntax': 0.4.2 972 972 + '@atproto/xrpc': 0.7.7 973 973 + await-lock: 2.2.2 974 974 + multiformats: 9.9.0 975 975 + tlds: 1.261.0 976 976 + zod: 3.25.76 977 977 + 978 978 + '@atproto/common-web@0.4.12': 979 979 + dependencies: 980 980 + '@atproto/lex-data': 0.0.8 981 981 + '@atproto/lex-json': 0.0.8 982 982 + zod: 3.25.76 983 983 + 984 984 + '@atproto/lex-data@0.0.8': 985 985 + dependencies: 986 986 + '@atproto/syntax': 0.4.2 987 987 + multiformats: 9.9.0 988 988 + tslib: 2.8.1 989 989 + uint8arrays: 3.0.0 990 990 + unicode-segmenter: 0.14.5 991 991 + 992 992 + '@atproto/lex-json@0.0.8': 993 993 + dependencies: 994 994 + '@atproto/lex-data': 0.0.8 995 995 + tslib: 2.8.1 996 996 + 997 997 + '@atproto/lexicon@0.6.0': 998 998 + dependencies: 999 999 + '@atproto/common-web': 0.4.12 1000 1000 + '@atproto/syntax': 0.4.2 1001 1001 + iso-datestring-validator: 2.2.2 1002 1002 + multiformats: 9.9.0 1003 1003 + zod: 3.25.76 1004 1004 + 1005 1005 + '@atproto/syntax@0.4.2': {} 1006 1006 + 1007 1007 + '@atproto/xrpc@0.7.7': 1008 1008 + dependencies: 1009 1009 + '@atproto/lexicon': 0.6.0 1010 1010 + zod: 3.25.76 1011 1011 + 917 1012 '@esbuild/aix-ppc64@0.27.2': 918 1013 optional: true 919 1014 ··· 1230 1325 1231 1326 aria-query@5.3.2: {} 1232 1327 1328 1328 + await-lock@2.2.2: {} 1329 1329 + 1233 1330 axobject-query@4.1.0: {} 1234 1331 1235 1332 chokidar@4.0.3: ··· 1306 1403 is-reference@3.0.3: 1307 1404 dependencies: 1308 1405 '@types/estree': 1.0.8 1406 1406 + 1407 1407 + iso-datestring-validator@2.2.2: {} 1309 1408 1310 1409 jiti@2.6.1: {} 1311 1410 ··· 1370 1469 1371 1470 mrmime@2.0.1: {} 1372 1471 1472 1472 + multiformats@9.9.0: {} 1473 1473 + 1373 1474 nanoid@3.3.11: {} 1374 1475 1375 1476 obug@2.1.1: {} ··· 1510 1611 fdir: 6.5.0(picomatch@4.0.3) 1511 1612 picomatch: 4.0.3 1512 1613 1614 1614 + tlds@1.261.0: {} 1615 1615 + 1513 1616 totalist@3.0.1: {} 1514 1617 1618 1618 + tslib@2.8.1: {} 1619 1619 + 1515 1620 typescript@5.9.3: {} 1621 1621 + 1622 1622 + uint8arrays@3.0.0: 1623 1623 + dependencies: 1624 1624 + multiformats: 9.9.0 1625 1625 + 1626 1626 + unicode-segmenter@0.14.5: {} 1516 1627 1517 1628 util-deprecate@1.0.2: {} 1518 1629 ··· 1534 1645 vite: 7.3.1(jiti@2.6.1)(lightningcss@1.30.2) 1535 1646 1536 1647 zimmerframe@1.1.4: {} 1648 1648 + 1649 1649 + zod@3.25.76: {}

+368

src/lib/client.ts

··· 1 1 + import type { 2 2 + SiteStandardConfig, 3 3 + Publication, 4 4 + Document, 5 5 + AtProtoRecord, 6 6 + ResolvedIdentity 7 7 + } from './types.js'; 8 8 + import { cache } from './utils/cache.js'; 9 9 + import { resolveIdentity, withFallback, buildPdsBlobUrl } from './utils/agents.js'; 10 10 + import { parseAtUri, atUriToHttps } from './utils/at-uri.js'; 11 11 + 12 12 + /** 13 13 + * Main client for interacting with site.standard.* records 14 14 + */ 15 15 + export class SiteStandardClient { 16 16 + private config: Required<SiteStandardConfig>; 17 17 + private pdsEndpoint: string | null = null; 18 18 + 19 19 + constructor(config: SiteStandardConfig) { 20 20 + this.config = { 21 21 + did: config.did, 22 22 + pds: config.pds ?? '', 23 23 + cacheTTL: config.cacheTTL ?? 5 * 60 * 1000 24 24 + }; 25 25 + 26 26 + // Set cache TTL 27 27 + cache.setDefaultTTL(this.config.cacheTTL); 28 28 + } 29 29 + 30 30 + /** 31 31 + * Resolve and cache PDS endpoint 32 32 + */ 33 33 + private async resolvePDS(fetchFn?: typeof fetch): Promise<string> { 34 34 + if (this.pdsEndpoint) return this.pdsEndpoint; 35 35 + 36 36 + if (this.config.pds) { 37 37 + this.pdsEndpoint = this.config.pds; 38 38 + return this.pdsEndpoint; 39 39 + } 40 40 + 41 41 + const identity = await resolveIdentity(this.config.did, fetchFn); 42 42 + this.pdsEndpoint = identity.pds; 43 43 + return this.pdsEndpoint; 44 44 + } 45 45 + 46 46 + /** 47 47 + * Convert a blob object to a URL string 48 48 + */ 49 49 + private async getBlobUrl(blob: any, fetchFn?: typeof fetch): Promise<string | undefined> { 50 50 + try { 51 51 + const cid = blob?.ref?.$link || blob?.cid; 52 52 + if (!cid) return undefined; 53 53 + 54 54 + const pds = await this.resolvePDS(fetchFn); 55 55 + return buildPdsBlobUrl(pds, this.config.did, cid); 56 56 + } catch (error) { 57 57 + console.warn('Failed to resolve blob URL:', error); 58 58 + return undefined; 59 59 + } 60 60 + } 61 61 + 62 62 + /** 63 63 + * Fetch a single publication by rkey 64 64 + * @param rkey - Record key for the publication 65 65 + * @param fetchFn - Optional fetch function for SSR 66 66 + * @returns Publication record or null if not found 67 67 + */ 68 68 + async fetchPublication( 69 69 + rkey: string, 70 70 + fetchFn?: typeof fetch 71 71 + ): Promise<AtProtoRecord<Publication> | null> { 72 72 + const cacheKey = `publication:${this.config.did}:${rkey}`; 73 73 + const cached = cache.get<AtProtoRecord<Publication>>(cacheKey); 74 74 + if (cached) return cached; 75 75 + 76 76 + try { 77 77 + const result = await withFallback( 78 78 + this.config.did, 79 79 + async (agent) => { 80 80 + const response = await agent.com.atproto.repo.getRecord({ 81 81 + repo: this.config.did, 82 82 + collection: 'site.standard.publication', 83 83 + rkey 84 84 + }); 85 85 + return response.data; 86 86 + }, 87 87 + fetchFn 88 88 + ); 89 89 + 90 90 + if (!result || !result.value) return null; 91 91 + 92 92 + const pubValue = result.value as any; 93 93 + 94 94 + // Build the publication object with converted blob URLs 95 95 + const record: AtProtoRecord<Publication> = { 96 96 + uri: result.uri, 97 97 + cid: result.cid || '', 98 98 + value: { 99 99 + $type: 'site.standard.publication', 100 100 + url: pubValue.url, 101 101 + name: pubValue.name, 102 102 + icon: pubValue.icon ? await this.getBlobUrl(pubValue.icon, fetchFn) : undefined, 103 103 + description: pubValue.description, 104 104 + basicTheme: pubValue.basicTheme, 105 105 + preferences: pubValue.preferences 106 106 + } 107 107 + }; 108 108 + 109 109 + cache.set(cacheKey, record); 110 110 + return record; 111 111 + } catch (error) { 112 112 + console.error(`Failed to fetch publication ${rkey}:`, error); 113 113 + return null; 114 114 + } 115 115 + } 116 116 + 117 117 + /** 118 118 + * Fetch all publications for the configured DID 119 119 + * @param fetchFn - Optional fetch function for SSR 120 120 + * @returns Array of publication records 121 121 + */ 122 122 + async fetchAllPublications(fetchFn?: typeof fetch): Promise<AtProtoRecord<Publication>[]> { 123 123 + const cacheKey = `publications:${this.config.did}:all`; 124 124 + const cached = cache.get<AtProtoRecord<Publication>[]>(cacheKey); 125 125 + if (cached) return cached; 126 126 + 127 127 + try { 128 128 + const allRecords: AtProtoRecord<Publication>[] = []; 129 129 + let cursor: string | undefined; 130 130 + 131 131 + do { 132 132 + const records = await withFallback( 133 133 + this.config.did, 134 134 + async (agent) => { 135 135 + const response = await agent.com.atproto.repo.listRecords({ 136 136 + repo: this.config.did, 137 137 + collection: 'site.standard.publication', 138 138 + limit: 100, 139 139 + cursor 140 140 + }); 141 141 + cursor = response.data.cursor; 142 142 + return response.data.records; 143 143 + }, 144 144 + fetchFn 145 145 + ); 146 146 + 147 147 + // Convert each record with blob URLs 148 148 + for (const record of records) { 149 149 + const pubValue = record.value as any; 150 150 + const pub: AtProtoRecord<Publication> = { 151 151 + uri: record.uri, 152 152 + cid: record.cid || '', 153 153 + value: { 154 154 + $type: 'site.standard.publication', 155 155 + url: pubValue.url, 156 156 + name: pubValue.name, 157 157 + icon: pubValue.icon ? await this.getBlobUrl(pubValue.icon, fetchFn) : undefined, 158 158 + description: pubValue.description, 159 159 + basicTheme: pubValue.basicTheme, 160 160 + preferences: pubValue.preferences 161 161 + } 162 162 + }; 163 163 + allRecords.push(pub); 164 164 + } 165 165 + } while (cursor); 166 166 + 167 167 + cache.set(cacheKey, allRecords); 168 168 + return allRecords; 169 169 + } catch (error) { 170 170 + console.error('Failed to fetch publications:', error); 171 171 + return []; 172 172 + } 173 173 + } 174 174 + 175 175 + /** 176 176 + * Fetch a single document by rkey 177 177 + * @param rkey - Record key for the document 178 178 + * @param fetchFn - Optional fetch function for SSR 179 179 + * @returns Document record or null if not found 180 180 + */ 181 181 + async fetchDocument( 182 182 + rkey: string, 183 183 + fetchFn?: typeof fetch 184 184 + ): Promise<AtProtoRecord<Document> | null> { 185 185 + const cacheKey = `document:${this.config.did}:${rkey}`; 186 186 + const cached = cache.get<AtProtoRecord<Document>>(cacheKey); 187 187 + if (cached) return cached; 188 188 + 189 189 + try { 190 190 + const result = await withFallback( 191 191 + this.config.did, 192 192 + async (agent) => { 193 193 + const response = await agent.com.atproto.repo.getRecord({ 194 194 + repo: this.config.did, 195 195 + collection: 'site.standard.document', 196 196 + rkey 197 197 + }); 198 198 + return response.data; 199 199 + }, 200 200 + fetchFn 201 201 + ); 202 202 + 203 203 + if (!result || !result.value) return null; 204 204 + 205 205 + const docValue = result.value as any; 206 206 + 207 207 + // Build the document object with converted blob URLs 208 208 + const record: AtProtoRecord<Document> = { 209 209 + uri: result.uri, 210 210 + cid: result.cid || '', 211 211 + value: { 212 212 + $type: 'site.standard.document', 213 213 + site: docValue.site, 214 214 + title: docValue.title, 215 215 + path: docValue.path, 216 216 + description: docValue.description, 217 217 + coverImage: docValue.coverImage 218 218 + ? await this.getBlobUrl(docValue.coverImage, fetchFn) 219 219 + : undefined, 220 220 + content: docValue.content, 221 221 + textContent: docValue.textContent, 222 222 + bskyPostRef: docValue.bskyPostRef, 223 223 + tags: docValue.tags, 224 224 + publishedAt: docValue.publishedAt, 225 225 + updatedAt: docValue.updatedAt 226 226 + } 227 227 + }; 228 228 + 229 229 + cache.set(cacheKey, record); 230 230 + return record; 231 231 + } catch (error) { 232 232 + console.error(`Failed to fetch document ${rkey}:`, error); 233 233 + return null; 234 234 + } 235 235 + } 236 236 + 237 237 + /** 238 238 + * Fetch all documents for the configured DID 239 239 + * @param fetchFn - Optional fetch function for SSR 240 240 + * @returns Array of document records 241 241 + */ 242 242 + async fetchAllDocuments(fetchFn?: typeof fetch): Promise<AtProtoRecord<Document>[]> { 243 243 + const cacheKey = `documents:${this.config.did}:all`; 244 244 + const cached = cache.get<AtProtoRecord<Document>[]>(cacheKey); 245 245 + if (cached) return cached; 246 246 + 247 247 + try { 248 248 + const allRecords: AtProtoRecord<Document>[] = []; 249 249 + let cursor: string | undefined; 250 250 + 251 251 + do { 252 252 + const records = await withFallback( 253 253 + this.config.did, 254 254 + async (agent) => { 255 255 + const response = await agent.com.atproto.repo.listRecords({ 256 256 + repo: this.config.did, 257 257 + collection: 'site.standard.document', 258 258 + limit: 100, 259 259 + cursor 260 260 + }); 261 261 + cursor = response.data.cursor; 262 262 + return response.data.records; 263 263 + }, 264 264 + fetchFn 265 265 + ); 266 266 + 267 267 + // Convert each record with blob URLs 268 268 + for (const record of records) { 269 269 + const docValue = record.value as any; 270 270 + const doc: AtProtoRecord<Document> = { 271 271 + uri: record.uri, 272 272 + cid: record.cid || '', 273 273 + value: { 274 274 + $type: 'site.standard.document', 275 275 + site: docValue.site, 276 276 + title: docValue.title, 277 277 + path: docValue.path, 278 278 + description: docValue.description, 279 279 + coverImage: docValue.coverImage 280 280 + ? await this.getBlobUrl(docValue.coverImage, fetchFn) 281 281 + : undefined, 282 282 + content: docValue.content, 283 283 + textContent: docValue.textContent, 284 284 + bskyPostRef: docValue.bskyPostRef, 285 285 + tags: docValue.tags, 286 286 + publishedAt: docValue.publishedAt, 287 287 + updatedAt: docValue.updatedAt 288 288 + } 289 289 + }; 290 290 + allRecords.push(doc); 291 291 + } 292 292 + } while (cursor); 293 293 + 294 294 + // Sort by publishedAt, newest first 295 295 + allRecords.sort( 296 296 + (a, b) => new Date(b.value.publishedAt).getTime() - new Date(a.value.publishedAt).getTime() 297 297 + ); 298 298 + 299 299 + cache.set(cacheKey, allRecords); 300 300 + return allRecords; 301 301 + } catch (error) { 302 302 + console.error('Failed to fetch documents:', error); 303 303 + return []; 304 304 + } 305 305 + } 306 306 + 307 307 + /** 308 308 + * Fetch documents for a specific publication 309 309 + * @param publicationUri - AT URI of the publication 310 310 + * @param fetchFn - Optional fetch function for SSR 311 311 + * @returns Array of document records belonging to the publication 312 312 + */ 313 313 + async fetchDocumentsByPublication( 314 314 + publicationUri: string, 315 315 + fetchFn?: typeof fetch 316 316 + ): Promise<AtProtoRecord<Document>[]> { 317 317 + const allDocs = await this.fetchAllDocuments(fetchFn); 318 318 + return allDocs.filter((doc) => doc.value.site === publicationUri); 319 319 + } 320 320 + 321 321 + /** 322 322 + * Fetch a record by AT URI 323 323 + * @param atUri - Full AT URI (e.g., at://did:plc:xxx/site.standard.publication/rkey) 324 324 + * @param fetchFn - Optional fetch function for SSR 325 325 + * @returns Record or null if not found 326 326 + */ 327 327 + async fetchByAtUri<T = Publication | Document>( 328 328 + atUri: string, 329 329 + fetchFn?: typeof fetch 330 330 + ): Promise<AtProtoRecord<T> | null> { 331 331 + const parsed = parseAtUri(atUri); 332 332 + if (!parsed) { 333 333 + console.error('Invalid AT URI:', atUri); 334 334 + return null; 335 335 + } 336 336 + 337 337 + if (parsed.collection === 'site.standard.publication') { 338 338 + return this.fetchPublication(parsed.rkey, fetchFn) as Promise<AtProtoRecord<T> | null>; 339 339 + } else if (parsed.collection === 'site.standard.document') { 340 340 + return this.fetchDocument(parsed.rkey, fetchFn) as Promise<AtProtoRecord<T> | null>; 341 341 + } 342 342 + 343 343 + return null; 344 344 + } 345 345 + 346 346 + /** 347 347 + * Clear all cached data 348 348 + */ 349 349 + clearCache(): void { 350 350 + cache.clear(); 351 351 + } 352 352 + 353 353 + /** 354 354 + * Get the resolved PDS endpoint 355 355 + */ 356 356 + async getPDS(fetchFn?: typeof fetch): Promise<string> { 357 357 + return this.resolvePDS(fetchFn); 358 358 + } 359 359 + } 360 360 + 361 361 + /** 362 362 + * Create a new SiteStandardClient instance 363 363 + * @param config - Configuration object 364 364 + * @returns Configured client instance 365 365 + */ 366 366 + export function createClient(config: SiteStandardConfig): SiteStandardClient { 367 367 + return new SiteStandardClient(config); 368 368 + }

+74

src/lib/components/DocumentCard.svelte

··· 1 1 + <script lang="ts"> 2 2 + import type { Document, AtProtoRecord } from '../types.js'; 3 3 + import { getDocumentSlug } from '../utils/document.js'; 4 4 + import { extractRkey } from '$lib/index.js'; 5 5 + 6 6 + interface Props { 7 7 + document: AtProtoRecord<Document>; 8 8 + class?: string; 9 9 + showCover?: boolean; 10 10 + } 11 11 + 12 12 + const { document, class: className = '', showCover = true }: Props = $props(); 13 13 + 14 14 + const value = $derived(document.value); 15 15 + 16 16 + // Construct the rkey-based URL: /[pub_rkey]/[doc_rkey] 17 17 + const pubRkey = $derived(extractRkey(value.site)); 18 18 + const docRkey = $derived(extractRkey(document.uri)); 19 19 + const href = $derived(`/${pubRkey}/${docRkey}`); 20 20 + 21 21 + function formatDate(dateString: string): string { 22 22 + return new Date(dateString).toLocaleDateString('en-US', { 23 23 + year: 'numeric', 24 24 + month: 'long', 25 25 + day: 'numeric' 26 26 + }); 27 27 + } 28 28 + </script> 29 29 + 30 30 + <a {href} class="group block"> 31 31 + <article 32 32 + class="flex gap-6 rounded-xl border border-gray-200 bg-white p-6 transition-all duration-200 hover:border-blue-300 hover:shadow-md {className}" 33 33 + > 34 34 + {#if showCover && value.coverImage} 35 35 + <img 36 36 + src={value.coverImage} 37 37 + alt="{value.title} cover" 38 38 + class="h-48 w-32 shrink-0 rounded-lg object-cover shadow-sm" 39 39 + /> 40 40 + {/if} 41 41 + 42 42 + <div class="flex-1"> 43 43 + <h3 class="mb-2 text-2xl font-bold text-gray-900 transition-colors group-hover:text-blue-600"> 44 44 + {value.title} 45 45 + </h3> 46 46 + 47 47 + {#if value.description} 48 48 + <p class="mb-4 line-clamp-3 text-sm leading-relaxed text-gray-600"> 49 49 + {value.description} 50 50 + </p> 51 51 + {/if} 52 52 + 53 53 + <div class="mb-4 flex flex-wrap items-center gap-x-4 gap-y-2 text-sm text-gray-500"> 54 54 + <time class="font-medium text-gray-700">{formatDate(value.publishedAt)}</time> 55 55 + {#if value.updatedAt} 56 56 + <span class="flex items-center gap-1"> 57 57 + <span class="h-1 w-1 rounded-full bg-gray-300"></span> 58 58 + Updated {formatDate(value.updatedAt)} 59 59 + </span> 60 60 + {/if} 61 61 + </div> 62 62 + 63 63 + {#if value.tags && value.tags.length > 0} 64 64 + <div class="flex flex-wrap gap-2"> 65 65 + {#each value.tags as tag} 66 66 + <span class="rounded-lg bg-blue-50 px-2.5 py-1 text-xs font-semibold text-blue-700"> 67 67 + #{tag} 68 68 + </span> 69 69 + {/each} 70 70 + </div> 71 71 + {/if} 72 72 + </div> 73 73 + </article> 74 74 + </a>

+50

src/lib/components/PublicationCard.svelte

··· 1 1 + <script lang="ts"> 2 2 + import type { Publication, AtProtoRecord } from '../types.js'; 3 3 + import { getThemeVars } from '../utils/theme.js'; 4 4 + 5 5 + interface Props { 6 6 + publication: AtProtoRecord<Publication>; 7 7 + class?: string; 8 8 + } 9 9 + 10 10 + const { publication, class: className = '' }: Props = $props(); 11 11 + 12 12 + // Access value reactively through a getter 13 13 + const value = $derived(publication.value); 14 14 + const themeVars = $derived(value.basicTheme ? getThemeVars(value.basicTheme) : {}); 15 15 + </script> 16 16 + 17 17 + <article 18 18 + class="rounded-lg border border-gray-200 bg-white p-6 transition-all hover:shadow-lg {className}" 19 19 + style={Object.entries(themeVars) 20 20 + .map(([k, v]) => `${k}:${v}`) 21 21 + .join(';')} 22 22 + > 23 23 + <div class="mb-4 flex gap-4"> 24 24 + {#if value.icon} 25 25 + <img 26 26 + src={value.icon} 27 27 + alt="{value.name} icon" 28 28 + class="size-16 flex-shrink-0 rounded-lg object-cover" 29 29 + /> 30 30 + {/if} 31 31 + <div class="flex-1"> 32 32 + <h3 class="mb-2 text-xl font-semibold text-gray-900">{value.name}</h3> 33 33 + {#if value.description} 34 34 + <p class="text-sm text-gray-600">{value.description}</p> 35 35 + {/if} 36 36 + </div> 37 37 + </div> 38 38 + <a 39 39 + href={value.url} 40 40 + target="_blank" 41 41 + rel="noopener noreferrer" 42 42 + class="inline-flex items-center gap-1 font-medium transition-opacity hover:opacity-80" 43 43 + style:color={value.basicTheme ? `var(--theme-accent)` : undefined} 44 44 + > 45 45 + Visit Site 46 46 + <svg class="size-4" fill="none" viewBox="0 0 24 24" stroke="currentColor"> 47 47 + <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7" /> 48 48 + </svg> 49 49 + </a> 50 50 + </article>

+2

src/lib/components/index.ts

··· 1 1 + export { default as PublicationCard } from './PublicationCard.svelte'; 2 2 + export { default as DocumentCard } from './DocumentCard.svelte';

+31

src/lib/config/env.ts

··· 1 1 + import { env } from '$env/dynamic/public'; 2 2 + import type { SiteStandardConfig } from '../types.js'; 3 3 + 4 4 + /** 5 5 + * Get configuration from environment variables 6 6 + * @returns Configuration object or null if required vars are missing 7 7 + */ 8 8 + export function getConfigFromEnv(): SiteStandardConfig | null { 9 9 + const did = env.PUBLIC_ATPROTO_DID; 10 10 + 11 11 + if (!did) { 12 12 + console.error('Missing required environment variable: PUBLIC_ATPROTO_DID'); 13 13 + return null; 14 14 + } 15 15 + 16 16 + return { 17 17 + did, 18 18 + pds: env.PUBLIC_ATPROTO_PDS || undefined, 19 19 + cacheTTL: env.PUBLIC_CACHE_TTL ? parseInt(env.PUBLIC_CACHE_TTL) : undefined 20 20 + }; 21 21 + } 22 22 + 23 23 + /** 24 24 + * Validate that required environment variables are set 25 25 + * @throws Error if required variables are missing 26 26 + */ 27 27 + export function validateEnv(): void { 28 28 + if (!env.PUBLIC_ATPROTO_DID) { 29 29 + throw new Error('Missing required environment variable: PUBLIC_ATPROTO_DID'); 30 30 + } 31 31 + }

+31 -1

src/lib/index.ts

··· 1 1 - // Reexport your entry components here 1 1 + // Main exports 2 2 + export { SiteStandardClient, createClient } from './client.js'; 3 3 + 4 4 + // Type exports 5 5 + export type { 6 6 + AtProtoBlob, 7 7 + StrongRef, 8 8 + RGBColor, 9 9 + BasicTheme, 10 10 + PublicationPreferences, 11 11 + Publication, 12 12 + Document, 13 13 + AtProtoRecord, 14 14 + ResolvedIdentity, 15 15 + SiteStandardConfig 16 16 + } from './types.js'; 17 17 + 18 18 + // Utility exports 19 19 + export { parseAtUri, atUriToHttps, buildAtUri, extractRkey, isAtUri } from './utils/at-uri.js'; 20 20 + 21 21 + export { resolveIdentity, buildPdsBlobUrl } from './utils/agents.js'; 22 22 + 23 23 + export { cache } from './utils/cache.js'; 24 24 + 25 25 + export { rgbToCSS, rgbToHex, getThemeVars } from './utils/theme.js'; 26 26 + 27 27 + export { 28 28 + getDocumentSlug, 29 29 + getDocumentUrl, 30 30 + extractRkey as extractRkeyFromUri 31 31 + } from './utils/document.js';

+111

src/lib/types.ts

··· 1 1 + /** 2 2 + * Core types for site.standard.* lexicons 3 3 + */ 4 4 + 5 5 + /** 6 6 + * AT Protocol blob reference 7 7 + */ 8 8 + export interface AtProtoBlob { 9 9 + $type: 'blob'; 10 10 + ref: { 11 11 + $link: string; 12 12 + }; 13 13 + mimeType: string; 14 14 + size: number; 15 15 + } 16 16 + 17 17 + /** 18 18 + * Strong reference to another AT Protocol record 19 19 + */ 20 20 + export interface StrongRef { 21 21 + uri: string; 22 22 + cid: string; 23 23 + } 24 24 + 25 25 + /** 26 26 + * RGB Color 27 27 + */ 28 28 + export interface RGBColor { 29 29 + r: number; // 0-255 30 30 + g: number; // 0-255 31 31 + b: number; // 0-255 32 32 + } 33 33 + 34 34 + /** 35 35 + * Basic theme for publications 36 36 + */ 37 37 + export interface BasicTheme { 38 38 + $type?: 'site.standard.theme.basic'; 39 39 + background: RGBColor; 40 40 + foreground: RGBColor; 41 41 + accent: RGBColor; 42 42 + accentForeground: RGBColor; 43 43 + } 44 44 + 45 45 + /** 46 46 + * Publication preferences 47 47 + */ 48 48 + export interface PublicationPreferences { 49 49 + showInDiscover?: boolean; 50 50 + } 51 51 + 52 52 + /** 53 53 + * Site Standard Publication record 54 54 + */ 55 55 + export interface Publication { 56 56 + $type: 'site.standard.publication'; 57 57 + url: string; 58 58 + name: string; 59 59 + icon?: string; // Blob URL converted to string 60 60 + description?: string; 61 61 + basicTheme?: BasicTheme; 62 62 + preferences?: PublicationPreferences; 63 63 + } 64 64 + 65 65 + /** 66 66 + * Site Standard Document record 67 67 + */ 68 68 + export interface Document { 69 69 + $type: 'site.standard.document'; 70 70 + site: string; // AT URI or HTTPS URL 71 71 + title: string; 72 72 + path?: string; 73 73 + description?: string; 74 74 + coverImage?: string; // Blob URL converted to string 75 75 + content?: any; // Open union 76 76 + textContent?: string; 77 77 + bskyPostRef?: StrongRef; 78 78 + tags?: string[]; 79 79 + publishedAt: string; 80 80 + updatedAt?: string; 81 81 + } 82 82 + 83 83 + /** 84 84 + * AT Protocol record response 85 85 + */ 86 86 + export interface AtProtoRecord<T = any> { 87 87 + uri: string; 88 88 + cid: string; 89 89 + value: T; 90 90 + } 91 91 + 92 92 + /** 93 93 + * Resolved identity from PDS resolution 94 94 + */ 95 95 + export interface ResolvedIdentity { 96 96 + did: string; 97 97 + pds: string; 98 98 + handle?: string; 99 99 + } 100 100 + 101 101 + /** 102 102 + * Configuration for the library 103 103 + */ 104 104 + export interface SiteStandardConfig { 105 105 + /** The DID to fetch records from */ 106 106 + did: string; 107 107 + /** Optional custom PDS endpoint */ 108 108 + pds?: string; 109 109 + /** Cache TTL in milliseconds (default: 5 minutes) */ 110 110 + cacheTTL?: number; 111 111 + }

+124

src/lib/utils/agents.ts

··· 1 1 + import { AtpAgent } from '@atproto/api'; 2 2 + import type { ResolvedIdentity } from '../types.js'; 3 3 + import { cache } from './cache.js'; 4 4 + 5 5 + /** 6 6 + * Creates an AtpAgent with optional fetch function injection 7 7 + */ 8 8 + export function createAgent(service: string, fetchFn?: typeof fetch): AtpAgent { 9 9 + const wrappedFetch = fetchFn 10 10 + ? async (url: URL | RequestInfo, init?: RequestInit) => { 11 11 + const urlStr = url instanceof URL ? url.toString() : url; 12 12 + const response = await fetchFn(urlStr, init); 13 13 + 14 14 + const headers = new Headers(response.headers); 15 15 + if (!headers.has('content-type')) { 16 16 + headers.set('content-type', 'application/json'); 17 17 + } 18 18 + 19 19 + return new Response(response.body, { 20 20 + status: response.status, 21 21 + statusText: response.statusText, 22 22 + headers 23 23 + }); 24 24 + } 25 25 + : undefined; 26 26 + 27 27 + return new AtpAgent({ 28 28 + service, 29 29 + ...(wrappedFetch && { fetch: wrappedFetch }) 30 30 + }); 31 31 + } 32 32 + 33 33 + /** 34 34 + * Resolves a DID to find its PDS endpoint using Slingshot 35 35 + * @param did - DID to resolve 36 36 + * @param fetchFn - Optional fetch function for SSR 37 37 + * @returns Resolved identity with PDS endpoint 38 38 + */ 39 39 + export async function resolveIdentity( 40 40 + did: string, 41 41 + fetchFn?: typeof fetch 42 42 + ): Promise<ResolvedIdentity> { 43 43 + const cacheKey = `identity:${did}`; 44 44 + const cached = cache.get<ResolvedIdentity>(cacheKey); 45 45 + if (cached) return cached; 46 46 + 47 47 + const _fetch = fetchFn ?? globalThis.fetch; 48 48 + 49 49 + const response = await _fetch( 50 50 + `https://slingshot.microcosm.blue/xrpc/com.bad-example.identity.resolveMiniDoc?identifier=${encodeURIComponent(did)}` 51 51 + ); 52 52 + 53 53 + if (!response.ok) { 54 54 + throw new Error(`Failed to resolve DID: ${response.status} ${response.statusText}`); 55 55 + } 56 56 + 57 57 + const rawText = await response.text(); 58 58 + const data = JSON.parse(rawText); 59 59 + 60 60 + if (!data.did || !data.pds) { 61 61 + throw new Error('Invalid response from identity resolver'); 62 62 + } 63 63 + 64 64 + cache.set(cacheKey, data); 65 65 + return data; 66 66 + } 67 67 + 68 68 + /** 69 69 + * Gets or creates a PDS-specific agent 70 70 + * @param did - DID to resolve PDS for 71 71 + * @param fetchFn - Optional fetch function for SSR 72 72 + * @returns AtpAgent configured for the user's PDS 73 73 + */ 74 74 + export async function getPDSAgent(did: string, fetchFn?: typeof fetch): Promise<AtpAgent> { 75 75 + const resolved = await resolveIdentity(did, fetchFn); 76 76 + return createAgent(resolved.pds, fetchFn); 77 77 + } 78 78 + 79 79 + /** 80 80 + * Executes a function with automatic fallback 81 81 + * @param did - The DID to resolve 82 82 + * @param operation - The operation to execute 83 83 + * @param fetchFn - Optional fetch function for SSR 84 84 + */ 85 85 + export async function withFallback<T>( 86 86 + did: string, 87 87 + operation: (agent: AtpAgent) => Promise<T>, 88 88 + fetchFn?: typeof fetch 89 89 + ): Promise<T> { 90 90 + const agents = [ 91 91 + () => getPDSAgent(did, fetchFn), 92 92 + () => 93 93 + Promise.resolve( 94 94 + fetchFn 95 95 + ? createAgent('https://public.api.bsky.app', fetchFn) 96 96 + : createAgent('https://public.api.bsky.app') 97 97 + ) 98 98 + ]; 99 99 + 100 100 + let lastError: any; 101 101 + 102 102 + for (const getAgent of agents) { 103 103 + try { 104 104 + const agent = await getAgent(); 105 105 + return await operation(agent); 106 106 + } catch (error) { 107 107 + lastError = error; 108 108 + } 109 109 + } 110 110 + 111 111 + throw lastError; 112 112 + } 113 113 + 114 114 + /** 115 115 + * Build a PDS blob URL 116 116 + * @param pds - PDS endpoint 117 117 + * @param did - Repository DID 118 118 + * @param cid - Blob CID 119 119 + * @returns Full blob URL 120 120 + */ 121 121 + export function buildPdsBlobUrl(pds: string, did: string, cid: string): string { 122 122 + const pdsBase = pds.replace(/\/$/, ''); 123 123 + return `${pdsBase}/xrpc/com.atproto.sync.getBlob?did=${encodeURIComponent(did)}&cid=${encodeURIComponent(cid)}`; 124 124 + }

+89

src/lib/utils/at-uri.ts

··· 1 1 + /** 2 2 + * AT URI parsing and conversion utilities 3 3 + */ 4 4 + 5 5 + /** 6 6 + * Parsed AT URI components 7 7 + */ 8 8 + export interface ParsedAtUri { 9 9 + did: string; 10 10 + collection: string; 11 11 + rkey: string; 12 12 + } 13 13 + 14 14 + /** 15 15 + * Parse an AT URI into its components 16 16 + * @param atUri - AT URI in format: at://did:plc:xxx/collection/rkey 17 17 + * @returns Parsed components or null if invalid 18 18 + */ 19 19 + export function parseAtUri(atUri: string): ParsedAtUri | null { 20 20 + if (!atUri.startsWith('at://')) return null; 21 21 + 22 22 + const withoutProtocol = atUri.slice(5); // Remove "at://" 23 23 + const parts = withoutProtocol.split('/'); 24 24 + 25 25 + if (parts.length !== 3) return null; 26 26 + 27 27 + const [did, collection, rkey] = parts; 28 28 + 29 29 + if (!did.startsWith('did:') || !collection || !rkey) return null; 30 30 + 31 31 + return { did, collection, rkey }; 32 32 + } 33 33 + 34 34 + /** 35 35 + * Convert AT URI to HTTPS URL for com.atproto.repo.getRecord 36 36 + * @param atUri - AT URI in format: at://did:plc:xxx/collection/rkey 37 37 + * @param pdsEndpoint - PDS endpoint (e.g., "https://cortinarius.us-west.host.bsky.network") 38 38 + * @returns HTTPS URL for getRecord XRPC call 39 39 + */ 40 40 + export function atUriToHttps(atUri: string, pdsEndpoint: string): string | null { 41 41 + const parsed = parseAtUri(atUri); 42 42 + if (!parsed) return null; 43 43 + 44 44 + // Ensure PDS endpoint doesn't have trailing slash 45 45 + const pds = pdsEndpoint.replace(/\/$/, ''); 46 46 + 47 47 + return `${pds}/xrpc/com.atproto.repo.getRecord?repo=${encodeURIComponent(parsed.did)}&collection=${encodeURIComponent(parsed.collection)}&rkey=${encodeURIComponent(parsed.rkey)}`; 48 48 + } 49 49 + 50 50 + /** 51 51 + * Construct an AT URI from components 52 52 + * @param did - DID of the repository 53 53 + * @param collection - Collection name 54 54 + * @param rkey - Record key 55 55 + * @returns AT URI string 56 56 + */ 57 57 + export function buildAtUri(did: string, collection: string, rkey: string): string { 58 58 + return `at://${did}/${collection}/${rkey}`; 59 59 + } 60 60 + 61 61 + /** 62 62 + * Extract rkey from an AT URI 63 63 + * @param atUri - AT URI 64 64 + * @returns rkey or null if invalid 65 65 + */ 66 66 + export function extractRkey(atUri: string): string | null { 67 67 + const parsed = parseAtUri(atUri); 68 68 + return parsed?.rkey ?? null; 69 69 + } 70 70 + 71 71 + /** 72 72 + * Validate if string is a valid AT URI 73 73 + * @param uri - String to validate 74 74 + * @returns true if valid AT URI 75 75 + */ 76 76 + export function isAtUri(uri: string): boolean { 77 77 + return parseAtUri(uri) !== null; 78 78 + } 79 79 + 80 80 + /** 81 81 + * Convert DID to PDS hostname format 82 82 + * @param did - DID to convert 83 83 + * @returns PDS hostname or null if unable to derive 84 84 + */ 85 85 + export function didToPdsHostname(did: string): string | null { 86 86 + // This is a simplified version - real implementation should use DID resolution 87 87 + // For now, we'll return null and rely on explicit PDS configuration 88 88 + return null; 89 89 + }

+46

src/lib/utils/cache.ts

··· 1 1 + /** 2 2 + * Simple in-memory cache with TTL support 3 3 + */ 4 4 + 5 5 + interface CacheEntry<T> { 6 6 + value: T; 7 7 + expires: number; 8 8 + } 9 9 + 10 10 + class Cache { 11 11 + private store = new Map<string, CacheEntry<any>>(); 12 12 + private defaultTTL = 5 * 60 * 1000; // 5 minutes 13 13 + 14 14 + get<T>(key: string): T | null { 15 15 + const entry = this.store.get(key); 16 16 + if (!entry) return null; 17 17 + 18 18 + if (Date.now() > entry.expires) { 19 19 + this.store.delete(key); 20 20 + return null; 21 21 + } 22 22 + 23 23 + return entry.value; 24 24 + } 25 25 + 26 26 + set<T>(key: string, value: T, ttl?: number): void { 27 27 + this.store.set(key, { 28 28 + value, 29 29 + expires: Date.now() + (ttl ?? this.defaultTTL) 30 30 + }); 31 31 + } 32 32 + 33 33 + delete(key: string): void { 34 34 + this.store.delete(key); 35 35 + } 36 36 + 37 37 + clear(): void { 38 38 + this.store.clear(); 39 39 + } 40 40 + 41 41 + setDefaultTTL(ttl: number): void { 42 42 + this.defaultTTL = ttl; 43 43 + } 44 44 + } 45 45 + 46 46 + export const cache = new Cache();

+41

src/lib/utils/document.ts

··· 1 1 + /** 2 2 + * Extract rkey from AT URI 3 3 + */ 4 4 + export function extractRkey(uri: string): string | null { 5 5 + const match = uri.match(/at:\/\/[^\/]+\/[^\/]+\/(.+)$/); 6 6 + return match ? match[1] : null; 7 7 + } 8 8 + 9 9 + /** 10 10 + * Get document slug (uses path if available, otherwise rkey) 11 11 + */ 12 12 + export function getDocumentSlug(document: { uri: string; value: { path?: string } }): string { 13 13 + if (document.value.path) { 14 14 + // Remove leading slash if present 15 15 + return document.value.path.replace(/^\//, ''); 16 16 + } 17 17 + return extractRkey(document.uri) || ''; 18 18 + } 19 19 + 20 20 + /** 21 21 + * Get document canonical URL 22 22 + */ 23 23 + export function getDocumentUrl(document: { 24 24 + value: { site: string; path?: string }; 25 25 + uri: string; 26 26 + }): string { 27 27 + const { site, path } = document.value; 28 28 + 29 29 + // If site is an AT URI, we'll use our local route 30 30 + if (site.startsWith('at://')) { 31 31 + return `/documents/${getDocumentSlug(document as any)}`; 32 32 + } 33 33 + 34 34 + // If site is HTTPS and we have a path, combine them 35 35 + if (path) { 36 36 + return `${site.replace(/\/$/, '')}/${path.replace(/^\//, '')}`; 37 37 + } 38 38 + 39 39 + // Fallback to local route 40 40 + return `/documents/${extractRkey(document.uri)}`; 41 41 + }

+33

src/lib/utils/theme.ts

··· 1 1 + import type { RGBColor } from '../types.js'; 2 2 + 3 3 + /** 4 4 + * Convert RGB color object to CSS rgb() string 5 5 + */ 6 6 + export function rgbToCSS(color: RGBColor): string { 7 7 + return `rgb(${color.r}, ${color.g}, ${color.b})`; 8 8 + } 9 9 + 10 10 + /** 11 11 + * Convert RGB color object to hex string 12 12 + */ 13 13 + export function rgbToHex(color: RGBColor): string { 14 14 + const toHex = (n: number) => n.toString(16).padStart(2, '0'); 15 15 + return `#${toHex(color.r)}${toHex(color.g)}${toHex(color.b)}`; 16 16 + } 17 17 + 18 18 + /** 19 19 + * Get theme CSS variables from BasicTheme 20 20 + */ 21 21 + export function getThemeVars(theme: { 22 22 + background: RGBColor; 23 23 + foreground: RGBColor; 24 24 + accent: RGBColor; 25 25 + accentForeground: RGBColor; 26 26 + }): Record<string, string> { 27 27 + return { 28 28 + '--theme-background': rgbToCSS(theme.background), 29 29 + '--theme-foreground': rgbToCSS(theme.foreground), 30 30 + '--theme-accent': rgbToCSS(theme.accent), 31 31 + '--theme-accent-foreground': rgbToCSS(theme.accentForeground) 32 32 + }; 33 33 + }

+40

src/routes/+page.server.ts

··· 1 1 + import { createClient } from '$lib/index.js'; 2 2 + import { getConfigFromEnv } from '$lib/config/env.js'; 3 3 + import type { PageServerLoad } from './$types.js'; 4 4 + 5 5 + export const load: PageServerLoad = async ({ fetch }) => { 6 6 + const config = getConfigFromEnv(); 7 7 + 8 8 + if (!config) { 9 9 + return { 10 10 + error: 'Missing configuration. Please set PUBLIC_ATPROTO_DID in your .env file.', 11 11 + publications: [], 12 12 + documents: [] 13 13 + }; 14 14 + } 15 15 + 16 16 + const client = createClient(config); 17 17 + 18 18 + try { 19 19 + const [publications, documents] = await Promise.all([ 20 20 + client.fetchAllPublications(fetch), 21 21 + client.fetchAllDocuments(fetch) 22 22 + ]); 23 23 + 24 24 + const pds = await client.getPDS(fetch); 25 25 + 26 26 + return { 27 27 + config, 28 28 + publications: JSON.parse(JSON.stringify(publications)), 29 29 + documents: JSON.parse(JSON.stringify(documents)), 30 30 + pds 31 31 + }; 32 32 + } catch (error) { 33 33 + console.error('Failed to load data:', error); 34 34 + return { 35 35 + error: error instanceof Error ? error.message : 'Failed to load data', 36 36 + publications: [], 37 37 + documents: [] 38 38 + }; 39 39 + } 40 40 + };

+215 -3

src/routes/+page.svelte

··· 1 1 - <h1>Welcome to your library project</h1> 2 2 - <p>Create your package using @sveltejs/package and preview/showcase your work with SvelteKit</p> 3 3 - <p>Visit <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a> to read the documentation</p> 1 1 + <script lang="ts"> 2 2 + import type { PageData } from './$types.js'; 3 3 + import { PublicationCard, DocumentCard } from '$lib/components/index.js'; 4 4 + 5 5 + const { data }: { data: PageData } = $props(); 6 6 + </script> 7 7 + 8 8 + <svelte:head> 9 9 + <title>Standard.Site Library - Showcase</title> 10 10 + <meta 11 11 + name="description" 12 12 + content="A SvelteKit library for fetching site.standard.* records from AT Protocol" 13 13 + /> 14 14 + </svelte:head> 15 15 + 16 16 + <div class="mx-auto max-w-7xl px-4 py-12"> 17 17 + <!-- Hero Section --> 18 18 + <header class="mb-16 text-center"> 19 19 + <h1 class="mb-4 text-5xl font-bold tracking-tight"> 20 20 + <span class="bg-linear-to-r from-blue-600 to-purple-600 bg-clip-text text-transparent"> 21 21 + Standard.Site 22 22 + </span> 23 23 + <span class="text-gray-900">Library</span> 24 24 + </h1> 25 25 + <p class="mx-auto mb-6 max-w-2xl text-xl text-gray-600"> 26 26 + A powerful SvelteKit library for fetching <code 27 27 + class="rounded bg-gray-100 px-2 py-1 text-base">site.standard.*</code 28 28 + > records from the AT Protocol ecosystem 29 29 + </p> 30 30 + <div class="flex items-center justify-center gap-4"> 31 31 + <a 32 32 + href="https://github.com/ewanc26/svelte-standard-site" 33 33 + target="_blank" 34 34 + rel="noopener noreferrer" 35 35 + class="rounded-lg bg-gray-900 px-6 py-3 font-semibold text-white transition hover:bg-gray-800" 36 36 + > 37 37 + View on GitHub 38 38 + </a> 39 39 + </div> 40 40 + </header> 41 41 + 42 42 + {#if data.error} 43 43 + <!-- Error State --> 44 44 + <div class="mb-12 rounded-xl border-2 border-red-200 bg-red-50 p-8"> 45 45 + <div class="flex items-start gap-4"> 46 46 + <svg 47 47 + class="size-6 shrink-0 text-red-600" 48 48 + fill="none" 49 49 + viewBox="0 0 24 24" 50 50 + stroke="currentColor" 51 51 + > 52 52 + <path 53 53 + stroke-linecap="round" 54 54 + stroke-linejoin="round" 55 55 + stroke-width="2" 56 56 + d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" 57 57 + /> 58 58 + </svg> 59 59 + <div class="flex-1"> 60 60 + <h2 class="mb-2 text-xl font-bold text-red-900">Configuration Error</h2> 61 61 + <p class="mb-4 text-red-800">{data.error}</p> 62 62 + <div class="rounded-lg bg-white p-4"> 63 63 + <p class="mb-2 font-semibold text-gray-900">Quick Fix:</p> 64 64 + <ol class="list-inside list-decimal space-y-2 text-sm text-gray-700"> 65 65 + <li> 66 66 + Create a <code class="rounded bg-gray-100 px-2 py-1">.env</code> file in your project 67 67 + root 68 68 + </li> 69 69 + <li> 70 70 + Add: <code class="rounded bg-gray-100 px-2 py-1" 71 71 + >PUBLIC_ATPROTO_DID=your-did-here</code 72 72 + > 73 73 + </li> 74 74 + <li>Restart your dev server</li> 75 75 + </ol> 76 76 + </div> 77 77 + </div> 78 78 + </div> 79 79 + </div> 80 80 + {:else} 81 81 + <!-- Configuration Info --> 82 82 + <section class="mb-16 rounded-xl bg-linear-to-r from-blue-50 to-purple-50 p-8"> 83 83 + <h2 class="mb-6 text-2xl font-bold text-gray-900">Active Configuration</h2> 84 84 + <div class="grid gap-6 md:grid-cols-2"> 85 85 + <div class="rounded-lg bg-white p-6 shadow-sm"> 86 86 + <dt class="mb-2 text-sm font-medium text-gray-600">DID</dt> 87 87 + <dd class="font-mono text-sm break-all text-gray-900">{data.config?.did}</dd> 88 88 + </div> 89 89 + <div class="rounded-lg bg-white p-6 shadow-sm"> 90 90 + <dt class="mb-2 text-sm font-medium text-gray-600">PDS Endpoint</dt> 91 91 + <dd class="font-mono text-sm break-all text-gray-900"> 92 92 + {data.pds || 'Auto-resolved'} 93 93 + </dd> 94 94 + </div> 95 95 + </div> 96 96 + </section> 97 97 + 98 98 + <!-- Publications Section --> 99 99 + <section class="mb-16"> 100 100 + <div class="mb-8 flex items-end justify-between"> 101 101 + <div> 102 102 + <h2 class="text-3xl font-bold text-gray-900">Publications</h2> 103 103 + <p class="mt-2 text-gray-600"> 104 104 + Site.standard.publication records from the configured repository 105 105 + </p> 106 106 + </div> 107 107 + <div class="rounded-full bg-blue-100 px-4 py-2 text-sm font-semibold text-blue-800"> 108 108 + {data.publications.length} found 109 109 + </div> 110 110 + </div> 111 111 + {#if data.publications.length === 0} 112 112 + <div class="rounded-xl border-2 border-dashed border-gray-300 p-12 text-center"> 113 113 + <svg 114 114 + class="mx-auto mb-4 size-12 text-gray-400" 115 115 + fill="none" 116 116 + viewBox="0 0 24 24" 117 117 + stroke="currentColor" 118 118 + > 119 119 + <path 120 120 + stroke-linecap="round" 121 121 + stroke-linejoin="round" 122 122 + stroke-width="2" 123 123 + d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" 124 124 + /> 125 125 + </svg> 126 126 + <h3 class="mb-2 text-lg font-semibold text-gray-900">No Publications Found</h3> 127 127 + <p class="text-gray-600"> 128 128 + This repository doesn't have any <code>site.standard.publication</code> records yet. 129 129 + </p> 130 130 + </div> 131 131 + {:else} 132 132 + <div class="grid gap-6 md:grid-cols-2 lg:grid-cols-3"> 133 133 + {#each data.publications as publication} 134 134 + <PublicationCard {publication} /> 135 135 + {/each} 136 136 + </div> 137 137 + {/if} 138 138 + </section> 139 139 + 140 140 + <!-- Documents Section --> 141 141 + <section> 142 142 + <div class="mb-8 flex items-end justify-between"> 143 143 + <div> 144 144 + <h2 class="text-3xl font-bold text-gray-900">Documents</h2> 145 145 + <p class="mt-2 text-gray-600"> 146 146 + <code>site.standard.document</code> records, sorted by publication date 147 147 + </p> 148 148 + </div> 149 149 + <div class="rounded-full bg-purple-100 px-4 py-2 text-sm font-semibold text-purple-800"> 150 150 + {data.documents.length} found 151 151 + </div> 152 152 + </div> 153 153 + {#if data.documents.length === 0} 154 154 + <div class="rounded-xl border-2 border-dashed border-gray-300 p-12 text-center"> 155 155 + <svg 156 156 + class="mx-auto mb-4 size-12 text-gray-400" 157 157 + fill="none" 158 158 + viewBox="0 0 24 24" 159 159 + stroke="currentColor" 160 160 + > 161 161 + <path 162 162 + stroke-linecap="round" 163 163 + stroke-linejoin="round" 164 164 + stroke-width="2" 165 165 + d="M7 21h10a2 2 0 002-2V9.414a1 1 0 00-.293-.707l-5.414-5.414A1 1 0 0012.586 3H7a2 2 0 00-2 2v14a2 2 0 002 2z" 166 166 + /> 167 167 + </svg> 168 168 + <h3 class="mb-2 text-lg font-semibold text-gray-900">No Documents Found</h3> 169 169 + <p class="text-gray-600"> 170 170 + This repository doesn't have any <code>site.standard.document</code> records yet. 171 171 + </p> 172 172 + </div> 173 173 + {:else} 174 174 + <div class="space-y-6"> 175 175 + {#each data.documents as document} 176 176 + <DocumentCard {document} /> 177 177 + {/each} 178 178 + </div> 179 179 + {/if} 180 180 + </section> 181 181 + 182 182 + <!-- Stats Footer --> 183 183 + <footer class="mt-16 rounded-xl bg-gray-50 p-8 text-center"> 184 184 + <div class="mb-4 flex items-center justify-center gap-8"> 185 185 + <div> 186 186 + <div class="text-4xl font-bold text-blue-600">{data.publications.length}</div> 187 187 + <div class="text-sm font-medium text-gray-600"> 188 188 + Publication{data.publications.length === 1 ? '' : 's'} 189 189 + </div> 190 190 + </div> 191 191 + <div class="h-12 w-px bg-gray-300"></div> 192 192 + <div> 193 193 + <div class="text-4xl font-bold text-purple-600">{data.documents.length}</div> 194 194 + <div class="text-sm font-medium text-gray-600"> 195 195 + Document{data.documents.length === 1 ? '' : 's'} 196 196 + </div> 197 197 + </div> 198 198 + </div> 199 199 + <p class="text-sm text-gray-600"> 200 200 + Powered by <a 201 201 + href="https://atproto.com" 202 202 + target="_blank" 203 203 + rel="noopener noreferrer" 204 204 + class="font-semibold text-blue-600 hover:underline">AT Protocol</a 205 205 + >, created by 206 206 + <a 207 207 + href="https://ewancroft.uk" 208 208 + target="_blank" 209 209 + rel="noopener noreferrer" 210 210 + class="font-semibold text-blue-600 hover:underline">Ewan Croft</a 211 211 + > 212 212 + </p> 213 213 + </footer> 214 214 + {/if} 215 215 + </div>

+53

src/routes/[pub_rkey]/[doc_rkey]/+page.server.ts

··· 1 1 + import { createClient } from '$lib/index.js'; 2 2 + import { getConfigFromEnv } from '$lib/config/env.js'; 3 3 + import { extractRkey } from '$lib/utils/document.js'; 4 4 + import { error } from '@sveltejs/kit'; 5 5 + import type { PageServerLoad } from './$types.js'; 6 6 + 7 7 + export const load: PageServerLoad = async ({ params, fetch }) => { 8 8 + const config = getConfigFromEnv(); 9 9 + 10 10 + if (!config) { 11 11 + throw error(500, 'Missing configuration. Please set PUBLIC_ATPROTO_DID in your .env file.'); 12 12 + } 13 13 + 14 14 + const client = createClient(config); 15 15 + const { pub_rkey, doc_rkey } = params; 16 16 + 17 17 + try { 18 18 + // 1. Fetch the specific document by its rkey 19 19 + // Assuming client.fetchDocument exists; if not, use fetchAllDocuments and find 20 20 + const documents = await client.fetchAllDocuments(fetch); 21 21 + 22 22 + const document = documents.find((doc) => { 23 23 + const rkey = extractRkey(doc.uri); 24 24 + const parentPubRkey = extractRkey(doc.value.site); 25 25 + // Validate both the document rkey AND that it belongs to the publication in the URL 26 26 + return rkey === doc_rkey && parentPubRkey === pub_rkey; 27 27 + }); 28 28 + 29 29 + if (!document) { 30 30 + throw error(404, 'Document not found under this publication'); 31 31 + } 32 32 + 33 33 + // 2. Fetch the publication metadata 34 34 + const publication = await client.fetchPublication(pub_rkey, fetch); 35 35 + 36 36 + if (!publication) { 37 37 + throw error(404, 'Publication not found'); 38 38 + } 39 39 + 40 40 + // 3. Return sanitized data to prevent "non-POJO" serialization errors 41 41 + return { 42 42 + document: JSON.parse(JSON.stringify(document)), 43 43 + publication: JSON.parse(JSON.stringify(publication)), 44 44 + config 45 45 + }; 46 46 + } catch (err) { 47 47 + console.error('Failed to load document:', err); 48 48 + if (err && typeof err === 'object' && 'status' in err) { 49 49 + throw err; 50 50 + } 51 51 + throw error(500, 'Failed to load document'); 52 52 + } 53 53 + };

+204

src/routes/[pub_rkey]/[doc_rkey]/+page.svelte

··· 1 1 + <script lang="ts"> 2 2 + import type { PageData } from './$types.js'; 3 3 + import { getThemeVars } from '$lib/utils/theme.js'; 4 4 + import { extractRkey } from '$lib/utils/document.js'; 5 5 + 6 6 + const { data }: { data: PageData } = $props(); 7 7 + 8 8 + const themeVars = $derived( 9 9 + data.publication?.value.basicTheme ? getThemeVars(data.publication.value.basicTheme) : {} 10 10 + ); 11 11 + 12 12 + function formatDate(dateString: string): string { 13 13 + return new Date(dateString).toLocaleDateString('en-US', { 14 14 + year: 'numeric', 15 15 + month: 'long', 16 16 + day: 'numeric' 17 17 + }); 18 18 + } 19 19 + </script> 20 20 + 21 21 + <svelte:head> 22 22 + <title>{data.document.value.title}</title> 23 23 + {#if data.document.value.description} 24 24 + <meta name="description" content={data.document.value.description} /> 25 25 + {/if} 26 26 + </svelte:head> 27 27 + 28 28 + <div 29 29 + class="min-h-screen" 30 30 + style:background-color={data.publication?.value.basicTheme 31 31 + ? `var(--theme-background)` 32 32 + : undefined} 33 33 + style={Object.entries(themeVars) 34 34 + .map(([k, v]) => `${k}:${v}`) 35 35 + .join(';')} 36 36 + > 37 37 + <article class="mx-auto max-w-4xl px-4 py-12"> 38 38 + <!-- Back link --> 39 39 + <a 40 40 + href="/" 41 41 + class="mb-8 inline-flex items-center gap-2 text-sm font-medium transition-opacity hover:opacity-70" 42 42 + style:color={data.publication?.value.basicTheme ? `var(--theme-accent)` : undefined} 43 43 + > 44 44 + <svg class="size-4" fill="none" viewBox="0 0 24 24" stroke="currentColor"> 45 45 + <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 19l-7-7 7-7" /> 46 46 + </svg> 47 47 + Back to Home 48 48 + </a> 49 49 + 50 50 + <!-- Publication info if available --> 51 51 + {#if data.publication} 52 52 + <div class="mb-8 flex items-center gap-3"> 53 53 + {#if data.publication.value.icon} 54 54 + <img 55 55 + src={data.publication.value.icon} 56 56 + alt="{data.publication.value.name} icon" 57 57 + class="size-10 rounded-lg object-cover" 58 58 + /> 59 59 + {/if} 60 60 + <div> 61 61 + <div 62 62 + class="text-sm font-medium" 63 63 + style:color={data.publication.value.basicTheme ? `var(--theme-foreground)` : undefined} 64 64 + > 65 65 + {data.publication.value.name} 66 66 + </div> 67 67 + {#if data.publication.value.url} 68 68 + <a 69 69 + href={data.publication.value.url} 70 70 + target="_blank" 71 71 + rel="noopener noreferrer" 72 72 + class="text-xs transition-opacity hover:opacity-70" 73 73 + style:color={data.publication.value.basicTheme ? `var(--theme-accent)` : undefined} 74 74 + > 75 75 + {data.publication.value.url} 76 76 + </a> 77 77 + {/if} 78 78 + </div> 79 79 + </div> 80 80 + {/if} 81 81 + 82 82 + <!-- Document header --> 83 83 + <header class="mb-8"> 84 84 + <h1 85 85 + class="mb-4 text-4xl leading-tight font-bold md:text-5xl" 86 86 + style:color={data.publication?.value.basicTheme ? `var(--theme-foreground)` : undefined} 87 87 + > 88 88 + {data.document.value.title} 89 89 + </h1> 90 90 + 91 91 + <div 92 92 + class="flex flex-wrap items-center gap-x-6 gap-y-2 border-b pb-6 text-sm" 93 93 + style:border-color={data.publication?.value.basicTheme 94 94 + ? `var(--theme-foreground, rgb(229, 231, 235))` 95 95 + : 'rgb(229, 231, 235)'} 96 96 + style:opacity={data.publication?.value.basicTheme ? '0.3' : '1'} 97 97 + > 98 98 + <time 99 99 + class="font-medium" 100 100 + style:color={data.publication?.value.basicTheme 101 101 + ? `var(--theme-foreground)` 102 102 + : 'rgb(17, 24, 39)'} 103 103 + > 104 104 + Published {formatDate(data.document.value.publishedAt)} 105 105 + </time> 106 106 + {#if data.document.value.updatedAt} 107 107 + <span 108 108 + style:color={data.publication?.value.basicTheme 109 109 + ? `var(--theme-foreground)` 110 110 + : 'rgb(107, 114, 128)'} 111 111 + > 112 112 + Updated {formatDate(data.document.value.updatedAt)} 113 113 + </span> 114 114 + {/if} 115 115 + </div> 116 116 + </header> 117 117 + 118 118 + <!-- Cover image --> 119 119 + {#if data.document.value.coverImage} 120 120 + <div class="mb-8"> 121 121 + <img 122 122 + src={data.document.value.coverImage} 123 123 + alt="{data.document.value.title} cover" 124 124 + class="w-full rounded-lg object-cover shadow-lg" 125 125 + style="max-height: 500px;" 126 126 + /> 127 127 + </div> 128 128 + {/if} 129 129 + 130 130 + <!-- Document content --> 131 131 + <div 132 132 + class="mx-auto prose prose-lg max-w-none" 133 133 + style:color={data.publication?.value.basicTheme ? `var(--theme-foreground)` : undefined} 134 134 + > 135 135 + {#if data.document.value.textContent} 136 136 + <div class="whitespace-pre-wrap">{data.document.value.textContent}</div> 137 137 + {:else if data.document.value.content} 138 138 + <div class="rounded-lg border border-gray-200 bg-gray-50 p-6"> 139 139 + <p class="mb-2 text-sm font-medium text-gray-700">Raw Content:</p> 140 140 + <pre class="overflow-x-auto text-xs">{JSON.stringify( 141 141 + data.document.value.content, 142 142 + null, 143 143 + 2 144 144 + )}</pre> 145 145 + </div> 146 146 + {:else} 147 147 + <p class="text-gray-500 italic">No content available</p> 148 148 + {/if} 149 149 + </div> 150 150 + 151 151 + <!-- Tags --> 152 152 + {#if data.document.value.tags && data.document.value.tags.length > 0} 153 153 + <div 154 154 + class="mt-12 border-t pt-8" 155 155 + style:border-color={data.publication?.value.basicTheme 156 156 + ? `var(--theme-foreground, rgb(229, 231, 235))` 157 157 + : 'rgb(229, 231, 235)'} 158 158 + style:opacity={data.publication?.value.basicTheme ? '0.3' : '1'} 159 159 + > 160 160 + <h2 161 161 + class="mb-4 text-sm font-medium tracking-wide uppercase" 162 162 + style:color={data.publication?.value.basicTheme 163 163 + ? `var(--theme-foreground)` 164 164 + : 'rgb(107, 114, 128)'} 165 165 + > 166 166 + Tags 167 167 + </h2> 168 168 + <div class="flex flex-wrap gap-2"> 169 169 + {#each data.document.value.tags as tag} 170 170 + <span 171 171 + class="rounded-full px-4 py-2 text-sm font-medium" 172 172 + style:background-color={data.publication?.value.basicTheme 173 173 + ? `var(--theme-accent, rgb(243, 244, 246))` 174 174 + : 'rgb(243, 244, 246)'} 175 175 + style:color={data.publication?.value.basicTheme 176 176 + ? `var(--theme-accent-foreground, rgb(75, 85, 99))` 177 177 + : 'rgb(75, 85, 99)'} 178 178 + > 179 179 + {tag} 180 180 + </span> 181 181 + {/each} 182 182 + </div> 183 183 + </div> 184 184 + {/if} 185 185 + 186 186 + <!-- Bluesky post reference --> 187 187 + {#if data.document.value.bskyPostRef} 188 188 + <div class="mt-8 rounded-lg border border-blue-200 bg-blue-50 p-4"> 189 189 + <p class="text-sm text-blue-900"> 190 190 + <a 191 191 + href="https://bsky.app/profile/{data.config?.did}/post/{extractRkey( 192 192 + data.document.value.bskyPostRef.uri 193 193 + )}" 194 194 + target="_blank" 195 195 + rel="noopener noreferrer" 196 196 + class="font-medium hover:underline" 197 197 + > 198 198 + View discussion on Bluesky → 199 199 + </a> 200 200 + </p> 201 201 + </div> 202 202 + {/if} 203 203 + </article> 204 204 + </div>