@seriphxyz/core 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,220 @@
+/**
+ * @seriphxyz/core
+ *
+ * Framework-agnostic API client, types, and controllers for Seriph widgets.
+ * Use this package directly or through framework-specific wrappers like @seriphxyz/astro.
+ */
+export declare const DEFAULT_ENDPOINT = "https://seriph.xyz";
+export declare const API_PATH = "/api/v1";
+export interface SeriphConfig {
+    /** Your site key (required) */
+    siteKey: string;
+    /** Base URL of your Seriph instance (default: 'https://seriph.xyz') */
+    endpoint?: string;
+}
+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 FormSubmitResponse {
+    success: boolean;
+    message: string;
+}
+export interface SubscribeResponse {
+    success: boolean;
+    message: string;
+}
+export interface SeriphPost {
+    id: string;
+    title: string;
+    slug: string;
+    /** Post content as Markdown */
+    content: string;
+    /** Raw TipTap/ProseMirror JSON content (for custom rendering) */
+    contentJson?: string;
+    excerpt?: string;
+    coverImage?: string;
+    metaTitle?: string;
+    metaDescription?: string;
+    tags: string[];
+    publishedAt: string;
+}
+/** Build full API URL from endpoint and path */
+export declare function buildUrl(endpoint: string | undefined, path: string): string;
+/** Get site key from config */
+export declare function getSiteKey(config: SeriphConfig): string;
+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 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;
+}>;
+export interface RemoveReactionOptions extends SeriphConfig {
+    pageId: string;
+    reactionType?: string;
+}
+export declare function removeReaction(options: RemoveReactionOptions): Promise<{
+    reactionType: string;
+    count: number;
+}>;
+export interface SubscribeOptions extends SeriphConfig {
+    email: string;
+}
+export declare function subscribe(options: SubscribeOptions): Promise<SubscribeResponse>;
+export interface FetchPostsOptions extends SeriphConfig {
+    /** Filter posts by tag */
+    tag?: string;
+    /** Maximum number of posts to fetch (default: 500) */
+    limit?: number;
+}
+export declare function fetchPosts(options: FetchPostsOptions): Promise<SeriphPost[]>;
+export interface FetchPostOptions extends SeriphConfig {
+    /** The post slug to fetch */
+    slug: string;
+}
+export declare function fetchPost(options: FetchPostOptions): Promise<SeriphPost | null>;
+export type ControllerStatus = "idle" | "loading" | "success" | "error";
+/** State for subscribe controllers */
+export interface SubscribeState {
+    status: ControllerStatus;
+    message: string | null;
+    error: Error | null;
+}
+/** State for form controllers */
+export interface FormState {
+    status: ControllerStatus;
+    message: string | null;
+    error: Error | null;
+}
+/** State for reactions controllers */
+export interface ReactionsState {
+    counts: Record<string, number>;
+    userReactions: string[];
+    status: ControllerStatus;
+    error: Error | null;
+}
+/** State for comments controllers */
+export interface CommentsState {
+    comments: Comment[];
+    status: ControllerStatus;
+    error: Error | null;
+}
+export interface ControllerListener<T> {
+    (state: T): void;
+}
+/**
+ * Headless controller for subscribe forms.
+ * Manages state without any DOM/framework dependencies.
+ *
+ * @example
+ * const controller = new SubscribeController({ siteKey: 'xxx' });
+ * controller.subscribe((state) => {
+ *   console.log(state.status, state.message, state.error);
+ * });
+ * await controller.submit('user@example.com');
+ */
+export declare class SubscribeController {
+    private config;
+    private listeners;
+    private _state;
+    constructor(config: SeriphConfig);
+    /** Get current state */
+    getState(): SubscribeState;
+    /** Subscribe to state changes */
+    subscribe(listener: ControllerListener<SubscribeState>): () => void;
+    private notify;
+    /** Submit email for subscription */
+    submit(email: string): Promise<SubscribeResponse>;
+    /** Reset to idle state */
+    reset(): void;
+}
+/**
+ * Headless controller for forms.
+ * Manages state without any DOM/framework dependencies.
+ */
+export declare class FormController {
+    private config;
+    private formSlug;
+    private listeners;
+    private loadTime;
+    private _state;
+    constructor(config: SeriphConfig, formSlug: string);
+    getState(): FormState;
+    subscribe(listener: ControllerListener<FormState>): () => void;
+    private notify;
+    submit(data: Record<string, unknown>): Promise<FormSubmitResponse>;
+    reset(): void;
+}
+/**
+ * Headless controller for reactions.
+ * Manages state and counts without any DOM/framework dependencies.
+ */
+export declare class ReactionsController {
+    private config;
+    private pageId;
+    private listeners;
+    private _state;
+    constructor(config: SeriphConfig, pageId: string);
+    getState(): ReactionsState;
+    subscribe(listener: ControllerListener<ReactionsState>): () => void;
+    private notify;
+    /** Fetch reactions from the server */
+    fetch(): Promise<ReactionsState>;
+    add(reactionType?: string): Promise<void>;
+    remove(reactionType?: string): Promise<void>;
+}
+/**
+ * Headless controller for comments.
+ * Manages state and comment list without any DOM/framework dependencies.
+ */
+export declare class CommentsController {
+    private config;
+    private pageId;
+    private listeners;
+    private _state;
+    constructor(config: SeriphConfig, pageId: string);
+    getState(): CommentsState;
+    subscribe(listener: ControllerListener<CommentsState>): () => void;
+    private notify;
+    /** Fetch comments from the server */
+    fetch(): Promise<Comment[]>;
+    post(authorName: string, content: string, options?: {
+        authorEmail?: string;
+        parentId?: string;
+    }): Promise<Comment>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,446 @@
+/**
+ * @seriphxyz/core
+ *
+ * Framework-agnostic API client, types, and controllers for Seriph widgets.
+ * Use this package directly or through framework-specific wrappers like @seriphxyz/astro.
+ */
+// =============================================================================
+// Constants
+// =============================================================================
+export const DEFAULT_ENDPOINT = "https://seriph.xyz";
+export const API_PATH = "/api/v1";
+// =============================================================================
+// Helpers
+// =============================================================================
+/** Build full API URL from endpoint and path */
+export function buildUrl(endpoint, path) {
+    const base = (endpoint || DEFAULT_ENDPOINT).replace(/\/+$/, "");
+    return `${base}${API_PATH}${path}`;
+}
+/** Get site key from config */
+export function getSiteKey(config) {
+    if (!config.siteKey) {
+        throw new Error("siteKey is required");
+    }
+    return config.siteKey;
+}
+export async function submitForm(options) {
+    const { endpoint, formSlug, data, formLoadTime } = options;
+    const siteKey = getSiteKey(options);
+    const url = buildUrl(endpoint, `/forms/${formSlug}/submit`);
+    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, authorName, authorEmail, content, parentId } = 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,
+            authorEmail,
+            content,
+            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;
+}
+export async function removeReaction(options) {
+    const { endpoint, pageId, reactionType = "like" } = options;
+    const siteKey = getSiteKey(options);
+    const url = buildUrl(endpoint, `/reactions/${encodeURIComponent(pageId)}`);
+    const response = await fetch(url, {
+        method: "DELETE",
+        headers: {
+            "Content-Type": "application/json",
+            "X-Seriph-Key": siteKey,
+        },
+        body: JSON.stringify({ reactionType }),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to remove reaction: ${response.statusText}`);
+    }
+    const data = await response.json();
+    return data.data;
+}
+export async function subscribe(options) {
+    const { endpoint, email } = options;
+    const siteKey = getSiteKey(options);
+    const url = buildUrl(endpoint, "/subscribe");
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "X-Seriph-Key": siteKey,
+        },
+        body: JSON.stringify({ email }),
+    });
+    if (!response.ok) {
+        throw new Error(`Subscription failed: ${response.statusText}`);
+    }
+    return response.json();
+}
+export async function fetchPosts(options) {
+    const { endpoint, tag, limit = 500 } = options;
+    const siteKey = getSiteKey(options);
+    const baseUrl = (endpoint || DEFAULT_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;
+}
+export async function fetchPost(options) {
+    const { endpoint, slug } = options;
+    const siteKey = getSiteKey(options);
+    const baseUrl = (endpoint || DEFAULT_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;
+}
+/**
+ * Headless controller for subscribe forms.
+ * Manages state without any DOM/framework dependencies.
+ *
+ * @example
+ * const controller = new SubscribeController({ siteKey: 'xxx' });
+ * controller.subscribe((state) => {
+ *   console.log(state.status, state.message, state.error);
+ * });
+ * await controller.submit('user@example.com');
+ */
+export class SubscribeController {
+    config;
+    listeners = new Set();
+    _state = { status: "idle", message: null, error: null };
+    constructor(config) {
+        this.config = config;
+    }
+    /** Get current state */
+    getState() {
+        return { ...this._state };
+    }
+    /** Subscribe to state changes */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        // Immediately call with current state
+        listener(this.getState());
+        return () => this.listeners.delete(listener);
+    }
+    notify() {
+        const state = this.getState();
+        for (const listener of this.listeners) {
+            listener(state);
+        }
+    }
+    /** Submit email for subscription */
+    async submit(email) {
+        this._state = { status: "loading", message: null, error: null };
+        this.notify();
+        try {
+            const result = await subscribe({ ...this.config, email });
+            this._state = { status: "success", message: result.message, error: null };
+            this.notify();
+            return result;
+        }
+        catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            this._state = { status: "error", message: error.message, error };
+            this.notify();
+            throw error;
+        }
+    }
+    /** Reset to idle state */
+    reset() {
+        this._state = { status: "idle", message: null, error: null };
+        this.notify();
+    }
+}
+/**
+ * Headless controller for forms.
+ * Manages state without any DOM/framework dependencies.
+ */
+export class FormController {
+    config;
+    formSlug;
+    listeners = new Set();
+    loadTime;
+    _state = { status: "idle", message: null, error: null };
+    constructor(config, formSlug) {
+        this.config = config;
+        this.formSlug = formSlug;
+        this.loadTime = Math.floor(Date.now() / 1000);
+    }
+    getState() {
+        return { ...this._state };
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        listener(this.getState());
+        return () => this.listeners.delete(listener);
+    }
+    notify() {
+        const state = this.getState();
+        for (const listener of this.listeners) {
+            listener(state);
+        }
+    }
+    async submit(data) {
+        this._state = { status: "loading", message: null, error: null };
+        this.notify();
+        try {
+            const result = await submitForm({
+                ...this.config,
+                formSlug: this.formSlug,
+                data,
+                formLoadTime: this.loadTime,
+            });
+            this._state = { status: "success", message: result.message, error: null };
+            this.notify();
+            return result;
+        }
+        catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            this._state = { status: "error", message: error.message, error };
+            this.notify();
+            throw error;
+        }
+    }
+    reset() {
+        this._state = { status: "idle", message: null, error: null };
+        this.loadTime = Math.floor(Date.now() / 1000);
+        this.notify();
+    }
+}
+/**
+ * Headless controller for reactions.
+ * Manages state and counts without any DOM/framework dependencies.
+ */
+export class ReactionsController {
+    config;
+    pageId;
+    listeners = new Set();
+    _state = { counts: {}, userReactions: [], status: "idle", error: null };
+    constructor(config, pageId) {
+        this.config = config;
+        this.pageId = pageId;
+    }
+    getState() {
+        return { ...this._state, counts: { ...this._state.counts }, userReactions: [...this._state.userReactions] };
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        listener(this.getState());
+        return () => this.listeners.delete(listener);
+    }
+    notify() {
+        const state = this.getState();
+        for (const listener of this.listeners) {
+            listener(state);
+        }
+    }
+    /** Fetch reactions from the server */
+    async fetch() {
+        this._state = { ...this._state, status: "loading", error: null };
+        this.notify();
+        try {
+            const result = await fetchReactions({ ...this.config, pageId: this.pageId });
+            this._state = { ...this._state, counts: result.counts, status: "success", error: null };
+            this.notify();
+            return this.getState();
+        }
+        catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            this._state = { ...this._state, status: "error", error };
+            this.notify();
+            throw error;
+        }
+    }
+    async add(reactionType = "like") {
+        try {
+            const result = await addReaction({ ...this.config, pageId: this.pageId, reactionType });
+            this._state.counts[reactionType] = result.count;
+            if (!this._state.userReactions.includes(reactionType)) {
+                this._state.userReactions = [...this._state.userReactions, reactionType];
+            }
+            this.notify();
+        }
+        catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            this._state = { ...this._state, error };
+            this.notify();
+            throw error;
+        }
+    }
+    async remove(reactionType = "like") {
+        try {
+            const result = await removeReaction({ ...this.config, pageId: this.pageId, reactionType });
+            this._state.counts[reactionType] = result.count;
+            this._state.userReactions = this._state.userReactions.filter(r => r !== reactionType);
+            this.notify();
+        }
+        catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            this._state = { ...this._state, error };
+            this.notify();
+            throw error;
+        }
+    }
+}
+/**
+ * Headless controller for comments.
+ * Manages state and comment list without any DOM/framework dependencies.
+ */
+export class CommentsController {
+    config;
+    pageId;
+    listeners = new Set();
+    _state = { comments: [], status: "idle", error: null };
+    constructor(config, pageId) {
+        this.config = config;
+        this.pageId = pageId;
+    }
+    getState() {
+        return { ...this._state, comments: [...this._state.comments] };
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        listener(this.getState());
+        return () => this.listeners.delete(listener);
+    }
+    notify() {
+        const state = this.getState();
+        for (const listener of this.listeners) {
+            listener(state);
+        }
+    }
+    /** Fetch comments from the server */
+    async fetch() {
+        this._state = { ...this._state, status: "loading", error: null };
+        this.notify();
+        try {
+            const comments = await fetchComments({ ...this.config, pageId: this.pageId });
+            this._state = { comments, status: "success", error: null };
+            this.notify();
+            return comments;
+        }
+        catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            this._state = { ...this._state, status: "error", error };
+            this.notify();
+            throw error;
+        }
+    }
+    async post(authorName, content, options) {
+        try {
+            const comment = await postComment({
+                ...this.config,
+                pageId: this.pageId,
+                authorName,
+                content,
+                authorEmail: options?.authorEmail,
+                parentId: options?.parentId,
+            });
+            // Reload to get updated tree structure
+            await this.fetch();
+            return comment;
+        }
+        catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            this._state = { ...this._state, error };
+            this.notify();
+            throw error;
+        }
+    }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@seriphxyz/core",
+  "version": "0.1.2",
+  "description": "Framework-agnostic API client and types for Seriph widgets",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seriphxyz/core.git"
+  },
+  "homepage": "https://seriph.xyz",
+  "author": "Tim Shedor",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "seriph",
+    "api",
+    "forms",
+    "comments",
+    "reactions",
+    "subscribe",
+    "widgets"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.7.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  }
+}