@tinycloudlabs/sdk-services 1.0.0

package/dist/context.js

@@ -0,0 +1,218 @@
+/**
+ * ServiceContext implementation for TinyCloud SDK Services
+ * @module @tinycloudlabs/sdk-services
+ */
+import { defaultRetryPolicy, } from "./types";
+/**
+ * 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
+ * const context = new ServiceContext({
+ *   invoke: wasmInvoke,
+ *   hosts: ['https://node.tinycloud.xyz'],
+ *   retryPolicy: { maxAttempts: 5 },
+ * });
+ *
+ * // Register a service
+ * const kvService = new KVService({});
+ * context.registerService('kv', kvService);
+ * kvService.initialize(context);
+ *
+ * // Update session when user signs in
+ * context.setSession(userSession);
+ * ```
+ */
+export class ServiceContext {
+    constructor(config) {
+        this._session = null;
+        this._services = new Map();
+        this._eventHandlers = new Map();
+        this._abortController = new AbortController();
+        this._invoke = config.invoke;
+        this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
+        this._hosts = config.hosts;
+        this._session = config.session ?? null;
+        this._retryPolicy = {
+            ...defaultRetryPolicy,
+            ...config.retryPolicy,
+        };
+    }
+    // ============================================================
+    // Session Management
+    // ============================================================
+    /**
+     * Get the current session.
+     */
+    get session() {
+        return this._session;
+    }
+    /**
+     * Check if the context has an authenticated session.
+     */
+    get isAuthenticated() {
+        return this._session !== null;
+    }
+    /**
+     * Update the session and notify all registered services.
+     *
+     * @param session - New session or null to clear
+     */
+    setSession(session) {
+        this._session = session;
+        this.emit('session.changed', { authenticated: session !== null });
+        // Notify all services of session change
+        for (const service of this._services.values()) {
+            service.onSessionChange(session);
+        }
+    }
+    // ============================================================
+    // Platform Dependencies
+    // ============================================================
+    /**
+     * Get the invoke function for WASM operations.
+     */
+    get invoke() {
+        return this._invoke;
+    }
+    /**
+     * Get the fetch function for HTTP requests.
+     */
+    get fetch() {
+        return this._fetch;
+    }
+    /**
+     * Get the list of TinyCloud host URLs.
+     */
+    get hosts() {
+        return this._hosts;
+    }
+    // ============================================================
+    // Service Registry
+    // ============================================================
+    /**
+     * Register a service with the context.
+     *
+     * @param name - Service name (e.g., 'kv')
+     * @param service - Service instance
+     */
+    registerService(name, service) {
+        this._services.set(name, service);
+    }
+    /**
+     * Unregister a service from the context.
+     *
+     * @param name - Service name to remove
+     */
+    unregisterService(name) {
+        this._services.delete(name);
+    }
+    /**
+     * Get a registered service by name.
+     *
+     * @param name - Service name
+     * @returns The service instance or undefined if not registered
+     */
+    getService(name) {
+        return this._services.get(name);
+    }
+    // ============================================================
+    // Event System (Telemetry)
+    // ============================================================
+    /**
+     * Emit a telemetry event.
+     *
+     * @param event - Event name
+     * @param data - Event data
+     */
+    emit(event, data) {
+        const handlers = this._eventHandlers.get(event);
+        if (handlers) {
+            for (const handler of handlers) {
+                try {
+                    handler(data);
+                }
+                catch (error) {
+                    // Don't let event handler errors break the flow
+                    console.error(`Error in event handler for "${event}":`, error);
+                }
+            }
+        }
+    }
+    /**
+     * Subscribe to telemetry events.
+     *
+     * @param event - Event name to subscribe to
+     * @param handler - Handler function
+     * @returns Unsubscribe function
+     */
+    on(event, handler) {
+        if (!this._eventHandlers.has(event)) {
+            this._eventHandlers.set(event, new Set());
+        }
+        this._eventHandlers.get(event).add(handler);
+        // Return unsubscribe function
+        return () => {
+            const handlers = this._eventHandlers.get(event);
+            if (handlers) {
+                handlers.delete(handler);
+                if (handlers.size === 0) {
+                    this._eventHandlers.delete(event);
+                }
+            }
+        };
+    }
+    /**
+     * Remove all event handlers for an event.
+     *
+     * @param event - Event name (if omitted, clears all events)
+     */
+    clearEventHandlers(event) {
+        if (event) {
+            this._eventHandlers.delete(event);
+        }
+        else {
+            this._eventHandlers.clear();
+        }
+    }
+    // ============================================================
+    // Lifecycle
+    // ============================================================
+    /**
+     * Get the abort signal for cancelling operations.
+     */
+    get abortSignal() {
+        return this._abortController.signal;
+    }
+    /**
+     * Abort all pending operations and notify services.
+     * Creates a new AbortController for future operations.
+     */
+    abort() {
+        this._abortController.abort();
+        this._abortController = new AbortController();
+        // Notify all services
+        for (const service of this._services.values()) {
+            service.onSignOut();
+        }
+    }
+    /**
+     * Sign out - abort operations and clear session.
+     */
+    signOut() {
+        this.abort();
+        this.setSession(null);
+        this.emit('session.expired', {});
+    }
+    // ============================================================
+    // Retry Policy
+    // ============================================================
+    /**
+     * Get the retry policy configuration.
+     */
+    get retryPolicy() {
+        return this._retryPolicy;
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SDK Services - Error Utilities
+ *
+ * Utilities for creating and handling service errors.
+ */
+import { ServiceError } from "./types";
+/**
+ * Create a service error for authentication required.
+ */
+export declare function authRequiredError(service: string): ServiceError;
+/**
+ * Create a service error for expired authentication.
+ */
+export declare function authExpiredError(service: string): ServiceError;
+/**
+ * Create a service error for network issues.
+ */
+export declare function networkError(service: string, message: string, cause?: Error): ServiceError;
+/**
+ * Create a service error for timeouts.
+ */
+export declare function timeoutError(service: string): ServiceError;
+/**
+ * Create a service error for aborted requests.
+ */
+export declare function abortedError(service: string): ServiceError;
+/**
+ * Create a service error for not found resources.
+ */
+export declare function notFoundError(service: string, resource: string): ServiceError;
+/**
+ * Create a service error for permission denied.
+ */
+export declare function permissionDeniedError(service: string, action: string): ServiceError;
+/**
+ * Wrap an unknown error in a ServiceError.
+ */
+export declare function wrapError(service: string, error: unknown, defaultCode?: string): ServiceError;
+/**
+ * Create an error Result from a ServiceError.
+ */
+export declare function errorResult(error: ServiceError): import("./types").Result<never, ServiceError>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAmB,MAAM,SAAS,CAAC;AAExD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAM/D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAM9D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,KAAK,GACZ,YAAY,CAOd;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAM1D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAM1D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,YAAY,CAMd;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,YAAY,CAMd;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,EACd,WAAW,GAAE,MAAiC,GAC7C,YAAY,CA4Bd;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,iDAE9C"}

package/dist/errors.js

@@ -0,0 +1,111 @@
+/**
+ * SDK Services - Error Utilities
+ *
+ * Utilities for creating and handling service errors.
+ */
+import { ErrorCodes, err } from "./types";
+/**
+ * Create a service error for authentication required.
+ */
+export function authRequiredError(service) {
+    return {
+        code: ErrorCodes.AUTH_REQUIRED,
+        message: "Authentication required. Please sign in first.",
+        service,
+    };
+}
+/**
+ * Create a service error for expired authentication.
+ */
+export function authExpiredError(service) {
+    return {
+        code: ErrorCodes.AUTH_EXPIRED,
+        message: "Session has expired. Please sign in again.",
+        service,
+    };
+}
+/**
+ * Create a service error for network issues.
+ */
+export function networkError(service, message, cause) {
+    return {
+        code: ErrorCodes.NETWORK_ERROR,
+        message,
+        service,
+        cause,
+    };
+}
+/**
+ * Create a service error for timeouts.
+ */
+export function timeoutError(service) {
+    return {
+        code: ErrorCodes.TIMEOUT,
+        message: "Request timed out.",
+        service,
+    };
+}
+/**
+ * Create a service error for aborted requests.
+ */
+export function abortedError(service) {
+    return {
+        code: ErrorCodes.ABORTED,
+        message: "Request was aborted.",
+        service,
+    };
+}
+/**
+ * Create a service error for not found resources.
+ */
+export function notFoundError(service, resource) {
+    return {
+        code: ErrorCodes.NOT_FOUND,
+        message: `Resource not found: ${resource}`,
+        service,
+    };
+}
+/**
+ * Create a service error for permission denied.
+ */
+export function permissionDeniedError(service, action) {
+    return {
+        code: ErrorCodes.PERMISSION_DENIED,
+        message: `Permission denied for action: ${action}`,
+        service,
+    };
+}
+/**
+ * Wrap an unknown error in a ServiceError.
+ */
+export function wrapError(service, error, defaultCode = ErrorCodes.NETWORK_ERROR) {
+    if (error instanceof Error) {
+        // Check for abort errors
+        if (error.name === "AbortError") {
+            return abortedError(service);
+        }
+        // Check for timeout errors (varies by platform)
+        if (error.name === "TimeoutError" ||
+            error.message.toLowerCase().includes("timeout")) {
+            return timeoutError(service);
+        }
+        return {
+            code: defaultCode,
+            message: error.message,
+            service,
+            cause: error,
+        };
+    }
+    return {
+        code: defaultCode,
+        message: String(error),
+        service,
+    };
+}
+/**
+ * Create an error Result from a ServiceError.
+ */
+export function errorResult(error) {
+    return err(error);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAgB,UAAU,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAExD;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,aAAa;QAC9B,OAAO,EAAE,gDAAgD;QACzD,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,YAAY;QAC7B,OAAO,EAAE,4CAA4C;QACrD,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAC1B,OAAe,EACf,OAAe,EACf,KAAa;IAEb,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,aAAa;QAC9B,OAAO;QACP,OAAO;QACP,KAAK;KACN,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,OAAO;QACxB,OAAO,EAAE,oBAAoB;QAC7B,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,OAAO;QACxB,OAAO,EAAE,sBAAsB;QAC/B,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAe,EACf,QAAgB;IAEhB,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,SAAS;QAC1B,OAAO,EAAE,uBAAuB,QAAQ,EAAE;QAC1C,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAe,EACf,MAAc;IAEd,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,iBAAiB;QAClC,OAAO,EAAE,iCAAiC,MAAM,EAAE;QAClD,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CACvB,OAAe,EACf,KAAc,EACd,cAAsB,UAAU,CAAC,aAAa;IAE9C,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,yBAAyB;QACzB,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YAChC,OAAO,YAAY,CAAC,OAAO,CAAC,CAAC;QAC/B,CAAC;QAED,gDAAgD;QAChD,IACE,KAAK,CAAC,IAAI,KAAK,cAAc;YAC7B,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,EAC/C,CAAC;YACD,OAAO,YAAY,CAAC,OAAO,CAAC,CAAC;QAC/B,CAAC;QAED,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,OAAO;YACP,KAAK,EAAE,KAAK;SACb,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC;QACtB,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,KAAmB;IAC7C,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;AACpB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * TinyCloud SDK Services
+ *
+ * Platform-agnostic services with plugin architecture for TinyCloud.
+ *
+ * @packageDocumentation
+ * @module @tinycloudlabs/sdk-services
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   ServiceContext,
+ *   BaseService,
+ *   Result,
+ *   ErrorCodes,
+ * } from '@tinycloudlabs/sdk-services';
+ *
+ * // Create a context
+ * const context = new ServiceContext({
+ *   invoke: wasmInvoke,
+ *   hosts: ['https://node.tinycloud.xyz'],
+ * });
+ *
+ * // Create and register a service
+ * const kv = new KVService({ prefix: 'myapp' });
+ * context.registerService('kv', kv);
+ * kv.initialize(context);
+ *
+ * // Use the service
+ * const result = await kv.get('key');
+ * if (result.ok) {
+ *   console.log(result.data);
+ * }
+ * ```
+ */
+export type { Result, ServiceError, 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, } 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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,YAAY,EACV,MAAM,EACN,YAAY,EACZ,SAAS,EACT,eAAe,EACf,QAAQ,EACR,cAAc,EACd,WAAW,EACX,cAAc,EACd,cAAc,EACd,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,eAAe,EACf,EAAE,EACF,GAAG,EACH,YAAY,GACb,MAAM,SAAS,CAAC;AAGjB,OAAO,EAEL,kBAAkB,EAClB,uBAAuB,EACvB,oBAAoB,EACpB,yBAAyB,EACzB,0BAA0B,EAC1B,uBAAuB,EACvB,uBAAuB,EACvB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAElB,kBAAkB,EAClB,sBAAsB,EAEtB,oBAAoB,EACpB,sBAAsB,EACtB,yBAAyB,EACzB,sBAAsB,EACtB,mBAAmB,EACnB,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAEV,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,EACxB,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAGtD,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,qBAAqB,EACrB,SAAS,EACT,WAAW,GACZ,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,YAAY,EACV,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAC1E,YAAY,EACV,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,eAAe,EACf,aAAa,EACb,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,YAAY,GACb,MAAM,MAAM,CAAC"}

package/dist/index.js

@@ -0,0 +1,53 @@
+/**
+ * TinyCloud SDK Services
+ *
+ * Platform-agnostic services with plugin architecture for TinyCloud.
+ *
+ * @packageDocumentation
+ * @module @tinycloudlabs/sdk-services
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   ServiceContext,
+ *   BaseService,
+ *   Result,
+ *   ErrorCodes,
+ * } from '@tinycloudlabs/sdk-services';
+ *
+ * // Create a context
+ * const context = new ServiceContext({
+ *   invoke: wasmInvoke,
+ *   hosts: ['https://node.tinycloud.xyz'],
+ * });
+ *
+ * // Create and register a service
+ * const kv = new KVService({ prefix: 'myapp' });
+ * context.registerService('kv', kv);
+ * kv.initialize(context);
+ *
+ * // Use the service
+ * const result = await kv.get('key');
+ * if (result.ok) {
+ *   console.log(result.data);
+ * }
+ * ```
+ */
+export { ErrorCodes, defaultRetryPolicy, TelemetryEvents, ok, err, serviceError, } from "./types";
+// Zod schemas and validation
+export { 
+// Schemas
+ServiceErrorSchema, KVResponseHeadersSchema, KVListResponseSchema, ServiceRequestEventSchema, ServiceResponseEventSchema, ServiceErrorEventSchema, ServiceRetryEventSchema, RetryPolicySchema, ServiceSessionSchema, GenericResultSchema, GenericKVResponseSchema, KVListResultSchema, 
+// Schema factories
+createResultSchema, createKVResponseSchema, 
+// Validation functions
+validateServiceError, validateKVListResponse, validateKVResponseHeaders, validateServiceSession, validateRetryPolicy, validateServiceRequestEvent, validateServiceResponseEvent, } from "./types.schema";
+// Context
+export { ServiceContext } from "./context";
+// Errors
+export { authRequiredError, authExpiredError, networkError, timeoutError, abortedError, notFoundError, permissionDeniedError, wrapError, errorResult, } from "./errors";
+// Base service
+export { BaseService } from "./base/index";
+// KV service
+export { KVService, PrefixedKVService, KVAction } from "./kv";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAyBH,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,eAAe,EACf,EAAE,EACF,GAAG,EACH,YAAY,GACb,MAAM,SAAS,CAAC;AAEjB,6BAA6B;AAC7B,OAAO;AACL,UAAU;AACV,kBAAkB,EAClB,uBAAuB,EACvB,oBAAoB,EACpB,yBAAyB,EACzB,0BAA0B,EAC1B,uBAAuB,EACvB,uBAAuB,EACvB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB;AAClB,mBAAmB;AACnB,kBAAkB,EAClB,sBAAsB;AACtB,uBAAuB;AACvB,oBAAoB,EACpB,sBAAsB,EACtB,yBAAyB,EACzB,sBAAsB,EACtB,mBAAmB,EACnB,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,gBAAgB,CAAC;AAkBxB,UAAU;AACV,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG3C,SAAS;AACT,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,qBAAqB,EACrB,SAAS,EACT,WAAW,GACZ,MAAM,UAAU,CAAC;AAElB,eAAe;AACf,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAO3C,aAAa;AACb,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAc,QAAQ,EAAE,MAAM,MAAM,CAAC"}

package/dist/kv/IKVService.d.ts

@@ -0,0 +1,148 @@
+/**
+ * IKVService - Interface for KV (Key-Value) service.
+ *
+ * Platform-agnostic interface for key-value storage operations.
+ * Implementations use dependency injection via IServiceContext.
+ */
+import { IService, Result } from "../types";
+import type { IPrefixedKVService } from "./PrefixedKVService";
+import { KVServiceConfig, KVGetOptions, KVPutOptions, KVListOptions, KVDeleteOptions, KVHeadOptions, KVResponse, KVListResponse } from "./types";
+/**
+ * KV service interface.
+ *
+ * Provides key-value storage operations with:
+ * - Result type pattern (no throwing)
+ * - Optional prefix namespacing
+ * - Configurable timeouts
+ * - Abort signal support
+ *
+ * @example
+ * ```typescript
+ * const result = await kv.get('user/settings');
+ * if (result.ok) {
+ *   console.log('Settings:', result.data.data);
+ * } else {
+ *   console.error('Error:', result.error.code);
+ * }
+ * ```
+ */
+export interface IKVService extends IService {
+    /**
+     * Get a value by key.
+     *
+     * @param key - The key to retrieve
+     * @param options - Optional get configuration
+     * @returns Result with the stored value and headers
+     *
+     * @example
+     * ```typescript
+     * const result = await kv.get<UserSettings>('settings');
+     * if (result.ok) {
+     *   const settings = result.data.data;
+     *   const etag = result.data.headers.etag;
+     * }
+     * ```
+     */
+    get<T = unknown>(key: string, options?: KVGetOptions): Promise<Result<KVResponse<T>>>;
+    /**
+     * Store a value at a key.
+     *
+     * Objects are automatically JSON stringified.
+     * Strings are stored as-is.
+     *
+     * @param key - The key to store under
+     * @param value - The value to store
+     * @param options - Optional put configuration
+     * @returns Result indicating success/failure
+     *
+     * @example
+     * ```typescript
+     * // Store an object (auto-stringified)
+     * const result = await kv.put('settings', { theme: 'dark' });
+     *
+     * // Store a string
+     * const result = await kv.put('name', 'Alice');
+     * ```
+     */
+    put(key: string, value: unknown, options?: KVPutOptions): Promise<Result<KVResponse<void>>>;
+    /**
+     * List keys with optional prefix filtering.
+     *
+     * @param options - Optional list configuration
+     * @returns Result with array of matching keys
+     *
+     * @example
+     * ```typescript
+     * // List all keys
+     * const result = await kv.list();
+     *
+     * // List keys with a specific prefix
+     * const result = await kv.list({ prefix: 'users/' });
+     * ```
+     */
+    list(options?: KVListOptions): Promise<Result<KVListResponse>>;
+    /**
+     * Delete a key.
+     *
+     * @param key - The key to delete
+     * @param options - Optional delete configuration
+     * @returns Result indicating success/failure
+     *
+     * @example
+     * ```typescript
+     * const result = await kv.delete('old-key');
+     * if (!result.ok && result.error.code === 'KV_NOT_FOUND') {
+     *   console.log('Key already deleted');
+     * }
+     * ```
+     */
+    delete(key: string, options?: KVDeleteOptions): Promise<Result<void>>;
+    /**
+     * Get metadata for a key without retrieving the value.
+     *
+     * Useful for checking if a key exists or getting headers
+     * without downloading the full value.
+     *
+     * @param key - The key to check
+     * @param options - Optional head configuration
+     * @returns Result with headers only
+     *
+     * @example
+     * ```typescript
+     * const result = await kv.head('large-file');
+     * if (result.ok) {
+     *   console.log('Size:', result.data.headers.contentLength);
+     * }
+     * ```
+     */
+    head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
+    /**
+     * Create a prefix-scoped view of this KV service.
+     *
+     * Returns a PrefixedKVService that automatically prefixes all
+     * key operations with the specified prefix. This enables apps
+     * to isolate their data within a shared space.
+     *
+     * @param prefix - The prefix to apply to all operations
+     * @returns A PrefixedKVService scoped to the prefix
+     *
+     * @example
+     * ```typescript
+     * const myApp = kv.withPrefix('/app.myapp.com');
+     *
+     * // Operations are automatically prefixed
+     * await myApp.put('settings.json', { theme: 'dark' });
+     * // -> Actually writes to: /app.myapp.com/settings.json
+     *
+     * // Nested prefixes
+     * const settings = myApp.withPrefix('/settings');
+     * await settings.get('theme.json');  // -> /app.myapp.com/settings/theme.json
+     * ```
+     */
+    withPrefix(prefix: string): IPrefixedKVService;
+    /**
+     * Service configuration.
+     */
+    readonly config: KVServiceConfig;
+}
+//# sourceMappingURL=IKVService.d.ts.map

package/dist/kv/IKVService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IKVService.d.ts","sourceRoot":"","sources":["../../src/kv/IKVService.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EACL,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,eAAe,EACf,aAAa,EACb,UAAU,EACV,cAAc,EACf,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,UAAW,SAAQ,QAAQ;IAC1C;;;;;;;;;;;;;;;OAeG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EACb,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAElC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAErC;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC;IAE/D;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAEtE;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAE9E;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,CAAC;IAE/C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;CAClC"}

package/dist/kv/IKVService.js

@@ -0,0 +1,8 @@
+/**
+ * IKVService - Interface for KV (Key-Value) service.
+ *
+ * Platform-agnostic interface for key-value storage operations.
+ * Implementations use dependency injection via IServiceContext.
+ */
+export {};
+//# sourceMappingURL=IKVService.js.map

package/dist/kv/IKVService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IKVService.js","sourceRoot":"","sources":["../../src/kv/IKVService.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}