@tinycloud/sdk-services 2.8.0-beta.0 → 2.10.0-beta.0

package/dist/kv/index.d.cts

@@ -6,6 +6,7 @@ import { R as Result, I as IService } from '../types-KCcgZiab.cjs';
  *
  * Type definitions for the KV (Key-Value) service operations.
  */
+
 /**
  * Configuration for KVService.
  */
@@ -143,6 +144,18 @@ interface KVBatchPutResponse {
      */
     count: number;
 }
+/**
+ * Response from a KV batch read. Transport or authorization failures are
+ * returned by the outer Result; each requested key has its own Result so a
+ * missing key does not discard successful siblings.
+ */
+interface KVBatchReadResponse<T = unknown> {
+    results: Array<{
+        key: string;
+        result: Result<KVResponse<T>>;
+    }>;
+    count: number;
+}
 /**
  * Options for KV list operations.
  */
@@ -398,6 +411,7 @@ interface IPrefixedKVService {
      * ```
      */
     get<T = unknown>(key: string, options?: Omit<KVGetOptions, 'prefix'>): Promise<Result<KVResponse<T>>>;
+    batchGet<T = unknown>(keys: string[], options?: Omit<KVGetOptions, 'prefix'>): Promise<Result<KVBatchReadResponse<T>>>;
     /**
      * Store a value at a key.
      *
@@ -472,6 +486,7 @@ interface IPrefixedKVService {
      * ```
      */
     head(key: string, options?: Omit<KVHeadOptions, 'prefix'>): Promise<Result<KVResponse<void>>>;
+    batchHead(keys: string[], options?: Omit<KVHeadOptions, 'prefix'>): Promise<Result<KVBatchReadResponse<void>>>;
     /**
      * Create a short-lived signed URL for reading a KV object.
      *
@@ -507,11 +522,13 @@ interface IPrefixedKVService {
  */
 interface IKVServiceLike {
     get<T = unknown>(key: string, options?: KVGetOptions): Promise<Result<KVResponse<T>>>;
+    batchGet<T = unknown>(keys: string[], options?: KVGetOptions): Promise<Result<KVBatchReadResponse<T>>>;
     put(key: string, value: unknown, options?: KVPutOptions): Promise<Result<KVResponse<void>>>;
     batchPut(items: KVBatchPutItem[], options?: KVBatchPutOptions): Promise<Result<KVBatchPutResponse>>;
     list(options?: KVListOptions): Promise<Result<KVListResponse>>;
     delete(key: string, options?: KVDeleteOptions): Promise<Result<KVResponse<void>>>;
     head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
+    batchHead(keys: string[], options?: KVHeadOptions): Promise<Result<KVBatchReadResponse<void>>>;
     createSignedReadUrl(key: string, options?: KVCreateSignedReadUrlOptions): Promise<Result<KVSignedReadUrlResponse>>;
 }
 /**
@@ -577,6 +594,7 @@ declare class PrefixedKVService implements IPrefixedKVService {
      * Get a value by key.
      */
     get<T = unknown>(key: string, options?: Omit<KVGetOptions, 'prefix'>): Promise<Result<KVResponse<T>>>;
+    batchGet<T = unknown>(keys: string[], options?: Omit<KVGetOptions, 'prefix'>): Promise<Result<KVBatchReadResponse<T>>>;
     /**
      * Store a value at a key.
      */
@@ -597,6 +615,7 @@ declare class PrefixedKVService implements IPrefixedKVService {
      * Get metadata for a key without retrieving the value.
      */
     head(key: string, options?: Omit<KVHeadOptions, 'prefix'>): Promise<Result<KVResponse<void>>>;
+    batchHead(keys: string[], options?: Omit<KVHeadOptions, 'prefix'>): Promise<Result<KVBatchReadResponse<void>>>;
     /**
      * Create a short-lived signed URL for reading a KV object.
      */
@@ -651,6 +670,7 @@ interface IKVService extends IService {
      * ```
      */
     get<T = unknown>(key: string, options?: KVGetOptions): Promise<Result<KVResponse<T>>>;
+    batchGet<T = unknown>(keys: string[], options?: KVGetOptions): Promise<Result<KVBatchReadResponse<T>>>;
     /**
      * Store a value at a key.
      *
@@ -734,6 +754,7 @@ interface IKVService extends IService {
      * ```
      */
     head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
+    batchHead(keys: string[], options?: KVHeadOptions): Promise<Result<KVBatchReadResponse<void>>>;
     /**
      * Create a short-lived signed URL for reading a KV object.
      *
@@ -881,6 +902,10 @@ declare class KVService extends BaseService implements IKVService {
      * @returns KVResponseHeaders object
      */
     private createResponseHeaders;
+    private createBatchResponseHeaders;
+    private parseBatchValue;
+    private normalizeBatchReadResponse;
+    private batchRead;
     /**
      * Parse response body based on content type.
      *
@@ -895,6 +920,7 @@ declare class KVService extends BaseService implements IKVService {
      * Get a value by key.
      */
     get<T = unknown>(key: string, options?: KVGetOptions): Promise<Result<KVResponse<T>>>;
+    batchGet<T = unknown>(keys: string[], options?: KVGetOptions): Promise<Result<KVBatchReadResponse<T>>>;
     /**
      * Store a value at a key.
      */
@@ -915,6 +941,7 @@ declare class KVService extends BaseService implements IKVService {
      * Get metadata for a key without retrieving the value.
      */
     head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
+    batchHead(keys: string[], options?: KVHeadOptions): Promise<Result<KVBatchReadResponse<void>>>;
     /**
      * Create a short-lived signed URL for reading a KV object.
      */
@@ -964,4 +991,4 @@ declare class KVService extends BaseService implements IKVService {
     withPrefix(prefix: string): IPrefixedKVService;
 }
 
-export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, type IKVService, type IPrefixedKVService, KVAction, type KVActionType, type KVBatchPutItem, type KVBatchPutOptions, type KVBatchPutResponse, type KVCreateSignedReadUrlOptions, type KVDeleteOptions, type KVGetOptions, type KVHeadOptions, type KVListOptions, type KVListResponse, type KVPutOptions, type KVResponse, type KVResponseHeaders, KVService, type KVServiceConfig, type KVSignedReadUrlResponse, PrefixedKVService };
+export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, type IKVService, type IPrefixedKVService, KVAction, type KVActionType, type KVBatchPutItem, type KVBatchPutOptions, type KVBatchPutResponse, type KVBatchReadResponse, type KVCreateSignedReadUrlOptions, type KVDeleteOptions, type KVGetOptions, type KVHeadOptions, type KVListOptions, type KVListResponse, type KVPutOptions, type KVResponse, type KVResponseHeaders, KVService, type KVServiceConfig, type KVSignedReadUrlResponse, PrefixedKVService };

package/dist/kv/index.d.ts

@@ -6,6 +6,7 @@ import { R as Result, I as IService } from '../types-KCcgZiab.js';
  *
  * Type definitions for the KV (Key-Value) service operations.
  */
+
 /**
  * Configuration for KVService.
  */
@@ -143,6 +144,18 @@ interface KVBatchPutResponse {
      */
     count: number;
 }
+/**
+ * Response from a KV batch read. Transport or authorization failures are
+ * returned by the outer Result; each requested key has its own Result so a
+ * missing key does not discard successful siblings.
+ */
+interface KVBatchReadResponse<T = unknown> {
+    results: Array<{
+        key: string;
+        result: Result<KVResponse<T>>;
+    }>;
+    count: number;
+}
 /**
  * Options for KV list operations.
  */
@@ -398,6 +411,7 @@ interface IPrefixedKVService {
      * ```
      */
     get<T = unknown>(key: string, options?: Omit<KVGetOptions, 'prefix'>): Promise<Result<KVResponse<T>>>;
+    batchGet<T = unknown>(keys: string[], options?: Omit<KVGetOptions, 'prefix'>): Promise<Result<KVBatchReadResponse<T>>>;
     /**
      * Store a value at a key.
      *
@@ -472,6 +486,7 @@ interface IPrefixedKVService {
      * ```
      */
     head(key: string, options?: Omit<KVHeadOptions, 'prefix'>): Promise<Result<KVResponse<void>>>;
+    batchHead(keys: string[], options?: Omit<KVHeadOptions, 'prefix'>): Promise<Result<KVBatchReadResponse<void>>>;
     /**
      * Create a short-lived signed URL for reading a KV object.
      *
@@ -507,11 +522,13 @@ interface IPrefixedKVService {
  */
 interface IKVServiceLike {
     get<T = unknown>(key: string, options?: KVGetOptions): Promise<Result<KVResponse<T>>>;
+    batchGet<T = unknown>(keys: string[], options?: KVGetOptions): Promise<Result<KVBatchReadResponse<T>>>;
     put(key: string, value: unknown, options?: KVPutOptions): Promise<Result<KVResponse<void>>>;
     batchPut(items: KVBatchPutItem[], options?: KVBatchPutOptions): Promise<Result<KVBatchPutResponse>>;
     list(options?: KVListOptions): Promise<Result<KVListResponse>>;
     delete(key: string, options?: KVDeleteOptions): Promise<Result<KVResponse<void>>>;
     head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
+    batchHead(keys: string[], options?: KVHeadOptions): Promise<Result<KVBatchReadResponse<void>>>;
     createSignedReadUrl(key: string, options?: KVCreateSignedReadUrlOptions): Promise<Result<KVSignedReadUrlResponse>>;
 }
 /**
@@ -577,6 +594,7 @@ declare class PrefixedKVService implements IPrefixedKVService {
      * Get a value by key.
      */
     get<T = unknown>(key: string, options?: Omit<KVGetOptions, 'prefix'>): Promise<Result<KVResponse<T>>>;
+    batchGet<T = unknown>(keys: string[], options?: Omit<KVGetOptions, 'prefix'>): Promise<Result<KVBatchReadResponse<T>>>;
     /**
      * Store a value at a key.
      */
@@ -597,6 +615,7 @@ declare class PrefixedKVService implements IPrefixedKVService {
      * Get metadata for a key without retrieving the value.
      */
     head(key: string, options?: Omit<KVHeadOptions, 'prefix'>): Promise<Result<KVResponse<void>>>;
+    batchHead(keys: string[], options?: Omit<KVHeadOptions, 'prefix'>): Promise<Result<KVBatchReadResponse<void>>>;
     /**
      * Create a short-lived signed URL for reading a KV object.
      */
@@ -651,6 +670,7 @@ interface IKVService extends IService {
      * ```
      */
     get<T = unknown>(key: string, options?: KVGetOptions): Promise<Result<KVResponse<T>>>;
+    batchGet<T = unknown>(keys: string[], options?: KVGetOptions): Promise<Result<KVBatchReadResponse<T>>>;
     /**
      * Store a value at a key.
      *
@@ -734,6 +754,7 @@ interface IKVService extends IService {
      * ```
      */
     head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
+    batchHead(keys: string[], options?: KVHeadOptions): Promise<Result<KVBatchReadResponse<void>>>;
     /**
      * Create a short-lived signed URL for reading a KV object.
      *
@@ -881,6 +902,10 @@ declare class KVService extends BaseService implements IKVService {
      * @returns KVResponseHeaders object
      */
     private createResponseHeaders;
+    private createBatchResponseHeaders;
+    private parseBatchValue;
+    private normalizeBatchReadResponse;
+    private batchRead;
     /**
      * Parse response body based on content type.
      *
@@ -895,6 +920,7 @@ declare class KVService extends BaseService implements IKVService {
      * Get a value by key.
      */
     get<T = unknown>(key: string, options?: KVGetOptions): Promise<Result<KVResponse<T>>>;
+    batchGet<T = unknown>(keys: string[], options?: KVGetOptions): Promise<Result<KVBatchReadResponse<T>>>;
     /**
      * Store a value at a key.
      */
@@ -915,6 +941,7 @@ declare class KVService extends BaseService implements IKVService {
      * Get metadata for a key without retrieving the value.
      */
     head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
+    batchHead(keys: string[], options?: KVHeadOptions): Promise<Result<KVBatchReadResponse<void>>>;
     /**
      * Create a short-lived signed URL for reading a KV object.
      */
@@ -964,4 +991,4 @@ declare class KVService extends BaseService implements IKVService {
     withPrefix(prefix: string): IPrefixedKVService;
 }
 
-export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, type IKVService, type IPrefixedKVService, KVAction, type KVActionType, type KVBatchPutItem, type KVBatchPutOptions, type KVBatchPutResponse, type KVCreateSignedReadUrlOptions, type KVDeleteOptions, type KVGetOptions, type KVHeadOptions, type KVListOptions, type KVListResponse, type KVPutOptions, type KVResponse, type KVResponseHeaders, KVService, type KVServiceConfig, type KVSignedReadUrlResponse, PrefixedKVService };
+export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, type IKVService, type IPrefixedKVService, KVAction, type KVActionType, type KVBatchPutItem, type KVBatchPutOptions, type KVBatchPutResponse, type KVBatchReadResponse, type KVCreateSignedReadUrlOptions, type KVDeleteOptions, type KVGetOptions, type KVHeadOptions, type KVListOptions, type KVListResponse, type KVPutOptions, type KVResponse, type KVResponseHeaders, KVService, type KVServiceConfig, type KVSignedReadUrlResponse, PrefixedKVService };

package/dist/kv/index.js

@@ -421,6 +421,20 @@ var PrefixedKVService = class _PrefixedKVService {
     const fullKey = this.getFullKey(key);
     return this._kv.get(fullKey, { ...options, prefix: "" });
   }
+  async batchGet(keys, options) {
+    const response = await this._kv.batchGet(
+      keys.map((key) => this.getFullKey(key)),
+      { ...options, prefix: "" }
+    );
+    if (!response.ok) return response;
+    return ok({
+      ...response.data,
+      results: response.data.results.map((item, index) => ({
+        ...item,
+        key: keys[index]
+      }))
+    });
+  }
   /**
    * Store a value at a key.
    */
@@ -465,6 +479,20 @@ var PrefixedKVService = class _PrefixedKVService {
     const fullKey = this.getFullKey(key);
     return this._kv.head(fullKey, { ...options, prefix: "" });
   }
+  async batchHead(keys, options) {
+    const response = await this._kv.batchHead(
+      keys.map((key) => this.getFullKey(key)),
+      { ...options, prefix: "" }
+    );
+    if (!response.ok) return response;
+    return ok({
+      ...response.data,
+      results: response.data.results.map((item, index) => ({
+        ...item,
+        key: keys[index]
+      }))
+    });
+  }
   /**
    * Create a short-lived signed URL for reading a KV object.
    */
@@ -493,6 +521,7 @@ var KVAction = {
 };
 
 // src/kv/KVService.ts
+var MAX_KV_BATCH_READ_ITEMS = 100;
 function encodeKvBatchPartName(path) {
   return encodeURIComponent(path).replace(
     /[!'()*]/g,
@@ -727,6 +756,173 @@ var KVService = class extends BaseService {
       get: (name) => headers.get(name)
     };
   }
+  createBatchResponseHeaders(values) {
+    const normalized = new Map(
+      Object.entries(values).map(([name, value]) => [name.toLowerCase(), value])
+    );
+    return this.createResponseHeaders({
+      get: (name) => normalized.get(name.toLowerCase()) ?? null
+    });
+  }
+  parseBatchValue(dataBase64, headers, raw = false, binary = false) {
+    const encoded = globalThis.atob(dataBase64);
+    const bytes = Uint8Array.from(encoded, (character) => character.charCodeAt(0));
+    if (binary) return bytes;
+    const text = new TextDecoder().decode(bytes);
+    if (raw) return text;
+    const contentType = Object.entries(headers).find(
+      ([name]) => name.toLowerCase() === "content-type"
+    )?.[1];
+    return contentType?.includes("application/json") ? JSON.parse(text) : text;
+  }
+  normalizeBatchReadResponse(data, paths, requireData) {
+    if (!data || typeof data !== "object") return void 0;
+    const response = data;
+    if (!Array.isArray(response.results) || response.results.length !== paths.length) {
+      return void 0;
+    }
+    for (let index = 0; index < response.results.length; index++) {
+      const item = response.results[index];
+      if (!item || typeof item !== "object" || item.key !== paths[index] || typeof item.ok !== "boolean") {
+        return void 0;
+      }
+      if (item.ok && (!item.headers || typeof item.headers !== "object" || Object.values(item.headers).some((value) => typeof value !== "string") || requireData && typeof item.dataBase64 !== "string")) {
+        return void 0;
+      }
+      if (!item.ok && (!item.error || typeof item.error.code !== "string" || typeof item.error.message !== "string")) {
+        return void 0;
+      }
+    }
+    return response;
+  }
+  async batchRead(keys, action, options) {
+    if (!this.requireAuth()) return err(authRequiredError("kv"));
+    if (keys.length === 0) return ok({ results: [], count: 0 });
+    if (keys.length > MAX_KV_BATCH_READ_ITEMS) {
+      return err(serviceError(
+        ErrorCodes.INVALID_INPUT,
+        `KV batch reads accept at most ${MAX_KV_BATCH_READ_ITEMS} keys`,
+        "kv"
+      ));
+    }
+    if (keys.length === 1) {
+      const key = keys[0];
+      const result = action === KVAction.GET ? await this.get(key, options) : await this.head(key, options);
+      return ok({
+        results: [{ key, result }],
+        count: 1
+      });
+    }
+    if (!this.context.invokeAny) {
+      return err(serviceError(
+        ErrorCodes.INVALID_INPUT,
+        "KV batch reads require SDK runtime support for multi-resource invocations",
+        "kv"
+      ));
+    }
+    const getOptions = action === KVAction.GET ? options : void 0;
+    if (getOptions?.maxResponseBytes !== void 0 && (!Number.isSafeInteger(getOptions.maxResponseBytes) || getOptions.maxResponseBytes <= 0)) {
+      return err(serviceError(
+        ErrorCodes.INVALID_INPUT,
+        "KV maxResponseBytes must be a positive safe integer",
+        "kv"
+      ));
+    }
+    const paths = keys.map((key) => this.getFullPath(key, options?.prefix));
+    if (new Set(paths).size !== paths.length) {
+      return err(serviceError(
+        ErrorCodes.INVALID_INPUT,
+        "KV batch read received duplicate keys after prefix resolution",
+        "kv"
+      ));
+    }
+    try {
+      const session = this.context.session;
+      const invocationHeaders = this.context.invokeAny(
+        session,
+        paths.map((path) => ({
+          spaceId: session.spaceId,
+          service: "kv",
+          path,
+          action
+        }))
+      );
+      const limitHeaders = {};
+      if (getOptions?.maxResponseBytes !== void 0) {
+        limitHeaders["x-tinycloud-max-response-bytes"] = String(
+          getOptions.maxResponseBytes
+        );
+      }
+      const headers = Array.isArray(invocationHeaders) ? [...invocationHeaders, ...Object.entries(limitHeaders)] : { ...invocationHeaders, ...limitHeaders };
+      const response = await this.context.fetch(`${this.host}/invoke`, {
+        method: "POST",
+        headers,
+        signal: this.combineSignals(options?.signal)
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        if (response.status === 401 || response.status === 403) {
+          const { resource, action: requiredAction } = parseAuthError(errorText);
+          return err(authUnauthorizedError("kv", errorText, {
+            status: response.status,
+            ...requiredAction && { requiredAction },
+            ...resource && { resource }
+          }));
+        }
+        if (response.status === 413) {
+          return err(serviceError(
+            ErrorCodes.KV_RESPONSE_TOO_LARGE,
+            "A KV batch value exceeds the requested response limit",
+            "kv",
+            { meta: { status: response.status, statusText: response.statusText } }
+          ));
+        }
+        return err(serviceError(
+          ErrorCodes.NETWORK_ERROR,
+          `Failed to batch read ${keys.length} key(s): ${response.status} - ${errorText}`,
+          "kv",
+          { meta: { status: response.status, statusText: response.statusText } }
+        ));
+      }
+      const payload = this.normalizeBatchReadResponse(
+        await response.json(),
+        paths,
+        action === KVAction.GET
+      );
+      if (!payload) {
+        return err(serviceError(
+          ErrorCodes.NETWORK_ERROR,
+          "KV batch read response did not match the requested keys",
+          "kv"
+        ));
+      }
+      const results = payload.results.map((item, index) => {
+        if (!item.ok) {
+          return {
+            key: keys[index],
+            result: err(serviceError(item.error.code, item.error.message, "kv"))
+          };
+        }
+        const headers2 = item.headers;
+        const data = action === KVAction.HEAD ? void 0 : this.parseBatchValue(
+          item.dataBase64,
+          headers2,
+          getOptions?.raw,
+          getOptions?.binary
+        );
+        return {
+          key: keys[index],
+          result: ok({
+            data,
+            headers: this.createBatchResponseHeaders(headers2)
+          })
+        };
+      });
+      return ok({ results, count: results.length });
+    } catch (error) {
+      return err(wrapError("kv", error));
+    }
+  }
   /**
    * Parse response body based on content type.
    *
@@ -873,6 +1069,13 @@ var KVService = class extends BaseService {
       }
     });
   }
+  async batchGet(keys, options) {
+    return this.withTelemetry(
+      "batchGet",
+      String(keys.length),
+      () => this.batchRead(keys, KVAction.GET, options)
+    );
+  }
   /**
    * Store a value at a key.
    */
@@ -1232,6 +1435,13 @@ var KVService = class extends BaseService {
       }
     });
   }
+  async batchHead(keys, options) {
+    return this.withTelemetry(
+      "batchHead",
+      String(keys.length),
+      () => this.batchRead(keys, KVAction.HEAD, options)
+    );
+  }
   /**
    * Create a short-lived signed URL for reading a KV object.
    */