@ranwhenparked/trustap-sdk 0.1.0

package/src/__tests__/helpers/mock-http-client.ts

@@ -0,0 +1,193 @@
+import type { MinimalHttpClient } from "../../core.ts";
+
+/**
+ * Middleware for intercepting and transforming HTTP requests and responses in tests.
+ *
+ * Contract:
+ * - `onRequest` MUST return a Request object (either the input request or a new one).
+ *   It MUST NOT return null/undefined or mutate the input request.
+ *   If middleware throws, the error bubbles up and fails the test.
+ *
+ * - `onResponse` MUST return a Response object (either the input response or a new one).
+ *   It MUST NOT return null/undefined or mutate the input response.
+ *   If middleware throws, the error bubbles up and fails the test.
+ *
+ * - Middleware can be synchronous or asynchronous (return Promise).
+ *
+ * - To skip processing, return the input request/response unchanged.
+ *
+ * Example:
+ * ```typescript
+ * const authMiddleware: MockMiddleware = {
+ *   onRequest: ({ request }) => {
+ *     const headers = new Headers(request.headers);
+ *     headers.set('Authorization', 'Bearer token');
+ *     return new Request(request, { headers });
+ *   }
+ * };
+ * ```
+ */
+export interface MockMiddleware {
+  onRequest?: (options: { request: Request }) => Request | Promise<Request>;
+  onResponse?: (options: {
+    request: Request;
+    response: Response;
+  }) => Response | Promise<Response>;
+}
+
+interface MockRequestRecord {
+  path: string;
+  method: string;
+  options?: unknown;
+  request: Request;
+  response: Response;
+}
+
+interface MockResult {
+  data?: unknown;
+  error?: unknown;
+  status?: number;
+  headers?: Record<string, string>;
+}
+
+const defaultResponse = (): Response =>
+  Response.json({ success: true }, {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+
+export class MockHttpClient implements MinimalHttpClient<MockMiddleware> {
+  private middleware: MockMiddleware[] = [];
+  private responses = new Map<string, MockResult>();
+  public requests: MockRequestRecord[] = [];
+
+  use(middleware: MockMiddleware): void {
+    this.middleware.push(middleware);
+  }
+
+  setResponse(path: string, method: string, result: MockResult): void {
+    this.responses.set(`${method.toUpperCase()}:${path}`, result);
+  }
+
+  private createRequestInit(method: string, options?: unknown): RequestInit {
+    const init: RequestInit = { method: method.toUpperCase() };
+    if (
+      options &&
+      typeof options === "object" &&
+      "headers" in (options as Record<string, unknown>)
+    ) {
+      const provided = (options as { headers?: HeadersInit }).headers;
+      if (provided) {
+        init.headers = new Headers(provided);
+      }
+    }
+    return init;
+  }
+
+  private async processRequestMiddleware(
+    request: Request,
+  ): Promise<Request> {
+    let processed = request;
+    for (const middleware of this.middleware) {
+      if (middleware.onRequest) {
+        const result = middleware.onRequest({ request: processed });
+        processed = result instanceof Promise ? await result : result;
+      }
+    }
+    return processed;
+  }
+
+  private buildMockResponse(
+    preset: MockResult | undefined,
+  ): Response {
+    if (!preset) {
+      return defaultResponse();
+    }
+    return Response.json(
+      preset.data ?? preset.error ?? { success: true },
+      {
+        status: preset.status ?? (preset.error ? 400 : 200),
+        headers: {
+          "content-type": "application/json",
+          ...preset.headers,
+        },
+      },
+    );
+  }
+
+  private async processResponseMiddleware(
+    request: Request,
+    response: Response,
+  ): Promise<Response> {
+    let processed = response;
+    for (const middleware of this.middleware) {
+      if (middleware.onResponse) {
+        const result = middleware.onResponse({
+          request,
+          response: processed,
+        });
+        processed = result instanceof Promise ? await result : result;
+      }
+    }
+    return processed;
+  }
+
+  private async dispatch(
+    path: string,
+    method: string,
+    options?: unknown,
+  ): Promise<{ data?: unknown; error?: unknown; response: Response }> {
+    const init = this.createRequestInit(method, options);
+    let request = new Request(`https://mock.local${path}`, init);
+    request = await this.processRequestMiddleware(request);
+
+    const key = `${method.toUpperCase()}:${path}`;
+    const preset = this.responses.get(key);
+    const response = this.buildMockResponse(preset);
+    const finalResponse = await this.processResponseMiddleware(request, response);
+
+    const record: MockRequestRecord = {
+      path,
+      method: method.toUpperCase(),
+      options,
+      request,
+      response: finalResponse,
+    };
+    this.requests.push(record);
+
+    // Return either data OR error, never both (matches real fetch client behavior)
+    if (preset?.error !== undefined) {
+      return {
+        error: preset.error,
+        response: finalResponse,
+      };
+    }
+
+    return {
+      data: preset?.data,
+      response: finalResponse,
+    };
+  }
+
+  GET(path: string, options?: unknown) {
+    return this.dispatch(path, "GET", options);
+  }
+  POST(path: string, options?: unknown) {
+    return this.dispatch(path, "POST", options);
+  }
+  PUT(path: string, options?: unknown) {
+    return this.dispatch(path, "PUT", options);
+  }
+  PATCH(path: string, options?: unknown) {
+    return this.dispatch(path, "PATCH", options);
+  }
+  DELETE(path: string, options?: unknown) {
+    return this.dispatch(path, "DELETE", options);
+  }
+  HEAD(path: string, options?: unknown) {
+    return this.dispatch(path, "HEAD", options);
+  }
+  OPTIONS(path: string, options?: unknown) {
+    return this.dispatch(path, "OPTIONS", options);
+  }
+}

package/src/__tests__/helpers/run-guard.ts

@@ -0,0 +1,24 @@
+import { describe } from "vitest";
+
+function containsNodeModules(url: string): boolean {
+  return url.includes("/node_modules/") || url.includes("\\node_modules\\");
+}
+
+export function runTrustapSuite(
+  moduleUrl: string,
+  suiteName: string,
+  callback: () => void,
+): void {
+  const shouldRun = !containsNodeModules(moduleUrl);
+
+  if (shouldRun) {
+    callback();
+  } else {
+    describe.skip(
+      suiteName,
+      () => {
+        // skipped when executed from a dependency context
+      },
+    );
+  }
+}

package/src/__tests__/helpers/test-fixtures.ts

@@ -0,0 +1,82 @@
+/* eslint-disable sonarjs/no-hardcoded-passwords */
+import type { CreateTrustapClientOptions } from "../../client-factory.ts";
+import type { operations } from "../../schema.d.ts";
+
+export const mockBasicAuth = {
+  username: "test_api_key",
+  password: "test_secret",
+} as const;
+
+export const mockOAuthToken = "test_oauth_token_abc123";
+
+export const sampleChargeQuery: operations["basic.getCharge"]["parameters"]["query"] =
+  {
+    price: 1234,
+    currency: "usd",
+  };
+
+export const sampleTransactionBody: operations["basic.createTransaction"]["requestBody"]["content"]["application/json"] =
+  {
+    charge: 250,
+    charge_calculator_version: 1,
+    charge_seller: 120,
+    currency: "usd",
+    description: "Test transaction",
+    price: 1234,
+    role: "buyer",
+  };
+
+export const sampleCarrierFacilityRequest: operations["basic.getCarrierFacilityOptions"]["requestBody"]["content"]["application/json"] =
+  {
+    country_code: "us",
+    delivery_type: "parcel_locker",
+    search_text: "Austin",
+  };
+
+export function createTestOptions(
+  overrides: Partial<CreateTrustapClientOptions> = {},
+): CreateTrustapClientOptions {
+  const hasBasicOverride = Object.prototype.hasOwnProperty.call(
+    overrides,
+    "basicAuth",
+  );
+  const hasTokenOverride = Object.prototype.hasOwnProperty.call(
+    overrides,
+    "getAccessToken",
+  );
+
+  return {
+    apiUrl: overrides.apiUrl ?? "https://test.trustap.com",
+    basicAuth: hasBasicOverride ? overrides.basicAuth : mockBasicAuth,
+    getAccessToken: hasTokenOverride
+      ? overrides.getAccessToken
+      : () => Promise.resolve(mockOAuthToken),
+    authOverrides: overrides.authOverrides,
+    basePath: overrides.basePath,
+  };
+}
+
+export function encodeBasicAuth(username: string, password: string): string {
+  const credentials = `${username}:${password}`;
+
+  // Use btoa if available (browser, Deno), otherwise use Buffer (Node)
+  if (typeof btoa !== "undefined") {
+    return btoa(credentials);
+  }
+
+  const bufferGlobal = (
+    globalThis as {
+      Buffer?: {
+        from: (input: string) => {
+          toString: (encoding: "base64") => string;
+        };
+      };
+    }
+  ).Buffer;
+
+  if (bufferGlobal) {
+    return bufferGlobal.from(credentials).toString("base64");
+  }
+
+  throw new Error("No base64 encoder available in this environment");
+}

package/src/__tests__/node-client.test.ts

@@ -0,0 +1,244 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { createTrustapClient } from "../index.ts";
+import type { TrustapClient } from "../index.ts";
+import { runTrustapSuite } from "./helpers/run-guard.ts";
+
+const TEST_USERNAME = "test_key";
+const TEST_PASSWORD = Buffer.from("test_secret").toString("base64");
+const TEST_ALT_PASSWORD = Buffer.from("secret").toString("base64");
+const TEST_URL = "https://test.trustap.com";
+const TEST_TOKEN = "test_token";
+
+// Helper functions for type validation tests
+function makeValidCall(client: TrustapClient) {
+  return client["basic.getCharge"]({
+    params: {
+      query: {
+        price: 1000,
+        currency: "usd",
+      },
+    },
+  });
+}
+
+function makeLegacyCall(client: TrustapClient) {
+  return client["basic.getCharge"]({
+    query: {
+      price: 2000,
+      currency: "eur",
+    },
+  });
+}
+
+function makeLegacyCallCompat(client: TrustapClient) {
+  return client["basic.getCharge"]({
+    query: { price: 1000, currency: "usd" },
+  });
+}
+
+function makeModernCallCompat(client: TrustapClient) {
+  return client["basic.getCharge"]({
+    params: {
+      query: { price: 1000, currency: "usd" },
+    },
+  });
+}
+
+runTrustapSuite(import.meta.url, "Node Client Integration", () => {
+  describe("Node Client Integration", () => {
+    let client: TrustapClient;
+
+    beforeEach(() => {
+      client = createTrustapClient({
+        apiUrl: TEST_URL,
+        basicAuth: {
+          username: TEST_USERNAME,
+          password: TEST_PASSWORD,
+        },
+      });
+    });
+
+    describe("Client Creation", () => {
+      it("should create a client with basic auth", () => {
+        expect(client).toBeDefined();
+        expect(typeof client["basic.getCharge"]).toBe("function");
+      });
+
+      it("should create a client with OAuth", () => {
+        const oauthClient = createTrustapClient({
+          apiUrl: TEST_URL,
+          getAccessToken: () => Promise.resolve(TEST_TOKEN),
+        });
+
+        expect(oauthClient).toBeDefined();
+      });
+
+      it("should create a client with auth overrides", () => {
+        const clientWithOverrides = createTrustapClient({
+          apiUrl: TEST_URL,
+          basicAuth: {
+            username: TEST_USERNAME,
+            password: TEST_PASSWORD,
+          },
+          authOverrides: {
+            "/custom": "basic",
+          },
+        });
+
+        expect(clientWithOverrides).toBeDefined();
+      });
+
+      it("should expose raw HTTP client", () => {
+        const rawClient = (client as { raw: unknown }).raw;
+        expect(rawClient).toBeDefined();
+        expect(typeof (rawClient as { GET: unknown }).GET).toBe("function");
+      });
+    });
+
+    describe("Operation Methods", () => {
+      it("should have operation methods from operationIdToPath", () => {
+        expect(typeof client["basic.getCharge"]).toBe("function");
+        expect(typeof client["basic.createTransaction"]).toBe("function");
+        expect(typeof client["oauth.getUser"]).toBe("function");
+        expect(typeof client["oauth.updateUser"]).toBe("function");
+      });
+
+      it("should return undefined for non-existent operations", () => {
+        const nonExistent = (client as Record<string, unknown>)[
+          "nonexistent.op"
+        ];
+        expect(nonExistent).toBeUndefined();
+      });
+    });
+
+    describe("TypeScript Types", () => {
+      it("should enforce correct parameter types at compile time", () => {
+        // This test verifies type safety through compilation
+        // If these type assertions pass TypeScript checking, types are correct
+
+        // Valid call with correct types
+        expect(makeValidCall).toBeDefined();
+        expect(() => makeValidCall(client)).not.toThrow();
+
+        // Legacy format should also be valid
+        expect(makeLegacyCall).toBeDefined();
+        expect(() => makeLegacyCall(client)).not.toThrow();
+      });
+
+      it("should return properly typed responses", () => {
+        // Mock the response at runtime since we don't have a real server
+        type ResponseType = Awaited<
+          ReturnType<(typeof client)["basic.getCharge"]>
+        >;
+        const mockResponse: ResponseType = {
+          data: {
+            charge: 250,
+            charge_calculator_version: 1,
+            charge_seller: 120,
+            currency: "usd",
+            price: 1234,
+          },
+          error: undefined,
+          response: Response.json({ id: "charge_123" }),
+        };
+
+        const response = mockResponse;
+
+        expect(response).toBeDefined();
+        expect(response.data).toBeDefined();
+        expect(response.response).toBeInstanceOf(Response);
+      });
+    });
+
+    describe("OpenAPI-Fetch Integration", () => {
+      it("should use openapi-fetch for HTTP requests", () => {
+        // The raw client should be an openapi-fetch client
+        const rawClient = (client as { raw: { GET: unknown } }).raw;
+        expect(typeof rawClient.GET).toBe("function");
+      });
+
+      it("should wrap client as path-based client", () => {
+        // Path-based access should work (from wrapAsPathBasedClient)
+        expect(client).toBeDefined();
+      });
+    });
+
+    describe("Middleware Application", () => {
+      it("should apply auth middleware for basic auth", () => {
+        const clientWithBasic = createTrustapClient({
+          apiUrl: TEST_URL,
+          basicAuth: {
+            username: "key",
+            password: TEST_ALT_PASSWORD,
+          },
+        });
+
+        // Middleware should be applied (verifiable through raw client)
+        const raw = (clientWithBasic as { raw: { use: unknown } }).raw;
+        expect(typeof raw.use).toBe("function");
+      });
+
+      it("should apply auth middleware for OAuth", () => {
+        const clientWithOAuth = createTrustapClient({
+          apiUrl: TEST_URL,
+          getAccessToken: () => Promise.resolve(TEST_TOKEN),
+        });
+
+        const raw = (clientWithOAuth as { raw: { use: unknown } }).raw;
+        expect(typeof raw.use).toBe("function");
+      });
+
+      it("should not apply middleware when no auth configured", () => {
+        const clientNoAuth = createTrustapClient({
+          apiUrl: TEST_URL,
+        });
+
+        expect(clientNoAuth).toBeDefined();
+      });
+    });
+
+    describe("Error Handling", () => {
+      it("should handle invalid API URLs gracefully", () => {
+        expect(() => {
+          createTrustapClient({
+            apiUrl: "",
+            basicAuth: { username: "test" },
+          });
+        }).not.toThrow();
+      });
+
+      it("should handle missing credentials gracefully", () => {
+        expect(() => {
+          createTrustapClient({
+            apiUrl: "https://test.trustap.com",
+          });
+        }).not.toThrow();
+      });
+    });
+
+    describe("Backward Compatibility", () => {
+      it("should support legacy query parameter format", () => {
+        expect(makeLegacyCallCompat).toBeDefined();
+        expect(() => makeLegacyCallCompat(client)).not.toThrow();
+      });
+
+      it("should support new params format", () => {
+        expect(makeModernCallCompat).toBeDefined();
+        expect(() => makeModernCallCompat(client)).not.toThrow();
+      });
+
+      it("should handle both formats interchangeably", () => {
+        // Both should be valid at runtime
+        const legacy = client["basic.getCharge"]({
+          query: { price: 1000, currency: "usd" },
+        });
+        const modern = client["basic.getCharge"]({
+          params: { query: { price: 1000, currency: "usd" } },
+        });
+
+        expect(legacy).toBeDefined();
+        expect(modern).toBeDefined();
+      });
+    });
+  });
+});