@respectify/astro 0.1.0

package/README.md

@@ -0,0 +1,189 @@
+# @respectify/astro
+
+Respectify-powered commenting for Astro. Drop in AI moderation, spam filtering, and a polished comment UX in minutes.
+
+Built for production — powers [nickhodges.com](https://nickhodges.com) as a live Respectify demo.
+
+## Features
+
+- **Respectify AI moderation** — spam detection, toxicity scoring, fallacy detection, revision suggestions
+- **Works with prerendered pages** — comments load at runtime via API; no rebuild needed
+- **One component** — `<CommentSection postSlug="..." />`
+- **Powered by Respectify branding** — optional callout and badge for demos
+- **Astro DB storage** — Turso/libSQL via `@astrojs/db`
+- **Self-contained CSS** — no Tailwind required; customize via CSS variables
+- **Fail-closed** — rejects comments when Respectify is unavailable
+
+## Requirements
+
+- Astro 5 or 6 with **`output: 'server'`** (or hybrid) and a server adapter (Vercel, Node, etc.)
+- [`@astrojs/db`](https://docs.astro.build/en/guides/astro-db/) configured with Turso for production
+- A [Respectify](https://respectify.ai) account (`RESPECTIFY_EMAIL` + `RESPECTIFY_API_KEY`)
+
+## Quick start
+
+### 1. Install
+
+```bash
+npm install @respectify/astro @respectify/client @astrojs/db
+```
+
+### 2. Add the integration
+
+```ts
+// astro.config.ts
+import { defineConfig } from 'astro/config';
+import db from '@astrojs/db';
+import respectify from '@respectify/astro';
+
+export default defineConfig({
+  site: 'https://yoursite.com',
+  output: 'server',
+  adapter: vercel(), // or node, netlify, etc.
+  integrations: [
+    db(),
+    respectify({
+      // Optional: customize post URL for Respectify topic context
+      getPostUrl: (slug, site) => `${site}/blog/${slug}/`,
+    }),
+  ],
+});
+```
+
+### 3. Configure Respectify
+
+Copy the default config to your project root:
+
+```bash
+cp node_modules/@respectify/astro/default-respectify.config.json ./respectify.config.json
+```
+
+Add environment variables:
+
+```env
+RESPECTIFY_EMAIL=you@example.com
+RESPECTIFY_API_KEY=your-api-key
+ASTRO_DB_REMOTE_URL=libsql://...
+ASTRO_DB_APP_TOKEN=...
+```
+
+### 4. Add the database table
+
+Copy this into `db/config.ts` (or import from `@respectify/astro/schema` if your setup supports it):
+
+```ts
+import { defineDb, defineTable, column, NOW } from 'astro:db';
+
+const Comment = defineTable({
+  columns: {
+    id: column.number({ primaryKey: true }),
+    postSlug: column.text(),
+    author: column.text(),
+    email: column.text({ optional: true }),
+    content: column.text(),
+    createdAt: column.date({ default: NOW }),
+    approved: column.boolean({ default: false }),
+    parentId: column.number({ optional: true }),
+  },
+  indexes: [
+    { on: ['postSlug'], unique: false },
+    { on: ['approved'], unique: false },
+  ],
+});
+
+export default defineDb({ tables: { Comment } });
+```
+
+Or use the exported helper:
+
+```ts
+import { defineDb } from 'astro:db';
+import { Comment } from '@respectify/astro/schema';
+
+export default defineDb({ tables: { Comment } });
+```
+
+Run migrations:
+
+```bash
+npx astro db push
+```
+
+### 5. Wire up Astro Actions
+
+```ts
+// src/actions/index.ts
+import { respectifyCommentActions } from '@respectify/astro/actions';
+
+export const server = {
+  comments: respectifyCommentActions,
+};
+```
+
+### 6. Add comments to your layout
+
+```astro
+---
+import CommentSection from '@respectify/astro/components/CommentSection.astro';
+---
+
+<CommentSection postSlug={post.id} />
+```
+
+That's it. Comments are moderated by Respectify before they appear.
+
+## Component props
+
+| Prop | Default | Description |
+|------|---------|-------------|
+| `postSlug` | required | Unique identifier for the page |
+| `apiPath` | `/api/respectify/comments` | Comments API path (must match integration) |
+| `showBranding` | `true` | Show Powered by Respectify callout |
+| `enableDelete` | `false` | Show delete controls when admin is authenticated |
+| `class` | — | Extra CSS class on root wrapper |
+
+## Customization
+
+### CSS variables
+
+Override on `.rf-comments`:
+
+```css
+.rf-comments {
+  --rf-accent: #2bbc89;
+  --rf-accent-hover: #24966f;
+  --rf-radius: 0.75rem;
+}
+```
+
+### Integration options
+
+```ts
+respectify({
+  configPath: './respectify.config.json',
+  commentsApiPath: '/api/respectify/comments',
+  showBranding: true,
+  getPostUrl: (slug, site) => `${site}/posts/${slug}/`,
+  rateLimit: { windowMs: 300_000, maxRequests: 10 },
+});
+```
+
+### Admin delete (optional)
+
+Set `enableDelete` on `CommentSection` and implement auth so `context.locals.isAuthenticated` is true. See the [Nick-Blog](https://github.com/NickHodges/Nick-Blog) repo for a full admin auth example.
+
+## How it works
+
+```text
+Visitor submits comment
+  → Astro Action (comments.submit)
+  → Respectify megacall (spam + respectfulness)
+  → If approved: save to Astro DB
+  → Client refreshes comment list via GET /api/respectify/comments
+```
+
+Post pages can stay `prerender = true`. Only the API route and actions need server runtime.
+
+## License
+
+MIT

package/client/comments.ts

@@ -0,0 +1,59 @@
+export interface CommentResponse {
+  id: number;
+  author: string;
+  content: string;
+  createdAt: string;
+}
+
+export function formatCommentDate(date: string | Date): string {
+  return new Date(date).toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+}
+
+export function escapeHtml(text: string): string {
+  const div = document.createElement('div');
+  div.textContent = text;
+  return div.innerHTML;
+}
+
+export function renderCommentHtml(comment: CommentResponse, options?: { showDelete?: boolean }): string {
+  const formattedDate = formatCommentDate(comment.createdAt);
+  const deleteControls = options?.showDelete
+    ? `
+      <span class="rf-comments__delete-controls" data-delete-for="${comment.id}">
+        <button class="rf-comments__delete-btn" data-comment-id="${comment.id}" type="button">Delete</button>
+        <span class="rf-comments__delete-confirm">
+          <span>Delete?</span>
+          <button class="rf-comments__delete-btn confirm-delete-btn" data-comment-id="${comment.id}" type="button">Yes</button>
+          <button class="rf-comments__delete-cancel cancel-delete-btn" type="button">Cancel</button>
+        </span>
+        <span class="rf-comments__delete-error rf-comments__hidden"></span>
+      </span>`
+    : '';
+
+  return `
+    <article class="rf-comments__item" data-comment-id="${comment.id}">
+      <header class="rf-comments__item-header">
+        <div>
+          <span class="rf-comments__author">${escapeHtml(comment.author)}</span>
+          ${deleteControls}
+        </div>
+        <time class="rf-comments__date" datetime="${comment.createdAt}">${formattedDate}</time>
+      </header>
+      <div class="rf-comments__content">${escapeHtml(comment.content)}</div>
+    </article>`;
+}
+
+export async function fetchComments(apiPath: string, postSlug: string): Promise<CommentResponse[]> {
+  const url = `${apiPath}?slug=${encodeURIComponent(postSlug)}`;
+  const response = await fetch(url);
+  if (!response.ok) return [];
+
+  const data = (await response.json()) as { comments?: CommentResponse[] };
+  return data.comments ?? [];
+}

package/components/CommentForm.astro

@@ -0,0 +1,133 @@
+---
+interface Props {
+  postSlug: string;
+}
+
+const { postSlug } = Astro.props;
+---
+
+<div class="rf-comments__form-panel">
+  <h3 class="rf-comments__form-title">Leave a Comment</h3>
+  <p class="rf-comments__form-note">
+    Your comment will be reviewed by <a href="https://respectify.ai" rel="noopener noreferrer" target="_blank">Respectify</a> before it appears.
+  </p>
+
+  <form class="rf-comments__form" data-post-slug={postSlug} id="rf-comment-form">
+    <div class="rf-comments__field">
+      <label class="rf-comments__label" for="rf-author">
+        Name <span class="rf-comments__required">*</span>
+      </label>
+      <input class="rf-comments__input" id="rf-author" maxlength="100" name="author" required type="text" />
+    </div>
+
+    <div class="rf-comments__field">
+      <label class="rf-comments__label" for="rf-email">Email (optional, not public)</label>
+      <input class="rf-comments__input" id="rf-email" name="email" type="email" />
+    </div>
+
+    <div class="rf-comments__field">
+      <label class="rf-comments__label" for="rf-content">
+        Comment <span class="rf-comments__required">*</span>
+      </label>
+      <textarea class="rf-comments__textarea" id="rf-content" maxlength="5000" name="content" required rows="5"></textarea>
+    </div>
+
+    <button class="rf-comments__submit" id="rf-submit-button" type="submit">
+      <span id="rf-button-text">Submit Comment</span>
+      <svg aria-hidden="true" class="rf-comments__spinner" fill="none" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+        <circle cx="12" cy="12" fill="none" r="10" stroke="currentColor" stroke-width="4" style="opacity:0.25"></circle>
+        <path d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" fill="currentColor" style="opacity:0.75"></path>
+      </svg>
+    </button>
+
+    <div class="rf-comments__message rf-comments__hidden" id="rf-form-message" role="status"></div>
+  </form>
+</div>
+
+<script>
+  import { actions } from 'astro:actions';
+
+  function createTextDiv(text: string, className: string): HTMLDivElement {
+    const div = document.createElement('div');
+    div.className = className;
+    div.textContent = text;
+    return div;
+  }
+
+  const form = document.getElementById('rf-comment-form') as HTMLFormElement | null;
+  const messageEl = document.getElementById('rf-form-message');
+  const submitButton = document.getElementById('rf-submit-button') as HTMLButtonElement | null;
+  const buttonText = document.getElementById('rf-button-text');
+
+  if (form && messageEl && submitButton && buttonText) {
+    const postSlug = form.dataset.postSlug || '';
+
+    form.addEventListener('submit', async (e) => {
+      e.preventDefault();
+
+      submitButton.disabled = true;
+      submitButton.classList.add('rf-comments__submit--analyzing');
+      buttonText.textContent = 'Analyzing with Respectify AI...';
+
+      const formData = new FormData(form);
+
+      try {
+        const { data, error } = await actions.comments.submit({
+          postSlug,
+          author: formData.get('author') as string,
+          email: (formData.get('email') as string) || undefined,
+          content: formData.get('content') as string,
+        });
+
+        messageEl.classList.remove('rf-comments__hidden', 'rf-comments__message--success', 'rf-comments__message--warning', 'rf-comments__message--error');
+        messageEl.replaceChildren();
+
+        if (error) {
+          messageEl.classList.add('rf-comments__message--error');
+          messageEl.appendChild(createTextDiv('An error occurred. Please try again.', 'rf-comments__message-title'));
+          messageEl.classList.remove('rf-comments__hidden');
+          return;
+        }
+
+        if (data.approved) {
+          messageEl.classList.add('rf-comments__message--success');
+          messageEl.appendChild(createTextDiv(`✓ ${data.message}`, 'rf-comments__message-title'));
+          messageEl.appendChild(createTextDiv(data.feedback, 'rf-comments__message-body'));
+          if (data.score !== undefined) {
+            messageEl.appendChild(createTextDiv(`Respectfulness score: ${(data.score * 100).toFixed(0)}%`, 'rf-comments__message-score'));
+          }
+          form.reset();
+          window.dispatchEvent(new CustomEvent('respectify:comment-published', { detail: { postSlug } }));
+        } else {
+          messageEl.classList.add('rf-comments__message--warning');
+          messageEl.appendChild(createTextDiv('Comment needs improvement', 'rf-comments__message-title'));
+          messageEl.appendChild(createTextDiv(data.feedback || 'Your comment did not meet our respectfulness standards.', 'rf-comments__message-body'));
+
+          if (data.suggestion) {
+            const suggestionBox = document.createElement('div');
+            suggestionBox.className = 'rf-comments__suggestion';
+            suggestionBox.appendChild(createTextDiv('Suggestion:', 'rf-comments__suggestion-label'));
+            suggestionBox.appendChild(createTextDiv(data.suggestion, 'rf-comments__suggestion-text'));
+            messageEl.appendChild(suggestionBox);
+          }
+
+          if (data.score !== undefined) {
+            messageEl.appendChild(createTextDiv(`Respectfulness score: ${(data.score * 100).toFixed(0)}%`, 'rf-comments__message-score'));
+          }
+
+          messageEl.appendChild(createTextDiv('Please revise your comment and try again.', 'rf-comments__message-footer'));
+        }
+
+        messageEl.classList.remove('rf-comments__hidden');
+      } catch {
+        messageEl.classList.remove('rf-comments__hidden');
+        messageEl.classList.add('rf-comments__message--error');
+        messageEl.replaceChildren(createTextDiv('An error occurred. Please try again.', 'rf-comments__message-title'));
+      } finally {
+        submitButton.disabled = false;
+        submitButton.classList.remove('rf-comments__submit--analyzing');
+        buttonText.textContent = 'Submit Comment';
+      }
+    });
+  }
+</script>

package/components/CommentList.astro

@@ -0,0 +1,119 @@
+---
+interface Props {
+  postSlug: string;
+  apiPath?: string;
+  enableDelete?: boolean;
+}
+
+const { postSlug, apiPath = '/api/respectify/comments', enableDelete = false } = Astro.props;
+---
+
+<section class="rf-comments__section" data-api-path={apiPath} data-enable-delete={String(enableDelete)} data-post-slug={postSlug}>
+  <h3 class="rf-comments__heading">
+    Comments (<span class="rf-comments__count">…</span>)
+  </h3>
+
+  <p class="rf-comments__loading">Loading comments…</p>
+  <div class="rf-comments__list rf-comments__hidden"></div>
+  <p class="rf-comments__empty rf-comments__hidden">No comments yet. Be the first to comment!</p>
+</section>
+
+<script define:vars={{ apiPath, enableDelete }}>
+  import { actions } from 'astro:actions';
+  import { fetchComments, renderCommentHtml } from '@respectify/astro/client';
+
+  async function checkAuthForDelete() {
+    if (!enableDelete) return false;
+    try {
+      const response = await fetch('/api/auth-status');
+      if (!response.ok) return false;
+      const data = await response.json();
+      return Boolean(data.isAuthenticated);
+    } catch {
+      return false;
+    }
+  }
+
+  function setupDeleteControls() {
+    document.querySelectorAll('.rf-comments__delete-controls').forEach((group) => {
+      if (group.getAttribute('data-delete-bound') === 'true') return;
+      group.setAttribute('data-delete-bound', 'true');
+      group.classList.add('rf-comments__delete-controls--visible');
+
+      const deleteBtn = group.querySelector('.rf-comments__delete-btn:not(.confirm-delete-btn)') ;
+      const confirmBtn = group.querySelector('.confirm-delete-btn');
+      const cancelBtn = group.querySelector('.cancel-delete-btn');
+      const confirmSpan = group.querySelector('.rf-comments__delete-confirm');
+
+      deleteBtn?.addEventListener('click', () => {
+        deleteBtn.classList.add('rf-comments__hidden');
+        confirmSpan?.classList.add('rf-comments__delete-confirm--visible');
+      });
+
+      cancelBtn?.addEventListener('click', () => {
+        confirmSpan?.classList.remove('rf-comments__delete-confirm--visible');
+        deleteBtn?.classList.remove('rf-comments__hidden');
+      });
+
+      confirmBtn?.addEventListener('click', async () => {
+        const commentId = parseInt(confirmBtn.getAttribute('data-comment-id') || '0', 10);
+        if (!commentId) return;
+
+        const { error } = await actions.comments.delete({ commentId });
+        if (error) return;
+
+        document.querySelector(`[data-comment-id="${commentId}"]`)?.remove();
+        const section = document.querySelector('.rf-comments__section');
+        const countEl = section?.querySelector('.rf-comments__count');
+        if (countEl) {
+          countEl.textContent = String(Math.max(parseInt(countEl.textContent || '0', 10) - 1, 0));
+        }
+      });
+    });
+  }
+
+  async function loadComments(section) {
+    const postSlug = section.dataset.postSlug || '';
+    const path = section.dataset.apiPath || apiPath;
+    const loadingEl = section.querySelector('.rf-comments__loading');
+    const listEl = section.querySelector('.rf-comments__list');
+    const emptyEl = section.querySelector('.rf-comments__empty');
+    const countEl = section.querySelector('.rf-comments__count');
+
+    try {
+      const isAdmin = await checkAuthForDelete();
+      const comments = await fetchComments(path, postSlug);
+
+      loadingEl?.classList.add('rf-comments__hidden');
+      if (countEl) countEl.textContent = String(comments.length);
+
+      if (comments.length === 0) {
+        emptyEl?.classList.remove('rf-comments__hidden');
+        return;
+      }
+
+      if (listEl) {
+        listEl.innerHTML = comments.map((c) => renderCommentHtml(c, { showDelete: isAdmin })).join('');
+        listEl.classList.remove('rf-comments__hidden');
+      }
+
+      if (isAdmin) setupDeleteControls();
+    } catch {
+      if (loadingEl) loadingEl.textContent = 'Unable to load comments.';
+    }
+  }
+
+  const section = document.querySelector('.rf-comments__section');
+  if (section) {
+    loadComments(section);
+
+    window.addEventListener('respectify:comment-published', (event) => {
+      const detail = event.detail;
+      if (detail?.postSlug === section.dataset.postSlug) {
+        section.querySelector('.rf-comments__empty')?.classList.add('rf-comments__hidden');
+        section.querySelector('.rf-comments__list')?.classList.remove('rf-comments__hidden');
+        loadComments(section);
+      }
+    });
+  }
+</script>

package/components/CommentSection.astro

@@ -0,0 +1,41 @@
+---
+import '@respectify/astro/styles.css';
+import PoweredByRespectify from './PoweredByRespectify.astro';
+import CommentList from './CommentList.astro';
+import CommentForm from './CommentForm.astro';
+
+interface Props {
+  /** Unique identifier for the page/post (e.g. blog slug) */
+  postSlug: string;
+  /** API path injected by the integration (default: /api/respectify/comments) */
+  apiPath?: string;
+  /** Show Powered by Respectify branding (default: true) */
+  showBranding?: boolean;
+  /** Enable admin delete controls when authenticated (default: false) */
+  enableDelete?: boolean;
+  /** Optional CSS class on the root wrapper */
+  class?: string;
+  /** Inline styles (e.g. CSS variable overrides) */
+  style?: string;
+}
+
+const {
+  postSlug,
+  apiPath = '/api/respectify/comments',
+  showBranding = true,
+  enableDelete = false,
+  class: className,
+  style,
+} = Astro.props;
+---
+
+<div class:list={['rf-comments', className]} style={style}>
+  {showBranding && <PoweredByRespectify variant="callout" />}
+  <CommentList postSlug={postSlug} apiPath={apiPath} enableDelete={enableDelete} />
+  <CommentForm postSlug={postSlug} />
+  {showBranding && (
+    <div style="display: flex; justify-content: flex-end;">
+      <PoweredByRespectify variant="badge" />
+    </div>
+  )}
+</div>

package/components/PoweredByRespectify.astro

@@ -0,0 +1,42 @@
+---
+interface Props {
+  variant?: 'badge' | 'callout';
+}
+
+const { variant = 'callout' } = Astro.props;
+
+const respectifyUrl = 'https://respectify.ai';
+const demoUrl = 'https://demo.respectify.ai';
+---
+
+{
+  variant === 'callout' ? (
+    <div class="rf-comments__brand">
+      <div class="rf-comments__brand-inner">
+        <div>
+          <p class="rf-comments__brand-title">
+            <a href={respectifyUrl} rel="noopener noreferrer" target="_blank">
+              <svg aria-hidden="true" fill="none" height="16" stroke="currentColor" stroke-width="2" viewBox="0 0 24 24" width="16" xmlns="http://www.w3.org/2000/svg">
+                <path d="M9 12.75 11.25 15 15 9.75m-3-7.036A11.959 11.959 0 0 1 3.598 6 11.99 11.99 0 0 0 3 9.749c0 5.592 3.824 10.29 9 11.623 5.176-1.332 9-6.03 9-11.622 0-1.31-.21-2.571-.598-3.751h-.152c-3.196 0-6.1-1.248-8.25-3.285Z" stroke-linecap="round" stroke-linejoin="round" />
+              </svg>
+              Powered by Respectify
+            </a>
+          </p>
+          <p class="rf-comments__brand-desc">
+            Comments are analyzed in real time for spam and respectfulness before they appear. Leave a comment to see Respectify in action.
+          </p>
+        </div>
+        <a class="rf-comments__brand-cta" href={demoUrl} rel="noopener noreferrer" target="_blank">
+          Try the demo →
+        </a>
+      </div>
+    </div>
+  ) : (
+    <a class="rf-comments__brand-badge" href={respectifyUrl} rel="noopener noreferrer" target="_blank">
+      <svg aria-hidden="true" fill="none" height="14" stroke="currentColor" stroke-width="2" viewBox="0 0 24 24" width="14" xmlns="http://www.w3.org/2000/svg">
+        <path d="M9 12.75 11.25 15 15 9.75m-3-7.036A11.959 11.959 0 0 1 3.598 6 11.99 11.99 0 0 0 3 9.749c0 5.592 3.824 10.29 9 11.623 5.176-1.332 9-6.03 9-11.622 0-1.31-.21-2.571-.598-3.751h-.152c-3.196 0-6.1-1.248-8.25-3.285Z" stroke-linecap="round" stroke-linejoin="round" />
+      </svg>
+      Powered by Respectify
+    </a>
+  )
+}