@classytic/arc 2.22.0 → 2.25.0

package/dist/auth/index.mjs

@@ -1,7 +1,8 @@
 import { d as createDomainError, l as UnauthorizedError, p as isArcError, t as ArcError } from "../errors-DkO8Nk6-.mjs";
-import { h as requireOrgRole, m as requireOrgMembership, v as requireTeamMembership } from "../permissions-BJMuKMl7.mjs";
-import { n as normalizeRoles, t as getUserRoles } from "../types-XTApa8b6.mjs";
-import { o as toJsonSchema } from "../schemaConverter-Ds5reSGs.mjs";
+import { n as requireSingleHeaderValue } from "../headers-BvlQSDMB.mjs";
+import { n as getUserRoles, r as normalizeRoles } from "../userHelpers-Cg_y3fBz.mjs";
+import { o as toJsonSchema } from "../schemaConverter-DJvodiHj.mjs";
+import { _ as requireOrgMembership, v as requireOrgRole, x as requireTeamMembership } from "../permissions-BrtiBKGs.mjs";
 import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
 import fp from "fastify-plugin";
 //#region src/auth/authPlugin.ts
@@ -289,6 +290,253 @@ var authPlugin_default = fp(authPlugin, {
 	fastify: "5.x"
 });
 //#endregion
