@xtrape/capsule-contracts-node 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +48 -2
  2. package/dist/index.cjs +56 -19
  3. package/dist/index.d.cts +728 -52
  4. package/dist/index.d.ts +728 -52
  5. package/dist/index.js +48 -19
  6. package/package.json +10 -9
package/README.md CHANGED
@@ -41,7 +41,7 @@ The package currently exports:
41
41
  - Zod itself as `z` for consumers that want one compatible Zod instance.
42
42
  - Status enum arrays and types: `AgentStatus`, `CapsuleServiceStatus`,
43
43
  `HealthStatus`, `CommandStatus`, `DangerLevel`, `AuditActorType`,
44
- `AuditResult`, `TokenStatus`.
44
+ `AuditResult`, `TokenStatus`, `AgentMode`.
45
45
  - Admin schemas: users, sessions, registration token requests/responses.
46
46
  - Agent schemas: registration, heartbeat, service report, command result.
47
47
  - Capsule Service schemas: manifest, health, config, action, service detail.
@@ -58,7 +58,7 @@ import { RegisterAgentRequestSchema } from "@xtrape/capsule-contracts-node";
58
58
  const request = RegisterAgentRequestSchema.parse(input);
59
59
 
60
60
  // request.registrationToken starts with opstage_reg_
61
- // request.agent.mode is embedded
61
+ // request.agent.mode is embedded or ophub
62
62
  ```
63
63
 
64
64
  Lowercase aliases are also exported for backend compatibility:
@@ -69,6 +69,52 @@ import { registerAgentRequestSchema } from "@xtrape/capsule-contracts-node";
69
69
  const request = registerAgentRequestSchema.parse(input);
70
70
  ```
71
71
 
72
+ ## v0.3 OpHub and Metadata
73
+
74
+ v0.3 adds the experimental `ophub` Agent mode. `sidecar` and `base-image`
75
+ remain OpHub deployment forms, but the wire contract should use
76
+ `mode: "ophub"` for an OpHub that represents one or more local Capsule
77
+ Services.
78
+
79
+ ```ts
80
+ import { RegisterAgentRequestSchema, ServiceReportRequestSchema } from "@xtrape/capsule-contracts-node";
81
+
82
+ RegisterAgentRequestSchema.parse({
83
+ registrationToken: "opstage_reg_...",
84
+ agent: {
85
+ code: "ophub-a",
86
+ name: "OpHub A",
87
+ mode: "ophub",
88
+ runtime: "go",
89
+ },
90
+ });
91
+
92
+ ServiceReportRequestSchema.parse({
93
+ services: [
94
+ {
95
+ code: "svc-one",
96
+ name: "Service One",
97
+ version: "0.3.0",
98
+ runtime: "nodejs",
99
+ manifest: {
100
+ kind: "CapsuleService",
101
+ code: "svc-one",
102
+ name: "Service One",
103
+ version: "0.3.0",
104
+ runtime: "nodejs",
105
+ agentMode: "ophub",
106
+ capabilities: [{ name: "inventory.read", label: "Inventory read" }],
107
+ events: [{ name: "inventory.changed", direction: "publish", designOnly: true }],
108
+ },
109
+ },
110
+ ],
111
+ });
112
+ ```
113
+
114
+ Capability metadata is implemented as declarative service metadata. Event
115
+ metadata is intentionally a foundation for future Capsule Bus work; `designOnly`
116
+ events must not be treated as a working event bus.
117
+
72
118
  ## Validate Service Report
73
119
 
