@company-semantics/contracts 0.104.0 → 0.105.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.104.0",
+  "version": "0.105.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -101,6 +101,11 @@
     "vitest": "^4.0.16",
     "yaml": "^2.8.3"
   },
+  "pnpm": {
+    "overrides": {
+      "picomatch": ">=4.0.4"
+    }
+  },
   "lint-staged": {
     "*.ts": "bash -c 'tsc -b --noEmit'",
     "*.md": "markdownlint-cli2",

package/src/api/generated.ts

@@ -25,6 +25,28 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/healthz/details": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Detailed system health state
+         * @description Returns system health derived from alert engine and windowed metrics.
+         *     Includes health status, trend, active alerts, and key metrics.
+         *     Must NOT depend on database availability.
+         */
+        get: operations["getHealthDetails"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/auth/start": {
         parameters: {
             query?: never;
@@ -1902,6 +1924,26 @@ export interface components {
             /** @description Current application environment */
             app_env: string;
         };
+        HealthStateResponse: {
+            /** @enum {string} */
+            status: "healthy" | "degraded" | "critical";
+            /** @enum {string} */
+            trend: "stable" | "worsening" | "improving";
+            alerts: Record<string, never>[];
+            metrics: {
+                errorRate: number;
+                p95Latency: number;
+                activeExecutions: number;
+                droppedEvents: {
+                    log: number;
+                    metric: number;
+                    alert: number;
+                    trace: number;
+                };
+            };
+            /** @description Unix timestamp (milliseconds) of last health state computation */
+            lastUpdated: number;
+        };
         MeResponse: {
             /** Format: uuid */
             userId: string;
@@ -1944,12 +1986,16 @@ export interface components {
         };
         UserOrgMembership: {
             /** Format: uuid */
-            id: string;
-            name: string;
-            slug: string;
+            userId: string;
+            /** Format: uuid */
+            orgId: string;
+            orgName: string;
+            orgSlug: string;
             role: components["schemas"]["WorkspaceRole"];
             /** Format: date-time */
             joinedAt: string;
+            isActive: boolean;
+            orgType: components["schemas"]["OrgType"];
         };
         SetActiveOrgRequest: {
             /**
@@ -2136,7 +2182,60 @@ export interface components {
         };
         /** @description AI usage summary for an organization */
         OrgExecutionSummary: {
-            [key: string]: unknown;
+            period: {
+                /** Format: date-time */
+                start: string;
+                /** Format: date-time */
+                end: string;
+            };
+            summary: components["schemas"]["UnifiedUsageSummary"];
+            daily: components["schemas"]["UnifiedDailyUsage"][];
+            byProfile: components["schemas"]["UnifiedProfileUsage"][];
+            byUser: components["schemas"]["UnifiedUserUsage"][];
+            byModel: components["schemas"]["UnifiedModelUsage"][];
+            byFeature: components["schemas"]["UnifiedFeatureUsage"][];
+        };
+        UnifiedUsageSummary: {
+            executions: number;
+            totalCostUsd: string;
+            totalTokens: number;
+            avgDurationMs: number;
+            failureRate: number;
+        };
+        UnifiedDailyUsage: {
+            date: string;
+            executions: number;
+            totalCostUsd: string;
+        };
+        UnifiedProfileUsage: {
+            profile: string;
+            executions: number;
+            percentOfTotal: number;
+            totalCostUsd: string;
+            avgDurationMs: number;
+            failureRate: number;
+        };
+        UnifiedUserUsage: {
+            /** Format: uuid */
+            userId: string;
+            email: string;
+            executions: number;
+            totalCostUsd: string;
+            totalTokens: number;
+            favoriteProfile: string;
+        };
+        UnifiedModelUsage: {
+            model: string;
+            provider: string;
+            totalTokens: number;
+            estimatedCostUsd: string;
+            requestCount: number;
+        };
+        UnifiedFeatureUsage: {
+            feature: string;
+            totalTokens: number;
+            estimatedCostUsd: string;
+            requestCount: number;
         };
         ErrorResponse: {
             error: string;
@@ -2462,6 +2561,8 @@ export interface components {
         OrgAuthPolicy: {
             requireSSO: boolean;
             allowedProviders: string[];
+            /** @description True when the requesting admin's own SSO session was revoked by this operation */
+            selfRevoked?: boolean;
         };
         CreateInviteRequest: {
             /**
@@ -2739,6 +2840,26 @@ export interface operations {
             };
         };
     };
+    getHealthDetails: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description System health state */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HealthStateResponse"];
+                };
+            };
+        };
+    };
     startAuth: {
         parameters: {
             query?: never;

package/src/errors/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Canonical error response types for all API surfaces.
+ *
+ * These types are the single source of truth for the error response shape
+ * across HTTP, streaming, agents, and the execution system.
+ *
+ * @see ADR-BE-098 for design rationale
+ */
+
+/** Field-level validation detail for VALIDATION_ERROR responses. */
+export interface ValidationDetail {
+  /** Field path (e.g. 'email', 'settings.name'). */
+  field: string
+  /** Human-readable error message for this field. */
+  message: string
+  /** Machine-readable sub-code (e.g. 'too_short', 'invalid_format') for frontend logic. */
+  code?: string
+}
+
+/** Canonical error response shape returned by all API surfaces. */
+export interface ErrorResponse {
+  /** Domain-specific error code (e.g. INVITE_EXPIRED, SSO_REQUIRED). */
+  error: string
+  /** HTTP status code — lives in payload for transport portability across HTTP, streaming, agents, execution system. */
+  status: number
+  /** Optional human-readable message — safe default applied by handler when absent. */
+  message?: string
+  /** Validation field-level details — only present for VALIDATION_ERROR. */
+  details?: ValidationDetail[]
+  /**
+   * Structured extension fields (e.g. ssoUrl, orgId).
+   *
+   * Conventions: camelCase keys, domain-scoped, shallow values,
+   * serializable, stable keys, no duplication of top-level fields.
+   */
+  meta?: Record<string, unknown>
+}

package/src/index.ts

@@ -540,9 +540,21 @@ export { resolveScope, toQueryKey, fromQueryKey, resourceRelationships, matchesR
 // Resource response wrapper (typed versioning for cache invalidation)
 export type { ResourceResponse } from './resource-response'
 
+// Error response types (canonical shape for all API surfaces)
+// @see ADR-BE-098 for design rationale
+export type { ValidationDetail, ErrorResponse } from './errors/index'
+
 // OpenAPI generated types (from openapi/backend.yaml)
 // @see src/api/README.md for codegen details
 export type { paths, components, operations } from './api/index'
 
 // OpenAPI route registry (generated from openapi/backend.yaml)
 export { openApiRoutes, type OpenApiRoute, type OpenApiMethod } from './generated/openapi-routes'
+
+// Secret wrapper (multi-surface redaction for sensitive values)
+export type { Secret } from './security/index'
+export { wrapSecret, unwrapSecret } from './security/index'
+
+// Analytics response metadata (shared vocabulary for OLTP/OLAP separation)
+// @see ADR-CTRL-053 for design rationale
+export type { AnalyticsResponseMeta } from './types/analytics'

package/src/security/index.ts

@@ -0,0 +1,2 @@
+export type { Secret } from './secret';
+export { wrapSecret, unwrapSecret } from './secret';

package/src/security/secret.ts

@@ -0,0 +1,47 @@
+/**
+ * Secret<T> — branded wrapper that prevents accidental secret leakage.
+ *
+ * Multi-surface protection:
+ * - toString() → [REDACTED] — template literals, string concatenation, error messages
+ * - toJSON() → [REDACTED] — JSON.stringify (API responses, serialization)
+ * - Symbol.toPrimitive → [REDACTED] — implicit type coercion
+ *
+ * Use wrapSecret() to wrap a value, unwrapSecret() to extract it.
+ * The __secret marker enables external detection (e.g., Pino serializers).
+ */
+
+// @vocabulary-exempt: Class required for prototype method control (toString/toJSON/Symbol.toPrimitive)
+class SecretValue<T> {
+  readonly __secret = true as const;
+  private readonly _value: T;
+
+  constructor(value: T) {
+    this._value = value;
+  }
+
+  unwrap(): T {
+    return this._value;
+  }
+
+  toString(): string {
+    return '[REDACTED]';
+  }
+
+  toJSON(): string {
+    return '[REDACTED]';
+  }
+
+  [Symbol.toPrimitive](): string {
+    return '[REDACTED]';
+  }
+}
+
+export type Secret<T> = SecretValue<T>;
+
+export function wrapSecret<T>(value: T): Secret<T> {
+  return new SecretValue(value);
+}
+
+export function unwrapSecret<T>(secret: Secret<T>): T {
+  return secret.unwrap();
+}

package/src/types/analytics.ts

@@ -0,0 +1,14 @@
+/**
+ * Metadata included in every analytics-backed API response.
+ * Enables consumers to know data freshness and which backend served the query.
+ *
+ * See ADR-CTRL-053 D8: Data Freshness Contract.
+ */
+export interface AnalyticsResponseMeta {
+  /** Replication lag from OLTP in milliseconds. 0 when source is 'oltp'. */
+  readonly dataFreshnessMs: number;
+  /** Which backend served this response. */
+  readonly source: 'oltp' | 'olap';
+  /** ISO 8601 timestamp: when the data was current as of. */
+  readonly timestamp: string;
+}