kizlo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kizlo
+
+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,74 @@
+<br>
+
+<p align="center">
+  <a name="readme-top"></a>
+  <a href="https://kizlo.io">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://cdn.kizlo.io/logo/icon-light.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://cdn.kizlo.io/logo/icon-dark.svg">
+      <img alt="Kizlo" src="https://cdn.kizlo.io/logo/icon-dark.svg" height="100">
+    </picture>
+  </a>
+</p>
+
+<h3 align="center">Headless WordPress Toolkit</h3>
+
+<p align="center">
+  Your backend, your frontend — Kizlo handles the plumbing.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/kizlo"><img src="https://img.shields.io/npm/v/kizlo?style=flat-square&color=333" alt="npm version"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/github/license/kizlo-io/kizlo?style=flat-square&color=333" alt="License"></a>
+  <a href="https://www.npmjs.com/package/kizlo"><img src="https://img.shields.io/npm/dt/kizlo?style=flat-square&color=333" alt="npm downloads"></a>
+</p>
+
+<p align="center">
+  <a href="https://kizlo.io"><strong>Website</strong></a> ·
+  <a href="https://kizlo.io/docs"><strong>Docs</strong></a> ·
+  <a href="https://discord.com/invite/MjAUZamx5g"><strong>Discord</strong></a> ·
+  <a href="https://x.com/kizlo_io"><strong>Twitter</strong></a>
+</p>
+
+---
+
+## What is Kizlo?
+
+Kizlo is a framework-agnostic toolkit for headless WordPress, built for a stack you host and own from top to bottom. Use it to build websites, mobile apps, agentic applications, and more — Kizlo takes care of the plumbing so you can focus on the design.
+
+## Quick start
+
+Set up Kizlo in your project:
+
+```bash
+npx kizlo init
+```
+
+Watch your extensions and regenerate the contract during development:
+
+```bash
+npx kizlo dev
+```
+
+Generate the contract once for production builds:
+
+```bash
+npx kizlo generate
+```
+
+See the [docs](https://kizlo.io/docs) for the full guide.
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](https://github.com/kizlo-io/kizlo/blob/main/CONTRIBUTING.md) for setup,
+workflow, and PR guidelines.
+
+## Security
+
+If you discover a security vulnerability within Kizlo, please send an e-mail to security@kizlo.io.
+
+All reports will be promptly addressed, and you'll be credited accordingly.
+
+## Disclaimer
+
+Kizlo is an independent project and is not endorsed by, sponsored by, or affiliated with the WordPress Foundation or WooCommerce, Inc. The WordPress® trademarks are the intellectual property of the WordPress Foundation, and the Woo® and WooCommerce® trademarks are the intellectual property of WooCommerce, Inc. Uses of the WordPress®, Woo®, and WooCommerce® names in this organization are for identification purposes only and do not imply endorsement.

package/dist/adapters/auth.d.ts

@@ -0,0 +1,18 @@
+import { Promisify } from "@kizlo/shared";
+
+//#region src/adapters/auth.d.ts
+interface AuthUser {
+  id: number;
+  email?: string;
+  phone?: string;
+  firstName: string;
+  lastName: string;
+}
+interface AuthAdapter {
+  getUser(request: Request | null): Promisify<AuthUser | null>;
+}
+declare function authMock(options?: {
+  mockUserId?: number;
+}): AuthAdapter;
+//#endregion
+export { AuthAdapter, AuthUser, authMock };

package/dist/adapters/auth.js

@@ -0,0 +1,15 @@
+//#region src/adapters/auth.ts
+function authMock(options) {
+	return { getUser() {
+		return {
+			id: options?.mockUserId ?? 0,
+			firstName: "Karan",
+			lastName: "Gill",
+			email: "karan@gmail.con",
+			phone: "12345678901"
+		};
+	} };
+}
+
+//#endregion
+export { authMock };

package/dist/adapters/captcha.d.ts

@@ -0,0 +1,28 @@
+//#region src/adapters/captcha.d.ts
+type CaptchaAdapter = (input: {
+  token: string;
+  ip: string;
+}) => Promise<boolean>;
+declare function recaptcha(opts: {
+  secret: string;
+  minScore?: number;
+}): CaptchaAdapter;
+declare function turnstile(opts: {
+  secret: string;
+}): CaptchaAdapter;
+declare function hcaptcha(opts: {
+  secret: string;
+  sitekey?: string;
+}): CaptchaAdapter;
+declare function friendlyCaptcha(opts: {
+  secret: string;
+  sitekey?: string;
+}): CaptchaAdapter;
+declare function arkose(opts: {
+  privateKey: string;
+}): CaptchaAdapter;
+declare function altcha(opts: {
+  hmacKey: string;
+}): CaptchaAdapter;
+//#endregion
+export { CaptchaAdapter, altcha, arkose, friendlyCaptcha, hcaptcha, recaptcha, turnstile };

package/dist/adapters/captcha.js

@@ -0,0 +1,86 @@
+//#region src/adapters/captcha.ts
+function recaptcha(opts) {
+	return async ({ token, ip }) => {
+		const data = await (await fetch("https://www.google.com/recaptcha/api/siteverify", {
+			method: "POST",
+			headers: { "Content-Type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams({
+				secret: opts.secret,
+				response: token,
+				...ip && { remoteip: ip }
+			})
+		})).json();
+		if (!data.success) return false;
+		if (opts.minScore !== void 0 && data.score !== void 0) return data.score >= opts.minScore;
+		return true;
+	};
+}
+function turnstile(opts) {
+	return async ({ token, ip }) => {
+		return (await (await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", {
+			method: "POST",
+			headers: { "Content-Type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams({
+				secret: opts.secret,
+				response: token,
+				...ip && { remoteip: ip }
+			})
+		})).json()).success === true;
+	};
+}
+function hcaptcha(opts) {
+	return async ({ token, ip }) => {
+		return (await (await fetch("https://api.hcaptcha.com/siteverify", {
+			method: "POST",
+			headers: { "Content-Type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams({
+				secret: opts.secret,
+				response: token,
+				...ip && { remoteip: ip },
+				...opts.sitekey && { sitekey: opts.sitekey }
+			})
+		})).json()).success === true;
+	};
+}
+function friendlyCaptcha(opts) {
+	return async ({ token }) => {
+		return (await (await fetch("https://api.friendlycaptcha.com/api/v1/siteverify", {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				solution: token,
+				secret: opts.secret,
+				...opts.sitekey && { sitekey: opts.sitekey }
+			})
+		})).json()).success === true;
+	};
+}
+function arkose(opts) {
+	return async ({ token, ip }) => {
+		return (await (await fetch("https://verify-api.arkoselabs.com/api/v4/verify/", {
+			method: "POST",
+			headers: { "Content-Type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams({
+				private_key: opts.privateKey,
+				session_token: token,
+				...ip && { log_data: ip }
+			})
+		})).json()).session_details?.solved === true;
+	};
+}
+function altcha(opts) {
+	return async ({ token }) => {
+		try {
+			const payload = JSON.parse(Buffer.from(token, "base64").toString("utf-8"));
+			const { createHmac, createHash } = await import("node:crypto");
+			const algo = payload.algorithm.toLowerCase().replace("-", "");
+			if (createHash(algo).update(`${payload.salt}${payload.number}`).digest("hex") !== payload.challenge) return false;
+			return createHmac(algo, opts.hmacKey).update(payload.challenge).digest("hex") === payload.signature;
+		} catch {
+			return false;
+		}
+	};
+}
+
+//#endregion
+export { altcha, arkose, friendlyCaptcha, hcaptcha, recaptcha, turnstile };

