@tinycloud/sdk-services 2.8.0 → 2.10.0

package/dist/index.cjs

@@ -514,7 +514,9 @@ function createKVResponseSchema(dataSchema) {
 var GenericKVResponseSchema = createKVResponseSchema(import_zod.z.unknown());
 var KVListResponseSchema = import_zod.z.object({
   /** Array of keys matching the list criteria */
-  keys: import_zod.z.array(import_zod.z.string())
+  keys: import_zod.z.array(import_zod.z.string()),
+  truncated: import_zod.z.boolean().optional(),
+  nextCursor: import_zod.z.string().optional()
 });
 var KVListResultSchema = createResultSchema(KVListResponseSchema);
 var ServiceRequestEventSchema = import_zod.z.object({
@@ -1418,6 +1420,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.
    */
@@ -1462,6 +1478,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.
    */
@@ -1490,6 +1520,7 @@ var KVAction = {
 };
 
 // src/kv/KVService.ts
+var MAX_KV_BATCH_READ_ITEMS = 100;
 function encodeKvBatchPartName(path) {
   return encodeURIComponent(path).replace(
     /[!'()*]/g,
@@ -1724,6 +1755,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.
    *
@@ -1870,6 +2068,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.
    */
@@ -2077,7 +2282,10 @@ var KVService = class extends BaseService {
           KVAction.LIST,
           void 0,
           options?.signal,
-          options?.limit === void 0 ? void 0 : { "x-tinycloud-limit": String(options.limit) }
+          options?.limit === void 0 && options?.cursor === void 0 ? void 0 : {
+            ...options?.limit === void 0 ? {} : { "x-tinycloud-limit": String(options.limit) },
+            ...options?.cursor === void 0 ? {} : { "x-tinycloud-cursor": options.cursor }
+          }
         );
         if (!response.ok) {
           if (response.status === 401) {
@@ -2109,7 +2317,8 @@ var KVService = class extends BaseService {
         }
         return ok({
           keys,
-          ...response.headers.get("x-tinycloud-truncated") === null ? {} : { truncated: response.headers.get("x-tinycloud-truncated") === "true" }
+          ...response.headers.get("x-tinycloud-truncated") === null ? {} : { truncated: response.headers.get("x-tinycloud-truncated") === "true" },
+          ...response.headers.get("x-tinycloud-next-cursor") === null ? {} : { nextCursor: response.headers.get("x-tinycloud-next-cursor") ?? void 0 }
         });
       } catch (error) {
         return err(wrapError("kv", error));
@@ -2229,6 +2438,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.
    */
@@ -4827,6 +5043,10 @@ var DataVaultService = class extends BaseService {
    * @returns Result with array of key names (vault/ prefix stripped)
    */
   async list(options) {
+    const page = await this.listPage(options);
+    return page.ok ? { ok: true, data: page.data.keys } : page;
+  }
+  async listPage(options) {
     return this.withTelemetry("list", options?.prefix, async () => {
       if (!this.isUnlocked) {
         return vaultError({
@@ -4844,7 +5064,9 @@ var DataVaultService = class extends BaseService {
         const listPrefix = options?.prefix ? `vault/${options.prefix}` : "vault/";
         const listResult = await this.tc.kv.list({
           prefix: listPrefix,
-          removePrefix: true
+          removePrefix: true,
+          ...options?.limit === void 0 ? {} : { limit: options.limit },
+          ...options?.cursor === void 0 ? {} : { cursor: options.cursor }
         });
         if (!listResult.ok) {
           return vaultError({
@@ -4861,7 +5083,11 @@ var DataVaultService = class extends BaseService {
             (k) => k.startsWith(userPrefix) ? k.slice(userPrefix.length) : k
           );
         }
-        return ok(keys);
+        return ok({
+          keys,
+          truncated: listResult.data.truncated === true,
+          ...listResult.data.nextCursor === void 0 ? {} : { nextCursor: listResult.data.nextCursor }
+        });
       } catch (error) {
         return vaultError({
           code: "STORAGE_ERROR",