import { type StandardSchemaV1 } from './schema.js';
export interface KvSetOptions {
    ex?: number;
}
export interface KvListResult {
    keys: string[];
    nextCursor: string | null;
}
/** kv.lock() 拿到的锁句柄；用完必须 release（放在 finally 里） */
export interface KvLock {
    /** 被锁住的业务键 */
    key: string;
    /** 释放锁；只删自己持有的那把（token 比对），不会误删超时后别人拿到的锁 */
    release(): Promise<void>;
}
export interface KvLockOptions {
    /** 锁的存活时间（毫秒，默认 10000）：持有者崩溃也会到点自动释放，别设得比临界区还短 */
    ttlMs?: number;
    /** 拿不到锁时最多等多久（毫秒，默认 0 = 不等，立刻返回 null） */
    waitMs?: number;
}
export interface KvClient {
    get<T = unknown>(key: string): Promise<T | null>;
    /**
     * 带 schema 的读取（zod / valibot 等 Standard Schema）：存在则校验并收窄类型，不合格抛 AppSdkError('INVALID_DATA')。
     * 用它替代 `kv.get<T>()` 的裸断言——线上数据结构漂移时能在读取处就暴露，而不是在渲染时炸。
     */
    get<T>(key: string, schema: StandardSchemaV1<unknown, T>): Promise<T | null>;
    set(key: string, value: unknown, opts?: KvSetOptions): Promise<void>;
    /**
     * 只在键不存在时写入，返回是否真的写进去了（技术方案 34 §2）。
     * 用于幂等（同一次提交只处理一次）、唯一占位、以及 lock() 的底座。edgeone 驱动下是 best-effort（Blob 没有原子写）。
     */
    setnx(key: string, value: unknown, opts?: KvSetOptions): Promise<boolean>;
    /**
     * 互斥锁（基于 setnx）：拿到返回句柄，没拿到返回 null。
     * ```ts
     * const lock = await kv.lock('seat:' + id, { waitMs: 2000 })
     * if (!lock) return { error: '请稍后重试' }
     * try { /* 读-改-写 *\/ } finally { await lock.release() }
     * ```
     */
    lock(key: string, opts?: KvLockOptions): Promise<KvLock | null>;
    del(key: string): Promise<boolean>;
    incr(key: string, by?: number): Promise<number>;
    expire(key: string, seconds: number): Promise<boolean>;
    mget<T = unknown>(keys: string[]): Promise<Array<T | null>>;
    list(prefix?: string, opts?: {
        cursor?: string | null;
        limit?: number;
    }): Promise<KvListResult>;
}
/** 驱动只实现 setnx 等原子原语，lock 由 withSchema 统一在上层实现 */
export type KvDriver = Omit<KvClient, 'lock'>;
/** 按当前配置取 KV 客户端（惰性、缓存；configure() 后自动重建） */
export declare function getKv(): KvClient;
/** 便捷单例：`import { kv } from '@chatu-ai/app-sdk'` */
export declare const kv: KvClient;