@seriphxyz/astro 0.1.2

package/src/loader.ts

@@ -0,0 +1,264 @@
+/**
+ * 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";
+
+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;
+}
+
+interface ApiResponse {
+  posts: Array<{
+    id: string;
+    title: string;
+    slug: string;
+    content: string;
+    excerpt?: string;
+    coverImage?: string;
+    metaTitle?: string;
+    metaDescription?: string;
+    tags: string[];
+    publishedAt: string;
+  }>;
+  total: number;
+}
+
+// Helper to get site key (supports both siteKey and deprecated apiKey)
+function getSiteKey(options: SeriphPostsLoaderOptions): string {
+  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: SeriphPostsLoaderOptions) {
+  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: LoaderContext) {
+      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: ApiResponse = 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;
+
+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 async function fetchPosts(options: FetchPostsOptions): Promise<SeriphPost[]> {
+  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: ApiResponse = await response.json();
+  return data.posts;
+}
+
+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 async function fetchPost(options: FetchPostOptions): Promise<SeriphPost | null> {
+  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;
+}