@ranwhenparked/trustap-sdk 0.1.0 → 0.2.0

package/scripts/generate-security-map.mjs

@@ -1,92 +0,0 @@
-#!/usr/bin/env node
-// Generate a minimal security map from an OpenAPI document (JSON or YAML)
-// Usage: node scripts/generate-security-map.mjs [/absolute/or/relative/path/or/url]
-
-import fs from 'node:fs';
-import path from 'node:path';
-import process from 'node:process';
-import { fileURLToPath } from 'node:url';
-import { createRequire } from 'node:module';
-
-const require = createRequire(import.meta.url);
-let YAML;
-try {
-  YAML = require('yaml');
-} catch {}
-
-const inputArg = process.argv[2] || 'https://docs.trustap.com/_spec/apis/openapi.yaml';
-
-async function readOpenApi(source) {
-  if (/^https?:\/\//.test(source)) {
-    const res = await fetch(source);
-    if (!res.ok) throw new Error(`Failed to fetch ${source}: ${res.status}`);
-    const text = await res.text();
-    if (source.endsWith('.yaml') || source.endsWith('.yml')) {
-      if (!YAML) throw new Error('yaml package not available');
-      return YAML.parse(text);
-    }
-    return JSON.parse(text);
-  }
-  const content = fs.readFileSync(source, 'utf8');
-  if (source.endsWith('.yaml') || source.endsWith('.yml')) {
-    if (!YAML) throw new Error('yaml package not available');
-    return YAML.parse(content);
-  }
-  return JSON.parse(content);
-}
-
-function normalizeSecurityArray(secArr) {
-  // Convert OpenAPI security array to a set of scheme names
-  // e.g., [{ OAuth2: [] }, { APIKey: [] }] -> Set(['OAuth2','APIKey'])
-  const set = new Set();
-  if (Array.isArray(secArr)) {
-    for (const entry of secArr) {
-      if (entry && typeof entry === 'object') {
-        for (const key of Object.keys(entry)) set.add(key);
-      }
-    }
-  }
-  return set;
-}
-
-function buildSecurityMap(doc) {
-  const out = {}; // { path: { METHOD: ['APIKey','OAuth2'] } }
-  const globalSec = normalizeSecurityArray(doc.security);
-  const paths = doc.paths || {};
-  for (const p of Object.keys(paths)) {
-    const item = paths[p] || {};
-    for (const method of Object.keys(item)) {
-      const op = item[method];
-      if (!op || typeof op !== 'object') continue;
-      if (!['get','post','put','patch','delete','head','options','trace'].includes(method)) continue;
-      const opSec = normalizeSecurityArray(op.security);
-      const effective = opSec.size > 0 ? opSec : globalSec;
-      if (!out[p]) out[p] = {};
-      out[p][method.toUpperCase()] = Array.from(effective);
-    }
-  }
-  return out;
-}
-
-function emitTs(securityMap) {
-  const header = `// generated by scripts/generate-security-map.mjs\n`;
-  const body = `export const securityMap = ${JSON.stringify(securityMap, null, 2)} as const;\n`;
-  return header + body;
-}
-
-async function main() {
-  const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-  const outFile = path.join(rootDir, 'src', 'security-map.ts');
-  const api = await readOpenApi(inputArg);
-  const map = buildSecurityMap(api);
-  const ts = emitTs(map);
-  fs.writeFileSync(outFile, ts, 'utf8');
-  console.log(`Wrote ${outFile}`);
-}
-
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});
-
-

package/src/__tests__/auth-middleware.test.ts

