feat: add keyValueStore.getRecordPublicUrl (#725)

This PR adds new method to KV store client:
- `getRecordPublicUrl(key: string)`

Note: We already have this same method
([KeyValueStore.getPublicUrl](https://github.com/apify/apify-sdk-js/blob/master/packages/apify/src/key_value_store.ts#L19))
in SDK.

Author: danpoletaev

src/resource_clients/dataset.ts

@@ -168,7 +168,7 @@ export class DatasetClient<
      * Generates a URL that can be used to access dataset items.
      *
      * If the client has permission to access the dataset's URL signing key,
-     * the URL will include a signature to verify its authenticity.
+     * the URL will include a signature which will allow the link to work even without authentication.
      *
      * You can optionally control how long the signed URL should be valid using the `expiresInMillis` option.
      * This value sets the expiration duration in milliseconds from the time the URL is generated.

src/resource_clients/key_value_store.ts

@@ -5,7 +5,7 @@ import type { JsonValue } from 'type-fest';
 
 import type { STORAGE_GENERAL_ACCESS } from '@apify/consts';
 import log from '@apify/log';
-import { createStorageContentSignature } from '@apify/utilities';
+import { createHmacSignature, createStorageContentSignature } from '@apify/utilities';
 
 import type { ApifyApiError } from '../apify_api_error';
 import type { ApiClientSubResourceOptions } from '../base/api_client';
@@ -86,10 +86,31 @@ export class KeyValueStoreClient extends ResourceClient {
     }
 
     /**
-     * Generates a URL that can be used to access key-value store keys.
+     * Generates a URL that can be used to access key-value store record.
      *
      * If the client has permission to access the key-value store's URL signing key,
      * the URL will include a signature to verify its authenticity.
+     */
+    async getRecordPublicUrl(key: string): Promise<string> {
+        ow(key, ow.string.nonEmpty);
+
+        const store = await this.get();
+
+        const recordPublicUrl = new URL(this._url(`records/${key}`));
+
+        if (store?.urlSigningSecretKey) {
+            const signature = createHmacSignature(store.urlSigningSecretKey, key);
+            recordPublicUrl.searchParams.append('signature', signature);
+        }
+
+        return recordPublicUrl.toString();
+    }
+
+    /**
+     * Generates a URL that can be used to access key-value store keys.
+     *
+     * If the client has permission to access the key-value store's URL signing key,
+     * the URL will include a signature which will allow the link to work even without authentication.
      *
      * You can optionally control how long the signed URL should be valid using the `expiresInMillis` option.
      * This value sets the expiration duration in milliseconds from the time the URL is generated.

test/key_value_stores.test.js

@@ -554,6 +554,28 @@ describe('Key-Value Store methods', () => {
             validateRequest({}, { storeId, key });
         });
 
+        describe('getRecordPublicUrl()', () => {
+            it('should include a signature in the URL when the caller has permission to access the signing secret key', async () => {
+                const storeId = 'id-with-secret-key';
+                const key = 'some-key';
+                const res = await client.keyValueStore(storeId).getRecordPublicUrl(key);
+
+                const url = new URL(res);
+                expect(url.searchParams.get('signature')).toBeDefined();
+                expect(url.pathname).toBe(`/v2/key-value-stores/${storeId}/records/${key}`);
+            });
+
+            it('should not include a signature in the URL when the caller lacks permission to access the signing secret key', async () => {
+                const storeId = 'some-id';
+                const key = 'some-key';
+                const res = await client.keyValueStore(storeId).getRecordPublicUrl(key);
+
+                const url = new URL(res);
+                expect(url.searchParams.get('signature')).toBeNull();
+                expect(url.pathname).toBe(`/v2/key-value-stores/${storeId}/records/${key}`);
+            });
+        });
+
         describe('createKeysPublicUrl()', () => {
             it('should include a signature in the URL when the caller has permission to access the signing secret key', async () => {
                 const storeId = 'id-with-secret-key';