@vecto-os/entity-schema 0.1.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 (3) hide show
  1. package/dist/index.d.ts +81 -0
  2. package/dist/index.js +74 -0
  3. package/package.json +44 -0
package/dist/index.d.ts ADDED
@@ -0,0 +1,81 @@
1
+ /**
2
+ * @vecto-os/entity-schema — Shared Zod schemas for the ENTITY node-type.
3
+ *
4
+ * Single source of truth for:
5
+ * - ExternalRef → multi-source ID record (Matter, Apple-Home, GS1, ...)
6
+ * - EntityAttributes → free-form structured key-value map
7
+ * - EntityCreatePayload → REST POST body / MCP create_node args for ENTITY
8
+ * - EntityUpdatePayload → REST PATCH body for ENTITY
9
+ *
10
+ * Consumed by:
11
+ * - dash-api → runtime validation in entityService + entities route
12
+ * - graph-tools → MCP tool-input shape (re-exports + composition)
13
+ * - vecto-mcp → forwarding via REST (validation server-side)
14
+ *
15
+ * See EPC-67 / DOC-286 / IDX-309 / IDX-310 in vcto-project for design context.
16
+ * Tier-A classification: feedback_node_type_tier_classification.md.
17
+ */
18
+ import { z } from 'zod';
19
+ /**
20
+ * One external-system reference for an ENTITY. Allows the same physical thing
21
+ * to be tracked across multiple systems (a Matter bridge can sit in both an
22
+ * Apple-Home and a Google-Home fabric with different node IDs).
23
+ */
24
+ export declare const ExternalRefSchema: z.ZodObject<{
25
+ source: z.ZodString;
26
+ id: z.ZodString;
27
+ metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
28
+ }, z.core.$strip>;
29
+ export type ExternalRef = z.infer<typeof ExternalRefSchema>;
30
+ export declare const ExternalRefsSchema: z.ZodArray<z.ZodObject<{
31
+ source: z.ZodString;
32
+ id: z.ZodString;
33
+ metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
34
+ }, z.core.$strip>>;
35
+ export type ExternalRefs = z.infer<typeof ExternalRefsSchema>;
36
+ /**
37
+ * Free-text discriminator for ENTITY rows. Per-project configurable (no
38
+ * platform-wide enum — see ADR scope-fences). Convention: kebab-case
39
+ * (host, iot-device, boardgame-component, supplier).
40
+ */
41
+ export declare const EntityTypeSchema: z.ZodString;
42
+ export type EntityType = z.infer<typeof EntityTypeSchema>;
43
+ /** Free-form structured key-value map. Shape is per-entity_type, not enforced. */
44
+ export declare const EntityAttributesSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
45
+ export type EntityAttributes = z.infer<typeof EntityAttributesSchema>;
46
+ /**
47
+ * Body for `POST /api/entities` or MCP `create_node` when type=ENTITY.
48
+ */
49
+ export declare const EntityCreatePayloadSchema: z.ZodObject<{
50
+ entity_type: z.ZodString;
51
+ title: z.ZodString;
52
+ attributes: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
53
+ external_refs: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
54
+ source: z.ZodString;
55
+ id: z.ZodString;
56
+ metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
57
+ }, z.core.$strip>>>>;
58
+ body: z.ZodOptional<z.ZodString>;
59
+ parent_ref: z.ZodOptional<z.ZodString>;
60
+ lifecycle_status: z.ZodOptional<z.ZodString>;
61
+ }, z.core.$strip>;
62
+ export type EntityCreatePayload = z.infer<typeof EntityCreatePayloadSchema>;
63
+ /**
64
+ * Body for `PATCH /api/entities/:ref`. All fields optional;
65
+ * partial-merge semantics on attributes/external_refs are handled
66
+ * service-side (replace, not deep-merge).
67
+ */
68
+ export declare const EntityUpdatePayloadSchema: z.ZodObject<{
69
+ entity_type: z.ZodOptional<z.ZodString>;
70
+ title: z.ZodOptional<z.ZodString>;
71
+ attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
72
+ external_refs: z.ZodOptional<z.ZodArray<z.ZodObject<{
73
+ source: z.ZodString;
74
+ id: z.ZodString;
75
+ metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
76
+ }, z.core.$strip>>>;
77
+ body: z.ZodOptional<z.ZodString>;
78
+ status: z.ZodOptional<z.ZodString>;
79
+ lifecycle_status: z.ZodOptional<z.ZodString>;
80
+ }, z.core.$strip>;
81
+ export type EntityUpdatePayload = z.infer<typeof EntityUpdatePayloadSchema>;
package/dist/index.js ADDED
@@ -0,0 +1,74 @@
1
+ /**
2
+ * @vecto-os/entity-schema — Shared Zod schemas for the ENTITY node-type.
3
+ *
4
+ * Single source of truth for:
5
+ * - ExternalRef → multi-source ID record (Matter, Apple-Home, GS1, ...)
6
+ * - EntityAttributes → free-form structured key-value map
7
+ * - EntityCreatePayload → REST POST body / MCP create_node args for ENTITY
8
+ * - EntityUpdatePayload → REST PATCH body for ENTITY
9
+ *
10
+ * Consumed by:
11
+ * - dash-api → runtime validation in entityService + entities route
12
+ * - graph-tools → MCP tool-input shape (re-exports + composition)
13
+ * - vecto-mcp → forwarding via REST (validation server-side)
14
+ *
15
+ * See EPC-67 / DOC-286 / IDX-309 / IDX-310 in vcto-project for design context.
16
+ * Tier-A classification: feedback_node_type_tier_classification.md.
17
+ */
18
+ import { z } from 'zod';
19
+ // ─── External references ────────────────────────────────────────────────────
20
+ /**
21
+ * One external-system reference for an ENTITY. Allows the same physical thing
22
+ * to be tracked across multiple systems (a Matter bridge can sit in both an
23
+ * Apple-Home and a Google-Home fabric with different node IDs).
24
+ */
25
+ export const ExternalRefSchema = z.object({
26
+ source: z.string().min(1).describe('Originating system (matter, apple-home, homey, unifi, gs1, ...)'),
27
+ id: z.string().min(1).describe('Identifier within that source system'),
28
+ metadata: z.record(z.string(), z.unknown()).optional().describe('Source-specific extra data'),
29
+ });
30
+ export const ExternalRefsSchema = z.array(ExternalRefSchema);
31
+ // ─── Entity-type discriminator ──────────────────────────────────────────────
32
+ /**
33
+ * Free-text discriminator for ENTITY rows. Per-project configurable (no
34
+ * platform-wide enum — see ADR scope-fences). Convention: kebab-case
35
+ * (host, iot-device, boardgame-component, supplier).
36
+ */
37
+ export const EntityTypeSchema = z
38
+ .string()
39
+ .min(1)
40
+ .max(64)
41
+ .regex(/^[a-z0-9][a-z0-9-]*$/, 'Must be lowercase kebab-case (a-z, 0-9, hyphens)');
42
+ // ─── Attributes ─────────────────────────────────────────────────────────────
43
+ /** Free-form structured key-value map. Shape is per-entity_type, not enforced. */
44
+ export const EntityAttributesSchema = z.record(z.string(), z.unknown());
45
+ // ─── Create / update payloads ──────────────────────────────────────────────
46
+ /**
47
+ * Body for `POST /api/entities` or MCP `create_node` when type=ENTITY.
48
+ */
49
+ export const EntityCreatePayloadSchema = z.object({
50
+ entity_type: EntityTypeSchema,
51
+ title: z.string().min(1).max(255),
52
+ attributes: EntityAttributesSchema.optional().default({}),
53
+ external_refs: ExternalRefsSchema.optional().default([]),
54
+ body: z.string().optional().describe('Optional markdown body for notes/history'),
55
+ parent_ref: z.string().optional().describe('Parent ref for CONTAINS-edge'),
56
+ lifecycle_status: z
57
+ .string()
58
+ .optional()
59
+ .describe('Free-text per entity_type (active, decommissioned, prototype, shipping, ...)'),
60
+ });
61
+ /**
62
+ * Body for `PATCH /api/entities/:ref`. All fields optional;
63
+ * partial-merge semantics on attributes/external_refs are handled
64
+ * service-side (replace, not deep-merge).
65
+ */
66
+ export const EntityUpdatePayloadSchema = z.object({
67
+ entity_type: EntityTypeSchema.optional(),
68
+ title: z.string().min(1).max(255).optional(),
69
+ attributes: EntityAttributesSchema.optional(),
70
+ external_refs: ExternalRefsSchema.optional(),
71
+ body: z.string().optional(),
72
+ status: z.string().optional(),
73
+ lifecycle_status: z.string().optional(),
74
+ });
package/package.json ADDED
@@ -0,0 +1,44 @@
1
+ {
2
+ "name": "@vecto-os/entity-schema",
3
+ "version": "0.1.0",
4
+ "type": "module",
5
+ "description": "Shared Zod schemas for the Vecto ENTITY node-type. Single source of truth for ExternalRef, EntityAttributes, EntityCreatePayload, EntityUpdatePayload — consumed by dash-api (REST validation), graph-tools (MCP tool input), and vecto-mcp (forwarding).",
6
+ "keywords": [
7
+ "vecto",
8
+ "entity",
9
+ "graph",
10
+ "schema",
11
+ "zod"
12
+ ],
13
+ "homepage": "https://github.com/ITbrouwerij/vecto-os#readme",
14
+ "repository": {
15
+ "type": "git",
16
+ "url": "git+https://github.com/ITbrouwerij/vecto-os.git",
17
+ "directory": "packages/entity-schema"
18
+ },
19
+ "bugs": {
20
+ "url": "https://github.com/ITbrouwerij/vecto-os/issues"
21
+ },
22
+ "license": "UNLICENSED",
23
+ "author": "ITbrouwerij",
24
+ "main": "dist/index.js",
25
+ "types": "dist/index.d.ts",
26
+ "files": [
27
+ "dist",
28
+ "README.md"
29
+ ],
30
+ "scripts": {
31
+ "build": "tsc",
32
+ "dev": "tsc --watch",
33
+ "prepublishOnly": "npm run build"
34
+ },
35
+ "dependencies": {
36
+ "zod": "^4.4.3"
37
+ },
38
+ "devDependencies": {
39
+ "typescript": "^5.3.3"
40
+ },
41
+ "engines": {
42
+ "node": ">=18.0.0"
43
+ }
44
+ }