@@ -1,171 +0,0 @@
-import { beforeEach, describe, expect, it, vi } 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,
-  encodeBasicAuth,
-  mockBasicAuth,
-  mockOAuthToken,
-  sampleCarrierFacilityRequest,
-  sampleChargeQuery,
-  sampleTransactionBody,
-} from "./helpers/test-fixtures.ts";
-import { runTrustapSuite } from "./helpers/run-guard.ts";
-
-runTrustapSuite(import.meta.url, "Auth Middleware", () => {
-  describe("Auth Middleware", () => {
-    let mockClient: MockHttpClient;
-
-    const createDeps = (): TrustapClientDependencies<
-      MockMiddleware,
-      MockHttpClient,
-      Record<string, unknown>
-    > => ({
-      createClient: () => mockClient,
-      wrapAsPathBasedClient: () => ({}),
-    });
-
-    const createClient = (
-      overrides?: Parameters<typeof createTestOptions>[0],
-    ) =>
-      createTrustapClientWithDeps(
-        createDeps(),
-        createTestOptions(overrides ?? {}),
-      );
-
-    beforeEach(() => {
-      mockClient = new MockHttpClient();
-    });
-
-    it("adds a Basic Authorization header when APIKey security is declared", async () => {
-      const client = createClient({ getAccessToken: undefined });
-
-      await client["basic.getCharge"]({
-        params: { query: sampleChargeQuery },
-      });
-
-      const header = mockClient.requests[0]?.request.headers.get(
-        "Authorization",
-      );
-      expect(header).toBe(
-        `Basic ${encodeBasicAuth(
-          mockBasicAuth.username,
-          mockBasicAuth.password,
-        )}`,
-      );
-    });
-
-    it("reuses the encoded Basic credentials for repeated calls", async () => {
-      const client = createClient({ getAccessToken: undefined });
-
-      await client["basic.getCharge"]({
-        params: { query: sampleChargeQuery },
-      });
-      await client["basic.getCharge"]({
-        params: { query: sampleChargeQuery },
-      });
-
-      const first = mockClient.requests[0]?.request.headers.get(
-        "Authorization",
-      );
-      const second = mockClient.requests[1]?.request.headers.get(
-        "Authorization",
-      );
-      expect(first).toBe(second);
-    });
-
-    it("requests bearer tokens for OAuth-protected endpoints", async () => {
-      const getAccessToken = vi.fn(() => Promise.resolve(mockOAuthToken));
-      const client = createClient({
-        basicAuth: undefined,
-        getAccessToken,
-      });
-
-      await client["oauth.getUser"]({
-        params: {
-          path: { userId: "user_123" },
-        },
-      });
-
-      const header = mockClient.requests[0]?.request.headers.get(
-        "Authorization",
-      );
-      expect(header).toBe(`Bearer ${mockOAuthToken}`);
-      expect(getAccessToken).toHaveBeenCalledTimes(1);
-    });
-
-    it("honors authOverrides using exact path matches", async () => {
-      const client = createClient({
-        authOverrides: {
-          "/transactions": "basic",
-        },
-      });
-
-      await client["basic.createTransaction"]({
-        body: sampleTransactionBody,
-      });
-
-      const header = mockClient.requests[0]?.request.headers.get(
-        "Authorization",
-      );
-      expect(header).toBe(
-        `Basic ${encodeBasicAuth(
-          mockBasicAuth.username,
-          mockBasicAuth.password,
-        )}`,
-      );
-    });
-
-    it("uses explicit OAuth overrides when provided", async () => {
-      const client = createClient({
-        authOverrides: {
-          "/transactions": "oauth2",
-        },
-        getAccessToken: () => Promise.resolve(mockOAuthToken),
-      });
-
-      await client["basic.createTransaction"]({
-        body: sampleTransactionBody,
-      });
-
-      const header = mockClient.requests[0]?.request.headers.get(
-        "Authorization",
-      );
-      expect(header).toBe(`Bearer ${mockOAuthToken}`);
-    });
-
-    it("does not override an Authorization header that is already present", async () => {
-      const client = createClient({ getAccessToken: undefined });
-
-      await client["basic.getCharge"]({
-        headers: { Authorization: "Custom token" },
-        params: { query: sampleChargeQuery },
-      });
-
-      const header = mockClient.requests[0]?.request.headers.get(
-        "Authorization",
-      );
-      expect(header).toBe("Custom token");
-    });
-
-    it("skips auth headers when no credentials are configured", async () => {
-      const client = createClient({
-        basicAuth: undefined,
-        getAccessToken: undefined,
-      });
-
-      await client["basic.getCarrierFacilityOptions"]({
-        params: { path: { carrier_id: "carrier_1" } },
-        body: sampleCarrierFacilityRequest,
-      });
-
-      const header = mockClient.requests[0]?.request.headers.get(
-        "Authorization",
-      );
-      expect(header).toBeNull();
-    });
-  });
-});

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

