web components for a integrable atproto based guestbook
nekomimi.pet
1# cutebook
2
3Web components for AT Protocol guestbooks. Sign and display guestbook entries stored in user repositories, indexed via Constellation.
4
5Demo: https://guestbook.nkp.pet/
6
7## Installation
8
9```bash
10npm install cutebook
11```
12
13Peer dependencies:
14
15```bash
16npm install @atcute/client @atcute/oauth-browser-client @atcute/identity-resolver
17```
18
19## Quick Start
20
21The simplest way to use the components is with the auto-register entry point:
22
23```ts
24import { configureGuestbook } from 'cutebook/register';
25
26configureGuestbook({
27 oauth: {
28 clientId: 'https://your-app.com/client-metadata.json',
29 redirectUri: 'https://your-app.com/',
30 scope: 'atproto transition:generic',
31 },
32});
33```
34
35Then use the custom elements in your HTML:
36
37```html
38<guestbook-sign did="did:plc:your-did-here"></guestbook-sign>
39<guestbook-display did="did:plc:your-did-here" limit="50"></guestbook-display>
40```
41
42## Manual Registration
43
44If you need more control over element registration:
45
46```ts
47import {
48 GuestbookSignElement,
49 GuestbookDisplayElement,
50 configureGuestbook
51} from 'cutebook';
52
53configureGuestbook({
54 oauth: {
55 clientId: 'https://your-app.com/client-metadata.json',
56 redirectUri: 'https://your-app.com/',
57 scope: 'atproto transition:generic',
58 },
59});
60
61customElements.define('my-guestbook-sign', GuestbookSignElement);
62customElements.define('my-guestbook-display', GuestbookDisplayElement);
63```
64
65## Components
66
67### guestbook-sign
68
69A form component that handles OAuth authentication and record creation.
70
71| Attribute | Description |
72|-----------|-------------|
73| `did` | The DID of the guestbook owner (required) |
74
75Dispatches a `sign-created` event with `{ uri, cid }` when a signature is successfully created.
76
77### guestbook-display
78
79Displays guestbook signatures by querying Constellation for backlinks.
80
81| Attribute | Description |
82|-----------|-------------|
83| `did` | The DID of the guestbook owner (required) |
84| `limit` | Maximum number of entries to display (default: 50) |
85
86Call `.refresh()` on the element to reload signatures.
87
88## Lexicon
89
90Signatures use the `pet.nkp.guestbook.sign` record type:
91
92```json
93{
94 "$type": "pet.nkp.guestbook.sign",
95 "subject": "did:plc:guestbook-owner",
96 "message": "Your message here",
97 "createdAt": "2024-01-01T00:00:00.000Z"
98}
99```
100
101## Development
102
103```bash
104npm run dev # Run demo app
105npm run build # Build library
106npm run build:demo # Build demo app
107npm run check # Type check
108```
109
110## Credits
111
112Handle typeahead powered by [actor-typeahead](https://tangled.org/jakelazaroff.com/actor-typeahead) by Jake Lazaroff.
113
114## License
115
116MIT