+//#region src/auth/betterAuthOpenApi.ts
+/**
+* Check if a value looks like a Better Auth endpoint (has .path and .options)
+*/
+function isBetterAuthEndpoint(value) {
+	if (typeof value !== "function" && typeof value !== "object") return false;
+	if (!value) return false;
+	const v = value;
+	return typeof v.path === "string" && typeof v.options === "object" && v.options !== null;
+}
+/**
+* Convert Fastify-style path params (/:id) to OpenAPI-style (/{id})
+*/
+function toOpenApiPath(path) {
+	return path.replace(/:([^/]+)/g, "{$1}");
+}
+/**
+* Extract path parameters from a path string
+*/
+function extractPathParams(path) {
+	const params = [];
+	const matches = path.matchAll(/:(\w+)/g);
+	for (const match of matches) {
+		const name = match[1];
+		if (!name) continue;
+		params.push({
+			name,
+			in: "path",
+			required: true,
+			schema: { type: "string" }
+		});
+	}
+	return params;
+}
+/**
+* Extract OpenAPI paths from a Better Auth instance's API object.
+*
+* Walks `authApi` (the `auth.api` object from Better Auth), discovers
+* endpoints, converts their Zod schemas to JSON Schema via `z.toJSONSchema()`,
+* and returns a complete `ExternalOpenApiPaths` object ready for Arc's spec builder.
+*/
+function extractBetterAuthOpenApi(authApi, options = {}) {
+	const { basePath = "/api/auth", tagName = "Authentication", tagDescription = "Better Auth authentication endpoints", excludePaths = [], excludeServerOnly = true, userFields } = options;
+	const normalizedBase = basePath.replace(/\/+$/, "");
+	const paths = {};
+	const detectedPlugins = detectActivePlugins(authApi);
+	const securityOptions = [{ cookieAuth: [] }, { bearerAuth: [] }];
+	if (detectedPlugins.apiKey) securityOptions.push({ apiKeyAuth: [] });
+	for (const [key, value] of Object.entries(authApi)) {
+		if (!isBetterAuthEndpoint(value)) continue;
+		const { path: endpointPath, options: endpointOpts } = value;
+		if (excludePaths.includes(endpointPath)) continue;
+		if (excludeServerOnly && endpointOpts.metadata?.SERVER_ONLY) continue;
+		const fullPath = toOpenApiPath(`${normalizedBase}${endpointPath}`);
+		const methods = [];
+		if (endpointOpts.method) if (Array.isArray(endpointOpts.method)) methods.push(...endpointOpts.method.map((m) => m.toLowerCase()));
+		else methods.push(endpointOpts.method.toLowerCase());
+		else methods.push(endpointOpts.body ? "post" : "get");
+		const openApiMeta = endpointOpts.metadata?.openapi;
+		for (const method of methods) {
+			const operation = {
+				tags: openApiMeta?.tags ?? [tagName],
+				operationId: openApiMeta?.operationId ?? key,
+				summary: openApiMeta?.summary ?? formatOperationSummary(key),
+				security: securityOptions
+			};
+			if (openApiMeta?.description) operation.description = openApiMeta.description;
+			const parameters = [...extractPathParams(endpointPath)];
+			if ((method === "get" || method === "delete") && endpointOpts.query) {
+				const querySchema = toJsonSchema(endpointOpts.query);
+				if (querySchema && querySchema.type === "object" && querySchema.properties) {
+					const props = querySchema.properties;
+					const required = querySchema.required ?? [];
+					for (const [name, prop] of Object.entries(props)) {
+						const paramEntry = {
+							name,
+							in: "query",
+							required: required.includes(name),
+							schema: prop
+						};
+						if (prop.description) paramEntry.description = prop.description;
+						parameters.push(paramEntry);
+					}
+				}
+			}
+			if (parameters.length > 0) operation.parameters = parameters;
+			if (method === "post" || method === "put" || method === "patch") {
+				if (openApiMeta?.requestBody) operation.requestBody = structuredClone(openApiMeta.requestBody);
+				else if (endpointOpts.body) {
+					const bodySchema = toJsonSchema(endpointOpts.body);
+					if (bodySchema) operation.requestBody = {
+						required: true,
+						content: { "application/json": { schema: bodySchema } }
+					};
+				}
+				if (userFields && isUserFieldEndpoint(endpointPath) && operation.requestBody) mergeUserFieldsIntoRequestBody(operation.requestBody, userFields, endpointPath);
+			}
+			if (openApiMeta?.responses) operation.responses = openApiMeta.responses;
+			else operation.responses = {
+				"200": { description: "Success" },
+				"400": { description: "Bad request" },
+				"401": { description: "Unauthorized" }
+			};
+			if (!paths[fullPath]) paths[fullPath] = {};
+			paths[fullPath][method] = operation;
+		}
+	}
+	const schemas = {
+		User: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				name: { type: "string" },
+				email: {
+					type: "string",
+					format: "email"
+				},
+				emailVerified: { type: "boolean" },
+				image: {
+					type: "string",
+					nullable: true
+				},
+				createdAt: {
+					type: "string",
+					format: "date-time"
+				},
+				updatedAt: {
+					type: "string",
+					format: "date-time"
+				}
+			}
+		},
+		Session: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				userId: { type: "string" },
+				token: { type: "string" },
+				expiresAt: {
+					type: "string",
+					format: "date-time"
+				},
+				ipAddress: {
+					type: "string",
+					nullable: true
+				},
+				userAgent: {
+					type: "string",
+					nullable: true
+				},
+				createdAt: {
+					type: "string",
+					format: "date-time"
+				},
+				updatedAt: {
+					type: "string",
+					format: "date-time"
+				}
+			}
+		}
+	};
+	if (userFields) {
+		const userProps = schemas.User?.properties;
+		for (const [name, field] of Object.entries(userFields)) {
+			const prop = { type: field.type };
+			if (field.description) prop.description = field.description;
+			userProps[name] = prop;
+		}
+	}
+	const securitySchemes = { cookieAuth: {
+		type: "apiKey",
+		in: "cookie",
+		name: "better-auth.session_token",
+		description: "Session cookie set by Better Auth after sign-in"
+	} };
+	if (detectedPlugins.apiKey) securitySchemes.apiKeyAuth = {
+		type: "apiKey",
+		in: "header",
+		name: "x-api-key",
+		description: "API key for programmatic access. Pass org context via x-organization-id header."
+	};
+	const resourceSecurity = [];
+	if (detectedPlugins.apiKey) resourceSecurity.push({
+		apiKeyAuth: [],
+		orgHeader: []
+	});
+	return {
+		paths,
+		schemas,
+		securitySchemes,
+		tags: [{
+			name: tagName,
+			description: tagDescription
+		}],
+		resourceSecurity: resourceSecurity.length > 0 ? resourceSecurity : void 0
+	};
+}
+/**
+* Auto-detect active Better Auth plugins by inspecting the API object.
+*
+* Rather than hardcoding plugin-specific behavior, we check for known
+* endpoint signatures that each plugin registers. This way the OpenAPI
+* spec adapts automatically to whatever plugins the app has enabled —
+* no Arc update needed when adding/removing plugins.
+*/
+function detectActivePlugins(authApi) {
+	const endpointPaths = /* @__PURE__ */ new Set();
+	for (const value of Object.values(authApi)) if (isBetterAuthEndpoint(value)) endpointPaths.add(value.path);
+	return {
+		apiKey: endpointPaths.has("/api-key/create"),
+		organization: endpointPaths.has("/organization/create")
+	};
+}
+/**
+* Convert a camelCase key like 'signInEmail' to a readable summary like 'Sign in email'
+*/
+function formatOperationSummary(key) {
+	return key.replace(/([A-Z])/g, " $1").replace(/^./, (s) => s.toUpperCase()).trim();
+}
+/**
+* Check if an endpoint path should have userFields merged into its request body.
+*/
+function isUserFieldEndpoint(path) {
+	return path === "/sign-up/email" || path === "/update-user";
+}
+/**
+* Merge user-defined fields into an existing requestBody schema.
+* For updateUser, all fields are treated as optional regardless of their `required` setting.
+*/
+function mergeUserFieldsIntoRequestBody(requestBody, userFields, endpointPath) {
+	const content = requestBody?.content?.["application/json"];
+	if (!content?.schema) return;
+	const schema = content.schema;
+	if (!schema.properties) schema.properties = {};
+	if (!schema.required) schema.required = [];
+	const props = schema.properties;
+	const required = schema.required;
+	for (const [name, field] of Object.entries(userFields)) {
+		if (field.input === false) continue;
+		const isRequired = endpointPath === "/update-user" ? false : field.required ?? false;
+		const prop = { type: field.type };
+		if (field.description) prop.description = field.description;
+		props[name] = prop;
+		if (isRequired && !required.includes(name)) required.push(name);
+	}
+}
+//#endregion
 //#region src/auth/betterAuth.ts
 /**
 * Convert a Fastify request into a Fetch API Request.
@@ -532,7 +780,8 @@ function createBetterAuthAdapter(options) {
 			};
 			if (orgEnabled) {
 				const session = sessionData.session;
-				const activeOrgId = session?.activeOrganizationId || request.headers["x-organization-id"];
+				const requestedOrgId = requireSingleHeaderValue(request.headers, "x-organization-id");
+				const activeOrgId = session?.activeOrganizationId || requestedOrgId;
 				if (activeOrgId) {
 					let orgRoles = await getActiveMemberRoles(auth, headers);
 					if (!orgRoles) orgRoles = await getMemberRolesByOrg(auth, headers, activeOrgId);
@@ -553,6 +802,7 @@ function createBetterAuthAdapter(options) {
 				}
 			}
 		} catch (err) {
+			if (err instanceof ArcError) throw err;
 			const message = exposeAuthErrors ? err instanceof Error ? err.message : String(err) : "Authentication required";
 			reply.code(401).send({
 				code: "arc.unauthorized",
@@ -586,7 +836,9 @@ function createBetterAuthAdapter(options) {
 				userRoles: optUserRoles
 			};
 			if (orgEnabled) {
-				const activeOrgId = sessionData.session?.activeOrganizationId || request.headers["x-organization-id"];
+				const session = sessionData.session;
+				const requestedOrgId = requireSingleHeaderValue(request.headers, "x-organization-id");
+				const activeOrgId = session?.activeOrganizationId || requestedOrgId;
 				if (activeOrgId) {
 					let orgRoles = await getActiveMemberRoles(auth, headers);
 					if (!orgRoles) orgRoles = await getMemberRolesByOrg(auth, headers, activeOrgId);
@@ -599,7 +851,9 @@ function createBetterAuthAdapter(options) {
 					};
 				}
 			}
-		} catch {}
+		} catch (err) {
+			if (err instanceof ArcError) throw err;
+		}
 	};
 	let extractedOpenApi;
 	if (openapiOpt === false) extractedOpenApi = void 0;
@@ -622,13 +876,10 @@ function createBetterAuthAdapter(options) {
 		if (!fastify.hasDecorator("optionalAuthenticate")) fastify.decorate("optionalAuthenticate", optionalAuthenticate);
 		if (!fastify.hasRequestDecorator("user")) fastify.decorateRequest("user", void 0);
 		if (!fastify.hasRequestDecorator("session")) fastify.decorateRequest("session", void 0);
-		if (!extractedOpenApi && openapiOpt !== false && auth.api && typeof auth.api === "object") {
-			const { extractBetterAuthOpenApi } = await import("../betterAuthOpenApi-CV1lxpRX.mjs");
-			extractedOpenApi = extractBetterAuthOpenApi(auth.api, {
-				basePath,
-				userFields
-			});
-		}
+		if (!extractedOpenApi && openapiOpt !== false && auth.api && typeof auth.api === "object") extractedOpenApi = extractBetterAuthOpenApi(auth.api, {
+			basePath,
+			userFields
+		});
 		if (extractedOpenApi) {
 			const arc = fastify.arc;
 			if (arc?.externalOpenApiPaths) arc.externalOpenApiPaths.push(extractedOpenApi);
@@ -651,253 +902,6 @@ function createBetterAuthAdapter(options) {
 	};
 }
 //#endregion
-//#region src/auth/betterAuthOpenApi.ts
-/**
-* Check if a value looks like a Better Auth endpoint (has .path and .options)
-*/
-function isBetterAuthEndpoint(value) {
-	if (typeof value !== "function" && typeof value !== "object") return false;
-	if (!value) return false;
-	const v = value;
-	return typeof v.path === "string" && typeof v.options === "object" && v.options !== null;
-}
-/**
-* Convert Fastify-style path params (/:id) to OpenAPI-style (/{id})
-*/
-function toOpenApiPath(path) {
-	return path.replace(/:([^/]+)/g, "{$1}");
-}
-/**
-* Extract path parameters from a path string
-*/
-function extractPathParams(path) {
-	const params = [];
-	const matches = path.matchAll(/:(\w+)/g);
-	for (const match of matches) {
-		const name = match[1];
-		if (!name) continue;
-		params.push({
-			name,
-			in: "path",
-			required: true,
-			schema: { type: "string" }
-		});
-	}
-	return params;
-}
-/**
-* Extract OpenAPI paths from a Better Auth instance's API object.
-*
-* Walks `authApi` (the `auth.api` object from Better Auth), discovers
-* endpoints, converts their Zod schemas to JSON Schema via `z.toJSONSchema()`,
-* and returns a complete `ExternalOpenApiPaths` object ready for Arc's spec builder.
-*/
-function extractBetterAuthOpenApi(authApi, options = {}) {
-	const { basePath = "/api/auth", tagName = "Authentication", tagDescription = "Better Auth authentication endpoints", excludePaths = [], excludeServerOnly = true, userFields } = options;
-	const normalizedBase = basePath.replace(/\/+$/, "");
-	const paths = {};
-	const detectedPlugins = detectActivePlugins(authApi);
-	const securityOptions = [{ cookieAuth: [] }, { bearerAuth: [] }];
-	if (detectedPlugins.apiKey) securityOptions.push({ apiKeyAuth: [] });
-	for (const [key, value] of Object.entries(authApi)) {
-		if (!isBetterAuthEndpoint(value)) continue;
-		const { path: endpointPath, options: endpointOpts } = value;
-		if (excludePaths.includes(endpointPath)) continue;
-		if (excludeServerOnly && endpointOpts.metadata?.SERVER_ONLY) continue;
-		const fullPath = toOpenApiPath(`${normalizedBase}${endpointPath}`);
-		const methods = [];
-		if (endpointOpts.method) if (Array.isArray(endpointOpts.method)) methods.push(...endpointOpts.method.map((m) => m.toLowerCase()));
-		else methods.push(endpointOpts.method.toLowerCase());
-		else methods.push(endpointOpts.body ? "post" : "get");
-		const openApiMeta = endpointOpts.metadata?.openapi;
-		for (const method of methods) {
-			const operation = {
-				tags: openApiMeta?.tags ?? [tagName],
-				operationId: openApiMeta?.operationId ?? key,
-				summary: openApiMeta?.summary ?? formatOperationSummary(key),
-				security: securityOptions
-			};
-			if (openApiMeta?.description) operation.description = openApiMeta.description;
-			const parameters = [...extractPathParams(endpointPath)];
-			if ((method === "get" || method === "delete") && endpointOpts.query) {
-				const querySchema = toJsonSchema(endpointOpts.query);
-				if (querySchema && querySchema.type === "object" && querySchema.properties) {
-					const props = querySchema.properties;
-					const required = querySchema.required ?? [];
-					for (const [name, prop] of Object.entries(props)) {
-						const paramEntry = {
-							name,
-							in: "query",
-							required: required.includes(name),
-							schema: prop
-						};
-						if (prop.description) paramEntry.description = prop.description;
-						parameters.push(paramEntry);
-					}
-				}
-			}
-			if (parameters.length > 0) operation.parameters = parameters;
-			if (method === "post" || method === "put" || method === "patch") {
-				if (openApiMeta?.requestBody) operation.requestBody = structuredClone(openApiMeta.requestBody);
-				else if (endpointOpts.body) {
-					const bodySchema = toJsonSchema(endpointOpts.body);
-					if (bodySchema) operation.requestBody = {
-						required: true,
-						content: { "application/json": { schema: bodySchema } }
-					};
-				}
-				if (userFields && isUserFieldEndpoint(endpointPath) && operation.requestBody) mergeUserFieldsIntoRequestBody(operation.requestBody, userFields, endpointPath);
-			}
-			if (openApiMeta?.responses) operation.responses = openApiMeta.responses;
-			else operation.responses = {
-				"200": { description: "Success" },
-				"400": { description: "Bad request" },
-				"401": { description: "Unauthorized" }
-			};
-			if (!paths[fullPath]) paths[fullPath] = {};
-			paths[fullPath][method] = operation;
-		}
-	}
-	const schemas = {
-		User: {
-			type: "object",
-			properties: {
-				id: { type: "string" },
-				name: { type: "string" },
-				email: {
-					type: "string",
-					format: "email"
-				},
-				emailVerified: { type: "boolean" },
-				image: {
-					type: "string",
-					nullable: true
-				},
-				createdAt: {
-					type: "string",
-					format: "date-time"
-				},
-				updatedAt: {
-					type: "string",
-					format: "date-time"
-				}
-			}
-		},
-		Session: {
-			type: "object",
-			properties: {
-				id: { type: "string" },
-				userId: { type: "string" },
-				token: { type: "string" },
-				expiresAt: {
-					type: "string",
-					format: "date-time"
-				},
-				ipAddress: {
-					type: "string",
-					nullable: true
-				},
-				userAgent: {
-					type: "string",
-					nullable: true
-				},
-				createdAt: {
-					type: "string",
-					format: "date-time"
-				},
-				updatedAt: {
-					type: "string",
-					format: "date-time"
-				}
-			}
-		}
-	};
-	if (userFields) {
-		const userProps = schemas.User?.properties;
-		for (const [name, field] of Object.entries(userFields)) {
-			const prop = { type: field.type };
-			if (field.description) prop.description = field.description;
-			userProps[name] = prop;
-		}
-	}
-	const securitySchemes = { cookieAuth: {
-		type: "apiKey",
-		in: "cookie",
-		name: "better-auth.session_token",
-		description: "Session cookie set by Better Auth after sign-in"
-	} };
-	if (detectedPlugins.apiKey) securitySchemes.apiKeyAuth = {
-		type: "apiKey",
-		in: "header",
-		name: "x-api-key",
-		description: "API key for programmatic access. Pass org context via x-organization-id header."
-	};
-	const resourceSecurity = [];
-	if (detectedPlugins.apiKey) resourceSecurity.push({
-		apiKeyAuth: [],
-		orgHeader: []
-	});
-	return {
-		paths,
-		schemas,
-		securitySchemes,
-		tags: [{
-			name: tagName,
-			description: tagDescription
-		}],
-		resourceSecurity: resourceSecurity.length > 0 ? resourceSecurity : void 0
-	};
-}
-/**
-* Auto-detect active Better Auth plugins by inspecting the API object.
-*
-* Rather than hardcoding plugin-specific behavior, we check for known
-* endpoint signatures that each plugin registers. This way the OpenAPI
-* spec adapts automatically to whatever plugins the app has enabled —
-* no Arc update needed when adding/removing plugins.
-*/
-function detectActivePlugins(authApi) {
-	const endpointPaths = /* @__PURE__ */ new Set();
-	for (const value of Object.values(authApi)) if (isBetterAuthEndpoint(value)) endpointPaths.add(value.path);
-	return {
-		apiKey: endpointPaths.has("/api-key/create"),
-		organization: endpointPaths.has("/organization/create")
-	};
-}
-/**
-* Convert a camelCase key like 'signInEmail' to a readable summary like 'Sign in email'
-*/
-function formatOperationSummary(key) {
-	return key.replace(/([A-Z])/g, " $1").replace(/^./, (s) => s.toUpperCase()).trim();
-}
-/**
-* Check if an endpoint path should have userFields merged into its request body.
-*/
-function isUserFieldEndpoint(path) {
-	return path === "/sign-up/email" || path === "/update-user";
-}
-/**
-* Merge user-defined fields into an existing requestBody schema.
-* For updateUser, all fields are treated as optional regardless of their `required` setting.
-*/
-function mergeUserFieldsIntoRequestBody(requestBody, userFields, endpointPath) {
-	const content = requestBody?.content?.["application/json"];
-	if (!content?.schema) return;
-	const schema = content.schema;
-	if (!schema.properties) schema.properties = {};
-	if (!schema.required) schema.required = [];
-	const props = schema.properties;
-	const required = schema.required;
-	for (const [name, field] of Object.entries(userFields)) {
-		if (field.input === false) continue;
-		const isRequired = endpointPath === "/update-user" ? false : field.required ?? false;
-		const prop = { type: field.type };
-		if (field.description) prop.description = field.description;
-		props[name] = prop;
-		if (isRequired && !required.includes(name)) required.push(name);
-	}
-}
-//#endregion
 //#region src/auth/sessionManager.ts
 /**
 * Session Management for Arc

package/dist/{buildHandler-D_2ULWxZ.mjs → buildHandler-Dtwd8fdz.mjs}

@@ -1,4 +1,4 @@
-import { i as compileAggRequest, t as adapterSupportsAggregate } from "./validate-C2mGgSXg.mjs";
+import { i as compileAggRequest, t as adapterSupportsAggregate } from "./validate-Bk44F2yT.mjs";
 //#region src/core/aggregation/buildHandler.ts
 /**
 * Framework-agnostic aggregation execution. Runs safety guards,

package/dist/cache/index.d.mts

@@ -1,6 +1,6 @@
-import { n as CacheStats, r as CacheStore, t as CacheLogger } from "../interface-C1_WLTMK.mjs";
-import { a as QueryCacheConfig, i as QueryCache, n as CacheResult, r as CacheStatus, t as CacheEnvelope } from "../QueryCache-Z1B38koh.mjs";
-import { i as queryCachePlugin, n as QueryCacheDefaults, r as QueryCachePluginOptions, t as CrossResourceRule } from "../queryCachePlugin-CfYWq-Ak.mjs";
+import { n as CacheStats, r as CacheStore, t as CacheLogger } from "../interface-BGZCzOGL.mjs";
+import { a as QueryCacheConfig, i as QueryCache, n as CacheResult, r as CacheStatus, t as CacheEnvelope } from "../QueryCache-DOMT_iq7.mjs";
+import { i as queryCachePlugin, n as QueryCacheDefaults, r as QueryCachePluginOptions, t as CrossResourceRule } from "../queryCachePlugin-br4otiqF.mjs";
 //#region src/cache/keys.d.ts
 /**
  * Cache Key Utilities
@@ -74,6 +74,18 @@ declare class MemoryCacheStore<TValue = unknown> implements CacheStore<TValue> {
   get(key: string): Promise<TValue | undefined>;
   set(key: string, value: TValue, ttlSeconds?: number): Promise<void>;
   delete(key: string): Promise<void>;
+  /**
+   * Atomic increment (canonical `CacheAdapter` signature: key, by, ttl) —
+   * synchronous on purpose: no `await` between read and write means
+   * concurrent bumps on the event loop can't interleave, which is the whole
+   * point of the `CacheStore.increment` contract.
+   *
+   * TTL semantics follow the repo-core contract: `ttlSeconds` applies only
+   * when the key is CREATED — an existing counter keeps its original expiry
+   * (Redis `EXPIRE ... NX` semantics), so every conforming adapter ages a
+   * counter identically.
+   */
+  increment(key: string, by?: number, ttlSeconds?: number): number;
   clear(pattern?: string): Promise<void>;
   close(): Promise<void>;
   stats(): CacheStats;
