@kb-labs/rest-api-contracts 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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';
+import * as _kb_labs_plugin_contracts from '@kb-labs/plugin-contracts';
+export { StudioConfig, StudioMenuEntry, StudioPageEntry } from '@kb-labs/plugin-contracts';
 
 /**
  * Standardized error codes shared across CLI, REST and Studio.
@@ -82,61 +82,13 @@ declare const errorEnvelopeSchema: z.ZodObject<{
         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;
-    }>;
+    }, z.core.$strip>;
     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;
-    };
-}>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
 /**
  * Structured error produced by the plugin runtime.
  */
@@ -159,6 +111,19 @@ interface PluginErrorEnvelope {
     };
 }
 
+/**
+ * Payload returned by the hello service.
+ */
+interface HelloPayload {
+    schema: 'kb.hello/1';
+    message: string;
+    ts: string;
+}
+/**
+ * Response envelope for GET /hello
+ */
+type HelloResponse = SuccessEnvelope<HelloPayload>;
+
 interface SystemHealthSnapshot {
     schema: 'kb.health/1';
     ts: string;
@@ -235,7 +200,7 @@ interface ReadyComponents {
         stale: boolean;
     };
     plugins: {
-        mounted: number;
+        mounted: boolean;
         inProgress: boolean;
         routeCount: number;
         errors: number;
@@ -268,56 +233,28 @@ type NotReadyResponse = ReadyResponseBase & {
 };
 
 /**
- * @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
+ * Studio plugin entry in the registry.
  */
-interface BatchDataRequest {
-    widgetIds: string[];
+interface StudioPluginEntryV2 {
+    pluginId: string;
+    displayName?: string;
+    pluginVersion?: string;
+    remoteName: string;
+    /** Browser URL for loading remoteEntry.js (relative, proxied through gateway) */
+    remoteEntryUrl: string;
+    /** Absolute filesystem path to dist/widgets/ directory (server-side only, used by gateway) */
+    widgetBundleDir: string;
+    pages: _kb_labs_plugin_contracts.StudioPageEntry[];
+    menus: _kb_labs_plugin_contracts.StudioMenuEntry[];
 }
 /**
- * Batch data response
+ * GET /api/v1/studio/registry 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;
+interface StudioRegistryV2 {
+    schema: 'kb.studio/2';
+    schemaVersion: 2;
+    generatedAt: string;
+    plugins: StudioPluginEntryV2[];
 }
 
 /**
@@ -499,4 +436,129 @@ interface PlatformConfigPayload {
 }
 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 };
+/**
+ * @module @kb-labs/rest-api-contracts/route-schemas
+ * Zod schemas for REST API route-level body/query/response.
+ * Used with fastify-type-provider-zod so route schemas are fully typed.
+ */
+
+declare const ErrorResponseSchema: z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    message: z.ZodOptional<z.ZodString>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+declare const OkResponseSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+}, z.core.$strip>;
+declare const ListJobsQuerySchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        paused: "paused";
+    }>>;
+}, z.core.$strip>;
+declare const JobSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        paused: "paused";
+    }>>;
+    schedule: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+declare const JobsListResponseSchema: z.ZodObject<{
+    jobs: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodEnum<{
+            active: "active";
+            paused: "paused";
+        }>>;
+        schedule: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+}, z.core.$strip>;
+declare const JobResponseSchema: z.ZodObject<{
+    job: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodEnum<{
+            active: "active";
+            paused: "paused";
+        }>>;
+        schedule: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+}, z.core.$strip>;
+declare const JobStatsResponseSchema: z.ZodObject<{
+    stats: z.ZodObject<{
+        total: z.ZodNumber;
+        jobs: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            status: z.ZodOptional<z.ZodEnum<{
+                active: "active";
+                paused: "paused";
+            }>>;
+            schedule: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+declare const JobActionResponseSchema: z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    message: z.ZodString;
+}, z.core.$strip>;
+declare const ListWorkflowsQuerySchema: z.ZodObject<{
+    source: z.ZodOptional<z.ZodEnum<{
+        manifest: "manifest";
+        standalone: "standalone";
+    }>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        paused: "paused";
+        disabled: "disabled";
+    }>>;
+    tags: z.ZodOptional<z.ZodString>;
+    search: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const WorkflowSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+declare const WorkflowsListResponseSchema: z.ZodObject<{
+    workflows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    total: z.ZodNumber;
+}, z.core.$strip>;
+declare const WorkflowResponseSchema: z.ZodObject<{
+    workflow: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+declare const CreateWorkflowBodySchema: z.ZodObject<{
+    spec: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+declare const UpdateWorkflowBodySchema: z.ZodObject<{
+    spec: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        on: z.ZodOptional<z.ZodAny>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        secrets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        jobs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, z.core.$strip>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        paused: "paused";
+        disabled: "disabled";
+    }>>;
+}, z.core.$strip>;
+declare const ScheduleConfigBodySchema: z.ZodObject<{
+    cron: z.ZodString;
+    enabled: z.ZodBoolean;
+    timezone: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const ValidateWorkflowBodySchema: z.ZodObject<{
+    spec: z.ZodAny;
+}, z.core.$strip>;
+declare const HandlersListResponseSchema: z.ZodObject<{
+    handlers: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    total: z.ZodNumber;
+}, z.core.$strip>;
+
+export { type AdapterValue, type CapabilitiesResponse, type ConfigResponse, CreateWorkflowBodySchema, type DevKitHealthPayload, type DevKitHealthSnapshot, type EnvelopeMeta, ErrorCode, type ErrorEnvelope, ErrorResponseSchema, HandlersListResponseSchema, type HeatmapCell, type HelloPayload, type HelloResponse, type HistoricalDataPoint, type InfoResponse, JobActionResponseSchema, JobResponseSchema, JobSchema, JobStatsResponseSchema, JobsListResponseSchema, ListJobsQuerySchema, ListWorkflowsQuerySchema, type MetricsHeatmapPayload, type MetricsHistoryPayload, type NamespaceStats, type NotReadyResponse, OkResponseSchema, type PermissionDiff, type PermissionSummary, type PlatformConfigPayload, type PlatformConfigResponse, type PluginErrorEnvelope, type ReadyComponents, type ReadyResponse, ScheduleConfigBodySchema, type StateBrokerStats, type StateBrokerStatsPayload, type StudioPluginEntryV2, type StudioRegistryV2, type SuccessEnvelope, type SystemCapabilitiesPayload, type SystemConfigPayload, type SystemHealthSnapshot, type SystemInfoPayload, type TenantStats, UpdateWorkflowBodySchema, ValidateWorkflowBodySchema, WorkflowResponseSchema, WorkflowSchema, WorkflowsListResponseSchema, errorEnvelopeSchema };

package/dist/index.js

@@ -1,5 +1,4 @@
 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) => {
@@ -31,7 +30,83 @@ var errorEnvelopeSchema = z.object({
     apiVersion: z.string()
   })
 });
+var ErrorResponseSchema = z.object({
+  ok: z.literal(false),
+  message: z.string().optional(),
+  error: z.object({
+    code: z.string(),
+    message: z.string()
+  })
+});
+var OkResponseSchema = z.object({ ok: z.literal(true) });
+var AnyRecord = z.record(z.string(), z.unknown());
+var ListJobsQuerySchema = z.object({
+  status: z.enum(["active", "paused"]).optional()
+});
+var JobSchema = z.object({
+  id: z.string(),
+  name: z.string().optional(),
+  status: z.enum(["active", "paused"]).optional(),
+  schedule: z.string().optional()
+}).passthrough();
+var JobsListResponseSchema = z.object({
+  jobs: z.array(JobSchema)
+});
+var JobResponseSchema = z.object({
+  job: JobSchema
+});
+var JobStatsResponseSchema = z.object({
+  stats: z.object({
+    total: z.number(),
+    jobs: z.array(JobSchema)
+  })
+});
+var JobActionResponseSchema = z.object({
+  success: z.literal(true),
+  message: z.string()
+});
+var ListWorkflowsQuerySchema = z.object({
+  source: z.enum(["manifest", "standalone"]).optional(),
+  status: z.enum(["active", "paused", "disabled"]).optional(),
+  tags: z.string().optional(),
+  search: z.string().optional()
+});
+var WorkflowSchema = AnyRecord;
+var WorkflowsListResponseSchema = z.object({
+  workflows: z.array(AnyRecord),
+  total: z.number()
+});
+var WorkflowResponseSchema = z.object({
+  workflow: AnyRecord.nullable()
+});
+var CreateWorkflowBodySchema = z.object({
+  spec: AnyRecord
+});
+var UpdateWorkflowBodySchema = z.object({
+  spec: z.object({
+    name: z.string().min(1).optional(),
+    version: z.string().min(1).optional(),
+    description: z.string().optional(),
+    on: z.any().optional(),
+    env: z.record(z.string(), z.string()).optional(),
+    secrets: z.array(z.string().min(1)).optional(),
+    jobs: z.record(z.string().min(1), z.any()).optional()
+  }).optional(),
+  status: z.enum(["active", "paused", "disabled"]).optional()
+});
+var ScheduleConfigBodySchema = z.object({
+  cron: z.string().min(1),
+  enabled: z.boolean(),
+  timezone: z.string().optional()
+});
+var ValidateWorkflowBodySchema = z.object({
+  spec: z.any()
+});
+var HandlersListResponseSchema = z.object({
+  handlers: z.array(AnyRecord),
+  total: z.number()
+});
 
-export { ErrorCode, errorEnvelopeSchema };
+export { CreateWorkflowBodySchema, ErrorCode, ErrorResponseSchema, HandlersListResponseSchema, JobActionResponseSchema, JobResponseSchema, JobSchema, JobStatsResponseSchema, JobsListResponseSchema, ListJobsQuerySchema, ListWorkflowsQuerySchema, OkResponseSchema, ScheduleConfigBodySchema, UpdateWorkflowBodySchema, ValidateWorkflowBodySchema, WorkflowResponseSchema, WorkflowSchema, WorkflowsListResponseSchema, errorEnvelopeSchema };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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"]}
+{"version":3,"sources":["../src/error-code.ts","../src/envelopes.ts","../src/route-schemas.ts"],"names":["ErrorCode","z"],"mappings":"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","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","/**\n * @module @kb-labs/rest-api-contracts/route-schemas\n * Zod schemas for REST API route-level body/query/response.\n * Used with fastify-type-provider-zod so route schemas are fully typed.\n */\n\nimport { z } from 'zod';\n\n// ── Shared ────────────────────────────────────────────────────────────────────\n\nexport const ErrorResponseSchema = z.object({\n  ok: z.literal(false),\n  message: z.string().optional(),\n  error: z.object({\n    code: z.string(),\n    message: z.string(),\n  }),\n});\n\nexport const OkResponseSchema = z.object({ ok: z.literal(true) });\n\nconst AnyRecord = z.record(z.string(), z.unknown());\n\n// ── Jobs ──────────────────────────────────────────────────────────────────────\n\nexport const ListJobsQuerySchema = z.object({\n  status: z.enum(['active', 'paused']).optional(),\n});\n\nexport const JobSchema = z.object({\n  id: z.string(),\n  name: z.string().optional(),\n  status: z.enum(['active', 'paused']).optional(),\n  schedule: z.string().optional(),\n}).passthrough();\n\nexport const JobsListResponseSchema = z.object({\n  jobs: z.array(JobSchema),\n});\n\nexport const JobResponseSchema = z.object({\n  job: JobSchema,\n});\n\nexport const JobStatsResponseSchema = z.object({\n  stats: z.object({\n    total: z.number(),\n    jobs: z.array(JobSchema),\n  }),\n});\n\nexport const JobActionResponseSchema = z.object({\n  success: z.literal(true),\n  message: z.string(),\n});\n\n// ── Workflows ─────────────────────────────────────────────────────────────────\n\nexport const ListWorkflowsQuerySchema = z.object({\n  source: z.enum(['manifest', 'standalone']).optional(),\n  status: z.enum(['active', 'paused', 'disabled']).optional(),\n  tags: z.string().optional(),\n  search: z.string().optional(),\n});\n\nexport const WorkflowSchema = AnyRecord;\n\nexport const WorkflowsListResponseSchema = z.object({\n  workflows: z.array(AnyRecord),\n  total: z.number(),\n});\n\nexport const WorkflowResponseSchema = z.object({\n  workflow: AnyRecord.nullable(),\n});\n\nexport const CreateWorkflowBodySchema = z.object({\n  spec: AnyRecord,\n});\n\nexport const UpdateWorkflowBodySchema = z.object({\n  spec: z.object({\n    name: z.string().min(1).optional(),\n    version: z.string().min(1).optional(),\n    description: z.string().optional(),\n    on: z.any().optional(),\n    env: z.record(z.string(), z.string()).optional(),\n    secrets: z.array(z.string().min(1)).optional(),\n    jobs: z.record(z.string().min(1), z.any()).optional(),\n  }).optional(),\n  status: z.enum(['active', 'paused', 'disabled']).optional(),\n});\n\nexport const ScheduleConfigBodySchema = z.object({\n  cron: z.string().min(1),\n  enabled: z.boolean(),\n  timezone: z.string().optional(),\n});\n\nexport const ValidateWorkflowBodySchema = z.object({\n  spec: z.any(),\n});\n\nexport const HandlersListResponseSchema = z.object({\n  handlers: z.array(AnyRecord),\n  total: z.number(),\n});\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kb-labs/rest-api-contracts",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Shared API contracts for KB Labs REST/CLI/Studio surfaces",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,12 +15,22 @@
     "dist",
     "README.md"
   ],
+  "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"
+  },
   "dependencies": {
-    "@kb-labs/studio-contracts": "link:../../../kb-labs-studio/packages/studio-contracts",
-    "zod": "^3.23.8"
+    "@kb-labs/plugin-contracts": "^1.1.0",
+    "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@kb-labs/devkit": "link:../../../kb-labs-devkit",
+    "@kb-labs/devkit": "link:../../../../infra/kb-labs-devkit",
     "@types/node": "^24.3.3",
     "rimraf": "^6.0.1",
     "tsup": "^8.5.0",
@@ -33,15 +43,5 @@
   },
   "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"
   }
-}
+}