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