@safeurl/sdk 1.0.0

package/src/client/types.gen.ts

@@ -0,0 +1,323 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type ClientOptions = {
+    baseUrl: `${string}://${string}` | (string & {});
+};
+
+export type GetHealthData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/health';
+};
+
+export type GetV1ApiKeysData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/v1/api-keys/';
+};
+
+export type GetV1ApiKeysErrors = {
+    /**
+     * Response for status 500
+     */
+    500: unknown;
+};
+
+export type GetV1ApiKeysResponses = {
+    /**
+     * Response for status 200
+     */
+    200: unknown;
+};
+
+export type PostV1ApiKeysData = {
+    body: unknown;
+    path?: never;
+    query?: never;
+    url: '/v1/api-keys/';
+};
+
+export type PostV1ApiKeysErrors = {
+    /**
+     * Response for status 500
+     */
+    500: unknown;
+};
+
+export type PostV1ApiKeysResponses = {
+    /**
+     * Response for status 201
+     */
+    201: unknown;
+};
+
+export type DeleteV1ApiKeysByIdData = {
+    body?: never;
+    path: {
+        id: string;
+    };
+    query?: never;
+    url: '/v1/api-keys/{id}';
+};
+
+export type DeleteV1ApiKeysByIdErrors = {
+    /**
+     * Response for status 400
+     */
+    400: unknown;
+    /**
+     * Response for status 404
+     */
+    404: unknown;
+    /**
+     * Response for status 500
+     */
+    500: unknown;
+};
+
+export type DeleteV1ApiKeysByIdResponses = {
+    /**
+     * Response for status 200
+     */
+    200: unknown;
+};
+
+export type GetV1ScansData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/v1/scans/';
+};
+
+export type GetV1ScansErrors = {
+    /**
+     * Insufficient scope (requires scan:read)
+     */
+    403: unknown;
+    /**
+     * Server error
+     */
+    500: unknown;
+};
+
+export type GetV1ScansResponses = {
+    /**
+     * List of scan jobs
+     */
+    200: unknown;
+};
+
+export type PostV1ScansData = {
+    body: unknown;
+    path?: never;
+    query?: never;
+    url: '/v1/scans/';
+};
+
+export type PostV1ScansResponses = {
+    /**
+     * Response for status 201
+     */
+    201: unknown;
+};
+
+export type PostV1ScansBatchData = {
+    body: unknown;
+    path?: never;
+    query?: never;
+    url: '/v1/scans/batch';
+};
+
+export type PostV1ScansBatchResponses = {
+    /**
+     * Response for status 201
+     */
+    201: unknown;
+};
+
+export type GetV1ScansByIdAnalyticsData = {
+    body?: never;
+    path: {
+        id: string;
+    };
+    query?: never;
+    url: '/v1/scans/{id}/analytics';
+};
+
+export type GetV1ScansByIdAnalyticsErrors = {
+    /**
+     * Insufficient scope (requires scan:read)
+     */
+    403: unknown;
+    /**
+     * Scan job not found
+     */
+    404: unknown;
+    /**
+     * Server error
+     */
+    500: unknown;
+};
+
+export type GetV1ScansByIdAnalyticsResponses = {
+    /**
+     * Scan analytics
+     */
+    200: unknown;
+};
+
+export type GetV1ScansByIdEventsData = {
+    body?: never;
+    path: {
+        id: string;
+    };
+    query?: never;
+    url: '/v1/scans/{id}/events';
+};
+
+export type GetV1ScansByIdEventsErrors = {
+    /**
+     * Insufficient scope (requires scan:read)
+     */
+    403: unknown;
+    /**
+     * Scan job not found
+     */
+    404: unknown;
+};
+
+export type GetV1ScansByIdEventsResponses = {
+    /**
+     * SSE stream
+     */
+    200: unknown;
+};
+
+export type GetV1ScansByIdData = {
+    body?: never;
+    path: {
+        id: string;
+    };
+    query?: never;
+    url: '/v1/scans/{id}';
+};
+
+export type GetV1ScansByIdErrors = {
+    /**
+     * Response for status 404
+     */
+    404: unknown;
+    /**
+     * Response for status 500
+     */
+    500: unknown;
+};
+
+export type GetV1ScansByIdResponses = {
+    /**
+     * Response for status 200
+     */
+    200: unknown;
+};
+
+export type GetV1CreditsData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/v1/credits/';
+};
+
+export type GetV1CreditsErrors = {
+    /**
+     * Response for status 500
+     */
+    500: unknown;
+};
+
+export type GetV1CreditsResponses = {
+    /**
+     * Response for status 200
+     */
+    200: unknown;
+};
+
+export type PostV1CreditsPurchaseData = {
+    body: unknown;
+    path?: never;
+    query?: never;
+    url: '/v1/credits/purchase';
+};
+
+export type PostV1CreditsPurchaseErrors = {
+    /**
+     * Response for status 400
+     */
+    400: unknown;
+    /**
+     * Response for status 402
+     */
+    402: unknown;
+    /**
+     * Response for status 500
+     */
+    500: unknown;
+};
+
+export type PostV1CreditsPurchaseResponses = {
+    /**
+     * Response for status 201
+     */
+    201: unknown;
+};
+
+export type GetV1SettingsData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/v1/settings/';
+};
+
+export type GetV1SettingsErrors = {
+    /**
+     * Response for status 404
+     */
+    404: unknown;
+    /**
+     * Response for status 500
+     */
+    500: unknown;
+};
+
+export type GetV1SettingsResponses = {
+    /**
+     * Response for status 200
+     */
+    200: unknown;
+};
+
+export type PutV1SettingsData = {
+    body: unknown;
+    path?: never;
+    query?: never;
+    url: '/v1/settings/';
+};
+
+export type PutV1SettingsErrors = {
+    /**
+     * Response for status 404
+     */
+    404: unknown;
+    /**
+     * Response for status 500
+     */
+    500: unknown;
+};
+
+export type PutV1SettingsResponses = {
+    /**
+     * Response for status 200
+     */
+    200: unknown;
+};

