kizlo 0.2.0 → 0.2.2

package/README.md

@@ -11,10 +11,10 @@
   </a>
 </p>
 
-<h3 align="center">Headless WordPress Toolkit</h3>
+<h3 align="center">Headless WordPress Toolkit for TypeScript</h3>
 
 <p align="center">
-  Your backend, your frontend — Kizlo handles the plumbing.
+  Develop, test, and ship from your machine with a fully typed RPC layer and WordPress API client.
 </p>
 
 <p align="center">
@@ -34,33 +34,29 @@
 
 ## 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.
+Kizlo is an open-source, typesafe toolkit for headless WordPress, built to sit behind any JavaScript framework as your backend or CMS. Its CLI spins up a local, Docker-based environment scoped to your project, giving you a fully typed RPC layer and WordPress API client to develop, test, and ship from your machine.
+
+> Kizlo extends through integrations, whether that's a WordPress plugin like WooCommerce or an external service for auth, analytics, and more. Browse all available [integrations](https://kizlo.io/integrations).
 
 ## Quick start
 
 Set up Kizlo in your project:
 
 ```bash
-npx kizlo init
+npx kizlo@latest init
 ```
 
-Watch your extensions and regenerate the contract during development:
+Start the local WordPress stack and regenerate the contract as you work:
 
 ```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,
+Contributions are welcome. See [CONTRIBUTING.md](https://github.com/kizlo-io/kizlo/blob/main/CONTRIBUTING.md) for setup,
 workflow, and PR guidelines.
 
 ## Security

package/dist/cli/commands/dev.js

@@ -2,6 +2,7 @@ import { createStack } from "../wp/docker.js";
 import { ensureGitignored, envGroups, getVersion, groupDefault, mergeEnv, pickStackPort, withSpinner } from "../utils.js";
 import { palette, printBanner } from "../banner.js";
 import { resolveDevConfig } from "../daemon/config.js";
+import { startWatcher } from "../daemon/watch.js";
 import { bootstrapDev } from "../wp/dev.js";
 import { reapOrphans, registerSession, removeProjectContainers, spawnWatchdog, unregisterSession } from "../wp/session.js";
 import { syncSiteSettings } from "../wp/settings.js";
@@ -195,6 +196,8 @@ async function startForeground(cfg) {
 	const took = ms < 1e3 ? `${ms}ms` : `${(ms / 1e3).toFixed(1)}s`;
 	process.stdout.write(`\n   ${dim}Press ${reset}${bold}Ctrl+C${reset}${dim} (or close the terminal) to stop the development stack${reset}\n`);
 	process.stdout.write(`\n ${green}✓${reset} Ready in ${took}\n\n`);
+	const stopWatcher = await startWatcher(ready.configDir);
+	if (stopWatcher) process.on("exit", stopWatcher);
 	setInterval(() => {}, 1 << 30);
 	await new Promise(() => {});
 }

package/dist/cli/commands/init.js

@@ -2,12 +2,12 @@ import { composeStop, createStack, dockerAvailable } from "../wp/docker.js";
 import { addDependencyArgs, detectImportAlias, detectPackageManager, ensureGitignored, envGroups, envKeysPresent, getVersion, loadEnvFiles, mergeEnv, pickStackPort, resolveModuleImport, runCommand, writeFileIfAbsent } from "../utils.js";
 import { printBanner } from "../banner.js";
 import { DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, resolveStackName } from "../daemon/config.js";
+import { CONTRACT_BARREL } from "../daemon/generate.js";
 import { createAdminAppPassword } from "../wp/bootstrap.js";
 import { bootstrapDev } from "../wp/dev.js";
 import { removeProjectContainers } from "../wp/session.js";
 import { syncSiteSettings } from "../wp/settings.js";
 import { devStack } from "../wp/stack.js";
-import { CONTRACT_BARREL } from "../daemon/generate.js";
 import { PRESETS, detectPreset, getPreset } from "../presets/index.js";
 import z from "zod/v4";
 import { randomBytes } from "node:crypto";
@@ -375,9 +375,9 @@ const init = defineCommand({
 		if (!hasKizlo) {
 			const s = p.spinner();
 			s.start(`Installing kizlo with ${pm}`);
-			const ok = runCommand(addDependencyArgs(pm, "kizlo"), cwd, "ignore");
+			const ok = runCommand(addDependencyArgs(pm, "kizlo@latest"), cwd, "ignore");
 			s.stop(ok ? "Installed kizlo" : "Could not install kizlo automatically");
-			if (!ok) p.log.warn(`Install it yourself: ${addDependencyArgs(pm, "kizlo").join(" ")}`);
+			if (!ok) p.log.warn(`Install it yourself: ${addDependencyArgs(pm, "kizlo@latest").join(" ")}`);
 		}
 		if (preset.apiPath && setup.baseUrl) setup.baseUrl = withApiPath(setup.baseUrl, preset.apiPath);
 		let adminPassword;
@@ -487,13 +487,14 @@ const init = defineCommand({
 		}
 		p.note([
 			...setup.mode === "local" ? [
-				`Start your local WordPress dev stack:`,
+				`Start your local WordPress dev stack (also watches your extensions):`,
 				`  npx kizlo dev`,
 				``
-			] : [],
-			`Watch your extensions and regenerate the contract during development:`,
-			`  npx kizlo watch`,
-			``,
+			] : [
+				`Watch your extensions and regenerate the contract during development:`,
+				`  npx kizlo watch`,
+				``
+			],
 			`Generate the contract once for production builds:`,
 			`  npx kizlo generate`
 		].join("\n"), "Next steps");

package/dist/cli/commands/test.js

@@ -5,6 +5,7 @@ import { isFree } from "../wp/ports.js";
 import { groupDefault, pickStackPort, withSpinner } from "../utils.js";
 import { resolveTestConfig } from "../daemon/config.js";
 import { testStack } from "../wp/stack.js";
+import { runPluginPhpunit } from "../wp/phpunit.js";
 import { runSeeds } from "../wp/setup.js";
 import { spawn } from "node:child_process";
 import { defineCommand } from "citty";
@@ -107,7 +108,9 @@ async function runSuite({ args }) {
 	log.info(cfg.command ? `Running: ${cfg.command}` : `Running: ${testCommand(cfg.packageManager).join(" ")}`);
 	let code = 1;
 	try {
-		code = await spawnTest(cfg.command, cfg.packageManager);
+		const jsCode = await spawnTest(cfg.command, cfg.packageManager);
+		const phpCode = await runPluginPhpunit(cfg);
+		code = jsCode !== 0 ? jsCode : phpCode;
 	} finally {
 		if (args.teardown) await withSpinner("Tearing down WordPress test stack", () => stack.composeDown(), "WordPress test stack stopped");
 		else log.info("Stack left running for fast reruns — `kizlo test stop` to stop it, or rerun with --teardown.");

package/dist/cli/commands/watch.js

@@ -1,10 +1,6 @@
-import { log } from "../daemon/logger.js";
 import { getVersion } from "../utils.js";
 import { printBanner } from "../banner.js";
-import { resolveConfig } from "../daemon/config.js";
-import { generateOnce } from "../daemon/generate.js";
-import { acquire, isLocked, lockPath, release } from "../daemon/lock.js";
-import { watch as watch$1 } from "../daemon/watch.js";
+import { startWatcher } from "../daemon/watch.js";
 import { defineCommand } from "citty";
 
 //#region src/cli/commands/watch.ts
@@ -13,32 +9,18 @@ const args = { dir: {
 	description: "Override the Kizlo directory (defaults to kizlo.config.ts)"
 } };
 async function run({ args: args$1 }) {
-	const cwd = process.cwd();
-	const lock = lockPath(cwd);
-	if (isLocked(lock)) {
-		log.info("Watcher already running — nothing to do.");
-		return;
-	}
 	printBanner(getVersion());
-	const cfg = await resolveConfig(cwd, { dir: args$1.dir });
-	acquire(lock);
-	const cleanup = () => release(lock);
-	process.on("exit", cleanup);
+	const stop = await startWatcher(process.cwd(), { dir: args$1.dir });
+	if (!stop) return;
+	process.on("exit", stop);
 	for (const signal of [
 		"SIGINT",
 		"SIGTERM",
 		"SIGHUP"
 	]) process.on(signal, () => {
-		cleanup();
+		stop();
 		process.exit(0);
 	});
-	try {
-		if (await generateOnce(cfg)) log.success("Contract generated");
-		else log.warn(`No Kizlo server found in ${cfg.serverEntry}`);
-	} catch (error) {
-		log.error("Failed to generate the Kizlo contract:", error);
-	}
-	await watch$1(cfg);
 }
 const watch = defineCommand({
 	meta: {

package/dist/cli/daemon/logger.js

@@ -3,6 +3,7 @@ import { consola } from "consola";
 //#region src/cli/daemon/logger.ts
 /** Tagged logger for the daemon — every line is prefixed with `kizlo`. */
 const log = consola.withTag("kizlo");
+log.options.formatOptions.date = false;
 
 //#endregion
 export { log };

package/dist/cli/daemon/watch.js

@@ -1,5 +1,7 @@
 import { log } from "./logger.js";
+import { resolveConfig } from "./config.js";
 import { generateOnce } from "./generate.js";
+import { acquire, isLocked, lockPath, release } from "./lock.js";
 import path from "node:path";
 import { FSWatcher } from "chokidar";
 
@@ -28,10 +30,41 @@ async function watch(cfg) {
 	});
 	const onChange = debounce(() => regenerate(cfg), 300);
 	watcher.add(path.resolve(cfg.cwd, cfg.serverDir));
-	watcher.on("ready", () => log.start("Watching for changes..."));
+	watcher.on("ready", () => log.start("Watching for contract changes..."));
 	watcher.on("all", () => void onChange());
 	return watcher;
 }
+/**
+* Acquire the single-instance lock, generate the contract once, and start the file
+* watcher. Returns a synchronous `stop()` that closes the watcher and releases the
+* lock — or `undefined` when another watcher already holds the lock (a standalone
+* `kizlo watch`, or a framework dev script), in which case the caller carries on
+* without watching. Shared by the standalone `kizlo watch` command and the
+* folded-in watcher of `kizlo dev`, so a single terminal covers both.
+*/
+async function startWatcher(cwd, opts) {
+	const lock = lockPath(cwd);
+	if (isLocked(lock)) {
+		log.info("Watcher already running — skipping the contract watcher.");
+		return;
+	}
+	const cfg = await resolveConfig(cwd, { dir: opts?.dir });
+	acquire(lock);
+	try {
+		if (await generateOnce(cfg)) log.success("Contract generated");
+		else log.warn(`No Kizlo server found in ${cfg.serverEntry}`);
+	} catch (error) {
+		log.error("Failed to generate the Kizlo contract:", error);
+	}
+	const watcher = await watch(cfg);
+	let stopped = false;
+	return () => {
+		if (stopped) return;
+		stopped = true;
+		release(lock);
+		watcher.close();
+	};
+}
 
 //#endregion
-export { watch };
+export { startWatcher };

package/dist/cli/wp/phpunit.js

@@ -0,0 +1,104 @@
+import { isLocalPlugin } from "./types.js";
+import { compose } from "./docker.js";
+import { log } from "../daemon/logger.js";
+import { existsSync } from "node:fs";
+import { basename, isAbsolute, resolve } from "node:path";
+
+//#region src/cli/wp/phpunit.ts
+const PLUGINS_DIR = `/var/www/html/wp-content/plugins`;
+/** Isolated database the PHP suite runs against — never the served site's DB. */
+const TEST_DB = "wordpress_test";
+/** Root creds from the compose file, used only to create the DB and grant access. */
+const MYSQL_ROOT_PASSWORD = "rootpass";
+/** The app user the served site already connects as; the suite reuses it. */
+const MYSQL_USER = "wordpress";
+/**
+* The bind-mounted local plugins that carry a `phpunit.xml` (or `.dist`), resolved
+* to their in-container plugin dir. Checked on the host (where the source lives),
+* run in the container (where WordPress lives) — so this works identically for a
+* consumer whose own plugin is mounted while kizlo comes from a release.
+*/
+function phpunitTargets(cfg) {
+	const seen = /* @__PURE__ */ new Set();
+	const targets = [];
+	for (const plugin of cfg.fixtures.flatMap((fixture) => fixture.plugins ?? [])) {
+		if (!isLocalPlugin(plugin)) continue;
+		const hostDir = isAbsolute(plugin.path) ? plugin.path : resolve(cfg.configDir, plugin.path);
+		const slug = basename(hostDir);
+		if (seen.has(slug)) continue;
+		seen.add(slug);
+		if (!(existsSync(resolve(hostDir, "phpunit.xml")) || existsSync(resolve(hostDir, "phpunit.xml.dist")))) continue;
+		if (!existsSync(resolve(hostDir, "vendor/bin/phpunit"))) {
+			log.warn(`${slug} has a phpunit config but no vendor/bin/phpunit — run \`composer install\` with dev dependencies to run its PHP tests. Skipping.`);
+			continue;
+		}
+		targets.push({
+			slug,
+			containerDir: `${PLUGINS_DIR}/${slug}`
+		});
+	}
+	return targets;
+}
+/**
+* Create the isolated `wordpress_test` database in the `mysql` service and grant the
+* app user full access to it. Idempotent (`IF NOT EXISTS` + a re-runnable grant), so
+* it can run on every `kizlo test` next to seeding without a guard.
+*/
+async function provisionTestDb() {
+	const sql = [
+		`CREATE DATABASE IF NOT EXISTS ${TEST_DB};`,
+		`GRANT ALL PRIVILEGES ON ${TEST_DB}.* TO '${MYSQL_USER}'@'%';`,
+		"FLUSH PRIVILEGES;"
+	].join(" ");
+	const res = await compose([
+		"exec",
+		"-T",
+		"mysql",
+		"mysql",
+		`-uroot`,
+		`-p${MYSQL_ROOT_PASSWORD}`,
+		"-e",
+		sql
+	]);
+	if (res.code !== 0) throw new Error(`Failed to provision the ${TEST_DB} database:\n${res.stderr || res.stdout}`);
+}
+/** Run one plugin's phpunit suite inside the `wordpress` container; resolve its exit code. */
+async function runTarget(target) {
+	const wpPhpunitDir = `${target.containerDir}/vendor/wp-phpunit/wp-phpunit`;
+	const res = await compose([
+		"exec",
+		"-T",
+		"-w",
+		target.containerDir,
+		"-e",
+		`WP_PHPUNIT__DIR=${wpPhpunitDir}`,
+		"wordpress",
+		"php",
+		"vendor/bin/phpunit",
+		"--colors=always"
+	]);
+	process.stdout.write(res.stdout);
+	if (res.stderr) process.stderr.write(res.stderr);
+	return res.code;
+}
+/**
+* Provision the test DB, then run phpunit for every bind-mounted local plugin that
+* ships a phpunit config. Returns the worst exit code (0 when nothing to run), so the
+* caller can fold PHP results into the overall `kizlo test` outcome. Plugin-agnostic:
+* it never hardcodes `plugins/kizlo`.
+*/
+async function runPluginPhpunit(cfg) {
+	const targets = phpunitTargets(cfg);
+	if (targets.length === 0) return 0;
+	await provisionTestDb();
+	let worst = 0;
+	for (const target of targets) {
+		log.info(`Running PHP tests for ${target.slug}…`);
+		const code = await runTarget(target);
+		if (code !== 0) worst = code;
+	}
+	return worst;
+}
+
+//#endregion
+export { runPluginPhpunit };

