@tinycloud/sdk-services 2.1.0 → 2.2.0-beta.12

package/dist/kv/index.d.cts

@@ -140,6 +140,47 @@ interface KVHeadOptions {
      */
     signal?: AbortSignal;
 }
+/**
+ * Default lifetime for signed KV read URLs when a caller omits expiresInSeconds.
+ * SDK duration defaults are stored in milliseconds; createSignedReadUrl converts
+ * this to the node endpoint's ttl_seconds field.
+ *
+ * Keep this in sync with EXPIRY.SIGNED_READ_URL_MS in @tinycloud/sdk-core.
+ * sdk-services cannot import sdk-core because sdk-core depends on sdk-services.
+ */
+declare const DEFAULT_SIGNED_READ_URL_EXPIRY_MS: number;
+/**
+ * Options for creating a signed KV read URL.
+ */
+interface KVCreateSignedReadUrlOptions {
+    /**
+     * Override the default prefix for this operation.
+     */
+    prefix?: string;
+    /**
+     * Requested URL lifetime in seconds.
+     * Defaults to {@link DEFAULT_SIGNED_READ_URL_EXPIRY_MS} converted to seconds.
+     * The node may cap this by its configured maximum, the invocation expiry,
+     * or the parent delegation expiry.
+     */
+    expiresInSeconds?: number;
+    /**
+     * Optional blake3 content hash to bind the signed URL to a specific object.
+     */
+    contentHash?: string;
+    /**
+     * Optional ETag to bind the signed URL to a specific object version.
+     */
+    etag?: string;
+    /**
+     * Custom timeout for this operation in milliseconds.
+     */
+    timeout?: number;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
 /**
  * Response headers from KV operations.
  */
@@ -192,6 +233,27 @@ interface KVListResponse {
      */
     keys: string[];
 }
+/**
+ * Response from signed KV read URL creation.
+ */
+interface KVSignedReadUrlResponse {
+    /**
+     * Absolute URL suitable for passing to external readers.
+     */
+    url: string;
+    /**
+     * Opaque URL returned by tinycloud-node, usually relative to the node host.
+     */
+    relativeUrl: string;
+    /**
+     * Opaque signed KV ticket identifier.
+     */
+    ticketId: string;
+    /**
+     * Expiry timestamp as returned by tinycloud-node.
+     */
+    expiresAt: string;
+}
 /**
  * KV service action types.
  */
@@ -333,6 +395,16 @@ interface IPrefixedKVService {
      * ```
      */
     head(key: string, options?: Omit<KVHeadOptions, 'prefix'>): Promise<Result<KVResponse<void>>>;
+    /**
+     * Create a short-lived signed URL for reading a KV object.
+     *
+     * The key is automatically prefixed with this service's prefix.
+     *
+     * @param key - The key to expose via a signed read URL (will be prefixed)
+     * @param options - Optional signed URL configuration
+     * @returns Result with URL and expiry metadata
+     */
+    createSignedReadUrl(key: string, options?: Omit<KVCreateSignedReadUrlOptions, 'prefix'>): Promise<Result<KVSignedReadUrlResponse>>;
     /**
      * Create a nested prefix-scoped view.
      *
@@ -362,6 +434,7 @@ interface IKVServiceLike {
     list(options?: KVListOptions): Promise<Result<KVListResponse>>;
     delete(key: string, options?: KVDeleteOptions): Promise<Result<void>>;
     head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
+    createSignedReadUrl(key: string, options?: KVCreateSignedReadUrlOptions): Promise<Result<KVSignedReadUrlResponse>>;
 }
 /**
  * PrefixedKVService - Implementation of prefix-scoped KV operations.
@@ -442,6 +515,10 @@ 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>>>;
+    /**
+     * Create a short-lived signed URL for reading a KV object.
+     */
+    createSignedReadUrl(key: string, options?: Omit<KVCreateSignedReadUrlOptions, 'prefix'>): Promise<Result<KVSignedReadUrlResponse>>;
     /**
      * Create a nested prefix-scoped view.
      */
@@ -564,6 +641,20 @@ interface IKVService extends IService {
      * ```
      */
     head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
+    /**
+     * Create a short-lived signed URL for reading a KV object.
+     *
+     * The request is authorized with the current session's `tinycloud.kv/get`
+     * capability for the resolved key path. The returned `url` is absolute and
+     * can be passed to external services that need bearer read access.
+     *
+     * Requires tinycloud-node with the `/signed/kv` endpoint from TC-1368.
+     *
+     * @param key - The key to expose via a signed read URL
+     * @param options - Optional signed URL configuration
+     * @returns Result with URL and expiry metadata
+     */
+    createSignedReadUrl(key: string, options?: KVCreateSignedReadUrlOptions): Promise<Result<KVSignedReadUrlResponse>>;
     /**
      * Create a prefix-scoped view of this KV service.
      *
@@ -655,6 +746,7 @@ declare class KVService extends BaseService implements IKVService {
      * Get the host URL.
      */
     private get host();
+    private withJsonContentType;
     /**
      * Execute an invoke operation.
      *
@@ -680,6 +772,8 @@ declare class KVService extends BaseService implements IKVService {
      * @returns Parsed data
      */
     private parseResponse;
+    private createSignedReadUrlError;
+    private normalizeSignedReadUrlResponse;
     /**
      * Get a value by key.
      */
@@ -700,6 +794,10 @@ 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>>>;
+    /**
+     * Create a short-lived signed URL for reading a KV object.
+     */
+    createSignedReadUrl(key: string, options?: KVCreateSignedReadUrlOptions): Promise<Result<KVSignedReadUrlResponse>>;
     /**
      * Create a prefix-scoped view of this KV service.
      *
@@ -745,4 +843,4 @@ declare class KVService extends BaseService implements IKVService {
     withPrefix(prefix: string): IPrefixedKVService;
 }
 
-export { type IKVService, type IPrefixedKVService, KVAction, type KVActionType, type KVDeleteOptions, type KVGetOptions, type KVHeadOptions, type KVListOptions, type KVListResponse, type KVPutOptions, type KVResponse, type KVResponseHeaders, KVService, type KVServiceConfig, PrefixedKVService };
+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 };

package/dist/kv/index.d.ts

@@ -140,6 +140,47 @@ interface KVHeadOptions {
      */
     signal?: AbortSignal;
 }
+/**
+ * Default lifetime for signed KV read URLs when a caller omits expiresInSeconds.
+ * SDK duration defaults are stored in milliseconds; createSignedReadUrl converts
+ * this to the node endpoint's ttl_seconds field.
+ *
+ * Keep this in sync with EXPIRY.SIGNED_READ_URL_MS in @tinycloud/sdk-core.
+ * sdk-services cannot import sdk-core because sdk-core depends on sdk-services.
+ */
+declare const DEFAULT_SIGNED_READ_URL_EXPIRY_MS: number;
+/**
+ * Options for creating a signed KV read URL.
+ */
+interface KVCreateSignedReadUrlOptions {
+    /**
+     * Override the default prefix for this operation.
+     */
+    prefix?: string;
+    /**
+     * Requested URL lifetime in seconds.
+     * Defaults to {@link DEFAULT_SIGNED_READ_URL_EXPIRY_MS} converted to seconds.
+     * The node may cap this by its configured maximum, the invocation expiry,
+     * or the parent delegation expiry.
+     */
+    expiresInSeconds?: number;
+    /**
+     * Optional blake3 content hash to bind the signed URL to a specific object.
+     */
+    contentHash?: string;
+    /**
+     * Optional ETag to bind the signed URL to a specific object version.
+     */
+    etag?: string;
+    /**
+     * Custom timeout for this operation in milliseconds.
+     */
+    timeout?: number;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
 /**
  * Response headers from KV operations.
  */
@@ -192,6 +233,27 @@ interface KVListResponse {
      */
     keys: string[];
 }
+/**
+ * Response from signed KV read URL creation.
+ */
+interface KVSignedReadUrlResponse {
+    /**
+     * Absolute URL suitable for passing to external readers.
+     */
+    url: string;
+    /**
+     * Opaque URL returned by tinycloud-node, usually relative to the node host.
+     */
+    relativeUrl: string;
+    /**
+     * Opaque signed KV ticket identifier.
+     */
+    ticketId: string;
+    /**
+     * Expiry timestamp as returned by tinycloud-node.
+     */
+    expiresAt: string;
+}
 /**
  * KV service action types.
  */
@@ -333,6 +395,16 @@ interface IPrefixedKVService {
      * ```
      */
     head(key: string, options?: Omit<KVHeadOptions, 'prefix'>): Promise<Result<KVResponse<void>>>;
+    /**
+     * Create a short-lived signed URL for reading a KV object.
+     *
+     * The key is automatically prefixed with this service's prefix.
+     *
+     * @param key - The key to expose via a signed read URL (will be prefixed)
+     * @param options - Optional signed URL configuration
+     * @returns Result with URL and expiry metadata
+     */
+    createSignedReadUrl(key: string, options?: Omit<KVCreateSignedReadUrlOptions, 'prefix'>): Promise<Result<KVSignedReadUrlResponse>>;
     /**
      * Create a nested prefix-scoped view.
      *
@@ -362,6 +434,7 @@ interface IKVServiceLike {
     list(options?: KVListOptions): Promise<Result<KVListResponse>>;
     delete(key: string, options?: KVDeleteOptions): Promise<Result<void>>;
     head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
+    createSignedReadUrl(key: string, options?: KVCreateSignedReadUrlOptions): Promise<Result<KVSignedReadUrlResponse>>;
 }
 /**
  * PrefixedKVService - Implementation of prefix-scoped KV operations.
@@ -442,6 +515,10 @@ 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>>>;
+    /**
+     * Create a short-lived signed URL for reading a KV object.
+     */
+    createSignedReadUrl(key: string, options?: Omit<KVCreateSignedReadUrlOptions, 'prefix'>): Promise<Result<KVSignedReadUrlResponse>>;
     /**
      * Create a nested prefix-scoped view.
      */
@@ -564,6 +641,20 @@ interface IKVService extends IService {
      * ```
      */
     head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
+    /**
+     * Create a short-lived signed URL for reading a KV object.
+     *
+     * The request is authorized with the current session's `tinycloud.kv/get`
+     * capability for the resolved key path. The returned `url` is absolute and
+     * can be passed to external services that need bearer read access.
+     *
+     * Requires tinycloud-node with the `/signed/kv` endpoint from TC-1368.
+     *
+     * @param key - The key to expose via a signed read URL
+     * @param options - Optional signed URL configuration
+     * @returns Result with URL and expiry metadata
+     */
+    createSignedReadUrl(key: string, options?: KVCreateSignedReadUrlOptions): Promise<Result<KVSignedReadUrlResponse>>;
     /**
      * Create a prefix-scoped view of this KV service.
      *
@@ -655,6 +746,7 @@ declare class KVService extends BaseService implements IKVService {
      * Get the host URL.
      */
     private get host();
+    private withJsonContentType;
     /**
      * Execute an invoke operation.
      *
@@ -680,6 +772,8 @@ declare class KVService extends BaseService implements IKVService {
      * @returns Parsed data
      */
     private parseResponse;
+    private createSignedReadUrlError;
+    private normalizeSignedReadUrlResponse;
     /**
      * Get a value by key.
      */
@@ -700,6 +794,10 @@ 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>>>;
+    /**
+     * Create a short-lived signed URL for reading a KV object.
+     */
+    createSignedReadUrl(key: string, options?: KVCreateSignedReadUrlOptions): Promise<Result<KVSignedReadUrlResponse>>;
     /**
      * Create a prefix-scoped view of this KV service.
      *
@@ -745,4 +843,4 @@ declare class KVService extends BaseService implements IKVService {
     withPrefix(prefix: string): IPrefixedKVService;
 }
 
-export { type IKVService, type IPrefixedKVService, KVAction, type KVActionType, type KVDeleteOptions, type KVGetOptions, type KVHeadOptions, type KVListOptions, type KVListResponse, type KVPutOptions, type KVResponse, type KVResponseHeaders, KVService, type KVServiceConfig, PrefixedKVService };
+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 };

package/dist/kv/index.js

@@ -386,6 +386,13 @@ var PrefixedKVService = class _PrefixedKVService {
     const fullKey = this.getFullKey(key);
     return this._kv.head(fullKey, { ...options, prefix: "" });
   }
+  /**
+   * Create a short-lived signed URL for reading a KV object.
+   */
+  async createSignedReadUrl(key, options) {
+    const fullKey = this.getFullKey(key);
+    return this._kv.createSignedReadUrl(fullKey, { ...options, prefix: "" });
+  }
   /**
    * Create a nested prefix-scoped view.
    */
@@ -397,6 +404,7 @@ var PrefixedKVService = class _PrefixedKVService {
 };
 
 // src/kv/types.ts
+var DEFAULT_SIGNED_READ_URL_EXPIRY_MS = 5 * 60 * 1e3;
 var KVAction = {
   GET: "tinycloud.kv/get",
   PUT: "tinycloud.kv/put",
@@ -481,6 +489,15 @@ var KVService = class extends BaseService {
   get host() {
     return this.context.hosts[0];
   }
+  withJsonContentType(headers) {
+    if (Array.isArray(headers)) {
+      return [...headers, ["content-type", "application/json"]];
+    }
+    return {
+      ...headers,
+      "content-type": "application/json"
+    };
+  }
   /**
    * Execute an invoke operation.
    *
@@ -550,6 +567,48 @@ var KVService = class extends BaseService {
       return text;
     }
   }
+  async createSignedReadUrlError(response, key) {
+    let errorText = response.statusText;
+    try {
+      const text = await response.text();
+      if (text) {
+        errorText = text;
+      }
+    } catch {
+    }
+    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 code = response.status === 400 ? ErrorCodes.INVALID_INPUT : ErrorCodes.NETWORK_ERROR;
+    return err(
+      serviceError(
+        code,
+        `Failed to create signed read URL for key "${key}": ${response.status} - ${errorText}`,
+        "kv",
+        { meta: { status: response.status, statusText: response.statusText } }
+      )
+    );
+  }
+  normalizeSignedReadUrlResponse(data) {
+    if (!data || typeof data !== "object") {
+      return void 0;
+    }
+    const response = data;
+    if (typeof response.url !== "string" || typeof response.ticketId !== "string" || typeof response.expiresAt !== "string") {
+      return void 0;
+    }
+    return {
+      url: new URL(response.url, this.host).toString(),
+      relativeUrl: response.url,
+      ticketId: response.ticketId,
+      expiresAt: response.expiresAt
+    };
+  }
   /**
    * Get a value by key.
    */
@@ -822,6 +881,61 @@ var KVService = class extends BaseService {
       }
     });
   }
+  /**
+   * Create a short-lived signed URL for reading a KV object.
+   */
+  async createSignedReadUrl(key, options) {
+    return this.withTelemetry("createSignedReadUrl", key, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("kv"));
+      }
+      const path = this.getFullPath(key, options?.prefix);
+      const session = this.context.session;
+      const headers = this.context.invoke(
+        session,
+        "kv",
+        path,
+        KVAction.GET
+      );
+      const body = {
+        space: session.spaceId,
+        path,
+        ttl_seconds: options?.expiresInSeconds ?? Math.ceil(DEFAULT_SIGNED_READ_URL_EXPIRY_MS / 1e3)
+      };
+      if (options?.contentHash !== void 0) {
+        body.content_hash = options.contentHash;
+      }
+      if (options?.etag !== void 0) {
+        body.etag = options.etag;
+      }
+      try {
+        const response = await this.context.fetch(`${this.host}/signed/kv`, {
+          method: "POST",
+          headers: this.withJsonContentType(headers),
+          body: JSON.stringify(body),
+          signal: this.combineSignals(options?.signal)
+        });
+        if (!response.ok) {
+          return this.createSignedReadUrlError(response, key);
+        }
+        const signedUrl = this.normalizeSignedReadUrlResponse(
+          await response.json()
+        );
+        if (!signedUrl) {
+          return err(
+            serviceError(
+              ErrorCodes.NETWORK_ERROR,
+              "Signed read URL response did not include url, ticketId, and expiresAt",
+              "kv"
+            )
+          );
+        }
+        return ok(signedUrl);
+      } catch (error) {
+        return err(wrapError("kv", error));
+      }
+    });
+  }
   /**
    * Create a prefix-scoped view of this KV service.
    *
@@ -873,6 +987,7 @@ var KVService = class extends BaseService {
  */
 KVService.serviceName = "kv";
 export {
+  DEFAULT_SIGNED_READ_URL_EXPIRY_MS,
   KVAction,
   KVService,
   PrefixedKVService