@xtrape/capsule-contracts-node 0.1.0-public-review.1 → 0.2.0

package/README.md

@@ -48,7 +48,7 @@ The package currently exports:
 - Command schemas: create command, command detail, command result.
 - Audit and dashboard schemas.
 - System health/version schemas.
-- Helpers: `newId`, `parseSort`, `paginate`, `HttpError`, `ListQueryBase`.
+- Helpers: `parseSort`, `paginate`, `HttpError`, `ListQueryBase`.
 
 ## Validate Agent Registration
 
@@ -249,16 +249,27 @@ Currently exported codes include:
 
 See the OpenAPI contract and docs site for endpoint-specific errors.
 
-## ID Helpers
+## ID generation
+
+This package validates IDs at the wire boundary (via Zod) but does **not** mint
+them. Until v0.1.x there was a small `newId()` helper plus an `idPrefixes`
+table; both were removed in `0.2.0` to keep the contracts surface focused on
+the wire spec — see [`CHANGELOG.md`](./CHANGELOG.md) and the
+"Breaking changes" section at the top of this README.
+
+Consumers that need local ID generation should provide their own factory.
+Example using `nanoid` directly:
 
 ```ts
-import { newId } from "@xtrape/capsule-contracts-node";
+import { customAlphabet } from "nanoid";
 
-const commandId = newId("cmd_");
+const idBody = customAlphabet("0123456789abcdefghijklmnopqrstuvwxyz", 21);
+const commandId = `cmd_${idBody()}`;
 ```
 
-Supported prefixes include `wks_`, `usr_`, `agt_`, `tok_`, `svc_`, `hlr_`,
-`cfg_`, `act_`, `cmd_`, `crs_`, and `aud_`.
+Documented ID prefixes in use across CE and the Agent SDK include `wks_`,
+`usr_`, `agt_`, `tok_`, `svc_`, `hlr_`, `cfg_`, `act_`, `cmd_`, `crs_`, and
+`aud_`. These are enforced by the Zod schemas via `z.string().startsWith(...)`.
 
 ## List Helpers
 
@@ -290,10 +301,24 @@ const response = paginate(items, query.page, query.pageSize, total);
 
 | Package                                | Compatible with                          |
 | -------------------------------------- | ---------------------------------------- |
+| `@xtrape/capsule-contracts-node@0.2.x` | Opstage CE `0.2.x` and Agent SDK `0.2.x` |
 | `@xtrape/capsule-contracts-node@0.1.x` | Opstage CE `0.1.x` and Agent SDK `0.1.x` |
 
