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

package/dist/kv/index.d.ts

@@ -1,10 +1,748 @@
+import { d as Result, b as IService, B as BaseService } from '../BaseService-D9BFm_rV.js';
+
 /**
- * KV Service Exports
+ * KV Service Types
  *
- * Key-Value storage service for TinyCloud SDK.
+ * Type definitions for the KV (Key-Value) service operations.
  */
-export { KVService } from "./KVService";
-export { PrefixedKVService, IPrefixedKVService } from "./PrefixedKVService";
-export { IKVService } from "./IKVService";
-export { KVServiceConfig, KVGetOptions, KVPutOptions, KVListOptions, KVDeleteOptions, KVHeadOptions, KVResponse, KVListResponse, KVResponseHeaders, KVAction, KVActionType, } from "./types";
-//# sourceMappingURL=index.d.ts.map
+/**
+ * Configuration for KVService.
+ */
+interface KVServiceConfig {
+    /**
+     * Default prefix for all keys.
+     * Useful for namespacing data within a space.
+     *
+     * @example
+     * ```typescript
+     * const kv = new KVService({ prefix: 'myapp/settings' });
+     * await kv.put('theme', 'dark'); // Stores at 'myapp/settings/theme'
+     * ```
+     */
+    prefix?: string;
+    /**
+     * Default timeout in milliseconds for KV operations.
+     * Overrides the context-level timeout if set.
+     */
+    timeout?: number;
+    /** Allow additional config properties */
+    [key: string]: unknown;
+}
+/**
+ * Options for KV get operations.
+ */
+interface KVGetOptions {
+    /**
+     * Override the default prefix for this operation.
+     */
+    prefix?: string;
+    /**
+     * Return raw response instead of parsed JSON.
+     * When true, data will be the raw response text.
+     */
+    raw?: boolean;
+    /**
+     * Custom timeout for this operation in milliseconds.
+     */
+    timeout?: number;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Options for KV put operations.
+ */
+interface KVPutOptions {
+    /**
+     * Override the default prefix for this operation.
+     */
+    prefix?: string;
+    /**
+     * Content type for the value.
+     * Defaults to 'application/json' for objects.
+     */
+    contentType?: string;
+    /**
+     * Custom metadata headers to store with the value.
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Custom timeout for this operation in milliseconds.
+     */
+    timeout?: number;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Options for KV list operations.
+ */
+interface KVListOptions {
+    /**
+     * Override the default prefix for this operation.
+     */
+    prefix?: string;
+    /**
+     * Additional path to append to the prefix.
+     */
+    path?: string;
+    /**
+     * Whether to remove the prefix from returned keys.
+     * When true, keys are returned relative to the prefix.
+     */
+    removePrefix?: boolean;
+    /**
+     * Return raw response instead of parsed JSON.
+     */
+    raw?: boolean;
+    /**
+     * Custom timeout for this operation in milliseconds.
+     */
+    timeout?: number;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Options for KV delete operations.
+ */
+interface KVDeleteOptions {
+    /**
+     * Override the default prefix for this operation.
+     */
+    prefix?: string;
+    /**
+     * Custom timeout for this operation in milliseconds.
+     */
+    timeout?: number;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Options for KV head (metadata) operations.
+ */
+interface KVHeadOptions {
+    /**
+     * Override the default prefix for this operation.
+     */
+    prefix?: string;
+    /**
+     * Custom timeout for this operation in milliseconds.
+     */
+    timeout?: number;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Response headers from KV operations.
+ */
+interface KVResponseHeaders {
+    /**
+     * ETag for conditional requests.
+     */
+    etag?: string;
+    /**
+     * Content type of the stored value.
+     */
+    contentType?: string;
+    /**
+     * Last modification timestamp.
+     */
+    lastModified?: string;
+    /**
+     * Content length in bytes.
+     */
+    contentLength?: number;
+    /**
+     * Get a header value by name.
+     * @param name - Header name (case-insensitive)
+     */
+    get(name: string): string | null;
+}
+/**
+ * Response from KV get/put operations.
+ *
+ * @template T - Type of the data payload
+ */
+interface KVResponse<T = unknown> {
+    /**
+     * The data payload.
+     * For get: the stored value.
+     * For put: undefined.
+     */
+    data: T;
+    /**
+     * Response headers with metadata.
+     */
+    headers: KVResponseHeaders;
+}
+/**
+ * Response from KV list operations.
+ */
+interface KVListResponse {
+    /**
+     * Array of keys matching the list criteria.
+     */
+    keys: string[];
+}
+/**
+ * KV service action types.
+ */
+declare const KVAction: {
+    readonly GET: "tinycloud.kv/get";
+    readonly PUT: "tinycloud.kv/put";
+    readonly LIST: "tinycloud.kv/list";
+    readonly DELETE: "tinycloud.kv/del";
+    readonly HEAD: "tinycloud.kv/metadata";
+};
+type KVActionType = (typeof KVAction)[keyof typeof KVAction];
+
+/**
+ * PrefixedKVService - A prefix-scoped view of KVService.
+ *
+ * Provides key-value operations scoped to a specific prefix.
+ * All operations automatically prefix keys, enabling app data isolation
+ * within a shared space.
+ *
+ * @example
+ * ```typescript
+ * const space = sdk.space('default');
+ *
+ * // Create prefix-scoped views
+ * const myApp = space.kv.withPrefix('/app.myapp.com');
+ * const sharedPhotos = space.kv.withPrefix('/photos');
+ *
+ * // Operations are automatically prefixed
+ * await myApp.put('settings.json', { theme: 'dark' });
+ * // -> Actually writes to: /app.myapp.com/settings.json
+ *
+ * await myApp.get('settings.json');
+ * // -> Actually reads from: /app.myapp.com/settings.json
+ *
+ * await sharedPhotos.list();
+ * // -> Lists: /photos/*
+ *
+ * // Nested prefixes
+ * const settings = myApp.withPrefix('/settings');
+ * await settings.get('theme.json');  // -> /app.myapp.com/settings/theme.json
+ * ```
+ */
+
+/**
+ * Interface for prefixed KV operations.
+ *
+ * Provides the same operations as IKVService but scoped to a prefix.
+ * Supports nested prefixes via withPrefix().
+ */
+interface IPrefixedKVService {
+    /**
+     * The current prefix for this scoped view.
+     */
+    readonly prefix: string;
+    /**
+     * Get a value by key.
+     *
+     * The key is automatically prefixed with this service's prefix.
+     *
+     * @param key - The key to retrieve (will be prefixed)
+     * @param options - Optional get configuration
+     * @returns Result with the stored value and headers
+     *
+     * @example
+     * ```typescript
+     * const myApp = kv.withPrefix('/app.myapp.com');
+     * const result = await myApp.get('settings.json');
+     * // -> Reads from: /app.myapp.com/settings.json
+     * ```
+     */
+    get<T = unknown>(key: string, options?: Omit<KVGetOptions, 'prefix'>): Promise<Result<KVResponse<T>>>;
+    /**
+     * Store a value at a key.
+     *
+     * The key is automatically prefixed with this service's prefix.
+     *
+     * @param key - The key to store under (will be prefixed)
+     * @param value - The value to store
+     * @param options - Optional put configuration
+     * @returns Result indicating success/failure
+     *
+     * @example
+     * ```typescript
+     * const myApp = kv.withPrefix('/app.myapp.com');
+     * await myApp.put('settings.json', { theme: 'dark' });
+     * // -> Stores at: /app.myapp.com/settings.json
+     * ```
+     */
+    put(key: string, value: unknown, options?: Omit<KVPutOptions, 'prefix'>): Promise<Result<KVResponse<void>>>;
+    /**
+     * List keys within this prefix.
+     *
+     * Returns keys that match the prefix, with keys returned relative
+     * to the prefix when removePrefix is true (default for prefixed service).
+     *
+     * @param options - Optional list configuration
+     * @returns Result with array of matching keys
+     *
+     * @example
+     * ```typescript
+     * const myApp = kv.withPrefix('/app.myapp.com');
+     * const result = await myApp.list();
+     * // -> Lists keys under: /app.myapp.com/*
+     * // Returns: ['settings.json', 'data/user.json', ...]
+     * ```
+     */
+    list(options?: Omit<KVListOptions, 'prefix'>): Promise<Result<KVListResponse>>;
+    /**
+     * Delete a key.
+     *
+     * The key is automatically prefixed with this service's prefix.
+     *
+     * @param key - The key to delete (will be prefixed)
+     * @param options - Optional delete configuration
+     * @returns Result indicating success/failure
+     *
+     * @example
+     * ```typescript
+     * const myApp = kv.withPrefix('/app.myapp.com');
+     * await myApp.delete('old-settings.json');
+     * // -> Deletes: /app.myapp.com/old-settings.json
+     * ```
+     */
+    delete(key: string, options?: Omit<KVDeleteOptions, 'prefix'>): Promise<Result<void>>;
+    /**
+     * Get metadata for a key without retrieving the value.
+     *
+     * The key is automatically prefixed with this service's prefix.
+     *
+     * @param key - The key to check (will be prefixed)
+     * @param options - Optional head configuration
+     * @returns Result with headers only
+     *
+     * @example
+     * ```typescript
+     * const myApp = kv.withPrefix('/app.myapp.com');
+     * const result = await myApp.head('large-file.bin');
+     * // -> Gets metadata for: /app.myapp.com/large-file.bin
+     * ```
+     */
+    head(key: string, options?: Omit<KVHeadOptions, 'prefix'>): Promise<Result<KVResponse<void>>>;
+    /**
+     * Create a nested prefix-scoped view.
+     *
+     * The subPrefix is appended to the current prefix.
+     *
+     * @param subPrefix - The sub-prefix to append
+     * @returns A new PrefixedKVService with the combined prefix
+     *
+     * @example
+     * ```typescript
+     * const myApp = kv.withPrefix('/app.myapp.com');
+     * const settings = myApp.withPrefix('/settings');
+     * await settings.get('theme.json');
+     * // -> Reads from: /app.myapp.com/settings/theme.json
+     * ```
+     */
+    withPrefix(subPrefix: string): IPrefixedKVService;
+}
+/**
+ * Interface for a KV service that supports prefix delegation.
+ *
+ * This is the subset of IKVService methods needed by PrefixedKVService.
+ */
+interface IKVServiceLike {
+    get<T = unknown>(key: string, options?: KVGetOptions): Promise<Result<KVResponse<T>>>;
+    put(key: string, value: unknown, options?: KVPutOptions): Promise<Result<KVResponse<void>>>;
+    list(options?: KVListOptions): Promise<Result<KVListResponse>>;
+    delete(key: string, options?: KVDeleteOptions): Promise<Result<void>>;
+    head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
+}
+/**
+ * PrefixedKVService - Implementation of prefix-scoped KV operations.
+ *
+ * This class wraps a KVService (or another PrefixedKVService) and
+ * automatically prefixes all key operations with the configured prefix.
+ *
+ * ## Prefix Convention
+ *
+ * | Pattern | Use Case | Example |
+ * | -- | -- | -- |
+ * | `/app.{domain}/` | App-private data | `/app.photos.xyz/settings.json` |
+ * | `/{type}/` | Shared data type | `/photos/vacation.jpg` |
+ * | `/.{name}/` | Hidden/system data | `/.cache/thumbnails/` |
+ * | `/public/` | Explicitly shareable | `/public/profile.json` |
+ *
+ * @example
+ * ```typescript
+ * // Create from KVService
+ * const prefixed = new PrefixedKVService(kvService, '/app.myapp.com');
+ *
+ * // Or use the withPrefix factory method on KVService
+ * const prefixed = kvService.withPrefix('/app.myapp.com');
+ *
+ * // All operations are automatically prefixed
+ * await prefixed.put('settings.json', { theme: 'dark' });
+ * await prefixed.get('settings.json');
+ *
+ * // Nested prefixes
+ * const nested = prefixed.withPrefix('/settings');
+ * await nested.get('theme.json');  // -> /app.myapp.com/settings/theme.json
+ * ```
+ */
+declare class PrefixedKVService implements IPrefixedKVService {
+    /**
+     * The underlying KV service.
+     */
+    private readonly _kv;
+    /**
+     * The prefix for this scoped view.
+     */
+    private readonly _prefix;
+    /**
+     * Create a new PrefixedKVService.
+     *
+     * @param kv - The underlying KV service to delegate to
+     * @param prefix - The prefix to apply to all operations
+     */
+    constructor(kv: IKVServiceLike, prefix: string);
+    /**
+     * The current prefix for this scoped view.
+     */
+    get prefix(): string;
+    /**
+     * Compute the full key path by combining prefix and key.
+     *
+     * @param key - The key to prefix
+     * @returns The full path including prefix
+     */
+    private getFullKey;
+    /**
+     * Get a value by key.
+     */
+    get<T = unknown>(key: string, options?: Omit<KVGetOptions, 'prefix'>): Promise<Result<KVResponse<T>>>;
+    /**
+     * Store a value at a key.
+     */
+    put(key: string, value: unknown, options?: Omit<KVPutOptions, 'prefix'>): Promise<Result<KVResponse<void>>>;
+    /**
+     * List keys within this prefix.
+     */
+    list(options?: Omit<KVListOptions, 'prefix'>): Promise<Result<KVListResponse>>;
+    /**
+     * Delete a key.
+     */
+    delete(key: string, options?: Omit<KVDeleteOptions, 'prefix'>): Promise<Result<void>>;
+    /**
+     * Get metadata for a key without retrieving the value.
+     */
+    head(key: string, options?: Omit<KVHeadOptions, 'prefix'>): Promise<Result<KVResponse<void>>>;
+    /**
+     * Create a nested prefix-scoped view.
+     */
+    withPrefix(subPrefix: string): IPrefixedKVService;
+}
+
+/**
+ * IKVService - Interface for KV (Key-Value) service.
+ *
+ * Platform-agnostic interface for key-value storage operations.
+ * Implementations use dependency injection via IServiceContext.
+ */
+
+/**
+ * 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);
+ * }
+ * ```
+ */
+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;
+}
+
+/**
+ * KVService - Key-Value storage service implementation.
+ *
+ * Platform-agnostic KV service that works with both web-sdk and node-sdk.
+ * Uses dependency injection via IServiceContext for platform dependencies.
+ */
+
+/**
+ * KV service implementation.
+ *
+ * Provides key-value storage operations using TinyCloud's KV API.
+ * Uses the Result type pattern for explicit error handling.
+ *
+ * @example
+ * ```typescript
+ * // Register with SDK
+ * const sdk = new TinyCloud({
+ *   services: { kv: KVService },
+ *   serviceConfigs: { kv: { prefix: 'myapp' } },
+ * });
+ *
+ * // Use the service
+ * const result = await sdk.kv.get('settings');
+ * if (result.ok) {
+ *   console.log(result.data.data);
+ * }
+ * ```
+ */
+declare class KVService extends BaseService implements IKVService {
+    /**
+     * Service identifier for registration.
+     */
+    static readonly serviceName = "kv";
+    /**
+     * Service configuration.
+     */
+    protected _config: KVServiceConfig;
+    /**
+     * Create a new KVService instance.
+     *
+     * @param config - Service configuration
+     */
+    constructor(config?: KVServiceConfig);
+    /**
+     * Get the service configuration.
+     */
+    get config(): KVServiceConfig;
+    private parseQuotaInfo;
+    private handleQuotaErrorResponse;
+    /**
+     * Get the full path with optional prefix.
+     *
+     * @param key - The key
+     * @param prefixOverride - Optional prefix override
+     * @returns The full path
+     */
+    private getFullPath;
+    /**
+     * Get the host URL.
+     */
+    private get host();
+    /**
+     * Execute an invoke operation.
+     *
+     * @param path - Resource path
+     * @param action - KV action
+     * @param body - Optional request body
+     * @param signal - Optional abort signal
+     * @returns Fetch response
+     */
+    private invokeOperation;
+    /**
+     * Create KVResponseHeaders from fetch response headers.
+     *
+     * @param headers - Fetch response headers
+     * @returns KVResponseHeaders object
+     */
+    private createResponseHeaders;
+    /**
+     * Parse response body based on content type.
+     *
+     * @param response - Fetch response
+     * @param raw - Whether to return raw text
+     * @returns Parsed data
+     */
+    private parseResponse;
+    /**
+     * Get a value by key.
+     */
+    get<T = unknown>(key: string, options?: KVGetOptions): Promise<Result<KVResponse<T>>>;
+    /**
+     * Store a value at a key.
+     */
+    put(key: string, value: unknown, options?: KVPutOptions): Promise<Result<KVResponse<void>>>;
+    /**
+     * List keys with optional prefix filtering.
+     */
+    list(options?: KVListOptions): Promise<Result<KVListResponse>>;
+    /**
+     * Delete a key.
+     */
+    delete(key: string, options?: KVDeleteOptions): Promise<Result<void>>;
+    /**
+     * Get metadata for a key without retrieving the value.
+     */
+    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
+     *
+     * ## Prefix Conventions
+     *
+     * | Pattern | Use Case | Example |
+     * | -- | -- | -- |
+     * | `/app.{domain}/` | App-private data | `/app.photos.xyz/settings.json` |
+     * | `/{type}/` | Shared data type | `/photos/vacation.jpg` |
+     * | `/.{name}/` | Hidden/system data | `/.cache/thumbnails/` |
+     * | `/public/` | Explicitly shareable | `/public/profile.json` |
+     *
+     * @example
+     * ```typescript
+     * const space = sdk.space('default');
+     *
+     * // Create prefix-scoped views
+     * const myApp = space.kv.withPrefix('/app.myapp.com');
+     * const sharedPhotos = space.kv.withPrefix('/photos');
+     *
+     * // Operations are automatically prefixed
+     * await myApp.put('settings.json', { theme: 'dark' });
+     * // -> Actually writes to: /app.myapp.com/settings.json
+     *
+     * await myApp.get('settings.json');
+     * // -> Actually reads from: /app.myapp.com/settings.json
+     *
+     * await sharedPhotos.list();
+     * // -> Lists: /photos/*
+     *
+     * // Nested prefixes
+     * const settings = myApp.withPrefix('/settings');
+     * await settings.get('theme.json');  // -> /app.myapp.com/settings/theme.json
+     * ```
+     */
+    withPrefix(prefix: string): IPrefixedKVService;
+}
+
+export { type IKVService, type IPrefixedKVService, KVAction, type KVActionType, type KVDeleteOptions, type KVGetOptions, type KVHeadOptions, type KVListOptions, type KVListResponse, type KVPutOptions, type KVResponse, type KVResponseHeaders, KVService, type KVServiceConfig, PrefixedKVService };