@tinycloud/sdk-services 2.3.0-beta.5 → 2.3.0-beta.7

package/dist/kv/index.d.cts

@@ -1,4 +1,4 @@
-import { e as Result, c as IService, B as BaseService } from '../BaseService-C_iXlTeN.cjs';
+import { e as Result, c as IService, B as BaseService } from '../BaseService-DZ2hBJeD.cjs';
 
 /**
  * KV Service Types
@@ -76,6 +76,57 @@ interface KVPutOptions {
      */
     signal?: AbortSignal;
 }
+/**
+ * One entry in a KV batch put request.
+ */
+interface KVBatchPutItem {
+    /**
+     * The key to store under.
+     */
+    key: string;
+    /**
+     * The value to store.
+     *
+     * Objects are JSON stringified. Strings are stored as text. Binary values
+     * should be supplied as Blob, ArrayBuffer, or Uint8Array.
+     */
+    value: unknown;
+    /**
+     * Content type for this item. Defaults to application/json for objects and
+     * application/octet-stream for binary values.
+     */
+    contentType?: string;
+}
+/**
+ * Options for KV batch put operations.
+ */
+interface KVBatchPutOptions {
+    /**
+     * Override the default prefix for all entries in this batch.
+     */
+    prefix?: string;
+    /**
+     * Custom timeout for this operation in milliseconds.
+     */
+    timeout?: number;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Response from KV batch put operations.
+ */
+interface KVBatchPutResponse {
+    /**
+     * Keys successfully written by the batch.
+     */
+    written: string[];
+    /**
+     * Number of written keys.
+     */
+    count: number;
+}
 /**
  * Options for KV list operations.
  */
@@ -343,6 +394,10 @@ interface IPrefixedKVService {
      * ```
      */
     put(key: string, value: unknown, options?: Omit<KVPutOptions, 'prefix'>): Promise<Result<KVResponse<void>>>;
+    /**
+     * Store multiple values within this prefix in one TinyCloud KV invocation.
+     */
+    batchPut(items: KVBatchPutItem[], options?: Omit<KVBatchPutOptions, 'prefix'>): Promise<Result<KVBatchPutResponse>>;
     /**
      * List keys within this prefix.
      *
@@ -431,6 +486,7 @@ interface IPrefixedKVService {
 interface IKVServiceLike {
     get<T = unknown>(key: string, options?: KVGetOptions): Promise<Result<KVResponse<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<void>>;
     head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
@@ -503,6 +559,10 @@ declare class PrefixedKVService implements IPrefixedKVService {
      * Store a value at a key.
      */
     put(key: string, value: unknown, options?: Omit<KVPutOptions, 'prefix'>): Promise<Result<KVResponse<void>>>;
+    /**
+     * Store multiple values within this prefix in one TinyCloud KV invocation.
+     */
+    batchPut(items: KVBatchPutItem[], options?: Omit<KVBatchPutOptions, 'prefix'>): Promise<Result<KVBatchPutResponse>>;
     /**
      * List keys within this prefix.
      */
@@ -590,6 +650,17 @@ interface IKVService extends IService {
      * ```
      */
     put(key: string, value: unknown, options?: KVPutOptions): Promise<Result<KVResponse<void>>>;
+    /**
+     * Store multiple values in one TinyCloud KV invocation.
+     *
+     * The batch is authorized as one invocation containing one `tinycloud.kv/put`
+     * capability per key. The node commits the whole batch or rejects it.
+     *
+     * @param items - Entries to write
+     * @param options - Optional batch configuration
+     * @returns Result with the written keys and count
+     */
+    batchPut(items: KVBatchPutItem[], options?: KVBatchPutOptions): Promise<Result<KVBatchPutResponse>>;
     /**
      * List keys with optional prefix filtering.
      *
@@ -757,6 +828,8 @@ declare class KVService extends BaseService implements IKVService {
      * @returns Fetch response
      */
     private invokeOperation;
+    private serializeBatchPutValue;
+    private normalizeBatchPutResponse;
     /**
      * Create KVResponseHeaders from fetch response headers.
      *
@@ -782,6 +855,10 @@ declare class KVService extends BaseService implements IKVService {
      * Store a value at a key.
      */
     put(key: string, value: unknown, options?: KVPutOptions): Promise<Result<KVResponse<void>>>;
+    /**
+     * Store multiple values in one TinyCloud KV invocation.
+     */
+    batchPut(items: KVBatchPutItem[], options?: KVBatchPutOptions): Promise<Result<KVBatchPutResponse>>;
     /**
      * List keys with optional prefix filtering.
      */
@@ -843,4 +920,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 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 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

@@ -1,4 +1,4 @@
-import { e as Result, c as IService, B as BaseService } from '../BaseService-C_iXlTeN.js';
+import { e as Result, c as IService, B as BaseService } from '../BaseService-DZ2hBJeD.js';
 
 /**
  * KV Service Types
@@ -76,6 +76,57 @@ interface KVPutOptions {
      */
     signal?: AbortSignal;
 }
+/**
+ * One entry in a KV batch put request.
+ */
+interface KVBatchPutItem {
+    /**
+     * The key to store under.
+     */
+    key: string;
+    /**
+     * The value to store.
+     *
+     * Objects are JSON stringified. Strings are stored as text. Binary values
+     * should be supplied as Blob, ArrayBuffer, or Uint8Array.
+     */
+    value: unknown;
+    /**
+     * Content type for this item. Defaults to application/json for objects and
+     * application/octet-stream for binary values.
+     */
+    contentType?: string;
+}
+/**
+ * Options for KV batch put operations.
+ */
+interface KVBatchPutOptions {
+    /**
+     * Override the default prefix for all entries in this batch.
+     */
+    prefix?: string;
+    /**
+     * Custom timeout for this operation in milliseconds.
+     */
+    timeout?: number;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Response from KV batch put operations.
+ */
+interface KVBatchPutResponse {
+    /**
+     * Keys successfully written by the batch.
+     */
+    written: string[];
+    /**
+     * Number of written keys.
+     */
+    count: number;
+}
 /**
  * Options for KV list operations.
  */
@@ -343,6 +394,10 @@ interface IPrefixedKVService {
      * ```
      */
     put(key: string, value: unknown, options?: Omit<KVPutOptions, 'prefix'>): Promise<Result<KVResponse<void>>>;
+    /**
+     * Store multiple values within this prefix in one TinyCloud KV invocation.
+     */
+    batchPut(items: KVBatchPutItem[], options?: Omit<KVBatchPutOptions, 'prefix'>): Promise<Result<KVBatchPutResponse>>;
     /**
      * List keys within this prefix.
      *
@@ -431,6 +486,7 @@ interface IPrefixedKVService {
 interface IKVServiceLike {
     get<T = unknown>(key: string, options?: KVGetOptions): Promise<Result<KVResponse<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<void>>;
     head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
@@ -503,6 +559,10 @@ declare class PrefixedKVService implements IPrefixedKVService {
      * Store a value at a key.
      */
     put(key: string, value: unknown, options?: Omit<KVPutOptions, 'prefix'>): Promise<Result<KVResponse<void>>>;
+    /**
+     * Store multiple values within this prefix in one TinyCloud KV invocation.
+     */
+    batchPut(items: KVBatchPutItem[], options?: Omit<KVBatchPutOptions, 'prefix'>): Promise<Result<KVBatchPutResponse>>;
     /**
      * List keys within this prefix.
      */
@@ -590,6 +650,17 @@ interface IKVService extends IService {
      * ```
      */
     put(key: string, value: unknown, options?: KVPutOptions): Promise<Result<KVResponse<void>>>;
+    /**
+     * Store multiple values in one TinyCloud KV invocation.
+     *
+     * The batch is authorized as one invocation containing one `tinycloud.kv/put`
+     * capability per key. The node commits the whole batch or rejects it.
+     *
+     * @param items - Entries to write
+     * @param options - Optional batch configuration
+     * @returns Result with the written keys and count
+     */
+    batchPut(items: KVBatchPutItem[], options?: KVBatchPutOptions): Promise<Result<KVBatchPutResponse>>;
     /**
      * List keys with optional prefix filtering.
      *
@@ -757,6 +828,8 @@ declare class KVService extends BaseService implements IKVService {
      * @returns Fetch response
      */
     private invokeOperation;
+    private serializeBatchPutValue;
+    private normalizeBatchPutResponse;
     /**
      * Create KVResponseHeaders from fetch response headers.
      *
@@ -782,6 +855,10 @@ declare class KVService extends BaseService implements IKVService {
      * Store a value at a key.
      */
     put(key: string, value: unknown, options?: KVPutOptions): Promise<Result<KVResponse<void>>>;
+    /**
+     * Store multiple values in one TinyCloud KV invocation.
+     */
+    batchPut(items: KVBatchPutItem[], options?: KVBatchPutOptions): Promise<Result<KVBatchPutResponse>>;
     /**
      * List keys with optional prefix filtering.
      */
@@ -843,4 +920,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 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 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

@@ -361,6 +361,18 @@ var PrefixedKVService = class _PrefixedKVService {
     const fullKey = this.getFullKey(key);
     return this._kv.put(fullKey, value, { ...options, prefix: "" });
   }
+  /**
+   * Store multiple values within this prefix in one TinyCloud KV invocation.
+   */
+  async batchPut(items, options) {
+    return this._kv.batchPut(
+      items.map((item) => ({
+        ...item,
+        key: this.getFullKey(item.key)
+      })),
+      { ...options, prefix: "" }
+    );
+  }
   /**
    * List keys within this prefix.
    */
@@ -414,6 +426,12 @@ var KVAction = {
 };
 
 // src/kv/KVService.ts
+function encodeKvBatchPartName(path) {
+  return encodeURIComponent(path).replace(
+    /[!'()*]/g,
+    (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`
+  );
+}
 var KVService = class extends BaseService {
   /**
    * Create a new KVService instance.
@@ -522,6 +540,53 @@ var KVService = class extends BaseService {
       signal: this.combineSignals(signal)
     });
   }
+  serializeBatchPutValue(item) {
+    const contentType = item.contentType;
+    if (item.value instanceof Blob) {
+      if (!contentType || item.value.type === contentType) {
+        return item.value;
+      }
+      return new Blob([item.value], { type: contentType });
+    }
+    if (item.value instanceof ArrayBuffer) {
+      return new Blob([item.value], {
+        type: contentType ?? "application/octet-stream"
+      });
+    }
+    if (ArrayBuffer.isView(item.value)) {
+      const value = item.value;
+      const bytes = new Uint8Array(value.byteLength);
+      bytes.set(new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
+      return new Blob([bytes], {
+        type: contentType ?? "application/octet-stream"
+      });
+    }
+    if (typeof item.value === "string") {
+      return new Blob([item.value], {
+        type: contentType ?? "text/plain;charset=UTF-8"
+      });
+    }
+    const json = JSON.stringify(item.value);
+    if (json === void 0) {
+      throw new Error(`Cannot JSON serialize KV batch value for key "${item.key}"`);
+    }
+    return new Blob([json], {
+      type: contentType ?? "application/json"
+    });
+  }
+  normalizeBatchPutResponse(data) {
+    if (!data || typeof data !== "object") {
+      return void 0;
+    }
+    const response = data;
+    if (!Array.isArray(response.written) || !response.written.every((key) => typeof key === "string") || typeof response.count !== "number") {
+      return void 0;
+    }
+    return {
+      written: response.written,
+      count: response.count
+    };
+  }
   /**
    * Create KVResponseHeaders from fetch response headers.
    *
@@ -723,6 +788,107 @@ var KVService = class extends BaseService {
       }
     });
   }
+  /**
+   * Store multiple values in one TinyCloud KV invocation.
+   */
+  async batchPut(items, options) {
+    return this.withTelemetry("batchPut", String(items.length), async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("kv"));
+      }
+      if (items.length === 0) {
+        return ok({ written: [], count: 0 });
+      }
+      if (!this.context.invokeAny) {
+        return err(
+          serviceError(
+            ErrorCodes.INVALID_INPUT,
+            "KV batchPut requires SDK runtime support for multi-resource invocations",
+            "kv"
+          )
+        );
+      }
+      const session = this.context.session;
+      const paths = items.map((item) => this.getFullPath(item.key, options?.prefix));
+      const seen = /* @__PURE__ */ new Set();
+      for (const path of paths) {
+        if (seen.has(path)) {
+          return err(
+            serviceError(
+              ErrorCodes.INVALID_INPUT,
+              `KV batchPut received duplicate key after prefix resolution: ${path}`,
+              "kv"
+            )
+          );
+        }
+        seen.add(path);
+      }
+      try {
+        const body = new FormData();
+        for (let index = 0; index < items.length; index++) {
+          body.append(
+            encodeKvBatchPartName(paths[index]),
+            this.serializeBatchPutValue(items[index])
+          );
+        }
+        const headers = this.context.invokeAny(
+          session,
+          paths.map((path) => ({
+            spaceId: session.spaceId,
+            service: "kv",
+            path,
+            action: KVAction.PUT
+          }))
+        );
+        const response = await this.context.fetch(`${this.host}/invoke`, {
+          method: "POST",
+          headers,
+          body,
+          signal: this.combineSignals(options?.signal)
+        });
+        if (!response.ok) {
+          const errorText = await response.text();
+          if (response.status === 401 || response.status === 403) {
+            const { resource, action } = parseAuthError(errorText);
+            return err(authUnauthorizedError("kv", errorText, {
+              status: response.status,
+              ...action && { requiredAction: action },
+              ...resource && { resource }
+            }));
+          }
+          const quotaError = this.handleQuotaErrorResponse(
+            response,
+            errorText,
+            "batch"
+          );
+          if (quotaError) {
+            return quotaError;
+          }
+          return err(
+            serviceError(
+              ErrorCodes.KV_WRITE_FAILED,
+              `Failed to batch put ${items.length} key(s): ${response.status} - ${errorText}`,
+              "kv",
+              { meta: { status: response.status, statusText: response.statusText } }
+            )
+          );
+        }
+        const batchResponse = this.normalizeBatchPutResponse(await response.json());
+        if (!batchResponse || batchResponse.count !== batchResponse.written.length) {
+          return err(
+            serviceError(
+              ErrorCodes.NETWORK_ERROR,
+              "KV batchPut response did not include matching written keys and count",
+              "kv"
+            )
+          );
+        }
+        return ok(batchResponse);
+      } catch (error) {
+        return err(wrapError("kv", error));
+      }
+    });
+  }
   /**
    * List keys with optional prefix filtering.
    */