git.stevedylan.dev

Add sequoia-recommend component fee58dda

Resolves #31

Heath Stewart · 2026-05-28 00:01 16 file(s) · +1897 −537

docs/docs/pages/recommend.mdx (added) +238 −0

1	+	# Recommend
2	+
3	+	Sequoia provides a recommend button web component that lets your readers recommend a document directly from your site using their AT Protocol account.
4	+
5	+	## Setup
6	+
7	+	The recommend component is bundled in the same file as the subscribe component. Run the following command to install it if you haven't already:
8	+
9	+	```bash [Terminal]
10	+	sequoia add sequoia-subscribe
11	+	```
12	+
13	+	The component will look for your document AT URI from a `<link rel="site.standard.document">` tag in the page `<head>` automatically, so no additional configuration is required for most setups.
14	+
15	+	:::tip
16	+	`sequoia-subscribe.js` registers both the `<sequoia-subscribe>` and `<sequoia-recommend>` custom elements. You only need to import it once even if you use both components on the same page.
17	+	:::
18	+
19	+	## Usage
20	+
21	+	Since `sequoia-recommend` is a standard Web Component, it works with any framework. Choose your setup below:
22	+
23	+	:::code-group
24	+
25	+	```html [HTML]
26	+	<head>
27	+	<!-- Optional: set the document URI via a link tag -->
28	+	<link rel="site.standard.document" href="at://did:plc:example/app.bsky.feed.post/rkey" />
29	+	</head>
30	+	<body>
31	+	<h1>My Post</h1>
32	+	<!--Content-->
33	+
34	+	<sequoia-recommend></sequoia-recommend>
35	+	<script type="module" src="./src/components/sequoia-subscribe.js"></script>
36	+	</body>
37	+	```
38	+
39	+	```tsx [React]
40	+	// Import the component (registers both custom elements)
41	+	import './components/sequoia-subscribe.js';
42	+
43	+	function PostPage() {
44	+	return (
45	+	<main>
46	+	<h1>My Post</h1>
47	+	{/* Content */}
48	+	<sequoia-recommend document-uri="at://did:plc:example/app.bsky.feed.post/rkey" />
49	+	</main>
50	+	);
51	+	}
52	+	```
53	+
54	+	```vue [Vue]
55	+	<script setup>
56	+	import './components/sequoia-subscribe.js';
57	+	</script>
58	+
59	+	<template>
60	+	<main>
61	+	<h1>My Post</h1>
62	+	<!-- Content -->
63	+	<sequoia-recommend document-uri="at://did:plc:example/app.bsky.feed.post/rkey" />
64	+	</main>
65	+	</template>
66	+	```
67	+
68	+	```svelte [Svelte]
69	+	<script>
70	+	import './components/sequoia-subscribe.js';
71	+	</script>
72	+
73	+	<main>
74	+	<h1>My Post</h1>
75	+	<!-- Content -->
76	+	<sequoia-recommend document-uri="at://did:plc:example/app.bsky.feed.post/rkey" />
77	+	</main>
78	+	```
79	+
80	+	```astro [Astro]
81	+	<main>
82	+	<h1>My Post</h1>
83	+	<!-- Content -->
84	+	<sequoia-recommend document-uri="at://did:plc:example/app.bsky.feed.post/rkey" />
85	+	<script>
86	+	import './components/sequoia-subscribe.js';
87	+	</script>
88	+	</main>
89	+	```
90	+
91	+	:::
92	+
93	+	### TypeScript Support
94	+
95	+	If you're using TypeScript with React, add this type declaration to avoid JSX errors:
96	+
97	+	```ts [custom-elements.d.ts]
98	+	declare namespace JSX {
99	+	interface IntrinsicElements {
100	+	'sequoia-recommend': React.DetailedHTMLProps<
101	+	React.HTMLAttributes<HTMLElement> & {
102	+	'document-uri'?: string;
103	+	'callback-uri'?: string;
104	+	'button-type'?: 'heart' \| 'star' \| 'thumbs-up';
105	+	hide?: string;
106	+	},
107	+	HTMLElement
108	+	>;
109	+	}
110	+	}
111	+	```
112	+
113	+	### Vue Configuration
114	+
115	+	For Vue, you may need to configure the compiler to recognize custom elements:
116	+
117	+	```ts [vite.config.ts]
118	+	export default defineConfig({
119	+	plugins: [
120	+	vue({
121	+	template: {
122	+	compilerOptions: {
123	+	isCustomElement: (tag) => tag === 'sequoia-recommend'
124	+	}
125	+	}
126	+	})
127	+	]
128	+	});
129	+	```
130	+
131	+	## Configuration
132	+
133	+	The recommend web component has several configuration options available.
134	+
135	+	### Attributes
136	+
137	+	The `<sequoia-recommend>` component accepts the following attributes:
138	+
139	+	\| Attribute \| Type \| Default \| Description \|
140	+	\|-----------\|------\|---------\|-------------\|
141	+	\| `document-uri` \| `string` \| - \| AT Protocol URI for the document to recommend. Optional if a `<link rel="site.standard.document">` tag exists in the page `<head>`. \|
142	+	\| `callback-uri` \| `string` \| `https://sequoia.pub/recommend` \| Redirect URI used for the OAuth authentication flow. \|
143	+	\| `button-type` \| `string` \| `heart` \| Icon style for the button. Accepted values: `heart`, `star`, `thumbs-up`. \|
144	+	\| `hide` \| `string` \| - \| Set to `"auto"` to hide the component if no document URI is detected. \|
145	+
146	+	#### Button Types
147	+
148	+	The `button-type` attribute controls which icon the button uses. Icons are outlined when not yet recommended and filled once recommended.
149	+
150	+	\| Type \| Icon \| Aria Label \|
151	+	\|------\|------\|-----------\|
152	+	\| `heart` \| Heart \| Recommend / Unrecommend \|
153	+	\| `star` \| Star \| Recommend / Unrecommend \|
154	+	\| `thumbs-up` \| Thumbs up \| Recommend / Unrecommend \|
155	+
156	+	```html
157	+	<!-- Default heart icon -->
158	+	<sequoia-recommend></sequoia-recommend>
159	+
160	+	<!-- Star icon -->
161	+	<sequoia-recommend button-type="star"></sequoia-recommend>
162	+
163	+	<!-- Thumbs-up icon -->
164	+	<sequoia-recommend button-type="thumbs-up"></sequoia-recommend>
165	+
166	+	<!-- Explicit document URI -->
167	+	<sequoia-recommend
168	+	document-uri="at://did:plc:example/app.bsky.feed.post/rkey">
169	+	</sequoia-recommend>
170	+	```
171	+
172	+	#### Resolving the Document URI
173	+
174	+	If `document-uri` is not set on the element, the component looks for a `<link>` tag in the page `<head>`:
175	+
176	+	```html
177	+	<link rel="site.standard.document" href="at://did:plc:example/app.bsky.feed.post/rkey" />
178	+	```
179	+
180	+	This lets you set the document URI once per page without having to pass it to every component instance.
181	+
182	+	### Events
183	+
184	+	The component dispatches custom events you can listen to:
185	+
186	+	\| Event \| Description \| Detail \|
187	+	\|-------\|-------------\|--------\|
188	+	\| `sequoia-recommended` \| Fired when the recommendation is created successfully. \| `{ documentUri: string, recordUri: string }` \|
189	+	\| `sequoia-recommend-error` \| Fired when the recommendation fails. \| `{ message: string }` \|
190	+
191	+	```js
192	+	const btn = document.querySelector('sequoia-recommend');
193	+
194	+	btn.addEventListener('sequoia-recommended', (e) => {
195	+	console.log('Recommended!', e.detail.recordUri);
196	+	});
197	+
198	+	btn.addEventListener('sequoia-recommend-error', (e) => {
199	+	console.error('Recommendation failed:', e.detail.message);
200	+	});
201	+	```
202	+
203	+	### Styling
204	+
205	+	The component uses the same CSS custom properties as `<sequoia-subscribe>` for theming, plus a `part="button"` attribute for direct CSS targeting:
206	+
207	+	\| CSS Property \| Default \| Description \|
208	+	\|--------------\|---------\|-------------\|
209	+	\| `--sequoia-fg-color` \| `#1f2937` \| Text color \|
210	+	\| `--sequoia-bg-color` \| `#ffffff` \| Background color \|
211	+	\| `--sequoia-border-color` \| `#e5e7eb` \| Border color \|
212	+	\| `--sequoia-accent-color` \| `#2563eb` \| Button background color \|
213	+	\| `--sequoia-secondary-color` \| `#6b7280` \| Secondary text color \|
214	+	\| `--sequoia-border-radius` \| `8px` \| Border radius for the button \|
215	+	\| `--sequoia-icon-display` \| `inline-block` \| Set to `none` to hide the button icon \|
216	+
217	+	### Example: Match Site Theme
218	+
219	+	```css
220	+	:root {
221	+	--sequoia-accent-color: #3A5A40;
222	+	--sequoia-border-radius: 6px;
223	+	--sequoia-bg-color: #F5F3EF;
224	+	--sequoia-fg-color: #2C2C2C;
225	+	--sequoia-border-color: #D5D1C8;
226	+	--sequoia-secondary-color: #8B7355;
227	+	}
228	+	```
229	+
230	+	### Using Both Components Together
231	+
232	+	Because `sequoia-subscribe.js` only needs to be imported once, you can use both components on the same page with a single script tag:
233	+
234	+	```html
235	+	<sequoia-subscribe></sequoia-subscribe>
236	+	<sequoia-recommend></sequoia-recommend>
237	+	<script type="module" src="./src/components/sequoia-subscribe.js"></script>
238	+	```

docs/docs/pages/subscribe.mdx +4 −0


The component will look for your publication AT URI from your site's `/.well-known/site.standard.publication` endpoint automatically, so no additional configuration is required for most setups.

:::tip
`sequoia-subscribe.js` registers both the `<sequoia-subscribe>` and `<sequoia-recommend>` custom elements. You only need to import it once even if you use both components on the same page.
:::

## Usage

Since `sequoia-subscribe` is a standard Web Component, it works with any framework. Choose your setup below:

docs/src/index.ts +17 −0

import { cors } from "hono/cors";
import auth from "./routes/auth";
import subscribe from "./routes/subscribe";
import recommend from "./routes/recommend";
import "./lib/path-redirect";

