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

package/dist/index.d.cts

@@ -3,7 +3,7 @@ export { g as ErrorCode, h as ErrorCodes, i as FetchRequestInit, j as FetchRespo
 import { z } from 'zod';
 import { B as BaseService } from './BaseService-DxSU4U-v.cjs';
 import { IKVService } from './kv/index.cjs';
-export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, IPrefixedKVService, KVAction, KVActionType, KVBatchPutItem, KVBatchPutOptions, KVBatchPutResponse, KVCreateSignedReadUrlOptions, KVDeleteOptions, KVGetOptions, KVHeadOptions, KVListOptions, KVListResponse, KVPutOptions, KVResponse, KVResponseHeaders, KVService, KVServiceConfig, KVSignedReadUrlResponse, PrefixedKVService } from './kv/index.cjs';
+export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, IPrefixedKVService, KVAction, KVActionType, KVBatchPutItem, KVBatchPutOptions, KVBatchPutResponse, KVBatchReadResponse, KVCreateSignedReadUrlOptions, KVDeleteOptions, KVGetOptions, KVHeadOptions, KVListOptions, KVListResponse, KVPutOptions, KVResponse, KVResponseHeaders, KVService, KVServiceConfig, KVSignedReadUrlResponse, PrefixedKVService } from './kv/index.cjs';
 export { BatchOptions, BatchResponse, DatabaseHandle, ExecuteOptions, ExecuteResponse, IDatabaseHandle, ISQLMigrations, ISQLService, QueryOptions, QueryResponse, SQLAction, SQLActionType, SQLMigrations, SQLService, SQLServiceConfig, SqlMigration, SqlMigrationApplyOptions, SqlMigrationApplyResponse, SqlStatement, SqlValue } from './sql/index.cjs';
 import { IEncryptionService, DecryptCapabilityProof } from './encryption/index.cjs';
 export { BuildCanonicalDecryptRequestInput, BuildDecryptFactsInput, BuildDecryptInvocationInput, BuiltDecryptInvocation, CanonicalDecryptRequest, CanonicalJson, DECRYPT_ACTION, DECRYPT_FACT_TYPE, DECRYPT_RESULT_TYPE, DEFAULT_ENCRYPTION_ALG, DEFAULT_KEY_VERSION, DecryptEnvelopeOptions, DecryptInvocationFact, DecryptInvocationSigner, DecryptRequestBody, DecryptResponseBody, DecryptTransport, DiscoverNetworkInput, DiscoveredNetwork, DiscoverySource, ENCRYPTION_NETWORK_URN_PREFIX, ENCRYPTION_SERVICE, ENCRYPTION_SERVICE_SHORT, ENVELOPE_VERSION, EncryptToNetworkInput, EncryptToNetworkOptions, EncryptToNetworkResult, EncryptionCrypto, EncryptionError, EncryptionErrorInput, EncryptionService, EncryptionServiceConfig, InlineEncryptedEnvelope, Json, NETWORK_NAME_PATTERN, NetworkDescriptor, NetworkIdError, NodeDescriptorFetcher, ParsedNetworkId, RandomReceiverKeyInput, ReceiverKeyPair, ReceiverKeySigner, SignedReceiverKeyInput, VerifyDecryptResponseInput, WellKnownDescriptorFetcher, base64Decode, base64Encode, buildCanonicalDecryptRequest, buildDecryptAttenuation, buildDecryptFacts, buildDecryptInvocation, buildNetworkId, canonicalHashHex, canonicalSignedResponse, canonicalize as canonicalizeEncryptionJson, checkDecryptInvocationInput, decryptEnvelopeWithKey, deriveSignedReceiverKey, discoverNetwork, encryptToNetwork, encryptionError, ensureNetworkUsableForDecrypt, generateRandomReceiverKey, hexDecode, hexEncode, isNetworkId, networkDiscoveryKey, openWrappedKey, parseNetworkId, utf8Decode, utf8Encode, validateEnvelope, verifyDecryptResponse } from './encryption/index.cjs';

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { g as ErrorCode, h as ErrorCodes, i as FetchRequestInit, j as FetchRespo
 import { z } from 'zod';
 import { B as BaseService } from './BaseService-BiYeqCRT.js';
 import { IKVService } from './kv/index.js';
-export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, IPrefixedKVService, KVAction, KVActionType, KVBatchPutItem, KVBatchPutOptions, KVBatchPutResponse, KVCreateSignedReadUrlOptions, KVDeleteOptions, KVGetOptions, KVHeadOptions, KVListOptions, KVListResponse, KVPutOptions, KVResponse, KVResponseHeaders, KVService, KVServiceConfig, KVSignedReadUrlResponse, PrefixedKVService } from './kv/index.js';
+export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, IPrefixedKVService, KVAction, KVActionType, KVBatchPutItem, KVBatchPutOptions, KVBatchPutResponse, KVBatchReadResponse, KVCreateSignedReadUrlOptions, KVDeleteOptions, KVGetOptions, KVHeadOptions, KVListOptions, KVListResponse, KVPutOptions, KVResponse, KVResponseHeaders, KVService, KVServiceConfig, KVSignedReadUrlResponse, PrefixedKVService } from './kv/index.js';
 export { BatchOptions, BatchResponse, DatabaseHandle, ExecuteOptions, ExecuteResponse, IDatabaseHandle, ISQLMigrations, ISQLService, QueryOptions, QueryResponse, SQLAction, SQLActionType, SQLMigrations, SQLService, SQLServiceConfig, SqlMigration, SqlMigrationApplyOptions, SqlMigrationApplyResponse, SqlStatement, SqlValue } from './sql/index.js';
 import { IEncryptionService, DecryptCapabilityProof } from './encryption/index.js';
 export { BuildCanonicalDecryptRequestInput, BuildDecryptFactsInput, BuildDecryptInvocationInput, BuiltDecryptInvocation, CanonicalDecryptRequest, CanonicalJson, DECRYPT_ACTION, DECRYPT_FACT_TYPE, DECRYPT_RESULT_TYPE, DEFAULT_ENCRYPTION_ALG, DEFAULT_KEY_VERSION, DecryptEnvelopeOptions, DecryptInvocationFact, DecryptInvocationSigner, DecryptRequestBody, DecryptResponseBody, DecryptTransport, DiscoverNetworkInput, DiscoveredNetwork, DiscoverySource, ENCRYPTION_NETWORK_URN_PREFIX, ENCRYPTION_SERVICE, ENCRYPTION_SERVICE_SHORT, ENVELOPE_VERSION, EncryptToNetworkInput, EncryptToNetworkOptions, EncryptToNetworkResult, EncryptionCrypto, EncryptionError, EncryptionErrorInput, EncryptionService, EncryptionServiceConfig, InlineEncryptedEnvelope, Json, NETWORK_NAME_PATTERN, NetworkDescriptor, NetworkIdError, NodeDescriptorFetcher, ParsedNetworkId, RandomReceiverKeyInput, ReceiverKeyPair, ReceiverKeySigner, SignedReceiverKeyInput, VerifyDecryptResponseInput, WellKnownDescriptorFetcher, base64Decode, base64Encode, buildCanonicalDecryptRequest, buildDecryptAttenuation, buildDecryptFacts, buildDecryptInvocation, buildNetworkId, canonicalHashHex, canonicalSignedResponse, canonicalize as canonicalizeEncryptionJson, checkDecryptInvocationInput, decryptEnvelopeWithKey, deriveSignedReceiverKey, discoverNetwork, encryptToNetwork, encryptionError, ensureNetworkUsableForDecrypt, generateRandomReceiverKey, hexDecode, hexEncode, isNetworkId, networkDiscoveryKey, openWrappedKey, parseNetworkId, utf8Decode, utf8Encode, validateEnvelope, verifyDecryptResponse } from './encryption/index.js';

package/dist/index.js

@@ -1277,6 +1277,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.
    */
@@ -1321,6 +1335,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.
    */
@@ -1349,6 +1377,7 @@ var KVAction = {
 };
 
 // src/kv/KVService.ts
+var MAX_KV_BATCH_READ_ITEMS = 100;
 function encodeKvBatchPartName(path) {
   return encodeURIComponent(path).replace(
     /[!'()*]/g,
@@ -1583,6 +1612,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.
    *
@@ -1729,6 +1925,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.
    */
@@ -2088,6 +2291,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.
    */