@tinycloud/sdk-services 2.7.0 → 2.8.0

package/dist/kv/index.d.cts

@@ -1,5 +1,5 @@
-import { B as BaseService } from '../BaseService-BwBU5CQ4.cjs';
-import { R as Result, I as IService } from '../types-DAY1O1kW.cjs';
+import { B as BaseService } from '../BaseService-DxSU4U-v.cjs';
+import { R as Result, I as IService } from '../types-KCcgZiab.cjs';
 
 /**
  * KV Service Types
@@ -48,6 +48,11 @@ interface KVGetOptions {
      * precedence over {@link raw}.
      */
     binary?: boolean;
+    /**
+     * Ask the node to reject the response when the stored value exceeds this
+     * number of bytes. This bounds downloads before the response body is read.
+     */
+    maxResponseBytes?: number;
     /**
      * Custom timeout for this operation in milliseconds.
      */
@@ -74,6 +79,10 @@ interface KVPutOptions {
      * Custom metadata headers to store with the value.
      */
     metadata?: Record<string, string>;
+    /** Only write when the current object has this strong ETag. */
+    ifMatch?: string;
+    /** Only write when the key does not exist. */
+    ifNoneMatch?: "*";
     /**
      * Custom timeout for this operation in milliseconds.
      */
@@ -155,6 +164,8 @@ interface KVListOptions {
      * Return raw response instead of parsed JSON.
      */
     raw?: boolean;
+    /** Maximum number of keys the node may return. */
+    limit?: number;
     /**
      * Custom timeout for this operation in milliseconds.
      */
@@ -172,6 +183,8 @@ interface KVDeleteOptions {
      * Override the default prefix for this operation.
      */
     prefix?: string;
+    /** Only delete when the current object has this strong ETag. */
+    ifMatch?: string;
     /**
      * Custom timeout for this operation in milliseconds.
      */
@@ -290,6 +303,8 @@ interface KVListResponse {
      * Array of keys matching the list criteria.
      */
     keys: string[];
+    /** True when more matching keys exist than the requested limit. */
+    truncated?: boolean;
 }
 /**
  * Response from signed KV read URL creation.
@@ -439,7 +454,7 @@ interface IPrefixedKVService {
      * // -> Deletes: /app.myapp.com/old-settings.json
      * ```
      */
-    delete(key: string, options?: Omit<KVDeleteOptions, 'prefix'>): Promise<Result<void>>;
+    delete(key: string, options?: Omit<KVDeleteOptions, 'prefix'>): Promise<Result<KVResponse<void>>>;
     /**
      * Get metadata for a key without retrieving the value.
      *
@@ -495,7 +510,7 @@ interface IKVServiceLike {
     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>>;
+    delete(key: string, options?: KVDeleteOptions): Promise<Result<KVResponse<void>>>;
     head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
     createSignedReadUrl(key: string, options?: KVCreateSignedReadUrlOptions): Promise<Result<KVSignedReadUrlResponse>>;
 }
@@ -577,7 +592,7 @@ declare class PrefixedKVService implements IPrefixedKVService {
     /**
      * Delete a key.
      */
-    delete(key: string, options?: Omit<KVDeleteOptions, 'prefix'>): Promise<Result<void>>;
+    delete(key: string, options?: Omit<KVDeleteOptions, 'prefix'>): Promise<Result<KVResponse<void>>>;
     /**
      * Get metadata for a key without retrieving the value.
      */
@@ -699,7 +714,7 @@ interface IKVService extends IService {
      * }
      * ```
      */
-    delete(key: string, options?: KVDeleteOptions): Promise<Result<void>>;
+    delete(key: string, options?: KVDeleteOptions): Promise<Result<KVResponse<void>>>;
     /**
      * Get metadata for a key without retrieving the value.
      *
@@ -895,7 +910,7 @@ declare class KVService extends BaseService implements IKVService {
     /**
      * Delete a key.
      */
-    delete(key: string, options?: KVDeleteOptions): Promise<Result<void>>;
+    delete(key: string, options?: KVDeleteOptions): Promise<Result<KVResponse<void>>>;
     /**
      * Get metadata for a key without retrieving the value.
      */

package/dist/kv/index.d.ts

@@ -1,5 +1,5 @@
-import { B as BaseService } from '../BaseService-CnPTKR5G.js';
-import { R as Result, I as IService } from '../types-DAY1O1kW.js';
+import { B as BaseService } from '../BaseService-BiYeqCRT.js';
+import { R as Result, I as IService } from '../types-KCcgZiab.js';
 
 /**
  * KV Service Types
@@ -48,6 +48,11 @@ interface KVGetOptions {
      * precedence over {@link raw}.
      */
     binary?: boolean;
+    /**
+     * Ask the node to reject the response when the stored value exceeds this
+     * number of bytes. This bounds downloads before the response body is read.
+     */
+    maxResponseBytes?: number;
     /**
      * Custom timeout for this operation in milliseconds.
      */
@@ -74,6 +79,10 @@ interface KVPutOptions {
      * Custom metadata headers to store with the value.
      */
     metadata?: Record<string, string>;
+    /** Only write when the current object has this strong ETag. */
+    ifMatch?: string;
+    /** Only write when the key does not exist. */
+    ifNoneMatch?: "*";
     /**
      * Custom timeout for this operation in milliseconds.
      */
@@ -155,6 +164,8 @@ interface KVListOptions {
      * Return raw response instead of parsed JSON.
      */
     raw?: boolean;
+    /** Maximum number of keys the node may return. */
+    limit?: number;
     /**
      * Custom timeout for this operation in milliseconds.
      */
@@ -172,6 +183,8 @@ interface KVDeleteOptions {
      * Override the default prefix for this operation.
      */
     prefix?: string;
+    /** Only delete when the current object has this strong ETag. */
+    ifMatch?: string;
     /**
      * Custom timeout for this operation in milliseconds.
      */
@@ -290,6 +303,8 @@ interface KVListResponse {
      * Array of keys matching the list criteria.
      */
     keys: string[];
+    /** True when more matching keys exist than the requested limit. */
+    truncated?: boolean;
 }
 /**
  * Response from signed KV read URL creation.
@@ -439,7 +454,7 @@ interface IPrefixedKVService {
      * // -> Deletes: /app.myapp.com/old-settings.json
      * ```
      */
-    delete(key: string, options?: Omit<KVDeleteOptions, 'prefix'>): Promise<Result<void>>;
+    delete(key: string, options?: Omit<KVDeleteOptions, 'prefix'>): Promise<Result<KVResponse<void>>>;
     /**
      * Get metadata for a key without retrieving the value.
      *
@@ -495,7 +510,7 @@ interface IKVServiceLike {
     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>>;
+    delete(key: string, options?: KVDeleteOptions): Promise<Result<KVResponse<void>>>;
     head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
     createSignedReadUrl(key: string, options?: KVCreateSignedReadUrlOptions): Promise<Result<KVSignedReadUrlResponse>>;
 }
@@ -577,7 +592,7 @@ declare class PrefixedKVService implements IPrefixedKVService {
     /**
      * Delete a key.
      */
-    delete(key: string, options?: Omit<KVDeleteOptions, 'prefix'>): Promise<Result<void>>;
+    delete(key: string, options?: Omit<KVDeleteOptions, 'prefix'>): Promise<Result<KVResponse<void>>>;
     /**
      * Get metadata for a key without retrieving the value.
      */
@@ -699,7 +714,7 @@ interface IKVService extends IService {
      * }
      * ```
      */
-    delete(key: string, options?: KVDeleteOptions): Promise<Result<void>>;
+    delete(key: string, options?: KVDeleteOptions): Promise<Result<KVResponse<void>>>;
     /**
      * Get metadata for a key without retrieving the value.
      *
@@ -895,7 +910,7 @@ declare class KVService extends BaseService implements IKVService {
     /**
      * Delete a key.
      */
-    delete(key: string, options?: KVDeleteOptions): Promise<Result<void>>;
+    delete(key: string, options?: KVDeleteOptions): Promise<Result<KVResponse<void>>>;
     /**
      * Get metadata for a key without retrieving the value.
      */

package/dist/kv/index.js

@@ -13,6 +13,9 @@ var ErrorCodes = {
   // KV-specific errors
   KV_NOT_FOUND: "KV_NOT_FOUND",
   KV_WRITE_FAILED: "KV_WRITE_FAILED",
+  KV_PRECONDITION_FAILED: "KV_PRECONDITION_FAILED",
+  KV_CONFLICT: "KV_CONFLICT",
+  KV_RESPONSE_TOO_LARGE: "KV_RESPONSE_TOO_LARGE",
   // SQL-specific errors
   SQL_ERROR: "SQL_ERROR",
   SQL_PERMISSION_DENIED: "SQL_PERMISSION_DENIED",
@@ -614,7 +617,7 @@ var KVService = class extends BaseService {
    * @param signal - Optional abort signal
    * @returns Fetch response
    */
-  async invokeOperation(path, action, body, signal) {
+  async invokeOperation(path, action, body, signal, extraHeaders) {
     const session = this.context.session;
     const headers = this.context.invoke(
       session,
@@ -622,9 +625,10 @@ var KVService = class extends BaseService {
       path,
       action
     );
+    const requestHeaders = Array.isArray(headers) ? [...headers, ...Object.entries(extraHeaders ?? {})] : { ...headers, ...extraHeaders };
     return this.context.fetch(`${this.host}/invoke`, {
       method: "POST",
-      headers,
+      headers: requestHeaders,
       body,
       signal: this.combineSignals(signal)
     });
@@ -806,13 +810,21 @@ var KVService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("kv"));
       }
+      if (options?.maxResponseBytes !== void 0 && (!Number.isSafeInteger(options.maxResponseBytes) || options.maxResponseBytes <= 0)) {
+        return err(serviceError(
+          ErrorCodes.INVALID_INPUT,
+          "KV maxResponseBytes must be a positive safe integer",
+          "kv"
+        ));
+      }
       const path = this.getFullPath(key, options?.prefix);
       try {
         const response = await this.invokeOperation(
           path,
           KVAction.GET,
           void 0,
-          options?.signal
+          options?.signal,
+          options?.maxResponseBytes === void 0 ? void 0 : { "x-tinycloud-max-response-bytes": String(options.maxResponseBytes) }
         );
         if (!response.ok) {
           if (response.status === 401 || response.status === 403) {
@@ -830,6 +842,14 @@ var KVService = class extends BaseService {
             return this.classifyNotFound(response, key);
           }
           const errorText = await response.text();
+          if (response.status === 413) {
+            return err(serviceError(
+              ErrorCodes.KV_RESPONSE_TOO_LARGE,
+              `KV value at key "${key}" exceeds the requested response limit`,
+              "kv",
+              { meta: { status: response.status, statusText: response.statusText } }
+            ));
+          }
           return err(
             serviceError(
               ErrorCodes.NETWORK_ERROR,
@@ -861,6 +881,13 @@ var KVService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("kv"));
       }
+      if (options?.ifMatch !== void 0 && options.ifNoneMatch !== void 0) {
+        return err(serviceError(
+          ErrorCodes.INVALID_INPUT,
+          "KV put cannot combine ifMatch and ifNoneMatch",
+          "kv"
+        ));
+      }
       const path = this.getFullPath(key, options?.prefix);
       const body = this.serializePutValue(value, options?.contentType);
       try {
@@ -868,7 +895,11 @@ var KVService = class extends BaseService {
           path,
           KVAction.PUT,
           body,
-          options?.signal
+          options?.signal,
+          {
+            ...options?.ifMatch === void 0 ? {} : { "if-match": options.ifMatch },
+            ...options?.ifNoneMatch === void 0 ? {} : { "if-none-match": options.ifNoneMatch }
+          }
         );
         if (!response.ok) {
           if (response.status === 401) {
@@ -881,6 +912,22 @@ var KVService = class extends BaseService {
             }));
           }
           const errorText = await response.text();
+          if (response.status === 412) {
+            return err(serviceError(
+              ErrorCodes.KV_PRECONDITION_FAILED,
+              `KV precondition failed for key "${key}"`,
+              "kv",
+              { meta: { status: response.status, statusText: response.statusText } }
+            ));
+          }
+          if (response.status === 503 && (options?.ifMatch !== void 0 || options?.ifNoneMatch !== void 0)) {
+            return err(serviceError(
+              ErrorCodes.KV_CONFLICT,
+              `Concurrent KV update conflicted for key "${key}"`,
+              "kv",
+              { meta: { status: response.status, statusText: response.statusText } }
+            ));
+          }
           const quotaError = this.handleQuotaErrorResponse(
             response,
             errorText,
@@ -1016,6 +1063,13 @@ var KVService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("kv"));
       }
+      if (options?.limit !== void 0 && (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 1e3)) {
+        return err(serviceError(
+          ErrorCodes.INVALID_INPUT,
+          "KV list limit must be an integer from 1 through 1000",
+          "kv"
+        ));
+      }
       let listPath = options?.prefix ?? this._config.prefix ?? "";
       if (options?.path) {
         listPath = listPath ? `${listPath}/${options.path}` : options.path;
@@ -1025,7 +1079,8 @@ var KVService = class extends BaseService {
           listPath,
           KVAction.LIST,
           void 0,
-          options?.signal
+          options?.signal,
+          options?.limit === void 0 ? void 0 : { "x-tinycloud-limit": String(options.limit) }
         );
         if (!response.ok) {
           if (response.status === 401) {
@@ -1055,7 +1110,10 @@ var KVService = class extends BaseService {
             (key) => key.startsWith(prefixWithSlash) ? key.slice(prefixWithSlash.length) : key
           );
         }
-        return ok({ keys });
+        return ok({
+          keys,
+          ...response.headers.get("x-tinycloud-truncated") === null ? {} : { truncated: response.headers.get("x-tinycloud-truncated") === "true" }
+        });
       } catch (error) {
         return err(wrapError("kv", error));
       }
@@ -1075,7 +1133,8 @@ var KVService = class extends BaseService {
           path,
           KVAction.DELETE,
           void 0,
-          options?.signal
+          options?.signal,
+          options?.ifMatch === void 0 ? void 0 : { "if-match": options.ifMatch }
         );
         if (!response.ok) {
           if (response.status === 401) {
@@ -1091,6 +1150,22 @@ var KVService = class extends BaseService {
             return this.classifyNotFound(response, key);
           }
           const errorText = await response.text();
+          if (response.status === 412) {
+            return err(serviceError(
+              ErrorCodes.KV_PRECONDITION_FAILED,
+              `KV precondition failed for key "${key}"`,
+              "kv",
+              { meta: { status: response.status, statusText: response.statusText } }
+            ));
+          }
+          if (response.status === 503 && options?.ifMatch !== void 0) {
+            return err(serviceError(
+              ErrorCodes.KV_CONFLICT,
+              `Concurrent KV delete conflicted for key "${key}"`,
+              "kv",
+              { meta: { status: response.status, statusText: response.statusText } }
+            ));
+          }
           return err(
             serviceError(
               ErrorCodes.NETWORK_ERROR,
@@ -1100,7 +1175,10 @@ var KVService = class extends BaseService {
             )
           );
         }
-        return ok(void 0);
+        return ok({
+          data: void 0,
+          headers: this.createResponseHeaders(response.headers)
+        });
       } catch (error) {
         return err(wrapError("kv", error));
       }