@ranwhenparked/trustap-sdk 0.1.0

package/src/__tests__/operation-proxy.test.ts

@@ -0,0 +1,268 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { createTrustapClientWithDeps } from "../client-factory.ts";
+import type { TrustapClientDependencies } from "../client-factory.ts";
+import { MockHttpClient } from "./helpers/mock-http-client.ts";
+import type { MockMiddleware } from "./helpers/mock-http-client.ts";
+import {
+  createTestOptions,
+  sampleChargeQuery,
+  sampleTransactionBody,
+} from "./helpers/test-fixtures.ts";
+import { runTrustapSuite } from "./helpers/run-guard.ts";
+
+const CHARGE_ENDPOINT = "/api/v4/charge";
+const TRANSACTIONS_ENDPOINT = "/api/v4/transactions";
+
+runTrustapSuite(import.meta.url, "Operation Proxy", () => {
+  describe("Operation Proxy", () => {
+    let mockClient: MockHttpClient;
+
+    beforeEach(() => {
+      mockClient = new MockHttpClient();
+    });
+
+    const createDeps = (): TrustapClientDependencies<
+      MockMiddleware,
+      MockHttpClient,
+      Record<string, unknown>
+    > => ({
+      createClient: () => mockClient,
+      wrapAsPathBasedClient: (client) => ({ pathBased: client }),
+    });
+
+  describe("Operation ID to HTTP Method Mapping", () => {
+    it("should map operation ID to GET request", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      );
+
+      mockClient.setResponse(CHARGE_ENDPOINT, "GET", {
+        data: { success: true },
+      });
+
+      await client["basic.getCharge"]({
+        params: { query: sampleChargeQuery },
+      });
+
+      expect(mockClient.requests).toHaveLength(1);
+      expect(mockClient.requests[0]?.method).toBe("GET");
+      expect(mockClient.requests[0]?.path).toBe(CHARGE_ENDPOINT);
+    });
+
+    it("should map operation ID to POST request", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      );
+
+      mockClient.setResponse(TRANSACTIONS_ENDPOINT, "POST", {
+        data: { success: true },
+      });
+
+      await client["basic.createTransaction"]({
+        body: sampleTransactionBody,
+      });
+
+      expect(mockClient.requests).toHaveLength(1);
+      expect(mockClient.requests[0]?.method).toBe("POST");
+      expect(mockClient.requests[0]?.path).toBe(TRANSACTIONS_ENDPOINT);
+    });
+
+    it("should map operation ID to PUT request", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      );
+
+      mockClient.setResponse(TRANSACTIONS_ENDPOINT, "PUT", {
+        data: { success: true },
+      });
+
+      await client["basic.joinTransaction"]({
+        params: { query: { join_code: "JOIN123" } },
+      });
+
+      expect(mockClient.requests).toHaveLength(1);
+      expect(mockClient.requests[0]?.method).toBe("PUT");
+      expect(mockClient.requests[0]?.path).toBe(TRANSACTIONS_ENDPOINT);
+    });
+  });
+
+  describe("HTTP Method Support", () => {
+    it("should support GET method", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      );
+
+      mockClient.setResponse(CHARGE_ENDPOINT, "GET", {
+        data: { success: true },
+      });
+
+      await client["basic.getCharge"]({
+        params: { query: sampleChargeQuery },
+      });
+
+      expect(mockClient.requests[0]?.method).toBe("GET");
+    });
+
+    it("should support POST method", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      );
+
+      mockClient.setResponse(TRANSACTIONS_ENDPOINT, "POST", {
+        data: { success: true },
+      });
+
+      await client["basic.createTransaction"]({
+        body: sampleTransactionBody,
+      });
+
+      expect(mockClient.requests[0]?.method).toBe("POST");
+    });
+
+    it("should support PUT method", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      );
+
+      mockClient.setResponse(TRANSACTIONS_ENDPOINT, "PUT", {
+        data: { success: true },
+      });
+
+      await client["basic.joinTransaction"]({
+        params: { query: { join_code: "JOIN123" } },
+      });
+
+      expect(mockClient.requests[0]?.method).toBe("PUT");
+    });
+
+    it("should support PATCH method", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      ) as unknown;
+
+      const rawClient = (client as { raw: MockHttpClient }).raw;
+      await rawClient.PATCH("/test", {});
+
+      const request = mockClient.requests.find((r) => r.method === "PATCH");
+      expect(request).toBeDefined();
+    });
+
+    it("should support DELETE method", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      ) as unknown;
+
+      const rawClient = (client as { raw: MockHttpClient }).raw;
+      await rawClient.DELETE("/test", {});
+
+      const request = mockClient.requests.find((r) => r.method === "DELETE");
+      expect(request).toBeDefined();
+    });
+
+    it("should support HEAD method", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      ) as unknown;
+
+      const rawClient = (client as { raw: MockHttpClient }).raw;
+      await rawClient.HEAD("/test", {});
+
+      const request = mockClient.requests.find((r) => r.method === "HEAD");
+      expect(request).toBeDefined();
+    });
+
+    it("should support OPTIONS method", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      ) as unknown;
+
+      const rawClient = (client as { raw: MockHttpClient }).raw;
+      await rawClient.OPTIONS("/test", {});
+
+      const request = mockClient.requests.find((r) => r.method === "OPTIONS");
+      expect(request).toBeDefined();
+    });
+  });
+
+  describe("Undefined Operation Handling", () => {
+    it("should return undefined for non-existent operation ID", () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      ) as Record<string, unknown>;
+
+      const nonExistent = client["nonexistent.operation"];
+
+      expect(nonExistent).toBeUndefined();
+    });
+
+    it("should not throw when accessing non-existent operation", () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      ) as Record<string, unknown>;
+
+      expect(() => {
+        const _ = client["another.fake.operation"];
+        return _;
+      }).not.toThrow();
+    });
+  });
+
+  describe("Proxy Behavior", () => {
+    it("should create operation functions dynamically", () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      );
+
+      const op1 = client["basic.getCharge"];
+      const op2 = client["basic.getCharge"];
+
+      // Should return the same function when accessed multiple times
+      expect(typeof op1).toBe("function");
+      expect(typeof op2).toBe("function");
+    });
+
+    it("should pass options through to HTTP client", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      );
+
+      mockClient.setResponse(TRANSACTIONS_ENDPOINT, "POST", {
+        data: { success: true },
+      });
+
+      const testOptions = {
+        body: sampleTransactionBody,
+      };
+
+      await client["basic.createTransaction"](testOptions);
+
+      expect(mockClient.requests).toHaveLength(1);
+      expect(mockClient.requests[0]?.options).toBeDefined();
+    });
+
+    it("should work with path-based client methods", () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      ) as unknown as { pathBased: unknown };
+
+      // Path-based client should be available
+      expect(client.pathBased).toBeDefined();
+    });
+  });
+});
+});