74
120
  ```ts
package/dist/index.cjs CHANGED
@@ -27,6 +27,8 @@ __export(index_exports, {
27
27
  AdminSessionSchema: () => AdminSessionSchema,
28
28
  AgentHeartbeatRequestSchema: () => AgentHeartbeatRequestSchema,
29
29
  AgentHeartbeatResponseSchema: () => AgentHeartbeatResponseSchema,
30
+ AgentMode: () => AgentMode,
31
+ AgentModeSchema: () => AgentModeSchema,
30
32
  AgentSchema: () => AgentSchema,
31
33
  AgentStatus: () => AgentStatus,
32
34
  AgentStatusSchema: () => AgentStatusSchema,
@@ -54,6 +56,7 @@ __export(index_exports, {
54
56
  DangerLevelSchema: () => DangerLevelSchema,
55
57
  DashboardSummarySchema: () => DashboardSummarySchema,
56
58
  ErrorCode: () => ErrorCode,
59
+ EventMetadataSchema: () => EventMetadataSchema,
57
60
  HealthReportInputSchema: () => HealthReportInputSchema,
58
61
  HealthReportSchema: () => HealthReportSchema,
59
62
  HealthStatus: () => HealthStatus,
@@ -66,6 +69,9 @@ __export(index_exports, {
66
69
  ReportCommandResultRequestSchema: () => ReportCommandResultRequestSchema,
67
70
  ReportedServiceSchema: () => ReportedServiceSchema,
68
71
  RuntimeKindSchema: () => RuntimeKindSchema,
72
+ ServiceCapabilitySchema: () => ServiceCapabilitySchema,
73
+ ServiceKind: () => ServiceKind,
74
+ ServiceKindSchema: () => ServiceKindSchema,
69
75
  ServiceReportRequestSchema: () => ServiceReportRequestSchema,
70
76
  SystemHealthSchema: () => SystemHealthSchema,
71
77
  SystemVersionSchema: () => SystemVersionSchema,
@@ -80,6 +86,7 @@ __export(index_exports, {
80
86
  createActionCommandRequestSchema: () => createActionCommandRequestSchema,
81
87
  createRegistrationTokenRequestSchema: () => createRegistrationTokenRequestSchema,
82
88
  createUserRequestSchema: () => createUserRequestSchema,
89
+ eventMetadataSchema: () => eventMetadataSchema,
83
90
  healthReportInputSchema: () => healthReportInputSchema,
84
91
  paginate: () => paginate,
85
92
  parseSort: () => parseSort,
@@ -87,6 +94,7 @@ __export(index_exports, {
87
94
  reportCommandResultRequestSchema: () => reportCommandResultRequestSchema,
88
95
  reportedServiceSchema: () => reportedServiceSchema,
89
96
  resetUserPasswordRequestSchema: () => resetUserPasswordRequestSchema,
97
+ serviceCapabilitySchema: () => serviceCapabilitySchema,
90
98
  serviceReportRequestSchema: () => serviceReportRequestSchema,
91
99
  updateUserRequestSchema: () => updateUserRequestSchema,
92
100
  z: () => import_zod.z
@@ -101,27 +109,16 @@ var DangerLevel = ["LOW", "MEDIUM", "HIGH"];
101
109
  var AuditActorType = ["USER", "AGENT", "SYSTEM"];
102
110
  var AuditResult = ["SUCCESS", "FAILURE"];
103
111
  var TokenStatus = ["ACTIVE", "REVOKED", "EXPIRED", "USED"];
104
- var ErrorCode = {
105
- INTERNAL_ERROR: "INTERNAL_ERROR",
106
- VALIDATION_FAILED: "VALIDATION_FAILED",
107
- UNAUTHORIZED: "UNAUTHORIZED",
108
- FORBIDDEN: "FORBIDDEN",
109
- NOT_FOUND: "NOT_FOUND",
110
- CONFLICT: "CONFLICT",
111
- CSRF_INVALID: "CSRF_INVALID",
112
- ACTION_REQUIRES_CONFIRMATION: "ACTION_REQUIRES_CONFIRMATION",
113
- COMMAND_EXPIRED: "COMMAND_EXPIRED",
114
- TOKEN_REVOKED: "TOKEN_REVOKED",
115
- TOKEN_EXPIRED: "TOKEN_EXPIRED",
116
- AGENT_REVOKED: "AGENT_REVOKED",
117
- AGENT_DISABLED: "AGENT_DISABLED"
118
- };
112
+ var AgentMode = ["embedded", "ophub"];
113
+ var ServiceKind = ["business", "infrastructure", "system"];
114
+ var ServiceKindSchema = import_zod.z.enum(ServiceKind);
119
115
  var AnyJson = import_zod.z.record(import_zod.z.any());
120
116
  var AgentStatusSchema = import_zod.z.enum(AgentStatus);
121
117
  var CapsuleServiceStatusSchema = import_zod.z.enum(CapsuleServiceStatus);
122
118
  var HealthStatusSchema = import_zod.z.enum(HealthStatus);
123
119
  var CommandStatusSchema = import_zod.z.enum(CommandStatus);
124
120
  var DangerLevelSchema = import_zod.z.enum(DangerLevel).default("LOW");
121
+ var AgentModeSchema = import_zod.z.enum(AgentMode);
125
122
  var UserSchema = import_zod.z.object({ id: import_zod.z.string().startsWith("usr_"), username: import_zod.z.string(), displayName: import_zod.z.string().nullable().optional(), createdAt: import_zod.z.string(), updatedAt: import_zod.z.string() });
126
123
  var UserRole = import_zod.z.enum(["owner", "operator", "viewer"]);
127
124
  var createUserRequestSchema = import_zod.z.object({ username: import_zod.z.string().min(1), password: import_zod.z.string().min(12), displayName: import_zod.z.string().optional(), role: UserRole.default("viewer") });
@@ -130,24 +127,41 @@ var resetUserPasswordRequestSchema = import_zod.z.object({ password: import_zod.
130
127
  var AdminLoginRequestSchema = import_zod.z.object({ username: import_zod.z.string().min(1), password: import_zod.z.string().min(1) });
131
128
  var adminLoginRequestSchema = AdminLoginRequestSchema;
132
129
  var AdminSessionSchema = import_zod.z.object({ user: UserSchema, csrfToken: import_zod.z.string(), expiresAt: import_zod.z.string() });
133
- var AgentSchema = import_zod.z.object({ id: import_zod.z.string().startsWith("agt_"), code: import_zod.z.string(), name: import_zod.z.string().nullable().optional(), mode: import_zod.z.enum(["embedded", "sidecar", "external"]), runtime: import_zod.z.string().nullable().optional(), status: AgentStatusSchema, lastHeartbeatAt: import_zod.z.string().nullable().optional(), createdAt: import_zod.z.string(), updatedAt: import_zod.z.string() });
130
+ var AgentSchema = import_zod.z.object({ id: import_zod.z.string().startsWith("agt_"), code: import_zod.z.string(), name: import_zod.z.string().nullable().optional(), mode: AgentModeSchema, runtime: import_zod.z.string().nullable().optional(), status: AgentStatusSchema, lastHeartbeatAt: import_zod.z.string().nullable().optional(), createdAt: import_zod.z.string(), updatedAt: import_zod.z.string() });
134
131
  var RegistrationTokenSchema = import_zod.z.object({ id: import_zod.z.string().startsWith("tok_"), name: import_zod.z.string(), status: import_zod.z.enum(TokenStatus), expiresAt: import_zod.z.string().nullable().optional(), usedAt: import_zod.z.string().nullable().optional(), createdAt: import_zod.z.string() });
135
132
  var CreateRegistrationTokenRequestSchema = import_zod.z.object({ name: import_zod.z.string().default("Default registration token").optional(), expiresInSeconds: import_zod.z.number().int().min(60).optional() });
136
133
  var createRegistrationTokenRequestSchema = CreateRegistrationTokenRequestSchema;
137
134
  var CreateRegistrationTokenResponseSchema = RegistrationTokenSchema.extend({ rawToken: import_zod.z.string().startsWith("opstage_reg_") });
138
- var CapsuleManifestSchema = import_zod.z.object({ kind: import_zod.z.literal("CapsuleService"), schemaVersion: import_zod.z.string().default("1.0").optional(), code: import_zod.z.string().min(1), name: import_zod.z.string().min(1), description: import_zod.z.string().optional(), version: import_zod.z.string().min(1), runtime: import_zod.z.enum(["nodejs", "java", "python", "go", "other"]), agentMode: import_zod.z.enum(["embedded", "sidecar", "external"]), capabilities: import_zod.z.array(import_zod.z.string()).optional(), labels: import_zod.z.record(import_zod.z.string()).optional() }).passthrough();
135
+ var ServiceCapabilitySchema = import_zod.z.object({ name: import_zod.z.string().min(1).max(120), label: import_zod.z.string().max(200).optional(), description: import_zod.z.string().max(2e3).optional(), metadata: AnyJson.optional() });
136
+ var serviceCapabilitySchema = ServiceCapabilitySchema;
137
+ var EventMetadataSchema = import_zod.z.object({ name: import_zod.z.string().min(1).max(160), direction: import_zod.z.enum(["publish", "subscribe"]).optional(), schema: AnyJson.optional(), designOnly: import_zod.z.boolean().default(true), metadata: AnyJson.optional() });
138
+ var eventMetadataSchema = EventMetadataSchema;
139
+ var CapsuleManifestSchema = import_zod.z.object({ kind: import_zod.z.literal("CapsuleService"), schemaVersion: import_zod.z.string().default("1.0").optional(), code: import_zod.z.string().min(1), name: import_zod.z.string().min(1), description: import_zod.z.string().optional(), version: import_zod.z.string().min(1), runtime: import_zod.z.enum(["nodejs", "java", "python", "go", "other"]), agentMode: AgentModeSchema, capabilities: import_zod.z.array(import_zod.z.union([import_zod.z.string(), ServiceCapabilitySchema])).optional(), events: import_zod.z.array(EventMetadataSchema).optional(), labels: import_zod.z.record(import_zod.z.string()).optional() }).passthrough();
139
140
  var HealthReportInputSchema = import_zod.z.object({ status: HealthStatusSchema, message: import_zod.z.string().optional(), details: AnyJson.optional() });
140
141
  var healthReportInputSchema = HealthReportInputSchema;
141
142
  var ConfigItemInputSchema = import_zod.z.object({ key: import_zod.z.string(), label: import_zod.z.string().optional(), type: import_zod.z.string(), source: import_zod.z.string().optional(), editable: import_zod.z.boolean().optional(), sensitive: import_zod.z.boolean().optional(), valuePreview: import_zod.z.string().optional(), defaultValue: import_zod.z.string().optional(), secretRef: import_zod.z.string().optional() });
142
143
  var configItemInputSchema = ConfigItemInputSchema;
143
144
  var ActionDefinitionInputSchema = import_zod.z.object({ name: import_zod.z.string(), label: import_zod.z.string(), description: import_zod.z.string().optional(), dangerLevel: import_zod.z.enum(DangerLevel).default("LOW").optional(), requiresConfirmation: import_zod.z.boolean().optional(), category: import_zod.z.string().optional(), order: import_zod.z.number().int().optional(), inputSchema: AnyJson.optional(), outputSchema: AnyJson.optional(), timeoutSeconds: import_zod.z.number().int().positive().optional() });
144
145
  var actionDefinitionInputSchema = ActionDefinitionInputSchema;
145
- var ReportedServiceSchema = import_zod.z.object({ code: import_zod.z.string().min(1).max(80), name: import_zod.z.string().min(1).max(200), description: import_zod.z.string().max(2e3).optional(), version: import_zod.z.string().max(80).optional(), runtime: import_zod.z.string().optional(), manifest: AnyJson, health: HealthReportInputSchema.optional(), configs: import_zod.z.array(ConfigItemInputSchema).optional(), actions: import_zod.z.array(ActionDefinitionInputSchema).optional() });
146
+ var ReportedServiceSchema = import_zod.z.object({
147
+ code: import_zod.z.string().min(1).max(80),
148
+ name: import_zod.z.string().min(1).max(200),
149
+ description: import_zod.z.string().max(2e3).optional(),
150
+ version: import_zod.z.string().max(80).optional(),
151
+ runtime: import_zod.z.string().optional(),
152
+ manifest: AnyJson,
153
+ capabilities: import_zod.z.array(ServiceCapabilitySchema).optional(),
154
+ events: import_zod.z.array(EventMetadataSchema).optional(),
155
+ health: HealthReportInputSchema.optional(),
156
+ configs: import_zod.z.array(ConfigItemInputSchema).optional(),
157
+ actions: import_zod.z.array(ActionDefinitionInputSchema).optional(),
158
+ serviceKind: ServiceKindSchema.optional()
159
+ });
146
160
  var reportedServiceSchema = ReportedServiceSchema;
147
161
  var ServiceReportRequestSchema = import_zod.z.object({ services: import_zod.z.array(ReportedServiceSchema).min(1) });
148
162
  var serviceReportRequestSchema = ServiceReportRequestSchema;
149
163
  var RuntimeKindSchema = import_zod.z.enum(["nodejs", "java", "python", "go", "other"]);
150
- var RegisterAgentRequestSchema = import_zod.z.object({ registrationToken: import_zod.z.string().startsWith("opstage_reg_"), agent: import_zod.z.object({ code: import_zod.z.string(), name: import_zod.z.string().optional(), mode: import_zod.z.literal("embedded"), runtime: RuntimeKindSchema.optional() }), service: ReportedServiceSchema.optional() });
164
+ var RegisterAgentRequestSchema = import_zod.z.object({ registrationToken: import_zod.z.string().startsWith("opstage_reg_"), agent: import_zod.z.object({ code: import_zod.z.string(), name: import_zod.z.string().optional(), mode: AgentModeSchema.default("embedded"), runtime: RuntimeKindSchema.or(import_zod.z.string()).optional() }), service: ReportedServiceSchema.optional() });
151
165
  var registerAgentRequestSchema = RegisterAgentRequestSchema;
152
166
  var RegisterAgentResponseSchema = import_zod.z.object({ agentId: import_zod.z.string().startsWith("agt_"), agentToken: import_zod.z.string().startsWith("opstage_agent_"), heartbeatIntervalSeconds: import_zod.z.number().int(), commandPollIntervalSeconds: import_zod.z.number().int() });
153
167
  var AgentHeartbeatResponseSchema = import_zod.z.object({ heartbeatIntervalSeconds: import_zod.z.number().int(), commandPollIntervalSeconds: import_zod.z.number().int() });
@@ -203,6 +217,21 @@ function parseSort(value, allowed) {
203
217
  function paginate(items, page, pageSize, total) {
204
218
  return { data: items, pagination: { page, pageSize, total } };
205
219
  }
220
+ var ErrorCode = {
221
+ INTERNAL_ERROR: "INTERNAL_ERROR",
222
+ VALIDATION_FAILED: "VALIDATION_FAILED",
223
+ UNAUTHORIZED: "UNAUTHORIZED",
224
+ FORBIDDEN: "FORBIDDEN",
225
+ NOT_FOUND: "NOT_FOUND",
226
+ CONFLICT: "CONFLICT",
227
+ CSRF_INVALID: "CSRF_INVALID",
228
+ ACTION_REQUIRES_CONFIRMATION: "ACTION_REQUIRES_CONFIRMATION",
229
+ COMMAND_EXPIRED: "COMMAND_EXPIRED",
230
+ TOKEN_REVOKED: "TOKEN_REVOKED",
231
+ TOKEN_EXPIRED: "TOKEN_EXPIRED",
232
+ AGENT_REVOKED: "AGENT_REVOKED",
233
+ AGENT_DISABLED: "AGENT_DISABLED"
234
+ };
206
235
  // Annotate the CommonJS export names for ESM import in node:
207
236
  0 && (module.exports = {
208
237
  ActionDefinitionInputSchema,
@@ -212,6 +241,8 @@ function paginate(items, page, pageSize, total) {
212
241
  AdminSessionSchema,
213
242
  AgentHeartbeatRequestSchema,
214
243
  AgentHeartbeatResponseSchema,
244
+ AgentMode,
245
+ AgentModeSchema,
215
246
  AgentSchema,
216
247
  AgentStatus,
217
248
  AgentStatusSchema,
@@ -239,6 +270,7 @@ function paginate(items, page, pageSize, total) {
239
270
  DangerLevelSchema,
240
271
  DashboardSummarySchema,
241
272
  ErrorCode,
273
+ EventMetadataSchema,
242
274
  HealthReportInputSchema,
243
275
  HealthReportSchema,
244
276
  HealthStatus,
@@ -251,6 +283,9 @@ function paginate(items, page, pageSize, total) {
251
283
  ReportCommandResultRequestSchema,
252
284
  ReportedServiceSchema,
253
285
  RuntimeKindSchema,
286
+ ServiceCapabilitySchema,
287
+ ServiceKind,
288
+ ServiceKindSchema,
254
289
  ServiceReportRequestSchema,
255
290
  SystemHealthSchema,
256
291
  SystemVersionSchema,
@@ -265,6 +300,7 @@ function paginate(items, page, pageSize, total) {
265
300
  createActionCommandRequestSchema,
266
301
  createRegistrationTokenRequestSchema,
267
302
  createUserRequestSchema,
303
+ eventMetadataSchema,
268
304
  healthReportInputSchema,
269
305
  paginate,
270
306
  parseSort,
@@ -272,6 +308,7 @@ function paginate(items, page, pageSize, total) {
272
308
  reportCommandResultRequestSchema,
273
309
  reportedServiceSchema,
274
310
  resetUserPasswordRequestSchema,
311
+ serviceCapabilitySchema,
275
312
  serviceReportRequestSchema,
276
313
  updateUserRequestSchema,
277
314
  z