package/tests/client.unit.test.ts

@@ -0,0 +1,118 @@
+import { expect, mock, test } from "bun:test";
+
+import { createClient } from "../src/client/client";
+import { getHealth, postV1Scans } from "../src/client";
+
+function lastRequest(mockFetch: ReturnType<typeof mock>) {
+  const calls = mockFetch.mock.calls as unknown as [
+    input: RequestInfo | URL,
+    init?: RequestInit,
+  ][];
+  const [input, init] = calls[calls.length - 1]!;
+  if (input instanceof Request) {
+    return input;
+  }
+  return new Request(input, init);
+}
+
+test("getHealth issues GET to {baseUrl}/health with Authorization", async () => {
+  const fetchMock = mock((_input: RequestInfo | URL, _init?: RequestInit) =>
+    Promise.resolve(
+      new Response(
+        JSON.stringify({
+          status: "healthy",
+          service: "safeurl-api",
+          checks: {
+            database: { status: "healthy" },
+            queue: { status: "healthy" },
+          },
+        }),
+        {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        },
+      ),
+    ),
+  );
+
+  const client = createClient({
+    baseUrl: "https://api.example.com",
+    headers: {
+      Authorization: "Bearer sk_live_unit",
+    },
+    fetch: fetchMock as typeof fetch,
+  });
+
+  const result = await getHealth({ client });
+  expect(result.response.status).toBe(200);
+
+  const req = lastRequest(fetchMock);
+  expect(req.method).toBe("GET");
+  expect(req.url).toBe("https://api.example.com/health");
+  expect(req.headers.get("Authorization")).toBe("Bearer sk_live_unit");
+});
+
+test("createClient normalizes baseUrl trailing slash before requests", async () => {
+  const fetchMock = mock((_input: RequestInfo | URL, _init?: RequestInit) =>
+    Promise.resolve(
+      new Response(
+        JSON.stringify({
+          status: "healthy",
+          service: "safeurl-api",
+          checks: {
+            database: { status: "healthy" },
+            queue: { status: "healthy" },
+          },
+        }),
+        {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        },
+      ),
+    ),
+  );
+
+  const client = createClient({
+    baseUrl: "https://api.example.com/",
+    fetch: fetchMock as typeof fetch,
+  });
+
+  await getHealth({ client });
+  const req = lastRequest(fetchMock);
+  expect(req.url).toBe("https://api.example.com/health");
+});
+
+test("postV1Scans sends JSON body and Content-Type application/json", async () => {
+  const fetchMock = mock((_input: RequestInfo | URL, _init?: RequestInit) =>
+    Promise.resolve(
+      new Response(
+        JSON.stringify({
+          id: "00000000-0000-0000-0000-000000000001",
+          state: "QUEUED",
+        }),
+        {
+          status: 201,
+          headers: { "Content-Type": "application/json" },
+        },
+      ),
+    ),
+  );
+
+  const client = createClient({
+    baseUrl: "https://api.example.com",
+    headers: { Authorization: "Bearer sk_live_unit" },
+    fetch: fetchMock as typeof fetch,
+  });
+
+  const result = await postV1Scans({
+    client,
+    body: { url: "https://example.com" },
+  });
+  expect(result.response.status).toBe(201);
+
+  const req = lastRequest(fetchMock);
+  expect(req.method).toBe("POST");
+  expect(req.url).toBe("https://api.example.com/v1/scans/");
+  expect(req.headers.get("Content-Type")).toBe("application/json");
+  expect(await req.text()).toBe(JSON.stringify({ url: "https://example.com" }));
+});

