## Requirements
- [Node.js](https://nodejs.org/en/) v20 or higher
## Getting Started
This package is available in the Node Package Repository and can be easily installed with [npm](https://docs.npmjs.com/getting-started/what-is-npm) or [yarn](https://yarnpkg.com).
```bash
$ npm i @nodesecure/ossf-scorecard-sdk
# or
$ yarn add @nodesecure/ossf-scorecard-sdk
```
## Usage example
```ts
import * as scorecard from "@nodesecure/ossf-scorecard-sdk";
const data = await scorecard.result("NodeSecure/scanner");
console.log(data);
```
You can provide either **GitHub** (`github.com`), **GitHub Enterprise Server (GHES)** (`github.corp.com`) or **GitLab** (`gitlab.com`) platform with the options payload:
```ts
const data = await scorecard.result("gitlab-org/gitlab-ui", {
platform: "gitlab.com", // default to github.com
});
console.log(data);
```
You can provide a NPM library:
```ts
const data = await scorecard.result("@nodesecure/scanner");
console.log(data);
```
You can disable `resolveOnNpmRegistry` option which is `true` by default.
> [!TIP]
> You can disable version control resolve when you are sure the given repository is well formatted using `resolveOnVersionControl: false`.
> This can save you from GitHub/GitLab rate limit when working with lots of repositories.
```ts
const data = await scorecard.result("NodeSecure/scanner", {
resolveOnNpmRegistry: false, // default to true
});
console.log(data);
```
Options are described with the following TypeScript interface:
```ts
export interface ResultOptions {
/**
* @description VCS platform. eg. github.com
* @default github.com
*/
platform?: "github.com" | "github.corp.com" | "gitlab.com";
/**
* @description Try to resolve the given repository on the NPM registry if its not found on the given platform.
* @default true
*/
resolveOnNpmRegistry?: boolean;
/**
* @description Try to resolve the given repository on the given platform. This can be useful when the given repository
* is not exactly the same as the one on the given platform (case sensitive).
* @default true
*/
resolveOnVersionControl?: boolean;
/**
* @description The version of the npm package (when `resolveOnNpmRegistry` only) to retrieve the scorecard for.
* @default "latest"
*/
npmPackageVersion?: string;
}
```
## API
### result(repository: string, options?: ResultOptions): Promise< ScorecardResult >
> [!TIP]
> You can use `GITHUB_TOKEN` environment variable to avoid rate-limit when `resolveOnVersionControl` is true.
Return the OpenSSF ScorecardResult for a given organization and repository.
The response is typed using the following set of types:
```ts
export type ScorecardCheck = {
name: string;
score: number;
reason: string;
details: null | string[];
documentation: {
short: string;
url: string;
};
};
export type ScorecardResult = {
date: string;
metadata: string;
repo: {
name: string;
commit: string;
};
scorecard: {
version: string;
commit: string;
};
score: number;
checks: ScorecardCheck[];
};
```
### badge(repository: string, options?: BadgeOptions): Promise< BadgeResult >
Return a string URL to the badge image of a given organization and repository.
The badge method has an additional `style` options.
```ts
export interface BadgeOptions extends ResultOptions {
/**
* Style to render the badge
*
* @default flat
*/
style?: "plastic" | "flat" | "flat-square" | "for-the-badge" | "social";
}
```
Then the response is described by the `BadgeResult` interface:
```ts
export interface BadgeResult {
/**
* HTTPS link to shields.io
*
* @example
* https://img.shields.io/ossf-scorecard/github.com/NodeSecure/scanner?label=openssf%20scorecard&style=flat
*/
image: string;
/**
* HTML SVG balise
*/
svg: string;
}
```
## Contributors ✨
[](#contributors-)
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