package/src/__tests__/query-params.test.ts

@@ -0,0 +1,232 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { createTrustapClientWithDeps } from "../client-factory.ts";
+import type { TrustapClientDependencies } from "../client-factory.ts";
+import { MockHttpClient } from "./helpers/mock-http-client.ts";
+import type { MockMiddleware } from "./helpers/mock-http-client.ts";
+import {
+  createTestOptions,
+  sampleChargeQuery,
+  sampleTransactionBody,
+} from "./helpers/test-fixtures.ts";
+import { runTrustapSuite } from "./helpers/run-guard.ts";
+
+const CHARGE_ENDPOINT = "/api/v4/charge";
+const TRANSACTIONS_ENDPOINT = "/api/v4/transactions";
+
+runTrustapSuite(import.meta.url, "Query Parameter Handling", () => {
+  describe("Query Parameter Handling", () => {
+    let mockClient: MockHttpClient;
+
+    beforeEach(() => {
+      mockClient = new MockHttpClient();
+    });
+
+    const createDeps = (): TrustapClientDependencies<
+      MockMiddleware,
+      MockHttpClient,
+      Record<string, unknown>
+    > => ({
+      createClient: () => mockClient,
+      wrapAsPathBasedClient: () => ({}),
+    });
+
+  describe("Legacy Format", () => {
+    it("should convert legacy { query: ... } format to new format", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      );
+
+      mockClient.setResponse(CHARGE_ENDPOINT, "GET", {
+        data: { success: true },
+      });
+
+      await client["basic.getCharge"]({
+        query: sampleChargeQuery,
+      } as Parameters<typeof client["basic.getCharge"]>[0]);
+
+      expect(mockClient.requests).toHaveLength(1);
+      const request = mockClient.requests[0];
+      expect(request?.path).toBe(CHARGE_ENDPOINT);
+      expect(request?.options).toBeDefined();
+    });
+
+    it("should handle legacy format with body", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      );
+
+      mockClient.setResponse(TRANSACTIONS_ENDPOINT, "POST", {
+        data: { success: true },
+      });
+
+      await client["basic.createTransaction"]({
+        query: sampleChargeQuery,
+        body: sampleTransactionBody,
+      } as unknown as Parameters<typeof client["basic.createTransaction"]>[0]);
+
+      expect(mockClient.requests).toHaveLength(1);
+      expect(mockClient.requests[0]?.options).toBeDefined();
+    });
+  });
+
+  describe("New Format", () => {
+    it("should handle { params: { query: ... } } format", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      );
+
+      mockClient.setResponse(CHARGE_ENDPOINT, "GET", {
+        data: { success: true },
+      });
+
+      await client["basic.getCharge"]({
+        params: {
+          query: sampleChargeQuery,
+        },
+      });
+
+      expect(mockClient.requests).toHaveLength(1);
+      const request = mockClient.requests[0];
+      expect(request?.options).toBeDefined();
+    });
+
+    it("should handle path parameters in params", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      );
+
+      mockClient.setResponse("/api/v4/users/user-123", "GET", {
+        data: { id: "user-123" },
+      });
+
+      await client["oauth.getUser"]({
+        params: {
+          path: { userId: "user-123" },
+        },
+      });
+
+      expect(mockClient.requests).toHaveLength(1);
+    });
+
+    it("should handle mixed query and path parameters", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      );
+
+      mockClient.setResponse("/api/v4/users/user-456", "GET", {
+        data: { id: "user-456" },
+      });
+
+      await client["oauth.getUser"]({
+        params: {
+          path: { userId: "user-456" },
+          query: sampleChargeQuery,
+        },
+      } as Parameters<typeof client["oauth.getUser"]>[0]);
+
+      expect(mockClient.requests).toHaveLength(1);
+    });
+
+    it("should handle body with new format", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      );
+
+      mockClient.setResponse("/api/v4/users/user-789", "PUT", {
+        data: { success: true },
+      });
+
+      await client["oauth.updateUser"]({
+        params: {
+          path: { userId: "user-789" },
+        },
+        body: {
+          email: "updated@example.com",
+        },
+      } as Parameters<typeof client["oauth.updateUser"]>[0]);
+
+      expect(mockClient.requests).toHaveLength(1);
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle empty query parameters", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      );
+
+      mockClient.setResponse(CHARGE_ENDPOINT, "GET", {
+        data: { success: true },
+      });
+
+      await client["basic.getCharge"]({
+        params: {
+          query: {},
+        },
+      } as Parameters<typeof client["basic.getCharge"]>[0]);
+
+      expect(mockClient.requests).toHaveLength(1);
+    });
+
+    it("should handle undefined options", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      );
+
+      mockClient.setResponse(CHARGE_ENDPOINT, "GET", {
+        data: { success: true },
+      });
+
+      await client["basic.getCharge"]();
+
+      expect(mockClient.requests).toHaveLength(1);
+    });
+
+    it("should handle options without query or params", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      );
+
+      mockClient.setResponse(TRANSACTIONS_ENDPOINT, "POST", {
+        data: { success: true },
+      });
+
+      await client["basic.createTransaction"]({
+        body: sampleTransactionBody,
+      });
+
+      expect(mockClient.requests).toHaveLength(1);
+    });
+
+    it("should not duplicate query params when converting", async () => {
+      const client = createTrustapClientWithDeps(
+        createDeps(),
+        createTestOptions({ getAccessToken: undefined }),
+      );
+
+      mockClient.setResponse(CHARGE_ENDPOINT, "GET", {
+        data: { success: true },
+      });
+
+      // Legacy format should be converted cleanly
+      await client["basic.getCharge"]({
+        query: sampleChargeQuery,
+      } as Parameters<typeof client["basic.getCharge"]>[0]);
+
+      expect(mockClient.requests).toHaveLength(1);
+      // Verify only one set of params exists (no duplication)
+      const options = mockClient.requests[0]?.options as Record<string, unknown> | undefined;
+      expect(options).toBeDefined();
+    });
+  });
+});
+});

