@jamwidgets/astro 0.1.0

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,250 @@
+# @jamwidgets/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 [JamWidgets](https://jamwidgets.com) - widgets for static sites.
+
+## Installation
+
+```bash
+npm install @jamwidgets/astro
+```
+
+## Setup
+
+Add your JamWidgets site key to your `.env`:
+
+```
+JAMWIDGETS_SITE_KEY=your_site_key_here
+```
+
+## Content Loader (Posts)
+
+Fetch posts from JamWidgets at build time using Astro's content collections:
+
+```ts
+// src/content.config.ts
+import { defineCollection } from "astro:content";
+import { jamwidgetsPostsLoader } from "@jamwidgets/astro/loader";
+
+const posts = defineCollection({
+  loader: jamwidgetsPostsLoader({
+    siteKey: import.meta.env.JAMWIDGETS_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
+jamwidgetsPostsLoader({
+  siteKey: string;        // Required - your JamWidgets site key
+  endpoint?: string;      // Default: 'https://jamwidgets.com'
+  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 "@jamwidgets/astro/Form";
+---
+
+<Form siteKey={import.meta.env.JAMWIDGETS_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 JamWidgets site key
+- `formSlug` (required) - The form slug as configured in JamWidgets
+- `endpoint` - Base URL (default: `https://jamwidgets.com`)
+- `theme` - `'light'` | `'dark'` | `'auto'` (default: `'light'`)
+- `class` - Additional CSS class
+
+**Events:**
+- `jamwidgets:loading` - Form submission started
+- `jamwidgets:success` - Submission successful (detail contains response)
+- `jamwidgets:error` - Submission failed (detail contains error)
+
+### Comments
+
+Threaded comments with a submission form:
+
+```astro
+---
+import Comments from "@jamwidgets/astro/Comments";
+---
+
+<Comments
+  siteKey={import.meta.env.JAMWIDGETS_SITE_KEY}
+  pageId={Astro.url.pathname}
+/>
+```
+
+**Props:**
+- `siteKey` (required) - Your JamWidgets site key
+- `pageId` (required) - Unique page identifier (e.g., URL path)
+- `endpoint` - Base URL (default: `https://jamwidgets.com`)
+- `theme` - `'light'` | `'dark'` | `'auto'` (default: `'light'`)
+- `class` - Additional CSS class
+
+**Events:**
+- `jamwidgets:comment-posted` - Comment submitted (detail contains comment)
+
+### Reactions
+
+Reaction buttons (like, love, clap, etc.):
+
+```astro
+---
+import Reactions from "@jamwidgets/astro/Reactions";
+---
+
+<Reactions
+  siteKey={import.meta.env.JAMWIDGETS_SITE_KEY}
+  pageId={Astro.url.pathname}
+  reactions={["like", "love", "clap"]}
+/>
+```
+
+**Props:**
+- `siteKey` (required) - Your JamWidgets site key
+- `pageId` (required) - Unique page identifier
+- `reactions` - Array of reaction types (default: `['like']`)
+- `icons` - Custom icons: `{ like: '👍', love: '❤️' }`
+- `endpoint` - Base URL (default: `https://jamwidgets.com`)
+- `theme` - `'light'` | `'dark'` | `'auto'` (default: `'light'`)
+- `class` - Additional CSS class
+
+**Built-in icons:** `like`, `love`, `clap`, `fire`, `think`, `sad`, `laugh`
+
+**Events:**
+- `jamwidgets:reaction-added` - Reaction added
+- `jamwidgets:reaction-removed` - Reaction removed
+
+### Subscribe
+
+Email subscription form with double opt-in:
+
+```astro
+---
+import Subscribe from "@jamwidgets/astro/Subscribe";
+---
+
+<Subscribe
+  siteKey={import.meta.env.JAMWIDGETS_SITE_KEY}
+  buttonText="Subscribe"
+  placeholder="your@email.com"
+/>
+```
+
+**Props:**
+- `siteKey` (required) - Your JamWidgets site key
+- `endpoint` - Base URL (default: `https://jamwidgets.com`)
+- `buttonText` - Submit button text (default: `'Subscribe'`)
+- `placeholder` - Email input placeholder
+- `successMessage` - Custom success message
+- `theme` - `'light'` | `'dark'` | `'auto'` (default: `'light'`)
+- `class` - Additional CSS class
+
+**Events:**
+- `jamwidgets:subscribed` - Subscription successful
+
+### SubscribeForm
+
+A more flexible subscription form that wraps your own markup:
+
+```astro
+---
+import SubscribeForm from "@jamwidgets/astro/SubscribeForm";
+---
+
+<SubscribeForm siteKey={import.meta.env.JAMWIDGETS_SITE_KEY}>
+  <input name="email" type="email" placeholder="Email" required />
+  <button type="submit">Join newsletter</button>
+</SubscribeForm>
+```
+
+## JavaScript API
+
+For advanced use cases, use the JavaScript API directly:
+
+```ts
+import {
+  submitForm,
+  fetchComments,
+  postComment,
+  fetchReactions,
+  addReaction,
+  fetchPosts,
+  fetchPost,
+} from "@jamwidgets/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
+.jamwidgets-comments {
+  --jamwidgets-border-color: #e5e7eb;
+  --jamwidgets-bg-color: #f9fafb;
+  --jamwidgets-text-color: inherit;
+  --jamwidgets-button-bg: #3b82f6;
+  /* ... see component source for all variables */
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @jamwidgets/astro
+ *
+ * Astro components and content loader for Jamwidgets.
+ * Re-exports all types, API functions, and controllers from @jamwidgets/core.
+ */
+export { DEFAULT_ENDPOINT, API_PATH, VISITOR_STORAGE_KEY, type JamWidgetsConfig, type SeriphConfig, // deprecated alias
+type Comment, type ReactionCounts, type FormSubmitResponse, type SubscribeResponse, type JamwidgetsPost, type SeriphPost, // deprecated alias
+type Announcement, type AnnouncementType, type Poll, type PollOption, type PollSettings, type PollWithResults, type ShowResultsMode, type FeedbackType, buildUrl, getSiteKey, getVisitorId, setVisitorId, type SubmitFormOptions, submitForm, type FetchCommentsOptions, fetchComments, type PostCommentOptions, postComment, type FetchReactionsOptions, type FetchReactionsResponse, fetchReactions, type AddReactionOptions, addReaction, type RemoveReactionOptions, removeReaction, type SubscribeOptions, subscribe, type JoinWaitlistOptions, type JoinWaitlistResponse, joinWaitlist, type ViewCountsOptions, type ViewCounts, type RecordViewResponse, getViewCounts, recordView, type SubmitFeedbackOptions, type SubmitFeedbackResponse, submitFeedback, type FetchPollOptions, fetchPoll, type VotePollOptions, type VotePollResponse, votePoll, type FetchAnnouncementsOptions, fetchAnnouncements, type DismissAnnouncementOptions, dismissAnnouncement, type FetchPostsOptions, fetchPosts, type FetchPostOptions, fetchPost, type ControllerStatus, type ControllerListener, type SubscribeState, type FormState, type ReactionsState, type CommentsState, type WaitlistState, type ViewCountsState, type FeedbackState, type PollState, type AnnouncementsState, SubscribeController, WaitlistController, FormController, ReactionsController, CommentsController, ViewCountsController, FeedbackController, PollController, AnnouncementsController, } from "@jamwidgets/core";
+export { jamwidgetsPostsLoader, seriphPostsLoader, // deprecated alias
+type JamwidgetsPostsLoaderOptions, type SeriphPostsLoaderOptions, } from "./loader.js";

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * @jamwidgets/astro
+ *
+ * Astro components and content loader for Jamwidgets.
+ * Re-exports all types, API functions, and controllers from @jamwidgets/core.
+ */
+// Re-export everything from core
+export { 
+// Constants
+DEFAULT_ENDPOINT, API_PATH, VISITOR_STORAGE_KEY, 
+// Helpers
+buildUrl, getSiteKey, getVisitorId, setVisitorId, submitForm, fetchComments, postComment, fetchReactions, addReaction, removeReaction, subscribe, joinWaitlist, getViewCounts, recordView, submitFeedback, fetchPoll, votePoll, fetchAnnouncements, dismissAnnouncement, fetchPosts, fetchPost, SubscribeController, WaitlistController, FormController, ReactionsController, CommentsController, ViewCountsController, FeedbackController, PollController, AnnouncementsController, } from "@jamwidgets/core";
+// Re-export loader (Astro-specific)
+export { jamwidgetsPostsLoader, seriphPostsLoader, // deprecated alias
+ } from "./loader.js";

package/dist/loader.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Astro Content Loader for Jamwidgets Posts
+ *
+ * Use this loader to fetch posts from your Jamwidgets instance at build time.
+ *
+ * @example
+ * // In src/content.config.ts
+ * import { defineCollection } from 'astro:content';
+ * import { jamwidgetsPostsLoader } from '@jamwidgets/astro/loader';
+ *
+ * const posts = defineCollection({
+ *   loader: jamwidgetsPostsLoader({
+ *     siteKey: import.meta.env.JAMWIDGETS_SITE_KEY,
+ *   }),
+ * });
+ *
+ * export const collections = { posts };
+ */
+import { fetchPosts as coreFetchPosts, fetchPost as coreFetchPost, type JamwidgetsPost, type SeriphPost, // deprecated alias
+type FetchPostsOptions, type FetchPostOptions } from "@jamwidgets/core";
+export type { JamwidgetsPost, SeriphPost, FetchPostsOptions, FetchPostOptions };
+export { coreFetchPosts as fetchPosts, coreFetchPost as fetchPost };
+export interface JamwidgetsPostsLoaderOptions {
+    /** Your site key (required) */
+    siteKey: string;
+    /** Base URL of your Jamwidgets instance (default: 'https://jamwidgets.com') */
+    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 JamwidgetsPostsLoaderOptions instead */
+export type SeriphPostsLoaderOptions = JamwidgetsPostsLoaderOptions;
+interface LoaderContext {
+    store: {
+        set: (entry: {
+            id: string;
+            data: JamwidgetsPost;
+        }) => 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 Jamwidgets.
+ *
+ * Posts are fetched at build time and cached by Astro.
+ */
+export declare function jamwidgetsPostsLoader(options: JamwidgetsPostsLoaderOptions): {
+    name: string;
+    load(context: LoaderContext): Promise<void>;
+};
+/** @deprecated Use jamwidgetsPostsLoader instead */
+export declare const seriphPostsLoader: typeof jamwidgetsPostsLoader;

package/dist/loader.js

@@ -0,0 +1,74 @@
+/**
+ * Astro Content Loader for Jamwidgets Posts
+ *
+ * Use this loader to fetch posts from your Jamwidgets instance at build time.
+ *
+ * @example
+ * // In src/content.config.ts
+ * import { defineCollection } from 'astro:content';
+ * import { jamwidgetsPostsLoader } from '@jamwidgets/astro/loader';
+ *
+ * const posts = defineCollection({
+ *   loader: jamwidgetsPostsLoader({
+ *     siteKey: import.meta.env.JAMWIDGETS_SITE_KEY,
+ *   }),
+ * });
+ *
+ * export const collections = { posts };
+ */
+import { DEFAULT_ENDPOINT, API_PATH, getSiteKey, fetchPosts as coreFetchPosts, fetchPost as coreFetchPost, } from "@jamwidgets/core";
+export { coreFetchPosts as fetchPosts, coreFetchPost as fetchPost };
+/**
+ * Creates an Astro content loader that fetches posts from Jamwidgets.
+ *
+ * Posts are fetched at build time and cached by Astro.
+ */
+export function jamwidgetsPostsLoader(options) {
+    const { endpoint = DEFAULT_ENDPOINT, tag, limit = 500, onError = "throw", } = options;
+    const siteKey = getSiteKey({ siteKey: options.siteKey });
+    const baseUrl = endpoint.replace(/\/+$/, "") + API_PATH;
+    return {
+        name: "jamwidgets-posts-loader",
+        async load(context) {
+            const { store, logger } = context;
+            try {
+                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-Jamwidgets-Key": siteKey,
+                        "X-JamWidgets-Key": siteKey, // backward compat
+                    },
+                });
+                if (!response.ok) {
+                    throw new Error(`Failed to fetch posts: ${response.status} ${response.statusText}`);
+                }
+                const data = await response.json();
+                store.clear();
+                for (const post of data.posts) {
+                    store.set({
+                        id: post.slug,
+                        data: post,
+                    });
+                }
+                logger.info(`Loaded ${data.posts.length} posts from Jamwidgets`);
+            }
+            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}`);
+                }
+            }
+        },
+    };
+}
+/** @deprecated Use jamwidgetsPostsLoader instead */
+export const seriphPostsLoader = jamwidgetsPostsLoader;

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@jamwidgets/astro",
+  "version": "0.1.0",
+  "description": "Astro components and content loader for Jamwidgets (forms, comments, reactions, posts)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jamwidgets/astro.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://jamwidgets.com",
+  "author": "Tim Marks <tim@imothee.xyz>",
+  "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",
+    "./Views": "./src/Views.astro",
+    "./Poll": "./src/Poll.astro",
+    "./Subscribe": "./src/Subscribe.astro",
+    "./SubscribeForm": "./src/SubscribeForm.astro",
+    "./Announcements": "./src/Announcements.astro",
+    "./Feedback": "./src/Feedback.astro",
+    "./Waitlist": "./src/Waitlist.astro",
+    "./Embed": "./src/Embed.astro"
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "keywords": [
+    "astro",
+    "jamwidgets",
+    "forms",
+    "comments",
+    "reactions",
+    "posts",
+    "widgets",
+    "content-loader",
+    "subscribe"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@jamwidgets/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "astro": "^5.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  }
+}