@respectify/astro-moderation 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Respectify
+
+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,94 @@
+# @respectify/astro-moderation
+
+Thin Astro integration for [Respectify](https://respectify.ai) comment moderation.
+
+Respectify does more than just comment moderation — it provides a complete solution for managing and enhancing user-generated content. It monitors for tone, logical fallacies, and spam and educates commenters on how to improve their comments.
+
+Add the integration, set two env vars, then call `moderateComment()` from your own actions or API routes. **No comment UI, no database, no Astro Actions wiring.**
+
+Want hosted Astro comments (UI + DB)? Use [`@respectify/astro`](https://www.npmjs.com/package/@respectify/astro) instead.
+API-only outside Astro? Use [`@respectify/client`](https://www.npmjs.com/package/@respectify/client).
+
+## Install
+
+```bash
+npm install @respectify/astro-moderation @respectify/client
+```
+
+## Setup
+
+```ts
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import respectifyModeration from "@respectify/astro-moderation";
+
+export default defineConfig({
+  integrations: [
+    respectifyModeration({
+      mode: "full", // or "spam-only" | "perspective"
+      toxicityThreshold: 0.7,
+    }),
+  ],
+});
+```
+
+```env
+RESPECTIFY_EMAIL=you@example.com
+RESPECTIFY_API_KEY=your-api-key
+```
+
+## Moderate a comment
+
+```ts
+// e.g. src/pages/api/comments.ts or an Astro Action
+import { moderateComment } from "@respectify/astro-moderation";
+
+const result = await moderateComment({
+  comment: userText,
+  topicUrl: Astro.site ? new URL(`/blog/${slug}`, Astro.site).toString() : undefined,
+});
+
+if (!result.approved) {
+  return { ok: false, feedback: result.feedback };
+}
+
+// save/publish the comment yourself
+```
+
+### Modes
+
+| Mode | Behaviour |
+| --- | --- |
+| `full` (default) | Spam check + comment score when topic context is available |
+| `spam-only` | Spam detection only |
+| `perspective` | Perspective-compatible toxicity / insult / profanity scores |
+
+### Tip: cache `articleId`
+
+`moderateComment()` returns `articleId` when it initializes a topic. Reuse it for later comments on the same page to avoid re-init:
+
+```ts
+const result = await moderateComment({
+  comment: userText,
+  articleId: cachedArticleIdForThisPost,
+});
+```
+
+## Compared to `@respectify/astro`
+
+| | `@respectify/astro-moderation` | `@respectify/astro` |
+| --- | --- | --- |
+| Purpose | Moderate existing comments | Full comments product |
+| UI | Yours | Included |
+| Database | Yours | Astro DB |
+| Setup | Integration + 2 env vars | DB + actions + component |
+
+## Links
+
+- Product: https://respectify.ai
+- Comment moderation API guide: https://respectify.ai/comment-moderation-api
+- Client SDK: https://www.npmjs.com/package/@respectify/client
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { default } from "./integration.js";
+export { default as respectifyModeration } from "./integration.js";
+export { moderateComment, getModerationDefaults, setModerationDefaults } from "./moderate.js";
+export type { ModerateCommentInput, ModerateCommentResult, ModerateMode, RespectifyAstroModerationOptions, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { default } from "./integration.js";
+export { default as respectifyModeration } from "./integration.js";
+export { moderateComment, getModerationDefaults, setModerationDefaults } from "./moderate.js";

package/dist/integration.d.ts

@@ -0,0 +1,12 @@
+import type { AstroIntegration } from "astro";
+import type { RespectifyAstroModerationOptions } from "./types.js";
+/**
+ * Thin Astro integration for Respectify moderation.
+ *
+ * Adds env schema for RESPECTIFY_EMAIL / RESPECTIFY_API_KEY and stores
+ * default options used by moderateComment().
+ *
+ * Does NOT inject comment UI, database schema, or Astro Actions —
+ * you keep your existing comment stack and call moderateComment() from it.
+ */
+export default function respectifyModeration(options?: RespectifyAstroModerationOptions): AstroIntegration;

package/dist/integration.js

@@ -0,0 +1,36 @@
+import { envField } from "astro/config";
+import { setModerationDefaults } from "./moderate.js";
+/**
+ * Thin Astro integration for Respectify moderation.
+ *
+ * Adds env schema for RESPECTIFY_EMAIL / RESPECTIFY_API_KEY and stores
+ * default options used by moderateComment().
+ *
+ * Does NOT inject comment UI, database schema, or Astro Actions —
+ * you keep your existing comment stack and call moderateComment() from it.
+ */
+export default function respectifyModeration(options = {}) {
+    setModerationDefaults(options);
+    return {
+        name: "@respectify/astro-moderation",
+        hooks: {
+            "astro:config:setup": ({ updateConfig, logger }) => {
+                updateConfig({
+                    env: {
+                        schema: {
+                            RESPECTIFY_EMAIL: envField.string({
+                                context: "server",
+                                access: "secret",
+                            }),
+                            RESPECTIFY_API_KEY: envField.string({
+                                context: "server",
+                                access: "secret",
+                            }),
+                        },
+                    },
+                });
+                logger.info(`Respectify moderation ready (mode=${options.mode ?? "full"}). Call moderateComment() from your actions/API routes.`);
+            },
+        },
+    };
+}

package/dist/moderate.d.ts

@@ -0,0 +1,8 @@
+import type { ModerateCommentInput, ModerateCommentResult, RespectifyAstroModerationOptions } from "./types.js";
+export declare function setModerationDefaults(options: RespectifyAstroModerationOptions): void;
+export declare function getModerationDefaults(): RespectifyAstroModerationOptions;
+/**
+ * Moderate a single comment with Respectify.
+ * Call from an Astro Action, API route, or server endpoint.
+ */
+export declare function moderateComment(input: ModerateCommentInput): Promise<ModerateCommentResult>;

package/dist/moderate.js

@@ -0,0 +1,145 @@
+import { RespectifyClient, AuthenticationError, PaymentRequiredError, RespectifyError, } from "@respectify/client";
+const articleIdCache = new Map();
+let client = null;
+let integrationDefaults = {};
+export function setModerationDefaults(options) {
+    integrationDefaults = { ...options };
+}
+export function getModerationDefaults() {
+    return integrationDefaults;
+}
+function getClient() {
+    if (client)
+        return client;
+    const email = process.env.RESPECTIFY_EMAIL;
+    const apiKey = process.env.RESPECTIFY_API_KEY;
+    if (!email || !apiKey) {
+        throw new Error("Respectify credentials missing. Set RESPECTIFY_EMAIL and RESPECTIFY_API_KEY.");
+    }
+    client = new RespectifyClient({ email, apiKey });
+    return client;
+}
+async function resolveArticleId(input) {
+    if (input.articleId)
+        return input.articleId;
+    const topicUrl = input.topicUrl ?? integrationDefaults.defaultTopicUrl;
+    const topicText = input.topicText;
+    const cacheKey = topicUrl ? `url:${topicUrl}` : topicText ? `text:${topicText.slice(0, 200)}` : null;
+    if (!cacheKey)
+        return undefined;
+    const cached = articleIdCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const respectify = getClient();
+    const init = topicUrl
+        ? await respectify.initTopicFromUrl(topicUrl)
+        : await respectify.initTopicFromText(topicText);
+    articleIdCache.set(cacheKey, init.article_id);
+    return init.article_id;
+}
+function decideFromToxicity(toxicityScore, threshold, extras) {
+    if (extras?.isSpam) {
+        return {
+            approved: false,
+            feedback: "This comment appears to be spam.",
+            toxicityScore,
+            isSpam: true,
+        };
+    }
+    if (toxicityScore !== undefined && toxicityScore >= threshold) {
+        return {
+            approved: false,
+            feedback: extras?.explanation || "This comment looks too disrespectful to publish as-is.",
+            toxicityScore,
+            isSpam: false,
+        };
+    }
+    return {
+        approved: true,
+        feedback: "Looks good.",
+        toxicityScore,
+        isSpam: false,
+    };
+}
+function perspectiveScores(response) {
+    if (!response?.attributeScores)
+        return undefined;
+    const out = {};
+    for (const [name, entry] of Object.entries(response.attributeScores)) {
+        out[name] = entry.summaryScore.value;
+    }
+    return out;
+}
+/**
+ * Moderate a single comment with Respectify.
+ * Call from an Astro Action, API route, or server endpoint.
+ */
+export async function moderateComment(input) {
+    const mode = input.mode ?? integrationDefaults.mode ?? "full";
+    const toxicityThreshold = input.toxicityThreshold ?? integrationDefaults.toxicityThreshold ?? 0.7;
+    try {
+        const respectify = getClient();
+        if (mode === "perspective") {
+            const response = await respectify.perspective.analyzeComment({
+                comment: { text: input.comment },
+                requestedAttributes: {
+                    TOXICITY: {},
+                    INSULT: {},
+                    PROFANITY: {},
+                },
+            });
+            const scores = perspectiveScores(response);
+            const toxicityScore = scores?.TOXICITY;
+            return {
+                ...decideFromToxicity(toxicityScore, toxicityThreshold),
+                perspectiveScores: scores,
+                raw: response,
+            };
+        }
+        const articleId = await resolveArticleId(input);
+        if (mode === "spam-only") {
+            const spam = await respectify.checkSpam(input.comment, articleId);
+            return {
+                approved: !spam.is_spam,
+                feedback: spam.is_spam
+                    ? spam.reasoning || "This comment appears to be spam."
+                    : "Looks good.",
+                isSpam: spam.is_spam,
+                articleId,
+                raw: spam,
+            };
+        }
+        // full
+        const megacallOptions = {
+            comment: input.comment,
+            includeSpam: true,
+        };
+        if (articleId) {
+            megacallOptions.articleId = articleId;
+            megacallOptions.includeCommentScore = true;
+        }
+        const result = await respectify.megacall(megacallOptions);
+        const toxicityScore = result.comment_score?.toxicity_score;
+        const explanation = result.comment_score?.toxicity_explanation;
+        return {
+            ...decideFromToxicity(toxicityScore, toxicityThreshold, {
+                isSpam: result.spam_check?.is_spam,
+                explanation,
+            }),
+            articleId,
+            raw: result,
+        };
+    }
+    catch (error) {
+        if (error instanceof AuthenticationError) {
+            throw new Error("Respectify authentication failed. Check RESPECTIFY_EMAIL and RESPECTIFY_API_KEY.");
+        }
+        if (error instanceof PaymentRequiredError) {
+            throw new Error("Respectify payment required. Top up your account balance.");
+        }
+        if (error instanceof RespectifyError) {
+            throw new Error(`Respectify API error (${error.statusCode ?? "unknown"}): ${error.message}`);
+        }
+        throw error;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+export type ModerateMode = "full" | "spam-only" | "perspective";
+export interface RespectifyAstroModerationOptions {
+    /**
+     * Which analysis path to use by default.
+     * - full: spam + comment score (topic context when URL/text provided)
+     * - spam-only: spam check only
+     * - perspective: Perspective-compatible toxicity attribute scores
+     * @default "full"
+     */
+    mode?: ModerateMode;
+    /**
+     * Toxicity block threshold for auto-decision (0–1). Higher = more toxic.
+     * Used when mode is "full" or "perspective".
+     * @default 0.7
+     */
+    toxicityThreshold?: number;
+    /**
+     * Optional default page/topic URL used to build article context when
+     * moderateComment() is called without topicUrl/topicText.
+     */
+    defaultTopicUrl?: string;
+}
+export interface ModerateCommentInput {
+    /** Comment text to analyse */
+    comment: string;
+    /** Existing Respectify article/topic UUID (skips init when set) */
+    articleId?: string;
+    /** Initialize topic from this URL when articleId is missing */
+    topicUrl?: string;
+    /** Initialize topic from this text when articleId / topicUrl missing */
+    topicText?: string;
+    /** Override integration default mode for this call */
+    mode?: ModerateMode;
+    /** Override toxicity threshold for this call */
+    toxicityThreshold?: number;
+}
+export interface ModerateCommentResult {
+    /** Whether the comment should be allowed through */
+    approved: boolean;
+    /** Short reason / coaching feedback for the commenter or your logs */
+    feedback: string;
+    /** Toxicity-ish score when available (0 = clean, 1 = highly toxic) */
+    toxicityScore?: number;
+    /** True when spam was detected */
+    isSpam?: boolean;
+    /** Article context used (useful to cache for later comments on the same page) */
+    articleId?: string;
+    /** Perspective attribute scores when mode is "perspective" */
+    perspectiveScores?: Record<string, number>;
+    /** Underlying megacall / perspective payload for advanced callers */
+    raw?: unknown;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@respectify/astro-moderation",
+  "version": "0.1.1",
+  "description": "Thin Astro integration for Respectify comment moderation — API key in, approve/block + feedback out.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Respectify <dave@respectify.ai>",
+  "homepage": "https://www.npmjs.com/package/@respectify/astro-moderation",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Respectify/respectify-astro-moderation.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Respectify/respectify-astro-moderation/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "withastro",
+    "respectify",
+    "moderation",
+    "comments",
+    "toxicity",
+    "spam",
+    "perspective-api"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./moderate": {
+      "types": "./dist/moderate.d.ts",
+      "import": "./dist/moderate.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@respectify/client": "^0.5.0",
+    "astro": "^5.0.0 || ^6.0.0"
+  },
+  "devDependencies": {
+    "@respectify/client": "^0.5.0",
+    "@types/node": "^26.1.1",
+    "astro": "^5.16.5",
+    "typescript": "^5.9.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}