package/dist/adapters/geo.d.ts

@@ -0,0 +1,18 @@
+import { Promisify } from "@kizlo/shared";
+
+//#region src/adapters/geo.d.ts
+interface ConnInfo {
+  ip: string | null;
+  country: string | null;
+  city: string | null;
+  state: string | null;
+  postcode: string | null;
+  timezone: string | null;
+  userAgent: string | null;
+}
+interface GeoAdapter {
+  getConnInfo(request: Request | null): Promisify<ConnInfo>;
+}
+declare function geoMock(values?: Partial<ConnInfo>): GeoAdapter;
+//#endregion
+export { ConnInfo, GeoAdapter, geoMock };

package/dist/adapters/geo.js

@@ -0,0 +1,18 @@
+//#region src/adapters/geo.ts
+function geoMock(values) {
+	return { getConnInfo(request) {
+		return {
+			ip: "49.205.46.133",
+			city: "DL",
+			state: "HR",
+			country: "IN",
+			postcode: "110058",
+			userAgent: request?.headers.get("User-Agent") ?? null,
+			timezone: null,
+			...values
+		};
+	} };
+}
+
+//#endregion
+export { geoMock };

package/dist/adapters/geo.vercel.d.ts

@@ -0,0 +1,6 @@
+import { GeoAdapter } from "./geo.js";
+
+//#region src/adapters/geo.vercel.d.ts
+declare function geoVercelNext(): GeoAdapter;
+//#endregion
+export { geoVercelNext };