package/tests/sdk-smoke.test.ts

@@ -0,0 +1,239 @@
+import { expect, test } from "bun:test";
+
+import { createClient } from "../src/client/client";
+import {
+  deleteV1ApiKeysById,
+  getHealth,
+  getV1ApiKeys,
+  getV1Credits,
+  getV1ScansById,
+  postV1ApiKeys,
+  postV1CreditsPurchase,
+  postV1Scans,
+} from "../src/client";
+
+type CreditsResponse = {
+  balance: number;
+  userId: string;
+  updatedAt: string;
+};
+
+type PurchaseCreditsResponse = {
+  id: string;
+  userId: string;
+  amount: number;
+  status: string;
+  createdAt: string;
+  completedAt: string;
+  newBalance: number;
+};
+
+type ScanResponse = {
+  id: string;
+  url: string;
+  state: "QUEUED" | "FETCHING" | "ANALYZING" | "COMPLETED" | "FAILED" | "TIMED_OUT";
+  createdAt: string;
+  updatedAt: string;
+};
+
+type CreateApiKeyResponse = {
+  id: string;
+  key: string;
+  name: string;
+  createdAt: string;
+};
+
+type ApiKeyListItem = {
+  id: string;
+  name: string;
+  scopes: string[];
+  expiresAt: string | null;
+  lastUsedAt: string | null;
+  createdAt: string;
+  revokedAt: string | null;
+};
+
+const baseUrl = process.env["SAFEURL_SDK_TEST_BASE_URL"] ?? "http://localhost:8081";
+const serviceSecret =
+  process.env["SAFEURL_SDK_TEST_SERVICE_SECRET"] ??
+  process.env["SAFEURL_SERVICE_SECRET"];
+const smoke = serviceSecret ? test : test.skip;
+
+smoke("bootstraps and uses a real API key", async () => {
+  if (!serviceSecret) {
+    return;
+  }
+
+  const serviceClient = createClient({
+    baseUrl,
+    headers: {
+      Authorization: `Bearer ${serviceSecret}`,
+    },
+  });
+
+  const health = await getHealth({
+    client: serviceClient,
+  });
+
+  expect(health.response.status).toBe(200);
+  expect(health.data).toMatchObject({
+    status: "healthy",
+    service: "safeurl-api",
+    checks: {
+      database: { status: "healthy" },
+      queue: { status: "healthy" },
+    },
+  });
+
+  let createdKey: CreateApiKeyResponse | undefined;
+  let revokeKey: CreateApiKeyResponse | undefined;
+
+  try {
+    const keyName = `ts-sdk-smoke-${Date.now()}`;
+    const createApiKeyResult = await postV1ApiKeys({
+      client: serviceClient,
+      body: {
+        name: keyName,
+        scopes: ["scan:read", "scan:write", "credits:read", "credits:write"],
+      },
+    });
+    expect(createApiKeyResult.response.status).toBe(201);
+    createdKey = createApiKeyResult.data as CreateApiKeyResponse;
+    expect(createdKey.id).toBeTruthy();
+    expect(createdKey.name).toBe(keyName);
+    expect(createdKey.key).toMatch(/^sk_live_/);
+
+    const apiKeyClient = createClient({
+      baseUrl,
+      headers: {
+        Authorization: `Bearer ${createdKey.key}`,
+      },
+    });
+
+    const apiKeyListResult = await getV1ApiKeys({
+      client: apiKeyClient,
+    });
+    expect(apiKeyListResult.response.status).toBe(200);
+    const apiKeyList = apiKeyListResult.data as ApiKeyListItem[];
+    expect(
+      apiKeyList.some((key) => key.id === createdKey?.id && key.name === keyName),
+    ).toBe(true);
+
+    const purchaseResult = await postV1CreditsPurchase({
+      client: serviceClient,
+      body: {
+        amount: 1,
+      },
+    });
+    expect(purchaseResult.response.status).toBe(201);
+    const purchase = purchaseResult.data as PurchaseCreditsResponse;
+    expect(purchase.amount).toBe(1);
+
+    const apiKeyCreditsResult = await getV1Credits({
+      client: apiKeyClient,
+    });
+    expect(apiKeyCreditsResult.response.status).toBe(200);
+    const apiKeyCredits = apiKeyCreditsResult.data as CreditsResponse;
+    expect(apiKeyCredits.balance).toBe(purchase.newBalance);
+
+    const revokeKeyName = `ts-sdk-revoke-${Date.now()}`;
+    const createRevokeKeyResult = await postV1ApiKeys({
+      client: serviceClient,
+      body: {
+        name: revokeKeyName,
+        scopes: ["scan:read", "credits:read"],
+      },
+    });
+    expect(createRevokeKeyResult.response.status).toBe(201);
+    revokeKey = createRevokeKeyResult.data as CreateApiKeyResponse;
+    expect(revokeKey.id).toBeTruthy();
+    expect(revokeKey.key).toMatch(/^sk_live_/);
+
+    const revokeClient = createClient({
+      baseUrl,
+      headers: {
+        Authorization: `Bearer ${revokeKey.key}`,
+      },
+    });
+
+    const revokePrecheck = await getV1Credits({
+      client: revokeClient,
+    });
+    expect(revokePrecheck.response.status).toBe(200);
+
+    const revokeResult = await deleteV1ApiKeysById({
+      client: apiKeyClient,
+      path: { id: revokeKey.id },
+    });
+    expect(revokeResult.response.status).toBe(200);
+    revokeKey = undefined;
+
+    const revokedCreditsResult = await getV1Credits({
+      client: revokeClient,
+    });
+    expect(revokedCreditsResult.response.status).toBe(401);
+
+    const unauthenticatedClient = createClient({ baseUrl });
+    const missingAuthResult = await getV1Credits({
+      client: unauthenticatedClient,
+    });
+    expect(missingAuthResult.response.status).toBe(401);
+
+    const invalidAuthClient = createClient({
+      baseUrl,
+      headers: {
+        Authorization: "Bearer sk_live_invalid_api_key",
+      },
+    });
+    const invalidAuthResult = await getV1Credits({
+      client: invalidAuthClient,
+    });
+    expect(invalidAuthResult.response.status).toBe(401);
+
+    const scanUrl = "https://example.com";
+    const createScanResult = await postV1Scans({
+      client: apiKeyClient,
+      body: {
+        url: scanUrl,
+      },
+    });
+    expect(createScanResult.response.status).toBe(201);
+
+    const createdScan = createScanResult.data as { id: string; state: "QUEUED" };
+    expect(createdScan.id).toBeTruthy();
+    expect(createdScan.state).toBe("QUEUED");
+
+    const scanResult = await getV1ScansById({
+      client: apiKeyClient,
+      path: { id: createdScan.id },
+    });
+    expect(scanResult.response.status).toBe(200);
+
+    const scan = scanResult.data as ScanResponse;
+    expect(scan.id).toBe(createdScan.id);
+    expect(scan.url).toBe(scanUrl);
+    expect([
+      "QUEUED",
+      "FETCHING",
+      "ANALYZING",
+      "COMPLETED",
+      "FAILED",
+      "TIMED_OUT",
+    ]).toContain(scan.state);
+    expect(scan.createdAt).toBeDefined();
+    expect(scan.updatedAt).toBeDefined();
+  } finally {
+    if (revokeKey?.id) {
+      await deleteV1ApiKeysById({
+        client: serviceClient,
+        path: { id: revokeKey.id },
+      });
+    }
+    if (createdKey?.id) {
+      await deleteV1ApiKeysById({
+        client: serviceClient,
+        path: { id: createdKey.id },
+      });
+    }
+  }
+}, 30_000);

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}