feat(helper): implement getAuthenticationParameters method and test cases

Author: manu4543

src/resources/helper.ts

@@ -14,6 +14,7 @@ import type {
 } from './shared';
 import transformationUtils, { safeBtoa } from '../lib/transformation-utils';
 import { createHmacSha1 } from '../lib/crypto-utils';
+import { uuid4 } from '../internal/utils/uuid';
 
 const TRANSFORMATION_PARAMETER = 'tr';
 const SIGNATURE_PARAMETER = 'ik-s';
@@ -132,8 +133,52 @@ export class Helper extends APIResource {
   buildTransformationString(transformation: Transformation[] | undefined): string {
     return buildTransformationString(transformation);
   }
+
+  /**
+   * Generates authentication parameters for client-side file uploads using ImageKit's Upload API V1.
+   *
+   * This method creates the required authentication signature that allows secure file uploads
+   * directly from the browser or mobile applications without exposing your private API key.
+   * The generated parameters include a unique token, expiration timestamp, and HMAC signature.
+   *
+   * @param token - Custom token for the upload session. If not provided, a UUID v4 will be generated automatically.
+   * @param expire - Expiration time in seconds from now. If not provided, defaults to 1800 seconds (30 minutes).
+   * @returns Authentication parameters object containing:
+   *   - `token`: Unique identifier for this upload session
+   *   - `expire`: Unix timestamp when these parameters expire
+   *   - `signature`: HMAC-SHA1 signature for authenticating the upload
+   *
+   * @throws {Error} If the private API key is not configured (should not happen in normal usage)
+   */
+  getAuthenticationParameters(token?: string, expire?: number) {
+    if (!this._client.privateAPIKey) {
+      throw new Error('Private API key is required for authentication parameters generation');
+    }
+
+    const DEFAULT_TIME_DIFF = 60 * 30;
+    const defaultExpire = Math.floor(Date.now() / 1000) + DEFAULT_TIME_DIFF;
+
+    const finalToken = token || uuid4();
+    const finalExpire = expire || defaultExpire;
+
+    return getAuthenticationParameters(finalToken, finalExpire, this._client.privateAPIKey);
+  }
 }
 
+const getAuthenticationParameters = function (token: string, expire: number, privateKey: string) {
+  var authParameters = {
+    token: token,
+    expire: expire,
+    signature: '',
+  };
+
+  var signature = createHmacSha1(privateKey, token + expire);
+
+  authParameters.signature = signature;
+
+  return authParameters;
+};
+
 function removeTrailingSlash(str: string): string {
   if (typeof str == 'string' && str[str.length - 1] == '/') {
     str = str.substring(0, str.length - 1);

tests/helper-authentication.test.ts

@@ -0,0 +1,62 @@
+import ImageKit from '@imagekit/nodejs';
+
+const client = new ImageKit({
+  privateAPIKey: 'private_key_test',
+  password: 'My Password',
+  baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010',
+});
+
+describe('Helper Authentication Parameters', function () {
+  it('should return correct authentication parameters with provided token and expire', function () {
+    const authenticationParameters = client.helper.getAuthenticationParameters('your_token', 1582269249);
+
+    expect(authenticationParameters).toEqual({
+      token: 'your_token',
+      expire: 1582269249,
+      signature: 'e71bcd6031016b060d349d212e23e85c791decdd',
+    });
+  });
+
+  it('should return authentication parameters with required properties when no params provided', function () {
+    const authenticationParameters = client.helper.getAuthenticationParameters();
+
+    expect(authenticationParameters).toHaveProperty('token');
+    expect(authenticationParameters).toHaveProperty('expire');
+    expect(authenticationParameters).toHaveProperty('signature');
+
+    // Token should be a UUID (36 characters with dashes)
+    expect(authenticationParameters.token).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+    );
+
+    // Expire should be a number greater than current time
+    expect(typeof authenticationParameters.expire).toBe('number');
+    expect(authenticationParameters.expire).toBeGreaterThan(Math.floor(Date.now() / 1000));
+
+    // Signature should be a hex string (40 characters for HMAC-SHA1)
+    expect(authenticationParameters.signature).toMatch(/^[a-f0-9]{40}$/);
+  });
+
+  it('should handle edge case with expire time 0', function () {
+    // When expire is 0, it's falsy, so the method uses default expire time
+    const authenticationParameters = client.helper.getAuthenticationParameters('test-token', 0);
+
+    expect(authenticationParameters.token).toBe('test-token');
+    // Since 0 is falsy, it should use the default expire (30 minutes from now)
+    const expectedExpire = Math.floor(Date.now() / 1000) + 60 * 30;
+    expect(authenticationParameters.expire).toBeCloseTo(expectedExpire, -1);
+    expect(authenticationParameters.signature).toMatch(/^[a-f0-9]{40}$/);
+  });
+
+  it('should handle empty string token', function () {
+    // When token is empty string, it's falsy, so the method generates a UUID
+    const authenticationParameters = client.helper.getAuthenticationParameters('', 1582269249);
+
+    // Since '' is falsy, it should generate a UUID
+    expect(authenticationParameters.token).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+    );
+    expect(authenticationParameters.expire).toBe(1582269249);
+    expect(authenticationParameters.signature).toMatch(/^[a-f0-9]{40}$/);
+  });
+});