@@ -102,6 +114,16 @@ interface RedisCacheClient {
   scan?(cursor: string | number, ...args: (string | number)[]): Promise<[string | number, string[]]>;
   /** Optional: pipeline for batched commands (ioredis compatible) */
   pipeline?(): RedisPipeline;
+  /** Optional: atomic increment-by (Redis INCRBY). Enables `CacheStore.increment`. */
+  incrBy?(key: string, by: number): Promise<number>;
+  /**
+   * Optional: set a TTL only when the key has none (Redis 7 `EXPIRE ... NX`,
+   * or a Lua `TTL`/`EXPIRE` script on older servers). Required alongside
+   * `incrBy` for the atomic `increment` path — the CacheAdapter contract is
+   * TTL-ON-CREATE, and no return value of INCRBY can prove creation (an
+   * existing counter at 0 incremented by `by` also returns `by`).
+   */
+  expireIfAbsent?(key: string, seconds: number): Promise<unknown>;
 }
 interface RedisPipeline {
   del(key: string): unknown;
@@ -134,6 +156,18 @@ declare class RedisCacheStore<TValue = unknown> implements CacheStore<TValue> {
   get(key: string): Promise<TValue | undefined>;
   set(key: string, value: TValue, ttlSeconds?: number): Promise<void>;
   delete(key: string): Promise<void>;
+  /**
+   * Atomic increment (canonical `CacheAdapter` signature: key, by, ttl).
+   *
+   * The atomic path requires `incrBy` AND — when a TTL is requested —
+   * `expireIfAbsent`: TTL-on-create cannot be inferred from INCRBY's
+   * return value (an existing counter at 0 also returns `by`), so the
+   * NX-expiry must be its own atomic server-side operation. A client that
+   * can't honor the COMPLETE contract falls back to read-modify-write
+   * (monotonic, but a concurrent replica's bump can be lost, and the TTL
+   * refreshes per write since plain SET can't preserve expiry).
+   */
+  increment(key: string, by?: number, ttlSeconds?: number): Promise<number>;
   /**
    * Invalidate keys. Pass a glob pattern to delete a subset (`user:*:v2`);
    * omit to clear every key under this store's prefix.
@@ -156,6 +190,8 @@ interface IoredisLike {
     del(key: string): unknown;
     exec(): Promise<unknown>;
   };
+  incrby?(key: string, by: number): Promise<number>;
+  eval?(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
 }
 /**
  * Wrap an ioredis instance as a `RedisCacheClient`.
@@ -193,6 +229,8 @@ interface UpstashRedisLike {
     match?: string;
     count?: number;
   }): Promise<[number, string[]] | [string, string[]]>;
+  incrby?(key: string, by: number): Promise<number>;
+  eval?(script: string, keys: string[], args: (string | number)[]): Promise<unknown>;
 }
 /**
  * Wrap an `@upstash/redis` REST client as a `RedisCacheClient`.