@calmify/next 0.0.0-stage → 1.0.2

package/README.md

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# @calmify/next
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Receive articles from Calmify in a Next.js (App Router) site.
+
+1. `npm install @calmify/next`
+2. Create `app/api/calmify/route.ts`:
+   ```ts
+   import { createCalmifyHandler } from "@calmify/next";
+   export const runtime = "nodejs";
+   export const { GET, POST } = createCalmifyHandler({
+     findByKey: async (key) => /* look up a post saved with this key */ null,
+     save: async (post) => { /* save to your DB/CMS, idempotent on post.idempotencyKey */ return { id: 1, url: `https://www.yoursite.com/blog/${post.slug}` }; },
+   });
+   ```
+3. `npx calmify-pair` once to generate `CALMIFY_API_KEY`; add it to your hosting env and deploy.
+4. In Calmify: Websites → Connection → Connect, then `npx calmify-pair CALM-XXXX-XXXX --endpoint https://www.yoursite.com/api/calmify`.
+
+Full guide: https://calmifye.vercel.app/docs/connect

package/bin/calmify-pair.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// npx calmify-pair CALM-XXXX-XXXX [--endpoint https://www.yoursite.com/api/calmify]
+// Needs CALMIFY_API_KEY in the environment (or .env.local). On success it
+// prints CALMIFY_ASSET_HOST and appends it to .env.local.
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+
+const args = process.argv.slice(2);
+const code = args.find((a) => !a.startsWith("--"));
+const opt = (n) => { const i = args.indexOf("--" + n); return i >= 0 ? args[i + 1] : undefined; };
+const envFile = ".env.local";
+const fileEnv = existsSync(envFile) ? Object.fromEntries(readFileSync(envFile, "utf8").split("\n").map((l) => l.match(/^([A-Z_]+)=(.*)$/)).filter(Boolean).map((m) => [m[1], m[2]])) : {};
+let key = process.env.CALMIFY_API_KEY || fileEnv.CALMIFY_API_KEY;
+if (!key) {
+  key = randomBytes(32).toString("hex");
+  appendFileSync(envFile, `\nCALMIFY_API_KEY=${key}\n`);
+  console.log("Generated CALMIFY_API_KEY in .env.local. Add it to your hosting environment too, redeploy, then run this again.");
+  process.exit(0);
+}
+let endpoint = opt("endpoint") || process.env.CALMIFY_ENDPOINT || fileEnv.CALMIFY_ENDPOINT;
+const calmify = (opt("calmify") || "https://calmifye.vercel.app").replace(/\/+$/, "");
+if (!code || !endpoint) {
+  console.log("Usage: npx calmify-pair CALM-XXXX-XXXX --endpoint https://www.yoursite.com/api/calmify");
+  process.exit(1);
+}
+for (let attempt = 0; attempt < 2; attempt++) {
+  console.log("Pairing " + endpoint + " …");
+  const res = await fetch(calmify + "/api/connect/pair", {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Accept: "application/json" },
+    body: JSON.stringify({ code, endpoint, key, receiver: "nextjs" }),
+  });
+  const body = await res.json().catch(() => ({}));
+  if (res.ok) {
+    appendFileSync(envFile, `\nCALMIFY_ASSET_HOST=${body.data.assetHost}\n`);
+    console.log(`Connected to Calmify website "${body.data.website}".`);
+    console.log(`Set CALMIFY_ASSET_HOST=${body.data.assetHost} in your hosting environment too (added to .env.local).`);
+    process.exit(0);
+  }
+  const suggested = body?.error?.fields?.suggestedEndpoint;
+  if (attempt === 0 && suggested) {
+    console.log("The site answers at " + suggested + ". Trying that address.");
+    endpoint = suggested;
+    continue;
+  }
+  console.error(body?.error?.message ?? `Pairing failed (HTTP ${res.status}).`);
+  process.exit(1);
+}

package/index.d.ts

@@ -0,0 +1,19 @@
+export type CalmifyPost = {
+  idempotencyKey: string;
+  title: string;
+  slug: string;
+  /** Sanitized HTML. */
+  contentHtml: string;
+  category: string;
+  metaDescription: string;
+  metaKeywords: string;
+  /** Cover image bytes (PNG/JPEG/WebP, checked) or null. */
+  image: { bytes: Uint8Array; ext: "png" | "jpg" | "webp"; alt: string } | null;
+};
+export type SaveResult = { id: string | number; url: string };
+export function createCalmifyHandler(options: {
+  /** Return the saved post's id and public URL. Must be idempotent on idempotencyKey. */
+  save: (post: CalmifyPost) => Promise<SaveResult>;
+  /** Return the existing post for a key, or null. */
+  findByKey: (idempotencyKey: string) => Promise<SaveResult | null>;
+}): { GET: (req: Request) => Promise<Response>; POST: (req: Request) => Promise<Response> };

