@tinycloud/sdk-services 1.7.0 → 2.0.2-beta.0

package/dist/index.d.ts

@@ -1,58 +1,1843 @@
+import { I as IServiceContext, a as InvokeFunction, F as FetchFunction, S as ServiceSession, R as RetryPolicy, b as IService, c as ServiceError, d as Result, B as BaseService, e as StorageQuotaInfo } from './BaseService-D9BFm_rV.js';
+export { E as ErrorCode, f as ErrorCodes, g as EventHandler, h as FetchRequestInit, i as FetchResponse, j as InvocationFact, k as InvocationFacts, l as ServiceErrorEvent, m as ServiceHeaders, n as ServiceRequestEvent, o as ServiceResponseEvent, p as ServiceRetryEvent, T as TelemetryEvents, q as defaultRetryPolicy, r as err, s as ok, t as serviceError } from './BaseService-D9BFm_rV.js';
+import { z } from 'zod';
+import { IKVService } from './kv/index.js';
+export { IPrefixedKVService, KVAction, KVActionType, KVDeleteOptions, KVGetOptions, KVHeadOptions, KVListOptions, KVListResponse, KVPutOptions, KVResponse, KVResponseHeaders, KVService, KVServiceConfig, PrefixedKVService } from './kv/index.js';
+export { BatchOptions, BatchResponse, DatabaseHandle, ExecuteOptions, ExecuteResponse, IDatabaseHandle, ISQLService, QueryOptions, QueryResponse, SQLAction, SQLActionType, SQLService, SQLServiceConfig, SqlStatement, SqlValue } from './sql/index.js';
+
 /**
- * TinyCloud SDK Services
+ * Zod schemas for SDK Services API response types.
  *
- * Platform-agnostic services with plugin architecture for TinyCloud.
+ * This is the source of truth for service response types. TypeScript types
+ * are derived from these schemas using z.infer<>.
  *
  * @packageDocumentation
+ */
+
+/**
+ * Validation error type for schema validation failures.
+ */
+interface ValidationError {
+    code: "VALIDATION_ERROR";
+    message: string;
+    service: string;
+    meta?: {
+        issues: z.ZodIssue[];
+        path?: string;
+    };
+}
+/**
+ * Schema for service error with structured information.
+ */
+declare const ServiceErrorSchema: z.ZodObject<{
+    /** Error code for programmatic handling (e.g., 'KV_NOT_FOUND', 'AUTH_EXPIRED') */
+    code: z.ZodString;
+    /** Human-readable error message */
+    message: z.ZodString;
+    /** Service that produced the error (e.g., 'kv', 'sql') */
+    service: z.ZodString;
+    /** Original error if this wraps another error - not validated since Error is a class */
+    cause: z.ZodOptional<z.ZodUnknown>;
+    /** Additional metadata about the error - passthrough allows any object properties */
+    meta: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    message: string;
+    service: string;
+    cause?: unknown;
+    meta?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+}, {
+    code: string;
+    message: string;
+    service: string;
+    cause?: unknown;
+    meta?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+}>;
+type ServiceErrorType = z.infer<typeof ServiceErrorSchema>;
+/**
+ * Creates a Result schema for a given data type.
+ * Result is a discriminated union: { ok: true, data: T } | { ok: false, error: E }
+ *
+ * @param dataSchema - Zod schema for the success data type
+ * @param errorSchema - Zod schema for the error type (defaults to ServiceErrorSchema)
+ * @returns A Zod schema for Result<T, E>
+ *
+ * @example
+ * ```typescript
+ * const KVGetResultSchema = createResultSchema(z.string());
+ * type KVGetResult = z.infer<typeof KVGetResultSchema>;
+ * ```
+ */
+declare function createResultSchema<T extends z.ZodTypeAny, E extends z.ZodTypeAny>(dataSchema: T, errorSchema?: E): z.ZodDiscriminatedUnion<"ok", [z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    data: T;
+}, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+    ok: z.ZodLiteral<true>;
+    data: T;
+}>, any> extends infer T_1 ? { [k in keyof T_1]: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+    ok: z.ZodLiteral<true>;
+    data: T;
+}>, any>[k]; } : never, z.baseObjectInputType<{
+    ok: z.ZodLiteral<true>;
+    data: T;
+}> extends infer T_2 ? { [k_1 in keyof T_2]: z.baseObjectInputType<{
+    ok: z.ZodLiteral<true>;
+    data: T;
+}>[k_1]; } : never>, z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    error: E;
+}, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+    ok: z.ZodLiteral<false>;
+    error: E;
+}>, any> extends infer T_3 ? { [k_2 in keyof T_3]: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+    ok: z.ZodLiteral<false>;
+    error: E;
+}>, any>[k_2]; } : never, z.baseObjectInputType<{
+    ok: z.ZodLiteral<false>;
+    error: E;
+}> extends infer T_4 ? { [k_3 in keyof T_4]: z.baseObjectInputType<{
+    ok: z.ZodLiteral<false>;
+    error: E;
+}>[k_3]; } : never>]>;
+/**
+ * Pre-built Result schema with unknown data and ServiceError.
+ * Useful for generic validation before type narrowing.
+ */
+declare const GenericResultSchema: z.ZodDiscriminatedUnion<"ok", [z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    data: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    ok: true;
+    data?: unknown;
+}, {
+    ok: true;
+    data?: unknown;
+}>, z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        /** Error code for programmatic handling (e.g., 'KV_NOT_FOUND', 'AUTH_EXPIRED') */
+        code: z.ZodString;
+        /** Human-readable error message */
+        message: z.ZodString;
+        /** Service that produced the error (e.g., 'kv', 'sql') */
+        service: z.ZodString;
+        /** Original error if this wraps another error - not validated since Error is a class */
+        cause: z.ZodOptional<z.ZodUnknown>;
+        /** Additional metadata about the error - passthrough allows any object properties */
+        meta: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    }, {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    error: {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    };
+    ok: false;
+}, {
+    error: {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    };
+    ok: false;
+}>]>;
+/**
+ * Schema for KV response headers metadata.
+ * Note: The `get` method is a function and cannot be validated with Zod.
+ * This schema validates the data properties only.
+ */
+declare const KVResponseHeadersSchema: z.ZodObject<{
+    /** ETag for conditional requests */
+    etag: z.ZodOptional<z.ZodString>;
+    /** Content type of the stored value */
+    contentType: z.ZodOptional<z.ZodString>;
+    /** Last modification timestamp */
+    lastModified: z.ZodOptional<z.ZodString>;
+    /** Content length in bytes */
+    contentLength: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    etag?: string | undefined;
+    contentType?: string | undefined;
+    lastModified?: string | undefined;
+    contentLength?: number | undefined;
+}, {
+    etag?: string | undefined;
+    contentType?: string | undefined;
+    lastModified?: string | undefined;
+    contentLength?: number | undefined;
+}>;
+type KVResponseHeadersType = z.infer<typeof KVResponseHeadersSchema>;
+/**
+ * Creates a KVResponse schema for a given data type.
+ *
+ * @param dataSchema - Zod schema for the data payload type
+ * @returns A Zod schema for KVResponse<T>
+ *
+ * @example
+ * ```typescript
+ * const UserResponseSchema = createKVResponseSchema(UserSchema);
+ * type UserResponse = z.infer<typeof UserResponseSchema>;
+ * ```
+ */
+declare function createKVResponseSchema<T extends z.ZodTypeAny>(dataSchema: T): z.ZodObject<{
+    /** The data payload */
+    data: T;
+    /** Response headers with metadata */
+    headers: z.ZodObject<{
+        /** ETag for conditional requests */
+        etag: z.ZodOptional<z.ZodString>;
+        /** Content type of the stored value */
+        contentType: z.ZodOptional<z.ZodString>;
+        /** Last modification timestamp */
+        lastModified: z.ZodOptional<z.ZodString>;
+        /** Content length in bytes */
+        contentLength: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        etag?: string | undefined;
+        contentType?: string | undefined;
+        lastModified?: string | undefined;
+        contentLength?: number | undefined;
+    }, {
+        etag?: string | undefined;
+        contentType?: string | undefined;
+        lastModified?: string | undefined;
+        contentLength?: number | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+    /** The data payload */
+    data: T;
+    /** Response headers with metadata */
+    headers: z.ZodObject<{
+        /** ETag for conditional requests */
+        etag: z.ZodOptional<z.ZodString>;
+        /** Content type of the stored value */
+        contentType: z.ZodOptional<z.ZodString>;
+        /** Last modification timestamp */
+        lastModified: z.ZodOptional<z.ZodString>;
+        /** Content length in bytes */
+        contentLength: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        etag?: string | undefined;
+        contentType?: string | undefined;
+        lastModified?: string | undefined;
+        contentLength?: number | undefined;
+    }, {
+        etag?: string | undefined;
+        contentType?: string | undefined;
+        lastModified?: string | undefined;
+        contentLength?: number | undefined;
+    }>;
+}>, any> extends infer T_1 ? { [k in keyof T_1]: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+    /** The data payload */
+    data: T;
+    /** Response headers with metadata */
+    headers: z.ZodObject<{
+        /** ETag for conditional requests */
+        etag: z.ZodOptional<z.ZodString>;
+        /** Content type of the stored value */
+        contentType: z.ZodOptional<z.ZodString>;
+        /** Last modification timestamp */
+        lastModified: z.ZodOptional<z.ZodString>;
+        /** Content length in bytes */
+        contentLength: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        etag?: string | undefined;
+        contentType?: string | undefined;
+        lastModified?: string | undefined;
+        contentLength?: number | undefined;
+    }, {
+        etag?: string | undefined;
+        contentType?: string | undefined;
+        lastModified?: string | undefined;
+        contentLength?: number | undefined;
+    }>;
+}>, any>[k]; } : never, z.baseObjectInputType<{
+    /** The data payload */
+    data: T;
+    /** Response headers with metadata */
+    headers: z.ZodObject<{
+        /** ETag for conditional requests */
+        etag: z.ZodOptional<z.ZodString>;
+        /** Content type of the stored value */
+        contentType: z.ZodOptional<z.ZodString>;
+        /** Last modification timestamp */
+        lastModified: z.ZodOptional<z.ZodString>;
+        /** Content length in bytes */
+        contentLength: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        etag?: string | undefined;
+        contentType?: string | undefined;
+        lastModified?: string | undefined;
+        contentLength?: number | undefined;
+    }, {
+        etag?: string | undefined;
+        contentType?: string | undefined;
+        lastModified?: string | undefined;
+        contentLength?: number | undefined;
+    }>;
+}> extends infer T_2 ? { [k_1 in keyof T_2]: z.baseObjectInputType<{
+    /** The data payload */
+    data: T;
+    /** Response headers with metadata */
+    headers: z.ZodObject<{
+        /** ETag for conditional requests */
+        etag: z.ZodOptional<z.ZodString>;
+        /** Content type of the stored value */
+        contentType: z.ZodOptional<z.ZodString>;
+        /** Last modification timestamp */
+        lastModified: z.ZodOptional<z.ZodString>;
+        /** Content length in bytes */
+        contentLength: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        etag?: string | undefined;
+        contentType?: string | undefined;
+        lastModified?: string | undefined;
+        contentLength?: number | undefined;
+    }, {
+        etag?: string | undefined;
+        contentType?: string | undefined;
+        lastModified?: string | undefined;
+        contentLength?: number | undefined;
+    }>;
+}>[k_1]; } : never>;
+/**
+ * Generic KVResponse schema with unknown data.
+ * Useful for generic validation before type narrowing.
+ */
+declare const GenericKVResponseSchema: z.ZodObject<{
+    /** The data payload */
+    data: z.ZodUnknown;
+    /** Response headers with metadata */
+    headers: z.ZodObject<{
+        /** ETag for conditional requests */
+        etag: z.ZodOptional<z.ZodString>;
+        /** Content type of the stored value */
+        contentType: z.ZodOptional<z.ZodString>;
+        /** Last modification timestamp */
+        lastModified: z.ZodOptional<z.ZodString>;
+        /** Content length in bytes */
+        contentLength: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        etag?: string | undefined;
+        contentType?: string | undefined;
+        lastModified?: string | undefined;
+        contentLength?: number | undefined;
+    }, {
+        etag?: string | undefined;
+        contentType?: string | undefined;
+        lastModified?: string | undefined;
+        contentLength?: number | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    headers: {
+        etag?: string | undefined;
+        contentType?: string | undefined;
+        lastModified?: string | undefined;
+        contentLength?: number | undefined;
+    };
+    data?: unknown;
+}, {
+    headers: {
+        etag?: string | undefined;
+        contentType?: string | undefined;
+        lastModified?: string | undefined;
+        contentLength?: number | undefined;
+    };
+    data?: unknown;
+}>;
+type GenericKVResponseType = z.infer<typeof GenericKVResponseSchema>;
+/**
+ * Schema for KV list response.
+ */
+declare const KVListResponseSchema: z.ZodObject<{
+    /** Array of keys matching the list criteria */
+    keys: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    keys: string[];
+}, {
+    keys: string[];
+}>;
+type KVListResponseType = z.infer<typeof KVListResponseSchema>;
+/**
+ * Result schema for KV list operations.
+ */
+declare const KVListResultSchema: z.ZodDiscriminatedUnion<"ok", [z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    data: z.ZodObject<{
+        /** Array of keys matching the list criteria */
+        keys: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        keys: string[];
+    }, {
+        keys: string[];
+    }>;
+}, "strip", z.ZodTypeAny, {
+    data: {
+        keys: string[];
+    };
+    ok: true;
+}, {
+    data: {
+        keys: string[];
+    };
+    ok: true;
+}>, z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    error: z.ZodTypeAny;
+}, "strip", z.ZodTypeAny, {
+    ok: false;
+    error?: any;
+}, {
+    ok: false;
+    error?: any;
+}>]>;
+type KVListResultType = z.infer<typeof KVListResultSchema>;
+/**
+ * Schema for service request event.
+ */
+declare const ServiceRequestEventSchema: z.ZodObject<{
+    service: z.ZodString;
+    action: z.ZodString;
+    key: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    service: string;
+    action: string;
+    timestamp: number;
+    key?: string | undefined;
+}, {
+    service: string;
+    action: string;
+    timestamp: number;
+    key?: string | undefined;
+}>;
+type ServiceRequestEventType = z.infer<typeof ServiceRequestEventSchema>;
+/**
+ * Schema for service response event.
+ */
+declare const ServiceResponseEventSchema: z.ZodObject<{
+    service: z.ZodString;
+    action: z.ZodString;
+    ok: z.ZodBoolean;
+    duration: z.ZodNumber;
+    status: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    service: string;
+    ok: boolean;
+    action: string;
+    duration: number;
+    status?: number | undefined;
+}, {
+    service: string;
+    ok: boolean;
+    action: string;
+    duration: number;
+    status?: number | undefined;
+}>;
+type ServiceResponseEventType = z.infer<typeof ServiceResponseEventSchema>;
+/**
+ * Schema for service error event.
+ */
+declare const ServiceErrorEventSchema: z.ZodObject<{
+    service: z.ZodString;
+    error: z.ZodObject<{
+        /** Error code for programmatic handling (e.g., 'KV_NOT_FOUND', 'AUTH_EXPIRED') */
+        code: z.ZodString;
+        /** Human-readable error message */
+        message: z.ZodString;
+        /** Service that produced the error (e.g., 'kv', 'sql') */
+        service: z.ZodString;
+        /** Original error if this wraps another error - not validated since Error is a class */
+        cause: z.ZodOptional<z.ZodUnknown>;
+        /** Additional metadata about the error - passthrough allows any object properties */
+        meta: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    }, {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    error: {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    };
+    service: string;
+}, {
+    error: {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    };
+    service: string;
+}>;
+type ServiceErrorEventType = z.infer<typeof ServiceErrorEventSchema>;
+/**
+ * Schema for service retry event.
+ */
+declare const ServiceRetryEventSchema: z.ZodObject<{
+    service: z.ZodString;
+    attempt: z.ZodNumber;
+    maxAttempts: z.ZodNumber;
+    error: z.ZodObject<{
+        /** Error code for programmatic handling (e.g., 'KV_NOT_FOUND', 'AUTH_EXPIRED') */
+        code: z.ZodString;
+        /** Human-readable error message */
+        message: z.ZodString;
+        /** Service that produced the error (e.g., 'kv', 'sql') */
+        service: z.ZodString;
+        /** Original error if this wraps another error - not validated since Error is a class */
+        cause: z.ZodOptional<z.ZodUnknown>;
+        /** Additional metadata about the error - passthrough allows any object properties */
+        meta: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    }, {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    error: {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    };
+    service: string;
+    attempt: number;
+    maxAttempts: number;
+}, {
+    error: {
+        code: string;
+        message: string;
+        service: string;
+        cause?: unknown;
+        meta?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    };
+    service: string;
+    attempt: number;
+    maxAttempts: number;
+}>;
+type ServiceRetryEventType = z.infer<typeof ServiceRetryEventSchema>;
+/**
+ * Schema for retry policy configuration.
+ */
+declare const RetryPolicySchema: z.ZodObject<{
+    /** Maximum number of attempts (including initial) */
+    maxAttempts: z.ZodNumber;
+    /** Backoff strategy between retries */
+    backoff: z.ZodEnum<["none", "linear", "exponential"]>;
+    /** Base delay in milliseconds for backoff calculation */
+    baseDelayMs: z.ZodNumber;
+    /** Maximum delay in milliseconds between retries */
+    maxDelayMs: z.ZodNumber;
+    /** Error codes that should trigger a retry */
+    retryableErrors: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    maxAttempts: number;
+    backoff: "none" | "linear" | "exponential";
+    baseDelayMs: number;
+    maxDelayMs: number;
+    retryableErrors: string[];
+}, {
+    maxAttempts: number;
+    backoff: "none" | "linear" | "exponential";
+    baseDelayMs: number;
+    maxDelayMs: number;
+    retryableErrors: string[];
+}>;
+type RetryPolicyType = z.infer<typeof RetryPolicySchema>;
+/**
+ * Schema for service session data required for authenticated operations.
+ */
+declare const ServiceSessionSchema: z.ZodObject<{
+    /** The delegation header containing the UCAN */
+    delegationHeader: z.ZodObject<{
+        Authorization: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        Authorization: string;
+    }, {
+        Authorization: string;
+    }>;
+    /** The delegation CID */
+    delegationCid: z.ZodString;
+    /** The space ID for this session */
+    spaceId: z.ZodString;
+    /** The verification method DID */
+    verificationMethod: z.ZodString;
+    /** The session key JWK (required for invoke) */
+    jwk: z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>;
+}, "strip", z.ZodTypeAny, {
+    delegationHeader: {
+        Authorization: string;
+    };
+    delegationCid: string;
+    spaceId: string;
+    verificationMethod: string;
+    jwk: {} & {
+        [k: string]: unknown;
+    };
+}, {
+    delegationHeader: {
+        Authorization: string;
+    };
+    delegationCid: string;
+    spaceId: string;
+    verificationMethod: string;
+    jwk: {} & {
+        [k: string]: unknown;
+    };
+}>;
+type ServiceSessionType = z.infer<typeof ServiceSessionSchema>;
+/**
+ * Validate service error against the schema.
+ *
+ * @param data - Unknown data to validate
+ * @returns Result with validated data or validation error
+ */
+declare function validateServiceError(data: unknown): {
+    ok: true;
+    data: ServiceErrorType;
+} | {
+    ok: false;
+    error: ValidationError;
+};
+/**
+ * Validate KV list response against the schema.
+ *
+ * @param data - Unknown data to validate
+ * @returns Result with validated data or validation error
+ */
+declare function validateKVListResponse(data: unknown): {
+    ok: true;
+    data: KVListResponseType;
+} | {
+    ok: false;
+    error: ValidationError;
+};
+/**
+ * Validate KV response headers against the schema.
+ *
+ * @param data - Unknown data to validate
+ * @returns Result with validated data or validation error
+ */
+declare function validateKVResponseHeaders(data: unknown): {
+    ok: true;
+    data: KVResponseHeadersType;
+} | {
+    ok: false;
+    error: ValidationError;
+};
+/**
+ * Validate service session against the schema.
+ *
+ * @param data - Unknown data to validate
+ * @returns Result with validated data or validation error
+ */
+declare function validateServiceSession(data: unknown): {
+    ok: true;
+    data: ServiceSessionType;
+} | {
+    ok: false;
+    error: ValidationError;
+};
+/**
+ * Validate retry policy against the schema.
+ *
+ * @param data - Unknown data to validate
+ * @returns Result with validated data or validation error
+ */
+declare function validateRetryPolicy(data: unknown): {
+    ok: true;
+    data: RetryPolicyType;
+} | {
+    ok: false;
+    error: ValidationError;
+};
+/**
+ * Validate service request event against the schema.
+ *
+ * @param data - Unknown data to validate
+ * @returns Result with validated data or validation error
+ */
+declare function validateServiceRequestEvent(data: unknown): {
+    ok: true;
+    data: ServiceRequestEventType;
+} | {
+    ok: false;
+    error: ValidationError;
+};
+/**
+ * Validate service response event against the schema.
+ *
+ * @param data - Unknown data to validate
+ * @returns Result with validated data or validation error
+ */
+declare function validateServiceResponseEvent(data: unknown): {
+    ok: true;
+    data: ServiceResponseEventType;
+} | {
+    ok: false;
+    error: ValidationError;
+};
+
+/**
+ * ServiceContext implementation for TinyCloud SDK Services
  * @module @tinycloud/sdk-services
+ */
+
+/**
+ * Event handler type for telemetry events.
+ */
+type EventHandler = (data: unknown) => void;
+/**
+ * Configuration options for ServiceContext.
+ */
+interface ServiceContextConfig {
+    /** Function to invoke WASM operations */
+    invoke: InvokeFunction;
+    /** Function to make HTTP requests (defaults to globalThis.fetch) */
+    fetch?: FetchFunction;
+    /** List of TinyCloud host URLs */
+    hosts: string[];
+    /** Initial session (optional) */
+    session?: ServiceSession | null;
+    /** Retry policy configuration */
+    retryPolicy?: Partial<RetryPolicy>;
+}
+/**
+ * ServiceContext provides platform dependencies and cross-service access to services.
+ * This is the primary interface services use to interact with the SDK runtime.
  *
  * @example
  * ```typescript
- * import {
- *   ServiceContext,
- *   BaseService,
- *   Result,
- *   ErrorCodes,
- * } from '@tinycloud/sdk-services';
- *
- * // Create a context
  * const context = new ServiceContext({
  *   invoke: wasmInvoke,
  *   hosts: ['https://node.tinycloud.xyz'],
+ *   retryPolicy: { maxAttempts: 5 },
  * });
  *
- * // Create and register a service
- * const kv = new KVService({ prefix: 'myapp' });
- * context.registerService('kv', kv);
- * kv.initialize(context);
+ * // Register a service
+ * const kvService = new KVService({});
+ * context.registerService('kv', kvService);
+ * kvService.initialize(context);
  *
- * // Use the service
- * const result = await kv.get('key');
- * if (result.ok) {
- *   console.log(result.data);
+ * // Update session when user signs in
+ * context.setSession(userSession);
+ * ```
+ */
+declare class ServiceContext implements IServiceContext {
+    private _session;
+    private _services;
+    private _eventHandlers;
+    private _abortController;
+    private readonly _invoke;
+    private readonly _fetch;
+    private readonly _hosts;
+    private readonly _retryPolicy;
+    constructor(config: ServiceContextConfig);
+    /**
+     * Get the current session.
+     */
+    get session(): ServiceSession | null;
+    /**
+     * Check if the context has an authenticated session.
+     */
+    get isAuthenticated(): boolean;
+    /**
+     * Update the session and notify all registered services.
+     *
+     * @param session - New session or null to clear
+     */
+    setSession(session: ServiceSession | null): void;
+    /**
+     * Get the invoke function for WASM operations.
+     */
+    get invoke(): InvokeFunction;
+    /**
+     * Get the fetch function for HTTP requests.
+     */
+    get fetch(): FetchFunction;
+    /**
+     * Get the list of TinyCloud host URLs.
+     */
+    get hosts(): string[];
+    /**
+     * Register a service with the context.
+     *
+     * @param name - Service name (e.g., 'kv')
+     * @param service - Service instance
+     */
+    registerService(name: string, service: IService): void;
+    /**
+     * Unregister a service from the context.
+     *
+     * @param name - Service name to remove
+     */
+    unregisterService(name: string): void;
+    /**
+     * Get a registered service by name.
+     *
+     * @param name - Service name
+     * @returns The service instance or undefined if not registered
+     */
+    getService<T extends IService>(name: string): T | undefined;
+    /**
+     * Emit a telemetry event.
+     *
+     * @param event - Event name
+     * @param data - Event data
+     */
+    emit(event: string, data: unknown): void;
+    /**
+     * Subscribe to telemetry events.
+     *
+     * @param event - Event name to subscribe to
+     * @param handler - Handler function
+     * @returns Unsubscribe function
+     */
+    on(event: string, handler: EventHandler): () => void;
+    /**
+     * Remove all event handlers for an event.
+     *
+     * @param event - Event name (if omitted, clears all events)
+     */
+    clearEventHandlers(event?: string): void;
+    /**
+     * Get the abort signal for cancelling operations.
+     */
+    get abortSignal(): AbortSignal;
+    /**
+     * Abort all pending operations and notify services.
+     * Creates a new AbortController for future operations.
+     */
+    abort(): void;
+    /**
+     * Sign out - abort operations and clear session.
+     */
+    signOut(): void;
+    /**
+     * Get the retry policy configuration.
+     */
+    get retryPolicy(): RetryPolicy;
+}
+
+/**
+ * Create a service error for authentication required.
+ */
+declare function authRequiredError(service: string): ServiceError;
+/**
+ * Create a service error for expired authentication.
+ */
+declare function authExpiredError(service: string): ServiceError;
+/**
+ * Create a service error for network issues.
+ */
+declare function networkError(service: string, message: string, cause?: Error): ServiceError;
+/**
+ * Create a service error for timeouts.
+ */
+declare function timeoutError(service: string): ServiceError;
+/**
+ * Create a service error for aborted requests.
+ */
+declare function abortedError(service: string): ServiceError;
+/**
+ * Create a service error for not found resources.
+ */
+declare function notFoundError(service: string, resource: string): ServiceError;
+/**
+ * Create a service error for permission denied.
+ */
+declare function permissionDeniedError(service: string, action: string): ServiceError;
+/**
+ * Parse the server's "Unauthorized Action: {resource} / {ability}" pattern.
+ */
+declare function parseAuthError(responseText: string): {
+    resource?: string;
+    action?: string;
+};
+/**
+ * Create a service error for unauthorized action (missing capability).
+ */
+declare function authUnauthorizedError(service: string, message: string, meta?: Record<string, unknown>): ServiceError;
+/**
+ * Create a service error for storage quota exceeded (402 Payment Required).
+ */
+declare function storageQuotaExceededError(service: string, message: string, meta?: Record<string, unknown>): ServiceError;
+/**
+ * Create a service error for storage limit reached (413 Payload Too Large).
+ */
+declare function storageLimitReachedError(service: string, message: string, meta?: Record<string, unknown>): ServiceError;
+/**
+ * Wrap an unknown error in a ServiceError.
+ */
+declare function wrapError(service: string, error: unknown, defaultCode?: string): ServiceError;
+/**
+ * Create an error Result from a ServiceError.
+ */
+declare function errorResult(error: ServiceError): Result<never, ServiceError>;
+
+/**
+ * Base Service Types
+ *
+ * Types specific to the base service infrastructure.
+ */
+
+/**
+ * Service constructor type for registration.
+ * Used by the SDK to instantiate services.
+ */
+interface ServiceConstructor<TConfig = Record<string, unknown>, TService extends IService = IService> {
+    /** Service identifier used for registration */
+    readonly serviceName: string;
+    /** Create a new instance of the service */
+    new (config?: TConfig): TService;
+}
+/**
+ * Service registration entry.
+ */
+interface ServiceRegistration {
+    /** The service class constructor */
+    constructor: ServiceConstructor;
+    /** Configuration for this service instance */
+    config?: Record<string, unknown>;
+}
+/**
+ * Options for base service operations.
+ */
+interface BaseServiceOptions {
+    /** Override the default timeout for this operation */
+    timeout?: number;
+    /** Custom abort signal for this operation */
+    signal?: AbortSignal;
+}
+
+/**
+ * DuckDB Service Types
+ *
+ * Type definitions for the DuckDB service operations.
+ */
+/**
+ * Configuration for DuckDbService.
+ */
+interface DuckDbServiceConfig {
+    /**
+     * Default database name.
+     * If not set, operations default to "default".
+     */
+    defaultDatabase?: string;
+    /**
+     * Default timeout in milliseconds for DuckDB operations.
+     */
+    timeout?: number;
+    /** Allow additional config properties */
+    [key: string]: unknown;
+}
+/**
+ * Options for DuckDB query operations.
+ */
+interface DuckDbQueryOptions {
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Options for DuckDB execute operations.
+ */
+interface DuckDbExecuteOptions {
+    /**
+     * Schema initialization statements (CREATE TABLE IF NOT EXISTS ...).
+     * Executed before the main statement on first write.
+     */
+    schema?: string[];
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Options for DuckDB batch operations.
+ */
+interface DuckDbBatchOptions {
+    /**
+     * Whether to run statements in a transaction.
+     */
+    transactional?: boolean;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Options for DuckDB operations that only need an abort signal.
+ */
+interface DuckDbOptions {
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * A DuckDB value: null, boolean, number, string, binary, array, or object.
+ */
+type DuckDbValue = null | boolean | number | string | Uint8Array | DuckDbValueArray | DuckDbValueRecord;
+/** Array of DuckDB values (workaround for circular type alias). */
+interface DuckDbValueArray extends Array<DuckDbValue> {
+}
+/** Record of DuckDB values (workaround for circular type alias). */
+interface DuckDbValueRecord {
+    [key: string]: DuckDbValue;
+}
+/**
+ * A DuckDB statement with optional parameters.
+ */
+interface DuckDbStatement {
+    sql: string;
+    params?: DuckDbValue[];
+}
+/**
+ * Response from DuckDB query operations.
+ */
+interface QueryResponse<T = Record<string, unknown>> {
+    columns: string[];
+    rows: T[][];
+    rowCount: number;
+}
+/**
+ * Response from DuckDB execute operations.
+ */
+interface ExecuteResponse {
+    changes: number;
+}
+/**
+ * Response from DuckDB batch operations.
+ */
+interface BatchResponse {
+    results: ExecuteResponse[];
+}
+/**
+ * Schema information for a DuckDB database.
+ */
+interface SchemaInfo {
+    tables: TableInfo[];
+    views: ViewInfo[];
+}
+/**
+ * Information about a table.
+ */
+interface TableInfo {
+    name: string;
+    columns: ColumnInfo[];
+}
+/**
+ * Information about a column.
+ */
+interface ColumnInfo {
+    name: string;
+    type: string;
+    nullable: boolean;
+}
+/**
+ * Information about a view.
+ */
+interface ViewInfo {
+    name: string;
+    sql: string;
+}
+/**
+ * DuckDB service action types.
+ */
+declare const DuckDbAction: {
+    readonly READ: "tinycloud.duckdb/read";
+    readonly WRITE: "tinycloud.duckdb/write";
+    readonly ADMIN: "tinycloud.duckdb/admin";
+    readonly DESCRIBE: "tinycloud.duckdb/describe";
+    readonly EXPORT: "tinycloud.duckdb/export";
+    readonly IMPORT: "tinycloud.duckdb/import";
+    readonly EXECUTE: "tinycloud.duckdb/execute";
+    readonly ALL: "tinycloud.duckdb/*";
+};
+type DuckDbActionType = (typeof DuckDbAction)[keyof typeof DuckDbAction];
+
+/**
+ * IDuckDbService - Interface for DuckDB service.
+ *
+ * Platform-agnostic interface for DuckDB database operations.
+ */
+
+/**
+ * Database handle interface for operations on a specific named database.
+ */
+interface IDuckDbDatabaseHandle {
+    /** The database name */
+    readonly name: string;
+    /**
+     * Execute a DuckDB query and return rows as JSON.
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: DuckDbValue[], options?: DuckDbQueryOptions): Promise<Result<QueryResponse<T>>>;
+    /**
+     * Execute a DuckDB query and return results as Arrow IPC stream.
+     */
+    queryArrow(sql: string, params?: DuckDbValue[], options?: DuckDbQueryOptions): Promise<Result<ArrayBuffer>>;
+    /**
+     * Execute a DuckDB statement and return change count.
+     */
+    execute(sql: string, params?: DuckDbValue[], options?: DuckDbExecuteOptions): Promise<Result<ExecuteResponse>>;
+    /**
+     * Execute multiple statements in a batch.
+     */
+    batch(statements: DuckDbStatement[], options?: DuckDbBatchOptions): Promise<Result<BatchResponse>>;
+    /**
+     * Execute a named prepared statement from delegation caveats.
+     */
+    executeStatement(name: string, params?: DuckDbValue[], options?: DuckDbQueryOptions): Promise<Result<QueryResponse | ExecuteResponse>>;
+    /**
+     * Describe the database schema.
+     */
+    describe(options?: DuckDbOptions): Promise<Result<SchemaInfo>>;
+    /**
+     * Export the database as a Blob.
+     */
+    export(options?: DuckDbOptions): Promise<Result<Blob>>;
+    /**
+     * Import a binary DuckDB database file.
+     */
+    import(data: Uint8Array, options?: DuckDbOptions): Promise<Result<void>>;
+}
+/**
+ * DuckDB service interface.
+ *
+ * Provides DuckDB database operations with:
+ * - Result type pattern (no throwing)
+ * - Named database handles
+ * - Configurable timeouts
+ * - Abort signal support
+ * - Arrow format support via queryArrow()
+ */
+interface IDuckDbService extends IService {
+    /**
+     * Get a handle to a named database.
+     * @param name - Database name (defaults to "default")
+     */
+    db(name?: string): IDuckDbDatabaseHandle;
+    /**
+     * Shortcut: query the default database (JSON format).
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: DuckDbValue[], options?: DuckDbQueryOptions): Promise<Result<QueryResponse<T>>>;
+    /**
+     * Shortcut: query the default database (Arrow IPC format).
+     */
+    queryArrow(sql: string, params?: DuckDbValue[], options?: DuckDbQueryOptions): Promise<Result<ArrayBuffer>>;
+    /**
+     * Shortcut: execute on the default database.
+     */
+    execute(sql: string, params?: DuckDbValue[], options?: DuckDbExecuteOptions): Promise<Result<ExecuteResponse>>;
+    /**
+     * Shortcut: batch on the default database.
+     */
+    batch(statements: DuckDbStatement[], options?: DuckDbBatchOptions): Promise<Result<BatchResponse>>;
+    /**
+     * Service configuration.
+     */
+    readonly config: DuckDbServiceConfig;
+}
+
+/**
+ * DuckDbService - DuckDB database service implementation.
+ *
+ * Platform-agnostic DuckDB service that works with both web-sdk and node-sdk.
+ * Uses dependency injection via IServiceContext for platform dependencies.
+ */
+
+declare class DuckDbService extends BaseService implements IDuckDbService {
+    static readonly serviceName = "duckdb";
+    protected _config: DuckDbServiceConfig;
+    constructor(config?: DuckDbServiceConfig);
+    get config(): DuckDbServiceConfig;
+    private get defaultDbName();
+    private get host();
+    /**
+     * Get a handle to a named database.
+     */
+    db(name?: string): IDuckDbDatabaseHandle;
+    /**
+     * Shortcut: query the default database (JSON format).
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: DuckDbValue[], options?: DuckDbQueryOptions): Promise<Result<QueryResponse<T>>>;
+    /**
+     * Shortcut: query the default database (Arrow IPC format).
+     */
+    queryArrow(sql: string, params?: DuckDbValue[], options?: DuckDbQueryOptions): Promise<Result<ArrayBuffer>>;
+    /**
+     * Shortcut: execute on the default database.
+     */
+    execute(sql: string, params?: DuckDbValue[], options?: DuckDbExecuteOptions): Promise<Result<ExecuteResponse>>;
+    /**
+     * Shortcut: batch on the default database.
+     */
+    batch(statements: DuckDbStatement[], options?: DuckDbBatchOptions): Promise<Result<BatchResponse>>;
+    queryOnDb<T = Record<string, unknown>>(dbName: string, sql: string, params?: DuckDbValue[], options?: DuckDbQueryOptions): Promise<Result<QueryResponse<T>>>;
+    queryArrowOnDb(dbName: string, sql: string, params?: DuckDbValue[], options?: DuckDbQueryOptions): Promise<Result<ArrayBuffer>>;
+    executeOnDb(dbName: string, sql: string, params?: DuckDbValue[], options?: DuckDbExecuteOptions): Promise<Result<ExecuteResponse>>;
+    batchOnDb(dbName: string, statements: DuckDbStatement[], options?: DuckDbBatchOptions): Promise<Result<BatchResponse>>;
+    executeStatementOnDb(dbName: string, name: string, params?: DuckDbValue[], options?: DuckDbQueryOptions): Promise<Result<QueryResponse | ExecuteResponse>>;
+    describeDb(dbName: string, options?: DuckDbOptions): Promise<Result<SchemaInfo>>;
+    exportOnDb(dbName: string, options?: DuckDbOptions): Promise<Result<Blob>>;
+    importOnDb(dbName: string, data: Uint8Array, options?: DuckDbOptions): Promise<Result<void>>;
+    private invokeDuckDb;
+    private handleErrorResponse;
+    private mapHttpStatusToErrorCode;
+}
+
+/**
+ * DuckDbDatabaseHandle - Handle for operations on a specific named database.
+ *
+ * Delegates all operations to the parent DuckDbService with the database name.
+ */
+
+declare class DuckDbDatabaseHandle implements IDuckDbDatabaseHandle {
+    private service;
+    readonly name: string;
+    constructor(service: DuckDbService, name: string);
+    query<T = Record<string, unknown>>(sql: string, params?: DuckDbValue[], options?: DuckDbQueryOptions): Promise<Result<QueryResponse<T>>>;
+    queryArrow(sql: string, params?: DuckDbValue[], options?: DuckDbQueryOptions): Promise<Result<ArrayBuffer>>;
+    execute(sql: string, params?: DuckDbValue[], options?: DuckDbExecuteOptions): Promise<Result<ExecuteResponse>>;
+    batch(statements: DuckDbStatement[], options?: DuckDbBatchOptions): Promise<Result<BatchResponse>>;
+    executeStatement(name: string, params?: DuckDbValue[], options?: DuckDbQueryOptions): Promise<Result<QueryResponse | ExecuteResponse>>;
+    describe(options?: DuckDbOptions): Promise<Result<SchemaInfo>>;
+    export(options?: DuckDbOptions): Promise<Result<Blob>>;
+    import(data: Uint8Array, options?: DuckDbOptions): Promise<Result<void>>;
+}
+
+interface QuotaConfig {
+    /** Called when a storage quota error is detected (402/413) */
+    onUpgradeRequired?: (info: StorageQuotaInfo) => void;
+}
+interface QuotaStatus {
+    /** Storage limit in bytes for this space */
+    limitBytes: number;
+    /** Storage used in bytes for this space */
+    usedBytes?: number;
+    /** Remaining storage in bytes */
+    remainingBytes?: number;
+}
+declare class TinyCloudQuota {
+    private config;
+    private quotaUrl;
+    constructor(config?: QuotaConfig);
+    /** Set the quota URL discovered from the /info endpoint */
+    setQuotaUrl(url: string | null): void;
+    /** Whether a quota service is available */
+    get available(): boolean;
+    /** Query quota status for a space from the quota URL */
+    getQuota(spaceId: string): Promise<QuotaStatus | null>;
+    /** Trigger the upgrade callback when a quota error is encountered */
+    handleQuotaError(info: StorageQuotaInfo): void;
+}
+
+/**
+ * Data Vault Service Types
+ *
+ * Type definitions for the Data Vault (encrypted KV) service operations.
+ */
+/**
+ * Configuration for DataVaultService.
+ */
+interface DataVaultConfig {
+    /** Space ID for encrypted data storage */
+    spaceId: string;
+    /** Key rotation policy */
+    keyRotation?: "per-write" | "per-key";
+}
+/**
+ * Options for vault put operations.
+ */
+interface VaultPutOptions {
+    /** Custom metadata tags appended to the envelope */
+    metadata?: Record<string, string>;
+    /** Content type hint for deserialization (default: auto-detect) */
+    contentType?: string;
+    /** Custom serializer (default: JSON.stringify for objects) */
+    serialize?: (value: unknown) => Uint8Array;
+}
+/**
+ * Options for vault get operations.
+ */
+interface VaultGetOptions<T = unknown> {
+    /** Custom deserializer (default: JSON.parse if content-type is JSON) */
+    deserialize?: (data: Uint8Array) => T;
+    /** Return raw decrypted bytes without deserialization */
+    raw?: boolean;
+    /** Delegated KV service for reading from the grantor's space (used by getShared) */
+    kv?: {
+        get<V>(key: string, options?: {
+            raw?: boolean;
+        }): Promise<{
+            ok: boolean;
+            data?: {
+                data: V;
+            };
+            error?: {
+                message: string;
+            };
+        }>;
+    };
+}
+/**
+ * Options for vault list operations.
+ */
+interface VaultListOptions {
+    /** Prefix filter for key names */
+    prefix?: string;
+    /** Remove prefix from returned keys */
+    removePrefix?: boolean;
+}
+/**
+ * Options for vault grant (sharing) operations.
+ */
+interface VaultGrantOptions {
+    /** Additional metadata on the grant */
+    metadata?: Record<string, string>;
+}
+/**
+ * A decrypted vault entry returned by get operations.
+ *
+ * @template T - Type of the decrypted value
+ */
+interface VaultEntry<T> {
+    /** Decrypted value */
+    value: T;
+    /** Envelope metadata */
+    metadata: Record<string, string>;
+    /** Key ID used for encryption */
+    keyId: string;
+}
+/**
+ * Structured error codes for vault operations.
+ */
+/**
+ * Input types for creating vault errors (service field added automatically).
+ */
+type VaultErrorInput = {
+    code: "DECRYPTION_FAILED";
+    message?: string;
+    cause?: Error;
+} | {
+    code: "KEY_NOT_FOUND";
+    key: string;
+    message?: string;
+} | {
+    code: "INTEGRITY_ERROR";
+    message?: string;
+    cause?: Error;
+} | {
+    code: "GRANT_NOT_FOUND";
+    grantor: string;
+    key: string;
+    message?: string;
+} | {
+    code: "VAULT_LOCKED";
+    message?: string;
+} | {
+    code: "PUBLIC_KEY_NOT_FOUND";
+    did: string;
+    message?: string;
+} | {
+    code: "STORAGE_ERROR";
+    cause: Error;
+    message?: string;
+};
+/**
+ * Vault error with service field (compatible with ServiceError).
+ */
+type VaultError = VaultErrorInput & {
+    service: "vault";
+    message: string;
+};
+/** KV actions the vault needs on the public space for key publishing. */
+declare const VaultPublicSpaceKVActions: readonly ["tinycloud.kv/get", "tinycloud.kv/put", "tinycloud.kv/metadata"];
+/** Metadata header keys used in vault envelopes */
+declare const VaultHeaders: {
+    readonly VERSION: "x-vault-version";
+    readonly CIPHER: "x-vault-cipher";
+    readonly KEY_ID: "x-vault-key-id";
+    readonly CONTENT_TYPE: "x-vault-content-type";
+    readonly KDF: "x-vault-kdf";
+    readonly KEY_ROTATION: "x-vault-key-rotation";
+    readonly GRANT_VERSION: "x-vault-grant-version";
+    readonly GRANTOR: "x-vault-grantor";
+};
+
+/**
+ * IDataVaultService - Interface for the Data Vault (encrypted KV) service.
+ *
+ * Platform-agnostic interface for encrypted key-value storage with
+ * client-side encryption, key management, and sharing via grants.
+ */
+
+/**
+ * Data Vault service interface.
+ *
+ * Provides encrypted key-value storage with:
+ * - Client-side encryption (data is encrypted before leaving the device)
+ * - Result type pattern (no throwing)
+ * - Key management and rotation
+ * - Sharing via grants (re-encrypt to recipient's public key)
+ *
+ * @example
+ * ```typescript
+ * // Unlock the vault (derives encryption keys)
+ * await vault.unlock(signer);
+ *
+ * // Store encrypted data
+ * const result = await vault.put('medical/records', { bloodType: 'O+' });
+ *
+ * // Retrieve and decrypt
+ * const entry = await vault.get<{ bloodType: string }>('medical/records');
+ * if (entry.ok) {
+ *   console.log(entry.data.value.bloodType); // 'O+'
  * }
+ *
+ * // Share with another user
+ * await vault.grant('medical/records', recipientDID);
+ * ```
+ */
+interface IDataVaultService extends IService {
+    /**
+     * Unlock the vault. Derives keys from wallet signatures.
+     * Signer is optional when cached signatures exist (browser only).
+     */
+    unlock(signer?: unknown): Promise<Result<void, VaultError>>;
+    /**
+     * Clear the cached vault signature.
+     * @param spaceId - Clear only this space's cache. If omitted, clears all.
+     */
+    clearCache(spaceId?: string): Promise<void>;
+    /** Lock the vault, clearing all key material from memory. */
+    lock(): void;
+    /** Whether the vault is currently unlocked. */
+    readonly isUnlocked: boolean;
+    /**
+     * Encrypt and store a value at the given key.
+     *
+     * @param key - The key to store under
+     * @param value - The value to encrypt and store
+     * @param options - Optional put configuration
+     */
+    put(key: string, value: unknown, options?: VaultPutOptions): Promise<Result<void, VaultError>>;
+    /**
+     * Retrieve and decrypt a value by key.
+     *
+     * @param key - The key to retrieve
+     * @param options - Optional get configuration
+     * @returns Result with the decrypted entry
+     */
+    get<T = unknown>(key: string, options?: VaultGetOptions<T>): Promise<Result<VaultEntry<T>, VaultError>>;
+    /**
+     * Delete an encrypted key.
+     *
+     * @param key - The key to delete
+     */
+    delete(key: string): Promise<Result<void, VaultError>>;
+    /**
+     * List vault keys with optional prefix filtering.
+     *
+     * @param options - Optional list configuration
+     * @returns Result with array of key names
+     */
+    list(options?: VaultListOptions): Promise<Result<string[], VaultError>>;
+    /**
+     * Get envelope metadata for a key without decrypting the value.
+     *
+     * @param key - The key to inspect
+     * @returns Result with metadata headers
+     */
+    head(key: string): Promise<Result<Record<string, string>, VaultError>>;
+    /**
+     * Encrypt and store multiple entries.
+     *
+     * @param entries - Array of key/value pairs with optional per-entry options
+     * @returns Array of results, one per entry
+     */
+    putMany(entries: Array<{
+        key: string;
+        value: unknown;
+        options?: VaultPutOptions;
+    }>): Promise<Result<void, VaultError>[]>;
+    /**
+     * Retrieve and decrypt multiple keys.
+     *
+     * @param keys - Array of keys to retrieve
+     * @param options - Optional get configuration applied to all entries
+     * @returns Array of results, one per key
+     */
+    getMany<T = unknown>(keys: string[], options?: VaultGetOptions<T>): Promise<Result<VaultEntry<T>, VaultError>[]>;
+    /**
+     * Grant access to a vault key for another user.
+     * Re-encrypts the data key to the recipient's public key.
+     *
+     * @deprecated Use reencrypt() instead.
+     * @param key - The key to share
+     * @param recipientDID - The recipient's primary DID (did:pkh:...)
+     * @param options - Optional grant configuration
+     */
+    grant(key: string, recipientDID: string, options?: VaultGrantOptions): Promise<Result<void, VaultError>>;
+    /**
+     * Re-encrypt a vault key for another user (renamed from grant).
+     * Re-encrypts the data key to the recipient's public key.
+     *
+     * @param key - The key to share
+     * @param recipientDID - The recipient's primary DID (did:pkh:...)
+     * @param options - Optional grant configuration
+     */
+    reencrypt(key: string, recipientDID: string, options?: VaultGrantOptions): Promise<Result<void, VaultError>>;
+    /**
+     * Revoke a previously issued grant.
+     *
+     * @param key - The key to revoke access to
+     * @param recipientDID - The recipient whose access to revoke
+     */
+    revoke(key: string, recipientDID: string): Promise<Result<void, VaultError>>;
+    /**
+     * List DIDs that have been granted access to a key.
+     *
+     * @param key - The key to list grants for
+     * @returns Result with array of recipient DIDs
+     */
+    listGrants(key: string): Promise<Result<string[], VaultError>>;
+    /**
+     * Retrieve and decrypt a value shared by another user.
+     *
+     * @param grantorDID - The DID of the user who shared the data
+     * @param key - The key that was shared
+     * @param options - Optional get configuration
+     * @returns Result with the decrypted entry
+     */
+    getShared<T = unknown>(grantorDID: string, key: string, options?: VaultGetOptions<T>): Promise<Result<VaultEntry<T>, VaultError>>;
+    /** The vault's public encryption key (X25519). */
+    readonly publicKey: Uint8Array;
+    /**
+     * Resolve another user's public encryption key from their DID.
+     *
+     * @param did - The DID to resolve
+     * @returns Result with the public key bytes
+     */
+    resolvePublicKey(did: string): Promise<Result<Uint8Array, VaultError>>;
+}
+
+/**
+ * DataVaultService - Encrypted key-value storage service implementation.
+ *
+ * Platform-agnostic encrypted KV service that wraps KVService internally.
+ * Uses dependency injection via VaultCrypto for WASM crypto operations
+ * and DataVaultServiceConfig for platform dependencies.
+ *
+ * Architecture:
+ * - Extends BaseService (not KVService)
+ * - Wraps two KV instances: dataKV (prefix "vault/") and keyKV (prefix "keys/")
+ * - Master key and encryption identity live in memory only (cleared on lock)
+ */
+
+/**
+ * Crypto operations interface - implementations provided by WASM bindings.
+ * Passed via DataVaultServiceConfig to keep the service platform-agnostic.
+ */
+interface VaultCrypto {
+    encrypt(key: Uint8Array, plaintext: Uint8Array): Uint8Array;
+    decrypt(key: Uint8Array, blob: Uint8Array): Uint8Array;
+    deriveKey(signature: Uint8Array, salt: Uint8Array, info: Uint8Array): Uint8Array;
+    x25519FromSeed(seed: Uint8Array): {
+        publicKey: Uint8Array;
+        privateKey: Uint8Array;
+    };
+    x25519Dh(privateKey: Uint8Array, publicKey: Uint8Array): Uint8Array;
+    randomBytes(length: number): Uint8Array;
+    sha256(data: Uint8Array): Uint8Array;
+}
+/**
+ * Extended config used internally by DataVaultService.
+ * Includes crypto operations and TinyCloud instance references.
+ */
+interface DataVaultServiceConfig extends DataVaultConfig {
+    [key: string]: unknown;
+    /** Crypto operations (WASM bindings) */
+    crypto: VaultCrypto;
+    /** TinyCloud instance for space/kv/delegation operations */
+    tc: {
+        kv: IKVService;
+        ensurePublicSpace(): Promise<Result<void>>;
+        publicKV: IKVService;
+        readPublicSpace<T>(host: string, spaceId: string, key: string): Promise<Result<T>>;
+        makePublicSpaceId(address: string, chainId: number): string;
+        did: string;
+        address: string;
+        chainId: number;
+        hosts: string[];
+    };
+}
+/**
+ * Data Vault service implementation.
+ *
+ * Provides encrypted key-value storage with client-side encryption,
+ * key management, and sharing via X25519 grants.
+ *
+ * @example
+ * ```typescript
+ * // Unlock the vault
+ * await vault.unlock(signer);
+ *
+ * // Store encrypted data
+ * await vault.put('secret/notes', { content: 'Hello' });
+ *
+ * // Retrieve and decrypt
+ * const entry = await vault.get<{ content: string }>('secret/notes');
+ * if (entry.ok) {
+ *   console.log(entry.data.value.content); // 'Hello'
+ * }
+ *
+ * // Share with another user
+ * await vault.grant('secret/notes', recipientDID);
  * ```
  */
-export type { Result, ServiceError, StorageQuotaInfo, ErrorCode, IServiceContext, IService, ServiceSession, RetryPolicy, InvokeFunction, InvocationFact, InvocationFacts, FetchFunction, FetchRequestInit, FetchResponse, ServiceHeaders, EventHandler, ServiceRequestEvent, ServiceResponseEvent, ServiceErrorEvent, ServiceRetryEvent, } from "./types";
-export { ErrorCodes, defaultRetryPolicy, TelemetryEvents, ok, err, serviceError, } from "./types";
-export { ServiceErrorSchema, KVResponseHeadersSchema, KVListResponseSchema, ServiceRequestEventSchema, ServiceResponseEventSchema, ServiceErrorEventSchema, ServiceRetryEventSchema, RetryPolicySchema, ServiceSessionSchema, GenericResultSchema, GenericKVResponseSchema, KVListResultSchema, createResultSchema, createKVResponseSchema, validateServiceError, validateKVListResponse, validateKVResponseHeaders, validateServiceSession, validateRetryPolicy, validateServiceRequestEvent, validateServiceResponseEvent, } from "./types.schema";
-export type { ValidationError, ServiceErrorType, KVResponseHeadersType, KVListResponseType, GenericKVResponseType, KVListResultType, ServiceRequestEventType, ServiceResponseEventType, ServiceErrorEventType, ServiceRetryEventType, RetryPolicyType, ServiceSessionType, } from "./types.schema";
-export { ServiceContext } from "./context";
-export type { ServiceContextConfig } from "./context";
-export { authRequiredError, authExpiredError, networkError, timeoutError, abortedError, notFoundError, permissionDeniedError, wrapError, errorResult, storageQuotaExceededError, storageLimitReachedError, parseAuthError, authUnauthorizedError, } from "./errors";
-export { BaseService } from "./base/index";
-export type { ServiceConstructor, ServiceRegistration, BaseServiceOptions, } from "./base/index";
-export { KVService, PrefixedKVService, IKVService, KVAction } from "./kv";
-export type { IPrefixedKVService, KVServiceConfig, KVGetOptions, KVPutOptions, KVListOptions, KVDeleteOptions, KVHeadOptions, KVResponse, KVListResponse, KVResponseHeaders, KVActionType, } from "./kv";
-export { SQLService, DatabaseHandle, SQLAction } from "./sql";
-export type { ISQLService, IDatabaseHandle } from "./sql";
-export type { SQLServiceConfig, QueryOptions, ExecuteOptions, BatchOptions, SqlValue, SqlStatement, QueryResponse, ExecuteResponse, BatchResponse, SQLActionType, } from "./sql";
-export { DuckDbService, DuckDbDatabaseHandle, DuckDbAction } from "./duckdb";
-export type { IDuckDbService, IDuckDbDatabaseHandle } from "./duckdb";
-export type { DuckDbServiceConfig, DuckDbQueryOptions, DuckDbExecuteOptions, DuckDbBatchOptions, DuckDbOptions, DuckDbValue, DuckDbStatement, DuckDbQueryResponse, DuckDbExecuteResponse, DuckDbBatchResponse, DuckDbActionType, SchemaInfo, TableInfo, ColumnInfo, ViewInfo, } from "./duckdb";
-export { TinyCloudQuota } from "./quota";
-export type { QuotaConfig, QuotaStatus } from "./quota";
-export { DataVaultService, VaultHeaders, VaultPublicSpaceKVActions, createVaultCrypto } from "./vault";
-export type { IDataVaultService, VaultCrypto, WasmVaultFunctions } from "./vault";
-export type { DataVaultConfig, VaultPutOptions, VaultGetOptions, VaultListOptions, VaultGrantOptions, VaultEntry, VaultError, } from "./vault";
-//# sourceMappingURL=index.d.ts.map
+declare class DataVaultService extends BaseService implements IDataVaultService {
+    /**
+     * Service identifier for registration.
+     */
+    static readonly serviceName = "vault";
+    /**
+     * Service configuration.
+     */
+    protected _config: DataVaultServiceConfig;
+    private masterKey;
+    private encryptionIdentity;
+    private _isUnlocked;
+    private vaultConfig;
+    /**
+     * Create a new DataVaultService instance.
+     *
+     * @param config - Service configuration including crypto and tc references
+     */
+    constructor(config: DataVaultServiceConfig);
+    /**
+     * Get the service configuration.
+     */
+    get config(): DataVaultServiceConfig;
+    /**
+     * Whether the vault is currently unlocked.
+     */
+    get isUnlocked(): boolean;
+    /**
+     * The vault's public encryption key (X25519).
+     * Throws if vault is locked.
+     */
+    get publicKey(): Uint8Array;
+    /**
+     * Convenience accessor for crypto operations.
+     */
+    private get crypto();
+    /**
+     * Convenience accessor for TinyCloud instance.
+     */
+    private get tc();
+    /**
+     * Get the host URL.
+     */
+    private get host();
+    /**
+     * Unlock the vault. Derives keys from two wallet signatures:
+     * 1. Master signature (per-space) — used to derive the master encryption key
+     * 2. Identity signature (per-address) — used to derive X25519 encryption identity
+     *
+     * If the identity public key already exists in the public space, the identity
+     * signature is skipped entirely (no wallet popup). The identity private key is
+     * only needed for sharing operations.
+     *
+     * @param signer - Object with signMessage method. Optional when cached
+     *                 signatures exist (browser only).
+     */
+    unlock(signer?: {
+        signMessage(message: string): Promise<string>;
+    } | unknown): Promise<Result<void, VaultError>>;
+    /**
+     * Clear the cached vault signatures.
+     *
+     * @param spaceId - Clear only this space's master cache. If omitted, clears all.
+     */
+    clearCache(spaceId?: string): Promise<void>;
+    /**
+     * Lock the vault, clearing all key material from memory.
+     */
+    lock(): void;
+    /**
+     * Called when SDK signs out. Locks the vault and aborts operations.
+     */
+    onSignOut(): void;
+    /**
+     * Encrypt and store a value at the given key.
+     *
+     * @param key - The key to store under
+     * @param value - The value to encrypt and store
+     * @param options - Optional put configuration
+     */
+    put(key: string, value: unknown, options?: VaultPutOptions): Promise<Result<void, VaultError>>;
+    /**
+     * Retrieve and decrypt a value by key.
+     *
+     * @param key - The key to retrieve
+     * @param options - Optional get configuration
+     * @returns Result with the decrypted entry
+     */
+    get<T = unknown>(key: string, options?: VaultGetOptions<T>): Promise<Result<VaultEntry<T>, VaultError>>;
+    /**
+     * Delete an encrypted key.
+     * Removes both the encrypted value and the key blob.
+     *
+     * @param key - The key to delete
+     */
+    delete(key: string): Promise<Result<void, VaultError>>;
+    /**
+     * List vault keys with optional prefix filtering.
+     *
+     * @param options - Optional list configuration
+     * @returns Result with array of key names (vault/ prefix stripped)
+     */
+    list(options?: VaultListOptions): Promise<Result<string[], VaultError>>;
+    /**
+     * Get envelope metadata for a key without decrypting the value.
+     *
+     * @param key - The key to inspect
+     * @returns Result with metadata headers
+     */
+    head(key: string): Promise<Result<Record<string, string>, VaultError>>;
+    /**
+     * Encrypt and store multiple entries.
+     *
+     * @param entries - Array of key/value pairs with optional per-entry options
+     * @returns Array of results, one per entry
+     */
+    putMany(entries: Array<{
+        key: string;
+        value: unknown;
+        options?: VaultPutOptions;
+    }>): Promise<Result<void, VaultError>[]>;
+    /**
+     * Retrieve and decrypt multiple keys.
+     *
+     * @param keys - Array of keys to retrieve
+     * @param options - Optional get configuration applied to all entries
+     * @returns Array of results, one per key
+     */
+    getMany<T = unknown>(keys: string[], options?: VaultGetOptions<T>): Promise<Result<VaultEntry<T>, VaultError>[]>;
+    /**
+     * Re-encrypt a vault key for another user (renamed from grant).
+     * Re-encrypts the data key to the recipient's public key via X25519 DH.
+     *
+     * @param key - The key to share
+     * @param recipientDID - The recipient's primary DID (did:pkh:...)
+     * @param options - Optional grant configuration
+     */
+    reencrypt(key: string, recipientDID: string, options?: VaultGrantOptions): Promise<Result<void, VaultError>>;
+    /**
+     * @deprecated Use reencrypt() instead.
+     */
+    grant(key: string, recipientDID: string, options?: VaultGrantOptions): Promise<Result<void, VaultError>>;
+    /**
+     * Retrieve and decrypt a value shared by another user.
+     *
+     * @param grantorDID - The DID of the user who shared the data
+     * @param key - The key that was shared
+     * @param options - Optional get configuration
+     * @returns Result with the decrypted entry
+     */
+    getShared<T = unknown>(grantorDID: string, key: string, options?: VaultGetOptions<T>): Promise<Result<VaultEntry<T>, VaultError>>;
+    /**
+     * Resolve another user's public encryption key from their DID.
+     *
+     * @param did - The DID to resolve (did:pkh:eip155:{chainId}:{address})
+     * @returns Result with the public key bytes
+     */
+    resolvePublicKey(did: string): Promise<Result<Uint8Array, VaultError>>;
+    /**
+     * List DIDs that have been granted access to a key.
+     *
+     * @param key - The key to list grants for
+     * @returns Result with array of recipient DIDs
+     */
+    listGrants(key: string): Promise<Result<string[], VaultError>>;
+    /**
+     * Revoke a previously issued grant.
+     *
+     * This performs a full key rotation:
+     * 1. Lists current grantees
+     * 2. Removes the revoked recipient
+     * 3. Re-encrypts the value with a new entry key
+     * 4. Re-issues grants to remaining recipients
+     *
+     * @param key - The key to revoke access to
+     * @param recipientDID - The recipient whose access to revoke
+     */
+    revoke(key: string, recipientDID: string): Promise<Result<void, VaultError>>;
+    /**
+     * Parse a DID string to extract address and chainId.
+     * Expected format: did:pkh:eip155:{chainId}:{address}
+     *
+     * @param did - The DID to parse
+     * @returns Parsed address and chainId, or null if invalid
+     */
+    private parseDID;
+}
+
+interface WasmVaultFunctions {
+    vault_encrypt(key: Uint8Array, plaintext: Uint8Array): Uint8Array;
+    vault_decrypt(key: Uint8Array, blob: Uint8Array): Uint8Array;
+    /** WASM order: (salt, signature, info) — NOT (signature, salt, info) */
+    vault_derive_key(salt: Uint8Array, signature: Uint8Array, info: Uint8Array): Uint8Array;
+    vault_x25519_from_seed(seed: Uint8Array): {
+        publicKey: Uint8Array;
+        privateKey: Uint8Array;
+    };
+    vault_x25519_dh(privateKey: Uint8Array, publicKey: Uint8Array): Uint8Array;
+    vault_random_bytes(length: number): Uint8Array;
+    vault_sha256(data: Uint8Array): Uint8Array;
+}
+declare function createVaultCrypto(wasm: WasmVaultFunctions): VaultCrypto;
+
+export { BaseService, type BaseServiceOptions, type ColumnInfo, type DataVaultConfig, DataVaultService, DuckDbAction, type DuckDbActionType, type DuckDbBatchOptions, type BatchResponse as DuckDbBatchResponse, DuckDbDatabaseHandle, type DuckDbExecuteOptions, type ExecuteResponse as DuckDbExecuteResponse, type DuckDbOptions, type DuckDbQueryOptions, type QueryResponse as DuckDbQueryResponse, DuckDbService, type DuckDbServiceConfig, type DuckDbStatement, type DuckDbValue, FetchFunction, GenericKVResponseSchema, type GenericKVResponseType, GenericResultSchema, type IDataVaultService, type IDuckDbDatabaseHandle, type IDuckDbService, IKVService, IService, IServiceContext, InvokeFunction, KVListResponseSchema, type KVListResponseType, KVListResultSchema, type KVListResultType, KVResponseHeadersSchema, type KVResponseHeadersType, type QuotaConfig, type QuotaStatus, Result, RetryPolicy, RetryPolicySchema, type RetryPolicyType, type SchemaInfo, type ServiceConstructor, ServiceContext, type ServiceContextConfig, ServiceError, ServiceErrorEventSchema, type ServiceErrorEventType, ServiceErrorSchema, type ServiceErrorType, type ServiceRegistration, ServiceRequestEventSchema, type ServiceRequestEventType, ServiceResponseEventSchema, type ServiceResponseEventType, ServiceRetryEventSchema, type ServiceRetryEventType, ServiceSession, ServiceSessionSchema, type ServiceSessionType, StorageQuotaInfo, type TableInfo, TinyCloudQuota, type ValidationError, type VaultCrypto, type VaultEntry, type VaultError, type VaultGetOptions, type VaultGrantOptions, VaultHeaders, type VaultListOptions, VaultPublicSpaceKVActions, type VaultPutOptions, type ViewInfo, type WasmVaultFunctions, abortedError, authExpiredError, authRequiredError, authUnauthorizedError, createKVResponseSchema, createResultSchema, createVaultCrypto, errorResult, networkError, notFoundError, parseAuthError, permissionDeniedError, storageLimitReachedError, storageQuotaExceededError, timeoutError, validateKVListResponse, validateKVResponseHeaders, validateRetryPolicy, validateServiceError, validateServiceRequestEvent, validateServiceResponseEvent, validateServiceSession, wrapError };