@kb-labs/rest-api-contracts 1.0.0

package/README.md

@@ -0,0 +1,48 @@
+# @kb-labs/api-contracts
+
+Shared API contracts for KB Labs REST, CLI, and Studio surfaces.
+
+## Overview
+
+Provides Zod schemas and TypeScript types for consistent API shapes across all KB Labs services.
+
+## API Reference
+
+### Error Codes
+
+- `ErrorCode` — standardized error code enum
+- `getErrorCode(error)` — extract error code from an error value
+
+### Response Envelopes
+
+- `SuccessEnvelope<T>` — `{ ok: true, data: T, meta }`
+- `ErrorEnvelope` — `{ ok: false, error: { code, message, details?, traceId? }, meta }`
+
+### System Types
+
+- `SystemInfo` — system information shape
+- `SystemHealth` — health snapshot shape
+- `ReadyState` — readiness probe shape
+- `isReady(state)` — type guard for readiness
+
+## Usage
+
+```typescript
+import { ErrorCode, SuccessEnvelope, ErrorEnvelope } from '@kb-labs/api-contracts';
+
+const success: SuccessEnvelope<{ id: string }> = {
+  ok: true,
+  data: { id: '01K...' },
+  meta: { requestId: '01K...', durationMs: 12, apiVersion: '1.0.0' },
+};
+
+const error: ErrorEnvelope = {
+  ok: false,
+  error: { code: ErrorCode.INTERNAL_ERROR, message: 'Something went wrong' },
+  meta: { requestId: '01K...', durationMs: 5, apiVersion: '1.0.0' },
+};
+```
+
+## License
+
+KB Public License v1.1 © KB Labs

package/dist/index.d.ts