package/dist/index.d.ts

@@ -17,6 +17,9 @@ import "./wordpress/index.js";
 import { DevPluginSource, Fixture, FixtureCleanupFn, FixtureSeedFn, JsonValue, LocalPlugin, PluginSource, SeedContext, TestAdminUser, TestCredentials, TestUser, defineFixture, isLocalPlugin } from "./cli/wp/types.js";
 import { AuthAdapter, AuthGetUser, AuthUser, authMock, createAuthAdapter } from "./adapters/auth.js";
 import { CaptchaAdapter, altcha, arkose, createCaptchaAdapter, friendlyCaptcha, hcaptcha, recaptcha, turnstile } from "./adapters/captcha.js";
+import { CONTENT_TYPES, ContentType, ListSitemapUrlInput, ListSitemapUrlInputBase, Robots, RobotsRule, Seo, SeoHead, SeoSchema, Sitemap, SitemapList, SitemapUrl, SitemapUrlImage, SitemapUrlList } from "./seo/schema.js";
+import { WPK_ListSitemapUrlInput, WPK_RobotRule, WPK_Robots, WPK_Seo, WPK_Sitemap, WPK_SitemapContentType, WPK_SitemapUrl, WPK_SitemapUrlImage } from "./seo/types.js";
+import { SitemapIndexEntry } from "./seo/utils.js";
 import { CurrencyFormat, IdentifierInput, LIST_ORDER, ListMetadata, ListOrder, Media, PreviewTokenData, PreviewTokenPayload } from "./shared/schema.js";
 import { AnyContext, AnyNestedClient, CookiesAdapter, CookiesDeleteAll, CookiesGetAll, CookiesSetAll, HTTPMethod, List, MaybeOptionalOptions, RedirectInput, RedirectStatus } from "./shared/types.js";
 import { createCookiesAdapter } from "./adapters/cookies.js";
