@tinycloudlabs/sdk-services 1.0.0

package/dist/kv/PrefixedKVService.d.ts

@@ -0,0 +1,246 @@
+/**
+ * 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
+ * ```
+ */
+import { Result } from "../types";
+import { KVGetOptions, KVPutOptions, KVListOptions, KVDeleteOptions, KVHeadOptions, KVResponse, KVListResponse } from "./types";
+/**
+ * Interface for prefixed KV operations.
+ *
+ * Provides the same operations as IKVService but scoped to a prefix.
+ * Supports nested prefixes via withPrefix().
+ */
+export 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
+ * ```
+ */
+export 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;
+}
+export {};
+//# sourceMappingURL=PrefixedKVService.d.ts.map

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

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

package/dist/kv/PrefixedKVService.js

@@ -0,0 +1,145 @@
+/**
+ * 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
+ * ```
+ */
+/**
+ * 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
+ * ```
+ */
+export class PrefixedKVService {
+    /**
+     * Create a new PrefixedKVService.
+     *
+     * @param kv - The underlying KV service to delegate to
+     * @param prefix - The prefix to apply to all operations
+     */
+    constructor(kv, prefix) {
+        this._kv = kv;
+        // Normalize prefix: ensure it doesn't end with slash
+        this._prefix = prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
+    }
+    /**
+     * The current prefix for this scoped view.
+     */
+    get prefix() {
+        return this._prefix;
+    }
+    /**
+     * Compute the full key path by combining prefix and key.
+     *
+     * @param key - The key to prefix
+     * @returns The full path including prefix
+     */
+    getFullKey(key) {
+        // Handle keys that start with slash
+        const normalizedKey = key.startsWith('/') ? key : `/${key}`;
+        return `${this._prefix}${normalizedKey}`;
+    }
+    /**
+     * Get a value by key.
+     */
+    async get(key, options) {
+        const fullKey = this.getFullKey(key);
+        // Use empty prefix override to use the full key as-is
+        return this._kv.get(fullKey, { ...options, prefix: '' });
+    }
+    /**
+     * Store a value at a key.
+     */
+    async put(key, value, options) {
+        const fullKey = this.getFullKey(key);
+        return this._kv.put(fullKey, value, { ...options, prefix: '' });
+    }
+    /**
+     * List keys within this prefix.
+     */
+    async list(options) {
+        // List uses the prefix directly, and by default removes the prefix from results
+        const removePrefix = options?.removePrefix ?? true;
+        return this._kv.list({
+            ...options,
+            prefix: this._prefix,
+            removePrefix,
+        });
+    }
+    /**
+     * Delete a key.
+     */
+    async delete(key, options) {
+        const fullKey = this.getFullKey(key);
+        return this._kv.delete(fullKey, { ...options, prefix: '' });
+    }
+    /**
+     * Get metadata for a key without retrieving the value.
+     */
+    async head(key, options) {
+        const fullKey = this.getFullKey(key);
+        return this._kv.head(fullKey, { ...options, prefix: '' });
+    }
+    /**
+     * Create a nested prefix-scoped view.
+     */
+    withPrefix(subPrefix) {
+        // Normalize subPrefix
+        const normalizedSubPrefix = subPrefix.startsWith('/')
+            ? subPrefix
+            : `/${subPrefix}`;
+        const combinedPrefix = `${this._prefix}${normalizedSubPrefix}`;
+        return new PrefixedKVService(this._kv, combinedPrefix);
+    }
+}
+//# sourceMappingURL=PrefixedKVService.js.map

package/dist/kv/PrefixedKVService.js.map

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

package/dist/kv/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * KV Service Exports
+ *
+ * Key-Value storage service for TinyCloud SDK.
+ */
+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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/kv/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAG5E,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,OAAO,EACL,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,eAAe,EACf,aAAa,EACb,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,QAAQ,EACR,YAAY,GACb,MAAM,SAAS,CAAC"}

package/dist/kv/index.js

@@ -0,0 +1,12 @@
+/**
+ * KV Service Exports
+ *
+ * Key-Value storage service for TinyCloud SDK.
+ */
+// Service implementation
+export { KVService } from "./KVService";
+// Prefixed service implementation
+export { PrefixedKVService } from "./PrefixedKVService";
+// Types
+export { KVAction, } from "./types";
+//# sourceMappingURL=index.js.map

package/dist/kv/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/kv/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,yBAAyB;AACzB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,kCAAkC;AAClC,OAAO,EAAE,iBAAiB,EAAsB,MAAM,qBAAqB,CAAC;AAK5E,QAAQ;AACR,OAAO,EAUL,QAAQ,GAET,MAAM,SAAS,CAAC"}

package/dist/kv/types.d.ts

@@ -0,0 +1,204 @@
+/**
+ * KV Service Types
+ *
+ * Type definitions for the KV (Key-Value) service operations.
+ */
+/**
+ * Configuration for KVService.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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
+ */
+export 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.
+ */
+export interface KVListResponse {
+    /**
+     * Array of keys matching the list criteria.
+     */
+    keys: string[];
+}
+/**
+ * KV service action types.
+ */
+export 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";
+};
+export type KVActionType = (typeof KVAction)[keyof typeof KVAction];
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/kv/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,yCAAyC;IACzC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IAEd;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAElC;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;OAEG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IAEd;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC;;;;OAIG;IACH,IAAI,EAAE,CAAC,CAAC;IAER;;OAEG;IACH,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;GAEG;AACH,eAAO,MAAM,QAAQ;;;;;;CAMX,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,OAAO,QAAQ,CAAC,CAAC"}

package/dist/kv/types.js

@@ -0,0 +1,16 @@
+/**
+ * KV Service Types
+ *
+ * Type definitions for the KV (Key-Value) service operations.
+ */
+/**
+ * KV service action types.
+ */
+export const KVAction = {
+    GET: "tinycloud.kv/get",
+    PUT: "tinycloud.kv/put",
+    LIST: "tinycloud.kv/list",
+    DELETE: "tinycloud.kv/del",
+    HEAD: "tinycloud.kv/metadata",
+};
+//# sourceMappingURL=types.js.map

package/dist/kv/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/kv/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA6NH;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,GAAG,EAAE,kBAAkB;IACvB,GAAG,EAAE,kBAAkB;IACvB,IAAI,EAAE,mBAAmB;IACzB,MAAM,EAAE,kBAAkB;IAC1B,IAAI,EAAE,uBAAuB;CACrB,CAAC"}