package/dist/adapters/geo.vercel.js

@@ -0,0 +1,41 @@
+//#region src/adapters/geo.vercel.ts
+function geoVercelNext() {
+	return { getConnInfo: async (request) => {
+		if (request) return readVercelHeaders(request.headers);
+		let nextHeaders;
+		try {
+			nextHeaders = await (await import("next/headers")).headers();
+		} catch (err) {
+			throw new Error("geoVercelNext: no Request was provided and `next/headers` could not be loaded. Install `next` as a peer dependency, or pass a Request to the SDK.", { cause: err });
+		}
+		return readVercelHeaders(nextHeaders);
+	} };
+}
+function readVercelHeaders(headers) {
+	const xRealIp = headers.get("x-real-ip");
+	const xff = headers.get("x-forwarded-for");
+	const ip = xRealIp || xff?.split(",")[0]?.trim() || null;
+	const country = headers.get("x-vercel-ip-country") || null;
+	const cityRaw = headers.get("x-vercel-ip-city");
+	const tzRaw = headers.get("x-vercel-ip-timezone");
+	const userAgent = headers.get("User-Agent");
+	return {
+		ip,
+		country,
+		city: cityRaw ? safeDecode(cityRaw) : null,
+		timezone: tzRaw ? safeDecode(tzRaw) : null,
+		postcode: null,
+		state: null,
+		userAgent
+	};
+}
+function safeDecode(value) {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value || null;
+	}
+}
+
+//#endregion
+export { geoVercelNext };

package/dist/adapters/logger.d.ts

