@company-semantics/contracts 0.102.1 → 0.103.1
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.
- package/package.json +8 -3
- package/src/api/README.md +20 -2
- package/src/api/generated.ts +7118 -0
- package/src/api/index.ts +9 -0
- package/src/generated/openapi-routes.ts +92 -0
- package/src/index.ts +7 -0
- package/src/resource-keys.ts +39 -9
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@company-semantics/contracts",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.103.1",
|
|
4
4
|
"private": false,
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -81,7 +81,10 @@
|
|
|
81
81
|
"guard:test": "vitest run scripts/ci/__tests__",
|
|
82
82
|
"release": "npx tsx scripts/release.ts",
|
|
83
83
|
"prepublishOnly": "echo 'ERROR: Publishing is CI-only via tag push. Use pnpm release instead.' && exit 1",
|
|
84
|
-
"test": "vitest run"
|
|
84
|
+
"test": "vitest run",
|
|
85
|
+
"generate:api-types": "openapi-typescript openapi/backend.yaml -o src/api/generated.ts",
|
|
86
|
+
"generate:openapi-routes": "tsx scripts/generate-openapi-routes.ts",
|
|
87
|
+
"generate:api-types:check": "openapi-typescript openapi/backend.yaml -o /tmp/cs-api-types-check.ts && diff -q src/api/generated.ts /tmp/cs-api-types-check.ts"
|
|
85
88
|
},
|
|
86
89
|
"packageManager": "pnpm@10.25.0",
|
|
87
90
|
"engines": {
|
|
@@ -92,9 +95,11 @@
|
|
|
92
95
|
"husky": "^9.1.7",
|
|
93
96
|
"lint-staged": "^16.2.7",
|
|
94
97
|
"markdownlint-cli2": "^0.20.0",
|
|
98
|
+
"openapi-typescript": "^7.13.0",
|
|
95
99
|
"tsx": "^4.21.0",
|
|
96
100
|
"typescript": "^5",
|
|
97
|
-
"vitest": "^4.0.16"
|
|
101
|
+
"vitest": "^4.0.16",
|
|
102
|
+
"yaml": "^2.8.3"
|
|
98
103
|
},
|
|
99
104
|
"lint-staged": {
|
|
100
105
|
"*.ts": "bash -c 'tsc -b --noEmit'",
|
package/src/api/README.md
CHANGED
|
@@ -1,21 +1,39 @@
|
|
|
1
1
|
# api/
|
|
2
2
|
|
|
3
|
-
Shared API route helpers and
|
|
3
|
+
Shared API route helpers, contracts, and generated types for backend HTTP endpoints.
|
|
4
4
|
|
|
5
5
|
## Purpose
|
|
6
6
|
|
|
7
|
-
Provides reusable functions that encode API response shapes shared between the contracts package and backend route implementations
|
|
7
|
+
Provides reusable functions that encode API response shapes shared between the contracts package and backend route implementations, plus auto-generated TypeScript types from the OpenAPI spec.
|
|
8
8
|
|
|
9
9
|
## Invariants
|
|
10
10
|
|
|
11
11
|
- Functions in this domain are pure — no side effects, no database access
|
|
12
12
|
- Response shapes must match the types defined in `src/mcp/` (e.g., `ToolDiscoveryResponse`)
|
|
13
13
|
- Capability graph inclusion is opt-in via query parameter convention (`?include=graph`)
|
|
14
|
+
- `generated.ts` contains only type exports — zero runtime imports, zero const/let/var/function declarations
|
|
15
|
+
- `generated.ts` must stay in sync with `openapi/backend.yaml` — run `pnpm generate:api-types:check` to verify
|
|
16
|
+
|
|
17
|
+
## Generated Types (`generated.ts`)
|
|
18
|
+
|
|
19
|
+
Auto-generated by `openapi-typescript` from `openapi/backend.yaml`. Exports three top-level interfaces:
|
|
20
|
+
|
|
21
|
+
- `paths` — Route-level type map (path → method → request/response types)
|
|
22
|
+
- `components` — All schema types (MeResponse, WorkspaceOverview, etc.)
|
|
23
|
+
- `operations` — Operation-level types keyed by operationId
|
|
24
|
+
|
|
25
|
+
Regenerate with `pnpm generate:api-types`. Check for staleness with `pnpm generate:api-types:check`.
|
|
26
|
+
|
|
27
|
+
The file is committed to the repo (not .gitignored) so consumers can import types without running the generator, and type changes are visible in code review diffs.
|
|
14
28
|
|
|
15
29
|
## Public API
|
|
16
30
|
|
|
17
31
|
- `buildToolDiscoveryResponse(tools, includeGraph)` — Constructs a `ToolDiscoveryResponse`, optionally including the capability graph derived from tool metadata
|
|
32
|
+
- `paths` (type) — OpenAPI route type map for typed fetch clients
|
|
33
|
+
- `components` (type) — OpenAPI schema types
|
|
34
|
+
- `operations` (type) — OpenAPI operation types keyed by operationId
|
|
18
35
|
|
|
19
36
|
## Dependencies
|
|
20
37
|
|
|
21
38
|
- `src/mcp/` — `MCPToolDescriptor`, `ToolDiscoveryResponse`, `CapabilityGraph` types and `buildCapabilityGraph` function
|
|
39
|
+
- `openapi/backend.yaml` — Source OpenAPI 3.1 spec for type generation
|