type Bindings = {


app.route("/oauth", auth);
app.route("/subscribe", subscribe);

app.use(
	"/recommend",
	cors({
		origin: (origin) => origin,
		credentials: true,
	}),
);
app.use(
	"/recommend/*",
	cors({
		origin: (origin) => origin,
		credentials: true,
	}),
);
app.route("/recommend", recommend);

app.get("/api/health", (c) => {
	return c.json({ status: "ok" });

docs/src/lib/oauth-client.ts +2 −2

import { createStateStore, createSessionStore } from "./kv-stores";

export const OAUTH_SCOPE =
	"atproto repo:site.standard.graph.subscription?action=create&action=delete";
	"atproto repo:site.standard.graph.recommend?action=create&action=delete repo:site.standard.graph.subscription?action=create&action=delete";

export function createOAuthClient(kv: KVNamespace, clientUrl: string) {
	const clientId = `${clientUrl}/oauth/client-metadata.json`;

			redirect_uris: [redirectUri],
			grant_types: ["authorization_code", "refresh_token"],
			response_types: ["code"],
			scope: "atproto repo:site.standard.graph.subscription?action=create",
			scope: OAUTH_SCOPE,
			token_endpoint_auth_method: "none",
			application_type: "web",
			dpop_bound_access_tokens: true,

docs/src/routes/lib.ts (added) +247 −0

1	+	import type { Agent } from "@atproto/api";
2	+
3	+	export const REDIRECT_DELAY_SECONDS = 5;
4	+
5	+	// ============================================================================
6	+	// Helpers
7	+	// ============================================================================
8	+
9	+	export function withReturnToParam(
10	+	returnTo: string \| undefined,
11	+	key: string,
12	+	value: string,
13	+	): string \| undefined {
14	+	if (!returnTo) return undefined;
15	+	try {
16	+	const url = new URL(returnTo);
17	+	url.searchParams.set(key, value);
18	+	return url.toString();
19	+	} catch {
20	+	return returnTo;
21	+	}
22	+	}
23	+
24	+	/**
25	+	* Scan a repo for a record in `collection` where `record[field] === uri`.
26	+	* Returns the record AT-URI, or null if not found.
27	+	*/
28	+	export async function findExistingRecord(
29	+	agent: Agent,
30	+	did: string,
31	+	collection: string,
32	+	field: string,
33	+	uri: string,
34	+	): Promise<string \| null> {
35	+	let cursor: string \| undefined;
36	+
37	+	do {
38	+	const result = await agent.com.atproto.repo.listRecords({
39	+	repo: did,
40	+	collection,
41	+	limit: 100,
42	+	cursor,
43	+	});
44	+
45	+	for (const record of result.data.records) {
46	+	const value = record.value as Record<string, unknown>;
47	+	if (value[field] === uri) {
48	+	return record.uri;
49	+	}
50	+	}
51	+
52	+	cursor = result.data.cursor;
53	+	} while (cursor);
54	+
55	+	return null;
56	+	}
57	+
58	+	// ============================================================================
59	+	// HTML rendering
60	+	// ============================================================================
61	+
62	+	export function renderHandleForm(
63	+	params: {
64	+	resourceUri: string;
65	+	resourceField: string;
66	+	loginPath: string;
67	+	title: string;
68	+	description: string;
69	+	buttonLabel: string;
70	+	returnTo?: string;
71	+	error?: string;
72	+	action?: string;
73	+	},
74	+	styleHref: string,
75	+	): string {
76	+	const {
77	+	resourceUri,
78	+	resourceField,
79	+	loginPath,
80	+	title,
81	+	description,
82	+	buttonLabel,
83	+	returnTo,
84	+	error,
85	+	action,
86	+	} = params;
87	+
88	+	const errorHtml = error
89	+	? `<p class="vocs_Paragraph error">${escapeHtml(error)}</p>`
90	+	: "";
91	+	const returnToInput = returnTo
92	+	? `<input type="hidden" name="returnTo" value="${escapeHtml(returnTo)}" />`
93	+	: "";
94	+	const actionInput = action
95	+	? `<input type="hidden" name="action" value="${escapeHtml(action)}" />`
96	+	: "";
97	+
98	+	return page(
99	+	`
100	+	<h1 class="vocs_H1 vocs_Heading">${escapeHtml(title)}</h1>
101	+	<p class="vocs_Paragraph">${escapeHtml(description)}</p>
102	+	${errorHtml}
103	+	<form method="POST" action="${escapeHtml(loginPath)}">
104	+	<input type="hidden" name="${escapeHtml(resourceField)}" value="${escapeHtml(resourceUri)}" />
105	+	${returnToInput}
106	+	${actionInput}
107	+	<input
108	+	type="text"
109	+	name="handle"
110	+	placeholder="you.bsky.social"
111	+	autocomplete="username"
112	+	required
113	+	autofocus
114	+	/>
115	+	<button type="submit" class="vocs_Button_button vocs_Button_button_accent">${escapeHtml(buttonLabel)}</button>
116	+	</form>
117	+	`,
118	+	styleHref,
119	+	);
120	+	}
121	+
122	+	export function renderSuccess(
123	+	params: {
124	+	resourceUri: string;
125	+	resourceLabel: string;
126	+	recordUri: string \| null;
127	+	heading: string;
128	+	msg: string;
129	+	returnTo?: string;
130	+	},
131	+	styleHref: string,
132	+	): string {
133	+	const { resourceUri, resourceLabel, recordUri, heading, msg, returnTo } =
134	+	params;
135	+	const escapedResourceUri = escapeHtml(resourceUri);
136	+	const escapedReturnTo = returnTo ? escapeHtml(returnTo) : "";
137	+
138	+	const redirectHtml = returnTo
139	+	? `<p class="vocs_Paragraph" id="redirect-msg">Redirecting to <a class="vocs_Anchor" href="${escapedReturnTo}">${escapedReturnTo}</a> in <span id="countdown">${REDIRECT_DELAY_SECONDS}</span>\u00a0seconds\u2026</p>
140	+	<script>
141	+	(function(){
142	+	var secs = ${REDIRECT_DELAY_SECONDS};
143	+	var el = document.getElementById('countdown');
144	+	var iv = setInterval(function(){
145	+	secs--;
146	+	if (el) el.textContent = String(secs);
147	+	if (secs <= 0) { clearInterval(iv); location.href = ${JSON.stringify(returnTo)}; }
148	+	}, 1000);
149	+	})();
150	+	</script>`
151	+	: "";
152	+	const headExtra = returnTo
153	+	? `<meta http-equiv="refresh" content="${REDIRECT_DELAY_SECONDS};url=${escapedReturnTo}" />`
154	+	: "";
155	+
156	+	return page(
157	+	`
158	+	<h1 class="vocs_H1 vocs_Heading">${escapeHtml(heading)}</h1>
159	+	<p class="vocs_Paragraph">${msg}</p>
160	+	${redirectHtml}
161	+	<table class="vocs_Table" style="display:table;table-layout:fixed;width:100%;overflow:hidden;">
162	+	<colgroup><col style="width:7rem;"><col></colgroup>
163	+	<tbody>
164	+	<tr class="vocs_TableRow">
165	+	<td class="vocs_TableCell">${escapeHtml(resourceLabel)}</td>
166	+	<td class="vocs_TableCell" style="overflow:hidden;">
167	+	<div style="overflow-x:auto;white-space:nowrap;"><code class="vocs_Code"><a href="https://pds.ls/${escapedResourceUri}">${escapedResourceUri}</a></code></div>
168	+	</td>
169	+	</tr>
170	+	${
171	+	recordUri
172	+	? `<tr class="vocs_TableRow">
173	+	<td class="vocs_TableCell">Record</td>
174	+	<td class="vocs_TableCell" style="overflow:hidden;">
175	+	<div style="overflow-x:auto;white-space:nowrap;"><code class="vocs_Code"><a href="https://pds.ls/${escapeHtml(recordUri)}">${escapeHtml(recordUri)}</a></code></div>
176	+	</td>
177	+	</tr>`
178	+	: ""
179	+	}
180	+	</tbody>
181	+	</table>
182	+	`,
183	+	styleHref,
184	+	headExtra,
185	+	);
186	+	}
187	+
188	+	export function renderError(message: string, styleHref: string): string {
189	+	return page(
190	+	`<h1 class="vocs_H1 vocs_Heading">Error</h1><p class="vocs_Paragraph error">${escapeHtml(message)}</p>`,
191	+	styleHref,
192	+	);
193	+	}
194	+
195	+	export function page(body: string, styleHref: string, headExtra = ""): string {
196	+	return `<!DOCTYPE html>
197	+	<html lang="en">
198	+	<head>
199	+	<meta charset="UTF-8" />
200	+	<meta name="viewport" content="width=device-width, initial-scale=1.0" />
201	+	<title>Sequoia</title>
202	+	<link rel="stylesheet" href="${styleHref}" />
203	+	<script>if(window.matchMedia('(prefers-color-scheme: dark)').matches)document.documentElement.classList.add('dark')</script>
204	+	${headExtra}
205	+	<style>
206	+	.page-container {
207	+	max-width: calc(var(--vocs-content_width, 480px) / 1.6);
208	+	margin: 4rem auto;
209	+	padding: 0 var(--vocs-space_20, 1.25rem);
210	+	}
211	+	.vocs_Heading { margin-bottom: var(--vocs-space_12, .75rem); }
212	+	.vocs_Paragraph { margin-bottom: var(--vocs-space_16, 1rem); }
213	+	input[type="text"] {
214	+	padding: var(--vocs-space_8, .5rem) var(--vocs-space_12, .75rem);
215	+	border: 1px solid var(--vocs-color_border, #D5D1C8);
216	+	border-radius: var(--vocs-borderRadius_6, 6px);
217	+	margin-bottom: var(--vocs-space_20, 1.25rem);
218	+	min-width: 30vh;
219	+	width: 100%;
220	+	font-size: var(--vocs-fontSize_16, 1rem);
221	+	font-family: inherit;
222	+	background: var(--vocs-color_background, #F5F3EF);
223	+	color: var(--vocs-color_text, #2C2C2C);
224	+	}
225	+	input[type="text"]:focus {
226	+	border-color: var(--vocs-color_borderAccent, #3A5A40);
227	+	outline: 2px solid var(--vocs-color_borderAccent, #3A5A40);
228	+	outline-offset: 2px;
229	+	}
230	+	.error { color: var(--vocs-color_dangerText, #8B3A3A); }
231	+	</style>
232	+	</head>
233	+	<body>
234	+	<div class="page-container">
235	+	${body}
236	+	</div>
237	+	</body>
238	+	</html>`;
239	+	}
240	+
241	+	export function escapeHtml(text: string): string {
242	+	return text
243	+	.replace(/&/g, "&")
244	+	.replace(/</g, "<")
245	+	.replace(/>/g, ">")
246	+	.replace(/"/g, """);
247	+	}

docs/src/routes/recommend.ts (added) +348 −0

1	+	import { Agent } from "@atproto/api";
2	+	import { Hono } from "hono";
3	+	import { createOAuthClient } from "../lib/oauth-client";
4	+	import { getSessionDid, setReturnToCookie } from "../lib/session";
5	+	import {
6	+	findExistingRecord,
7	+	renderError,
8	+	renderHandleForm,
9	+	renderSuccess,
10	+	withReturnToParam,
11	+	} from "./lib";
12	+
13	+	interface Env {
14	+	ASSETS: Fetcher;
15	+	SEQUOIA_SESSIONS: KVNamespace;
16	+	CLIENT_URL: string;
17	+	}
18	+
19	+	// Cache the vocs-generated stylesheet href across requests (changes on rebuild).
20	+	let _vocsStyleHref: string \| null = null;
21	+
22	+	async function getVocsStyleHref(
23	+	assets: Fetcher,
24	+	baseUrl: string,
25	+	): Promise<string> {
26	+	if (_vocsStyleHref) return _vocsStyleHref;
27	+	try {
28	+	const indexUrl = new URL("/", baseUrl).toString();
29	+	const res = await assets.fetch(indexUrl);
30	+	const html = await res.text();
31	+	const match = html.match(/<link[^>]+href="(\/assets\/style[^"]+\.css)"/);
32	+	if (match?.[1]) {
33	+	_vocsStyleHref = match[1];
34	+	return match[1];
35	+	}
36	+	} catch {
37	+	// Fall back to the custom stylesheet which at least provides --sequoia-* vars
38	+	}
39	+	return "/styles.css";
40	+	}
41	+
42	+	const recommend = new Hono<{ Bindings: Env }>();
43	+
44	+	const COLLECTION = "site.standard.graph.recommend";
45	+
46	+	// ============================================================================
47	+	// POST /recommend
48	+	// ============================================================================
49	+
50	+	recommend.post("/", async (c) => {
51	+	let documentUri: string;
52	+	try {
53	+	const body = await c.req.json<{ documentUri?: string }>();
54	+	documentUri = body.documentUri ?? "";
55	+	} catch {
56	+	return c.json({ error: "Invalid JSON body" }, 400);
57	+	}
58	+
59	+	if (!documentUri \|\| !documentUri.startsWith("at://")) {
60	+	return c.json({ error: "Missing or invalid documentUri" }, 400);
61	+	}
62	+
63	+	const did = getSessionDid(c);
64	+	if (!did) {
65	+	const subscribeUrl = `${c.env.CLIENT_URL}/recommend?documentUri=${encodeURIComponent(documentUri)}`;
66	+	return c.json({ authenticated: false, subscribeUrl }, 401);
67	+	}
68	+
69	+	try {
70	+	const client = createOAuthClient(c.env.SEQUOIA_SESSIONS, c.env.CLIENT_URL);
71	+	const session = await client.restore(did);
72	+	const agent = new Agent(session);
73	+
74	+	const existingUri = await findExistingRecord(
75	+	agent,
76	+	did,
77	+	COLLECTION,
78	+	"document",
79	+	documentUri,
80	+	);
81	+	if (existingUri) {
82	+	return c.json({
83	+	recommended: true,
84	+	existing: true,
85	+	recordUri: existingUri,
86	+	});
87	+	}
88	+
89	+	const result = await agent.com.atproto.repo.createRecord({
90	+	repo: did,
91	+	collection: COLLECTION,
92	+	record: {
93	+	$type: COLLECTION,
94	+	document: documentUri,
95	+	createdAt: new Date().toISOString(),
96	+	},
97	+	});
98	+
99	+	return c.json({
100	+	recommended: true,
101	+	existing: false,
102	+	recordUri: result.data.uri,
103	+	});
104	+	} catch (error) {
105	+	console.error("Recommend POST error:", error);
106	+	const subscribeUrl = `${c.env.CLIENT_URL}/recommend?documentUri=${encodeURIComponent(documentUri)}`;
107	+	return c.json({ authenticated: false, subscribeUrl }, 401);
108	+	}
109	+	});
110	+
111	+	// ============================================================================
112	+	// GET /recommend?documentUri=at://...
113	+	//
114	+	// Full-page OAuth + recommendation flow. Unauthenticated users land here after
115	+	// the component redirects them, and authenticated users land here after the
116	+	// OAuth callback (via the login_return_to cookie set in POST /recommend/login).
117	+	// ============================================================================
118	+
119	+	recommend.get("/", async (c) => {
120	+	const documentUri = c.req.query("documentUri");
121	+	const action = c.req.query("action");
122	+	const styleHref = await getVocsStyleHref(c.env.ASSETS, c.req.url);
123	+
124	+	if (action && action !== "remove") {
125	+	return c.html(renderError(`Unsupported action: ${action}`, styleHref), 400);
126	+	}
127	+
128	+	if (!documentUri \|\| !documentUri.startsWith("at://")) {
129	+	return c.html(
130	+	renderError("Missing or invalid document URI.", styleHref),
131	+	400,
132	+	);
133	+	}
134	+
135	+	// Prefer an explicit returnTo query param (survives the OAuth round-trip);
136	+	// fall back to the Referer header on the first visit, ignoring self-referrals.
137	+	const referer = c.req.header("referer");
138	+	const returnTo =
139	+	c.req.query("returnTo") ??
140	+	(referer && !referer.includes("/recommend") ? referer : undefined);
141	+
142	+	const did = getSessionDid(c);
143	+	if (!did) {
144	+	return c.html(
145	+	renderHandleForm(
146	+	{
147	+	resourceUri: documentUri,
148	+	resourceField: "documentUri",
149	+	loginPath: "/recommend/login",
150	+	title: "Recommend on Sequoia",
151	+	description: "Enter your Bluesky handle to recommend this document.",
152	+	buttonLabel: "Continue on Bluesky",
153	+	returnTo,
154	+	action,
155	+	},
156	+	styleHref,
157	+	),
158	+	);
159	+	}
160	+
161	+	try {
162	+	const client = createOAuthClient(c.env.SEQUOIA_SESSIONS, c.env.CLIENT_URL);
163	+	const session = await client.restore(did);
164	+	const agent = new Agent(session);
165	+
166	+	if (action === "remove") {
167	+	const existingUri = await findExistingRecord(
168	+	agent,
169	+	did,
170	+	COLLECTION,
171	+	"document",
172	+	documentUri,
173	+	);
174	+	if (existingUri) {
175	+	const rkey = existingUri.split("/").pop()!;
176	+	await agent.com.atproto.repo.deleteRecord({
177	+	repo: did,
178	+	collection: COLLECTION,
179	+	rkey,
180	+	});
181	+	}
182	+
183	+	return c.html(
184	+	renderSuccess(
185	+	{
186	+	resourceUri: documentUri,
187	+	resourceLabel: "Document",
188	+	recordUri: null,
189	+	heading: "Recommendation Removed \u2713",
190	+	msg: existingUri
191	+	? "You've successfully removed your recommendation."
192	+	: "You hadn't recommended this document.",
193	+	returnTo: withReturnToParam(returnTo, "sequoia_did", did),
194	+	},
195	+	styleHref,
196	+	),
197	+	);
198	+	}
199	+
200	+	const existingUri = await findExistingRecord(
201	+	agent,
202	+	did,
203	+	COLLECTION,
204	+	"document",
205	+	documentUri,
206	+	);
207	+	const returnToWithDid = withReturnToParam(returnTo, "sequoia_did", did);
208	+
209	+	if (existingUri) {
210	+	return c.html(
211	+	renderSuccess(
212	+	{
213	+	resourceUri: documentUri,
214	+	resourceLabel: "Document",
215	+	recordUri: existingUri,
216	+	heading: "Recommended \u2713",
217	+	msg: "You've already recommended this document.",
218	+	returnTo: returnToWithDid,
219	+	},
220	+	styleHref,
221	+	),
222	+	);
223	+	}
224	+
225	+	const result = await agent.com.atproto.repo.createRecord({
226	+	repo: did,
227	+	collection: COLLECTION,
228	+	record: {
229	+	$type: COLLECTION,
230	+	document: documentUri,
231	+	createdAt: new Date().toISOString(),
232	+	},
233	+	});
234	+
235	+	return c.html(
236	+	renderSuccess(
237	+	{
238	+	resourceUri: documentUri,
239	+	resourceLabel: "Document",
240	+	recordUri: result.data.uri,
241	+	heading: "Recommended \u2713",
242	+	msg: "You've successfully recommended this document!",
243	+	returnTo: returnToWithDid,
244	+	},
245	+	styleHref,
246	+	),
247	+	);
248	+	} catch (error) {
249	+	console.error("Recommend GET error:", error);
250	+	// Session expired - ask the user to sign in again
251	+	return c.html(
252	+	renderHandleForm(
253	+	{
254	+	resourceUri: documentUri,
255	+	resourceField: "documentUri",
256	+	loginPath: "/recommend/login",
257	+	title: "Recommend on Sequoia",
258	+	description: "Enter your Bluesky handle to recommend this document.",
259	+	buttonLabel: "Continue on Bluesky",
260	+	returnTo,
261	+	error: "Session expired. Please sign in again.",
262	+	action,
263	+	},
264	+	styleHref,
265	+	),
266	+	);
267	+	}
268	+	});
269	+
270	+	// ============================================================================
271	+	// GET /recommend/check?documentUri=at://...
272	+	//
273	+	// JSON-only endpoint for the web component to check recommendation status.
274	+	//
275	+	// Responses:
276	+	// 200 { recommended: true, recordUri: string }
277	+	// 200 { recommended: false }
278	+	// 400 { error: string }
279	+	// 401 { authenticated: false }
280	+	// ============================================================================
281	+
282	+	recommend.get("/check", async (c) => {
283	+	const documentUri = c.req.query("documentUri");
284	+
285	+	if (!documentUri \|\| !documentUri.startsWith("at://")) {
286	+	return c.json({ error: "Missing or invalid documentUri" }, 400);
287	+	}
288	+
289	+	// Prefer the server-side session DID; fall back to a client-provided DID
290	+	// (stored by the web component from a previous recommend flow).
291	+	const did = getSessionDid(c) ?? c.req.query("did") ?? null;
292	+	if (!did \|\| !did.startsWith("did:")) {
293	+	return c.json({ authenticated: false }, 401);
294	+	}
295	+
296	+	try {
297	+	const client = createOAuthClient(c.env.SEQUOIA_SESSIONS, c.env.CLIENT_URL);
298	+	const session = await client.restore(did);
299	+	const agent = new Agent(session);
300	+	const recordUri = await findExistingRecord(
301	+	agent,
302	+	did,
303	+	COLLECTION,
304	+	"document",
305	+	documentUri,
306	+	);
307	+	return recordUri
308	+	? c.json({ recommended: true, recordUri })
309	+	: c.json({ recommended: false });
310	+	} catch {
311	+	return c.json({ authenticated: false }, 401);
312	+	}
313	+	});
314	+
315	+	// ============================================================================
316	+	// POST /recommend/login
317	+	//
318	+	// Handles the handle-entry form submission. Stores the return URL in a cookie
319	+	// so the OAuth callback in auth.ts can redirect back to /recommend after auth.
320	+	// ============================================================================
321	+
322	+	recommend.post("/login", async (c) => {
323	+	const body = await c.req.parseBody();
324	+	const handle = (body.handle as string \| undefined)?.trim();
325	+	const documentUri = body.documentUri as string \| undefined;
326	+	const formReturnTo = (body.returnTo as string \| undefined) \|\| undefined;
327	+	const formAction = (body.action as string \| undefined) \|\| undefined;
328	+
329	+	if (!handle \|\| !documentUri) {
330	+	const styleHref = await getVocsStyleHref(c.env.ASSETS, c.req.url);
331	+	return c.html(
332	+	renderError("Missing handle or document URI.", styleHref),
333	+	400,
334	+	);
335	+	}
336	+
337	+	const returnTo =
338	+	`${c.env.CLIENT_URL}/recommend?documentUri=${encodeURIComponent(documentUri)}` +
339	+	(formAction ? `&action=${encodeURIComponent(formAction)}` : "") +
340	+	(formReturnTo ? `&returnTo=${encodeURIComponent(formReturnTo)}` : "");
341	+	setReturnToCookie(c, returnTo, c.env.CLIENT_URL);
342	+
343	+	return c.redirect(
344	+	`${c.env.CLIENT_URL}/oauth/login?handle=${encodeURIComponent(handle)}`,
345	+	);
346	+	});
347	+
348	+	export default recommend;

docs/src/routes/subscribe.ts +75 −244

import { Hono } from "hono";
import { createOAuthClient } from "../lib/oauth-client";
import { getSessionDid, setReturnToCookie } from "../lib/session";
import {
	findExistingRecord,
	renderError,
	renderHandleForm,
	renderSuccess,
	withReturnToParam,
} from "./lib";

interface Env {
	ASSETS: Fetcher;

const subscribe = new Hono<{ Bindings: Env }>();

const COLLECTION = "site.standard.graph.subscription";
const REDIRECT_DELAY_SECONDS = 5;

// ============================================================================
// Helpers
// ============================================================================

/**
 * Append a query parameter to a returnTo URL, preserving existing params.
 */
function withReturnToParam(
	returnTo: string | undefined,
	key: string,
	value: string,
): string | undefined {
	if (!returnTo) return undefined;
	try {
		const url = new URL(returnTo);
		url.searchParams.set(key, value);
		return url.toString();
	} catch {
		return returnTo;
	}
}

/**
 * Scan the user's repo for an existing site.standard.graph.subscription
 * matching the given publication URI. Returns the record AT-URI if found.
 */
async function findExistingSubscription(
	agent: Agent,
	did: string,
	publicationUri: string,
): Promise<string | null> {
	let cursor: string | undefined;

	do {
		const result = await agent.com.atproto.repo.listRecords({
			repo: did,
			collection: COLLECTION,
			limit: 100,
			cursor,
		});

		for (const record of result.data.records) {
			const value = record.value as { publication?: string };
			if (value.publication === publicationUri) {
				return record.uri;
			}
		}

		cursor = result.data.cursor;
	} while (cursor);

	return null;
}

// ============================================================================
// POST /subscribe
//

		const session = await client.restore(did);
		const agent = new Agent(session);

		const existingUri = await findExistingSubscription(
		const existingUri = await findExistingRecord(
			agent,
			did,
			COLLECTION,
			"publication",
			publicationUri,
		);
		if (existingUri) {

	const did = getSessionDid(c);
	if (!did) {
		return c.html(
			renderHandleForm(publicationUri, styleHref, returnTo, undefined, action),
			renderHandleForm(
				{
					resourceUri: publicationUri,
					resourceField: "publicationUri",
					loginPath: "/subscribe/login",
					title: "Subscribe on Sequoia",
					description:
						"Enter your Bluesky handle to subscribe to this publication.",
					buttonLabel: "Continue on Bluesky",
					returnTo,
					action,
				},
				styleHref,
			),
		);
	}


		const agent = new Agent(session);

		if (action === "unsubscribe") {
			const existingUri = await findExistingSubscription(
			const existingUri = await findExistingRecord(
				agent,
				did,
				COLLECTION,
				"publication",
				publicationUri,
			);
			if (existingUri) {


			return c.html(
				renderSuccess(
					publicationUri,
					null,
					"Unsubscribed ✓",
					existingUri
						? "You've successfully unsubscribed!"
						: "You weren't subscribed to this publication.",
					{
						resourceUri: publicationUri,
						resourceLabel: "Publication",
						recordUri: null,
						heading: "Unsubscribed ✓",
						msg: existingUri
							? "You've successfully unsubscribed!"
							: "You weren't subscribed to this publication.",
						returnTo: withReturnToParam(
							cleanReturnTo,
							"sequoia_unsubscribed",
							"1",
						),
					},
					styleHref,
					withReturnToParam(cleanReturnTo, "sequoia_unsubscribed", "1"),
				),
			);
		}

		const existingUri = await findExistingSubscription(
		const existingUri = await findExistingRecord(
			agent,
			did,
			COLLECTION,
			"publication",
			publicationUri,
		);
		const returnToWithDid = withReturnToParam(returnTo, "sequoia_did", did);

		if (existingUri) {
			return c.html(
				renderSuccess(
					publicationUri,
					existingUri,
					"Subscribed ✓",
					"You're already subscribed to this publication.",
					{
						resourceUri: publicationUri,
						resourceLabel: "Publication",
						recordUri: existingUri,
						heading: "Subscribed ✓",
						msg: "You're already subscribed to this publication.",
						returnTo: returnToWithDid,
					},
					styleHref,
					returnToWithDid,
				),
			);
		}


		return c.html(
			renderSuccess(
				publicationUri,
				result.data.uri,
				"Subscribed ✓",
				"You've successfully subscribed!",
				{
					resourceUri: publicationUri,
					resourceLabel: "Publication",
					recordUri: result.data.uri,
					heading: "Subscribed ✓",
					msg: "You've successfully subscribed!",
					returnTo: returnToWithDid,
				},
				styleHref,
				returnToWithDid,
			),
		);
	} catch (error) {

		// Session expired - ask the user to sign in again
		return c.html(
			renderHandleForm(
				publicationUri,
				{
					resourceUri: publicationUri,
					resourceField: "publicationUri",
					loginPath: "/subscribe/login",
					title: "Subscribe on Sequoia",
					description:
						"Enter your Bluesky handle to subscribe to this publication.",
					buttonLabel: "Continue on Bluesky",
					returnTo,
					error: "Session expired. Please sign in again.",
					action,
				},
				styleHref,
				returnTo,
				"Session expired. Please sign in again.",
				action,
			),
		);
	}

		const client = createOAuthClient(c.env.SEQUOIA_SESSIONS, c.env.CLIENT_URL);
		const session = await client.restore(did);
		const agent = new Agent(session);
		const recordUri = await findExistingSubscription(
		const recordUri = await findExistingRecord(
			agent,
			did,
			COLLECTION,
			"publication",
			publicationUri,
		);
		return recordUri

		`${c.env.CLIENT_URL}/oauth/login?handle=${encodeURIComponent(handle)}`,
	);
});

// ============================================================================
// HTML rendering
// ============================================================================

function renderHandleForm(
	publicationUri: string,
	styleHref: string,
	returnTo?: string,
	error?: string,
	action?: string,
): string {
	const errorHtml = error
		? `<p class="vocs_Paragraph error">${escapeHtml(error)}</p>`
		: "";
	const returnToInput = returnTo
		? `<input type="hidden" name="returnTo" value="${escapeHtml(returnTo)}" />`
		: "";
	const actionInput = action
		? `<input type="hidden" name="action" value="${escapeHtml(action)}" />`
		: "";

	return page(
		`
		<h1 class="vocs_H1 vocs_Heading">Subscribe on Bluesky</h1>
		<p class="vocs_Paragraph">Enter your Bluesky handle to subscribe to this publication.</p>
		${errorHtml}
		<form method="POST" action="/subscribe/login">
			<input type="hidden" name="publicationUri" value="${escapeHtml(publicationUri)}" />
			${returnToInput}
			${actionInput}
			<input
				type="text"
				name="handle"
				placeholder="you.bsky.social"
				autocomplete="username"
				required
				autofocus
			/>
			<button type="submit" class="vocs_Button_button vocs_Button_button_accent">Continue on Bluesky</button>
		</form>
	`,
		styleHref,
	);
}

function renderSuccess(
	publicationUri: string,
	recordUri: string | null,
	heading: string,
	msg: string,
	styleHref: string,
	returnTo?: string,
): string {
	const escapedPublicationUri = escapeHtml(publicationUri);
	const escapedReturnTo = returnTo ? escapeHtml(returnTo) : "";

	const redirectHtml = returnTo
		? `<p class="vocs_Paragraph" id="redirect-msg">Redirecting to <a class="vocs_Anchor" href="${escapedReturnTo}">${escapedReturnTo}</a> in <span id="countdown">${REDIRECT_DELAY_SECONDS}</span>\u00a0seconds\u2026</p>
		<script>
		(function(){
			var secs = ${REDIRECT_DELAY_SECONDS};
			var el = document.getElementById('countdown');
			var iv = setInterval(function(){
				secs--;
				if (el) el.textContent = String(secs);
				if (secs <= 0) { clearInterval(iv); location.href = ${JSON.stringify(returnTo)}; }
			}, 1000);
		})();
		</script>`
		: "";
	const headExtra = returnTo
		? `<meta http-equiv="refresh" content="${REDIRECT_DELAY_SECONDS};url=${escapedReturnTo}" />`
		: "";

	return page(
		`
		<h1 class="vocs_H1 vocs_Heading">${escapeHtml(heading)}</h1>
		<p class="vocs_Paragraph">${msg}</p>
		${redirectHtml}
		<table class="vocs_Table" style="display:table;table-layout:fixed;width:100%;overflow:hidden;">
			<colgroup><col style="width:7rem;"><col></colgroup>
			<tbody>
				<tr class="vocs_TableRow">
					<td class="vocs_TableCell">Publication</td>
					<td class="vocs_TableCell" style="overflow:hidden;">
						<div style="overflow-x:auto;white-space:nowrap;"><code class="vocs_Code"><a href="https://pds.ls/${escapedPublicationUri}">${escapedPublicationUri}</a></code></div>
					</td>
				</tr>
				${
					recordUri
						? `<tr class="vocs_TableRow">
					<td class="vocs_TableCell">Record</td>
					<td class="vocs_TableCell" style="overflow:hidden;">
						<div style="overflow-x:auto;white-space:nowrap;"><code class="vocs_Code"><a href="https://pds.ls/${escapeHtml(recordUri)}">${escapeHtml(recordUri)}</a></code></div>
					</td>
				</tr>`
						: ""
				}
			</tbody>
		</table>
	`,
		styleHref,
		headExtra,
	);
}

function renderError(message: string, styleHref: string): string {
	return page(
		`<h1 class="vocs_H1 vocs_Heading">Error</h1><p class="vocs_Paragraph error">${escapeHtml(message)}</p>`,
		styleHref,
	);
}

function page(body: string, styleHref: string, headExtra = ""): string {
	return `<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Sequoia · Subscribe</title>
  <link rel="stylesheet" href="${styleHref}" />
  <script>if(window.matchMedia('(prefers-color-scheme: dark)').matches)document.documentElement.classList.add('dark')</script>
  ${headExtra}
  <style>
    .page-container {
      max-width: calc(var(--vocs-content_width, 480px) / 1.6);
      margin: 4rem auto;
      padding: 0 var(--vocs-space_20, 1.25rem);
    }
    .vocs_Heading { margin-bottom: var(--vocs-space_12, .75rem); }
    .vocs_Paragraph { margin-bottom: var(--vocs-space_16, 1rem); }
    input[type="text"] {
      padding: var(--vocs-space_8, .5rem) var(--vocs-space_12, .75rem);
      border: 1px solid var(--vocs-color_border, #D5D1C8);
      border-radius: var(--vocs-borderRadius_6, 6px);
      margin-bottom: var(--vocs-space_20, 1.25rem);
	  min-width: 30vh;
	  width: 100%;
      font-size: var(--vocs-fontSize_16, 1rem);
      font-family: inherit;
      background: var(--vocs-color_background, #F5F3EF);
      color: var(--vocs-color_text, #2C2C2C);
    }
    input[type="text"]:focus {
      border-color: var(--vocs-color_borderAccent, #3A5A40);
      outline: 2px solid var(--vocs-color_borderAccent, #3A5A40);
      outline-offset: 2px;
    }
    .error { color: var(--vocs-color_dangerText, #8B3A3A); }
  </style>
</head>
<body>
  <div class="page-container">
    ${body}
  </div>
</body>
</html>`;
}

function escapeHtml(text: string): string {
	return text
		.replace(/&/g, "&amp;")
		.replace(/</g, "&lt;")
		.replace(/>/g, "&gt;")
		.replace(/"/g, "&quot;");
}

export default subscribe;

docs/vocs.config.ts +1 −0

				{ text: "Setup", link: "/setup" },
				{ text: "Publishing", link: "/publishing" },
				{ text: "Comments", link: "/comments" },
				{ text: "Recommend", link: "/recommend" },
				{ text: "Subscribe", link: "/subscribe" },
				{ text: "Verifying", link: "/verifying" },
				{ text: "Workflows", link: "/workflows" },

docs/wrangler.toml +1 −1

binding = "ASSETS"
not_found_handling = "single-page-application"
html_handling = "auto-trailing-slash"
run_worker_first = ["/api/*", "/oauth/*", "/subscribe", "/subscribe/*"]
run_worker_first = ["/api/*", "/oauth/*", "/recommend", "/recommend/*", "/subscribe", "/subscribe/*"]

[[kv_namespaces]]
binding = "SEQUOIA_SESSIONS"

packages/cli/src/components/sequoia-subscribe.js +398 −103

/**
 * Sequoia Subscribe - An AT Protocol-powered subscribe component
 *
 * A self-contained Web Component that lets users subscribe to a publication
 * via the AT Protocol by creating a site.standard.graph.subscription record.
 *
 * Usage:
 *   <sequoia-subscribe></sequoia-subscribe>
 * Sequoia Web Components — AT Protocol-powered engagement components
 *
 * The component resolves the publication AT URI from the host site's
 * /.well-known/site.standard.publication endpoint.
 * Self-contained Web Components for subscribing to publications and
 * recommending documents via the AT Protocol.
 *
 * Attributes:
 *   - publication-uri: Override the publication AT URI (optional)
 *   - callback-uri: Redirect URI after OAuth authentication (default: "https://sequoia.pub/subscribe")
 *   - button-type: Branding style — "sequoia" (default), "bluesky", "blacksky", "atmosphere", or "plain"
 *   - label: Override the subscribe button label text
 *   - unsubscribe-label: Override the unsubscribe button label text
 *   - hide: Set to "auto" to hide if no publication URI is detected
 * Both components share:
 *   - OAuth redirect flow via a hosted callback endpoint
 *   - DID caching in a cookie (primary) and localStorage (fallback)
 *   - A common visual style driven by CSS custom properties
 *
 * CSS Custom Properties:
 * CSS Custom Properties (apply to both components):
 *   - --sequoia-fg-color: Text color (default: #1f2937)
 *   - --sequoia-bg-color: Background color (default: #ffffff)
 *   - --sequoia-border-color: Border color (default: #e5e7eb)

 *   - --sequoia-secondary-color: Secondary text color (default: #6b7280)
 *   - --sequoia-border-radius: Border radius (default: 8px)
 *   - --sequoia-icon-display: Icon display mode (default: inline-block) — set to "none" to hide
 *
 * Events:
 *   - sequoia-subscribed: Fired when the subscription is created successfully.
 *     detail: { publicationUri: string, recordUri: string }
 *   - sequoia-subscribe-error: Fired when the subscription fails.
 *     detail: { message: string }
 */

// ============================================================================

	box-sizing: border-box;
}

.sequoia-subscribe-button {
.sequoia-button {
	display: inline-flex;
	align-items: center;
	gap: 0.375rem;

	font-family: inherit;
}

.sequoia-subscribe-button:hover:not(:disabled) {
.sequoia-button:hover:not(:disabled) {
	background: color-mix(in srgb, var(--sequoia-accent-color, #2563eb) 85%, black);
}

.sequoia-subscribe-button:disabled {
.sequoia-button:disabled {
	opacity: 0.6;
	cursor: not-allowed;
}

.sequoia-subscribe-button svg {
.sequoia-button svg {
	display: var(--sequoia-icon-display, inline-block);
	width: 1rem;
	height: 1rem;

};

// ============================================================================
// Recommend Icon Configuration
// ============================================================================

const HEART_PATH =
	"M20.84 4.61a5.5 5.5 0 0 0-7.78 0L12 5.67l-1.06-1.06a5.5 5.5 0 0 0-7.78 7.78l1.06 1.06L12 21.23l7.78-7.78 1.06-1.06a5.5 5.5 0 0 0 0-7.78z";
const HEART_ICON_OUTLINED = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="${HEART_PATH}"/></svg>`;
const HEART_ICON_FILLED = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor"><path d="${HEART_PATH}"/></svg>`;

const STAR_PATH =
	"M3.612 15.443c-.386.198-.824-.149-.746-.592l.83-4.73L.173 6.765c-.329-.314-.158-.888.283-.95l4.898-.696L7.538.792c.197-.39.73-.39.927 0l2.184 4.327 4.898.696c.441.062.612.636.282.95l-3.522 3.356.83 4.73c.078.443-.36.79-.746.592L8 13.187l-4.389 2.256z";
const STAR_ICON_OUTLINED = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round"><path d="${STAR_PATH}"/></svg>`;
const STAR_ICON_FILLED = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor"><path d="${STAR_PATH}"/></svg>`;

const THUMBS_UP_RECT_PATH = "M1 21h4V9H1v12z";
const THUMBS_UP_HAND_PATH =
	"M23 10c0-1.1-.9-2-2-2h-6.31l.95-4.57.03-.32c0-.41-.17-.79-.44-1.06L14.17 1 7.59 7.59C7.22 7.95 7 8.45 7 9v10c0 1.1.9 2 2 2h9c.83 0 1.54-.5 1.84-1.22l3.02-7.05c.09-.23.14-.47.14-.73v-2z";
const THUMBS_UP_ICON_OUTLINED = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="${THUMBS_UP_RECT_PATH}" fill="currentColor"/><path d="${THUMBS_UP_HAND_PATH}" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round"/></svg>`;
const THUMBS_UP_ICON_FILLED = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor"><path d="${THUMBS_UP_RECT_PATH}"/><path d="${THUMBS_UP_HAND_PATH}"/></svg>`;

const RECOMMEND_ICON_TYPES = {
	heart: {
		icon: HEART_ICON_OUTLINED,
		iconActioned: HEART_ICON_FILLED,
		action: "Recommend",
		unaction: "Unrecommend",
	},
	star: {
		icon: STAR_ICON_OUTLINED,
		iconActioned: STAR_ICON_FILLED,
		action: "Recommend",
		unaction: "Unrecommend",
	},
	"thumbs-up": {
		icon: THUMBS_UP_ICON_OUTLINED,
		iconActioned: THUMBS_UP_ICON_FILLED,
		action: "Recommend",
		unaction: "Unrecommend",
	},
};

// ============================================================================
// DID Storage
// ============================================================================


// SSR-safe base class - use HTMLElement in browser, empty class in Node.js
const BaseElement = typeof HTMLElement !== "undefined" ? HTMLElement : class {};

class SequoiaSubscribe extends BaseElement {
/**
 * Abstract base class shared by SequoiaSubscribe and SequoiaRecommend.
 * Handles shadow DOM setup, state management, the OAuth redirect flow,
 * DID storage, and button rendering. Subclasses implement template methods
 * to provide resource-specific behaviour.
 */
class SequoiaActionBase extends BaseElement {
	constructor() {
		super();
		const shadow = this.attachShadow({ mode: "open" });

		wrapper.part = "container";

		this.wrapper = wrapper;
		this.subscribed = false;
		this.actioned = false;
		this.state = { type: "idle" };
		this.abortController = null;
		this.render();
	}

	static get observedAttributes() {
		return [
			"publication-uri",
			"callback-uri",
			"label",
			"unsubscribe-label",
			"button-type",
			"hide",
		];
	}

	connectedCallback() {
		consumeReturnParams();
		this.checkPublication();
	}

	disconnectedCallback() {
		this.abortController?.abort();
	}

	attributeChangedCallback() {
		if (this.state.type === "error" || this.state.type === "no-publication") {
		if (this.state.type === "error" || this.state.type === "no-resource") {
			this.state = { type: "idle" };
		}
		this.render();
	}

	get publicationUri() {
		return this.getAttribute("publication-uri") ?? null;
	// ── Shared getters ───────────────────────────────────────────────────────

	get callbackUri() {
		return this.getAttribute("callback-uri") ?? this.defaultCallbackUri;
	}

	get hide() {
		return this.getAttribute("hide") === "auto";
	}

	// ── Template methods (override in subclasses) ────────────────────────────

	/** @returns {string} Default callback URI when the attribute is absent */
	get defaultCallbackUri() {
		return "";
	}

	/** @returns {string} Query-parameter name for the resource URI */
	get resourceParam() {
		return "resourceUri";
	}

	get callbackUri() {
		return this.getAttribute("callback-uri") ?? "https://sequoia.pub/subscribe";
	/**
	 * Value of the `action` query-parameter used in the unaction redirect.
	 * @returns {string}
	 */
	get unactionValue() {
		return "unaction";
	}

	get label() {
		return this.getAttribute("label") ?? null;
	/** @returns {string} Key in the /check response that signals the action was taken */
	get actionedKey() {
		return "actioned";
	}

	get unsubscribeLabel() {
		return this.getAttribute("unsubscribe-label") ?? null;
	/** @returns {string} CustomEvent name dispatched on success */
	get actionedEventName() {
		return "sequoia-actioned";
	}

	get buttonType() {
		const val = this.getAttribute("button-type");
		return val && val in BUTTON_TYPES ? val : "sequoia";
	/** @returns {string} CustomEvent name dispatched on error */
	get errorEventName() {
		return "sequoia-action-error";
	}

	/** @returns {string} Fallback error message when the thrown value has no message */
	get defaultErrorMessage() {
		return "Action failed";
	}

	get hide() {
		const hideAttr = this.getAttribute("hide");
		return hideAttr === "auto";
	/** @returns {string} SVG string for the button icon */
	getIcon() {
		return "";
	}

	async checkPublication() {
		this.abortController?.abort();
		this.abortController = new AbortController();
	/** @returns {string} Accessible label for the button (defaults to the visible label) */
	getAriaLabel() {
		return this.actioned
			? (this.getUnactionLabel?.() ?? this.getDefaultUnactionLabel?.() ?? "")
			: (this.label ?? this.getDefaultActionLabel?.() ?? "");
	}

		try {
			const uri = this.publicationUri ?? (await fetchPublicationUri());
			this.checkSubscription(uri);
		} catch {
			this.state = { type: "no-publication" };
			this.render();
		}
	/**
	 * Resolve the resource URI for this action. May perform async network calls.
	 * @returns {Promise<string>}
	 */
	async resolveResourceUri() {
		throw new Error("resolveResourceUri() must be implemented by subclass");
	}

	async checkSubscription(publicationUri) {
	// ── Shared logic ─────────────────────────────────────────────────────────

	/**
	 * Check whether the current user has already taken this action for the
	 * given resource URI. Updates this.actioned and re-renders on success.
	 * @param {string} resourceUri
	 */
	async checkStatusFor(resourceUri) {
		try {
			const checkUrl = new URL(`${this.callbackUri}/check`);
			checkUrl.searchParams.set("publicationUri", publicationUri);
			checkUrl.searchParams.set(this.resourceParam, resourceUri);

			// Pass the stored DID so the server can check without a session cookie
			const storedDid = getStoredSubscriberDid();

			});
			if (!res.ok) return;
			const data = await res.json();
			if (data.subscribed) {
				this.subscribed = true;
			if (data[this.actionedKey]) {
				this.actioned = true;
				this.render();
			}
		} catch {
			// Ignore errors — show default subscribe button
			// Ignore errors — show default action button
		}
	}


			return;
		}

		// Unsubscribe: redirect to full-page unsubscribe flow
		if (this.subscribed) {
			const publicationUri =
				this.publicationUri ?? (await fetchPublicationUri());
			window.location.href = `${this.callbackUri}?publicationUri=${encodeURIComponent(publicationUri)}&action=unsubscribe`;
		// Unaction: redirect to the full-page unaction flow
		if (this.actioned) {
			const resourceUri = await this.resolveResourceUri();
			window.location.href = `${this.callbackUri}?${this.resourceParam}=${encodeURIComponent(resourceUri)}&action=${this.unactionValue}`;
			return;
		}


		this.render();

		try {
			const publicationUri =
				this.publicationUri ?? (await fetchPublicationUri());
			const resourceUri = await this.resolveResourceUri();

			const response = await fetch(this.callbackUri, {
				method: "POST",
				headers: { "Content-Type": "application/json" },
				credentials: "include",
				referrerPolicy: "no-referrer-when-downgrade",
				body: JSON.stringify({ publicationUri }),
				body: JSON.stringify({ [this.resourceParam]: resourceUri }),
			});

			const data = await response.json();

			if (response.status === 401 && data.authenticated === false) {
				// Redirect to the hosted subscribe page to complete OAuth,
				// Redirect to the hosted action page to complete OAuth,
				// passing the current page URL (without credentials) as returnTo.
				const subscribeUrl = new URL(data.subscribeUrl);
				const actionUrl = new URL(data.subscribeUrl);
				const pageUrl = new URL(window.location.href);
				pageUrl.username = "";
				pageUrl.password = "";
				subscribeUrl.searchParams.set("returnTo", pageUrl.toString());
				window.location.href = subscribeUrl.toString();
				actionUrl.searchParams.set("returnTo", pageUrl.toString());
				window.location.href = actionUrl.toString();
				return;
			}


				}
			}

			this.subscribed = true;
			this.actioned = true;
			this.state = { type: "idle" };
			this.render();

			this.dispatchEvent(
				new CustomEvent("sequoia-subscribed", {
				new CustomEvent(this.actionedEventName, {
					bubbles: true,
					composed: true,
					detail: { publicationUri, recordUri },
					detail: { [this.resourceParam]: resourceUri, recordUri },
				}),
			);
		} catch (error) {
			if (this.state.type !== "loading") return;

			const message =
				error instanceof Error ? error.message : "Failed to subscribe";
				error instanceof Error ? error.message : this.defaultErrorMessage;
			this.state = { type: "error", message };
			this.render();

			this.dispatchEvent(
				new CustomEvent("sequoia-subscribe-error", {
				new CustomEvent(this.errorEventName, {
					bubbles: true,
					composed: true,
					detail: { message },

	render() {
		const { type } = this.state;

		if (type === "no-publication") {
		if (type === "no-resource") {
			if (this.hide) {
				this.wrapper.innerHTML = "";
				this.wrapper.style.display = "none";

		}

		const isLoading = type === "loading";
		const config = BUTTON_TYPES[this.buttonType] ?? BUTTON_TYPES.sequoia;

		const icon = isLoading
			? `<span class="sequoia-loading-spinner"></span>`
			: config.icon;
			: this.getIcon();

		const label = this.actioned
			? (this.getUnactionLabel?.() ?? this.getDefaultUnactionLabel?.() ?? "")
			: (this.label ?? this.getDefaultActionLabel?.() ?? "");

		const label = this.subscribed
			? (this.unsubscribeLabel ?? config.unsubscribe)
			: (this.label ?? config.subscribe);
		const ariaLabel = this.getAriaLabel();

		const errorHtml =
			type === "error"


		this.wrapper.innerHTML = `
			<button
				class="sequoia-subscribe-button"
				class="sequoia-button"
				type="button"
				part="button"
				${isLoading ? "disabled" : ""}
				aria-label="${label}"
				aria-label="${ariaLabel}"
			>
				${icon}
				${label}

	}
}

class SequoiaSubscribe extends SequoiaActionBase {
	static get observedAttributes() {
		return [
			"publication-uri",
			"callback-uri",
			"label",
			"unsubscribe-label",
			"button-type",
			"hide",
		];
	}

	connectedCallback() {
		consumeReturnParams();
		this.checkPublication();
	}

	get publicationUri() {
		return this.getAttribute("publication-uri") ?? null;
	}

	get label() {
		return this.getAttribute("label") ?? null;
	}

	get buttonType() {
		const val = this.getAttribute("button-type");
		return val && val in BUTTON_TYPES ? val : "sequoia";
	}

	get unsubscribeLabel() {
		return this.getAttribute("unsubscribe-label") ?? null;
	}

	// ── Template method overrides ────────────────────────────────────────────

	get defaultCallbackUri() {
		return "https://sequoia.pub/subscribe";
	}
	get resourceParam() {
		return "publicationUri";
	}
	get unactionValue() {
		return "unsubscribe";
	}
	get actionedKey() {
		return "subscribed";
	}
	get actionedEventName() {
		return "sequoia-subscribed";
	}
	get errorEventName() {
		return "sequoia-subscribe-error";
	}
	get defaultErrorMessage() {
		return "Failed to subscribe";
	}

	getDefaultActionLabel() {
		return (BUTTON_TYPES[this.buttonType] ?? BUTTON_TYPES.sequoia).subscribe;
	}

	getDefaultUnactionLabel() {
		return (BUTTON_TYPES[this.buttonType] ?? BUTTON_TYPES.sequoia).unsubscribe;
	}

	getUnactionLabel() {
		return this.unsubscribeLabel;
	}

	getIcon() {
		return (BUTTON_TYPES[this.buttonType] ?? BUTTON_TYPES.sequoia).icon;
	}

	async resolveResourceUri() {
		return this.publicationUri ?? (await fetchPublicationUri());
	}

	// ── SequoiaSubscribe-specific logic ──────────────────────────────────────

	/** @returns {boolean} Whether the user is currently subscribed. Alias for this.actioned. */
	get subscribed() {
		return this.actioned;
	}

	/**
	 * Check whether the current user is subscribed to the given publication URI.
	 * Forwards to the shared checkStatusFor() method.
	 * @param {string} publicationUri
	 */
	checkSubscription(publicationUri) {
		return this.checkStatusFor(publicationUri);
	}

	async checkPublication() {
		this.abortController?.abort();
		this.abortController = new AbortController();

		try {
			const uri = await this.resolveResourceUri();
			this.checkStatusFor(uri);
		} catch {
			this.state = { type: "no-resource" };
			this.render();
		}
	}
}

class SequoiaRecommend extends SequoiaActionBase {
	static get observedAttributes() {
		return ["document-uri", "callback-uri", "button-type", "hide"];
	}

	connectedCallback() {
		consumeReturnParams();
		this.checkDocument();
	}

	get documentUri() {
		const attrUri = this.getAttribute("document-uri");
		if (attrUri) return attrUri;
		const linkTag = document.querySelector(
			'link[rel="site.standard.document"]',
		);
		return linkTag?.href ?? null;
	}

	get buttonType() {
		const val = this.getAttribute("button-type");
		return val && val in RECOMMEND_ICON_TYPES ? val : "heart";
	}

	// ── Template method overrides ────────────────────────────────────────────

	get defaultCallbackUri() {
		return "https://sequoia.pub/recommend";
	}
	get resourceParam() {
		return "documentUri";
	}
	get unactionValue() {
		return "remove";
	}
	get actionedKey() {
		return "recommended";
	}
	get actionedEventName() {
		return "sequoia-recommended";
	}
	get errorEventName() {
		return "sequoia-recommend-error";
	}
	get defaultErrorMessage() {
		return "Failed to recommend";
	}

	getAriaLabel() {
		const config =
			RECOMMEND_ICON_TYPES[this.buttonType] ?? RECOMMEND_ICON_TYPES.heart;
		return this.actioned ? config.unaction : config.action;
	}

	getIcon() {
		const config =
			RECOMMEND_ICON_TYPES[this.buttonType] ?? RECOMMEND_ICON_TYPES.heart;
		return this.actioned ? config.iconActioned : config.icon;
	}

	async resolveResourceUri() {
		const uri = this.documentUri;
		if (!uri) throw new Error("No document URI found");
		return uri;
	}

	// ── SequoiaRecommend-specific logic ──────────────────────────────────────

	async checkDocument() {
		this.abortController?.abort();
		this.abortController = new AbortController();

		const uri = this.documentUri;
		if (!uri) {
			this.state = { type: "no-resource" };
			this.render();
			return;
		}

		this.checkStatusFor(uri);
	}
}

/**
 * Escape HTML special characters (no DOM dependency for SSR).
 * @param {string} text

		.replace(/"/g, "&quot;");
}

// Register the custom element
// Register the custom elements
if (typeof customElements !== "undefined") {
	customElements.define("sequoia-subscribe", SequoiaSubscribe);
	customElements.define("sequoia-recommend", SequoiaRecommend);
}

// Export for module usage
/**
 * Sequoia Subscribe - An AT Protocol-powered subscribe component
 *
 * A self-contained Web Component that lets users subscribe to a publication
 * via the AT Protocol by creating a site.standard.graph.subscription record.
 *
 * Usage:
 *   <sequoia-subscribe></sequoia-subscribe>
 *
 * The component resolves the publication AT URI from the host site's
 * /.well-known/site.standard.publication endpoint.
 *
 * Attributes:
 *   - publication-uri: Override the publication AT URI (optional)
 *   - callback-uri: Redirect URI after OAuth authentication (default: "https://sequoia.pub/subscribe")
 *   - button-type: Branding style — "sequoia" (default), "bluesky", "blacksky", "atmosphere", or "plain"
 *   - label: Override the subscribe button label text
 *   - unsubscribe-label: Override the unsubscribe button label text
 *   - hide: Set to "auto" to hide if no publication URI is detected
 *
 * Events:
 *   - sequoia-subscribed: Fired when the subscription is created successfully.
 *     detail: { publicationUri: string, recordUri: string }
 *   - sequoia-subscribe-error: Fired when the subscription fails.
 *     detail: { message: string }
 */
export { SequoiaSubscribe };

/**
 * Sequoia Recommend - An AT Protocol-powered recommend component
 *
 * A self-contained Web Component that lets users recommend a document
 * via the AT Protocol by creating a site.standard.graph.recommend record.
 *
 * Usage:
 *   <sequoia-recommend></sequoia-recommend>
 *
 * The component resolves the document AT URI from the `document-uri` attribute
 * or a <link rel="site.standard.document" href="at://..."> tag in the page head.
 *
 * Attributes:
 *   - document-uri: AT Protocol URI of the document to recommend (optional if link tag present)
 *   - callback-uri: Redirect URI after OAuth authentication (default: "https://sequoia.pub/recommend")
 *   - button-type: Icon style — "heart" (default), "star", or "thumbs-up"
 *   - hide: Set to "auto" to hide if no document URI is detected
 *
 * Events:
 *   - sequoia-recommended: Fired when the recommendation is created successfully.
 *     detail: { documentUri: string, recordUri: string }
 *   - sequoia-recommend-error: Fired when the recommendation fails.
 *     detail: { message: string }
 */
export { SequoiaRecommend };

packages/server/README.md +9 −5

# Sequoia Server

Self-hostable AT Protocol OAuth and subscription server. Handles Bluesky login and manages `site.standard.graph.subscription` records on behalf of users. Built with Bun, Hono, and Redis.
Self-hostable AT Protocol OAuth and subscription/recommendation server. Handles Bluesky login and manages `site.standard.graph.subscription` and `site.standard.graph.recommend` records on behalf of users. Built with Bun, Hono, and Redis.

## Quickstart



## How it works

1. A user visits `/subscribe?publicationUri=at://...` and enters their Bluesky handle
1. A user visits `/subscribe?publicationUri=at://...` or `/recommend?documentUri=at://...` and enters their Bluesky handle
2. The server initiates an AT Protocol OAuth flow — the user authorizes on Bluesky
3. After callback, the server creates a `site.standard.graph.subscription` record in the user's repo
4. The [sequoia-subscribe](https://github.com/standard-schema/sequoia) web component can point to this server for the full flow
3. After callback, the server creates a `site.standard.graph.subscription` or `site.standard.graph.recommend` record in the user's repo
4. The [sequoia-subscribe](https://github.com/standard-schema/sequoia) web components can point to this server for the full flow

### Routes


| `/subscribe` | POST | Subscribe via API (JSON) |
| `/subscribe/check` | GET | Check subscription status |
| `/subscribe/login` | POST | Handle form submission |
| `/recommend` | GET | Recommend page (HTML) |
| `/recommend` | POST | Recommend via API (JSON) |
| `/recommend/check` | GET | Check recommendation status |
| `/recommend/login` | POST | Handle form submission |

## Configuration



### Theming

The subscribe pages use CSS custom properties that can be overridden via environment variables:
The subscribe and recommend pages use CSS custom properties that can be overridden via environment variables:

| Variable | Default |
|----------|---------|

packages/server/src/index.ts +18 −0

import { openDatabase } from "./lib/db";
import auth from "./routes/auth";
import subscribe from "./routes/subscribe";
import recommend from "./routes/recommend";

const env = loadEnv();


	}),
);
app.route("/subscribe", subscribe);

// Recommend routes with CORS
app.use(
	"/recommend/*",
	cors({
		origin: (origin) => origin,
		credentials: true,
	}),
);
app.use(
	"/recommend",
	cors({
		origin: (origin) => origin,
		credentials: true,
	}),
);
app.route("/recommend", recommend);

console.log(`Sequoia server listening on port ${env.PORT}`);


packages/server/src/lib/oauth-client.ts +1 −1

import { createStateStore, createSessionStore } from "./stores";

export const OAUTH_SCOPE =
	"atproto repo:site.standard.graph.subscription?action=create&action=delete";
	"atproto repo:site.standard.graph.recommend?action=create&action=delete repo:site.standard.graph.subscription?action=create&action=delete";

export function createOAuthClient(
	db: Database,

packages/server/src/routes/lib.ts (added) +179 −0

1	+	import type { Agent } from "@atproto/api";
2	+	import { escapeHtml, page } from "../lib/theme";
3	+
4	+	export const REDIRECT_DELAY_SECONDS = 5;
5	+
6	+	// ============================================================================
7	+	// Helpers
8	+	// ============================================================================
9	+
10	+	export function withReturnToParam(
11	+	returnTo: string \| undefined,
12	+	key: string,
13	+	value: string,
14	+	): string \| undefined {
15	+	if (!returnTo) return undefined;
16	+	try {
17	+	const url = new URL(returnTo);
18	+	url.searchParams.set(key, value);
19	+	return url.toString();
20	+	} catch {
21	+	return returnTo;
22	+	}
23	+	}
24	+
25	+	/**
26	+	* Scan a repo for a record in `collection` where `record[field] === uri`.
27	+	* Returns the record AT-URI, or null if not found.
28	+	*/
29	+	export async function findExistingRecord(
30	+	agent: Agent,
31	+	did: string,
32	+	collection: string,
33	+	field: string,
34	+	uri: string,
35	+	): Promise<string \| null> {
36	+	let cursor: string \| undefined;
37	+
38	+	do {
39	+	const result = await agent.com.atproto.repo.listRecords({
40	+	repo: did,
41	+	collection,
42	+	limit: 100,
43	+	cursor,
44	+	});
45	+
46	+	for (const record of result.data.records) {
47	+	const value = record.value as Record<string, unknown>;
48	+	if (value[field] === uri) {
49	+	return record.uri;
50	+	}
51	+	}
52	+
53	+	cursor = result.data.cursor;
54	+	} while (cursor);
55	+
56	+	return null;
57	+	}
58	+
59	+	// ============================================================================
60	+	// HTML rendering
61	+	// ============================================================================
62	+
63	+	export function renderHandleForm(params: {
64	+	resourceUri: string;
65	+	resourceField: string;
66	+	loginPath: string;
67	+	title: string;
68	+	description: string;
69	+	buttonLabel: string;
70	+	returnTo?: string;
71	+	error?: string;
72	+	action?: string;
73	+	}): string {
74	+	const {
75	+	resourceUri,
76	+	resourceField,
77	+	loginPath,
78	+	title,
79	+	description,
80	+	buttonLabel,
81	+	returnTo,
82	+	error,
83	+	action,
84	+	} = params;
85	+
86	+	const errorHtml = error ? `<p class="error">${escapeHtml(error)}</p>` : "";
87	+	const returnToInput = returnTo
88	+	? `<input type="hidden" name="returnTo" value="${escapeHtml(returnTo)}" />`
89	+	: "";
90	+	const actionInput = action
91	+	? `<input type="hidden" name="action" value="${escapeHtml(action)}" />`
92	+	: "";
93	+
94	+	return page(`
95	+	<h1>${escapeHtml(title)}</h1>
96	+	<p>${escapeHtml(description)}</p>
97	+	${errorHtml}
98	+	<form method="POST" action="${escapeHtml(loginPath)}">
99	+	<input type="hidden" name="${escapeHtml(resourceField)}" value="${escapeHtml(resourceUri)}" />
100	+	${returnToInput}
101	+	${actionInput}
102	+	<input
103	+	type="text"
104	+	name="handle"
105	+	placeholder="you.bsky.social"
106	+	autocomplete="username"
107	+	required
108	+	autofocus
109	+	/>
110	+	<button type="submit">${escapeHtml(buttonLabel)}</button>
111	+	</form>
112	+	`);
113	+	}
114	+
115	+	export function renderSuccess(params: {
116	+	resourceUri: string;
117	+	resourceLabel: string;
118	+	recordUri: string \| null;
119	+	heading: string;
120	+	msg: string;
121	+	returnTo?: string;
122	+	}): string {
123	+	const { resourceUri, resourceLabel, recordUri, heading, msg, returnTo } =
124	+	params;
125	+	const escapedResourceUri = escapeHtml(resourceUri);
126	+	const escapedReturnTo = returnTo ? escapeHtml(returnTo) : "";
127	+
128	+	const redirectHtml = returnTo
129	+	? `<p id="redirect-msg">Redirecting to <a href="${escapedReturnTo}">${escapedReturnTo}</a> in <span id="countdown">${REDIRECT_DELAY_SECONDS}</span>\u00a0seconds\u2026</p>
130	+	<script>
131	+	(function(){
132	+	var secs = ${REDIRECT_DELAY_SECONDS};
133	+	var el = document.getElementById('countdown');
134	+	var iv = setInterval(function(){
135	+	secs--;
136	+	if (el) el.textContent = String(secs);
137	+	if (secs <= 0) { clearInterval(iv); location.href = ${JSON.stringify(returnTo)}; }
138	+	}, 1000);
139	+	})();
140	+	</script>`
141	+	: "";
142	+	const headExtra = returnTo
143	+	? `<meta http-equiv="refresh" content="${REDIRECT_DELAY_SECONDS};url=${escapedReturnTo}" />`
144	+	: "";
145	+
146	+	return page(
147	+	`
148	+	<h1>${escapeHtml(heading)}</h1>
149	+	<p>${msg}</p>
150	+	${redirectHtml}
151	+	<table>
152	+	<colgroup><col style="width:7rem;"><col></colgroup>
153	+	<tbody>
154	+	<tr>
155	+	<td>${escapeHtml(resourceLabel)}</td>
156	+	<td>
157	+	<div><code><a href="https://pds.ls/${escapedResourceUri}">${escapedResourceUri}</a></code></div>
158	+	</td>
159	+	</tr>
160	+	${
161	+	recordUri
162	+	? `<tr>
163	+	<td>Record</td>
164	+	<td>
165	+	<div><code><a href="https://pds.ls/${escapeHtml(recordUri)}">${escapeHtml(recordUri)}</a></code></div>
166	+	</td>
167	+	</tr>`
168	+	: ""
169	+	}
170	+	</tbody>
171	+	</table>
172	+	`,
173	+	headExtra,
174	+	);
175	+	}
176	+
177	+	export function renderError(message: string): string {
178	+	return page(`<h1>Error</h1><p class="error">${escapeHtml(message)}</p>`);
179	+	}

packages/server/src/routes/recommend.ts (added) +291 −0

1	+	import { Agent } from "@atproto/api";
2	+	import { Hono } from "hono";
3	+	import type { Database } from "bun:sqlite";
4	+	import { createOAuthClient } from "../lib/oauth-client";
5	+	import { getSessionDid, setReturnToCookie } from "../lib/session";
6	+	import type { Env } from "../env";
7	+	import {
8	+	findExistingRecord,
9	+	renderError,
10	+	renderHandleForm,
11	+	renderSuccess,
12	+	withReturnToParam,
13	+	} from "./lib";
14	+
15	+	type Variables = { env: Env; db: Database };
16	+
17	+	const recommend = new Hono<{ Variables: Variables }>();
18	+
19	+	const COLLECTION = "site.standard.graph.recommend";
20	+
21	+	// ============================================================================
22	+	// POST /recommend
23	+	// ============================================================================
24	+
25	+	recommend.post("/", async (c) => {
26	+	const env = c.get("env");
27	+	const db = c.get("db");
28	+
29	+	let documentUri: string;
30	+	try {
31	+	const body = await c.req.json<{ documentUri?: string }>();
32	+	documentUri = body.documentUri ?? "";
33	+	} catch {
34	+	return c.json({ error: "Invalid JSON body" }, 400);
35	+	}
36	+
37	+	if (!documentUri \|\| !documentUri.startsWith("at://")) {
38	+	return c.json({ error: "Missing or invalid documentUri" }, 400);
39	+	}
40	+
41	+	const did = getSessionDid(c);
42	+	if (!did) {
43	+	const subscribeUrl = `${env.CLIENT_URL}/recommend?documentUri=${encodeURIComponent(documentUri)}`;
44	+	return c.json({ authenticated: false, subscribeUrl }, 401);
45	+	}
46	+
47	+	try {
48	+	const client = createOAuthClient(db, env.CLIENT_URL, env.CLIENT_NAME);
49	+	const session = await client.restore(did);
50	+	const agent = new Agent(session);
51	+
52	+	const existingUri = await findExistingRecord(
53	+	agent,
54	+	did,
55	+	COLLECTION,
56	+	"document",
57	+	documentUri,
58	+	);
59	+	if (existingUri) {
60	+	return c.json({
61	+	recommended: true,
62	+	existing: true,
63	+	recordUri: existingUri,
64	+	});
65	+	}
66	+
67	+	const result = await agent.com.atproto.repo.createRecord({
68	+	repo: did,
69	+	collection: COLLECTION,
70	+	record: {
71	+	$type: COLLECTION,
72	+	document: documentUri,
73	+	createdAt: new Date().toISOString(),
74	+	},
75	+	});
76	+
77	+	return c.json({
78	+	recommended: true,
79	+	existing: false,
80	+	recordUri: result.data.uri,
81	+	});
82	+	} catch (error) {
83	+	console.error("Recommend POST error:", error);
84	+	const subscribeUrl = `${env.CLIENT_URL}/recommend?documentUri=${encodeURIComponent(documentUri)}`;
85	+	return c.json({ authenticated: false, subscribeUrl }, 401);
86	+	}
87	+	});
88	+
89	+	// ============================================================================
90	+	// GET /recommend
91	+	// ============================================================================
92	+
93	+	recommend.get("/", async (c) => {
94	+	const env = c.get("env");
95	+	const db = c.get("db");
96	+
97	+	const documentUri = c.req.query("documentUri");
98	+	const action = c.req.query("action");
99	+
100	+	if (action && action !== "remove") {
101	+	return c.html(renderError(`Unsupported action: ${action}`), 400);
102	+	}
103	+
104	+	if (!documentUri \|\| !documentUri.startsWith("at://")) {
105	+	return c.html(renderError("Missing or invalid document URI."), 400);
106	+	}
107	+
108	+	const referer = c.req.header("referer");
109	+	const returnTo =
110	+	c.req.query("returnTo") ??
111	+	(referer && !referer.includes("/recommend") ? referer : undefined);
112	+
113	+	const did = getSessionDid(c);
114	+	if (!did) {
115	+	return c.html(
116	+	renderHandleForm({
117	+	resourceUri: documentUri,
118	+	resourceField: "documentUri",
119	+	loginPath: "/recommend/login",
120	+	title: "Recommend on Sequoia",
121	+	description: "Enter your Bluesky handle to recommend this document.",
122	+	buttonLabel: "Continue on Bluesky",
123	+	returnTo,
124	+	action,
125	+	}),
126	+	);
127	+	}
128	+
129	+	try {
130	+	const client = createOAuthClient(db, env.CLIENT_URL, env.CLIENT_NAME);
131	+	const session = await client.restore(did);
132	+	const agent = new Agent(session);
133	+
134	+	if (action === "remove") {
135	+	const existingUri = await findExistingRecord(
136	+	agent,
137	+	did,
138	+	COLLECTION,
139	+	"document",
140	+	documentUri,
141	+	);
142	+	if (existingUri) {
143	+	const rkey = existingUri.split("/").pop()!;
144	+	await agent.com.atproto.repo.deleteRecord({
145	+	repo: did,
146	+	collection: COLLECTION,
147	+	rkey,
148	+	});
149	+	}
150	+
151	+	return c.html(
152	+	renderSuccess({
153	+	resourceUri: documentUri,
154	+	resourceLabel: "Document",
155	+	recordUri: null,
156	+	heading: "Recommendation Removed",
157	+	msg: existingUri
158	+	? "You've successfully removed your recommendation."
159	+	: "You hadn't recommended this document.",
160	+	returnTo: withReturnToParam(returnTo, "sequoia_did", did),
161	+	}),
162	+	);
163	+	}
164	+
165	+	const existingUri = await findExistingRecord(
166	+	agent,
167	+	did,
168	+	COLLECTION,
169	+	"document",
170	+	documentUri,
171	+	);
172	+	const returnToWithDid = withReturnToParam(returnTo, "sequoia_did", did);
173	+
174	+	if (existingUri) {
175	+	return c.html(
176	+	renderSuccess({
177	+	resourceUri: documentUri,
178	+	resourceLabel: "Document",
179	+	recordUri: existingUri,
180	+	heading: "Recommended",
181	+	msg: "You've already recommended this document.",
182	+	returnTo: returnToWithDid,
183	+	}),
184	+	);
185	+	}
186	+
187	+	const result = await agent.com.atproto.repo.createRecord({
188	+	repo: did,
189	+	collection: COLLECTION,
190	+	record: {
191	+	$type: COLLECTION,
192	+	document: documentUri,
193	+	createdAt: new Date().toISOString(),
194	+	},
195	+	});
196	+
197	+	return c.html(
198	+	renderSuccess({
199	+	resourceUri: documentUri,
200	+	resourceLabel: "Document",
201	+	recordUri: result.data.uri,
202	+	heading: "Recommended",
203	+	msg: "You've successfully recommended this document!",
204	+	returnTo: returnToWithDid,
205	+	}),
206	+	);
207	+	} catch (error) {
208	+	console.error("Recommend GET error:", error);
209	+	return c.html(
210	+	renderHandleForm({
211	+	resourceUri: documentUri,
212	+	resourceField: "documentUri",
213	+	loginPath: "/recommend/login",
214	+	title: "Recommend on Sequoia",
215	+	description: "Enter your Bluesky handle to recommend this document.",
216	+	buttonLabel: "Continue on Bluesky",
217	+	returnTo,
218	+	error: "Session expired. Please sign in again.",
219	+	action,
220	+	}),
221	+	);
222	+	}
223	+	});
224	+
225	+	// ============================================================================
226	+	// GET /recommend/check
227	+	// ============================================================================
228	+
229	+	recommend.get("/check", async (c) => {
230	+	const env = c.get("env");
231	+	const db = c.get("db");
232	+
233	+	const documentUri = c.req.query("documentUri");
234	+
235	+	if (!documentUri \|\| !documentUri.startsWith("at://")) {
236	+	return c.json({ error: "Missing or invalid documentUri" }, 400);
237	+	}
238	+
239	+	const did = getSessionDid(c) ?? c.req.query("did") ?? null;
240	+	if (!did \|\| !did.startsWith("did:")) {
241	+	return c.json({ authenticated: false }, 401);
242	+	}
243	+
244	+	try {
245	+	const client = createOAuthClient(db, env.CLIENT_URL, env.CLIENT_NAME);
246	+	const session = await client.restore(did);
247	+	const agent = new Agent(session);
248	+	const recordUri = await findExistingRecord(
249	+	agent,
250	+	did,
251	+	COLLECTION,
252	+	"document",
253	+	documentUri,
254	+	);
255	+	return recordUri
256	+	? c.json({ recommended: true, recordUri })
257	+	: c.json({ recommended: false });
258	+	} catch {
259	+	return c.json({ authenticated: false }, 401);
260	+	}
261	+	});
262	+
263	+	// ============================================================================
264	+	// POST /recommend/login
265	+	// ============================================================================
266	+
267	+	recommend.post("/login", async (c) => {
268	+	const env = c.get("env");
269	+
270	+	const body = await c.req.parseBody();
271	+	const handle = (body.handle as string \| undefined)?.trim();
272	+	const documentUri = body.documentUri as string \| undefined;
273	+	const formReturnTo = (body.returnTo as string \| undefined) \|\| undefined;
274	+	const formAction = (body.action as string \| undefined) \|\| undefined;
275	+
276	+	if (!handle \|\| !documentUri) {
277	+	return c.html(renderError("Missing handle or document URI."), 400);
278	+	}
279	+
280	+	const returnTo =
281	+	`${env.CLIENT_URL}/recommend?documentUri=${encodeURIComponent(documentUri)}` +
282	+	(formAction ? `&action=${encodeURIComponent(formAction)}` : "") +
283	+	(formReturnTo ? `&returnTo=${encodeURIComponent(formReturnTo)}` : "");
284	+	setReturnToCookie(c, returnTo, env.CLIENT_URL);
285	+
286	+	return c.redirect(
287	+	`${env.CLIENT_URL}/oauth/login?handle=${encodeURIComponent(handle)}`,
288	+	);
289	+	});
290	+
291	+	export default recommend;

packages/server/src/routes/subscribe.ts +68 −181

import type { Database } from "bun:sqlite";
import { createOAuthClient } from "../lib/oauth-client";
import { getSessionDid, setReturnToCookie } from "../lib/session";
import { page, escapeHtml } from "../lib/theme";
import type { Env } from "../env";
import {
	findExistingRecord,
	renderError,
	renderHandleForm,
	renderSuccess,
	withReturnToParam,
} from "./lib";

type Variables = { env: Env; db: Database };

const subscribe = new Hono<{ Variables: Variables }>();

const COLLECTION = "site.standard.graph.subscription";
const REDIRECT_DELAY_SECONDS = 5;

// ============================================================================
// Helpers
// ============================================================================

function withReturnToParam(
	returnTo: string | undefined,
	key: string,
	value: string,
): string | undefined {
	if (!returnTo) return undefined;
	try {
		const url = new URL(returnTo);
		url.searchParams.set(key, value);
		return url.toString();
	} catch {
		return returnTo;
	}
}

async function findExistingSubscription(
	agent: Agent,
	did: string,
	publicationUri: string,
): Promise<string | null> {
	let cursor: string | undefined;

	do {
		const result = await agent.com.atproto.repo.listRecords({
			repo: did,
			collection: COLLECTION,
			limit: 100,
			cursor,
		});

		for (const record of result.data.records) {
			const value = record.value as { publication?: string };
			if (value.publication === publicationUri) {
				return record.uri;
			}
		}

		cursor = result.data.cursor;
	} while (cursor);

	return null;
}

// ============================================================================
// POST /subscribe

		const session = await client.restore(did);
		const agent = new Agent(session);

		const existingUri = await findExistingSubscription(
		const existingUri = await findExistingRecord(
			agent,
			did,
			COLLECTION,
			"publication",
			publicationUri,
		);
		if (existingUri) {

	const did = getSessionDid(c);
	if (!did) {
		return c.html(
			renderHandleForm(publicationUri, returnTo, undefined, action),
			renderHandleForm({
				resourceUri: publicationUri,
				resourceField: "publicationUri",
				loginPath: "/subscribe/login",
				title: "Subscribe on Sequoia",
				description:
					"Enter your Bluesky handle to subscribe to this publication.",
				buttonLabel: "Continue on Bluesky",
				returnTo,
				action,
			}),
		);
	}


		const agent = new Agent(session);

		if (action === "unsubscribe") {
			const existingUri = await findExistingSubscription(
			const existingUri = await findExistingRecord(
				agent,
				did,
				COLLECTION,
				"publication",
				publicationUri,
			);
			if (existingUri) {

			}

			return c.html(
				renderSuccess(
					publicationUri,
					null,
					"Unsubscribed",
					existingUri
				renderSuccess({
					resourceUri: publicationUri,
					resourceLabel: "Publication",
					recordUri: null,
					heading: "Unsubscribed",
					msg: existingUri
						? "You've successfully unsubscribed!"
						: "You weren't subscribed to this publication.",
					withReturnToParam(cleanReturnTo, "sequoia_unsubscribed", "1"),
				),
					returnTo: withReturnToParam(
						cleanReturnTo,
						"sequoia_unsubscribed",
						"1",
					),
				}),
			);
		}

		const existingUri = await findExistingSubscription(
		const existingUri = await findExistingRecord(
			agent,
			did,
			COLLECTION,
			"publication",
			publicationUri,
		);
		const returnToWithDid = withReturnToParam(returnTo, "sequoia_did", did);

		if (existingUri) {
			return c.html(
				renderSuccess(
					publicationUri,
					existingUri,
					"Subscribed",
					"You're already subscribed to this publication.",
					returnToWithDid,
				),
				renderSuccess({
					resourceUri: publicationUri,
					resourceLabel: "Publication",
					recordUri: existingUri,
					heading: "Subscribed",
					msg: "You're already subscribed to this publication.",
					returnTo: returnToWithDid,
				}),
			);
		}


		});

		return c.html(
			renderSuccess(
				publicationUri,
				result.data.uri,
				"Subscribed",
				"You've successfully subscribed!",
				returnToWithDid,
			),
			renderSuccess({
				resourceUri: publicationUri,
				resourceLabel: "Publication",
				recordUri: result.data.uri,
				heading: "Subscribed",
				msg: "You've successfully subscribed!",
				returnTo: returnToWithDid,
			}),
		);
	} catch (error) {
		console.error("Subscribe GET error:", error);
		return c.html(
			renderHandleForm(
				publicationUri,
			renderHandleForm({
				resourceUri: publicationUri,
				resourceField: "publicationUri",
				loginPath: "/subscribe/login",
				title: "Subscribe on Sequoia",
				description:
					"Enter your Bluesky handle to subscribe to this publication.",
				buttonLabel: "Continue on Bluesky",
				returnTo,
				"Session expired. Please sign in again.",
				error: "Session expired. Please sign in again.",
				action,
			),
			}),
		);
	}
});

		const client = createOAuthClient(db, env.CLIENT_URL, env.CLIENT_NAME);
		const session = await client.restore(did);
		const agent = new Agent(session);
		const recordUri = await findExistingSubscription(
		const recordUri = await findExistingRecord(
			agent,
			did,
			COLLECTION,
			"publication",
			publicationUri,
		);
		return recordUri

		`${env.CLIENT_URL}/oauth/login?handle=${encodeURIComponent(handle)}`,
	);
});

// ============================================================================
// HTML rendering
// ============================================================================

function renderHandleForm(
	publicationUri: string,
	returnTo?: string,
	error?: string,
	action?: string,
): string {
	const errorHtml = error ? `<p class="error">${escapeHtml(error)}</p>` : "";
	const returnToInput = returnTo
		? `<input type="hidden" name="returnTo" value="${escapeHtml(returnTo)}" />`
		: "";
	const actionInput = action
		? `<input type="hidden" name="action" value="${escapeHtml(action)}" />`
		: "";

	return page(`
		<h1>Subscribe on Bluesky</h1>
		<p>Enter your Bluesky handle to subscribe to this publication.</p>
		${errorHtml}
		<form method="POST" action="/subscribe/login">
			<input type="hidden" name="publicationUri" value="${escapeHtml(publicationUri)}" />
			${returnToInput}
			${actionInput}
			<input
				type="text"
				name="handle"
				placeholder="you.bsky.social"
				autocomplete="username"
				required
				autofocus
			/>
			<button type="submit">Continue on Bluesky</button>
		</form>
	`);
}

function renderSuccess(
	publicationUri: string,
	recordUri: string | null,
	heading: string,
	msg: string,
	returnTo?: string,
): string {
	const escapedPublicationUri = escapeHtml(publicationUri);
	const escapedReturnTo = returnTo ? escapeHtml(returnTo) : "";

	const redirectHtml = returnTo
		? `<p id="redirect-msg">Redirecting to <a href="${escapedReturnTo}">${escapedReturnTo}</a> in <span id="countdown">${REDIRECT_DELAY_SECONDS}</span>\u00a0seconds\u2026</p>
		<script>
		(function(){
			var secs = ${REDIRECT_DELAY_SECONDS};
			var el = document.getElementById('countdown');
			var iv = setInterval(function(){
				secs--;
				if (el) el.textContent = String(secs);
				if (secs <= 0) { clearInterval(iv); location.href = ${JSON.stringify(returnTo)}; }
			}, 1000);
		})();
		</script>`
		: "";
	const headExtra = returnTo
		? `<meta http-equiv="refresh" content="${REDIRECT_DELAY_SECONDS};url=${escapedReturnTo}" />`
		: "";

	return page(
		`
		<h1>${escapeHtml(heading)}</h1>
		<p>${msg}</p>
		${redirectHtml}
		<table>
			<colgroup><col style="width:7rem;"><col></colgroup>
			<tbody>
				<tr>
					<td>Publication</td>
					<td>
						<div><code><a href="https://pds.ls/${escapedPublicationUri}">${escapedPublicationUri}</a></code></div>
					</td>
				</tr>
				${
					recordUri
						? `<tr>
					<td>Record</td>
					<td>
						<div><code><a href="https://pds.ls/${escapeHtml(recordUri)}">${escapeHtml(recordUri)}</a></code></div>
					</td>
				</tr>`
						: ""
				}
			</tbody>
		</table>
	`,
		headExtra,
	);
}

function renderError(message: string): string {
	return page(`<h1>Error</h1><p class="error">${escapeHtml(message)}</p>`);
}

export default subscribe;

12	12
13	13		The component will look for your publication AT URI from your site's `/.well-known/site.standard.publication` endpoint automatically, so no additional configuration is required for most setups.
14	14
	15	+	:::tip
	16	+	`sequoia-subscribe.js` registers both the `<sequoia-subscribe>` and `<sequoia-recommend>` custom elements. You only need to import it once even if you use both components on the same page.
	17	+	:::
	18	+
15	19		## Usage
16	20
17	21		Since `sequoia-subscribe` is a standard Web Component, it works with any framework. Choose your setup below:

2	2		import { cors } from "hono/cors";
3	3		import auth from "./routes/auth";
4	4		import subscribe from "./routes/subscribe";
	5	+	import recommend from "./routes/recommend";
5	6		import "./lib/path-redirect";
6	7
7	8		type Bindings = {

29	30
30	31		app.route("/oauth", auth);
31	32		app.route("/subscribe", subscribe);
	33	+
	34	+	app.use(
	35	+	"/recommend",
	36	+	cors({
	37	+	origin: (origin) => origin,
	38	+	credentials: true,
	39	+	}),
	40	+	);
	41	+	app.use(
	42	+	"/recommend/*",
	43	+	cors({
	44	+	origin: (origin) => origin,
	45	+	credentials: true,
	46	+	}),
	47	+	);
	48	+	app.route("/recommend", recommend);
32	49
33	50		app.get("/api/health", (c) => {
34	51		return c.json({ status: "ok" });

4	4		import { createStateStore, createSessionStore } from "./kv-stores";
5	5
6	6		export const OAUTH_SCOPE =
7		-	"atproto repo:site.standard.graph.subscription?action=create&action=delete";
	7	+	"atproto repo:site.standard.graph.recommend?action=create&action=delete repo:site.standard.graph.subscription?action=create&action=delete";
8	8
9	9		export function createOAuthClient(kv: KVNamespace, clientUrl: string) {
10	10		const clientId = `${clientUrl}/oauth/client-metadata.json`;

22	22		redirect_uris: [redirectUri],
23	23		grant_types: ["authorization_code", "refresh_token"],
24	24		response_types: ["code"],
25		-	scope: "atproto repo:site.standard.graph.subscription?action=create",
	25	+	scope: OAUTH_SCOPE,
26	26		token_endpoint_auth_method: "none",
27	27		application_type: "web",
28	28		dpop_bound_access_tokens: true,

34	34		{ text: "Setup", link: "/setup" },
35	35		{ text: "Publishing", link: "/publishing" },
36	36		{ text: "Comments", link: "/comments" },
	37	+	{ text: "Recommend", link: "/recommend" },
37	38		{ text: "Subscribe", link: "/subscribe" },
38	39		{ text: "Verifying", link: "/verifying" },
39	40		{ text: "Workflows", link: "/workflows" },

8	8		binding = "ASSETS"
9	9		not_found_handling = "single-page-application"
10	10		html_handling = "auto-trailing-slash"
11		-	run_worker_first = ["/api/", "/oauth/", "/subscribe", "/subscribe/*"]
	11	+	run_worker_first = ["/api/", "/oauth/", "/recommend", "/recommend/", "/subscribe", "/subscribe/"]
12	12
13	13		[[kv_namespaces]]
14	14		binding = "SEQUOIA_SESSIONS"

1	1		# Sequoia Server
2	2
3		-	Self-hostable AT Protocol OAuth and subscription server. Handles Bluesky login and manages `site.standard.graph.subscription` records on behalf of users. Built with Bun, Hono, and Redis.
	3	+	Self-hostable AT Protocol OAuth and subscription/recommendation server. Handles Bluesky login and manages `site.standard.graph.subscription` and `site.standard.graph.recommend` records on behalf of users. Built with Bun, Hono, and Redis.
4	4
5	5		## Quickstart
6	6

23	23
24	24		## How it works
25	25
26		-	1. A user visits `/subscribe?publicationUri=at://...` and enters their Bluesky handle
	26	+	1. A user visits `/subscribe?publicationUri=at://...` or `/recommend?documentUri=at://...` and enters their Bluesky handle
27	27		2. The server initiates an AT Protocol OAuth flow — the user authorizes on Bluesky
28		-	3. After callback, the server creates a `site.standard.graph.subscription` record in the user's repo
29		-	4. The [sequoia-subscribe](https://github.com/standard-schema/sequoia) web component can point to this server for the full flow
	28	+	3. After callback, the server creates a `site.standard.graph.subscription` or `site.standard.graph.recommend` record in the user's repo
	29	+	4. The [sequoia-subscribe](https://github.com/standard-schema/sequoia) web components can point to this server for the full flow
30	30
31	31		### Routes
32	32

42	42		\| `/subscribe` \| POST \| Subscribe via API (JSON) \|
43	43		\| `/subscribe/check` \| GET \| Check subscription status \|
44	44		\| `/subscribe/login` \| POST \| Handle form submission \|
	45	+	\| `/recommend` \| GET \| Recommend page (HTML) \|
	46	+	\| `/recommend` \| POST \| Recommend via API (JSON) \|
	47	+	\| `/recommend/check` \| GET \| Check recommendation status \|
	48	+	\| `/recommend/login` \| POST \| Handle form submission \|
45	49
46	50		## Configuration
47	51

54	58
55	59		### Theming
56	60
57		-	The subscribe pages use CSS custom properties that can be overridden via environment variables:
	61	+	The subscribe and recommend pages use CSS custom properties that can be overridden via environment variables:
58	62
59	63		\| Variable \| Default \|
60	64		\|----------\|---------\|

5	5		import { openDatabase } from "./lib/db";
6	6		import auth from "./routes/auth";
7	7		import subscribe from "./routes/subscribe";
	8	+	import recommend from "./routes/recommend";
8	9
9	10		const env = loadEnv();
10	11

43	44		}),
44	45		);
45	46		app.route("/subscribe", subscribe);
	47	+
	48	+	// Recommend routes with CORS
	49	+	app.use(
	50	+	"/recommend/*",
	51	+	cors({
	52	+	origin: (origin) => origin,
	53	+	credentials: true,
	54	+	}),
	55	+	);
	56	+	app.use(
	57	+	"/recommend",
	58	+	cors({
	59	+	origin: (origin) => origin,
	60	+	credentials: true,
	61	+	}),
	62	+	);
	63	+	app.route("/recommend", recommend);
46	64
47	65		console.log(`Sequoia server listening on port ${env.PORT}`);
48	66