cwe-api-client 0.0.1 → 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,594 @@
+/**
+ * A related weakness reference within a CWE entry.
+ */
+interface CweRelatedWeakness {
+    /** Relationship nature (e.g. `'ChildOf'`, `'CanPrecede'`, `'PeerOf'`) */
+    Nature: string;
+    /** Related CWE identifier */
+    CweID: string;
+    /** View context for this relationship */
+    ViewID: string;
+    /** Ordinal designation (e.g. `'Primary'`) */
+    Ordinal?: string;
+}
+/**
+ * Weakness ordinality entry.
+ */
+interface CweWeaknessOrdinality {
+    /** Ordinality value (e.g. `'Resultant'`, `'Primary'`) */
+    Ordinality: string;
+}
+/**
+ * An applicable platform entry for a weakness.
+ */
+interface CweApplicablePlatform {
+    /** Platform type (e.g. `'Language'`, `'Technology'`, `'Operating System'`) */
+    Type: string;
+    /** Platform class (e.g. `'Not Language-Specific'`, `'Web Based'`) */
+    Class?: string;
+    /** Platform name (e.g. `'Java'`, `'AI/ML'`) */
+    Name?: string;
+    /** Prevalence (e.g. `'Often'`, `'Sometimes'`, `'Undetermined'`) */
+    Prevalence: string;
+}
+/**
+ * An alternate term or synonym for a weakness.
+ */
+interface CweAlternateTerm {
+    /** Alternate term string */
+    Term: string;
+    /** Description of when/how this term is used */
+    Description: string;
+}
+/**
+ * Full weakness entry returned by `GET /cwe/weakness/{id}`.
+ */
+interface CweWeakness {
+    /** CWE identifier string (e.g. `'79'`) */
+    ID: string;
+    /** Weakness name */
+    Name: string;
+    /** Abstraction level (e.g. `'Pillar'`, `'Class'`, `'Base'`, `'Variant'`) */
+    Abstraction: string;
+    /** Structure type (e.g. `'Simple'`, `'Composite'`, `'Chain'`) */
+    Structure: string;
+    /** Status (e.g. `'Stable'`, `'Draft'`, `'Incomplete'`, `'Deprecated'`) */
+    Status: string;
+    /** Path to a diagram image, if available */
+    Diagram?: string;
+    /** Short description of the weakness */
+    Description: string;
+    /** Extended description with additional details */
+    ExtendedDescription?: string;
+    /** Likelihood of exploitation (e.g. `'High'`, `'Medium'`, `'Low'`) */
+    LikelihoodOfExploit?: string;
+    /** References to related weaknesses */
+    RelatedWeaknesses?: CweRelatedWeakness[];
+    /** Ordinality of this weakness */
+    WeaknessOrdinalities?: CweWeaknessOrdinality[];
+    /** Platforms to which this weakness applies */
+    ApplicablePlatforms?: CweApplicablePlatform[];
+    /** Background context paragraphs */
+    BackgroundDetails?: string[];
+    /** Alternate names or terms for this weakness */
+    AlternateTerms?: CweAlternateTerm[];
+}
+
+/**
+ * A CWE entry as represented in hierarchy relationship responses.
+ */
+interface CweRelationEntry {
+    /** Entry type (e.g. `'pillar_weakness'`, `'class_weakness'`, `'view'`) */
+    Type: string;
+    /** CWE identifier string */
+    ID: string;
+    /** View context for this relationship */
+    ViewID: string;
+    /** Whether this is the primary parent (present on parent entries) */
+    Primary_Parent?: boolean;
+}
+/**
+ * A node in the ancestor tree returned by `GET /cwe/{id}/ancestors`.
+ * Each node references its parent chain recursively up to the view root.
+ */
+interface CweAncestorNode {
+    /** This node's CWE entry data */
+    Data: CweRelationEntry;
+    /** Parent nodes, or `null` if this node is the root */
+    Parents: CweAncestorNode[] | null;
+}
+/**
+ * A node in the descendant tree returned by `GET /cwe/{id}/descendants`.
+ * Each node references its children recursively down to leaf entries.
+ */
+interface CweDescendantNode {
+    /** This node's CWE entry data */
+    Data: CweRelationEntry;
+    /** Child nodes, or `null` if this node is a leaf */
+    Children: CweDescendantNode[] | null;
+}
+
+/** @internal */
+type RequestFn = <T>(path: string, params?: Record<string, string | number | boolean>) => Promise<T>;
+/**
+ * Represents a CWE weakness resource, providing access to weakness details
+ * and its position in the CWE hierarchy.
+ *
+ * Implements `PromiseLike<CweWeakness>` so it can be awaited directly to
+ * fetch the full weakness, while also exposing hierarchy methods.
+ *
+ * @example
+ * ```typescript
+ * // Await directly to get full weakness data
+ * const weakness = await cwe.weakness(79);
+ *
+ * // Or call .get() explicitly
+ * const weakness = await cwe.weakness(79).get();
+ *
+ * // Navigate the hierarchy
+ * const parents = await cwe.weakness(74).parents(1000);
+ * const children = await cwe.weakness(74).children(1000);
+ * const ancestors = await cwe.weakness(74).ancestors(1000);
+ * const descendants = await cwe.weakness(74).descendants(1000);
+ * ```
+ */
+declare class WeaknessResource implements PromiseLike<CweWeakness> {
+    private readonly request;
+    private readonly id;
+    /** @internal */
+    constructor(request: RequestFn, id: number);
+    /**
+     * Allows the resource to be awaited directly, resolving with the full weakness.
+     * Delegates to {@link WeaknessResource.get}.
+     */
+    then<TResult1 = CweWeakness, TResult2 = never>(onfulfilled?: ((value: CweWeakness) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * Fetches the full weakness entry.
+     *
+     * `GET /cwe/weakness/{id}`
+     *
+     * @returns The weakness object
+     */
+    get(): Promise<CweWeakness>;
+    /**
+     * Fetches the direct parents of this weakness in a given view.
+     *
+     * `GET /cwe/{id}/parents?view={viewId}`
+     *
+     * @param viewId - CWE view ID to scope the hierarchy (e.g. `1000`)
+     * @returns Array of direct parent entries
+     *
+     * @example
+     * ```typescript
+     * const parents = await cwe.weakness(74).parents(1000);
+     * ```
+     */
+    parents(viewId?: number): Promise<CweRelationEntry[]>;
+    /**
+     * Fetches the direct children of this weakness in a given view.
+     *
+     * `GET /cwe/{id}/children?view={viewId}`
+     *
+     * @param viewId - CWE view ID to scope the hierarchy (e.g. `1000`)
+     * @returns Array of direct child entries
+     *
+     * @example
+     * ```typescript
+     * const children = await cwe.weakness(74).children(1000);
+     * ```
+     */
+    children(viewId?: number): Promise<CweRelationEntry[]>;
+    /**
+     * Fetches the full ancestor tree of this weakness in a given view.
+     *
+     * `GET /cwe/{id}/ancestors?view={viewId}`
+     *
+     * @param viewId - CWE view ID to scope the hierarchy (e.g. `1000`)
+     * @returns Recursive ancestor tree from this node up to the view root
+     *
+     * @example
+     * ```typescript
+     * const tree = await cwe.weakness(74).ancestors(1000);
+     * ```
+     */
+    ancestors(viewId?: number): Promise<CweAncestorNode[]>;
+    /**
+     * Fetches the full descendant tree of this weakness in a given view.
+     *
+     * `GET /cwe/{id}/descendants?view={viewId}`
+     *
+     * @param viewId - CWE view ID to scope the hierarchy (e.g. `1000`)
+     * @returns Recursive descendant tree from this node down to leaf entries
+     *
+     * @example
+     * ```typescript
+     * const tree = await cwe.weakness(74).descendants(1000);
+     * ```
+     */
+    descendants(viewId?: number): Promise<CweDescendantNode[]>;
+}
+
+/**
+ * A taxonomy mapping entry linking a category to an external standard.
+ */
+interface CweTaxonomyMapping {
+    /** Name of the external taxonomy (e.g. `'SEI CERT Perl Coding Standard'`) */
+    TaxonomyName: string;
+    /** Entry identifier within the taxonomy */
+    EntryID?: string;
+    /** Entry name within the taxonomy */
+    EntryName: string;
+    /** How well the mapping fits (e.g. `'CWE More Abstract'`, `'Exact'`) */
+    MappingFit?: string;
+}
+/**
+ * A member relationship entry within a category.
+ */
+interface CweCategoryRelationship {
+    /** CWE identifier of the member */
+    CweID: string;
+    /** View context for this membership */
+    ViewID: string;
+}
+/**
+ * An external reference cited by a category.
+ */
+interface CweCategoryReference {
+    /** External reference identifier (e.g. `'REF-1287'`) */
+    ExternalReferenceID: string;
+}
+/**
+ * Full category entry returned by `GET /cwe/category/{id}`.
+ */
+interface CweCategory {
+    /** CWE identifier string (e.g. `'189'`) */
+    ID: string;
+    /** Category name */
+    Name: string;
+    /** Status (e.g. `'Draft'`, `'Stable'`, `'Deprecated'`) */
+    Status: string;
+    /** Short summary of what this category covers */
+    Summary: string;
+    /** Mappings to external taxonomies */
+    TaxonomyMappings?: CweTaxonomyMapping[];
+    /** Weaknesses that belong to this category */
+    Relationships?: CweCategoryRelationship[];
+    /** External references */
+    References?: CweCategoryReference[];
+}
+
+/**
+ * Represents a CWE category resource, providing access to category details.
+ *
+ * Implements `PromiseLike<CweCategory>` so it can be awaited directly.
+ *
+ * @example
+ * ```typescript
+ * // Await directly to get full category data
+ * const category = await cwe.category(189);
+ *
+ * // Or call .get() explicitly
+ * const category = await cwe.category(189).get();
+ * ```
+ */
+declare class CategoryResource implements PromiseLike<CweCategory> {
+    private readonly request;
+    private readonly id;
+    /** @internal */
+    constructor(request: RequestFn, id: number);
+    /**
+     * Allows the resource to be awaited directly, resolving with the full category.
+     * Delegates to {@link CategoryResource.get}.
+     */
+    then<TResult1 = CweCategory, TResult2 = never>(onfulfilled?: ((value: CweCategory) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * Fetches the full category entry.
+     *
+     * `GET /cwe/category/{id}`
+     *
+     * @returns The category object
+     */
+    get(): Promise<CweCategory>;
+}
+
+/**
+ * An audience entry describing who a view is relevant for.
+ */
+interface CweViewAudience {
+    /** Audience type (e.g. `'Software Developers'`, `'Educators'`) */
+    Type: string;
+    /** Description of how this view is relevant to this audience */
+    Description: string;
+}
+/**
+ * A member entry within a view.
+ */
+interface CweViewMember {
+    /** CWE identifier of the member */
+    CweID: string;
+    /** View identifier this membership belongs to */
+    ViewID: string;
+}
+/**
+ * Full view entry returned by `GET /cwe/view/{id}`.
+ */
+interface CweView {
+    /** CWE identifier string (e.g. `'1425'`) */
+    ID: string;
+    /** View name */
+    Name: string;
+    /** View type (e.g. `'Graph'`, `'Explicit'`, `'Implicit'`) */
+    Type: string;
+    /** Status (e.g. `'Draft'`, `'Stable'`, `'Deprecated'`) */
+    Status: string;
+    /** Objective description of the view */
+    Objective?: string;
+    /** Intended audiences for this view */
+    Audience?: CweViewAudience[];
+    /** CWE entries that are members of this view */
+    Members?: CweViewMember[];
+}
+
+/**
+ * Represents a CWE view resource, providing access to view details.
+ *
+ * Implements `PromiseLike<CweView>` so it can be awaited directly.
+ *
+ * @example
+ * ```typescript
+ * // Await directly to get full view data
+ * const view = await cwe.view(1425);
+ *
+ * // Or call .get() explicitly
+ * const view = await cwe.view(1425).get();
+ * ```
+ */
+declare class ViewResource implements PromiseLike<CweView> {
+    private readonly request;
+    private readonly id;
+    /** @internal */
+    constructor(request: RequestFn, id: number);
+    /**
+     * Allows the resource to be awaited directly, resolving with the full view.
+     * Delegates to {@link ViewResource.get}.
+     */
+    then<TResult1 = CweView, TResult2 = never>(onfulfilled?: ((value: CweView) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * Fetches the full view entry.
+     *
+     * `GET /cwe/view/{id}`
+     *
+     * @returns The view object
+     */
+    get(): Promise<CweView>;
+}
+
+/**
+ * CWE content version metadata returned by `GET /cwe/version`.
+ */
+interface CweVersion {
+    /** CWE content version string (e.g. `'4.19.1'`) */
+    ContentVersion: string;
+    /** Date the content was published (e.g. `'2026-01-21'`) */
+    ContentDate: string;
+    /** Total number of weaknesses in this release */
+    TotalWeaknesses: number;
+    /** Total number of categories in this release */
+    TotalCategories: number;
+    /** Total number of views in this release */
+    TotalViews: number;
+}
+
+/**
+ * CWE entry type string.
+ */
+type CweEntryType = 'pillar_weakness' | 'class_weakness' | 'base_weakness' | 'variant_weakness' | 'compound_element' | 'category' | 'view';
+/**
+ * Lightweight CWE entry returned by the multi-ID lookup endpoint
+ * (`GET /cwe/{ids}`).
+ */
+interface CweEntry {
+    /** CWE entry type (e.g. `'base_weakness'`, `'category'`, `'view'`) */
+    Type: CweEntryType;
+    /** CWE identifier string (e.g. `'79'`) */
+    ID: string;
+}
+
+/**
+ * Payload emitted on every HTTP request made by {@link CweClient}.
+ */
+interface RequestEvent {
+    /** Full URL that was requested */
+    url: string;
+    /** HTTP method used */
+    method: 'GET';
+    /** Timestamp when the request started */
+    startedAt: Date;
+    /** Timestamp when the request finished (success or error) */
+    finishedAt: Date;
+    /** Total duration in milliseconds */
+    durationMs: number;
+    /** HTTP status code returned by the server, if a response was received */
+    statusCode?: number;
+    /** Error thrown, if the request failed */
+    error?: Error;
+}
+/** Map of supported client events to their callback signatures */
+interface CweClientEvents {
+    request: (event: RequestEvent) => void;
+}
+/**
+ * Constructor options for {@link CweClient}.
+ */
+interface CweClientOptions {
+    /**
+     * Base URL for the CWE API (default: `'https://cwe-api.mitre.org/api/v1'`).
+     * Override for mirrors or local instances.
+     */
+    baseUrl?: string;
+}
+/**
+ * Main entry point for the MITRE CWE API client.
+ *
+ * @example
+ * ```typescript
+ * import { CweClient } from 'cwe-api-client';
+ *
+ * const cwe = new CweClient();
+ *
+ * // Get content version metadata
+ * const version = await cwe.version();
+ *
+ * // Look up multiple CWEs at once
+ * const entries = await cwe.lookup([74, 79]);
+ *
+ * // Get full weakness details
+ * const weakness = await cwe.weakness(79);
+ *
+ * // Navigate the hierarchy
+ * const parents = await cwe.weakness(74).parents(1000);
+ * const descendants = await cwe.weakness(74).descendants(1000);
+ *
+ * // Get category and view details
+ * const category = await cwe.category(189);
+ * const view = await cwe.view(1425);
+ * ```
+ */
+declare class CweClient {
+    private readonly baseUrl;
+    private readonly listeners;
+    /**
+     * @param options - Optional configuration for the API base URL
+     */
+    constructor(options?: CweClientOptions);
+    /**
+     * Subscribes to a client event.
+     *
+     * @example
+     * ```typescript
+     * cwe.on('request', (event) => {
+     *   console.log(`${event.method} ${event.url} — ${event.durationMs}ms`);
+     *   if (event.error) console.error('Request failed:', event.error);
+     * });
+     * ```
+     */
+    on<K extends keyof CweClientEvents>(event: K, callback: CweClientEvents[K]): this;
+    private emit;
+    /**
+     * Performs a GET request to the CWE API.
+     *
+     * @param path - Path to append to the base URL (e.g. `/cwe/version`)
+     * @param params - Optional query parameters
+     * @internal
+     */
+    request<T>(path: string, params?: Record<string, string | number | boolean>): Promise<T>;
+    /**
+     * Fetches CWE content version metadata.
+     *
+     * `GET /cwe/version`
+     *
+     * @returns Version metadata including content version, date, and counts
+     *
+     * @example
+     * ```typescript
+     * const v = await cwe.version();
+     * console.log(v.ContentVersion); // '4.19.1'
+     * console.log(v.TotalWeaknesses); // 969
+     * ```
+     */
+    version(): Promise<CweVersion>;
+    /**
+     * Looks up multiple CWE entries by their numeric IDs in a single request.
+     *
+     * `GET /cwe/{ids}` (comma-separated)
+     *
+     * @param ids - Array of CWE numeric IDs (e.g. `[74, 79]`)
+     * @returns Array of lightweight CWE entries with type and ID
+     *
+     * @example
+     * ```typescript
+     * const entries = await cwe.lookup([74, 79]);
+     * entries.forEach(e => console.log(e.ID, e.Type));
+     * ```
+     */
+    lookup(ids: number[]): Promise<CweEntry[]>;
+    /**
+     * Returns a {@link WeaknessResource} for a given CWE weakness ID, providing
+     * access to weakness details and its hierarchy (parents, children, ancestors,
+     * descendants).
+     *
+     * The returned resource can be awaited directly to fetch the full weakness,
+     * or chained to access hierarchy methods.
+     *
+     * @param id - The CWE weakness numeric ID (e.g. `79`)
+     * @returns A chainable weakness resource
+     *
+     * @example
+     * ```typescript
+     * const weakness = await cwe.weakness(79);
+     * const parents = await cwe.weakness(74).parents(1000);
+     * const tree = await cwe.weakness(74).descendants(1000);
+     * ```
+     */
+    weakness(id: number): WeaknessResource;
+    /**
+     * Returns a {@link CategoryResource} for a given CWE category ID, providing
+     * access to category details.
+     *
+     * The returned resource can be awaited directly to fetch the full category.
+     *
+     * @param id - The CWE category numeric ID (e.g. `189`)
+     * @returns A chainable category resource
+     *
+     * @example
+     * ```typescript
+     * const category = await cwe.category(189);
+     * console.log(category.Name); // 'Numeric Errors'
+     * ```
+     */
+    category(id: number): CategoryResource;
+    /**
+     * Returns a {@link ViewResource} for a given CWE view ID, providing access
+     * to view details.
+     *
+     * The returned resource can be awaited directly to fetch the full view.
+     *
+     * @param id - The CWE view numeric ID (e.g. `1425`)
+     * @returns A chainable view resource
+     *
+     * @example
+     * ```typescript
+     * const view = await cwe.view(1425);
+     * console.log(view.Name); // 'Weaknesses in the 2023 CWE Top 25...'
+     * ```
+     */
+    view(id: number): ViewResource;
+}
+
+/**
+ * Thrown when the CWE API returns a non-2xx response.
+ *
+ * @example
+ * ```typescript
+ * import { CweApiError } from 'cwe-api-client';
+ *
+ * try {
+ *   await cwe.weakness(99999).get();
+ * } catch (err) {
+ *   if (err instanceof CweApiError) {
+ *     console.log(err.status);     // 404
+ *     console.log(err.statusText); // 'Not Found'
+ *     console.log(err.message);    // 'CWE API error: 404 Not Found'
+ *   }
+ * }
+ * ```
+ */
+declare class CweApiError extends Error {
+    /** HTTP status code (e.g. `404`, `400`, `500`) */
+    readonly status: number;
+    /** HTTP status text (e.g. `'Not Found'`, `'Bad Request'`) */
+    readonly statusText: string;
+    constructor(status: number, statusText: string);
+}
+
+export { CategoryResource, type CweAlternateTerm, type CweAncestorNode, CweApiError, type CweApplicablePlatform, type CweCategory, type CweCategoryReference, type CweCategoryRelationship, CweClient, type CweClientEvents, type CweClientOptions, type CweDescendantNode, type CweEntry, type CweEntryType, type CweRelatedWeakness, type CweRelationEntry, type CweTaxonomyMapping, type CweVersion, type CweView, type CweViewAudience, type CweViewMember, type CweWeakness, type CweWeaknessOrdinality, type RequestEvent, ViewResource, WeaknessResource };