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

package/dist/kv/index.js

@@ -1,12 +1,880 @@
+// src/types.ts
+var ErrorCodes = {
+  // Common errors
+  NOT_FOUND: "NOT_FOUND",
+  AUTH_EXPIRED: "AUTH_EXPIRED",
+  AUTH_REQUIRED: "AUTH_REQUIRED",
+  AUTH_UNAUTHORIZED: "AUTH_UNAUTHORIZED",
+  NETWORK_ERROR: "NETWORK_ERROR",
+  TIMEOUT: "TIMEOUT",
+  ABORTED: "ABORTED",
+  INVALID_INPUT: "INVALID_INPUT",
+  PERMISSION_DENIED: "PERMISSION_DENIED",
+  // KV-specific errors
+  KV_NOT_FOUND: "KV_NOT_FOUND",
+  KV_WRITE_FAILED: "KV_WRITE_FAILED",
+  // SQL-specific errors
+  SQL_ERROR: "SQL_ERROR",
+  SQL_PERMISSION_DENIED: "SQL_PERMISSION_DENIED",
+  SQL_DATABASE_NOT_FOUND: "SQL_DATABASE_NOT_FOUND",
+  SQL_RESPONSE_TOO_LARGE: "SQL_RESPONSE_TOO_LARGE",
+  SQL_QUOTA_EXCEEDED: "SQL_QUOTA_EXCEEDED",
+  SQL_INVALID_STATEMENT: "SQL_INVALID_STATEMENT",
+  SQL_SCHEMA_ERROR: "SQL_SCHEMA_ERROR",
+  SQL_READONLY_VIOLATION: "SQL_READONLY_VIOLATION",
+  // Storage quota errors
+  STORAGE_QUOTA_EXCEEDED: "STORAGE_QUOTA_EXCEEDED",
+  STORAGE_LIMIT_REACHED: "STORAGE_LIMIT_REACHED",
+  // DuckDB-specific errors
+  DUCKDB_ERROR: "DUCKDB_ERROR",
+  DUCKDB_PERMISSION_DENIED: "DUCKDB_PERMISSION_DENIED",
+  DUCKDB_DATABASE_NOT_FOUND: "DUCKDB_DATABASE_NOT_FOUND",
+  DUCKDB_RESPONSE_TOO_LARGE: "DUCKDB_RESPONSE_TOO_LARGE",
+  DUCKDB_QUOTA_EXCEEDED: "DUCKDB_QUOTA_EXCEEDED",
+  DUCKDB_INVALID_STATEMENT: "DUCKDB_INVALID_STATEMENT",
+  DUCKDB_SCHEMA_ERROR: "DUCKDB_SCHEMA_ERROR",
+  DUCKDB_READONLY_VIOLATION: "DUCKDB_READONLY_VIOLATION"
+};
+var defaultRetryPolicy = {
+  maxAttempts: 3,
+  backoff: "exponential",
+  baseDelayMs: 1e3,
+  maxDelayMs: 1e4,
+  retryableErrors: [ErrorCodes.NETWORK_ERROR, ErrorCodes.TIMEOUT]
+};
+var TelemetryEvents = {
+  SERVICE_REQUEST: "service.request",
+  SERVICE_RESPONSE: "service.response",
+  SERVICE_ERROR: "service.error",
+  SERVICE_RETRY: "service.retry",
+  SESSION_CHANGED: "session.changed",
+  SESSION_EXPIRED: "session.expired"
+};
+function ok(data) {
+  return { ok: true, data };
+}
+function err(error) {
+  return { ok: false, error };
+}
+function serviceError(code, message, service, options) {
+  return {
+    code,
+    message,
+    service,
+    cause: options?.cause,
+    meta: options?.meta
+  };
+}
+
+// src/errors.ts
+function authRequiredError(service) {
+  return {
+    code: ErrorCodes.AUTH_REQUIRED,
+    message: "Authentication required. Please sign in first.",
+    service
+  };
+}
+function timeoutError(service) {
+  return {
+    code: ErrorCodes.TIMEOUT,
+    message: "Request timed out.",
+    service
+  };
+}
+function abortedError(service) {
+  return {
+    code: ErrorCodes.ABORTED,
+    message: "Request was aborted.",
+    service
+  };
+}
+function parseAuthError(responseText) {
+  const match = responseText.match(/^Unauthorized Action:\s*(.+?)\s*\/\s*(tinycloud\.\S+)$/m);
+  if (match) {
+    return { resource: match[1].trim(), action: match[2].trim() };
+  }
+  return {};
+}
+function authUnauthorizedError(service, message, meta) {
+  return serviceError(ErrorCodes.AUTH_UNAUTHORIZED, message, service, { meta });
+}
+function storageQuotaExceededError(service, message, meta) {
+  return {
+    code: ErrorCodes.STORAGE_QUOTA_EXCEEDED,
+    message,
+    service,
+    meta
+  };
+}
+function storageLimitReachedError(service, message, meta) {
+  return {
+    code: ErrorCodes.STORAGE_LIMIT_REACHED,
+    message,
+    service,
+    meta
+  };
+}
+function wrapError(service, error, defaultCode = ErrorCodes.NETWORK_ERROR) {
+  if (error instanceof Error) {
+    if (error.name === "AbortError") {
+      return abortedError(service);
+    }
+    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
+  };
+}
+
+// src/base/BaseService.ts
+var BaseService = class {
+  constructor() {
+    /**
+     * Abort controller for this service's operations.
+     * Reset on sign-out.
+     */
+    this.abortController = new AbortController();
+    /**
+     * Service-specific configuration.
+     */
+    this._config = {};
+  }
+  /**
+   * Get the service configuration.
+   */
+  get config() {
+    return this._config;
+  }
+  /**
+   * Initialize the service with context.
+   * Called by the SDK after instantiation.
+   *
+   * @param context - The service context
+   */
+  initialize(context) {
+    this.context = context;
+  }
+  /**
+   * Called when session changes (sign-in, sign-out, refresh).
+   * Override in subclasses to handle session changes.
+   *
+   * @param session - The new session, or null if signed out
+   */
+  onSessionChange(session) {
+  }
+  /**
+   * Called when SDK signs out.
+   * Aborts all pending operations.
+   */
+  onSignOut() {
+    this.abortController.abort();
+    this.abortController = new AbortController();
+  }
+  /**
+   * Get the abort signal for this service.
+   * Combines the service-level abort with context-level abort.
+   */
+  get abortSignal() {
+    return this.abortController.signal;
+  }
+  /**
+   * Check if the service is authenticated.
+   */
+  get isAuthenticated() {
+    return this.context?.isAuthenticated ?? false;
+  }
+  /**
+   * Get the current session.
+   * Throws if not authenticated.
+   */
+  get session() {
+    if (!this.context?.session) {
+      throw new Error("Not authenticated");
+    }
+    return this.context.session;
+  }
+  /**
+   * Check authentication and return error result if not authenticated.
+   * Use this at the start of methods that require authentication.
+   *
+   * @returns true if authenticated, false otherwise
+   */
+  requireAuth() {
+    return this.isAuthenticated;
+  }
+  /**
+   * Emit a telemetry event.
+   *
+   * @param event - Event name
+   * @param data - Event data
+   */
+  emit(event, data) {
+    this.context?.emit(event, data);
+  }
+  /**
+   * Emit a service request event.
+   *
+   * @param action - The action being performed
+   * @param key - Optional key/path being accessed
+   */
+  emitRequest(action, key) {
+    this.emit(TelemetryEvents.SERVICE_REQUEST, {
+      service: this.getServiceName(),
+      action,
+      key,
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Emit a service response event.
+   *
+   * @param action - The action that was performed
+   * @param ok - Whether the request was successful
+   * @param startTime - Start time for duration calculation
+   * @param status - Optional HTTP status code
+   */
+  emitResponse(action, ok2, startTime, status) {
+    this.emit(TelemetryEvents.SERVICE_RESPONSE, {
+      service: this.getServiceName(),
+      action,
+      ok: ok2,
+      duration: Date.now() - startTime,
+      status
+    });
+  }
+  /**
+   * Emit a service error event.
+   *
+   * @param error - The service error
+   */
+  emitError(error) {
+    this.emit(TelemetryEvents.SERVICE_ERROR, {
+      service: this.getServiceName(),
+      error
+    });
+  }
+  /**
+   * Get the service name from the static property.
+   * Subclasses must define static serviceName.
+   */
+  getServiceName() {
+    return this.constructor.serviceName;
+  }
+  /**
+   * Create a combined abort signal from multiple sources.
+   *
+   * @param signals - Additional abort signals to combine
+   * @returns A combined abort signal
+   */
+  combineSignals(...signals) {
+    const controller = new AbortController();
+    const allSignals = [this.abortSignal, ...signals.filter(Boolean)];
+    for (const signal of allSignals) {
+      if (signal.aborted) {
+        controller.abort(signal.reason);
+        return controller.signal;
+      }
+      signal.addEventListener("abort", () => controller.abort(signal.reason), {
+        once: true
+      });
+    }
+    return controller.signal;
+  }
+  /**
+   * Wrap an operation with error handling and telemetry.
+   *
+   * @param action - The action name for telemetry
+   * @param key - Optional key for telemetry
+   * @param operation - The operation to execute
+   * @returns Result of the operation
+   */
+  async withTelemetry(action, key, operation) {
+    const startTime = Date.now();
+    this.emitRequest(action, key);
+    try {
+      const result = await operation();
+      if (result.ok) {
+        this.emitResponse(action, true, startTime);
+      } else {
+        this.emitResponse(action, false, startTime);
+        this.emitError(result.error);
+      }
+      return result;
+    } catch (error) {
+      const serviceError2 = wrapError(this.getServiceName(), error);
+      this.emitResponse(action, false, startTime);
+      this.emitError(serviceError2);
+      return err(serviceError2);
+    }
+  }
+};
+
+// src/kv/PrefixedKVService.ts
+var PrefixedKVService = 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;
+    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) {
+    const normalizedKey = key.startsWith("/") ? key : `/${key}`;
+    return `${this._prefix}${normalizedKey}`;
+  }
+  /**
+   * Get a value by key.
+   */
+  async get(key, options) {
+    const fullKey = this.getFullKey(key);
+    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) {
+    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) {
+    const normalizedSubPrefix = subPrefix.startsWith("/") ? subPrefix : `/${subPrefix}`;
+    const combinedPrefix = `${this._prefix}${normalizedSubPrefix}`;
+    return new _PrefixedKVService(this._kv, combinedPrefix);
+  }
+};
+
+// src/kv/types.ts
+var KVAction = {
+  GET: "tinycloud.kv/get",
+  PUT: "tinycloud.kv/put",
+  LIST: "tinycloud.kv/list",
+  DELETE: "tinycloud.kv/del",
+  HEAD: "tinycloud.kv/metadata"
+};
+
+// src/kv/KVService.ts
+var KVService = class extends BaseService {
+  /**
+   * Create a new KVService instance.
+   *
+   * @param config - Service configuration
+   */
+  constructor(config = {}) {
+    super();
+    this._config = config;
+  }
+  /**
+   * Get the service configuration.
+   */
+  get config() {
+    return this._config;
+  }
+  // Parses "Used: X bytes, Limit: Y bytes" from tinycloud-node error responses
+  parseQuotaInfo(errorText) {
+    const match = errorText.match(
+      /Used:\s*(\d+)\s*bytes,\s*Limit:\s*(\d+)\s*bytes/i
+    );
+    if (match) {
+      return {
+        usedBytes: parseInt(match[1], 10),
+        limitBytes: parseInt(match[2], 10)
+      };
+    }
+    return void 0;
+  }
+  handleQuotaErrorResponse(response, errorText, key) {
+    if (response.status === 402) {
+      const quotaInfo = this.parseQuotaInfo(errorText);
+      return err(
+        storageQuotaExceededError(
+          "kv",
+          `Storage quota exceeded for key "${key}": ${errorText}`,
+          {
+            status: response.status,
+            ...quotaInfo ? { usedBytes: quotaInfo.usedBytes, limitBytes: quotaInfo.limitBytes } : {}
+          }
+        )
+      );
+    }
+    if (response.status === 413) {
+      const quotaInfo = this.parseQuotaInfo(errorText);
+      return err(
+        storageLimitReachedError(
+          "kv",
+          `Storage limit reached for key "${key}": ${errorText}`,
+          {
+            status: response.status,
+            ...quotaInfo ? { usedBytes: quotaInfo.usedBytes, limitBytes: quotaInfo.limitBytes } : {}
+          }
+        )
+      );
+    }
+    return void 0;
+  }
+  /**
+   * Get the full path with optional prefix.
+   *
+   * @param key - The key
+   * @param prefixOverride - Optional prefix override
+   * @returns The full path
+   */
+  getFullPath(key, prefixOverride) {
+    const prefix = prefixOverride ?? this._config.prefix ?? "";
+    return prefix ? `${prefix}/${key}` : key;
+  }
+  /**
+   * Get the host URL.
+   */
+  get host() {
+    return this.context.hosts[0];
+  }
+  /**
+   * 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
+   */
+  async invokeOperation(path, action, body, signal) {
+    const session = this.context.session;
+    const headers = this.context.invoke(
+      session,
+      "kv",
+      path,
+      action
+    );
+    return this.context.fetch(`${this.host}/invoke`, {
+      method: "POST",
+      headers,
+      body,
+      signal: this.combineSignals(signal)
+    });
+  }
+  /**
+   * Create KVResponseHeaders from fetch response headers.
+   *
+   * @param headers - Fetch response headers
+   * @returns KVResponseHeaders object
+   */
+  createResponseHeaders(headers) {
+    return {
+      etag: headers.get("etag") ?? void 0,
+      contentType: headers.get("content-type") ?? void 0,
+      lastModified: headers.get("last-modified") ?? void 0,
+      contentLength: headers.get("content-length") ? parseInt(headers.get("content-length"), 10) : void 0,
+      get: (name) => headers.get(name)
+    };
+  }
+  /**
+   * Parse response body based on content type.
+   *
+   * @param response - Fetch response
+   * @param raw - Whether to return raw text
+   * @returns Parsed data
+   */
+  async parseResponse(response, raw = false) {
+    if (!response.ok) {
+      return void 0;
+    }
+    if (raw) {
+      return await response.text();
+    }
+    const contentType = response.headers.get("content-type");
+    if (contentType?.includes("application/json")) {
+      return await response.json();
+    } else if (contentType?.startsWith("text/")) {
+      return await response.text();
+    }
+    const text = await response.text();
+    if (!text) {
+      return void 0;
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  /**
+   * Get a value by key.
+   */
+  async get(key, options) {
+    return this.withTelemetry("get", key, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("kv"));
+      }
+      const path = this.getFullPath(key, options?.prefix);
+      try {
+        const response = await this.invokeOperation(
+          path,
+          KVAction.GET,
+          void 0,
+          options?.signal
+        );
+        if (!response.ok) {
+          if (response.status === 401) {
+            const errorText2 = await response.text();
+            const { resource, action } = parseAuthError(errorText2);
+            return err(authUnauthorizedError("kv", errorText2, {
+              status: response.status,
+              ...action && { requiredAction: action },
+              ...resource && { resource }
+            }));
+          }
+          if (response.status === 404) {
+            return err(
+              serviceError(
+                ErrorCodes.KV_NOT_FOUND,
+                `Key not found: ${key}`,
+                "kv"
+              )
+            );
+          }
+          const errorText = await response.text();
+          return err(
+            serviceError(
+              ErrorCodes.NETWORK_ERROR,
+              `Failed to get key "${key}": ${response.status} - ${errorText}`,
+              "kv",
+              { meta: { status: response.status, statusText: response.statusText } }
+            )
+          );
+        }
+        const data = await this.parseResponse(response, options?.raw);
+        return ok({
+          data,
+          headers: this.createResponseHeaders(response.headers)
+        });
+      } catch (error) {
+        return err(wrapError("kv", error));
+      }
+    });
+  }
+  /**
+   * Store a value at a key.
+   */
+  async put(key, value, options) {
+    return this.withTelemetry("put", key, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("kv"));
+      }
+      const path = this.getFullPath(key, options?.prefix);
+      let body;
+      if (typeof value === "string") {
+        body = value;
+      } else {
+        body = JSON.stringify(value);
+      }
+      try {
+        const response = await this.invokeOperation(
+          path,
+          KVAction.PUT,
+          body,
+          options?.signal
+        );
+        if (!response.ok) {
+          if (response.status === 401) {
+            const errorText2 = await response.text();
+            const { resource, action } = parseAuthError(errorText2);
+            return err(authUnauthorizedError("kv", errorText2, {
+              status: response.status,
+              ...action && { requiredAction: action },
+              ...resource && { resource }
+            }));
+          }
+          const errorText = await response.text();
+          const quotaError = this.handleQuotaErrorResponse(
+            response,
+            errorText,
+            key
+          );
+          if (quotaError) {
+            return quotaError;
+          }
+          return err(
+            serviceError(
+              ErrorCodes.KV_WRITE_FAILED,
+              `Failed to put key "${key}": ${response.status} - ${errorText}`,
+              "kv",
+              { meta: { status: response.status, statusText: response.statusText } }
+            )
+          );
+        }
+        return ok({
+          data: void 0,
+          headers: this.createResponseHeaders(response.headers)
+        });
+      } catch (error) {
+        return err(wrapError("kv", error));
+      }
+    });
+  }
+  /**
+   * List keys with optional prefix filtering.
+   */
+  async list(options) {
+    return this.withTelemetry("list", options?.prefix, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("kv"));
+      }
+      let listPath = options?.prefix ?? this._config.prefix ?? "";
+      if (options?.path) {
+        listPath = listPath ? `${listPath}/${options.path}` : options.path;
+      }
+      try {
+        const response = await this.invokeOperation(
+          listPath,
+          KVAction.LIST,
+          void 0,
+          options?.signal
+        );
+        if (!response.ok) {
+          if (response.status === 401) {
+            const errorText2 = await response.text();
+            const { resource, action } = parseAuthError(errorText2);
+            return err(authUnauthorizedError("kv", errorText2, {
+              status: response.status,
+              ...action && { requiredAction: action },
+              ...resource && { resource }
+            }));
+          }
+          const errorText = await response.text();
+          return err(
+            serviceError(
+              ErrorCodes.NETWORK_ERROR,
+              `Failed to list keys: ${response.status} - ${errorText}`,
+              "kv",
+              { meta: { status: response.status, statusText: response.statusText } }
+            )
+          );
+        }
+        let keys = await this.parseResponse(response, options?.raw);
+        keys = keys ?? [];
+        if (options?.removePrefix && listPath) {
+          const prefixWithSlash = listPath.endsWith("/") ? listPath : `${listPath}/`;
+          keys = keys.map(
+            (key) => key.startsWith(prefixWithSlash) ? key.slice(prefixWithSlash.length) : key
+          );
+        }
+        return ok({ keys });
+      } catch (error) {
+        return err(wrapError("kv", error));
+      }
+    });
+  }
+  /**
+   * Delete a key.
+   */
+  async delete(key, options) {
+    return this.withTelemetry("delete", key, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("kv"));
+      }
+      const path = this.getFullPath(key, options?.prefix);
+      try {
+        const response = await this.invokeOperation(
+          path,
+          KVAction.DELETE,
+          void 0,
+          options?.signal
+        );
+        if (!response.ok) {
+          if (response.status === 401) {
+            const errorText2 = await response.text();
+            const { resource, action } = parseAuthError(errorText2);
+            return err(authUnauthorizedError("kv", errorText2, {
+              status: response.status,
+              ...action && { requiredAction: action },
+              ...resource && { resource }
+            }));
+          }
+          if (response.status === 404) {
+            return err(
+              serviceError(
+                ErrorCodes.KV_NOT_FOUND,
+                `Key not found: ${key}`,
+                "kv"
+              )
+            );
+          }
+          const errorText = await response.text();
+          return err(
+            serviceError(
+              ErrorCodes.NETWORK_ERROR,
+              `Failed to delete key "${key}": ${response.status} - ${errorText}`,
+              "kv",
+              { meta: { status: response.status, statusText: response.statusText } }
+            )
+          );
+        }
+        return ok(void 0);
+      } catch (error) {
+        return err(wrapError("kv", error));
+      }
+    });
+  }
+  /**
+   * Get metadata for a key without retrieving the value.
+   */
+  async head(key, options) {
+    return this.withTelemetry("head", key, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("kv"));
+      }
+      const path = this.getFullPath(key, options?.prefix);
+      try {
+        const response = await this.invokeOperation(
+          path,
+          KVAction.HEAD,
+          void 0,
+          options?.signal
+        );
+        if (!response.ok) {
+          if (response.status === 401) {
+            const errorText2 = await response.text();
+            const { resource, action } = parseAuthError(errorText2);
+            return err(authUnauthorizedError("kv", errorText2, {
+              status: response.status,
+              ...action && { requiredAction: action },
+              ...resource && { resource }
+            }));
+          }
+          if (response.status === 404) {
+            return err(
+              serviceError(
+                ErrorCodes.KV_NOT_FOUND,
+                `Key not found: ${key}`,
+                "kv"
+              )
+            );
+          }
+          const errorText = await response.text();
+          return err(
+            serviceError(
+              ErrorCodes.NETWORK_ERROR,
+              `Failed to get metadata for key "${key}": ${response.status} - ${errorText}`,
+              "kv",
+              { meta: { status: response.status, statusText: response.statusText } }
+            )
+          );
+        }
+        return ok({
+          data: void 0,
+          headers: this.createResponseHeaders(response.headers)
+        });
+      } catch (error) {
+        return err(wrapError("kv", error));
+      }
+    });
+  }
+  /**
+   * 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) {
+    return new PrefixedKVService(this, prefix);
+  }
+};
 /**
- * KV Service Exports
- *
- * Key-Value storage service for TinyCloud SDK.
+ * Service identifier for registration.
  */
-// Service implementation
-export { KVService } from "./KVService";
-// Prefixed service implementation
-export { PrefixedKVService } from "./PrefixedKVService";
-// Types
-export { KVAction, } from "./types";
+KVService.serviceName = "kv";
+export {
+  KVAction,
+  KVService,
+  PrefixedKVService
+};
 //# sourceMappingURL=index.js.map