Improve SDK robustness: signing path filtering, backoff jitter, input validation

Author: loookashow

src/config.ts

@@ -19,7 +19,9 @@ export const DEFAULT_RETRY_CONFIG: Readonly<RetryConfig> = {
   methods: ['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE'],
 };
 
-export const DEFAULT_USER_AGENT = 'foxnose-sdk-js/0.1.0';
+export const SDK_VERSION = '0.1.0';
+
+export const DEFAULT_USER_AGENT = `foxnose-sdk-js/${SDK_VERSION}`;
 
 /**
  * General transport-level configuration shared by all clients.

src/flux/client.ts

@@ -53,21 +53,21 @@ export class FluxClient {
     return suffix ? `${base}${suffix}` : base;
   }
 
-  async listResources(folderPath: string, params?: Record<string, any>): Promise<any> {
+  async listResources<T = any>(folderPath: string, params?: Record<string, any>): Promise<T> {
     const path = this.buildPath(folderPath);
     return this.transport.request('GET', path, { params });
   }
 
-  async getResource(
+  async getResource<T = any>(
     folderPath: string,
     resourceKey: string,
     params?: Record<string, any>,
-  ): Promise<any> {
+  ): Promise<T> {
     const path = this.buildPath(folderPath, `/${resourceKey}`);
     return this.transport.request('GET', path, { params });
   }
 
-  async search(folderPath: string, body: Record<string, any>): Promise<any> {
+  async search<T = any>(folderPath: string, body: Record<string, any>): Promise<T> {
     const path = this.buildPath(folderPath, '/_search');
     return this.transport.request('POST', path, { jsonBody: body });
   }

src/http.ts

@@ -95,7 +95,7 @@ export class HttpTransport {
     const requestData: RequestData = {
       method: method.toUpperCase(),
       url,
-      path: path + (options?.params ? `?${new URLSearchParams(options.params as Record<string, string>).toString()}` : ''),
+      path: this.buildSigningPath(path, options?.params),
       body,
     };
 
@@ -113,6 +113,20 @@ export class HttpTransport {
     return { url, init, body };
   }
 
+  private buildSigningPath(path: string, params?: Record<string, any>): string {
+    if (!params || Object.keys(params).length === 0) {
+      return path;
+    }
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== undefined && value !== null) {
+        searchParams.append(key, String(value));
+      }
+    }
+    const qs = searchParams.toString();
+    return qs ? `${path}?${qs}` : path;
+  }
+
   private shouldRetry(method: string, statusCode: number): boolean {
     if (!this.retry.methods.includes(method.toUpperCase())) {
       return false;
@@ -128,7 +142,8 @@ export class HttpTransport {
       }
       return 0;
     }
-    return this.retry.backoffFactor * Math.pow(2, Math.max(attempt - 1, 0)) * 1000;
+    const base = this.retry.backoffFactor * Math.pow(2, Math.max(attempt - 1, 0)) * 1000;
+    return base * (0.5 + Math.random() * 0.5);
   }
 
   private async maybeDecodeResponse(response: Response, parseJson: boolean): Promise<any> {

src/index.ts

@@ -10,7 +10,7 @@ export type { AuthStrategy, RequestData, TokenProvider } from './auth/index.js';
 
 // Config
 export type { FoxnoseConfig, RetryConfig } from './config.js';
-export { createConfig, DEFAULT_RETRY_CONFIG, DEFAULT_USER_AGENT } from './config.js';
+export { createConfig, DEFAULT_RETRY_CONFIG, DEFAULT_USER_AGENT, SDK_VERSION } from './config.js';
 
 // Errors
 export {
@@ -75,6 +75,11 @@ export type {
   PlanDetails,
   OrganizationPlanStatus,
   OrganizationUsage,
+  UnitsUsage,
+  StorageUsage,
+  UsageMetric,
+  UsageBreakdown,
+  CurrentUsage,
   BatchUpsertItem,
   BatchItemError,
   BatchUpsertResult,
@@ -96,4 +101,4 @@ export type {
 
 export { resolveKey } from './management/models.js';
 
-export const VERSION = '0.1.0';
+export { SDK_VERSION as VERSION } from './config.js';

src/management/paths.ts

@@ -15,10 +15,8 @@ export function managementPaths(environmentKey: string) {
       `/organizations/${orgKey}/projects/${projectKey}/environments/${envKey}`,
 
     // Folder paths
-    foldersRoot: () => `/v1/${environmentKey}/folders`,
     foldersTreeRoot: () => `/v1/${environmentKey}/folders/tree`,
     foldersTreeItem: () => `/v1/${environmentKey}/folders/tree/folder`,
-    folderRoot: (folderKey: string) => `/v1/${environmentKey}/folders/${folderKey}`,
     folderVersionsBase: (folderKey: string) =>
       `/v1/${environmentKey}/folders/${folderKey}/model/versions`,
     folderSchemaTree: (folderKey: string, versionKey: string) =>

tests/http.test.ts

@@ -345,6 +345,27 @@ describe('HttpTransport', () => {
     expect(url).not.toContain('c=');
   });
 
+  it('signing path filters null/undefined params same as URL', async () => {
+    let capturedPath = '';
+    const auth = {
+      buildHeaders: (req: any) => {
+        capturedPath = req.path;
+        return {};
+      },
+    };
+    const fetchMock = mockFetch([{ status: 200, body: {} }]);
+    globalThis.fetch = fetchMock;
+
+    const transport = new HttpTransport({ config: baseConfig, auth });
+    await transport.request('GET', '/test', {
+      params: { a: 'yes', b: null, c: undefined },
+    });
+
+    expect(capturedPath).toBe('/test?a=yes');
+    expect(capturedPath).not.toContain('null');
+    expect(capturedPath).not.toContain('undefined');
+  });
+
   it('handles non-JSON error response body', async () => {
     globalThis.fetch = vi.fn(async () =>
       new Response('Plain text error', { status: 500 }),

tests/management/paths.test.ts

@@ -28,18 +28,10 @@ describe('managementPaths', () => {
     );
   });
 
-  it('foldersRoot', () => {
-    expect(paths.foldersRoot()).toBe('/v1/env-abc/folders');
-  });
-
   it('foldersTreeRoot', () => {
     expect(paths.foldersTreeRoot()).toBe('/v1/env-abc/folders/tree');
   });
 
-  it('folderRoot', () => {
-    expect(paths.folderRoot('f1')).toBe('/v1/env-abc/folders/f1');
-  });
-
   it('folderVersionsBase', () => {
     expect(paths.folderVersionsBase('f1')).toBe('/v1/env-abc/folders/f1/model/versions');
   });