@@ -1,105 +0,0 @@
-import { beforeEach, describe, expect, it } 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,
-  encodeBasicAuth,
-  mockBasicAuth,
-  sampleChargeQuery,
-} from "./helpers/test-fixtures.ts";
-import { runTrustapSuite } from "./helpers/run-guard.ts";
-
-runTrustapSuite(import.meta.url, "Client Factory", () => {
-  describe("Client Factory", () => {
-    let mockClient: MockHttpClient;
-
-    const createDeps = (): TrustapClientDependencies<
-      MockMiddleware,
-      MockHttpClient,
-      { pathBased: MockHttpClient }
-    > => ({
-      createClient: () => mockClient,
-      wrapAsPathBasedClient: (client) => ({ pathBased: client }),
-    });
-
-    beforeEach(() => {
-      mockClient = new MockHttpClient();
-    });
-
-    it("creates a client that exposes operation-id functions", () => {
-      const client = createTrustapClientWithDeps(
-        createDeps(),
-        createTestOptions({ getAccessToken: undefined }),
-      );
-
-      expect(client).toBeDefined();
-      expect(typeof client["basic.getCharge"]).toBe("function");
-    });
-
-    it("routes requests using the generated operations map", async () => {
-      const client = createTrustapClientWithDeps(
-        createDeps(),
-        createTestOptions({ getAccessToken: undefined }),
-      );
-
-      await client["basic.getCharge"]({
-        params: { query: sampleChargeQuery },
-      });
-
-      expect(mockClient.requests).toHaveLength(1);
-      expect(mockClient.requests[0]?.path).toBe("/api/v4/charge");
-      expect(mockClient.requests[0]?.method).toBe("GET");
-    });
-
-    it("applies auth middleware sourced from the security map", async () => {
-      const client = createTrustapClientWithDeps(
-        createDeps(),
-        createTestOptions({ getAccessToken: undefined }),
-      );
-
-      await client["basic.getCharge"]({
-        params: { query: sampleChargeQuery },
-      });
-
-      const header = mockClient.requests[0]?.request.headers.get(
-        "Authorization",
-      );
-      expect(header).toBe(
-        `Basic ${encodeBasicAuth(
-          mockBasicAuth.username,
-          mockBasicAuth.password,
-        )}`,
-      );
-    });
-
-    it("exposes the underlying HTTP client via the raw property", () => {
-      const client = createTrustapClientWithDeps(
-        createDeps(),
-        createTestOptions({ getAccessToken: undefined }),
-      ) as { raw: MockHttpClient };
-
-      expect(client.raw).toBe(mockClient);
-    });
-
-    it("merges the path-based wrapper onto the returned client", () => {
-      const deps: TrustapClientDependencies<
-        MockMiddleware,
-        MockHttpClient,
-        { byPath: MockHttpClient }
-      > = {
-        createClient: () => mockClient,
-        wrapAsPathBasedClient: (client) => ({ byPath: client }),
-      };
-
-      const client = createTrustapClientWithDeps(
-        deps,
-        createTestOptions({ getAccessToken: undefined }),
-      ) as { byPath: MockHttpClient };
-
-      expect(client.byPath).toBe(mockClient);
-    });
-  });
-});

package/src/__tests__/error-handling.test.ts