@@ -0,0 +1,31 @@
+import { LiteralUnion } from "@kizlo/shared";
+
+//#region src/adapters/logger.d.ts
+type LogLevel = "debug" | "info" | "warn" | "error";
+type Environment = LiteralUnion<"development" | "production" | "test", string>;
+interface LogPayload {
+  level: LogLevel;
+  message: string;
+  timestamp: Date;
+  context?: Record<string, unknown>;
+  error?: Error;
+}
+type LoggerAdapter = (payload: LogPayload) => void | Promise<void>;
+interface Logger {
+  debug(message: string, context?: Record<string, unknown>): void;
+  info(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  error(message: string, error?: Error, context?: Record<string, unknown>): void;
+  child(context: Record<string, unknown>): Logger;
+}
+interface ConsoleLogAdapterOptions {
+  /**
+   * Which levels to log. `true` means all, an array means only those.
+   * Default: all levels.
+   */
+  levels?: boolean | LogLevel[];
+}
+declare function consoleLog(opts?: ConsoleLogAdapterOptions): LoggerAdapter;
+declare const noopAdapter: LoggerAdapter;
+//#endregion
+export { ConsoleLogAdapterOptions, Environment, LogLevel, LogPayload, Logger, LoggerAdapter, consoleLog, noopAdapter };

package/dist/adapters/logger.js

@@ -0,0 +1,30 @@
+//#region src/adapters/logger.ts
+function consoleLog(opts = {}) {
+	const levelsOpt = opts.levels ?? true;
+	const allowed = levelsOpt === true ? null : new Set(levelsOpt === false ? [] : levelsOpt);
+	return (payload) => {
+		if (allowed && !allowed.has(payload.level)) return;
+		const { level, message, timestamp, context, error } = payload;
+		const args = [`[${timestamp.toISOString()}] [${level.toUpperCase()}]`, message];
+		if (context) args.push(context);
+		if (error) args.push(error);
+		switch (level) {
+			case "debug":
+				console.debug(...args);
+				break;
+			case "info":
+				console.info(...args);
+				break;
+			case "warn":
+				console.warn(...args);
+				break;
+			case "error":
+				console.error(...args);
+				break;
+		}
+	};
+}
+const noopAdapter = () => {};
+
+//#endregion
+export { consoleLog, noopAdapter };

package/dist/cli/banner.js

@@ -0,0 +1,26 @@
+//#region src/cli/banner.ts
+const KIZLO_CLI_WORD_MARK = [
+	"██╗  ██╗██╗███████╗██╗      ██████╗ ",
+	"██║ ██╔╝██║╚══███╔╝██║     ██╔═══██╗",
+	"█████╔╝ ██║  ███╔╝ ██║     ██║   ██║",
+	"██╔═██╗ ██║ ███╔╝  ██║     ██║   ██║",
+	"██║  ██╗██║███████╗███████╗╚██████╔╝",
+	"╚═╝  ╚═╝╚═╝╚══════╝╚══════╝ ╚═════╝ "
+];
+const KIZLO_TAGLINE = "Headless WordPress toolkit for TypeScript";
+function colorSupported() {
+	return Boolean(process.stdout.isTTY) && process.env.NO_COLOR === void 0 && process.env.TERM !== "dumb";
+}
+function printBanner(version) {
+	const color = colorSupported();
+	const cyan = color ? "\x1B[38;5;44m" : "";
+	const bold = color ? "\x1B[1m" : "";
+	const dim = color ? "\x1B[2m" : "";
+	const reset = color ? "\x1B[0m" : "";
+	const art = KIZLO_CLI_WORD_MARK.map((line) => `${cyan}${line}${reset}`).join("\n");
+	process.stdout.write(`\n${art}\n\n`);
+	process.stdout.write(`${dim}${KIZLO_TAGLINE}${reset}  ${bold}v${version}${reset}\n\n`);
+}
+
+//#endregion
+export { printBanner };

package/dist/cli/commands/generate.js

@@ -0,0 +1,34 @@
+import { log } from "../daemon/logger.js";
+import { resolveConfig } from "../daemon/config.js";
+import { generateOnce } from "../daemon/generate.js";
+import { defineCommand } from "citty";
+
+//#region src/cli/commands/generate.ts
+const generate = defineCommand({
+	meta: {
+		name: "generate",
+		description: "Generate the Kizlo contract once (for builds and CI)"
+	},
+	args: { dir: {
+		type: "string",
+		description: "Override the Kizlo directory (defaults to kizlo.config.ts)"
+	} },
+	async run({ args }) {
+		const cfg = await resolveConfig(process.cwd(), { dir: args.dir });
+		let ok;
+		try {
+			ok = await generateOnce(cfg);
+		} catch (error) {
+			log.error("Failed to generate the Kizlo contract:", error);
+			process.exit(1);
+		}
+		if (!ok) {
+			log.error(`No Kizlo server found in ${cfg.serverEntry}`);
+			process.exit(1);
+		}
+		log.success("Contract generated");
+	}
+});
+
+//#endregion
+export { generate };