Documentation - Getting Started - API Reference - Feedback

The official dependency-free TypeScript SDK for the Hardcore security scanning API. It provides typed access to repositories, scanner configuration, scans, findings, and triage from Node.js 18+ and modern browsers.

Documentation

• Hardcore repository — server, dashboard, scanner adapters, and deployment configuration.
• GraphQL schema — authoritative API schema.
• Source — client implementation and public TypeScript models.

Getting started

Installation

Using npm:

npm install @hardcore.cloud/sdk

Using yarn:

yarn add @hardcore.cloud/sdk

Using pnpm:

pnpm add @hardcore.cloud/sdk

Configure the SDK

Create one client for your Hardcore API, API key, and team:

import { HardcoreClient } from '@hardcore.cloud/sdk';

const hardcore = new HardcoreClient({
  baseUrl: 'https://api.example.com/graphql',
  apiKey: process.env.HARDCORE_API_KEY,
  teamId: 'your-team-id',
});

The default URL is http://localhost:8000/graphql. Browsers and Node.js 18+ use the built-in Fetch API; alternative runtimes can provide a compatible fetch implementation through the constructor.

Start a scan

const repos = await hardcore.listRepos();

const scan = await hardcore.startScan({
  repoId: repos[0].id,
  ref: 'main',
  scannerKeys: ['semgrep', 'gitleaks'],
});

console.log(scan.id, scan.status);

Review and triage findings

const completed = await hardcore.getScan(scan.id);

for (const finding of completed?.findings ?? []) {
  console.log(finding.severity, finding.title, finding.file);

  if (finding.severity === 'critical') {
    await hardcore.triageFinding(finding.id, 'confirmed');
  }
}

Handle API errors

import { HardcoreApiError } from '@hardcore.cloud/sdk';

try {
  await hardcore.listRepos();
} catch (error) {
  if (error instanceof HardcoreApiError) {
    console.error(error.status, error.requestId, error.errors);
  }
}

API reference

Client

• new HardcoreClient(options) — configure the API URL, API key, team, headers, and Fetch implementation.
• request<T>(query, variables?, options?) — execute a typed custom GraphQL operation.
• me() and team() — retrieve the current identity and team.
• listRepos() and addRepo(input) — manage repositories.
• listScanners(), listScannerConfigs(), and configureScanner(input) — manage the scanner fleet.
• storeCredential(input) — store a write-only encrypted scanner credential.
• listScans(repoId?), getScan(id), startScan(input), and cancelScan(id) — manage scans.
• getFinding(id) and triageFinding(id, status) — review and triage findings.

All methods accept an optional { signal } argument for cancellation. JSON-backed GraphQL fields such as scanner schemas, scan totals, and transcript payloads are parsed into typed objects automatically.

Types

The package exports User, Team, Repo, ScannerDefinition, ScannerConfig, Scan, ScanStep, ScanEvent, Finding, Severity, ScanStatus, and TriageStatus.

Feedback

Contributing

We appreciate focused fixes and improvements. Run the SDK checks before opening a pull request:

npm test
npm run typecheck
npm run build

Publishing

The release scripts verify access to the npm hardcore.cloud organization, mirror the package version against npm, run the complete validation suite, publish publicly, commit the version bump, create an sdk-v<version> tag, and push the commit and tag. If publishing fails, the version files are restored automatically.

# Validate the exact package without publishing or changing its version
npm run release:dry

# Publish patch, minor, or major releases
npm run release:patch
npm run release:minor
npm run release:major

# Prerelease or explicit version
npm run release -- prerelease
npm run release -- 1.0.0-beta.1

Run npm login first, or configure an NPM_TOKEN in .npmrc. A real release requires a clean SDK package tree and membership in the npm hardcore.cloud organization. The @hardcore.cloud:developers team has publishing access.

Raise an issue

To report a bug or request an SDK feature, open an issue.

Vulnerability reporting

Please do not report security vulnerabilities through public issues. Use GitHub private vulnerability reporting.

This package is licensed under the MIT License.