@secureport/sdk 0.5.0

package/src/client.ts

@@ -0,0 +1,328 @@
+import type { ErrorCode } from './errors.js';
+import {
+  FALLBACK_CODE_BY_STATUS,
+  RETRYABLE_STATUSES,
+  SecureportError,
+  SecureportNetworkError,
+} from './errors.js';
+import { BrandingResource } from './resources/branding.js';
+import { IssuesResource } from './resources/issues.js';
+import { ReportsResource } from './resources/reports.js';
+import { RunsResource } from './resources/runs.js';
+import { SuppressionRulesResource } from './resources/suppression-rules.js';
+import { TargetsResource } from './resources/targets.js';
+
+/**
+ * The narrow interface a resource (`targets`, and later `issues`/`runs`/
+ * `reports`) depends on — {@link SecureportClient.request} bound to its
+ * instance, not the whole client. Keeps a resource's own tests, if it ever
+ * needs its own, from having to construct a full client.
+ */
+export type Requester = <T = unknown>(input: RequestInput) => Promise<T>;
+
+/**
+ * The narrow interface {@link ReportsResource} depends on —
+ * {@link SecureportClient.requestRaw} bound to its instance, the same way
+ * {@link Requester} is {@link SecureportClient.request} bound.
+ */
+export type RawRequester = (input: RequestInput) => Promise<Response>;
+
+/** The `fetch` shape the transport needs — the global function satisfies it. */
+export type Fetch = typeof globalThis.fetch;
+
+/**
+ * What a `fetch` body may be — `RequestInit['body']` rather than the DOM
+ * lib's `BodyInit`, since `tsconfig.base.json`'s `lib` is `ES2023` only and
+ * does not carry that name; the global `RequestInit`/`Response` interfaces
+ * `@types/node` merges in are what `Fetch` itself already relies on.
+ */
+export type FetchBody = Exclude<RequestInit['body'], null | undefined>;
+
+/**
+ * What a client is constructed with.
+ *
+ * `apiKey` comes from wherever the caller reads it — this package takes no
+ * position on environment variables, unlike `@secureport/cli`'s hosted mode,
+ * which is a terminal program and can insist on one. A library has no
+ * terminal to insist to.
+ */
+export interface ClientOptions {
+  /** Sent as `Authorization: Bearer <apiKey>` on every request. */
+  readonly apiKey: string;
+
+  /** The API's base URL, with no trailing slash required. */
+  readonly baseUrl: string;
+
+  /** Overrides the transport's `fetch`. Defaults to the global. Tests use this. */
+  readonly fetch?: Fetch;
+
+  /**
+   * How many times a retryable response is retried before giving up.
+   *
+   * Sized for scan polling, not just upload-and-done calls: a hosted scan
+   * run can sit behind a busy queue for longer than an upload ever would, so
+   * the default favours patience over a fast failure.
+   *
+   * @defaultValue 4
+   */
+  readonly maxAttempts?: number;
+
+  /**
+   * How long a single attempt may take before it is aborted and treated as a
+   * network failure.
+   *
+   * @defaultValue 30_000
+   */
+  readonly timeoutMs?: number;
+}
+
+/** One HTTP call the transport makes. */
+export interface RequestInput {
+  /** e.g. `'GET'`, `'POST'`. */
+  readonly method: string;
+
+  /** Path only, e.g. `'/issues'` — joined onto {@link ClientOptions.baseUrl}. */
+  readonly path: string;
+
+  /** Sent as `?name=value`. A `undefined` value is omitted, not sent empty. */
+  readonly query?: Readonly<Record<string, string | number | boolean | undefined>>;
+
+  /** JSON-serialised and sent with `content-type: application/json`. Omitted entirely when absent. */
+  readonly body?: unknown;
+
+  /**
+   * A body sent exactly as given, with this `content-type` — never
+   * JSON-encoded. Mutually exclusive with {@link RequestInput.body}; used
+   * only by `runs.import()`, the one route that accepts a raw scanner
+   * artifact rather than a JSON payload.
+   */
+  readonly rawBody?: { readonly data: FetchBody; readonly contentType: string };
+}
+
+/** The API's one error envelope shape, read defensively — see {@link parseErrorBody}. */
+interface ErrorEnvelope {
+  readonly error: {
+    readonly code: string;
+    readonly message: string;
+    readonly requestId: string;
+  };
+}
+
+const DEFAULT_MAX_ATTEMPTS = 4;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const BASE_DELAY_MS = 500;
+const MAX_DELAY_MS = 8_000;
+
+/**
+ * The transport every resource client is built on: authentication, retry
+ * with backoff on the four statuses the API answers transiently with, and
+ * typed errors for everything else. Usable on its own via
+ * {@link SecureportClient.request}/{@link SecureportClient.requestRaw}
+ * without going through a resource.
+ */
+export class SecureportClient {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+  private readonly fetchImpl: Fetch;
+  private readonly maxAttempts: number;
+  private readonly timeoutMs: number;
+
+  /** Targets, and the per-target verification flow every hosted scan needs. */
+  readonly targets: TargetsResource;
+
+  /** Issues — the tracked entity findings reconcile into. */
+  readonly issues: IssuesResource;
+
+  /** Runs — one execution against a target, and the scan lifecycle around it. */
+  readonly runs: RunsResource;
+
+  /** Reports — rendering a run's snapshot into a document or a machine-readable export. */
+  readonly reports: ReportsResource;
+
+  /** Branding — the one record per organisation reports render with. */
+  readonly branding: BrandingResource;
+
+  /** Suppression rules — pre-emptive "never open an issue for this" globs. */
+  readonly suppressionRules: SuppressionRulesResource;
+
+  constructor(options: ClientOptions) {
+    this.apiKey = options.apiKey;
+    this.baseUrl = options.baseUrl.replace(/\/+$/u, '');
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    this.maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.targets = new TargetsResource(this.request.bind(this));
+    this.issues = new IssuesResource(this.request.bind(this));
+    this.runs = new RunsResource(this.request.bind(this));
+    this.reports = new ReportsResource(this.requestRaw.bind(this));
+    this.branding = new BrandingResource(this.request.bind(this));
+    this.suppressionRules = new SuppressionRulesResource(this.request.bind(this));
+  }
+
+  /**
+   * Makes one logical call, retrying transient failures internally. Resolves
+   * with the parsed JSON body, or `undefined` for a `204`.
+   *
+   * @throws {SecureportError} for any response the API answered with, after
+   * retries (if any) are exhausted.
+   * @throws {SecureportNetworkError} if no response was ever received.
+   */
+  async request<T = unknown>(input: RequestInput): Promise<T> {
+    const response = await this.requestRaw(input);
+    if (response.status === 204) return undefined as T;
+    return (await response.json()) as T;
+  }
+
+  /**
+   * The same authentication, retry-with-backoff and typed-error handling as
+   * {@link SecureportClient.request}, but without the JSON parse: resolves with the raw
+   * `Response` itself, for a route whose body is not JSON — currently just
+   * `reports.request()`, whose formats are streamed text (`text/csv`,
+   * `application/sarif+json`, …) rather than a parsed envelope.
+   *
+   * @throws {SecureportError} for any response the API answered with, after
+   * retries (if any) are exhausted.
+   * @throws {SecureportNetworkError} if no response was ever received.
+   */
+  async requestRaw(input: RequestInput): Promise<Response> {
+    const url = this.buildUrl(input.path, input.query);
+    const { headers, body } = requestBody(input);
+
+    for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+      const response = await this.attempt(url, input.method, headers, body);
+
+      if (RETRYABLE_STATUSES.has(response.status) && attempt < this.maxAttempts) {
+        await delay(retryDelayMs(response, attempt));
+        continue;
+      }
+
+      if (response.status >= 200 && response.status < 300) return response;
+
+      throw await toSecureportError(response);
+    }
+
+    // Unreachable while maxAttempts >= 1: the loop above always either
+    // returns or throws on its final iteration.
+    throw new Error('request() exhausted its attempts without a terminal response');
+  }
+
+  private async attempt(
+    url: string,
+    method: string,
+    headers: Readonly<Record<string, string>>,
+    body: FetchBody | undefined,
+  ): Promise<Response> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await this.fetchImpl(url, {
+        method,
+        headers: {
+          authorization: `Bearer ${this.apiKey}`,
+          accept: 'application/json',
+          ...headers,
+        },
+        ...(body === undefined ? {} : { body }),
+        signal: controller.signal,
+      });
+    } catch (error) {
+      throw new SecureportNetworkError(
+        `cannot reach ${this.baseUrl}: ${error instanceof Error ? error.message : String(error)}`,
+        error,
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  private buildUrl(path: string, query: RequestInput['query']): string {
+    const url = new URL(`${this.baseUrl}${path}`);
+    for (const [name, value] of Object.entries(query ?? {})) {
+      if (value !== undefined) url.searchParams.set(name, String(value));
+    }
+    return url.toString();
+  }
+}
+
+/** Constructs a {@link SecureportClient}. The package's one entry point. */
+export function createClient(options: ClientOptions): SecureportClient {
+  return new SecureportClient(options);
+}
+
+/** How long to wait before the next attempt, honouring `Retry-After` when the API sends one. */
+function retryDelayMs(response: Response, attempt: number): number {
+  const retryAfter = response.headers.get('retry-after');
+  if (retryAfter !== null) {
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+  }
+  return Math.min(BASE_DELAY_MS * 2 ** (attempt - 1), MAX_DELAY_MS);
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * The headers and body one request sends — {@link RequestInput.rawBody} wins
+ * when both it and {@link RequestInput.body} are given, though a resource
+ * method never sets both.
+ */
+function requestBody(input: RequestInput): {
+  headers: Readonly<Record<string, string>>;
+  body: FetchBody | undefined;
+} {
+  if (input.rawBody !== undefined) {
+    return { headers: { 'content-type': input.rawBody.contentType }, body: input.rawBody.data };
+  }
+  if (input.body !== undefined) {
+    return { headers: { 'content-type': 'application/json' }, body: JSON.stringify(input.body) };
+  }
+  return { headers: {}, body: undefined };
+}
+
+/**
+ * Builds the typed error for a terminal (non-retried, non-2xx) response.
+ *
+ * `502`/`504` are the edge answering for a dead or slow origin — the body is
+ * Cloudflare's, not this API's envelope — so those (and `429`, sent by this
+ * API but read defensively the same way) fall back to a status-derived code
+ * rather than assuming the body parses.
+ */
+async function toSecureportError(response: Response): Promise<SecureportError> {
+  const parsed = await parseErrorBody(response);
+  if (parsed !== undefined) {
+    return new SecureportError(
+      parsed.error.code as ErrorCode,
+      parsed.error.message,
+      response.status,
+      parsed.error.requestId,
+    );
+  }
+
+  const fallbackCode = FALLBACK_CODE_BY_STATUS[response.status];
+  return new SecureportError(
+    fallbackCode ?? 'internal',
+    fallbackCode === undefined
+      ? `the API answered ${String(response.status)} with a body this SDK could not read.`
+      : `the API answered ${String(response.status)} with no readable body — the edge, not the API itself.`,
+    response.status,
+  );
+}
+
+/** The response body as this API's error envelope, or `undefined` if it doesn't parse as one. */
+async function parseErrorBody(response: Response): Promise<ErrorEnvelope | undefined> {
+  try {
+    const body: unknown = await response.json();
+    if (typeof body !== 'object' || body === null || !('error' in body)) return undefined;
+
+    const error = body.error;
+    if (typeof error !== 'object' || error === null) return undefined;
+    if (!('code' in error) || !('message' in error)) return undefined;
+    if (typeof error.code !== 'string' || typeof error.message !== 'string') return undefined;
+
+    return body as ErrorEnvelope;
+  } catch {
+    return undefined;
+  }
+}

package/src/errors.ts

@@ -0,0 +1,120 @@
+/**
+ * Every error code the hosted API can answer with.
+ *
+ * Mirrored from `apps/api/src/errors.ts`'s `ERROR_CODES` rather than imported
+ * from it: `apps/api` is `"private": true` and pulls in Hono, drizzle and
+ * postgres, so a published package cannot depend on it. Kept honest by a
+ * drift assertion in `apps/api/tests/openapi.test.ts`, which compares this
+ * list against the live `/openapi.json` document's `Error` schema — the same
+ * technique that file already uses to keep `docs/api-endpoints.md` from
+ * drifting.
+ *
+ * The union is closed on purpose: a `switch` over {@link ErrorCode} is
+ * exhaustive, and adding a code here without the API test agreeing fails
+ * that test rather than shipping quietly out of sync.
+ */
+export const ERROR_CODES = [
+  'malformed',
+  'validation',
+  'unauthorized',
+  'payment_required',
+  'forbidden',
+  'not_entitled',
+  'org_deleted',
+  'terms_required',
+  'verification_required',
+  'not_found',
+  'method_not_allowed',
+  'not_acceptable',
+  'request_timeout',
+  'conflict',
+  'gone',
+  'precondition_failed',
+  'payload_too_large',
+  'uri_too_long',
+  'unsupported_media_type',
+  'misdirected_request',
+  'rate_limited',
+  'quota_exceeded',
+  'headers_too_large',
+  'internal',
+  'not_implemented',
+  'bad_gateway',
+  'unavailable',
+  'gateway_timeout',
+] as const;
+
+/** One of {@link ERROR_CODES}. What a caller branches on. */
+export type ErrorCode = (typeof ERROR_CODES)[number];
+
+/**
+ * The four statuses the transport retries with backoff, and nothing else.
+ *
+ * `terms_required` and `verification_required` both answer `403` — a settled
+ * refusal, not a transient one — so `403` is deliberately absent here even
+ * though it shares a status family with codes that could look retryable.
+ * Retrying an authorisation refusal would turn a clear "do this first" into a
+ * slow, confusing one.
+ */
+export const RETRYABLE_STATUSES: ReadonlySet<number> = new Set([429, 502, 503, 504]);
+
+/**
+ * The code a response is assumed to carry when its body cannot be read as
+ * this API's error envelope — which happens exactly on `502`/`504`, because
+ * those are the edge answering for a dead or slow origin and the body is
+ * Cloudflare's, not this API's. Each of the four statuses here maps to
+ * exactly one {@link ErrorCode}, so the fallback is unambiguous; no other
+ * status gets one; a `403` with an unparseable body, for instance, could be
+ * any of four different codes and none should be silently guessed.
+ */
+export const FALLBACK_CODE_BY_STATUS: Readonly<Partial<Record<number, ErrorCode>>> = {
+  429: 'rate_limited',
+  502: 'bad_gateway',
+  503: 'unavailable',
+  504: 'gateway_timeout',
+};
+
+/**
+ * Thrown for every non-2xx response the API returns, and for a response the
+ * transport gave up retrying.
+ *
+ * `requestId` is the same id the API's own `x-request-id` response header and
+ * error envelope carry, worth including in a support request. It is absent
+ * only when the body could not be read as this API's envelope at all (the
+ * `502`/`504` edge case above).
+ */
+export class SecureportError extends Error {
+  constructor(
+    /** What to branch on. */
+    readonly code: ErrorCode,
+    message: string,
+    /** The HTTP status the response actually carried. */
+    readonly status: number,
+    /** The API's `x-request-id` for this call, when the body could be read as its envelope. */
+    readonly requestId?: string,
+  ) {
+    super(message);
+    this.name = 'SecureportError';
+  }
+}
+
+/**
+ * Thrown when the request never reached a server at all — DNS failure,
+ * connection refused, TLS error. Distinct from {@link SecureportError}
+ * because there is no status and no code: nothing answered.
+ *
+ * Not retried by the transport. A network failure of this kind is usually a
+ * configuration problem (wrong `baseUrl`, no connectivity) rather than a
+ * transient one, and retrying it silently would turn a five-second failure
+ * into a much slower one for no better odds of success.
+ */
+export class SecureportNetworkError extends Error {
+  constructor(
+    message: string,
+    /** Whatever `fetch` itself threw or rejected with. */
+    readonly cause: unknown,
+  ) {
+    super(message);
+    this.name = 'SecureportNetworkError';
+  }
+}

package/src/index.ts

@@ -0,0 +1,100 @@
+/**
+ * The Secureport SDK.
+ *
+ * A typed client for the hosted API. Its types mirror `@secureport/core`'s
+ * domain model structurally rather than importing it — the wire always
+ * carries ISO 8601 date strings, never a `Date`, and this package depends on
+ * nothing at runtime. Authenticates with an API key, retries the four
+ * statuses the API answers transiently with, and throws a typed
+ * {@link SecureportError} for everything else.
+ *
+ * @packageDocumentation
+ */
+export type {
+  ClientOptions,
+  Fetch,
+  FetchBody,
+  RawRequester,
+  Requester,
+  RequestInput,
+} from './client.js';
+export { SecureportClient, createClient } from './client.js';
+export type { ErrorCode } from './errors.js';
+export { ERROR_CODES, SecureportError, SecureportNetworkError } from './errors.js';
+export type { Page, PageQuery } from './pagination.js';
+export { paginate } from './pagination.js';
+export type {
+  NewSuppressionRule,
+  SuppressionRule,
+  SuppressionRulePage,
+} from './resources/suppression-rules.js';
+export { SuppressionRulesResource } from './resources/suppression-rules.js';
+export type {
+  IssuedTargetVerification,
+  NewTarget,
+  NewTargetVerification,
+  Target,
+  TargetPage,
+  TargetPatch,
+  TargetVerification,
+  TargetVerificationCheckResult,
+  VerificationMethod,
+  VerificationState,
+} from './resources/targets.js';
+export { TargetsResource } from './resources/targets.js';
+export type {
+  Finding,
+  IgnoreInput,
+  IgnoreReason,
+  IgnoreScope,
+  Issue,
+  IssueComment,
+  IssueDetail,
+  IssueEvent,
+  IssueEventType,
+  IssueFilters,
+  IssueOrigin,
+  IssuePage,
+  IssuePatch,
+  IssueStatus,
+  NewIssue,
+  NewIssueComment,
+  ResolveInput,
+  Severity,
+} from './resources/issues.js';
+export { IssuesResource } from './resources/issues.js';
+export type {
+  ArtifactProcessingStatus,
+  CompleteRunImport,
+  Coverage,
+  FinishRunInput,
+  NewRun,
+  NewRunImport,
+  NewRunImportUrl,
+  Run,
+  RunArtifact,
+  RunArtifactList,
+  RunFilters,
+  RunKind,
+  RunPage,
+  RunStatus,
+  RunSummary,
+  RunTrigger,
+  RunUploadUrl,
+  ScanPhase,
+  ScanProgress,
+  ScanSize,
+  SeverityCounts,
+  WaitForArtifactOptions,
+  WaitUntilFinishedOptions,
+} from './resources/runs.js';
+export { RunsResource } from './resources/runs.js';
+export type {
+  EvidenceVerbosity,
+  ReportFormat,
+  ReportKind,
+  ReportRequest,
+} from './resources/reports.js';
+export { ReportsResource } from './resources/reports.js';
+export type { Branding } from './resources/branding.js';
+export { BrandingResource } from './resources/branding.js';

package/src/pagination.ts

@@ -0,0 +1,41 @@
+/**
+ * One page of `T`, as every list endpoint returns it — mirrors the wire shape
+ * `apps/api/src/http/pagination.ts`'s `pageSchema` defines.
+ */
+export interface Page<T> {
+  readonly data: readonly T[];
+
+  /** Rows matching the filters, across every page — not just this one. */
+  readonly total: number;
+
+  /** 1-based. */
+  readonly page: number;
+
+  readonly pageCount: number;
+}
+
+/** `?page=&limit=` — every list method takes this. */
+export interface PageQuery {
+  readonly page?: number;
+  readonly limit?: number;
+}
+
+/**
+ * Walks every page of a list endpoint, yielding items one at a time.
+ *
+ * `fetchPage(1)` is called first; the walk stops once a page's own `page`
+ * number reaches its `pageCount`, so a caller that only reads a few items
+ * from the front (`break`s out of a `for await`) never fetches pages it
+ * doesn't use.
+ */
+export async function* paginate<T>(
+  fetchPage: (page: number) => Promise<Page<T>>,
+): AsyncIterable<T> {
+  let page = 1;
+  for (;;) {
+    const result = await fetchPage(page);
+    yield* result.data;
+    if (page >= result.pageCount) return;
+    page++;
+  }
+}

package/src/resources/branding.ts

@@ -0,0 +1,59 @@
+import type { Requester } from '../client.js';
+
+/**
+ * Your reports' branding — company name, colour, logo, watermark and the
+ * details printed in the footer. One record per organisation; there is no
+ * id and no collection, because a second one is not a thing that can exist.
+ *
+ * No date fields appear here — nothing about this record is time-ordered —
+ * so unlike other resources' wire types, there is no ISO-string-vs-`Date`
+ * distinction to document.
+ */
+export interface Branding {
+  readonly companyName?: string;
+  readonly primaryColour?: string;
+  readonly whiteLabel?: boolean;
+  readonly watermark?: string;
+
+  /** A `data:` URI, at most 512 KiB. */
+  readonly logo?: string;
+  readonly companyDetails?: readonly string[];
+}
+
+/**
+ * Branding — the one record per organisation that reports render with. See
+ * {@link BrandingResource.replace} for why this is `PUT`, not `PATCH`.
+ */
+export class BrandingResource {
+  constructor(private readonly request: Requester) {}
+
+  /** @throws {SecureportError} `not_found` if no branding has been set. */
+  get(): Promise<Branding> {
+    return this.request({ method: 'GET', path: '/branding' });
+  }
+
+  /**
+   * Replaces your branding wholesale. Branding is one record, so this is
+   * `PUT` rather than `PATCH`: every field is optional, and a merge could
+   * not express "remove the logo" — omit a field and it is gone, not left
+   * as it was.
+   *
+   * @throws {SecureportError} `validation` if a field fails core's own
+   * check (a malformed colour, a logo that isn't a `data:` URI, or a
+   * disallowed `whiteLabel` combination) — not a shape problem, a meaning
+   * one, so it survives past normal request validation.
+   */
+  replace(input: Branding): Promise<Branding> {
+    return this.request({ method: 'PUT', path: '/branding', body: input });
+  }
+
+  /**
+   * Removes your branding; reports fall back to the unbranded default.
+   *
+   * @throws {SecureportError} `not_found` if nothing was set — removing
+   * twice is not a no-op, it tells you the second attempt changed nothing.
+   */
+  delete(): Promise<void> {
+    return this.request({ method: 'DELETE', path: '/branding' });
+  }
+}