package/src/__tests__/setup.ts

@@ -0,0 +1,44 @@
+import { afterAll, afterEach, beforeAll, vi } from "vitest";
+
+beforeAll(() => {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(() => Promise.resolve(new Response("{}", {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    }))),
+  );
+});
+
+// Per-test setup - clear mocks after each test to prevent state leakage
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+afterAll(() => {
+  vi.unstubAllGlobals();
+});
+
+// Test utilities
+export function createMockRequest(
+  url: string,
+  options?: RequestInit,
+): Request {
+  return new Request(url, options);
+}
+
+export function createMockResponse(
+  body?: unknown,
+  options?: ResponseInit,
+): Response {
+  const responseBody = body
+    ? JSON.stringify(body)
+    : undefined;
+  return new Response(responseBody, {
+    status: 200,
+    headers: {
+      "content-type": "application/json",
+    },
+    ...options,
+  });
+}

package/src/__tests__/types.test.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect, expectTypeOf } from "vitest";
+import { createTrustapClient } from "../index.ts";
+import type { operations } from "../schema.d.ts";
+import {
+  sampleChargeQuery,
+  sampleTransactionBody,
+} from "./helpers/test-fixtures.ts";
+import { runTrustapSuite } from "./helpers/run-guard.ts";
+
+const TEST_API_URL = "https://test.api";
+const TEST_CREDENTIALS_USERNAME = "test";
+const TEST_CREDENTIALS_PASSWORD = Buffer.from("test").toString("base64");
+
+runTrustapSuite(import.meta.url, "TypeScript Type Integration", () => {
+  describe("TypeScript Type Integration", () => {
+    describe("Operation Parameter Types", () => {
+      it("should extract proper parameter types from operations", () => {
+        const client = createTrustapClient({
+          apiUrl: TEST_API_URL,
+          basicAuth: { username: TEST_CREDENTIALS_USERNAME, password: TEST_CREDENTIALS_PASSWORD },
+        });
+
+        // Test that basic.getCharge has proper types
+        const chargeRequest = client["basic.getCharge"]({
+          params: {
+            query: {
+              price: 1000,
+              currency: "usd",
+            },
+          },
+        });
+
+        expect(chargeRequest).toBeDefined();
+      });
+
+      it("should support backward compatible legacy format", () => {
+        const client = createTrustapClient({
+          apiUrl: TEST_API_URL,
+          basicAuth: { username: TEST_CREDENTIALS_USERNAME, password: TEST_CREDENTIALS_PASSWORD },
+        });
+
+        // Test backward compatibility with legacy format
+        const chargeRequestLegacy = client["basic.getCharge"]({
+          query: sampleChargeQuery,
+        });
+
+        expect(chargeRequestLegacy).toBeDefined();
+      });
+    });
+
+    describe("Operation Type Assertions", () => {
+      it("should correctly type operation query parameters", () => {
+        // Type assertion tests
+        type BasicGetChargeOperation = operations["basic.getCharge"];
+        type QueryParams = BasicGetChargeOperation["parameters"]["query"];
+
+        // Ensure the types are correct at compile time
+        const validParams: QueryParams = {
+          price: 1000,
+          currency: "usd",
+        };
+
+        expect(validParams).toEqual({
+          price: 1000,
+          currency: "usd",
+        });
+      });
+
+      it("should enforce required parameters", () => {
+        type BasicGetChargeOperation = operations["basic.getCharge"];
+        type QueryParams = BasicGetChargeOperation["parameters"]["query"];
+
+        // This should compile if price and currency are required
+        const params: QueryParams = {
+          price: 2500,
+          currency: "gbp",
+        };
+
+        expect(params.price).toBe(2500);
+        expect(params.currency).toBe("gbp");
+      });
+    });
+
+    describe("Response Type Inference", () => {
+      it("should infer proper response types", () => {
+        const client = createTrustapClient({
+          apiUrl: TEST_API_URL,
+          basicAuth: { username: TEST_CREDENTIALS_USERNAME, password: TEST_CREDENTIALS_PASSWORD },
+        });
+
+        // Type should be inferred as Promise<{ data?: ..., error?: ..., response: Response }>
+        type ResponseType = ReturnType<(typeof client)["basic.getCharge"]>;
+        expectTypeOf<ResponseType>().toExtend<
+          Promise<{
+            data?: unknown;
+            error?: unknown;
+            response: Response;
+          }>
+        >();
+
+        // Verify it's a Promise
+        const isPromise = (value: unknown): value is Promise<unknown> =>
+          value instanceof Promise ||
+          (typeof value === "object" && value !== null && "then" in value);
+
+        const result = client["basic.getCharge"]();
+        expect(isPromise(result)).toBe(true);
+      });
+    });
+
+    describe("Path Parameter Types", () => {
+      it("should enforce path parameter types", () => {
+        const client = createTrustapClient({
+          apiUrl: TEST_API_URL,
+          getAccessToken: () => Promise.resolve("token"),
+        });
+
+        // userId should be properly typed
+        const userRequest = client["oauth.getUser"]({
+          params: {
+            path: {
+              userId: "user-123",
+            },
+          },
+        });
+
+        expect(userRequest).toBeDefined();
+      });
+    });
+
+    describe("Body Parameter Types", () => {
+      it("should enforce request body types", () => {
+        const client = createTrustapClient({
+          apiUrl: TEST_API_URL,
+          basicAuth: { username: TEST_CREDENTIALS_USERNAME, password: TEST_CREDENTIALS_PASSWORD },
+        });
+
+        // Body should be properly typed
+        const transactionRequest = client["basic.createTransaction"]({
+          body: sampleTransactionBody,
+        });
+
+        expect(transactionRequest).toBeDefined();
+      });
+    });
+
+    describe("Mixed Parameter Types", () => {
+      it("should handle operations with path, query, and body parameters", () => {
+        const client = createTrustapClient({
+          apiUrl: TEST_API_URL,
+          getAccessToken: () => Promise.resolve("token"),
+        });
+
+        // Should accept all parameter types
+        const updateRequest = client["oauth.updateUser"]({
+          params: {
+            path: {
+              userId: "user-456",
+            },
+            query: sampleChargeQuery,
+          },
+          body: sampleTransactionBody,
+        } as Parameters<(typeof client)["oauth.updateUser"]>[0]);
+
+        expect(updateRequest).toBeDefined();
+      });
+    });
+  });
+});