@@ -1,302 +0,0 @@
-import { beforeEach, describe, expect, it } 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 } from "./helpers/test-fixtures.ts";
-import { runTrustapSuite } from "./helpers/run-guard.ts";
-
-const CHARGE_ENDPOINT = "/api/v4/charge";
-
-runTrustapSuite(import.meta.url, "Error Handling", () => {
-  describe("Error Handling", () => {
-    let mockClient: MockHttpClient;
-
-    const createDeps = (): TrustapClientDependencies<
-      MockMiddleware,
-      MockHttpClient,
-      Record<string, unknown>
-    > => ({
-      createClient: () => mockClient,
-      wrapAsPathBasedClient: () => ({}),
-    });
-
-    const createClient = (
-      overrides?: Parameters<typeof createTestOptions>[0],
-    ) =>
-      createTrustapClientWithDeps(
-        createDeps(),
-        createTestOptions(overrides ?? {}),
-      );
-
-    beforeEach(() => {
-      mockClient = new MockHttpClient();
-    });
-
-    describe("Network Failures", () => {
-      it("handles network errors when middleware throws", async () => {
-        const client = createClient({ getAccessToken: undefined });
-
-        // Simulate network failure by adding middleware that throws
-        mockClient.use({
-          onRequest: () => {
-            throw new Error("Network connection failed");
-          },
-        });
-
-        await expect(client["basic.getCharge"]()).rejects.toThrow(
-          "Network connection failed",
-        );
-      });
-
-      it("handles errors in response middleware", async () => {
-        const client = createClient({ getAccessToken: undefined });
-
-        mockClient.use({
-          onResponse: () => {
-            throw new Error("Response processing failed");
-          },
-        });
-
-        await expect(client["basic.getCharge"]()).rejects.toThrow(
-          "Response processing failed",
-        );
-      });
-    });
-
-    describe("HTTP Error Responses", () => {
-      it("returns error for 400 Bad Request", async () => {
-        const client = createClient({ getAccessToken: undefined });
-
-        mockClient.setResponse(CHARGE_ENDPOINT, "GET", {
-          error: { message: "Invalid parameters" },
-          status: 400,
-        });
-
-        const result = await client["basic.getCharge"]();
-
-        expect(result.error).toEqual({ message: "Invalid parameters" });
-        expect(result.data).toBeUndefined();
-        expect(result.response.status).toBe(400);
-      });
-
-      it("returns error for 401 Unauthorized", async () => {
-        const client = createClient({ getAccessToken: undefined });
-
-        mockClient.setResponse(CHARGE_ENDPOINT, "GET", {
-          error: { message: "Unauthorized" },
-          status: 401,
-        });
-
-        const result = await client["basic.getCharge"]();
-
-        expect(result.error).toEqual({ message: "Unauthorized" });
-        expect(result.data).toBeUndefined();
-        expect(result.response.status).toBe(401);
-      });
-
-      it("returns error for 403 Forbidden", async () => {
-        const client = createClient({ getAccessToken: undefined });
-
-        mockClient.setResponse(CHARGE_ENDPOINT, "GET", {
-          error: { message: "Forbidden" },
-          status: 403,
-        });
-
-        const result = await client["basic.getCharge"]();
-
-        expect(result.error).toEqual({ message: "Forbidden" });
-        expect(result.data).toBeUndefined();
-        expect(result.response.status).toBe(403);
-      });
-
-      it("returns error for 404 Not Found", async () => {
-        const client = createClient({ getAccessToken: undefined });
-
-        mockClient.setResponse(CHARGE_ENDPOINT, "GET", {
-          error: { message: "Not found" },
-          status: 404,
-        });
-
-        const result = await client["basic.getCharge"]();
-
-        expect(result.error).toEqual({ message: "Not found" });
-        expect(result.data).toBeUndefined();
-        expect(result.response.status).toBe(404);
-      });
-
-      it("returns error for 500 Internal Server Error", async () => {
-        const client = createClient({ getAccessToken: undefined });
-
-        mockClient.setResponse(CHARGE_ENDPOINT, "GET", {
-          error: { message: "Internal server error" },
-          status: 500,
-        });
-
-        const result = await client["basic.getCharge"]();
-
-        expect(result.error).toEqual({ message: "Internal server error" });
-        expect(result.data).toBeUndefined();
-        expect(result.response.status).toBe(500);
-      });
-
-      it("returns error for 503 Service Unavailable", async () => {
-        const client = createClient({ getAccessToken: undefined });
-
-        mockClient.setResponse(CHARGE_ENDPOINT, "GET", {
-          error: { message: "Service unavailable" },
-          status: 503,
-        });
-
-        const result = await client["basic.getCharge"]();
-
-        expect(result.error).toEqual({ message: "Service unavailable" });
-        expect(result.data).toBeUndefined();
-        expect(result.response.status).toBe(503);
-      });
-    });
-
-    describe("Malformed Responses", () => {
-      it("handles responses with invalid JSON", async () => {
-        const client = createClient({ getAccessToken: undefined });
-
-        // Mock a response that will fail JSON parsing
-        mockClient.use({
-          onResponse: () => {
-            return new Response("Invalid JSON {{{", {
-              status: 200,
-              headers: { "content-type": "application/json" },
-            });
-          },
-        });
-
-        const result = await client["basic.getCharge"]();
-
-        // Response should still be returned even if body parsing might fail later
-        expect(result.response).toBeInstanceOf(Response);
-        expect(result.response.status).toBe(200);
-      });
-
-      it("handles responses with missing content-type", async () => {
-        const client = createClient({ getAccessToken: undefined });
-
-        mockClient.use({
-          onResponse: () => {
-            return Response.json({ data: "test" }, {
-              status: 200,
-              // No content-type header
-            });
-          },
-        });
-
-        const result = await client["basic.getCharge"]();
-
-        expect(result.response).toBeInstanceOf(Response);
-        expect(result.response.status).toBe(200);
-      });
-
-      it("handles empty response bodies", async () => {
-        const client = createClient({ getAccessToken: undefined });
-
-        mockClient.use({
-          onResponse: () => {
-            return new Response(null, {
-              status: 204,
-              headers: { "content-type": "application/json" },
-            });
-          },
-        });
-
-        const result = await client["basic.getCharge"]();
-
-        expect(result.response).toBeInstanceOf(Response);
-        expect(result.response.status).toBe(204);
-      });
-    });
-
-    describe("Authentication Errors", () => {
-      it("handles OAuth token retrieval failures", async () => {
-        const client = createClient({
-          basicAuth: undefined,
-          getAccessToken: () =>
-            Promise.reject(new Error("Failed to get access token")),
-        });
-
-        await expect(
-          client["oauth.getUser"]({
-            params: { path: { userId: "user_123" } },
-          }),
-        ).rejects.toThrow("Failed to get access token");
-      });
-
-      it("continues when OAuth token is null or empty", async () => {
-        const client = createClient({
-          basicAuth: undefined,
-          getAccessToken: () => Promise.resolve(""),
-        });
-
-        // Should not throw, just proceed without auth header
-        const result = await client["oauth.getUser"]({
-          params: { path: { userId: "user_123" } },
-        });
-
-        expect(result.response).toBeInstanceOf(Response);
-
-        // Verify no Authorization header was set
-        const authHeader = mockClient.requests[0]?.request.headers.get(
-          "Authorization",
-        );
-        expect(authHeader).toBeNull();
-      });
-    });
-
-    describe("Path Parameter Errors", () => {
-      it("handles missing required path parameters", async () => {
-        const client = createClient({
-          basicAuth: undefined,
-          getAccessToken: () => Promise.resolve("token"),
-        });
-
-        // Call with missing userId parameter
-        await client["oauth.getUser"]({
-          params: { path: {} },
-        });
-
-        // Path should contain the unreplaced placeholder
-        const requestPath = mockClient.requests[0]?.path;
-        expect(requestPath).toContain("{userId}");
-      });
-
-      it("handles null path parameters", async () => {
-        const client = createClient({
-          basicAuth: undefined,
-          getAccessToken: () => Promise.resolve("token"),
-        });
-
-        await client["oauth.getUser"]({
-          params: { path: { userId: null } },
-        });
-
-        // Path should contain the unreplaced placeholder
-        const requestPath = mockClient.requests[0]?.path;
-        expect(requestPath).toContain("{userId}");
-      });
-
-      it("handles undefined path parameters", async () => {
-        const client = createClient({
-          basicAuth: undefined,
-          getAccessToken: () => Promise.resolve("token"),
-        });
-
-        await client["oauth.getUser"]({
-          params: { path: { userId: undefined } },
-        });
-
-        // Path should contain the unreplaced placeholder
-        const requestPath = mockClient.requests[0]?.path;
-        expect(requestPath).toContain("{userId}");
-      });
-    });
-  });
-});