-During Public Review and Public Preview, keep CE, Agent SDK, and Contracts on
-matching minor versions. The wire protocol may still evolve before `v1.0`.
+Pin matching minor versions across CE, Agent SDK, and Contracts. The wire
+protocol may still evolve before `v1.0`.
+
+## Breaking changes in `0.2.0`
+
+- **`newId()` removed.** The helper minted random IDs with a prefix; it was
+  never used by CE (entity IDs are minted in the backend). External consumers
+  that imported `newId` must wire their own factory — see the
+  [ID generation](#id-generation) section above.
+- **`idPrefixes` constant and `IdPrefix` type removed.** Same rationale.
+- **`nanoid` runtime dependency removed** as a consequence. Consumers that
+  relied on a transitive `nanoid` install must now add it directly.
+
+The wire schemas themselves are **unchanged** between `0.1.x` and `0.2.x`;
+existing `0.1.x` agents continue to validate against a `0.2.x` backend.
 
 ## Schema Stability
 
@@ -309,7 +334,7 @@ guarantees per schema group are:
 | `ActionPrepareResultSchema`                                                                                      | Provisional | Added in `0.1.0-public-review.0`. Field shape may still tighten before `v1.0`.                                                                                       |
 | `Command.type` enum                                                                                              |  Evolving  | Currently `ACTION_PREPARE` / `ACTION_EXECUTE`. New types may be added.                                                                                                |
 | Error codes (`ErrorCode`)                                                                                        |  Evolving  | New codes may be added. Existing codes will not change meaning before `v1.0`.                                                                                        |
-| Helpers (`newId`, `parseSort`, `paginate`, `HttpError`, `ListQueryBase`)                                         | Provisional | Helpful for backend-style consumers but not strictly part of the wire spec; may move to a separate utility package — see [#8](https://github.com/xtrape-com/xtrape-capsule-contracts-node/issues/8). |
+| Helpers (`parseSort`, `paginate`, `HttpError`, `ListQueryBase`)                                                  | Provisional | Helpful for backend-style consumers but not strictly part of the wire spec; may move to a separate utility package in a future minor. (`newId` / `idPrefixes` / `IdPrefix` were removed in `0.2.0` — see "Breaking changes in `0.2.0`" above.) |
 
 **Until `v1.0`**, pin to a single minor across CE / Agent SDK / Contracts.
 Breaking changes will be called out in `CHANGELOG.md`.

package/dist/index.cjs

@@ -81,8 +81,6 @@ __export(index_exports, {
   createRegistrationTokenRequestSchema: () => createRegistrationTokenRequestSchema,
   createUserRequestSchema: () => createUserRequestSchema,
   healthReportInputSchema: () => healthReportInputSchema,
-  idPrefixes: () => idPrefixes,
-  newId: () => newId,
   paginate: () => paginate,
   parseSort: () => parseSort,
   registerAgentRequestSchema: () => registerAgentRequestSchema,
@@ -94,7 +92,6 @@ __export(index_exports, {
   z: () => import_zod.z
 });
 module.exports = __toCommonJS(index_exports);
-var import_nanoid = require("nanoid");
 var import_zod = require("zod");
 var AgentStatus = ["PENDING", "ONLINE", "OFFLINE", "DISABLED", "REVOKED"];
 var CapsuleServiceStatus = ["UNKNOWN", "HEALTHY", "UNHEALTHY", "STALE", "OFFLINE"];
@@ -119,11 +116,6 @@ var ErrorCode = {
   AGENT_REVOKED: "AGENT_REVOKED",
   AGENT_DISABLED: "AGENT_DISABLED"
 };
-var idPrefixes = ["wks_", "usr_", "agt_", "tok_", "svc_", "hlr_", "cfg_", "act_", "cmd_", "crs_", "aud_"];
-var NANO = (0, import_nanoid.customAlphabet)("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_-", 21);
-function newId(prefix) {
-  return `${prefix}${NANO()}`;
-}
 var AnyJson = import_zod.z.record(import_zod.z.any());
 var AgentStatusSchema = import_zod.z.enum(AgentStatus);
 var CapsuleServiceStatusSchema = import_zod.z.enum(CapsuleServiceStatus);
@@ -274,8 +266,6 @@ function paginate(items, page, pageSize, total) {
   createRegistrationTokenRequestSchema,
   createUserRequestSchema,
   healthReportInputSchema,
-  idPrefixes,
-  newId,
   paginate,
   parseSort,
   registerAgentRequestSchema,

package/dist/index.d.cts

@@ -33,10 +33,6 @@ declare const ErrorCode: {
     readonly AGENT_DISABLED: "AGENT_DISABLED";
 };
 type ErrorCode = typeof ErrorCode[keyof typeof ErrorCode];
-declare const idPrefixes: readonly ["wks_", "usr_", "agt_", "tok_", "svc_", "hlr_", "cfg_", "act_", "cmd_", "crs_", "aud_"];
-type IdPrefix = typeof idPrefixes[number];
-
-declare function newId<P extends IdPrefix>(prefix: P): `${P}${string}`;
 declare const AnyJson: z.ZodRecord<z.ZodString, z.ZodAny>;
 declare const AgentStatusSchema: z.ZodEnum<["PENDING", "ONLINE", "OFFLINE", "DISABLED", "REVOKED"]>;
 declare const CapsuleServiceStatusSchema: z.ZodEnum<["UNKNOWN", "HEALTHY", "UNHEALTHY", "STALE", "OFFLINE"]>;
@@ -2781,4 +2777,4 @@ declare function paginate<T>(items: T[], page: number, pageSize: number, total:
     };
 };
 
-export { type ActionDefinition, type ActionDefinitionInput, ActionDefinitionInputSchema, ActionDefinitionSchema, type ActionPrepareResult, ActionPrepareResultSchema, type AdminLoginRequest, AdminLoginRequestSchema, type AdminSession, AdminSessionSchema, type Agent, type AgentHeartbeatRequest, AgentHeartbeatRequestSchema, type AgentHeartbeatResponse, AgentHeartbeatResponseSchema, AgentSchema, AgentStatus, AgentStatusSchema, AnyJson, AuditActorType, type AuditEvent, AuditEventSchema, AuditResult, type CapsuleManifest, CapsuleManifestSchema, type CapsuleService, type CapsuleServiceDetail, CapsuleServiceDetailSchema, CapsuleServiceSchema, CapsuleServiceStatus, CapsuleServiceStatusSchema, type Command, type CommandDetail, CommandDetailSchema, type CommandResult, CommandResultSchema, CommandSchema, CommandStatus, CommandStatusSchema, type CommandType, CommandTypeSchema, type ConfigItem, type ConfigItemInput, ConfigItemInputSchema, ConfigItemSchema, type CreateActionCommandRequest, CreateActionCommandRequestSchema, type CreateRegistrationTokenRequest, CreateRegistrationTokenRequestSchema, type CreateRegistrationTokenResponse, CreateRegistrationTokenResponseSchema, type CreateUserRequest, DangerLevel, DangerLevelSchema, type DashboardSummary, DashboardSummarySchema, ErrorCode, type ErrorEnvelope, type HealthReport, type HealthReportInput, HealthReportInputSchema, HealthReportSchema, HealthStatus, HealthStatusSchema, HttpError, type IdPrefix, ListQueryBase, type Pagination, type RegisterAgentRequest, RegisterAgentRequestSchema, type RegisterAgentResponse, RegisterAgentResponseSchema, type RegistrationToken, RegistrationTokenSchema, type ReportCommandResultRequest, ReportCommandResultRequestSchema, type ReportedService, ReportedServiceSchema, type ResetUserPasswordRequest, type RuntimeKind, RuntimeKindSchema, type ServiceReportRequest, ServiceReportRequestSchema, type SuccessEnvelope, type SystemHealth, SystemHealthSchema, type SystemVersion, SystemVersionSchema, TokenStatus, type UpdateUserRequest, type User, UserRole, UserSchema, actionDefinitionInputSchema, actionPrepareResultSchema, adminLoginRequestSchema, agentHeartbeatRequestSchema, configItemInputSchema, createActionCommandRequestSchema, createRegistrationTokenRequestSchema, createUserRequestSchema, healthReportInputSchema, idPrefixes, newId, paginate, parseSort, registerAgentRequestSchema, reportCommandResultRequestSchema, reportedServiceSchema, resetUserPasswordRequestSchema, serviceReportRequestSchema, updateUserRequestSchema };
+export { type ActionDefinition, type ActionDefinitionInput, ActionDefinitionInputSchema, ActionDefinitionSchema, type ActionPrepareResult, ActionPrepareResultSchema, type AdminLoginRequest, AdminLoginRequestSchema, type AdminSession, AdminSessionSchema, type Agent, type AgentHeartbeatRequest, AgentHeartbeatRequestSchema, type AgentHeartbeatResponse, AgentHeartbeatResponseSchema, AgentSchema, AgentStatus, AgentStatusSchema, AnyJson, AuditActorType, type AuditEvent, AuditEventSchema, AuditResult, type CapsuleManifest, CapsuleManifestSchema, type CapsuleService, type CapsuleServiceDetail, CapsuleServiceDetailSchema, CapsuleServiceSchema, CapsuleServiceStatus, CapsuleServiceStatusSchema, type Command, type CommandDetail, CommandDetailSchema, type CommandResult, CommandResultSchema, CommandSchema, CommandStatus, CommandStatusSchema, type CommandType, CommandTypeSchema, type ConfigItem, type ConfigItemInput, ConfigItemInputSchema, ConfigItemSchema, type CreateActionCommandRequest, CreateActionCommandRequestSchema, type CreateRegistrationTokenRequest, CreateRegistrationTokenRequestSchema, type CreateRegistrationTokenResponse, CreateRegistrationTokenResponseSchema, type CreateUserRequest, DangerLevel, DangerLevelSchema, type DashboardSummary, DashboardSummarySchema, ErrorCode, type ErrorEnvelope, type HealthReport, type HealthReportInput, HealthReportInputSchema, HealthReportSchema, HealthStatus, HealthStatusSchema, HttpError, ListQueryBase, type Pagination, type RegisterAgentRequest, RegisterAgentRequestSchema, type RegisterAgentResponse, RegisterAgentResponseSchema, type RegistrationToken, RegistrationTokenSchema, type ReportCommandResultRequest, ReportCommandResultRequestSchema, type ReportedService, ReportedServiceSchema, type ResetUserPasswordRequest, type RuntimeKind, RuntimeKindSchema, type ServiceReportRequest, ServiceReportRequestSchema, type SuccessEnvelope, type SystemHealth, SystemHealthSchema, type SystemVersion, SystemVersionSchema, TokenStatus, type UpdateUserRequest, type User, UserRole, UserSchema, actionDefinitionInputSchema, actionPrepareResultSchema, adminLoginRequestSchema, agentHeartbeatRequestSchema, configItemInputSchema, createActionCommandRequestSchema, createRegistrationTokenRequestSchema, createUserRequestSchema, healthReportInputSchema, paginate, parseSort, registerAgentRequestSchema, reportCommandResultRequestSchema, reportedServiceSchema, resetUserPasswordRequestSchema, serviceReportRequestSchema, updateUserRequestSchema };

package/dist/index.d.ts

@@ -33,10 +33,6 @@ declare const ErrorCode: {
     readonly AGENT_DISABLED: "AGENT_DISABLED";
 };
 type ErrorCode = typeof ErrorCode[keyof typeof ErrorCode];
-declare const idPrefixes: readonly ["wks_", "usr_", "agt_", "tok_", "svc_", "hlr_", "cfg_", "act_", "cmd_", "crs_", "aud_"];
-type IdPrefix = typeof idPrefixes[number];
-
-declare function newId<P extends IdPrefix>(prefix: P): `${P}${string}`;
 declare const AnyJson: z.ZodRecord<z.ZodString, z.ZodAny>;
 declare const AgentStatusSchema: z.ZodEnum<["PENDING", "ONLINE", "OFFLINE", "DISABLED", "REVOKED"]>;
 declare const CapsuleServiceStatusSchema: z.ZodEnum<["UNKNOWN", "HEALTHY", "UNHEALTHY", "STALE", "OFFLINE"]>;
@@ -2781,4 +2777,4 @@ declare function paginate<T>(items: T[], page: number, pageSize: number, total:
     };
 };
 
-export { type ActionDefinition, type ActionDefinitionInput, ActionDefinitionInputSchema, ActionDefinitionSchema, type ActionPrepareResult, ActionPrepareResultSchema, type AdminLoginRequest, AdminLoginRequestSchema, type AdminSession, AdminSessionSchema, type Agent, type AgentHeartbeatRequest, AgentHeartbeatRequestSchema, type AgentHeartbeatResponse, AgentHeartbeatResponseSchema, AgentSchema, AgentStatus, AgentStatusSchema, AnyJson, AuditActorType, type AuditEvent, AuditEventSchema, AuditResult, type CapsuleManifest, CapsuleManifestSchema, type CapsuleService, type CapsuleServiceDetail, CapsuleServiceDetailSchema, CapsuleServiceSchema, CapsuleServiceStatus, CapsuleServiceStatusSchema, type Command, type CommandDetail, CommandDetailSchema, type CommandResult, CommandResultSchema, CommandSchema, CommandStatus, CommandStatusSchema, type CommandType, CommandTypeSchema, type ConfigItem, type ConfigItemInput, ConfigItemInputSchema, ConfigItemSchema, type CreateActionCommandRequest, CreateActionCommandRequestSchema, type CreateRegistrationTokenRequest, CreateRegistrationTokenRequestSchema, type CreateRegistrationTokenResponse, CreateRegistrationTokenResponseSchema, type CreateUserRequest, DangerLevel, DangerLevelSchema, type DashboardSummary, DashboardSummarySchema, ErrorCode, type ErrorEnvelope, type HealthReport, type HealthReportInput, HealthReportInputSchema, HealthReportSchema, HealthStatus, HealthStatusSchema, HttpError, type IdPrefix, ListQueryBase, type Pagination, type RegisterAgentRequest, RegisterAgentRequestSchema, type RegisterAgentResponse, RegisterAgentResponseSchema, type RegistrationToken, RegistrationTokenSchema, type ReportCommandResultRequest, ReportCommandResultRequestSchema, type ReportedService, ReportedServiceSchema, type ResetUserPasswordRequest, type RuntimeKind, RuntimeKindSchema, type ServiceReportRequest, ServiceReportRequestSchema, type SuccessEnvelope, type SystemHealth, SystemHealthSchema, type SystemVersion, SystemVersionSchema, TokenStatus, type UpdateUserRequest, type User, UserRole, UserSchema, actionDefinitionInputSchema, actionPrepareResultSchema, adminLoginRequestSchema, agentHeartbeatRequestSchema, configItemInputSchema, createActionCommandRequestSchema, createRegistrationTokenRequestSchema, createUserRequestSchema, healthReportInputSchema, idPrefixes, newId, paginate, parseSort, registerAgentRequestSchema, reportCommandResultRequestSchema, reportedServiceSchema, resetUserPasswordRequestSchema, serviceReportRequestSchema, updateUserRequestSchema };
+export { type ActionDefinition, type ActionDefinitionInput, ActionDefinitionInputSchema, ActionDefinitionSchema, type ActionPrepareResult, ActionPrepareResultSchema, type AdminLoginRequest, AdminLoginRequestSchema, type AdminSession, AdminSessionSchema, type Agent, type AgentHeartbeatRequest, AgentHeartbeatRequestSchema, type AgentHeartbeatResponse, AgentHeartbeatResponseSchema, AgentSchema, AgentStatus, AgentStatusSchema, AnyJson, AuditActorType, type AuditEvent, AuditEventSchema, AuditResult, type CapsuleManifest, CapsuleManifestSchema, type CapsuleService, type CapsuleServiceDetail, CapsuleServiceDetailSchema, CapsuleServiceSchema, CapsuleServiceStatus, CapsuleServiceStatusSchema, type Command, type CommandDetail, CommandDetailSchema, type CommandResult, CommandResultSchema, CommandSchema, CommandStatus, CommandStatusSchema, type CommandType, CommandTypeSchema, type ConfigItem, type ConfigItemInput, ConfigItemInputSchema, ConfigItemSchema, type CreateActionCommandRequest, CreateActionCommandRequestSchema, type CreateRegistrationTokenRequest, CreateRegistrationTokenRequestSchema, type CreateRegistrationTokenResponse, CreateRegistrationTokenResponseSchema, type CreateUserRequest, DangerLevel, DangerLevelSchema, type DashboardSummary, DashboardSummarySchema, ErrorCode, type ErrorEnvelope, type HealthReport, type HealthReportInput, HealthReportInputSchema, HealthReportSchema, HealthStatus, HealthStatusSchema, HttpError, ListQueryBase, type Pagination, type RegisterAgentRequest, RegisterAgentRequestSchema, type RegisterAgentResponse, RegisterAgentResponseSchema, type RegistrationToken, RegistrationTokenSchema, type ReportCommandResultRequest, ReportCommandResultRequestSchema, type ReportedService, ReportedServiceSchema, type ResetUserPasswordRequest, type RuntimeKind, RuntimeKindSchema, type ServiceReportRequest, ServiceReportRequestSchema, type SuccessEnvelope, type SystemHealth, SystemHealthSchema, type SystemVersion, SystemVersionSchema, TokenStatus, type UpdateUserRequest, type User, UserRole, UserSchema, actionDefinitionInputSchema, actionPrepareResultSchema, adminLoginRequestSchema, agentHeartbeatRequestSchema, configItemInputSchema, createActionCommandRequestSchema, createRegistrationTokenRequestSchema, createUserRequestSchema, healthReportInputSchema, paginate, parseSort, registerAgentRequestSchema, reportCommandResultRequestSchema, reportedServiceSchema, resetUserPasswordRequestSchema, serviceReportRequestSchema, updateUserRequestSchema };

package/dist/index.js

@@ -1,5 +1,4 @@
 // src/index.ts
-import { customAlphabet } from "nanoid";
 import { z } from "zod";
 var AgentStatus = ["PENDING", "ONLINE", "OFFLINE", "DISABLED", "REVOKED"];
 var CapsuleServiceStatus = ["UNKNOWN", "HEALTHY", "UNHEALTHY", "STALE", "OFFLINE"];
@@ -24,11 +23,6 @@ var ErrorCode = {
   AGENT_REVOKED: "AGENT_REVOKED",
   AGENT_DISABLED: "AGENT_DISABLED"
 };
-var idPrefixes = ["wks_", "usr_", "agt_", "tok_", "svc_", "hlr_", "cfg_", "act_", "cmd_", "crs_", "aud_"];
-var NANO = customAlphabet("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_-", 21);
-function newId(prefix) {
-  return `${prefix}${NANO()}`;
-}
 var AnyJson = z.record(z.any());
 var AgentStatusSchema = z.enum(AgentStatus);
 var CapsuleServiceStatusSchema = z.enum(CapsuleServiceStatus);
@@ -178,8 +172,6 @@ export {
   createRegistrationTokenRequestSchema,
   createUserRequestSchema,
   healthReportInputSchema,
-  idPrefixes,
-  newId,
   paginate,
   parseSort,
   registerAgentRequestSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtrape/capsule-contracts-node",
-  "version": "0.1.0-public-review.1",
+  "version": "0.2.0",
   "description": "TypeScript contracts and Zod schemas for Xtrape Capsule and Opstage wire protocols.",
   "keywords": [
     "xtrape",
@@ -36,15 +36,7 @@
     "LICENSE",
     "NOTICE"
   ],
-  "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts",
-    "prepack": "pnpm build",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "lint": "tsc --noEmit"
-  },
   "dependencies": {
-    "nanoid": "^5.0.9",
     "zod": "^3.25.0"
   },
   "devDependencies": {
@@ -59,5 +51,11 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "license": "Apache-2.0"
-}
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit"
+  }
+}