@nexusm/sdk 5.0.0 → 5.1.0

package/dist/index.d.mts

@@ -457,6 +457,21 @@ declare class HttpClient {
      * @returns The parsed response body.
      */
     patch<T>(path: string, data?: unknown, signal?: AbortSignal): Promise<T>;
+    /**
+     * Send a GET request and return the raw response body as a string.
+     *
+     * Intended for file-download endpoints (e.g. `GET /dashboard/export`) that
+     * return `text/csv` or `application/json` as a raw file stream rather than a
+     * JSON-parsed object.  The retry and auth interceptors still apply; the
+     * response cache is intentionally bypassed (export payloads are not cacheable
+     * at the SDK layer).
+     *
+     * @param path   - URL path relative to the base URL (e.g. `/dashboard/export`).
+     * @param params - Optional query parameters.
+     * @param signal - Optional {@link AbortSignal} to cancel the request.
+     * @returns The raw response body as a string.
+     */
+    getText(path: string, params?: Record<string, unknown>, signal?: AbortSignal): Promise<string>;
     /**
      * Send a DELETE request.
      *
@@ -2305,6 +2320,133 @@ declare class ErrorService extends BaseService {
     submit(data: ErrorReportRequest, options?: RequestOptions): Promise<ErrorReportResponse>;
 }
 
+/**
+ * @module types/dashboard
+ * @description Dashboard Service type definitions.
+ *
+ * Mirrors the Nexus API dashboard export contract:
+ * - GET /v1/dashboard/export — download a dataset as CSV or JSON
+ *
+ * The export endpoint returns raw file content (text/csv or application/json),
+ * not a JSON-parsed object.  The SDK therefore exposes these types only for
+ * the _request_ side; the return value is `string`.
+ */
+/**
+ * The set of exportable dashboard datasets.
+ *
+ * Must stay in sync with the backend `DashboardExportDataset` Literal:
+ * - `quality_distribution` — Quality score bucket distribution
+ * - `feedback_trend`       — Feedback rating trend over time
+ * - `diagnosis_stats`      — Diagnosis type statistics
+ * - `feedback_health`      — Overall feedback health metrics
+ * - `error_heatmap`        — Error frequency heatmap by endpoint / time
+ * - `ab_distribution`      — A/B experiment assignment distribution
+ */
+type DashboardExportDataset = 'quality_distribution' | 'feedback_trend' | 'diagnosis_stats' | 'feedback_health' | 'error_heatmap' | 'ab_distribution';
+/**
+ * Query parameters for `GET /v1/dashboard/export`.
+ */
+interface DashboardExportParams {
+    /**
+     * The dataset to export.  Required.
+     *
+     * Must be one of the six whitelisted values ({@link DashboardExportDataset}).
+     * The backend returns HTTP 422 for unknown values.
+     */
+    dataset: DashboardExportDataset;
+    /**
+     * File format for the exported data.
+     *
+     * - `'csv'`  — Comma-separated values (default when omitted).
+     * - `'json'` — Raw JSON text (not parsed; returned as a string by the SDK).
+     *
+     * @default 'csv'
+     */
+    format?: 'csv' | 'json';
+    /**
+     * Filter results to a specific tenant.
+     *
+     * Only usable by API keys that carry the admin scope.  The backend returns
+     * HTTP 403 when this field is present but the caller lacks admin privileges,
+     * and HTTP 400 when the value is not a valid UUID (it is normalized to
+     * canonical form server-side).
+     */
+    target_tenant_id?: string;
+}
+
+/**
+ * @module services/dashboard
+ * @description Dashboard Service — export analytics datasets.
+ *
+ * Wraps the Nexus Dashboard API:
+ * - GET /v1/dashboard/export — download a dataset as raw CSV or JSON text
+ *
+ * The export endpoint is a file-download endpoint: the backend responds with
+ * `Content-Disposition: attachment` and a raw file body (not a JSON envelope).
+ * Accordingly, `export()` returns the raw response string rather than parsing
+ * it into an object — callers receive exactly the bytes the server sent.
+ *
+ * ### WebSocket realtime subscriptions — deferred
+ *
+ * US-033b FU-3 scope is limited to the REST export method.  A WebSocket
+ * subscription helper (`subscribe()` / `DashboardSubscription`) was evaluated
+ * for inclusion but is deferred to FU-4 (WS replay/catchup protocol decision).
+ * Reasons:
+ *   1. The WS message schema is not yet stabilised (FU-4 owns that contract).
+ *   2. A proper WS abstraction requires a browser/Node `WebSocket` shim strategy
+ *      that is a non-trivial independent surface.
+ * Track the WS helper in FU-4; this file should be extended there.
+ *
+ * @example
+ * ```typescript
+ * const nexus = new NexusClient({ apiKey: 'nx_test_abc123' });
+ *
+ * // Download quality distribution as CSV (default format)
+ * const csv = await nexus.dashboard.export({ dataset: 'quality_distribution' });
+ * // csv is a string like: "bucket,count\n0-1,12\n1-2,45\n..."
+ *
+ * // Download feedback trend as JSON
+ * const json = await nexus.dashboard.export({
+ *   dataset: 'feedback_trend',
+ *   format: 'json',
+ * });
+ *
+ * // Admin: export data scoped to a specific tenant
+ * const tenantCsv = await nexus.dashboard.export({
+ *   dataset: 'error_heatmap',
+ *   format: 'csv',
+ *   target_tenant_id: 'tenant-abc',
+ * });
+ * ```
+ */
+
+/**
+ * Service for exporting dashboard analytics datasets.
+ *
+ * Exposes `GET /v1/dashboard/export` as a typed method that returns the raw
+ * file body (CSV or JSON text) as a string.
+ */
+declare class DashboardService extends BaseService {
+    /**
+     * Export a dashboard dataset as raw file content.
+     *
+     * Sends `GET /dashboard/export` with the given query parameters and returns
+     * the raw response body as a string.  The string is exactly the file the
+     * server would send for a browser download:
+     * - `format: 'csv'` (default) → comma-separated text
+     * - `format: 'json'`          → JSON text (not parsed into an object)
+     *
+     * @param params  - Dataset selection and format options.
+     * @param options - Optional request options (e.g. AbortSignal).
+     * @returns Raw file body string.
+     *
+     * @throws {ApiError} HTTP 401 — missing or invalid API key.
+     * @throws {ApiError} HTTP 403 — `target_tenant_id` requires admin scope.
+     * @throws {ApiError} HTTP 422 — `dataset` is not one of the six whitelisted values.
+     */
+    export(params: DashboardExportParams, options?: RequestOptions): Promise<string>;
+}
+
 /**
  * @module client
  * @description Main entry point for the Nexus SDK.
@@ -2356,6 +2498,8 @@ declare class NexusClient {
     readonly feedback: FeedbackService;
     /** Error reporting — submit structured error reports (US-031). */
     readonly errors: ErrorService;
+    /** Dashboard analytics — export datasets as CSV or JSON (US-033b FU-3). */
+    readonly dashboard: DashboardService;
     /** @internal Shared HTTP transport. */
     private readonly http;
     /**

package/dist/index.d.ts

@@ -457,6 +457,21 @@ declare class HttpClient {
      * @returns The parsed response body.
      */
     patch<T>(path: string, data?: unknown, signal?: AbortSignal): Promise<T>;
+    /**
+     * Send a GET request and return the raw response body as a string.
+     *
+     * Intended for file-download endpoints (e.g. `GET /dashboard/export`) that
+     * return `text/csv` or `application/json` as a raw file stream rather than a
+     * JSON-parsed object.  The retry and auth interceptors still apply; the
+     * response cache is intentionally bypassed (export payloads are not cacheable
+     * at the SDK layer).
+     *
+     * @param path   - URL path relative to the base URL (e.g. `/dashboard/export`).
+     * @param params - Optional query parameters.
+     * @param signal - Optional {@link AbortSignal} to cancel the request.
+     * @returns The raw response body as a string.
+     */
+    getText(path: string, params?: Record<string, unknown>, signal?: AbortSignal): Promise<string>;
     /**
      * Send a DELETE request.
      *
@@ -2305,6 +2320,133 @@ declare class ErrorService extends BaseService {
     submit(data: ErrorReportRequest, options?: RequestOptions): Promise<ErrorReportResponse>;
 }
 
+/**
+ * @module types/dashboard
+ * @description Dashboard Service type definitions.
+ *
+ * Mirrors the Nexus API dashboard export contract:
+ * - GET /v1/dashboard/export — download a dataset as CSV or JSON
+ *
+ * The export endpoint returns raw file content (text/csv or application/json),
+ * not a JSON-parsed object.  The SDK therefore exposes these types only for
+ * the _request_ side; the return value is `string`.
+ */
+/**
+ * The set of exportable dashboard datasets.
+ *
+ * Must stay in sync with the backend `DashboardExportDataset` Literal:
+ * - `quality_distribution` — Quality score bucket distribution
+ * - `feedback_trend`       — Feedback rating trend over time
+ * - `diagnosis_stats`      — Diagnosis type statistics
+ * - `feedback_health`      — Overall feedback health metrics
+ * - `error_heatmap`        — Error frequency heatmap by endpoint / time
+ * - `ab_distribution`      — A/B experiment assignment distribution
+ */
+type DashboardExportDataset = 'quality_distribution' | 'feedback_trend' | 'diagnosis_stats' | 'feedback_health' | 'error_heatmap' | 'ab_distribution';
+/**
+ * Query parameters for `GET /v1/dashboard/export`.
+ */
+interface DashboardExportParams {
+    /**
+     * The dataset to export.  Required.
+     *
+     * Must be one of the six whitelisted values ({@link DashboardExportDataset}).
+     * The backend returns HTTP 422 for unknown values.
+     */
+    dataset: DashboardExportDataset;
+    /**
+     * File format for the exported data.
+     *
+     * - `'csv'`  — Comma-separated values (default when omitted).
+     * - `'json'` — Raw JSON text (not parsed; returned as a string by the SDK).
+     *
+     * @default 'csv'
+     */
+    format?: 'csv' | 'json';
+    /**
+     * Filter results to a specific tenant.
+     *
+     * Only usable by API keys that carry the admin scope.  The backend returns
+     * HTTP 403 when this field is present but the caller lacks admin privileges,
+     * and HTTP 400 when the value is not a valid UUID (it is normalized to
+     * canonical form server-side).
+     */
+    target_tenant_id?: string;
+}
+
+/**
+ * @module services/dashboard
+ * @description Dashboard Service — export analytics datasets.
+ *
+ * Wraps the Nexus Dashboard API:
+ * - GET /v1/dashboard/export — download a dataset as raw CSV or JSON text
+ *
+ * The export endpoint is a file-download endpoint: the backend responds with
+ * `Content-Disposition: attachment` and a raw file body (not a JSON envelope).
+ * Accordingly, `export()` returns the raw response string rather than parsing
+ * it into an object — callers receive exactly the bytes the server sent.
+ *
+ * ### WebSocket realtime subscriptions — deferred
+ *
+ * US-033b FU-3 scope is limited to the REST export method.  A WebSocket
+ * subscription helper (`subscribe()` / `DashboardSubscription`) was evaluated
+ * for inclusion but is deferred to FU-4 (WS replay/catchup protocol decision).
+ * Reasons:
+ *   1. The WS message schema is not yet stabilised (FU-4 owns that contract).
+ *   2. A proper WS abstraction requires a browser/Node `WebSocket` shim strategy
+ *      that is a non-trivial independent surface.
+ * Track the WS helper in FU-4; this file should be extended there.
+ *
+ * @example
+ * ```typescript
+ * const nexus = new NexusClient({ apiKey: 'nx_test_abc123' });
+ *
+ * // Download quality distribution as CSV (default format)
+ * const csv = await nexus.dashboard.export({ dataset: 'quality_distribution' });
+ * // csv is a string like: "bucket,count\n0-1,12\n1-2,45\n..."
+ *
+ * // Download feedback trend as JSON
+ * const json = await nexus.dashboard.export({
+ *   dataset: 'feedback_trend',
+ *   format: 'json',
+ * });
+ *
+ * // Admin: export data scoped to a specific tenant
+ * const tenantCsv = await nexus.dashboard.export({
+ *   dataset: 'error_heatmap',
+ *   format: 'csv',
+ *   target_tenant_id: 'tenant-abc',
+ * });
+ * ```
+ */
+
+/**
+ * Service for exporting dashboard analytics datasets.
+ *
+ * Exposes `GET /v1/dashboard/export` as a typed method that returns the raw
+ * file body (CSV or JSON text) as a string.
+ */
+declare class DashboardService extends BaseService {
+    /**
+     * Export a dashboard dataset as raw file content.
+     *
+     * Sends `GET /dashboard/export` with the given query parameters and returns
+     * the raw response body as a string.  The string is exactly the file the
+     * server would send for a browser download:
+     * - `format: 'csv'` (default) → comma-separated text
+     * - `format: 'json'`          → JSON text (not parsed into an object)
+     *
+     * @param params  - Dataset selection and format options.
+     * @param options - Optional request options (e.g. AbortSignal).
+     * @returns Raw file body string.
+     *
+     * @throws {ApiError} HTTP 401 — missing or invalid API key.
+     * @throws {ApiError} HTTP 403 — `target_tenant_id` requires admin scope.
+     * @throws {ApiError} HTTP 422 — `dataset` is not one of the six whitelisted values.
+     */
+    export(params: DashboardExportParams, options?: RequestOptions): Promise<string>;
+}
+
 /**
  * @module client
  * @description Main entry point for the Nexus SDK.
@@ -2356,6 +2498,8 @@ declare class NexusClient {
     readonly feedback: FeedbackService;
     /** Error reporting — submit structured error reports (US-031). */
     readonly errors: ErrorService;
+    /** Dashboard analytics — export datasets as CSV or JSON (US-033b FU-3). */
+    readonly dashboard: DashboardService;
     /** @internal Shared HTTP transport. */
     private readonly http;
     /**

package/dist/index.js

@@ -794,6 +794,30 @@ var HttpClient = class {
     this.cache.invalidate(path.split("/").filter(Boolean)[0] ?? path);
     return result;
   }
+  /**
+   * Send a GET request and return the raw response body as a string.
+   *
+   * Intended for file-download endpoints (e.g. `GET /dashboard/export`) that
+   * return `text/csv` or `application/json` as a raw file stream rather than a
+   * JSON-parsed object.  The retry and auth interceptors still apply; the
+   * response cache is intentionally bypassed (export payloads are not cacheable
+   * at the SDK layer).
+   *
+   * @param path   - URL path relative to the base URL (e.g. `/dashboard/export`).
+   * @param params - Optional query parameters.
+   * @param signal - Optional {@link AbortSignal} to cancel the request.
+   * @returns The raw response body as a string.
+   */
+  async getText(path, params, signal) {
+    return this.retry.execute(async () => {
+      const response = await this.axios.get(path, {
+        params,
+        signal,
+        responseType: "text"
+      });
+      return response.data;
+    });
+  }
   /**
    * Send a DELETE request.
    *
@@ -1410,6 +1434,35 @@ var ErrorService = class extends BaseService {
   }
 };
 
+// src/services/dashboard.ts
+var DashboardService = class extends BaseService {
+  /**
+   * Export a dashboard dataset as raw file content.
+   *
+   * Sends `GET /dashboard/export` with the given query parameters and returns
+   * the raw response body as a string.  The string is exactly the file the
+   * server would send for a browser download:
+   * - `format: 'csv'` (default) → comma-separated text
+   * - `format: 'json'`          → JSON text (not parsed into an object)
+   *
+   * @param params  - Dataset selection and format options.
+   * @param options - Optional request options (e.g. AbortSignal).
+   * @returns Raw file body string.
+   *
+   * @throws {ApiError} HTTP 401 — missing or invalid API key.
+   * @throws {ApiError} HTTP 403 — `target_tenant_id` requires admin scope.
+   * @throws {ApiError} HTTP 422 — `dataset` is not one of the six whitelisted values.
+   */
+  async export(params, options) {
+    const query = { dataset: params.dataset };
+    if (params.format !== void 0) query["format"] = params.format;
+    if (params.target_tenant_id !== void 0) {
+      query["target_tenant_id"] = params.target_tenant_id;
+    }
+    return this.http.getText("/dashboard/export", query, options?.signal);
+  }
+};
+
 // src/client.ts
 var NexusClient = class {
   /**
@@ -1431,6 +1484,7 @@ var NexusClient = class {
     this.tenants = new TenantService(this.http);
     this.feedback = new FeedbackService(this.http);
     this.errors = new ErrorService(this.http);
+    this.dashboard = new DashboardService(this.http);
     if (resolved.autoErrorReport) {
       this.http.onApiError = (statusCode, method, url, detail) => {
         this.errors.submit({