is-it-spam 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# isSpamLLM
+
+Simple LLM-based spam classifier. Works with any OpenAI-compatible API.
+
+## Install
+
+```bash
+npm install spam-classifier
+```
+
+## Usage
+
+```typescript
+import { createClassifier } from "spam-classifier";
+
+// Set up once
+const isSpam = createClassifier({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+});
+
+// Use anywhere - returns true/false
+if (await isSpam("Need a quote for your services")) {
+  // spam - ignore it
+}
+
+// Or get details
+const result = await isSpam.details("Need a quote");
+// { isSpam: false, confidence: 0.95, reason: "Customer requesting quote" }
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | string | **required** | API key |
+| `model` | string | `"openai/gpt-4o-mini"` | Model to use |
+| `baseUrl` | string | OpenRouter | API endpoint |
+| `zdr` | boolean | `false` | Enable Zero Data Retention |
+
+## Providers
+
+Works with any OpenAI-compatible API:
+
+```typescript
+// OpenRouter (default)
+const isSpam = createClassifier({ apiKey: process.env.OPENROUTER_API_KEY! });
+
+// OpenAI directly
+const isSpam = createClassifier({
+  apiKey: process.env.OPENAI_API_KEY!,
+  baseUrl: "https://api.openai.com/v1/chat/completions",
+  model: "gpt-4o-mini",
+});
+
+// Local LLM
+const isSpam = createClassifier({
+  apiKey: "not-needed",
+  baseUrl: "http://localhost:11434/v1/chat/completions",
+  model: "llama3",
+});
+```
+
+## Fail-Safe
+
+Returns `false` (legitimate) if the API fails, so you never block real customers.
+
+## Cost
+
+~$0.0002 per classification. 10,000 submissions = ~$2.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * isSpamLLM
+ *
+ * Simple LLM-based spam classifier.
+ * Works with any OpenAI-compatible API.
+ */
+export interface ClassifierOptions {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+    zdr?: boolean;
+}
+export interface ClassifyResult {
+    isSpam: boolean;
+    confidence?: number;
+    reason?: string;
+}
+type Classifier = ((content: string) => Promise<boolean>) & {
+    details: (content: string) => Promise<ClassifyResult>;
+};
+/**
+ * Create a spam classifier function.
+ *
+ * @example
+ * ```typescript
+ * // Set up once
+ * const isSpam = createClassifier({
+ *   apiKey: process.env.OPENROUTER_API_KEY!,
+ * });
+ *
+ * // Use anywhere
+ * if (await isSpam("Need a quote")) {
+ *   // spam
+ * }
+ *
+ * // Or get details
+ * const result = await isSpam.details("Need a quote");
+ * // { isSpam: false, confidence: 0.95, reason: "..." }
+ * ```
+ */
+export declare function createClassifier(options: ClassifierOptions): Classifier;
+export {};

package/dist/index.js

@@ -0,0 +1,107 @@
+/**
+ * isSpamLLM
+ *
+ * Simple LLM-based spam classifier.
+ * Works with any OpenAI-compatible API.
+ */
+const DEFAULT_BASE_URL = "https://openrouter.ai/api/v1/chat/completions";
+const DEFAULT_MODEL = "openai/gpt-5.4-nano";
+const SYSTEM_PROMPT = `You are a spam filter.
+Determine if the input is spam or a legitimate message.
+
+LEGITIMATE: genuine inquiries, customer questions, support requests, etc.
+SPAM: web design pitches, SEO offers, lead gen, "grow your business", partnership requests, unsolicited sales pitches, etc.
+
+Key indicator: Is this a sales pitch TO the recipient or a genuine message FROM someone?
+
+Respond with JSON: {"is_spam": boolean, "confidence": number, "reason": string}`;
+async function classify(content, options) {
+    const { apiKey, model = DEFAULT_MODEL, baseUrl = DEFAULT_BASE_URL, zdr = false, } = options;
+    const body = {
+        model,
+        messages: [
+            { role: "system", content: SYSTEM_PROMPT },
+            { role: "user", content: `Classify this:\n\n${content}` },
+        ],
+        response_format: {
+            type: "json_schema",
+            json_schema: {
+                name: "spam_classification",
+                strict: true,
+                schema: {
+                    type: "object",
+                    properties: {
+                        is_spam: { type: "boolean" },
+                        confidence: { type: "number" },
+                        reason: { type: "string" },
+                    },
+                    required: ["is_spam", "confidence", "reason"],
+                    additionalProperties: false,
+                },
+            },
+        },
+        temperature: 0,
+        max_tokens: 200,
+    };
+    if (zdr) {
+        body.provider = { zdr: true };
+    }
+    const response = await fetch(baseUrl, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        throw new Error(`API error: ${response.status}`);
+    }
+    const data = (await response.json());
+    const parsed = JSON.parse(data.choices[0].message.content);
+    return {
+        isSpam: parsed.is_spam,
+        confidence: parsed.confidence,
+        reason: parsed.reason,
+    };
+}
+/**
+ * Create a spam classifier function.
+ *
+ * @example
+ * ```typescript
+ * // Set up once
+ * const isSpam = createClassifier({
+ *   apiKey: process.env.OPENROUTER_API_KEY!,
+ * });
+ *
+ * // Use anywhere
+ * if (await isSpam("Need a quote")) {
+ *   // spam
+ * }
+ *
+ * // Or get details
+ * const result = await isSpam.details("Need a quote");
+ * // { isSpam: false, confidence: 0.95, reason: "..." }
+ * ```
+ */
+export function createClassifier(options) {
+    const classifier = async (content) => {
+        try {
+            const result = await classify(content, options);
+            return result.isSpam;
+        }
+        catch {
+            return false; // Fail open
+        }
+    };
+    classifier.details = async (content) => {
+        try {
+            return await classify(content, options);
+        }
+        catch {
+            return { isSpam: false, confidence: 0, reason: "Classification failed" };
+        }
+    };
+    return classifier;
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "is-it-spam",
+  "version": "0.1.0",
+  "description": "LLM-based spam classifier. Works with any OpenAI-compatible API.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test"
+  },
+  "keywords": [
+    "spam",
+    "classifier",
+    "llm",
+    "form",
+    "openai",
+    "openrouter"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}