@@ -0,0 +1,502 @@
+import { z } from 'zod';
+import { StudioRegistry } from '@kb-labs/studio-contracts';
+export { ActionConfirm, ActionHandler, ActionHandlerType, AlertData, AlertOptions, BreadcrumbData, BreadcrumbOptions, COMPOSITE_WIDGET_KINDS, CardData, CardListData, CardListOptions, CardOptions, ChartAreaData, ChartAreaOptions, ChartBarData, ChartBarOptions, ChartLineData, ChartLineOptions, ChartPieData, ChartPieOptions, CheckboxGroupData, CheckboxGroupOptions, CompositeWidgetDecl, CompositeWidgetKind, ConfirmData, ConfirmOptions, DataSource, DatePickerData, DatePickerOptions, DiffData, DiffOptions, EmitActionHandler, FlattenedRegistry, FormData, FormOptions, GridLayoutConfig, GridOptions, InputData, InputOptions, JsonData, JsonOptions, LayoutConfig, LayoutHint, LayoutKind, LeafWidgetDecl, LeafWidgetKind, LogsData, LogsOptions, MenuData, MenuOptions, MetricData, MetricGroupData, MetricGroupOptions, MetricOptions, MockDataSource, ModalData, ModalOptions, NavigateActionHandler, RestActionHandler, RestDataSource, STANDARD_EVENTS, STUDIO_SCHEMA_VERSION, STUDIO_SCHEMA_VERSION_NUMBER, SchemaRef, SectionOptions, SelectData, SelectOptions, StackLayoutConfig, StackOptions, StandardEventName, StaticDataSource, StepperData, StepperOptions, StudioConfig, StudioLayoutDecl, StudioMenuDecl, StudioPluginEntry, StudioRegistry, StudioWidgetDecl, StudioWidgetKind, SwitchData, SwitchOptions, TableColumn, TableData, TableOptions, TabsOptions, TimelineData, TimelineOptions, TreeData, TreeOptions, UserContext, VisibilityRule, WIDGET_CATEGORIES, WidgetAction, WidgetCategory, WidgetData, WidgetDataMap, WidgetEvent, WidgetEventConfig, WidgetOptionsMap, createEmptyRegistry, flattenRegistry, isCompositeKind, isCompositeWidget, isEmitActionHandler, isGridConfig, isLeafWidget, isMockDataSource, isNavigateActionHandler, isRestActionHandler, isRestDataSource, isStackConfig, isStaticDataSource, matchesVisibility, needsMigration, validateSchemaVersion } from '@kb-labs/studio-contracts';
+
+/**
+ * Standardized error codes shared across CLI, REST and Studio.
+ * These values intentionally line up with the codes used by the
+ * plugin runtime so adapters can map them to HTTP status codes.
+ */
+declare enum ErrorCode {
+    INTERNAL = "INTERNAL",
+    PLUGIN_PERMISSION_DENIED = "PLUGIN_PERMISSION_DENIED",
+    PLUGIN_CAPABILITY_MISSING = "PLUGIN_CAPABILITY_MISSING",
+    PLUGIN_HANDLER_NOT_FOUND = "PLUGIN_HANDLER_NOT_FOUND",
+    PLUGIN_TIMEOUT = "PLUGIN_TIMEOUT",
+    PLUGIN_SCHEMA_VALIDATION_FAILED = "PLUGIN_SCHEMA_VALIDATION_FAILED",
+    PLUGIN_ARTIFACT_FAILED = "PLUGIN_ARTIFACT_FAILED",
+    PLUGIN_QUOTA_EXCEEDED = "PLUGIN_QUOTA_EXCEEDED",
+    ARTIFACT_READ_DENIED = "ARTIFACT_READ_DENIED",
+    ARTIFACT_WRITE_DENIED = "ARTIFACT_WRITE_DENIED",
+    CONFLICT = "CONFLICT"
+}
+/**
+ * Helper describing a compact permission summary.
+ */
+interface PermissionSummary {
+    fs?: {
+        mode?: string;
+        allowCount?: number;
+        denyCount?: number;
+    };
+    net?: 'none' | {
+        allowHostsCount?: number;
+        denyHostsCount?: number;
+    };
+    env?: {
+        allowCount?: number;
+    };
+    quotas?: {
+        timeoutMs?: number;
+        memoryMb?: number;
+        cpuMs?: number;
+    };
+    capabilities?: string[];
+}
+/**
+ * Permissions diff emitted when the runtime compares required
+ * vs granted permissions for a failing invocation.
+ */
+interface PermissionDiff {
+    required?: string[];
+    granted?: string[];
+}
+
+interface EnvelopeMeta {
+    requestId: string;
+    durationMs: number;
+    apiVersion: string;
+    [key: string]: unknown;
+}
+type SuccessEnvelope<T = unknown> = {
+    ok: true;
+    data: T;
+    meta?: EnvelopeMeta;
+};
+type ErrorEnvelope = {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+        cause?: unknown;
+        traceId?: string;
+    };
+    meta: EnvelopeMeta;
+};
+declare const errorEnvelopeSchema: z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        cause: z.ZodOptional<z.ZodUnknown>;
+        traceId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        message: string;
+        details?: Record<string, unknown> | undefined;
+        cause?: unknown;
+        traceId?: string | undefined;
+    }, {
+        code: string;
+        message: string;
+        details?: Record<string, unknown> | undefined;
+        cause?: unknown;
+        traceId?: string | undefined;
+    }>;
+    meta: z.ZodObject<{
+        requestId: z.ZodString;
+        durationMs: z.ZodNumber;
+        apiVersion: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        requestId: string;
+        durationMs: number;
+        apiVersion: string;
+    }, {
+        requestId: string;
+        durationMs: number;
+        apiVersion: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown> | undefined;
+        cause?: unknown;
+        traceId?: string | undefined;
+    };
+    meta: {
+        requestId: string;
+        durationMs: number;
+        apiVersion: string;
+    };
+}, {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown> | undefined;
+        cause?: unknown;
+        traceId?: string | undefined;
+    };
+    meta: {
+        requestId: string;
+        durationMs: number;
+        apiVersion: string;
+    };
+}>;
+/**
+ * Structured error produced by the plugin runtime.
+ */
+interface PluginErrorEnvelope {
+    status: 'error';
+    http: number;
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+    trace?: string;
+    meta: {
+        requestId: string;
+        pluginId: string;
+        pluginVersion: string;
+        routeOrCommand: string;
+        timeMs: number;
+        cpuMs?: number;
+        memMb?: number;
+        perms?: PermissionSummary | PermissionDiff | Record<string, unknown>;
+    };
+}
+
+interface SystemHealthSnapshot {
+    schema: 'kb.health/1';
+    ts: string;
+    uptimeSec: number;
+    version: {
+        kbLabs: string;
+        cli: string;
+        rest: string;
+        studio?: string;
+        git?: {
+            sha: string;
+            dirty: boolean;
+        };
+        [key: string]: unknown;
+    };
+    registry: {
+        total: number;
+        withRest: number;
+        withStudio: number;
+        errors: number;
+        generatedAt: string;
+        expiresAt?: string;
+        partial: boolean;
+        stale: boolean;
+    };
+    status: 'healthy' | 'degraded';
+    components: Array<{
+        id: string;
+        version?: string;
+        restRoutes?: number;
+        studioWidgets?: number;
+        lastError?: string;
+        meta?: Record<string, unknown>;
+    }>;
+    meta?: Record<string, unknown>;
+}
+interface SystemInfoPayload {
+    schema: 'kb.info/1';
+    ts: string;
+    uptimeSec: number;
+    environment: string;
+    versions: Record<string, string>;
+    features?: Record<string, boolean>;
+    meta?: Record<string, unknown>;
+}
+interface SystemCapabilitiesPayload {
+    schema: 'kb.capabilities/1';
+    capabilities: Array<{
+        id: string;
+        describe: string;
+        granted: boolean;
+        origin?: string;
+    }>;
+    plugins?: Record<string, string[]>;
+    meta?: Record<string, unknown>;
+}
+interface SystemConfigPayload {
+    schema: 'kb.config.redacted/1';
+    config: Record<string, unknown>;
+    redacted: string[];
+    meta?: Record<string, unknown>;
+}
+type InfoResponse = SuccessEnvelope<SystemInfoPayload>;
+type CapabilitiesResponse = SuccessEnvelope<SystemCapabilitiesPayload>;
+type ConfigResponse = SuccessEnvelope<SystemConfigPayload>;
+
+interface ReadyComponents {
+    cliApi: {
+        initialized: boolean;
+    };
+    registry: {
+        loaded: boolean;
+        partial: boolean;
+        stale: boolean;
+    };
+    plugins: {
+        mounted: number;
+        inProgress: boolean;
+        routeCount: number;
+        errors: number;
+        failures: Array<{
+            id: string;
+            error: string;
+        }>;
+        lastCompletedAt: string | null;
+        lastDurationMs: number | null;
+    };
+    redis: {
+        enabled: boolean;
+        healthy: boolean;
+        states?: Record<string, unknown>;
+    };
+}
+interface ReadyResponseBase {
+    schema: 'kb.ready/1';
+    ts: string;
+    reason: string;
+    components: ReadyComponents;
+}
+type ReadyResponse = ReadyResponseBase & {
+    ready: true;
+    status: 'ready' | 'degraded';
+};
+type NotReadyResponse = ReadyResponseBase & {
+    ready: false;
+    status: 'initializing' | 'degraded';
+};
+
+/**
+ * @module @kb-labs/rest-api-contracts/studio
+ * Re-exports from @kb-labs/studio-contracts + REST-specific types.
+ *
+ * Studio should ONLY import from this package - no server-side dependencies.
+ *
+ * @example
+ * ```typescript
+ * // Preferred: Import directly from studio-contracts
+ * import { StudioWidgetDecl, StudioConfig } from '@kb-labs/studio-contracts';
+ *
+ * // Still works: Import via rest-api-contracts (re-export)
+ * import { StudioWidgetDecl, StudioConfig } from '@kb-labs/rest-api-contracts';
+ * ```
+ */
+
+/**
+ * GET /studio/registry response
+ * Extends StudioRegistry with REST-specific metadata
+ */
+type StudioRegistryResponse = StudioRegistry;
+/**
+ * Batch data request for multiple widgets
+ */
+interface BatchDataRequest {
+    widgetIds: string[];
+}
+/**
+ * Batch data response
+ */
+interface BatchDataResponse {
+    /** widgetId -> data mapping */
+    data: Record<string, unknown>;
+    /** widgetId -> error message for failed widgets */
+    errors?: Record<string, string>;
+}
+/**
+ * Action execution request
+ */
+interface ActionRequest {
+    widgetId: string;
+    actionId: string;
+    payload?: unknown;
+}
+/**
+ * Action execution response
+ */
+interface ActionResponse {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+}
+
+/**
+ * @module @kb-labs/rest-api-contracts/observability
+ * Observability contracts for system monitoring endpoints
+ */
+/**
+ * Statistics from State Broker daemon
+ *
+ * Provides metrics about in-memory cache performance, namespace usage,
+ * and multi-tenancy statistics.
+ */
+interface StateBrokerStats {
+    /** Daemon uptime in milliseconds */
+    uptime: number;
+    /** Total number of cache entries across all namespaces */
+    totalEntries: number;
+    /** Total cache size in bytes (estimated) */
+    totalSize: number;
+    /** Cache hit rate (0-1) */
+    hitRate: number;
+    /** Cache miss rate (0-1) */
+    missRate: number;
+    /** Number of evicted entries */
+    evictions: number;
+    /** Stats per namespace (mind, workflow, etc.) */
+    namespaces: Record<string, NamespaceStats>;
+    /** Stats per tenant (multi-tenancy support) */
+    byTenant?: Record<string, TenantStats>;
+}
+/**
+ * Statistics for a specific namespace
+ */
+interface NamespaceStats {
+    /** Number of entries in this namespace */
+    entries: number;
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Estimated size in bytes */
+    size: number;
+}
+/**
+ * Statistics for a specific tenant
+ */
+interface TenantStats {
+    /** Number of entries for this tenant */
+    entries: number;
+    /** Total operations performed */
+    operations: number;
+}
+/**
+ * DevKit health check results
+ *
+ * Provides monorepo health metrics including health score, issues breakdown,
+ * and type coverage statistics.
+ */
+interface DevKitHealthSnapshot {
+    /** Health score (0-100) */
+    healthScore: number;
+    /** Letter grade (A-F) based on health score */
+    grade: 'A' | 'B' | 'C' | 'D' | 'F';
+    /** Breakdown of issues affecting health score */
+    issues: {
+        /** Number of duplicate dependencies */
+        duplicateDeps?: number;
+        /** Number of packages missing README files */
+        missingReadmes?: number;
+        /** Number of TypeScript type errors */
+        typeErrors?: number;
+        /** Number of broken imports */
+        brokenImports?: number;
+        /** Number of unused exports */
+        unusedExports?: number;
+        /** Other issues (custom keys) */
+        [key: string]: number | undefined;
+    };
+    /** Total number of packages in monorepo */
+    packages: number;
+    /** Average TypeScript type coverage (0-100) */
+    avgTypeCoverage?: number;
+    /** Number of packages with poor type coverage (<70%) */
+    poorTypeCoverageCount?: number;
+}
+/**
+ * Response payload for GET /api/v1/observability/state-broker
+ */
+interface StateBrokerStatsPayload {
+    ok: true;
+    data: StateBrokerStats;
+    meta: {
+        source: 'state-broker';
+        daemonUrl: string;
+    };
+}
+/**
+ * Response payload for GET /api/v1/observability/devkit
+ */
+interface DevKitHealthPayload {
+    ok: true;
+    data: DevKitHealthSnapshot;
+    meta: {
+        source: 'devkit-cli';
+        repoRoot: string;
+        command: string;
+    };
+}
+/**
+ * Historical data point
+ */
+interface HistoricalDataPoint {
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Metric value */
+    value: number;
+}
+/**
+ * Heatmap cell data (7 days × 24 hours)
+ */
+interface HeatmapCell {
+    /** Day of week: 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun' */
+    day: string;
+    /** Hour of day: 0-23 */
+    hour: number;
+    /** Aggregated metric value */
+    value: number;
+}
+/**
+ * Response payload for GET /api/v1/observability/metrics/history
+ */
+interface MetricsHistoryPayload {
+    ok: true;
+    data: HistoricalDataPoint[];
+    meta: {
+        source: 'historical-metrics-collector';
+        metric: 'requests' | 'errors' | 'latency' | 'uptime';
+        range: '1m' | '5m' | '10m' | '30m' | '1h';
+        interval: '5s' | '1m' | '5m';
+        points: number;
+    };
+}
+/**
+ * Response payload for GET /api/v1/observability/metrics/heatmap
+ */
+interface MetricsHeatmapPayload {
+    ok: true;
+    data: HeatmapCell[];
+    meta: {
+        source: 'historical-metrics-collector';
+        metric: 'latency' | 'errors' | 'requests';
+        days: 7 | 14 | 30;
+        cells: number;
+    };
+}
+
+/**
+ * Adapter value can be:
+ * - string: single adapter package
+ * - string[]: multiple adapters (first = primary)
+ * - null: disabled/NoOp
+ */
+type AdapterValue = string | string[] | null;
+/**
+ * Platform configuration snapshot.
+ * Returns current platform adapters and their options (redacted for sensitive data).
+ */
+interface PlatformConfigPayload {
+    schema: 'kb.platform.config/1';
+    ts: string;
+    /** Adapter packages (can be string, string[], or null for each key) */
+    adapters: Record<string, AdapterValue>;
+    adapterOptions: Record<string, unknown>;
+    execution: {
+        mode: string;
+    };
+    /** List of keys that were redacted from adapterOptions */
+    redacted: string[];
+}
+type PlatformConfigResponse = SuccessEnvelope<PlatformConfigPayload>;
+
+export { type ActionRequest, type ActionResponse, type AdapterValue, type BatchDataRequest, type BatchDataResponse, type CapabilitiesResponse, type ConfigResponse, type DevKitHealthPayload, type DevKitHealthSnapshot, type EnvelopeMeta, ErrorCode, type ErrorEnvelope, type HeatmapCell, type HistoricalDataPoint, type InfoResponse, type MetricsHeatmapPayload, type MetricsHistoryPayload, type NamespaceStats, type NotReadyResponse, type PermissionDiff, type PermissionSummary, type PlatformConfigPayload, type PlatformConfigResponse, type PluginErrorEnvelope, type ReadyComponents, type ReadyResponse, type StateBrokerStats, type StateBrokerStatsPayload, type StudioRegistryResponse, type SuccessEnvelope, type SystemCapabilitiesPayload, type SystemConfigPayload, type SystemHealthSnapshot, type SystemInfoPayload, type TenantStats, errorEnvelopeSchema };