package/index.js

@@ -0,0 +1,89 @@
+// @calmify/next: Calmify receiver for the App Router.
+//
+//   // app/api/calmify/route.ts
+//   import { createCalmifyHandler } from "@calmify/next";
+//   export const runtime = "nodejs";
+//   export const { GET, POST } = createCalmifyHandler({ save, findByKey });
+//
+// Env: CALMIFY_API_KEY (any 64-char random hex), CALMIFY_ASSET_HOST (set by
+// `npx calmify-pair`). GET answers Calmify's connection check; POST
+// receives a post. You store it (your DB/CMS) in `save`.
+import { createHash, timingSafeEqual } from "node:crypto";
+import sanitizeHtml from "sanitize-html";
+
+const MAX_BODY = 600 * 1024;
+const MAX_IMAGE = 5 * 1024 * 1024;
+const json = (status, body) => Response.json(body, { status });
+const same = (a, b) => timingSafeEqual(createHash("sha256").update(a).digest(), createHash("sha256").update(b).digest());
+const authorized = (req) => {
+  const key = process.env.CALMIFY_API_KEY ?? "";
+  return key.length >= 32 && same(key, req.headers.get("x-calmify-key") ?? "");
+};
+
+async function cover(url) {
+  let u;
+  try {
+    u = new URL(url);
+  } catch {
+    return null;
+  }
+  if (u.protocol !== "https:" || u.hostname !== process.env.CALMIFY_ASSET_HOST || u.username) return null;
+  const res = await fetch(u, { redirect: "manual", signal: AbortSignal.timeout(20_000) });
+  if (res.status !== 200 || !res.body) return null;
+  const chunks = [];
+  let size = 0;
+  for await (const c of res.body) {
+    size += c.byteLength;
+    if (size > MAX_IMAGE) return null;
+    chunks.push(c);
+  }
+  const b = Buffer.concat(chunks);
+  const ext =
+    b.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) ? "png"
+    : b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff ? "jpg"
+    : b.toString("ascii", 0, 4) === "RIFF" && b.toString("ascii", 8, 12) === "WEBP" ? "webp"
+    : null;
+  return ext ? { bytes: new Uint8Array(b), ext } : null;
+}
+
+export function createCalmifyHandler({ save, findByKey }) {
+  return {
+    async GET(req) {
+      if (!authorized(req)) return json(401, { error: "unauthorized" });
+      return json(200, { ok: true, receiver: "nextjs" });
+    },
+    async POST(req) {
+      if (!authorized(req)) return json(401, { error: "unauthorized" });
+      const raw = await req.text();
+      if (raw.length > MAX_BODY) return json(413, { error: "too_large" });
+      const key = req.headers.get("idempotency-key") ?? "";
+      let b;
+      try {
+        b = JSON.parse(raw);
+      } catch {
+        return json(400, { error: "invalid_json" });
+      }
+      const s = (k, max, required = false) => {
+        const v = b[k] ?? (required ? undefined : "");
+        return typeof v === "string" && v.length <= max && (!required || v) ? v : null;
+      };
+      const p = { title: s("title", 300, true), slug: s("slug", 120, true), content: s("content", 500_000, true), category: s("category", 100), description: s("meta_description", 320), keywords: s("meta_keywords", 1000), alt: s("image_alt", 300) };
+      if (!key || key.length > 200 || Object.values(p).includes(null) || !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(p.slug)) return json(422, { error: "invalid" });
+      const existing = await findByKey(key);
+      if (existing) return json(200, existing);
+      let image = null;
+      if (typeof b.image_url === "string" && b.image_url) {
+        const got = await cover(b.image_url);
+        if (!got) return json(422, { error: "image_rejected" });
+        image = { ...got, alt: p.alt };
+      }
+      try {
+        const saved = await save({ idempotencyKey: key, title: p.title, slug: p.slug, contentHtml: sanitizeHtml(p.content), category: p.category, metaDescription: p.description, metaKeywords: p.keywords, image });
+        return json(201, saved);
+      } catch {
+        const again = await findByKey(key);
+        return again ? json(200, again) : json(409, { error: "slug_taken" });
+      }
+    },
+  };
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@calmify/next",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.2",
+  "description": "Receive articles from Calmify in a Next.js app: a route handler and a one-time pairing command.",
+  "license": "MIT",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "bin": {
+    "calmify-pair": "bin/calmify-pair.js"
+  },
+  "peerDependencies": {
+    "next": ">=14"
+  },
+  "dependencies": {
+    "sanitize-html": "^2.13.0"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "bin",
+    "README.md"
+  ],
+  "keywords": [
+    "calmify",
+    "nextjs",
+    "blog",
+    "cms",
+    "receiver"
+  ],
+  "homepage": "https://calmifye.vercel.app/docs/connect",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  }
+}