@@ -34,11 +37,10 @@ import { AuthUserFn, ConnInfoFn, Context, ContextConfig, ServerContext, VerifyCa
 import { AnyMiddleware, ExtractMiddlewareContextOutput, InferUses, Middleware, MiddlewareHandler, MiddlewareNextFn, MiddlewareOptions, MiddlewareResult, createMiddleware } from "./shared/middleware.js";
 import { AnyProcedure, AnyProcedureRouter, BaseHandlerOptions, ExtractParams, ExtractProcedureByScope, InvocationScope, OpenapiPart, Procedure, ProcedureContext, ProcedureErrors, ProcedureHandler, ProcedureOptions, ResolveParamsPart, ResolvedSchemaInput, ResolvedSchemaOutput, RouterDepthTuple, SchemaIO, buildProcedure, combineDetailed, createProcedure, handleUnexpectedError, schemaType } from "./shared/procedure.js";
 import { KizloClient, KizloClientConfig, createKizloClient } from "./client.js";
-import { CONTENT_TYPES, ContentType, ListSitemapUrlInput, ListSitemapUrlInputBase, Robots, RobotsRule, Seo, SeoHead, SeoSchema, Sitemap, SitemapList, SitemapUrl, SitemapUrlImage, SitemapUrlList } from "./seo/schema.js";
-import { WPK_ListSitemapUrlInput, WPK_RobotRule, WPK_Robots, WPK_Seo, WPK_Sitemap, WPK_SitemapContentType, WPK_SitemapUrl, WPK_SitemapUrlImage } from "./seo/types.js";
+import { CreateSitemapRouteOptions, SITEMAP_BASE, SITEMAP_INDEX_SLUG, SitemapRouteExtra, createSitemapRoute } from "./seo/sitemap.js";
 import { Contract, ContractProcedure, generateContract, isContractProcedure, restoreContract } from "./shared/contract.js";
 import { compare, hash, hmac } from "./shared/crypto.js";
 import { Identifier, parseIdentifier } from "./shared/identifier.js";
 import { createOrpcRouter } from "./shared/router.js";
 import { deserializeCurrencyFormat, deserializeListMetadata, emptyList, serializeCurrencyFormat } from "./shared/serialize.js";
-export { AnyContext, AnyEventSchema, AnyEvents, AnyExtension, AnyKizloConfig, AnyMiddleware, AnyNestedClient, AnyProcedure, AnyProcedureRouter, AuthAdapter, AuthGetUser, AuthUser, AuthUserFn, BaseHandlerOptions, CART_HASH_HEADER_KEY, COMMON_ERRORS, CONTENT_TYPES, CaptchaAdapter, CommentService, CommonErrorCode, CommonErrorLiteral, CommonErrorMap, ConnInfo, ConnInfoFn, ConsoleLogAdapterOptions, ContentType, Context, ContextConfig, Contract, ContractProcedure, CookiesAdapter, CookiesDeleteAll, CookiesGetAll, CookiesSetAll, CreateKizloOptions, CurrencyFormat, DefinedErrorMapLike, DevPluginSource, Environment, ErrorDefinition, EventHandler, EventHandlerFn, Extension, ExtensionInitFn, ExtensionInitOptions, ExtensionInitResult, ExtractExtensionRouter, ExtractMiddlewareContextOutput, ExtractParams, ExtractProcedureByScope, Fixture, FixtureCleanupFn, FixtureSeedFn, GeoAdapter, GeoGetConnInfo, HTTPMethod, Identifier, IdentifierInput, InferEventUnion, InferExtensionRouter, InferUses, InvocationScope, JsonValue, Kizlo, KizloAuthorsSettings, KizloAuthorsSettingsInput, KizloClient, KizloClientConfig, KizloConfig, KizloCrawlingSettings, KizloCrawlingSettingsInput, KizloError, KizloErrorOptions, KizloIdentitySettings, KizloIdentitySettingsInput, KizloMedia, KizloOrganizationFounder, KizloOrganizationSettings, KizloOrganizationSettingsInput, KizloPersonSettings, KizloPersonSettingsInput, KizloPostStatus, KizloPostTypeSettings, KizloPostTypeSettingsInput, KizloSettings, KizloSettingsService, KizloSiteSettings, KizloSiteSettingsInput, KizloSocialProfile, KizloTarget, KizloTaxonomySettings, KizloTaxonomySettingsInput, KizloWebhookSettings, KizloWebhookSettingsInput, LIST_ORDER, List, ListMetadata, ListOrder, ListSitemapUrlInput, ListSitemapUrlInputBase, LocalPlugin, LogLevel, LogPayload, Logger, LoggerAdapter, MaybeOptionalOptions, Media, MenuItemService, MenuService, Middleware, MiddlewareHandler, MiddlewareNextFn, MiddlewareOptions, MiddlewareResult, OpenapiPart, PluginSource, PostService, PreviewTokenData, PreviewTokenPayload, Procedure, ProcedureContext, ProcedureErrors, ProcedureHandler, ProcedureOptions, RedirectInput, RedirectStatus, ResolveParamsPart, ResolvedSchemaInput, ResolvedSchemaOutput, Robots, RobotsRule, RootRouter, RouterDepthTuple, S2SClient, SAFE_REQUEST_TIMEOUT, SchemaIO, SeedContext, Seo, SeoHead, SeoSchema, ServerContext, Service, ServiceAdapters, ServiceConfig, Sitemap, SitemapList, SitemapUrl, SitemapUrlImage, SitemapUrlList, TestAdminUser, TestCredentials, TestUser, ThrowableErrorFn, ThrowableErrorMap, UNEXPECTED_BODY_SNIPPET_LENGTH, UserService, VerifyCaptchaFn, VerifyPreviewTokenFn, WC_CORE_BASE, WC_STORE_BASE, WPK_ListSitemapUrlInput, WPK_RobotRule, WPK_Robots, WPK_Seo, WPK_Sitemap, WPK_SitemapContentType, WPK_SitemapUrl, WPK_SitemapUrlImage, WP_AUTH_HEADER_KEY, WP_AUTH_TYPE, WP_CORE_BASE, WP_Comment, WP_CommentAvatarUrls, WP_CommentContent, WP_CommentContentInput, WP_CommentCreateErrorCode, WP_CommentCreateInput, WP_CommentDeleteErrorCode, WP_CommentDeleteInput, WP_CommentDeleteResponse, WP_CommentLinks, WP_CommentListErrorCode, WP_CommentListInput, WP_CommentOrderBy, WP_CommentRetrieveErrorCode, WP_CommentRetrieveInput, WP_CommentStatus, WP_CommentStatusFilter, WP_CommentStatusInput, WP_CommentType, WP_CommentUpdateErrorCode, WP_CommentUpdateInput, WP_CommonErrorCode, WP_Context, WP_CurrencyFormat, WP_Error, WP_ErrorData, WP_KIZLO_BASE, WP_Link, WP_List, WP_ListMetadata, WP_ListOrder, WP_Menu, WP_MenuCreateErrorCode, WP_MenuCreateInput, WP_MenuDeleteErrorCode, WP_MenuDeleteInput, WP_MenuDeleteResponse, WP_MenuItem, WP_MenuItemCreateErrorCode, WP_MenuItemCreateInput, WP_MenuItemDeleteErrorCode, WP_MenuItemDeleteInput, WP_MenuItemDeleteResponse, WP_MenuItemLinks, WP_MenuItemListErrorCode, WP_MenuItemListInput, WP_MenuItemOrderBy, WP_MenuItemRetrieveErrorCode, WP_MenuItemRetrieveInput, WP_MenuItemStatus, WP_MenuItemStatusFilter, WP_MenuItemTarget, WP_MenuItemTaxRelation, WP_MenuItemTitle, WP_MenuItemTitleInput, WP_MenuItemType, WP_MenuItemUpdateErrorCode, WP_MenuItemUpdateInput, WP_MenuLinks, WP_MenuListErrorCode, WP_MenuListInput, WP_MenuOrderBy, WP_MenuRetrieveErrorCode, WP_MenuRetrieveInput, WP_MenuUpdateErrorCode, WP_MenuUpdateInput, WP_Post, WP_PostCommentStatus, WP_PostContent, WP_PostContentInput, WP_PostCreateErrorCode, WP_PostCreateInput, WP_PostDeleteErrorCode, WP_PostDeleteInput, WP_PostDeleteResponse, WP_PostExcerpt, WP_PostExcerptInput, WP_PostFormat, WP_PostGuid, WP_PostLinks, WP_PostListErrorCode, WP_PostListInput, WP_PostOrderBy, WP_PostRetrieveErrorCode, WP_PostRetrieveInput, WP_PostStatus, WP_PostStatusFilter, WP_PostTaxRelation, WP_PostTitle, WP_PostTitleInput, WP_PostUpdateErrorCode, WP_PostUpdateInput, WP_RequestInput, WP_Result, WP_User, WP_UserAvatarUrls, WP_UserCapabilities, WP_UserCreateErrorCode, WP_UserCreateInput, WP_UserDeleteErrorCode, WP_UserDeleteInput, WP_UserDeleteMeErrorCode, WP_UserDeleteMeInput, WP_UserDeleteMeResponse, WP_UserDeleteResponse, WP_UserLinks, WP_UserListErrorCode, WP_UserListInput, WP_UserOrderBy, WP_UserRetrieveErrorCode, WP_UserRetrieveInput, WP_UserRetrieveMeErrorCode, WP_UserRetrieveMeInput, WP_UserUpdateErrorCode, WP_UserUpdateInput, WP_UserUpdateMeErrorCode, WP_UserUpdateMeInput, WP_UserWho, WebhookOptions, WithCommonErrorMap, WordPressCredentials, WordPressService, altcha, arkose, authMock, buildProcedure, combineDetailed, compare, consoleLog, createAuthAdapter, createCaptchaAdapter, createCookiesAdapter, createEventHandler, createExtension, createGeoAdapter, createKizlo, createKizloClient, createLoggerAdapter, createMiddleware, createOrpcRouter, createProcedure, createThrowableErrorMap, createWebhookRouter, defineErrorMap, defineFixture, deserializeCurrencyFormat, deserializeListMetadata, emptyList, friendlyCaptcha, generateContract, geoMock, geoVercelNext, handleUnexpectedError, hash, hcaptcha, hmac, isContractProcedure, isKizloError, isLocalPlugin, isWordPressResourceError, noopAdapter, parseIdentifier, recaptcha, resolveKizloConfig, restoreContract, schemaType, serializeCurrencyFormat, toKizloError, turnstile };
+export { AnyContext, AnyEventSchema, AnyEvents, AnyExtension, AnyKizloConfig, AnyMiddleware, AnyNestedClient, AnyProcedure, AnyProcedureRouter, AuthAdapter, AuthGetUser, AuthUser, AuthUserFn, BaseHandlerOptions, CART_HASH_HEADER_KEY, COMMON_ERRORS, CONTENT_TYPES, CaptchaAdapter, CommentService, CommonErrorCode, CommonErrorLiteral, CommonErrorMap, ConnInfo, ConnInfoFn, ConsoleLogAdapterOptions, ContentType, Context, ContextConfig, Contract, ContractProcedure, CookiesAdapter, CookiesDeleteAll, CookiesGetAll, CookiesSetAll, CreateKizloOptions, CreateSitemapRouteOptions, CurrencyFormat, DefinedErrorMapLike, DevPluginSource, Environment, ErrorDefinition, EventHandler, EventHandlerFn, Extension, ExtensionInitFn, ExtensionInitOptions, ExtensionInitResult, ExtractExtensionRouter, ExtractMiddlewareContextOutput, ExtractParams, ExtractProcedureByScope, Fixture, FixtureCleanupFn, FixtureSeedFn, GeoAdapter, GeoGetConnInfo, HTTPMethod, Identifier, IdentifierInput, InferEventUnion, InferExtensionRouter, InferUses, InvocationScope, JsonValue, Kizlo, KizloAuthorsSettings, KizloAuthorsSettingsInput, KizloClient, KizloClientConfig, KizloConfig, KizloCrawlingSettings, KizloCrawlingSettingsInput, KizloError, KizloErrorOptions, KizloIdentitySettings, KizloIdentitySettingsInput, KizloMedia, KizloOrganizationFounder, KizloOrganizationSettings, KizloOrganizationSettingsInput, KizloPersonSettings, KizloPersonSettingsInput, KizloPostStatus, KizloPostTypeSettings, KizloPostTypeSettingsInput, KizloSettings, KizloSettingsService, KizloSiteSettings, KizloSiteSettingsInput, KizloSocialProfile, KizloTarget, KizloTaxonomySettings, KizloTaxonomySettingsInput, KizloWebhookSettings, KizloWebhookSettingsInput, LIST_ORDER, List, ListMetadata, ListOrder, ListSitemapUrlInput, ListSitemapUrlInputBase, LocalPlugin, LogLevel, LogPayload, Logger, LoggerAdapter, MaybeOptionalOptions, Media, MenuItemService, MenuService, Middleware, MiddlewareHandler, MiddlewareNextFn, MiddlewareOptions, MiddlewareResult, OpenapiPart, PluginSource, PostService, PreviewTokenData, PreviewTokenPayload, Procedure, ProcedureContext, ProcedureErrors, ProcedureHandler, ProcedureOptions, RedirectInput, RedirectStatus, ResolveParamsPart, ResolvedSchemaInput, ResolvedSchemaOutput, Robots, RobotsRule, RootRouter, RouterDepthTuple, S2SClient, SAFE_REQUEST_TIMEOUT, SITEMAP_BASE, SITEMAP_INDEX_SLUG, SchemaIO, SeedContext, Seo, SeoHead, SeoSchema, ServerContext, Service, ServiceAdapters, ServiceConfig, Sitemap, type SitemapIndexEntry, SitemapList, SitemapRouteExtra, SitemapUrl, SitemapUrlImage, SitemapUrlList, TestAdminUser, TestCredentials, TestUser, ThrowableErrorFn, ThrowableErrorMap, UNEXPECTED_BODY_SNIPPET_LENGTH, UserService, VerifyCaptchaFn, VerifyPreviewTokenFn, WC_CORE_BASE, WC_STORE_BASE, WPK_ListSitemapUrlInput, WPK_RobotRule, WPK_Robots, WPK_Seo, WPK_Sitemap, WPK_SitemapContentType, WPK_SitemapUrl, WPK_SitemapUrlImage, WP_AUTH_HEADER_KEY, WP_AUTH_TYPE, WP_CORE_BASE, WP_Comment, WP_CommentAvatarUrls, WP_CommentContent, WP_CommentContentInput, WP_CommentCreateErrorCode, WP_CommentCreateInput, WP_CommentDeleteErrorCode, WP_CommentDeleteInput, WP_CommentDeleteResponse, WP_CommentLinks, WP_CommentListErrorCode, WP_CommentListInput, WP_CommentOrderBy, WP_CommentRetrieveErrorCode, WP_CommentRetrieveInput, WP_CommentStatus, WP_CommentStatusFilter, WP_CommentStatusInput, WP_CommentType, WP_CommentUpdateErrorCode, WP_CommentUpdateInput, WP_CommonErrorCode, WP_Context, WP_CurrencyFormat, WP_Error, WP_ErrorData, WP_KIZLO_BASE, WP_Link, WP_List, WP_ListMetadata, WP_ListOrder, WP_Menu, WP_MenuCreateErrorCode, WP_MenuCreateInput, WP_MenuDeleteErrorCode, WP_MenuDeleteInput, WP_MenuDeleteResponse, WP_MenuItem, WP_MenuItemCreateErrorCode, WP_MenuItemCreateInput, WP_MenuItemDeleteErrorCode, WP_MenuItemDeleteInput, WP_MenuItemDeleteResponse, WP_MenuItemLinks, WP_MenuItemListErrorCode, WP_MenuItemListInput, WP_MenuItemOrderBy, WP_MenuItemRetrieveErrorCode, WP_MenuItemRetrieveInput, WP_MenuItemStatus, WP_MenuItemStatusFilter, WP_MenuItemTarget, WP_MenuItemTaxRelation, WP_MenuItemTitle, WP_MenuItemTitleInput, WP_MenuItemType, WP_MenuItemUpdateErrorCode, WP_MenuItemUpdateInput, WP_MenuLinks, WP_MenuListErrorCode, WP_MenuListInput, WP_MenuOrderBy, WP_MenuRetrieveErrorCode, WP_MenuRetrieveInput, WP_MenuUpdateErrorCode, WP_MenuUpdateInput, WP_Post, WP_PostCommentStatus, WP_PostContent, WP_PostContentInput, WP_PostCreateErrorCode, WP_PostCreateInput, WP_PostDeleteErrorCode, WP_PostDeleteInput, WP_PostDeleteResponse, WP_PostExcerpt, WP_PostExcerptInput, WP_PostFormat, WP_PostGuid, WP_PostLinks, WP_PostListErrorCode, WP_PostListInput, WP_PostOrderBy, WP_PostRetrieveErrorCode, WP_PostRetrieveInput, WP_PostStatus, WP_PostStatusFilter, WP_PostTaxRelation, WP_PostTitle, WP_PostTitleInput, WP_PostUpdateErrorCode, WP_PostUpdateInput, WP_RequestInput, WP_Result, WP_User, WP_UserAvatarUrls, WP_UserCapabilities, WP_UserCreateErrorCode, WP_UserCreateInput, WP_UserDeleteErrorCode, WP_UserDeleteInput, WP_UserDeleteMeErrorCode, WP_UserDeleteMeInput, WP_UserDeleteMeResponse, WP_UserDeleteResponse, WP_UserLinks, WP_UserListErrorCode, WP_UserListInput, WP_UserOrderBy, WP_UserRetrieveErrorCode, WP_UserRetrieveInput, WP_UserRetrieveMeErrorCode, WP_UserRetrieveMeInput, WP_UserUpdateErrorCode, WP_UserUpdateInput, WP_UserUpdateMeErrorCode, WP_UserUpdateMeInput, WP_UserWho, WebhookOptions, WithCommonErrorMap, WordPressCredentials, WordPressService, altcha, arkose, authMock, buildProcedure, combineDetailed, compare, consoleLog, createAuthAdapter, createCaptchaAdapter, createCookiesAdapter, createEventHandler, createExtension, createGeoAdapter, createKizlo, createKizloClient, createLoggerAdapter, createMiddleware, createOrpcRouter, createProcedure, createSitemapRoute, createThrowableErrorMap, createWebhookRouter, defineErrorMap, defineFixture, deserializeCurrencyFormat, deserializeListMetadata, emptyList, friendlyCaptcha, generateContract, geoMock, geoVercelNext, handleUnexpectedError, hash, hcaptcha, hmac, isContractProcedure, isKizloError, isLocalPlugin, isWordPressResourceError, noopAdapter, parseIdentifier, recaptcha, resolveKizloConfig, restoreContract, schemaType, serializeCurrencyFormat, toKizloError, turnstile };

package/dist/index.js

@@ -29,7 +29,8 @@ import { parseIdentifier } from "./shared/identifier.js";
 import { CONTENT_TYPES, ContentType, ListSitemapUrlInput, ListSitemapUrlInputBase, Robots, RobotsRule, Seo, SeoHead, SeoSchema, Sitemap, SitemapList, SitemapUrl, SitemapUrlImage, SitemapUrlList } from "./seo/schema.js";
 import { createEventHandler, createWebhookRouter } from "./webhook/index.js";
 import { Kizlo, createKizlo, resolveKizloConfig } from "./kizlo.js";
+import { SITEMAP_BASE, SITEMAP_INDEX_SLUG, createSitemapRoute } from "./seo/sitemap.js";
 import { createExtension } from "./shared/extension.js";
 import { createMiddleware } from "./shared/middleware.js";
 
-export { CART_HASH_HEADER_KEY, COMMON_ERRORS, CONTENT_TYPES, CommentService, ContentType, Context, CurrencyFormat, IdentifierInput, Kizlo, KizloClient, KizloError, KizloSettingsService, LIST_ORDER, ListMetadata, ListOrder, ListSitemapUrlInput, ListSitemapUrlInputBase, Media, MenuItemService, MenuService, PostService, PreviewTokenData, PreviewTokenPayload, Robots, RobotsRule, SAFE_REQUEST_TIMEOUT, Seo, SeoHead, SeoSchema, Service, Sitemap, SitemapList, SitemapUrl, SitemapUrlImage, SitemapUrlList, UNEXPECTED_BODY_SNIPPET_LENGTH, UserService, WC_CORE_BASE, WC_STORE_BASE, WP_AUTH_HEADER_KEY, WP_AUTH_TYPE, WP_CORE_BASE, WP_Error, WP_KIZLO_BASE, WordPressService, altcha, arkose, authMock, buildProcedure, combineDetailed, compare, consoleLog, createAuthAdapter, createCaptchaAdapter, createCookiesAdapter, createEventHandler, createExtension, createGeoAdapter, createKizlo, createKizloClient, createLoggerAdapter, createMiddleware, createOrpcRouter, createProcedure, createThrowableErrorMap, createWebhookRouter, defineErrorMap, defineFixture, deserializeCurrencyFormat, deserializeListMetadata, emptyList, friendlyCaptcha, generateContract, geoMock, geoVercelNext, handleUnexpectedError, hash, hcaptcha, hmac, isContractProcedure, isKizloError, isLocalPlugin, isWordPressResourceError, noopAdapter, parseIdentifier, recaptcha, resolveKizloConfig, restoreContract, schemaType, serializeCurrencyFormat, toKizloError, turnstile };
+export { CART_HASH_HEADER_KEY, COMMON_ERRORS, CONTENT_TYPES, CommentService, ContentType, Context, CurrencyFormat, IdentifierInput, Kizlo, KizloClient, KizloError, KizloSettingsService, LIST_ORDER, ListMetadata, ListOrder, ListSitemapUrlInput, ListSitemapUrlInputBase, Media, MenuItemService, MenuService, PostService, PreviewTokenData, PreviewTokenPayload, Robots, RobotsRule, SAFE_REQUEST_TIMEOUT, SITEMAP_BASE, SITEMAP_INDEX_SLUG, Seo, SeoHead, SeoSchema, Service, Sitemap, SitemapList, SitemapUrl, SitemapUrlImage, SitemapUrlList, UNEXPECTED_BODY_SNIPPET_LENGTH, UserService, WC_CORE_BASE, WC_STORE_BASE, WP_AUTH_HEADER_KEY, WP_AUTH_TYPE, WP_CORE_BASE, WP_Error, WP_KIZLO_BASE, WordPressService, altcha, arkose, authMock, buildProcedure, combineDetailed, compare, consoleLog, createAuthAdapter, createCaptchaAdapter, createCookiesAdapter, createEventHandler, createExtension, createGeoAdapter, createKizlo, createKizloClient, createLoggerAdapter, createMiddleware, createOrpcRouter, createProcedure, createSitemapRoute, createThrowableErrorMap, createWebhookRouter, defineErrorMap, defineFixture, deserializeCurrencyFormat, deserializeListMetadata, emptyList, friendlyCaptcha, generateContract, geoMock, geoVercelNext, handleUnexpectedError, hash, hcaptcha, hmac, isContractProcedure, isKizloError, isLocalPlugin, isWordPressResourceError, noopAdapter, parseIdentifier, recaptcha, resolveKizloConfig, restoreContract, schemaType, serializeCurrencyFormat, toKizloError, turnstile };

package/dist/integrations/nextjs/kizlo.server.d.ts

@@ -1,12 +1,11 @@
 import { AnyExtension } from "../../shared/extension.js";
 import { CreateKizloOptions, Kizlo } from "../../kizlo.js";
+import { NextRevalidateOptions } from "./revalidate.js";
 
 //#region src/integrations/nextjs/kizlo.server.d.ts
-type KizloServerOptions<TExts extends readonly AnyExtension[] = []> = CreateKizloOptions<TExts>;
-/**
- * Creates a Kizlo server for Next.js — same as the base `createKizlo`, but reads
- * the public base URL from `NEXT_PUBLIC_KIZLO_BACKEND_URL`.
- */
-declare function createKizlo<TExts extends readonly AnyExtension[] = []>(options?: CreateKizloOptions<TExts>): Kizlo<TExts>;
+type KizloServerOptions<TExts extends readonly AnyExtension[] = []> = CreateKizloOptions<TExts> & {
+  revalidate?: boolean | NextRevalidateOptions;
+};
+declare function createKizlo<TExts extends readonly AnyExtension[] = []>(options?: KizloServerOptions<TExts>): Kizlo<TExts>;
 //#endregion
 export { KizloServerOptions, createKizlo };

package/dist/integrations/nextjs/kizlo.server.js

@@ -1,12 +1,14 @@
 import { Kizlo, resolveKizloConfig } from "../../kizlo.js";
+import { nextRevalidation } from "./revalidate.js";
 
 //#region src/integrations/nextjs/kizlo.server.ts
-/**
-* Creates a Kizlo server for Next.js — same as the base `createKizlo`, but reads
-* the public base URL from `NEXT_PUBLIC_KIZLO_BACKEND_URL`.
-*/
 function createKizlo(options) {
-	return new Kizlo(resolveKizloConfig(options, { baseUrlEnvKey: "NEXT_PUBLIC_KIZLO_BACKEND_URL" }));
+	const revalidate = options?.revalidate;
+	const extensions = [...revalidate === false ? [] : [nextRevalidation(typeof revalidate === "object" ? revalidate : void 0)], ...options?.extensions ?? []];
+	return new Kizlo(resolveKizloConfig({
+		...options,
+		extensions
+	}, { baseUrlEnvKey: "NEXT_PUBLIC_KIZLO_BACKEND_URL" }));
 }
 
 //#endregion

package/dist/integrations/nextjs/revalidate.d.ts

@@ -0,0 +1,25 @@
+import { KizloEvent } from "../../webhook/schema.js";
+import "../../index.js";
+import { Pathname } from "@kizlo/shared";
+
+//#region src/integrations/nextjs/revalidate.d.ts
+type RevalidatePathFn = (path: string, type?: "layout" | "page") => void;
+/** A path to revalidate, optionally with the Next `type` a dynamic route needs (e.g. `"page"`). */
+type RevalidateTarget = Pathname | {
+  path: Pathname;
+  type?: "layout" | "page";
+};
+interface NextRevalidateOptions {
+  revalidatePath?: RevalidatePathFn;
+  /** Return extra paths to revalidate for a given event, on top of the event's own URL. */
+  paths?: (event: KizloEvent) => Pathname[] | Promise<Pathname[]>;
+  /**
+   * How to revalidate the sitemap. Defaults to the route `createSitemapRoute` serves
+   * (`/sitemaps/[sitemap]`, revalidated as a dynamic page). Override this only if you
+   * serve sitemaps from your own route(s) instead of `createSitemapRoute`; pass `false`
+   * to skip sitemap revalidation.
+   */
+  sitemap?: false | RevalidateTarget | RevalidateTarget[];
+}
+//#endregion
+export { NextRevalidateOptions };

package/dist/integrations/nextjs/revalidate.js

@@ -0,0 +1,46 @@
+import { createEventHandler } from "../../webhook/index.js";
+import { createExtension } from "../../shared/extension.js";
+import { SITEMAP_ROUTE } from "./sitemap.js";
+
+//#region src/integrations/nextjs/revalidate.ts
+const ROBOTS_PATH = "/robots.txt";
+const DEFAULT_SITEMAP_TARGET = {
+	path: SITEMAP_ROUTE,
+	type: "page"
+};
+function nextRevalidation(options) {
+	return createExtension({
+		id: "nextjs-revalidation",
+		init: () => ({ events: [createEventHandler(async (event) => {
+			if (!event) return;
+			if (event.type.startsWith("settings")) return;
+			const revalidatePath = options?.revalidatePath ?? (await import("next/cache")).revalidatePath;
+			const paths = [
+				...await Promise.resolve(options?.paths?.(event) ?? []),
+				...event.data?.url ? [event.data.url] : [],
+				ROBOTS_PATH
+			];
+			for (const path of normalizePaths(paths)) revalidatePath(path);
+			for (const target of resolveSitemapTargets(options?.sitemap)) revalidatePath(normalizePath(target.path), target.type);
+		})] })
+	});
+}
+function resolveSitemapTargets(option) {
+	if (option === false) return [];
+	return (option === void 0 ? [DEFAULT_SITEMAP_TARGET] : Array.isArray(option) ? option : [option]).map((target) => typeof target === "string" ? { path: target } : target);
+}
+function normalizePaths(paths) {
+	return Array.from(new Set((Array.isArray(paths) ? paths : paths ? [paths] : []).map(normalizePath).filter(Boolean)));
+}
+function normalizePath(path) {
+	try {
+		return normalizePath(new URL(path).pathname);
+	} catch {
+		const trimmed = path.trim();
+		if (!trimmed) return "";
+		return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+	}
+}
+
+//#endregion
+export { nextRevalidation };

package/dist/integrations/nextjs/seo.d.ts

@@ -0,0 +1,7 @@
+import { SeoHead } from "../../seo/schema.js";
+import { Metadata } from "next";
+
+//#region src/integrations/nextjs/seo.d.ts
+declare function toMetadata(head: SeoHead): Metadata;
+//#endregion
+export { toMetadata };

package/dist/integrations/nextjs/seo.js

@@ -0,0 +1,41 @@
+//#region src/integrations/nextjs/seo.ts
+function toMetadata(head) {
+	const robots = [
+		head.robots.index,
+		head.robots.follow,
+		head.robots.maxSnippet,
+		head.robots.maxImagePreview,
+		head.robots.maxVideoPreview
+	].join(", ");
+	return {
+		title: { absolute: head.title },
+		description: head.og.description || void 0,
+		alternates: { canonical: head.canonical },
+		robots,
+		openGraph: {
+			type: head.og.type,
+			title: head.og.title,
+			description: head.og.description || void 0,
+			url: head.og.url,
+			siteName: head.og.siteName,
+			locale: head.og.locale,
+			images: head.og.image ? [{
+				url: head.og.image.url,
+				width: head.og.image.width,
+				height: head.og.image.height,
+				alt: head.og.image.alt ?? void 0
+			}] : void 0
+		},
+		twitter: {
+			card: head.twitter.card,
+			title: head.twitter.title,
+			description: head.twitter.description || void 0,
+			site: head.twitter.site ?? void 0,
+			creator: head.twitter.creator ?? void 0,
+			images: head.twitter.image ? [head.twitter.image] : void 0
+		}
+	};
+}
+
+//#endregion
+export { toMetadata };

package/dist/integrations/nextjs/sitemap.d.ts

@@ -0,0 +1,30 @@
+import { S2SClient } from "../../kizlo.js";
+import { CreateSitemapRouteOptions } from "../../seo/sitemap.js";
+
+//#region src/integrations/nextjs/sitemap.d.ts
+
+/**
+ * The Next route the sitemap handler is mounted at: a single dynamic segment named
+ * `[sitemap]`. It is fixed (not configurable) so that one `revalidatePath(SITEMAP_ROUTE,
+ * "page")` refreshes the index and every generated sitemap at once. `[sitemap]` is Next's
+ * file-routing convention, which is why it lives in this integration and not in core.
+ */
+declare const SITEMAP_ROUTE: "/sitemaps/[sitemap]";
+/** Next's dynamic-route context. `params` is a promise in the App Router. */
+interface NextRouteContext {
+  params?: {
+    sitemap?: string;
+  } | Promise<{
+    sitemap?: string;
+  }>;
+}
+/**
+ * Next wrapper around the framework-agnostic {@link createCoreSitemapRoute}. It serves the
+ * same sitemap index and collection pages, and additionally asserts the route is mounted at
+ * {@link SITEMAP_ROUTE}: if the dynamic segment is not named `[sitemap]`, `params.sitemap`
+ * is missing and a wrong mount would silently break `revalidatePath(SITEMAP_ROUTE, "page")`,
+ * so it throws loudly on the first request instead.
+ */
+declare function createSitemapRoute(client: S2SClient<[]>, options?: CreateSitemapRouteOptions): (request: Request, ctx?: NextRouteContext) => Promise<Response>;
+//#endregion
+export { SITEMAP_ROUTE, createSitemapRoute };

package/dist/integrations/nextjs/sitemap.js

@@ -0,0 +1,28 @@
+import { SITEMAP_BASE, createSitemapRoute } from "../../seo/sitemap.js";
+
+//#region src/integrations/nextjs/sitemap.ts
+/**
+* The Next route the sitemap handler is mounted at: a single dynamic segment named
+* `[sitemap]`. It is fixed (not configurable) so that one `revalidatePath(SITEMAP_ROUTE,
+* "page")` refreshes the index and every generated sitemap at once. `[sitemap]` is Next's
+* file-routing convention, which is why it lives in this integration and not in core.
+*/
+const SITEMAP_ROUTE = `${SITEMAP_BASE}/[sitemap]`;
+/**
+* Next wrapper around the framework-agnostic {@link createCoreSitemapRoute}. It serves the
+* same sitemap index and collection pages, and additionally asserts the route is mounted at
+* {@link SITEMAP_ROUTE}: if the dynamic segment is not named `[sitemap]`, `params.sitemap`
+* is missing and a wrong mount would silently break `revalidatePath(SITEMAP_ROUTE, "page")`,
+* so it throws loudly on the first request instead.
+*/
+function createSitemapRoute$1(client, options) {
+	const handler = createSitemapRoute(client, options);
+	return async function GET(request, ctx) {
+		const params = ctx?.params ? await ctx.params : void 0;
+		if (params && params.sitemap === void 0) throw new Error(`createSitemapRoute must be mounted at "${SITEMAP_ROUTE}". The dynamic segment must be named [sitemap].`);
+		return handler(request);
+	};
+}
+
+//#endregion
+export { SITEMAP_ROUTE, createSitemapRoute$1 as createSitemapRoute };

package/dist/nextjs/server.d.ts

@@ -1,2 +1,3 @@
 import { KizloServerOptions, createKizlo } from "../integrations/nextjs/kizlo.server.js";
-export { KizloServerOptions, createKizlo };
+import { SITEMAP_ROUTE, createSitemapRoute } from "../integrations/nextjs/sitemap.js";
+export { KizloServerOptions, SITEMAP_ROUTE, createKizlo, createSitemapRoute };

package/dist/nextjs/server.js

@@ -1,3 +1,4 @@
+import { SITEMAP_ROUTE, createSitemapRoute } from "../integrations/nextjs/sitemap.js";
 import { createKizlo } from "../integrations/nextjs/kizlo.server.js";
 
-export { createKizlo };
+export { SITEMAP_ROUTE, createKizlo, createSitemapRoute };

package/dist/nextjs.d.ts

@@ -1,2 +1,3 @@
 import { KizloClientOptions, createKizloClient } from "./integrations/nextjs/kizlo.client.js";
-export { KizloClientOptions, createKizloClient };
+import { toMetadata } from "./integrations/nextjs/seo.js";
+export { KizloClientOptions, createKizloClient, toMetadata };

package/dist/nextjs.js

@@ -1,3 +1,4 @@
 import { createKizloClient } from "./integrations/nextjs/kizlo.client.js";
+import { toMetadata } from "./integrations/nextjs/seo.js";
 
-export { createKizloClient };
+export { createKizloClient, toMetadata };

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.2.0";
+var version = "0.2.2";
 
 //#endregion
 export { version };

package/dist/router.d.ts

@@ -299,6 +299,53 @@ declare const ROUTER_MAP: {
     }>;
   };
   seo: {
+    homepage: Procedure<"internal", {}, {
+      head: {
+        title: string;
+        canonical: string;
+        robots: {
+          index: string;
+          follow: string;
+          maxSnippet: string;
+          maxImagePreview: string;
+          maxVideoPreview: string;
+        };
+        og: {
+          locale: string;
+          type: string;
+          title: string;
+          url: string;
+          siteName: string;
+          description: string;
+          image: {
+            url: string;
+            width: string;
+            height: string;
+            type: string;
+            alt: string | null;
+          } | null;
+        };
+        twitter: {
+          card: "summary" | "summary_large_image";
+          title: string;
+          site: string | null;
+          creator: string | null;
+          description: string;
+          image: string | null;
+        };
+        article: {
+          publishedTime: string;
+          modifiedTime: string;
+          author: string;
+          authorUrl: string;
+          section: string;
+        } | null;
+      };
+      schema: {
+        "@context": "https://schema.org";
+        "@graph": Record<string, unknown>[];
+      };
+    }, DefinedErrorMapLike>;
     sitemaps: Procedure<"internal", {}, {
       key: string;
       type: "author" | "post_type" | "taxonomy";

package/dist/seo/index.js

@@ -1,9 +1,58 @@
 import { createProcedure } from "../shared/procedure.js";
 import { WP_KIZLO_BASE } from "../wordpress/constants.js";
-import { ListSitemapUrlInput, Robots, SitemapList, SitemapUrlList } from "./schema.js";
+import { ListSitemapUrlInput, Robots, Seo, SitemapList, SitemapUrlList } from "./schema.js";
 
 //#region src/seo/index.ts
 const SEO_ROUTER_MAP = {
+	homepage: createProcedure({
+		scope: "internal",
+		output: Seo
+	}, async ({ context, errors }) => {
+		const response = await context.service.wordpress.get("/seo/homepage", { base: WP_KIZLO_BASE });
+		if (response.error) {
+			context.logger.error("Get homepage seo unhandled error", response.error);
+			throw errors.INTERNAL_SERVER_ERROR();
+		}
+		const { head } = response.data;
+		return {
+			head: {
+				title: head.title,
+				canonical: head.canonical,
+				robots: {
+					index: head.robots.index,
+					follow: head.robots.follow,
+					maxSnippet: head.robots["max-snippet"],
+					maxImagePreview: head.robots["max-image-preview"],
+					maxVideoPreview: head.robots["max-video-preview"]
+				},
+				og: {
+					locale: head.og.locale,
+					type: head.og.type,
+					title: head.og.title,
+					url: head.og.url,
+					siteName: head.og.site_name,
+					description: head.og.description ?? "",
+					image: head.og.image
+				},
+				twitter: {
+					card: head.twitter.card,
+					title: head.twitter.title,
+					site: head.twitter.site,
+					creator: head.twitter.creator,
+					description: head.twitter.description ?? "",
+					image: head.twitter.image
+				},
+				article: head.article && {
+					publishedTime: head.article.published_time,
+					modifiedTime: head.article.modified_time,
+					author: head.article.author,
+					authorUrl: head.article.author_url,
+					section: head.article.section
+				}
+			},
+			schema: response.data.schema
+		};
+	}),
 	sitemaps: createProcedure({
 		scope: "internal",
 		output: SitemapList

package/dist/seo/sitemap.d.ts

@@ -0,0 +1,39 @@
+import { SitemapUrl } from "./schema.js";
+import { SitemapIndexEntry } from "./utils.js";
+import { S2SClient } from "../kizlo.js";
+
+//#region src/seo/sitemap.d.ts
+
+/**
+ * Every generated sitemap is served from `/sitemaps`: the index at `/sitemaps/index.xml`
+ * and each collection page at `/sitemaps/{key}.xml` (later pages `-{n}`). The base is fixed
+ * because the index `<loc>` entries (built by `sitemapEntryPath`) point at it, so the route
+ * must be mounted there for the links to resolve. How the route is mounted is a
+ * framework concern; this handler only cares about the trailing slug.
+ */
+declare const SITEMAP_BASE = "/sitemaps";
+/** Slug that serves the sitemap index (`/sitemaps/index.xml`) rather than a collection. */
+declare const SITEMAP_INDEX_SLUG = "index.xml";
+/**
+ * A sitemap not backed by WordPress (e.g. docs pages living in the app). It joins the
+ * same index/urlset pipeline: `entry` adds it to the index, `urls` serves its pages.
+ */
+interface SitemapRouteExtra {
+  entry: SitemapIndexEntry;
+  urls: (origin: string, page: number) => SitemapUrl[] | Promise<SitemapUrl[]>;
+}
+interface CreateSitemapRouteOptions {
+  /** Extra, non-WordPress sitemaps to fold into the index and serve. */
+  extra?: SitemapRouteExtra[];
+}
+/**
+ * Builds a Web `Request` -> `Response` handler that serves the sitemap index
+ * (`/sitemaps/index.xml`) and every collection page, merging any `extra` sitemaps in.
+ * Framework-agnostic: the slug is the last path segment of the request URL, so this runs
+ * as-is on any web-standard server (Hono, a plain fetch handler, a Next route handler).
+ * Mounting it at the right path is the caller's job; framework wrappers (e.g. the Next
+ * integration) add mount assertions on top.
+ */
+declare function createSitemapRoute(client: S2SClient<[]>, options?: CreateSitemapRouteOptions): (request: Request) => Promise<Response>;
+//#endregion
+export { CreateSitemapRouteOptions, SITEMAP_BASE, SITEMAP_INDEX_SLUG, SitemapRouteExtra, createSitemapRoute };

package/dist/seo/sitemap.js

@@ -0,0 +1,64 @@
+import { parseSitemapSlug, renderSitemapIndex, renderUrlSet, xmlResponse } from "./utils.js";
+
+//#region src/seo/sitemap.ts
+/**
+* Every generated sitemap is served from `/sitemaps`: the index at `/sitemaps/index.xml`
+* and each collection page at `/sitemaps/{key}.xml` (later pages `-{n}`). The base is fixed
+* because the index `<loc>` entries (built by `sitemapEntryPath`) point at it, so the route
+* must be mounted there for the links to resolve. How the route is mounted is a
+* framework concern; this handler only cares about the trailing slug.
+*/
+const SITEMAP_BASE = "/sitemaps";
+/** Slug that serves the sitemap index (`/sitemaps/index.xml`) rather than a collection. */
+const SITEMAP_INDEX_SLUG = "index.xml";
+/**
+* Builds a Web `Request` -> `Response` handler that serves the sitemap index
+* (`/sitemaps/index.xml`) and every collection page, merging any `extra` sitemaps in.
+* Framework-agnostic: the slug is the last path segment of the request URL, so this runs
+* as-is on any web-standard server (Hono, a plain fetch handler, a Next route handler).
+* Mounting it at the right path is the caller's job; framework wrappers (e.g. the Next
+* integration) add mount assertions on top.
+*/
+function createSitemapRoute(client, options) {
+	const extra = options?.extra ?? [];
+	return async function GET(request) {
+		const url = new URL(request.url);
+		const slug = lastPathSegment(url);
+		if (!slug) return notFound();
+		const { origin } = url;
+		if (slug === SITEMAP_INDEX_SLUG) {
+			const { data: data$1 } = await client.seo.sitemaps();
+			return xmlResponse(renderSitemapIndex([...data$1 ?? [], ...extra.map((item) => item.entry)], origin));
+		}
+		const parsed = parseSitemapSlug(slug);
+		if (!parsed) return notFound();
+		const custom = extra.find((item) => item.entry.key === parsed.key);
+		if (custom) {
+			if (parsed.page > custom.entry.pages) return notFound();
+			return xmlResponse(renderUrlSet(await custom.urls(origin, parsed.page)));
+		}
+		const { data: sitemaps } = await client.seo.sitemaps();
+		if (!sitemaps) return notFound();
+		const entry = sitemaps.find((item) => item.key === parsed.key);
+		if (!entry || parsed.page > entry.pages) return notFound();
+		const { data } = await client.seo.urls(entry.type === "author" ? {
+			type: "author",
+			page: parsed.page
+		} : {
+			type: entry.type,
+			key: entry.key,
+			page: parsed.page
+		});
+		if (!data) return notFound();
+		return xmlResponse(renderUrlSet(data));
+	};
+}
+function lastPathSegment(url) {
+	return decodeURIComponent(url.pathname.split("/").filter(Boolean).pop() ?? "");
+}
+function notFound() {
+	return new Response("Not Found", { status: 404 });
+}
+
+//#endregion
+export { SITEMAP_BASE, SITEMAP_INDEX_SLUG, createSitemapRoute };

package/dist/seo/utils.d.ts

@@ -0,0 +1,6 @@
+import { Sitemap } from "./schema.js";
+
+//#region src/seo/utils.d.ts
+type SitemapIndexEntry = Pick<Sitemap, "key" | "pages" | "lastmod">;
+//#endregion
+export { SitemapIndexEntry };

package/dist/seo/utils.js

@@ -39,6 +39,41 @@ function deserializeSeo(data) {
 		schema: data.schema
 	};
 }
+function sitemapEntryPath(key, page) {
+	return `/sitemaps/${key}${page > 1 ? `-${page}` : ""}.xml`;
+}
+function parseSitemapSlug(slug) {
+	const match = /^(.+?)(?:-(\d+))?\.xml$/.exec(slug);
+	if (!match) return null;
+	const [, key, rawPage] = match;
+	const page = rawPage ? Number(rawPage) : 1;
+	if (!key || !Number.isInteger(page) || page < 1) return null;
+	return {
+		key,
+		page
+	};
+}
+function escapeXml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function renderSitemapIndex(sitemaps, origin) {
+	return `<?xml version="1.0" encoding="UTF-8"?>\n<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${sitemaps.flatMap((sitemap) => Array.from({ length: sitemap.pages }, (_, index) => {
+		return `\t<sitemap>\n\t\t<loc>${escapeXml(`${origin}${sitemapEntryPath(sitemap.key, index + 1)}`)}</loc>\n\t\t<lastmod>${escapeXml(sitemap.lastmod)}</lastmod>\n\t</sitemap>`;
+	})).join("\n")}\n</sitemapindex>\n`;
+}
+function renderUrlSet(urls) {
+	return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">\n${urls.map((url) => {
+		const images = url.images.map((image) => `\t\t<image:image>\n\t\t\t<image:loc>${escapeXml(image.loc)}</image:loc>\n\t\t</image:image>`).join("\n");
+		const imageBlock = images ? `\n${images}` : "";
+		return `\t<url>\n\t\t<loc>${escapeXml(url.loc)}</loc>\n\t\t<lastmod>${escapeXml(url.lastmod)}</lastmod>${imageBlock}\n\t</url>`;
+	}).join("\n")}\n</urlset>\n`;
+}
+function xmlResponse(body) {
+	return new Response(body, { headers: {
+		"Content-Type": "application/xml; charset=utf-8",
+		"Cache-Control": "public, max-age=0, s-maxage=3600, stale-while-revalidate=86400"
+	} });
+}
 
 //#endregion
-export { deserializeSeo };
+export { deserializeSeo, parseSitemapSlug, renderSitemapIndex, renderUrlSet, xmlResponse };

package/dist/settings/service.interface.d.ts

@@ -17,6 +17,7 @@ interface KizloSiteSettings {
   title_separator: string;
   fallback_image: KizloMedia | null;
   search_action_structure: string | null;
+  discourage_search_engines: boolean;
 }
 interface KizloPersonSettings {
   name: string;

package/dist/shared/error.d.ts

@@ -1,4 +1,4 @@
-import { AnySchema, LiteralUnion, Metadata, SchemaInput, SchemaOutput } from "@kizlo/shared";
+import { LiteralUnion, Metadata, Schema, SchemaInput, SchemaOutput } from "@kizlo/shared";
 
 //#region src/shared/error.d.ts
 declare const COMMON_ERRORS: {
@@ -116,11 +116,11 @@ type ErrorDefinition = {
   /** Human-readable message. Overridable per throw via `errors.CODE({ message })`. */
   message?: string;
   /** Standard Schema for the error's `data` payload — validated and typed when you throw `errors.CODE({ data })`. */
-  data?: AnySchema;
+  data?: Schema;
 };
 declare function defineErrorMap<const T extends Partial<Record<CommonErrorLiteral, ErrorDefinition>>>(map: T): T;
 type DefinedErrorMapLike = Record<string, ErrorDefinition>;
-type ThrowableErrorFn<TCode extends string, T extends ErrorDefinition> = T["data"] extends AnySchema ? undefined extends SchemaInput<T["data"]> ? (options?: {
+type ThrowableErrorFn<TCode extends string, T extends ErrorDefinition> = T["data"] extends Schema ? undefined extends SchemaInput<T["data"]> ? (options?: {
   status?: number;
   message?: string;
   data?: SchemaInput<T["data"]>;

package/dist/shared/procedure.d.ts

@@ -2,7 +2,7 @@ import { DefinedErrorMapLike, ThrowableErrorMap, WithCommonErrorMap } from "./er
 import { ServerContext } from "../context.js";
 import { AnyMiddleware, InferUses, Middleware } from "./middleware.js";
 import * as _orpc_contract0 from "@orpc/contract";
-import { AnySchema, DeepMerge, Pathname, Prettify, Promisify, Schema, SchemaInput, SchemaOutput } from "@kizlo/shared";
+import { DeepMerge, Pathname, Prettify, Promisify, Schema, SchemaInput, SchemaOutput } from "@kizlo/shared";
 import * as _orpc_server0 from "@orpc/server";
 import { HTTPMethod } from "@orpc/server";
 import { JsonifiedValue } from "@orpc/openapi-client";
@@ -33,25 +33,25 @@ interface Procedure<TScope extends InvocationScope, TInput, TOutput, TError exte
     options: {
       scope: TScope;
       errors?: TError;
-      output: AnySchema;
+      output: Schema;
       inputValidation?: boolean;
       outputValidation?: boolean;
       middlewares?: AnyMiddleware[];
     } & ({
       scope: "internal";
-      input?: AnySchema;
+      input?: Schema;
     } | {
       scope: "remote";
-      input?: AnySchema;
+      input?: Schema;
       method?: HTTPMethod;
     } | {
       scope: "api";
       method?: HTTPMethod;
       path?: Pathname;
-      body?: AnySchema;
-      query?: AnySchema;
-      params?: AnySchema;
-      headers?: AnySchema;
+      body?: Schema;
+      query?: Schema;
+      params?: Schema;
+      headers?: Schema;
     });
   };
 }
@@ -112,9 +112,9 @@ type ProcedureOptions<TScope extends InvocationScope, TPathname extends Pathname
   input?: TInput;
 });
 declare function createProcedure<TScope extends InvocationScope, TPathname extends Pathname, TInput extends Schema | undefined = undefined, TBody extends Schema | undefined = undefined, TParams extends Schema | undefined = undefined, TQuery extends Schema | undefined = undefined, THeaders extends Schema | undefined = undefined, TOutput extends Schema = Schema, TError extends DefinedErrorMapLike = DefinedErrorMapLike, TMiddlewares extends Middleware<ResolvedSchemaOutput<TScope, TPathname, TInput, TBody, TParams, TQuery, THeaders>, SchemaOutput<TOutput>, TError>[] = Middleware<ResolvedSchemaOutput<TScope, TPathname, TInput, TBody, TParams, TQuery, THeaders>, SchemaOutput<TOutput>, TError>[], TContext extends ProcedureContext<TMiddlewares> = ProcedureContext<TMiddlewares>>(options: ProcedureOptions<TScope, TPathname, TInput, TBody, TParams, TQuery, THeaders, TOutput, TError, TMiddlewares>, handler: ProcedureHandler<ResolvedSchemaOutput<TScope, TPathname, TInput, TBody, TParams, TQuery, THeaders>, SchemaOutput<TOutput>, TError, TContext>): Procedure<TScope, ResolvedSchemaInput<TScope, TPathname, TInput, TBody, TParams, TQuery, THeaders>, TScope extends "api" ? JsonifiedValue<SchemaOutput<TOutput>> : SchemaOutput<TOutput>, TError>;
-declare function schemaType<TInput, TOutput = TInput>(schema?: AnySchema): Schema<TInput, TOutput>;
+declare function schemaType<TInput, TOutput = TInput>(schema?: Schema): Schema<TInput, TOutput>;
 declare function buildProcedure(procedure: AnyProcedure): _orpc_server0.DecoratedProcedure<_orpc_server0.Context & Record<never, never>, _orpc_server0.Context, _orpc_contract0.Schema<unknown, unknown>, _orpc_contract0.Schema<any, any>, Record<never, never>, Record<never, never>>;
 declare function handleUnexpectedError(error: unknown, errors?: DefinedErrorMapLike): never;
-declare function combineDetailed(parts: Record<string, AnySchema>): AnySchema;
+declare function combineDetailed(parts: Record<string, Schema>): Schema;
 //#endregion
 export { AnyProcedure, AnyProcedureRouter, BaseHandlerOptions, ExtractParams, ExtractProcedureByScope, InvocationScope, OpenapiPart, Procedure, ProcedureContext, ProcedureErrors, ProcedureHandler, ProcedureOptions, ResolveParamsPart, ResolvedSchemaInput, ResolvedSchemaOutput, RouterDepthTuple, SchemaIO, buildProcedure, combineDetailed, createProcedure, handleUnexpectedError, schemaType };

package/dist/webhook/schema.d.ts

@@ -12,6 +12,7 @@ declare const KizloEvent: z.ZodUnion<readonly [z.ZodObject<{
   data: z.ZodObject<{
     post_id: z.ZodNumber;
     post_type: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
   type: z.ZodEnum<{
@@ -24,15 +25,7 @@ declare const KizloEvent: z.ZodUnion<readonly [z.ZodObject<{
     taxonomy: z.ZodString;
     post_types: z.ZodArray<z.ZodString>;
     count: z.ZodNumber;
-  }, z.core.$strip>;
-}, z.core.$strip>, z.ZodObject<{
-  type: z.ZodEnum<{
-    "payment.status_requested": "payment.status_requested";
-  }>;
-  data: z.ZodObject<{
-    transaction_id: z.ZodNullable<z.ZodString>;
-    payment_method_id: z.ZodString;
-    payment_session_id: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
   type: z.ZodEnum<{

package/dist/webhook/schema.js

@@ -27,7 +27,8 @@ const EVENT_TYPES = [
 const EventType = z.enum(EVENT_TYPES);
 const PostEventData = z.object({
 	post_id: z.number(),
-	post_type: z.string()
+	post_type: z.string(),
+	url: z.string().optional()
 });
 const PostEvent = z.object({
 	type: PostEventType,
@@ -37,21 +38,13 @@ const TermEventData = z.object({
 	term_id: z.number(),
 	taxonomy: z.string(),
 	post_types: z.array(z.string()),
-	count: z.number().nonnegative()
+	count: z.number().nonnegative(),
+	url: z.string().optional()
 });
 const TermEvent = z.object({
 	type: TermEventType,
 	data: TermEventData
 });
-const PaymentEventData = z.object({
-	transaction_id: z.nullable(z.string()),
-	payment_method_id: z.string(),
-	payment_session_id: z.string()
-});
-const PaymentEvent = z.object({
-	type: PaymentEventType,
-	data: PaymentEventData
-});
 const SettingsEventData = z.null();
 const SettingsEvent = z.object({
 	type: SettingsEventType,
@@ -60,7 +53,6 @@ const SettingsEvent = z.object({
 const KizloEvent = z.union([
 	PostEvent,
 	TermEvent,
-	PaymentEvent,
 	SettingsEvent
 ]);
 const AnyEvent = z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kizlo",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "description": "A headless WordPress toolkit for TypeScript.",
   "keywords": [
@@ -76,7 +76,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.5.1",
-    "@kizlo/shared": "0.1.1",
+    "@kizlo/shared": "0.1.2",
     "@orpc/client": "^1.14.3",
     "@orpc/contract": "^1.14.3",
     "@orpc/openapi": "^1.14.3",