package/dist/index.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+export { COMPOSITE_WIDGET_KINDS, STANDARD_EVENTS, STUDIO_SCHEMA_VERSION, STUDIO_SCHEMA_VERSION_NUMBER, WIDGET_CATEGORIES, createEmptyRegistry, flattenRegistry, isCompositeKind, isCompositeWidget, isEmitActionHandler, isGridConfig, isLeafWidget, isMockDataSource, isNavigateActionHandler, isRestActionHandler, isRestDataSource, isStackConfig, isStaticDataSource, matchesVisibility, needsMigration, validateSchemaVersion } from '@kb-labs/studio-contracts';
+
+// src/error-code.ts
+var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
+  ErrorCode2["INTERNAL"] = "INTERNAL";
+  ErrorCode2["PLUGIN_PERMISSION_DENIED"] = "PLUGIN_PERMISSION_DENIED";
+  ErrorCode2["PLUGIN_CAPABILITY_MISSING"] = "PLUGIN_CAPABILITY_MISSING";
+  ErrorCode2["PLUGIN_HANDLER_NOT_FOUND"] = "PLUGIN_HANDLER_NOT_FOUND";
+  ErrorCode2["PLUGIN_TIMEOUT"] = "PLUGIN_TIMEOUT";
+  ErrorCode2["PLUGIN_SCHEMA_VALIDATION_FAILED"] = "PLUGIN_SCHEMA_VALIDATION_FAILED";
+  ErrorCode2["PLUGIN_ARTIFACT_FAILED"] = "PLUGIN_ARTIFACT_FAILED";
+  ErrorCode2["PLUGIN_QUOTA_EXCEEDED"] = "PLUGIN_QUOTA_EXCEEDED";
+  ErrorCode2["ARTIFACT_READ_DENIED"] = "ARTIFACT_READ_DENIED";
+  ErrorCode2["ARTIFACT_WRITE_DENIED"] = "ARTIFACT_WRITE_DENIED";
+  ErrorCode2["CONFLICT"] = "CONFLICT";
+  return ErrorCode2;
+})(ErrorCode || {});
+var errorEnvelopeSchema = z.object({
+  ok: z.literal(false),
+  error: z.object({
+    code: z.string(),
+    message: z.string(),
+    details: z.record(z.string(), z.unknown()).optional(),
+    cause: z.unknown().optional(),
+    traceId: z.string().optional()
+  }),
+  meta: z.object({
+    requestId: z.string(),
+    durationMs: z.number(),
+    apiVersion: z.string()
+  })
+});
+
+export { ErrorCode, errorEnvelopeSchema };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/error-code.ts","../src/envelopes.ts"],"names":["ErrorCode"],"mappings":";;;;AAKO,IAAK,SAAA,qBAAAA,UAAAA,KAAL;AACL,EAAAA,WAAA,UAAA,CAAA,GAAW,UAAA;AACX,EAAAA,WAAA,0BAAA,CAAA,GAA2B,0BAAA;AAC3B,EAAAA,WAAA,2BAAA,CAAA,GAA4B,2BAAA;AAC5B,EAAAA,WAAA,0BAAA,CAAA,GAA2B,0BAAA;AAC3B,EAAAA,WAAA,gBAAA,CAAA,GAAiB,gBAAA;AACjB,EAAAA,WAAA,iCAAA,CAAA,GAAkC,iCAAA;AAClC,EAAAA,WAAA,wBAAA,CAAA,GAAyB,wBAAA;AACzB,EAAAA,WAAA,uBAAA,CAAA,GAAwB,uBAAA;AACxB,EAAAA,WAAA,sBAAA,CAAA,GAAuB,sBAAA;AACvB,EAAAA,WAAA,uBAAA,CAAA,GAAwB,uBAAA;AACxB,EAAAA,WAAA,UAAA,CAAA,GAAW,UAAA;AAXD,EAAA,OAAAA,UAAAA;AAAA,CAAA,EAAA,SAAA,IAAA,EAAA;ACuBL,IAAM,mBAAA,GAAsB,EAAE,MAAA,CAAO;AAAA,EAC1C,EAAA,EAAI,CAAA,CAAE,OAAA,CAAQ,KAAK,CAAA;AAAA,EACnB,KAAA,EAAO,EAAE,MAAA,CAAO;AAAA,IACd,IAAA,EAAM,EAAE,MAAA,EAAO;AAAA,IACf,OAAA,EAAS,EAAE,MAAA,EAAO;AAAA,IAClB,OAAA,EAAS,CAAA,CAAE,MAAA,CAAO,CAAA,CAAE,MAAA,IAAU,CAAA,CAAE,OAAA,EAAS,CAAA,CAAE,QAAA,EAAS;AAAA,IACpD,KAAA,EAAO,CAAA,CAAE,OAAA,EAAQ,CAAE,QAAA,EAAS;AAAA,IAC5B,OAAA,EAAS,CAAA,CAAE,MAAA,EAAO,CAAE,QAAA;AAAS,GAC9B,CAAA;AAAA,EACD,IAAA,EAAM,EAAE,MAAA,CAAO;AAAA,IACb,SAAA,EAAW,EAAE,MAAA,EAAO;AAAA,IACpB,UAAA,EAAY,EAAE,MAAA,EAAO;AAAA,IACrB,UAAA,EAAY,EAAE,MAAA;AAAO,GACtB;AACH,CAAC","file":"index.js","sourcesContent":["/**\n * Standardized error codes shared across CLI, REST and Studio.\n * These values intentionally line up with the codes used by the\n * plugin runtime so adapters can map them to HTTP status codes.\n */\nexport enum ErrorCode {\n  INTERNAL = 'INTERNAL',\n  PLUGIN_PERMISSION_DENIED = 'PLUGIN_PERMISSION_DENIED',\n  PLUGIN_CAPABILITY_MISSING = 'PLUGIN_CAPABILITY_MISSING',\n  PLUGIN_HANDLER_NOT_FOUND = 'PLUGIN_HANDLER_NOT_FOUND',\n  PLUGIN_TIMEOUT = 'PLUGIN_TIMEOUT',\n  PLUGIN_SCHEMA_VALIDATION_FAILED = 'PLUGIN_SCHEMA_VALIDATION_FAILED',\n  PLUGIN_ARTIFACT_FAILED = 'PLUGIN_ARTIFACT_FAILED',\n  PLUGIN_QUOTA_EXCEEDED = 'PLUGIN_QUOTA_EXCEEDED',\n  ARTIFACT_READ_DENIED = 'ARTIFACT_READ_DENIED',\n  ARTIFACT_WRITE_DENIED = 'ARTIFACT_WRITE_DENIED',\n  CONFLICT = 'CONFLICT',\n}\n\n/**\n * Helper describing a compact permission summary.\n */\nexport interface PermissionSummary {\n  fs?: {\n    mode?: string;\n    allowCount?: number;\n    denyCount?: number;\n  };\n  net?: 'none' | { allowHostsCount?: number; denyHostsCount?: number };\n  env?: { allowCount?: number };\n  quotas?: {\n    timeoutMs?: number;\n    memoryMb?: number;\n    cpuMs?: number;\n  };\n  capabilities?: string[];\n}\n\n/**\n * Permissions diff emitted when the runtime compares required\n * vs granted permissions for a failing invocation.\n */\nexport interface PermissionDiff {\n  required?: string[];\n  granted?: string[];\n}\n\n","import { z } from 'zod';\nimport type { PermissionDiff, PermissionSummary } from './error-code';\n\nexport interface EnvelopeMeta {\n  requestId: string;\n  durationMs: number;\n  apiVersion: string;\n  [key: string]: unknown;\n}\n\nexport type SuccessEnvelope<T = unknown> = {\n  ok: true;\n  data: T;\n  meta?: EnvelopeMeta;\n};\n\nexport type ErrorEnvelope = {\n  ok: false;\n  error: {\n    code: string;\n    message: string;\n    details?: Record<string, unknown>;\n    cause?: unknown;\n    traceId?: string;\n  };\n  meta: EnvelopeMeta;\n};\n\nexport const errorEnvelopeSchema = z.object({\n  ok: z.literal(false),\n  error: z.object({\n    code: z.string(),\n    message: z.string(),\n    details: z.record(z.string(), z.unknown()).optional(),\n    cause: z.unknown().optional(),\n    traceId: z.string().optional(),\n  }),\n  meta: z.object({\n    requestId: z.string(),\n    durationMs: z.number(),\n    apiVersion: z.string(),\n  }),\n});\n\n/**\n * Structured error produced by the plugin runtime.\n */\nexport interface PluginErrorEnvelope {\n  status: 'error';\n  http: number;\n  code: string;\n  message: string;\n  details?: Record<string, unknown>;\n  trace?: string;\n  meta: {\n    requestId: string;\n    pluginId: string;\n    pluginVersion: string;\n    routeOrCommand: string;\n    timeMs: number;\n    cpuMs?: number;\n    memMb?: number;\n    perms?: PermissionSummary | PermissionDiff | Record<string, unknown>;\n  };\n}\n\n\n"]}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@kb-labs/rest-api-contracts",
+  "version": "1.0.0",
+  "description": "Shared API contracts for KB Labs REST/CLI/Studio surfaces",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@kb-labs/studio-contracts": "link:../../../kb-labs-studio/packages/studio-contracts",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@kb-labs/devkit": "link:../../../kb-labs-devkit",
+    "@types/node": "^24.3.3",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "clean": "rimraf dist",
+    "lint": "eslint src",
+    "test": "vitest run --passWithNoTests",
+    "lint:fix": "eslint . --fix",
+    "type-check": "tsc --noEmit",
+    "test:watch": "vitest"
+  }
+}