@seriphxyz/astro 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Tim Shedor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# @seriphxyz/astro
+
+> **Note:** This repo is a read-only mirror. Source lives in a private monorepo.
+> For issues/PRs, please open them here and we'll sync changes back.
+
+Astro components and content loader for [Seriph](https://seriph.xyz) - widgets for static sites.
+
+## Installation
+
+```bash
+npm install @seriphxyz/astro
+```
+
+## Setup
+
+Add your Seriph site key to your `.env`:
+
+```
+SERIPH_SITE_KEY=your_site_key_here
+```
+
+## Content Loader (Posts)
+
+Fetch posts from Seriph at build time using Astro's content collections:
+
+```ts
+// src/content.config.ts
+import { defineCollection } from "astro:content";
+import { seriphPostsLoader } from "@seriphxyz/astro/loader";
+
+const posts = defineCollection({
+  loader: seriphPostsLoader({
+    siteKey: import.meta.env.SERIPH_SITE_KEY,
+  }),
+});
+
+export const collections = { posts };
+```
+
+Then use in your pages:
+
+```astro
+---
+import { getCollection } from "astro:content";
+const posts = await getCollection("posts");
+---
+
+{posts.map((post) => (
+  <article>
+    <h2>{post.data.title}</h2>
+    <p>{post.data.excerpt}</p>
+  </article>
+))}
+```
+
+### Loader Options
+
+```ts
+seriphPostsLoader({
+  siteKey: string;        // Required - your Seriph site key
+  endpoint?: string;      // Default: 'https://seriph.xyz'
+  tag?: string;           // Filter posts by tag
+  limit?: number;         // Max posts to fetch (default: 500)
+  onError?: 'throw' | 'warn' | 'ignore';  // Error handling
+})
+```
+
+## Components
+
+### Form
+
+A wrapper component for contact forms with built-in spam protection:
+
+```astro
+---
+import Form from "@seriphxyz/astro/Form";
+---
+
+<Form siteKey={import.meta.env.SERIPH_SITE_KEY} formSlug="contact">
+  <input name="name" placeholder="Name" required />
+  <input name="email" type="email" placeholder="Email" required />
+  <textarea name="message" placeholder="Message" required></textarea>
+  <button type="submit">Send</button>
+</Form>
+```
+
+**Props:**
+- `siteKey` (required) - Your Seriph site key
+- `formSlug` (required) - The form slug as configured in Seriph
+- `endpoint` - Base URL (default: `https://seriph.xyz`)
+- `theme` - `'light'` | `'dark'` | `'auto'` (default: `'light'`)
+- `class` - Additional CSS class
+
+**Events:**
+- `seriph:loading` - Form submission started
+- `seriph:success` - Submission successful (detail contains response)
+- `seriph:error` - Submission failed (detail contains error)
+
+### Comments
+
+Threaded comments with a submission form:
+
+```astro
+---
+import Comments from "@seriphxyz/astro/Comments";
+---
+
+<Comments
+  siteKey={import.meta.env.SERIPH_SITE_KEY}
+  pageId={Astro.url.pathname}
+/>
+```
+
+**Props:**
+- `siteKey` (required) - Your Seriph site key
+- `pageId` (required) - Unique page identifier (e.g., URL path)
+- `endpoint` - Base URL (default: `https://seriph.xyz`)
+- `theme` - `'light'` | `'dark'` | `'auto'` (default: `'light'`)
+- `class` - Additional CSS class
+
+**Events:**
+- `seriph:comment-posted` - Comment submitted (detail contains comment)
+
+### Reactions
+
+Reaction buttons (like, love, clap, etc.):
+
+```astro
+---
+import Reactions from "@seriphxyz/astro/Reactions";
+---
+
+<Reactions
+  siteKey={import.meta.env.SERIPH_SITE_KEY}
+  pageId={Astro.url.pathname}
+  reactions={["like", "love", "clap"]}
+/>
+```
+
+**Props:**
+- `siteKey` (required) - Your Seriph site key
+- `pageId` (required) - Unique page identifier
+- `reactions` - Array of reaction types (default: `['like']`)
+- `icons` - Custom icons: `{ like: '👍', love: '❤️' }`
+- `endpoint` - Base URL (default: `https://seriph.xyz`)
+- `theme` - `'light'` | `'dark'` | `'auto'` (default: `'light'`)
+- `class` - Additional CSS class
+
+**Built-in icons:** `like`, `love`, `clap`, `fire`, `think`, `sad`, `laugh`
+
+**Events:**
+- `seriph:reaction-added` - Reaction added
+- `seriph:reaction-removed` - Reaction removed
+
+## JavaScript API
+
+For advanced use cases, use the JavaScript API directly:
+
+```ts
+import {
+  submitForm,
+  fetchComments,
+  postComment,
+  fetchReactions,
+  addReaction,
+  fetchPosts,
+  fetchPost,
+} from "@seriphxyz/astro";
+
+// Submit a form
+await submitForm({
+  siteKey: "your_key",
+  formSlug: "contact",
+  data: { name: "John", email: "john@example.com", message: "Hello!" },
+});
+
+// Fetch comments
+const comments = await fetchComments({
+  siteKey: "your_key",
+  pageId: "/blog/my-post",
+});
+
+// Add a reaction
+await addReaction({
+  siteKey: "your_key",
+  pageId: "/blog/my-post",
+  reactionType: "like",
+});
+```
+
+## Styling
+
+Components use CSS custom properties for theming. Override them to match your site:
+
+```css
+.seriph-comments {
+  --seriph-border-color: #e5e7eb;
+  --seriph-bg-color: #f9fafb;
+  --seriph-text-color: inherit;
+  --seriph-button-bg: #3b82f6;
+  /* ... see component source for all variables */
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+export interface SeriphConfig {
+    /** Your site key (required) */
+    siteKey: string;
+    /** @deprecated Use siteKey instead */
+    apiKey?: string;
+    /** Base URL of your Seriph instance (default: 'https://seriph.xyz') */
+    endpoint?: string;
+}
+/** @deprecated Use SeriphConfig instead */
+export type SeraphConfig = SeriphConfig;
+export { seriphPostsLoader, seraphPostsLoader, fetchPosts, fetchPost, type SeriphPost, type SeraphPost, type SeriphPostsLoaderOptions, type SeraphPostsLoaderOptions, type FetchPostsOptions, type FetchPostOptions, } from "./loader.js";
+export interface FormSubmitOptions {
+    onSuccess?: (data: unknown) => void;
+    onError?: (error: Error) => void;
+}
+export interface Comment {
+    id: string;
+    pageId: string;
+    parentId?: string;
+    authorName: string;
+    content: string;
+    createdAt: string;
+    replies: Comment[];
+}
+export interface ReactionCounts {
+    pageId: string;
+    counts: Record<string, number>;
+}
+export interface SubmitFormOptions extends SeriphConfig {
+    formSlug: string;
+    data: Record<string, unknown>;
+    /** Form load timestamp for spam detection (auto-set if not provided) */
+    formLoadTime?: number;
+}
+export interface FormSubmitResponse {
+    success: boolean;
+    message: string;
+}
+export declare function submitForm(options: SubmitFormOptions): Promise<FormSubmitResponse>;
+export interface FetchCommentsOptions extends SeriphConfig {
+    pageId: string;
+}
+export declare function fetchComments(options: FetchCommentsOptions): Promise<Comment[]>;
+export interface PostCommentOptions extends SeriphConfig {
+    pageId: string;
+    authorName: string;
+    authorEmail?: string;
+    content: string;
+    parentId?: string;
+}
+export declare function postComment(options: PostCommentOptions): Promise<Comment>;
+export interface FetchReactionsOptions extends SeriphConfig {
+    pageId: string;
+}
+export declare function fetchReactions(options: FetchReactionsOptions): Promise<ReactionCounts>;
+export interface AddReactionOptions extends SeriphConfig {
+    pageId: string;
+    reactionType?: string;
+}
+export declare function addReaction(options: AddReactionOptions): Promise<{
+    reactionType: string;
+    count: number;
+}>;

package/dist/index.js

@@ -0,0 +1,111 @@
+const DEFAULT_ENDPOINT = "https://seriph.xyz";
+const API_PATH = "/api/v1";
+// Re-export loader
+export { seriphPostsLoader, seraphPostsLoader, fetchPosts, fetchPost, } from "./loader.js";
+// Helper to build API URL
+function buildUrl(endpoint, path) {
+    const base = (endpoint || DEFAULT_ENDPOINT).replace(/\/+$/, "");
+    return `${base}${API_PATH}${path}`;
+}
+// Helper to get site key (supports both siteKey and deprecated apiKey)
+function getSiteKey(config) {
+    const key = config.siteKey || config.apiKey;
+    if (!key) {
+        throw new Error("siteKey is required");
+    }
+    return key;
+}
+// Client utilities
+export async function submitForm(options) {
+    const { endpoint, formSlug, data, formLoadTime } = options;
+    const siteKey = getSiteKey(options);
+    const url = buildUrl(endpoint, `/forms/${formSlug}/submit`);
+    // Include timestamp for time-based spam detection
+    const payload = {
+        ...data,
+        _seriph_ts: formLoadTime || Math.floor(Date.now() / 1000),
+    };
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "X-Seriph-Key": siteKey,
+        },
+        body: JSON.stringify(payload),
+    });
+    if (!response.ok) {
+        throw new Error(`Form submission failed: ${response.statusText}`);
+    }
+    return response.json();
+}
+export async function fetchComments(options) {
+    const { endpoint, pageId } = options;
+    const siteKey = getSiteKey(options);
+    const url = buildUrl(endpoint, `/comments/${encodeURIComponent(pageId)}`);
+    const response = await fetch(url, {
+        headers: {
+            "X-Seriph-Key": siteKey,
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch comments: ${response.statusText}`);
+    }
+    const data = await response.json();
+    return data.data || [];
+}
+export async function postComment(options) {
+    const { endpoint, pageId, ...rest } = options;
+    const siteKey = getSiteKey(options);
+    const url = buildUrl(endpoint, `/comments/${encodeURIComponent(pageId)}`);
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "X-Seriph-Key": siteKey,
+        },
+        body: JSON.stringify({
+            authorName: rest.authorName,
+            authorEmail: rest.authorEmail,
+            content: rest.content,
+            parentId: rest.parentId,
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to post comment: ${response.statusText}`);
+    }
+    const data = await response.json();
+    return data.data;
+}
+export async function fetchReactions(options) {
+    const { endpoint, pageId } = options;
+    const siteKey = getSiteKey(options);
+    const url = buildUrl(endpoint, `/reactions/${encodeURIComponent(pageId)}`);
+    const response = await fetch(url, {
+        headers: {
+            "X-Seriph-Key": siteKey,
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch reactions: ${response.statusText}`);
+    }
+    const data = await response.json();
+    return data.data;
+}
+export async function addReaction(options) {
+    const { endpoint, pageId, reactionType = "like" } = options;
+    const siteKey = getSiteKey(options);
+    const url = buildUrl(endpoint, `/reactions/${encodeURIComponent(pageId)}`);
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "X-Seriph-Key": siteKey,
+        },
+        body: JSON.stringify({ reactionType }),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to add reaction: ${response.statusText}`);
+    }
+    const data = await response.json();
+    return data.data;
+}

package/dist/loader.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Astro Content Loader for Seriph Posts
+ *
+ * Use this loader to fetch posts from your Seriph instance at build time.
+ *
+ * @example
+ * // In src/content.config.ts
+ * import { defineCollection } from 'astro:content';
+ * import { seriphPostsLoader } from 'seriph-astro/loader';
+ *
+ * const posts = defineCollection({
+ *   loader: seriphPostsLoader({
+ *     siteKey: import.meta.env.SERIPH_SITE_KEY,
+ *   }),
+ * });
+ *
+ * export const collections = { posts };
+ */
+export interface SeriphPost {
+    id: string;
+    title: string;
+    slug: string;
+    content: string;
+    excerpt?: string;
+    coverImage?: string;
+    metaTitle?: string;
+    metaDescription?: string;
+    tags: string[];
+    publishedAt: string;
+}
+/** @deprecated Use SeriphPost instead */
+export type SeraphPost = SeriphPost;
+export interface SeriphPostsLoaderOptions {
+    /** Your site key (required) */
+    siteKey?: string;
+    /** @deprecated Use siteKey instead */
+    apiKey?: string;
+    /** Base URL of your Seriph instance (default: 'https://seriph.xyz') */
+    endpoint?: string;
+    /** Filter posts by tag */
+    tag?: string;
+    /** Maximum number of posts to fetch (default: 500) */
+    limit?: number;
+    /** How to handle errors: 'throw' (default), 'warn', or 'ignore' */
+    onError?: "throw" | "warn" | "ignore";
+}
+/** @deprecated Use SeriphPostsLoaderOptions instead */
+export type SeraphPostsLoaderOptions = SeriphPostsLoaderOptions;
+interface LoaderContext {
+    store: {
+        set: (entry: {
+            id: string;
+            data: SeriphPost;
+        }) => void;
+        clear: () => void;
+    };
+    logger: {
+        info: (message: string) => void;
+        warn: (message: string) => void;
+        error: (message: string) => void;
+    };
+    generateDigest: (data: unknown) => string;
+}
+/**
+ * Creates an Astro content loader that fetches posts from Seriph.
+ *
+ * Posts are fetched at build time and cached by Astro.
+ */
+export declare function seriphPostsLoader(options: SeriphPostsLoaderOptions): {
+    name: string;
+    load(context: LoaderContext): Promise<void>;
+};
+/** @deprecated Use seriphPostsLoader instead (note the 'i' in seriph) */
+export declare const seraphPostsLoader: typeof seriphPostsLoader;
+export interface FetchPostsOptions {
+    /** Your site key (required) */
+    siteKey?: string;
+    /** @deprecated Use siteKey instead */
+    apiKey?: string;
+    /** Base URL of your Seriph instance (default: 'https://seriph.xyz') */
+    endpoint?: string;
+    /** Filter posts by tag */
+    tag?: string;
+    /** Maximum number of posts to fetch (default: 500) */
+    limit?: number;
+}
+/**
+ * Utility function to fetch posts directly (for server-side use cases)
+ */
+export declare function fetchPosts(options: FetchPostsOptions): Promise<SeriphPost[]>;
+export interface FetchPostOptions {
+    /** Your site key (required) */
+    siteKey?: string;
+    /** @deprecated Use siteKey instead */
+    apiKey?: string;
+    /** Base URL of your Seriph instance (default: 'https://seriph.xyz') */
+    endpoint?: string;
+    /** The post slug to fetch */
+    slug: string;
+}
+/**
+ * Utility function to fetch a single post by slug
+ */
+export declare function fetchPost(options: FetchPostOptions): Promise<SeriphPost | null>;
+export {};

package/dist/loader.js

@@ -0,0 +1,141 @@
+/**
+ * Astro Content Loader for Seriph Posts
+ *
+ * Use this loader to fetch posts from your Seriph instance at build time.
+ *
+ * @example
+ * // In src/content.config.ts
+ * import { defineCollection } from 'astro:content';
+ * import { seriphPostsLoader } from 'seriph-astro/loader';
+ *
+ * const posts = defineCollection({
+ *   loader: seriphPostsLoader({
+ *     siteKey: import.meta.env.SERIPH_SITE_KEY,
+ *   }),
+ * });
+ *
+ * export const collections = { posts };
+ */
+const DEFAULT_ENDPOINT = "https://seriph.xyz";
+const API_PATH = "/api/v1";
+// Helper to get site key (supports both siteKey and deprecated apiKey)
+function getSiteKey(options) {
+    const key = options.siteKey || options.apiKey;
+    if (!key) {
+        throw new Error("siteKey is required");
+    }
+    return key;
+}
+/**
+ * Creates an Astro content loader that fetches posts from Seriph.
+ *
+ * Posts are fetched at build time and cached by Astro.
+ */
+export function seriphPostsLoader(options) {
+    const { endpoint = DEFAULT_ENDPOINT, tag, limit = 500, onError = "throw", } = options;
+    const siteKey = getSiteKey(options);
+    // Build the base API URL (strip trailing slash, add API path)
+    const baseUrl = endpoint.replace(/\/+$/, "") + API_PATH;
+    return {
+        name: "seriph-posts-loader",
+        async load(context) {
+            const { store, logger } = context;
+            try {
+                // Build the URL with query parameters
+                const url = new URL(`${baseUrl}/posts`);
+                url.searchParams.set("limit", String(limit));
+                if (tag) {
+                    url.searchParams.set("tag", tag);
+                }
+                logger.info(`Fetching posts from ${url.toString()}`);
+                const response = await fetch(url.toString(), {
+                    headers: {
+                        "X-Seriph-Key": siteKey,
+                    },
+                });
+                if (!response.ok) {
+                    throw new Error(`Failed to fetch posts: ${response.status} ${response.statusText}`);
+                }
+                const data = await response.json();
+                // Clear previous entries
+                store.clear();
+                // Add each post as an entry
+                for (const post of data.posts) {
+                    store.set({
+                        id: post.slug,
+                        data: {
+                            id: post.id,
+                            title: post.title,
+                            slug: post.slug,
+                            content: post.content,
+                            excerpt: post.excerpt,
+                            coverImage: post.coverImage,
+                            metaTitle: post.metaTitle,
+                            metaDescription: post.metaDescription,
+                            tags: post.tags,
+                            publishedAt: post.publishedAt,
+                        },
+                    });
+                }
+                logger.info(`Loaded ${data.posts.length} posts from Seriph`);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (onError === "throw") {
+                    logger.error(`Error loading posts: ${message}`);
+                    throw error;
+                }
+                else if (onError === "warn") {
+                    logger.warn(`Error loading posts (continuing anyway): ${message}`);
+                }
+                // onError === "ignore" - silently continue
+            }
+        },
+    };
+}
+/** @deprecated Use seriphPostsLoader instead (note the 'i' in seriph) */
+export const seraphPostsLoader = seriphPostsLoader;
+/**
+ * Utility function to fetch posts directly (for server-side use cases)
+ */
+export async function fetchPosts(options) {
+    const { endpoint = DEFAULT_ENDPOINT, tag, limit = 500 } = options;
+    const siteKey = getSiteKey(options);
+    const baseUrl = endpoint.replace(/\/+$/, "") + API_PATH;
+    const url = new URL(`${baseUrl}/posts`);
+    url.searchParams.set("limit", String(limit));
+    if (tag) {
+        url.searchParams.set("tag", tag);
+    }
+    const response = await fetch(url.toString(), {
+        headers: {
+            "X-Seriph-Key": siteKey,
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch posts: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    return data.posts;
+}
+/**
+ * Utility function to fetch a single post by slug
+ */
+export async function fetchPost(options) {
+    const { endpoint = DEFAULT_ENDPOINT, slug } = options;
+    const siteKey = getSiteKey(options);
+    const baseUrl = endpoint.replace(/\/+$/, "") + API_PATH;
+    const response = await fetch(`${baseUrl}/posts/${encodeURIComponent(slug)}`, {
+        headers: {
+            "X-Seriph-Key": siteKey,
+        },
+    });
+    if (response.status === 404) {
+        return null;
+    }
+    if (!response.ok) {
+        throw new Error(`Failed to fetch post: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    return data.public_post || data;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@seriphxyz/astro",
+  "version": "0.1.2",
+  "description": "Astro components and content loader for Seriph widgets (forms, comments, reactions, posts)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/seriphxyz/astro"
+  },
+  "homepage": "https://seriph.xyz",
+  "author": "Tim Shedor",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./loader": {
+      "types": "./dist/loader.d.ts",
+      "import": "./dist/loader.js"
+    },
+    "./Form": "./src/Form.astro",
+    "./Comments": "./src/Comments.astro",
+    "./Reactions": "./src/Reactions.astro"
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "astro",
+    "seriph",
+    "forms",
+    "comments",
+    "reactions",
+    "posts",
+    "widgets",
+    "content-loader"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "astro": "^5.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3"
+  }
+}