cwe-api-client 0.0.1 → 1.0.0

package/README.md

@@ -0,0 +1,225 @@
+# cwe-api-client
+
+[![CI](https://github.com/ElJijuna/cwe-api-client/actions/workflows/ci.yml/badge.svg)](https://github.com/ElJijuna/cwe-api-client/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/cwe-api-client)](https://www.npmjs.com/package/cwe-api-client)
+[![Bundle size](https://img.shields.io/bundlephobia/minzip/cwe-api-client)](https://bundlephobia.com/package/cwe-api-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/node/v/cwe-api-client)](https://nodejs.org/)
+
+TypeScript client for the [MITRE CWE REST API](https://cwe-api.mitre.org/api/v1).
+Works in **Node.js** and the **browser** (isomorphic). Fully typed, zero runtime dependencies.
+
+---
+
+## Installation
+
+```bash
+npm install cwe-api-client
+```
+
+---
+
+## Quick start
+
+```typescript
+import { CweClient } from 'cwe-api-client';
+
+const cwe = new CweClient();
+
+// Custom API base URL (e.g. a mirror)
+const cwe = new CweClient({ baseUrl: 'https://my-mirror.example.com/api/v1' });
+```
+
+---
+
+## API reference
+
+### Version metadata
+
+```typescript
+const version = await cwe.version();
+
+console.log(version.ContentVersion);  // '4.19.1'
+console.log(version.ContentDate);     // '2026-01-21'
+console.log(version.TotalWeaknesses); // 969
+console.log(version.TotalCategories); // 420
+console.log(version.TotalViews);      // 58
+```
+
+### Multi-ID lookup
+
+Look up multiple CWE entries by their numeric IDs in a single request:
+
+```typescript
+const entries = await cwe.lookup([74, 79]);
+
+entries.forEach(e => console.log(`CWE-${e.ID} (${e.Type})`));
+// CWE-74 (class_weakness)
+// CWE-79 (base_weakness)
+```
+
+### Weakness details
+
+```typescript
+// Await directly
+const weakness = await cwe.weakness(79);
+
+// Or call .get() explicitly
+const weakness = await cwe.weakness(79).get();
+
+console.log(weakness.Name);                 // 'Improper Neutralization of Input...'
+console.log(weakness.Abstraction);          // 'Base'
+console.log(weakness.Status);              // 'Stable'
+console.log(weakness.LikelihoodOfExploit); // 'High'
+console.log(weakness.Description);
+```
+
+### Category details
+
+```typescript
+const category = await cwe.category(189);
+
+console.log(category.Name);    // 'Numeric Errors'
+console.log(category.Status);  // 'Draft'
+console.log(category.Summary);
+console.log(category.Relationships?.length); // number of member weaknesses
+```
+
+### View details
+
+```typescript
+const view = await cwe.view(1425);
+
+console.log(view.Name);    // 'Weaknesses in the 2023 CWE Top 25...'
+console.log(view.Type);    // 'Graph'
+console.log(view.Status);  // 'Draft'
+console.log(view.Members?.length); // 25
+```
+
+### Hierarchy navigation
+
+All hierarchy methods accept an optional `viewId` to scope the results to a specific CWE view (e.g. `1000` for Research Concepts):
+
+```typescript
+// Direct parents
+const parents = await cwe.weakness(74).parents(1000);
+parents.forEach(p => console.log(`CWE-${p.ID}`, p.Primary_Parent ? '[primary]' : ''));
+
+// Direct children
+const children = await cwe.weakness(74).children(1000);
+children.forEach(c => console.log(`CWE-${c.ID} (${c.Type})`));
+
+// Full ancestor tree (recursive, up to the view root)
+const ancestors = await cwe.weakness(74).ancestors(1000);
+// ancestors[0].Data        → this node
+// ancestors[0].Parents     → parent nodes (recursive)
+
+// Full descendant tree (recursive, down to leaf entries)
+const descendants = await cwe.weakness(74).descendants(1000);
+// descendants[0].Data      → this node
+// descendants[0].Children  → child nodes (recursive)
+```
+
+---
+
+## Chainable resource pattern
+
+Every resource implements `PromiseLike`, so it can be **awaited directly** or **chained** to sub-methods:
+
+```typescript
+// Await directly → fetches the full weakness
+const weakness = await cwe.weakness(79);
+
+// Chain → fetches hierarchy
+const parents     = await cwe.weakness(74).parents(1000);
+const descendants = await cwe.weakness(74).descendants(1000);
+```
+
+---
+
+## Request events
+
+Subscribe to every HTTP request for logging, monitoring, or debugging:
+
+```typescript
+cwe.on('request', (event) => {
+  console.log(`[${event.method}] ${event.url} → ${event.statusCode} (${event.durationMs}ms)`);
+  if (event.error) {
+    console.error('Request failed:', event.error.message);
+  }
+});
+```
+
+The `event` object contains:
+
+| Field | Type | Description |
+|---|---|---|
+| `url` | `string` | Full URL that was requested |
+| `method` | `'GET'` | HTTP method used |
+| `startedAt` | `Date` | When the request started |
+| `finishedAt` | `Date` | When the request finished |
+| `durationMs` | `number` | Duration in milliseconds |
+| `statusCode` | `number \| undefined` | HTTP status code, if a response was received |
+| `error` | `Error \| undefined` | Present only if the request failed |
+
+Multiple listeners can be registered. The event is always emitted after the request completes, whether it succeeded or failed.
+
+---
+
+## Error handling
+
+Non-2xx responses throw a `CweApiError` with the HTTP status code and status text:
+
+```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'
+    console.log(err.stack);      // full stack trace
+  }
+}
+```
+
+---
+
+## TypeScript types
+
+All domain types are exported:
+
+```typescript
+import type {
+  // Client
+  CweClientOptions, RequestEvent, CweClientEvents,
+  // Version
+  CweVersion,
+  // Multi-ID lookup
+  CweEntry, CweEntryType,
+  // Weakness
+  CweWeakness, CweRelatedWeakness, CweWeaknessOrdinality,
+  CweApplicablePlatform, CweAlternateTerm,
+  // Category
+  CweCategory, CweTaxonomyMapping, CweCategoryRelationship, CweCategoryReference,
+  // View
+  CweView, CweViewAudience, CweViewMember,
+  // Relations / hierarchy
+  CweRelationEntry, CweAncestorNode, CweDescendantNode,
+} from 'cwe-api-client';
+```
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](.github/CONTRIBUTING.md).
+
+---
+
+## License
+
+[MIT](LICENSE)

package/dist/index.cjs

@@ -0,0 +1,382 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CategoryResource: () => CategoryResource,
+  CweApiError: () => CweApiError,
+  CweClient: () => CweClient,
+  ViewResource: () => ViewResource,
+  WeaknessResource: () => WeaknessResource
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors/CweApiError.ts
+var CweApiError = class extends Error {
+  constructor(status, statusText) {
+    super(`CWE API error: ${status} ${statusText}`);
+    this.name = "CweApiError";
+    this.status = status;
+    this.statusText = statusText;
+  }
+};
+
+// src/resources/WeaknessResource.ts
+var WeaknessResource = class {
+  /** @internal */
+  constructor(request, id) {
+    this.request = request;
+    this.id = id;
+  }
+  /**
+   * Allows the resource to be awaited directly, resolving with the full weakness.
+   * Delegates to {@link WeaknessResource.get}.
+   */
+  then(onfulfilled, onrejected) {
+    return this.get().then(onfulfilled, onrejected);
+  }
+  /**
+   * Fetches the full weakness entry.
+   *
+   * `GET /cwe/weakness/{id}`
+   *
+   * @returns The weakness object
+   */
+  async get() {
+    const data = await this.request(`/cwe/weakness/${this.id}`);
+    return data.Weaknesses[0];
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async parents(viewId) {
+    return this.request(
+      `/cwe/${this.id}/parents`,
+      viewId !== void 0 ? { view: viewId } : void 0
+    );
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async children(viewId) {
+    return this.request(
+      `/cwe/${this.id}/children`,
+      viewId !== void 0 ? { view: viewId } : void 0
+    );
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async ancestors(viewId) {
+    return this.request(
+      `/cwe/${this.id}/ancestors`,
+      viewId !== void 0 ? { view: viewId } : void 0
+    );
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async descendants(viewId) {
+    return this.request(
+      `/cwe/${this.id}/descendants`,
+      viewId !== void 0 ? { view: viewId } : void 0
+    );
+  }
+};
+
+// src/resources/CategoryResource.ts
+var CategoryResource = class {
+  /** @internal */
+  constructor(request, id) {
+    this.request = request;
+    this.id = id;
+  }
+  /**
+   * Allows the resource to be awaited directly, resolving with the full category.
+   * Delegates to {@link CategoryResource.get}.
+   */
+  then(onfulfilled, onrejected) {
+    return this.get().then(onfulfilled, onrejected);
+  }
+  /**
+   * Fetches the full category entry.
+   *
+   * `GET /cwe/category/{id}`
+   *
+   * @returns The category object
+   */
+  async get() {
+    const data = await this.request(`/cwe/category/${this.id}`);
+    return data.Categories[0];
+  }
+};
+
+// src/resources/ViewResource.ts
+var ViewResource = class {
+  /** @internal */
+  constructor(request, id) {
+    this.request = request;
+    this.id = id;
+  }
+  /**
+   * Allows the resource to be awaited directly, resolving with the full view.
+   * Delegates to {@link ViewResource.get}.
+   */
+  then(onfulfilled, onrejected) {
+    return this.get().then(onfulfilled, onrejected);
+  }
+  /**
+   * Fetches the full view entry.
+   *
+   * `GET /cwe/view/{id}`
+   *
+   * @returns The view object
+   */
+  async get() {
+    const data = await this.request(`/cwe/view/${this.id}`);
+    return data.Views[0];
+  }
+};
+
+// src/CweClient.ts
+var DEFAULT_BASE_URL = "https://cwe-api.mitre.org/api/v1";
+var CweClient = class {
+  /**
+   * @param options - Optional configuration for the API base URL
+   */
+  constructor(options = {}) {
+    this.listeners = /* @__PURE__ */ new Map();
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+  }
+  /**
+   * 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(event, callback) {
+    const callbacks = this.listeners.get(event) ?? [];
+    callbacks.push(callback);
+    this.listeners.set(event, callbacks);
+    return this;
+  }
+  emit(event, payload) {
+    const callbacks = this.listeners.get(event) ?? [];
+    for (const cb of callbacks) {
+      cb(payload);
+    }
+  }
+  /**
+   * 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
+   */
+  async request(path, params) {
+    const url = buildUrl(`${this.baseUrl}${path}`, params);
+    const startedAt = /* @__PURE__ */ new Date();
+    let statusCode;
+    try {
+      const response = await fetch(url, {
+        headers: { Accept: "application/json" }
+      });
+      statusCode = response.status;
+      if (!response.ok) {
+        throw new CweApiError(response.status, response.statusText);
+      }
+      const data = await response.json();
+      this.emit("request", {
+        url,
+        method: "GET",
+        startedAt,
+        finishedAt: /* @__PURE__ */ new Date(),
+        durationMs: Date.now() - startedAt.getTime(),
+        statusCode
+      });
+      return data;
+    } catch (err) {
+      const finishedAt = /* @__PURE__ */ new Date();
+      this.emit("request", {
+        url,
+        method: "GET",
+        startedAt,
+        finishedAt,
+        durationMs: finishedAt.getTime() - startedAt.getTime(),
+        statusCode,
+        error: err instanceof Error ? err : new Error(String(err))
+      });
+      throw err;
+    }
+  }
+  /**
+   * 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
+   * ```
+   */
+  async version() {
+    return this.request("/cwe/version");
+  }
+  /**
+   * 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));
+   * ```
+   */
+  async lookup(ids) {
+    return this.request(`/cwe/${ids.join(",")}`);
+  }
+  /**
+   * 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) {
+    return new WeaknessResource(
+      (path, params) => this.request(path, params),
+      id
+    );
+  }
+  /**
+   * 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) {
+    return new CategoryResource(
+      (path, params) => this.request(path, params),
+      id
+    );
+  }
+  /**
+   * 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) {
+    return new ViewResource(
+      (path, params) => this.request(path, params),
+      id
+    );
+  }
+};
+function buildUrl(base, params) {
+  if (!params) return base;
+  const entries = Object.entries(params).filter(([, v]) => v !== void 0);
+  if (entries.length === 0) return base;
+  const search = new URLSearchParams(entries.map(([k, v]) => [k, String(v)]));
+  return `${base}?${search.toString()}`;
+}
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/errors/CweApiError.ts","../src/resources/WeaknessResource.ts","../src/resources/CategoryResource.ts","../src/resources/ViewResource.ts","../src/CweClient.ts"],"sourcesContent":["export { CweClient } from './CweClient';\nexport { CweApiError } from './errors/CweApiError';\nexport type { CweClientOptions, RequestEvent, CweClientEvents } from './CweClient';\nexport { WeaknessResource } from './resources/WeaknessResource';\nexport { CategoryResource } from './resources/CategoryResource';\nexport { ViewResource } from './resources/ViewResource';\nexport type { CweVersion } from './domain/Version';\nexport type { CweEntry, CweEntryType } from './domain/CweEntry';\nexport type {\n  CweWeakness,\n  CweRelatedWeakness,\n  CweWeaknessOrdinality,\n  CweApplicablePlatform,\n  CweAlternateTerm,\n} from './domain/Weakness';\nexport type {\n  CweCategory,\n  CweTaxonomyMapping,\n  CweCategoryRelationship,\n  CweCategoryReference,\n} from './domain/Category';\nexport type {\n  CweView,\n  CweViewAudience,\n  CweViewMember,\n} from './domain/View';\nexport type {\n  CweRelationEntry,\n  CweAncestorNode,\n  CweDescendantNode,\n} from './domain/Relations';\n","/**\n * Thrown when the CWE API returns a non-2xx response.\n *\n * @example\n * ```typescript\n * import { CweApiError } from 'cwe-api-client';\n *\n * try {\n *   await cwe.weakness(99999).get();\n * } catch (err) {\n *   if (err instanceof CweApiError) {\n *     console.log(err.status);     // 404\n *     console.log(err.statusText); // 'Not Found'\n *     console.log(err.message);    // 'CWE API error: 404 Not Found'\n *   }\n * }\n * ```\n */\nexport class CweApiError extends Error {\n  /** HTTP status code (e.g. `404`, `400`, `500`) */\n  readonly status: number;\n  /** HTTP status text (e.g. `'Not Found'`, `'Bad Request'`) */\n  readonly statusText: string;\n\n  constructor(status: number, statusText: string) {\n    super(`CWE API error: ${status} ${statusText}`);\n    this.name = 'CweApiError';\n    this.status = status;\n    this.statusText = statusText;\n  }\n}\n","import type { CweWeakness } from '../domain/Weakness';\nimport type { CweRelationEntry, CweAncestorNode, CweDescendantNode } from '../domain/Relations';\n\n/** @internal */\nexport type RequestFn = <T>(\n  path: string,\n  params?: Record<string, string | number | boolean>,\n) => Promise<T>;\n\n/**\n * Represents a CWE weakness resource, providing access to weakness details\n * and its position in the CWE hierarchy.\n *\n * Implements `PromiseLike<CweWeakness>` so it can be awaited directly to\n * fetch the full weakness, while also exposing hierarchy methods.\n *\n * @example\n * ```typescript\n * // Await directly to get full weakness data\n * const weakness = await cwe.weakness(79);\n *\n * // Or call .get() explicitly\n * const weakness = await cwe.weakness(79).get();\n *\n * // Navigate the hierarchy\n * const parents = await cwe.weakness(74).parents(1000);\n * const children = await cwe.weakness(74).children(1000);\n * const ancestors = await cwe.weakness(74).ancestors(1000);\n * const descendants = await cwe.weakness(74).descendants(1000);\n * ```\n */\nexport class WeaknessResource implements PromiseLike<CweWeakness> {\n  /** @internal */\n  constructor(\n    private readonly request: RequestFn,\n    private readonly id: number,\n  ) {}\n\n  /**\n   * Allows the resource to be awaited directly, resolving with the full weakness.\n   * Delegates to {@link WeaknessResource.get}.\n   */\n  then<TResult1 = CweWeakness, TResult2 = never>(\n    onfulfilled?: ((value: CweWeakness) => TResult1 | PromiseLike<TResult1>) | null,\n    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,\n  ): PromiseLike<TResult1 | TResult2> {\n    return this.get().then(onfulfilled, onrejected);\n  }\n\n  /**\n   * Fetches the full weakness entry.\n   *\n   * `GET /cwe/weakness/{id}`\n   *\n   * @returns The weakness object\n   */\n  async get(): Promise<CweWeakness> {\n    const data = await this.request<{ Weaknesses: CweWeakness[] }>(`/cwe/weakness/${this.id}`);\n    return data.Weaknesses[0];\n  }\n\n  /**\n   * Fetches the direct parents of this weakness in a given view.\n   *\n   * `GET /cwe/{id}/parents?view={viewId}`\n   *\n   * @param viewId - CWE view ID to scope the hierarchy (e.g. `1000`)\n   * @returns Array of direct parent entries\n   *\n   * @example\n   * ```typescript\n   * const parents = await cwe.weakness(74).parents(1000);\n   * ```\n   */\n  async parents(viewId?: number): Promise<CweRelationEntry[]> {\n    return this.request<CweRelationEntry[]>(\n      `/cwe/${this.id}/parents`,\n      viewId !== undefined ? { view: viewId } : undefined,\n    );\n  }\n\n  /**\n   * Fetches the direct children of this weakness in a given view.\n   *\n   * `GET /cwe/{id}/children?view={viewId}`\n   *\n   * @param viewId - CWE view ID to scope the hierarchy (e.g. `1000`)\n   * @returns Array of direct child entries\n   *\n   * @example\n   * ```typescript\n   * const children = await cwe.weakness(74).children(1000);\n   * ```\n   */\n  async children(viewId?: number): Promise<CweRelationEntry[]> {\n    return this.request<CweRelationEntry[]>(\n      `/cwe/${this.id}/children`,\n      viewId !== undefined ? { view: viewId } : undefined,\n    );\n  }\n\n  /**\n   * Fetches the full ancestor tree of this weakness in a given view.\n   *\n   * `GET /cwe/{id}/ancestors?view={viewId}`\n   *\n   * @param viewId - CWE view ID to scope the hierarchy (e.g. `1000`)\n   * @returns Recursive ancestor tree from this node up to the view root\n   *\n   * @example\n   * ```typescript\n   * const tree = await cwe.weakness(74).ancestors(1000);\n   * ```\n   */\n  async ancestors(viewId?: number): Promise<CweAncestorNode[]> {\n    return this.request<CweAncestorNode[]>(\n      `/cwe/${this.id}/ancestors`,\n      viewId !== undefined ? { view: viewId } : undefined,\n    );\n  }\n\n  /**\n   * Fetches the full descendant tree of this weakness in a given view.\n   *\n   * `GET /cwe/{id}/descendants?view={viewId}`\n   *\n   * @param viewId - CWE view ID to scope the hierarchy (e.g. `1000`)\n   * @returns Recursive descendant tree from this node down to leaf entries\n   *\n   * @example\n   * ```typescript\n   * const tree = await cwe.weakness(74).descendants(1000);\n   * ```\n   */\n  async descendants(viewId?: number): Promise<CweDescendantNode[]> {\n    return this.request<CweDescendantNode[]>(\n      `/cwe/${this.id}/descendants`,\n      viewId !== undefined ? { view: viewId } : undefined,\n    );\n  }\n}\n","import type { CweCategory } from '../domain/Category';\nimport type { RequestFn } from './WeaknessResource';\n\n/**\n * Represents a CWE category resource, providing access to category details.\n *\n * Implements `PromiseLike<CweCategory>` so it can be awaited directly.\n *\n * @example\n * ```typescript\n * // Await directly to get full category data\n * const category = await cwe.category(189);\n *\n * // Or call .get() explicitly\n * const category = await cwe.category(189).get();\n * ```\n */\nexport class CategoryResource implements PromiseLike<CweCategory> {\n  /** @internal */\n  constructor(\n    private readonly request: RequestFn,\n    private readonly id: number,\n  ) {}\n\n  /**\n   * Allows the resource to be awaited directly, resolving with the full category.\n   * Delegates to {@link CategoryResource.get}.\n   */\n  then<TResult1 = CweCategory, TResult2 = never>(\n    onfulfilled?: ((value: CweCategory) => TResult1 | PromiseLike<TResult1>) | null,\n    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,\n  ): PromiseLike<TResult1 | TResult2> {\n    return this.get().then(onfulfilled, onrejected);\n  }\n\n  /**\n   * Fetches the full category entry.\n   *\n   * `GET /cwe/category/{id}`\n   *\n   * @returns The category object\n   */\n  async get(): Promise<CweCategory> {\n    const data = await this.request<{ Categories: CweCategory[] }>(`/cwe/category/${this.id}`);\n    return data.Categories[0];\n  }\n}\n","import type { CweView } from '../domain/View';\nimport type { RequestFn } from './WeaknessResource';\n\n/**\n * Represents a CWE view resource, providing access to view details.\n *\n * Implements `PromiseLike<CweView>` so it can be awaited directly.\n *\n * @example\n * ```typescript\n * // Await directly to get full view data\n * const view = await cwe.view(1425);\n *\n * // Or call .get() explicitly\n * const view = await cwe.view(1425).get();\n * ```\n */\nexport class ViewResource implements PromiseLike<CweView> {\n  /** @internal */\n  constructor(\n    private readonly request: RequestFn,\n    private readonly id: number,\n  ) {}\n\n  /**\n   * Allows the resource to be awaited directly, resolving with the full view.\n   * Delegates to {@link ViewResource.get}.\n   */\n  then<TResult1 = CweView, TResult2 = never>(\n    onfulfilled?: ((value: CweView) => TResult1 | PromiseLike<TResult1>) | null,\n    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,\n  ): PromiseLike<TResult1 | TResult2> {\n    return this.get().then(onfulfilled, onrejected);\n  }\n\n  /**\n   * Fetches the full view entry.\n   *\n   * `GET /cwe/view/{id}`\n   *\n   * @returns The view object\n   */\n  async get(): Promise<CweView> {\n    const data = await this.request<{ Views: CweView[] }>(`/cwe/view/${this.id}`);\n    return data.Views[0];\n  }\n}\n","import { CweApiError } from './errors/CweApiError';\nimport { WeaknessResource } from './resources/WeaknessResource';\nimport { CategoryResource } from './resources/CategoryResource';\nimport { ViewResource } from './resources/ViewResource';\nimport type { CweVersion } from './domain/Version';\nimport type { CweEntry } from './domain/CweEntry';\n\nconst DEFAULT_BASE_URL = 'https://cwe-api.mitre.org/api/v1';\n\n/**\n * Payload emitted on every HTTP request made by {@link CweClient}.\n */\nexport interface RequestEvent {\n  /** Full URL that was requested */\n  url: string;\n  /** HTTP method used */\n  method: 'GET';\n  /** Timestamp when the request started */\n  startedAt: Date;\n  /** Timestamp when the request finished (success or error) */\n  finishedAt: Date;\n  /** Total duration in milliseconds */\n  durationMs: number;\n  /** HTTP status code returned by the server, if a response was received */\n  statusCode?: number;\n  /** Error thrown, if the request failed */\n  error?: Error;\n}\n\n/** Map of supported client events to their callback signatures */\nexport interface CweClientEvents {\n  request: (event: RequestEvent) => void;\n}\n\n/**\n * Constructor options for {@link CweClient}.\n */\nexport interface CweClientOptions {\n  /**\n   * Base URL for the CWE API (default: `'https://cwe-api.mitre.org/api/v1'`).\n   * Override for mirrors or local instances.\n   */\n  baseUrl?: string;\n}\n\n/**\n * Main entry point for the MITRE CWE API client.\n *\n * @example\n * ```typescript\n * import { CweClient } from 'cwe-api-client';\n *\n * const cwe = new CweClient();\n *\n * // Get content version metadata\n * const version = await cwe.version();\n *\n * // Look up multiple CWEs at once\n * const entries = await cwe.lookup([74, 79]);\n *\n * // Get full weakness details\n * const weakness = await cwe.weakness(79);\n *\n * // Navigate the hierarchy\n * const parents = await cwe.weakness(74).parents(1000);\n * const descendants = await cwe.weakness(74).descendants(1000);\n *\n * // Get category and view details\n * const category = await cwe.category(189);\n * const view = await cwe.view(1425);\n * ```\n */\nexport class CweClient {\n  private readonly baseUrl: string;\n  private readonly listeners: Map<\n    keyof CweClientEvents,\n    CweClientEvents[keyof CweClientEvents][]\n  > = new Map();\n\n  /**\n   * @param options - Optional configuration for the API base URL\n   */\n  constructor(options: CweClientOptions = {}) {\n    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/$/, '');\n  }\n\n  /**\n   * Subscribes to a client event.\n   *\n   * @example\n   * ```typescript\n   * cwe.on('request', (event) => {\n   *   console.log(`${event.method} ${event.url} — ${event.durationMs}ms`);\n   *   if (event.error) console.error('Request failed:', event.error);\n   * });\n   * ```\n   */\n  on<K extends keyof CweClientEvents>(event: K, callback: CweClientEvents[K]): this {\n    const callbacks = this.listeners.get(event) ?? [];\n    callbacks.push(callback);\n    this.listeners.set(event, callbacks);\n    return this;\n  }\n\n  private emit<K extends keyof CweClientEvents>(\n    event: K,\n    payload: Parameters<CweClientEvents[K]>[0],\n  ): void {\n    const callbacks = this.listeners.get(event) ?? [];\n    for (const cb of callbacks) {\n      (cb as (p: typeof payload) => void)(payload);\n    }\n  }\n\n  /**\n   * Performs a GET request to the CWE API.\n   *\n   * @param path - Path to append to the base URL (e.g. `/cwe/version`)\n   * @param params - Optional query parameters\n   * @internal\n   */\n  async request<T>(\n    path: string,\n    params?: Record<string, string | number | boolean>,\n  ): Promise<T> {\n    const url = buildUrl(`${this.baseUrl}${path}`, params);\n    const startedAt = new Date();\n    let statusCode: number | undefined;\n    try {\n      const response = await fetch(url, {\n        headers: { Accept: 'application/json' },\n      });\n      statusCode = response.status;\n      if (!response.ok) {\n        throw new CweApiError(response.status, response.statusText);\n      }\n      const data = await response.json() as T;\n      this.emit('request', {\n        url,\n        method: 'GET',\n        startedAt,\n        finishedAt: new Date(),\n        durationMs: Date.now() - startedAt.getTime(),\n        statusCode,\n      });\n      return data;\n    } catch (err) {\n      const finishedAt = new Date();\n      this.emit('request', {\n        url,\n        method: 'GET',\n        startedAt,\n        finishedAt,\n        durationMs: finishedAt.getTime() - startedAt.getTime(),\n        statusCode,\n        error: err instanceof Error ? err : new Error(String(err)),\n      });\n      throw err;\n    }\n  }\n\n  /**\n   * Fetches CWE content version metadata.\n   *\n   * `GET /cwe/version`\n   *\n   * @returns Version metadata including content version, date, and counts\n   *\n   * @example\n   * ```typescript\n   * const v = await cwe.version();\n   * console.log(v.ContentVersion); // '4.19.1'\n   * console.log(v.TotalWeaknesses); // 969\n   * ```\n   */\n  async version(): Promise<CweVersion> {\n    return this.request<CweVersion>('/cwe/version');\n  }\n\n  /**\n   * Looks up multiple CWE entries by their numeric IDs in a single request.\n   *\n   * `GET /cwe/{ids}` (comma-separated)\n   *\n   * @param ids - Array of CWE numeric IDs (e.g. `[74, 79]`)\n   * @returns Array of lightweight CWE entries with type and ID\n   *\n   * @example\n   * ```typescript\n   * const entries = await cwe.lookup([74, 79]);\n   * entries.forEach(e => console.log(e.ID, e.Type));\n   * ```\n   */\n  async lookup(ids: number[]): Promise<CweEntry[]> {\n    return this.request<CweEntry[]>(`/cwe/${ids.join(',')}`);\n  }\n\n  /**\n   * Returns a {@link WeaknessResource} for a given CWE weakness ID, providing\n   * access to weakness details and its hierarchy (parents, children, ancestors,\n   * descendants).\n   *\n   * The returned resource can be awaited directly to fetch the full weakness,\n   * or chained to access hierarchy methods.\n   *\n   * @param id - The CWE weakness numeric ID (e.g. `79`)\n   * @returns A chainable weakness resource\n   *\n   * @example\n   * ```typescript\n   * const weakness = await cwe.weakness(79);\n   * const parents = await cwe.weakness(74).parents(1000);\n   * const tree = await cwe.weakness(74).descendants(1000);\n   * ```\n   */\n  weakness(id: number): WeaknessResource {\n    return new WeaknessResource(\n      <T>(path: string, params?: Record<string, string | number | boolean>) =>\n        this.request<T>(path, params),\n      id,\n    );\n  }\n\n  /**\n   * Returns a {@link CategoryResource} for a given CWE category ID, providing\n   * access to category details.\n   *\n   * The returned resource can be awaited directly to fetch the full category.\n   *\n   * @param id - The CWE category numeric ID (e.g. `189`)\n   * @returns A chainable category resource\n   *\n   * @example\n   * ```typescript\n   * const category = await cwe.category(189);\n   * console.log(category.Name); // 'Numeric Errors'\n   * ```\n   */\n  category(id: number): CategoryResource {\n    return new CategoryResource(\n      <T>(path: string, params?: Record<string, string | number | boolean>) =>\n        this.request<T>(path, params),\n      id,\n    );\n  }\n\n  /**\n   * Returns a {@link ViewResource} for a given CWE view ID, providing access\n   * to view details.\n   *\n   * The returned resource can be awaited directly to fetch the full view.\n   *\n   * @param id - The CWE view numeric ID (e.g. `1425`)\n   * @returns A chainable view resource\n   *\n   * @example\n   * ```typescript\n   * const view = await cwe.view(1425);\n   * console.log(view.Name); // 'Weaknesses in the 2023 CWE Top 25...'\n   * ```\n   */\n  view(id: number): ViewResource {\n    return new ViewResource(\n      <T>(path: string, params?: Record<string, string | number | boolean>) =>\n        this.request<T>(path, params),\n      id,\n    );\n  }\n}\n\n/**\n * Appends query parameters to a URL string, skipping `undefined` values.\n * @internal\n */\nfunction buildUrl(base: string, params?: Record<string, string | number | boolean>): string {\n  if (!params) return base;\n  const entries = Object.entries(params).filter(([, v]) => v !== undefined);\n  if (entries.length === 0) return base;\n  const search = new URLSearchParams(entries.map(([k, v]) => [k, String(v)]));\n  return `${base}?${search.toString()}`;\n}\n"],"mappings":"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","names":[]}