@unifiedcommerce/core 0.1.0 → 0.2.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 (245) hide show
  1. package/dist/auth/setup.d.ts.map +1 -1
  2. package/dist/auth/setup.js +8 -3
  3. package/dist/config/types.d.ts +3 -1
  4. package/dist/config/types.d.ts.map +1 -1
  5. package/dist/index.d.ts +1 -0
  6. package/dist/index.d.ts.map +1 -1
  7. package/dist/index.js +1 -0
  8. package/dist/interfaces/mcp/server.d.ts +3 -5
  9. package/dist/interfaces/mcp/server.d.ts.map +1 -1
  10. package/dist/interfaces/mcp/server.js +25 -510
  11. package/dist/interfaces/mcp/tool-builder.d.ts +120 -0
  12. package/dist/interfaces/mcp/tool-builder.d.ts.map +1 -0
  13. package/dist/interfaces/mcp/tool-builder.js +224 -0
  14. package/dist/interfaces/mcp/tools/analytics.d.ts +42 -0
  15. package/dist/interfaces/mcp/tools/analytics.d.ts.map +1 -0
  16. package/dist/interfaces/mcp/tools/analytics.js +70 -0
  17. package/dist/interfaces/mcp/tools/cart.d.ts +14 -0
  18. package/dist/interfaces/mcp/tools/cart.d.ts.map +1 -0
  19. package/dist/interfaces/mcp/tools/cart.js +47 -0
  20. package/dist/interfaces/mcp/tools/catalog.d.ts +53 -0
  21. package/dist/interfaces/mcp/tools/catalog.d.ts.map +1 -0
  22. package/dist/interfaces/mcp/tools/catalog.js +284 -0
  23. package/dist/interfaces/mcp/tools/index.d.ts +3 -0
  24. package/dist/interfaces/mcp/tools/index.d.ts.map +1 -0
  25. package/dist/interfaces/mcp/tools/index.js +20 -0
  26. package/dist/interfaces/mcp/tools/inventory.d.ts +27 -0
  27. package/dist/interfaces/mcp/tools/inventory.d.ts.map +1 -0
  28. package/dist/interfaces/mcp/tools/inventory.js +143 -0
  29. package/dist/interfaces/mcp/tools/orders.d.ts +18 -0
  30. package/dist/interfaces/mcp/tools/orders.d.ts.map +1 -0
  31. package/dist/interfaces/mcp/tools/orders.js +82 -0
  32. package/dist/interfaces/mcp/tools/pricing.d.ts +29 -0
  33. package/dist/interfaces/mcp/tools/pricing.d.ts.map +1 -0
  34. package/dist/interfaces/mcp/tools/pricing.js +90 -0
  35. package/dist/interfaces/mcp/tools/promotions.d.ts +44 -0
  36. package/dist/interfaces/mcp/tools/promotions.d.ts.map +1 -0
  37. package/dist/interfaces/mcp/tools/promotions.js +109 -0
  38. package/dist/interfaces/mcp/tools/registry.d.ts +32 -0
  39. package/dist/interfaces/mcp/tools/registry.d.ts.map +1 -0
  40. package/dist/interfaces/mcp/tools/registry.js +55 -0
  41. package/dist/interfaces/mcp/tools/search.d.ts +14 -0
  42. package/dist/interfaces/mcp/tools/search.d.ts.map +1 -0
  43. package/dist/interfaces/mcp/tools/search.js +39 -0
  44. package/dist/interfaces/mcp/tools/webhooks.d.ts +15 -0
  45. package/dist/interfaces/mcp/tools/webhooks.d.ts.map +1 -0
  46. package/dist/interfaces/mcp/tools/webhooks.js +48 -0
  47. package/dist/interfaces/mcp/transport.d.ts +17 -2
  48. package/dist/interfaces/mcp/transport.d.ts.map +1 -1
  49. package/dist/interfaces/mcp/transport.js +91 -44
  50. package/dist/interfaces/rest/router.d.ts.map +1 -1
  51. package/dist/interfaces/rest/routes/checkout.d.ts.map +1 -1
  52. package/dist/interfaces/rest/routes/checkout.js +1 -1
  53. package/dist/interfaces/rest/routes/promotions.d.ts.map +1 -1
  54. package/dist/interfaces/rest/routes/promotions.js +3 -2
  55. package/dist/kernel/database/adapter.d.ts +8 -0
  56. package/dist/kernel/database/adapter.d.ts.map +1 -1
  57. package/dist/kernel/factory/repository-factory.d.ts.map +1 -1
  58. package/dist/kernel/factory/repository-factory.js +3 -1
  59. package/dist/kernel/local-api.d.ts.map +1 -1
  60. package/dist/kernel/local-api.js +2 -0
  61. package/dist/kernel/plugin/manifest.d.ts +3 -3
  62. package/dist/kernel/plugin/manifest.d.ts.map +1 -1
  63. package/dist/kernel/plugin/manifest.js +36 -7
  64. package/dist/runtime/kernel.d.ts +1 -2
  65. package/dist/runtime/kernel.d.ts.map +1 -1
  66. package/dist/runtime/kernel.js +16 -8
  67. package/dist/runtime/server.d.ts.map +1 -1
  68. package/dist/runtime/server.js +8 -3
  69. package/dist/test-utils/create-pglite-adapter.d.ts.map +1 -1
  70. package/dist/test-utils/create-pglite-adapter.js +7 -6
  71. package/dist/tsconfig.tsbuildinfo +1 -0
  72. package/package.json +2 -2
  73. package/src/adapters/console-email.ts +0 -43
  74. package/src/auth/access.ts +0 -187
  75. package/src/auth/auth-schema.ts +0 -139
  76. package/src/auth/middleware.ts +0 -161
  77. package/src/auth/org.ts +0 -41
  78. package/src/auth/permissions.ts +0 -28
  79. package/src/auth/setup.ts +0 -169
  80. package/src/auth/system-actor.ts +0 -19
  81. package/src/auth/types.ts +0 -10
  82. package/src/config/defaults.ts +0 -82
  83. package/src/config/define-config.ts +0 -53
  84. package/src/config/types.ts +0 -299
  85. package/src/generated/plugin-capabilities.d.ts +0 -20
  86. package/src/generated/plugin-manifest.ts +0 -23
  87. package/src/generated/plugin-repositories.d.ts +0 -20
  88. package/src/hooks/checkout-completion.ts +0 -262
  89. package/src/hooks/checkout.ts +0 -677
  90. package/src/hooks/order-emails.ts +0 -62
  91. package/src/index.ts +0 -214
  92. package/src/interfaces/mcp/agent-prompt.ts +0 -174
  93. package/src/interfaces/mcp/context-enrichment.ts +0 -177
  94. package/src/interfaces/mcp/server.ts +0 -617
  95. package/src/interfaces/mcp/transport.ts +0 -68
  96. package/src/interfaces/rest/customer-portal.ts +0 -299
  97. package/src/interfaces/rest/index.ts +0 -74
  98. package/src/interfaces/rest/router.ts +0 -334
  99. package/src/interfaces/rest/routes/admin-jobs.ts +0 -58
  100. package/src/interfaces/rest/routes/audit.ts +0 -50
  101. package/src/interfaces/rest/routes/carts.ts +0 -89
  102. package/src/interfaces/rest/routes/catalog.ts +0 -493
  103. package/src/interfaces/rest/routes/checkout.ts +0 -283
  104. package/src/interfaces/rest/routes/inventory.ts +0 -70
  105. package/src/interfaces/rest/routes/media.ts +0 -86
  106. package/src/interfaces/rest/routes/orders.ts +0 -78
  107. package/src/interfaces/rest/routes/payments.ts +0 -60
  108. package/src/interfaces/rest/routes/pricing.ts +0 -57
  109. package/src/interfaces/rest/routes/promotions.ts +0 -92
  110. package/src/interfaces/rest/routes/search.ts +0 -71
  111. package/src/interfaces/rest/routes/webhooks.ts +0 -46
  112. package/src/interfaces/rest/schemas/admin-jobs.ts +0 -40
  113. package/src/interfaces/rest/schemas/audit.ts +0 -46
  114. package/src/interfaces/rest/schemas/carts.ts +0 -125
  115. package/src/interfaces/rest/schemas/catalog.ts +0 -450
  116. package/src/interfaces/rest/schemas/checkout.ts +0 -66
  117. package/src/interfaces/rest/schemas/customer-portal.ts +0 -195
  118. package/src/interfaces/rest/schemas/inventory.ts +0 -138
  119. package/src/interfaces/rest/schemas/media.ts +0 -75
  120. package/src/interfaces/rest/schemas/orders.ts +0 -104
  121. package/src/interfaces/rest/schemas/pricing.ts +0 -80
  122. package/src/interfaces/rest/schemas/promotions.ts +0 -110
  123. package/src/interfaces/rest/schemas/responses.ts +0 -85
  124. package/src/interfaces/rest/schemas/search.ts +0 -58
  125. package/src/interfaces/rest/schemas/shared.ts +0 -62
  126. package/src/interfaces/rest/schemas/webhooks.ts +0 -68
  127. package/src/interfaces/rest/utils.ts +0 -104
  128. package/src/interfaces/rest/webhook-router.ts +0 -50
  129. package/src/kernel/compensation/executor.ts +0 -61
  130. package/src/kernel/compensation/types.ts +0 -26
  131. package/src/kernel/database/adapter.ts +0 -13
  132. package/src/kernel/database/drizzle-db.ts +0 -56
  133. package/src/kernel/database/migrate.ts +0 -76
  134. package/src/kernel/database/plugin-types.ts +0 -34
  135. package/src/kernel/database/schema.ts +0 -49
  136. package/src/kernel/database/scoped-db.ts +0 -68
  137. package/src/kernel/database/tx-context.ts +0 -46
  138. package/src/kernel/error-mapper.ts +0 -15
  139. package/src/kernel/errors.ts +0 -89
  140. package/src/kernel/factory/repository-factory.ts +0 -242
  141. package/src/kernel/hooks/create-context.ts +0 -43
  142. package/src/kernel/hooks/executor.ts +0 -88
  143. package/src/kernel/hooks/registry.ts +0 -74
  144. package/src/kernel/hooks/types.ts +0 -52
  145. package/src/kernel/http-error.ts +0 -44
  146. package/src/kernel/jobs/adapter.ts +0 -36
  147. package/src/kernel/jobs/drizzle-adapter.ts +0 -58
  148. package/src/kernel/jobs/runner.ts +0 -153
  149. package/src/kernel/jobs/schema.ts +0 -46
  150. package/src/kernel/jobs/types.ts +0 -30
  151. package/src/kernel/local-api.ts +0 -185
  152. package/src/kernel/plugin/manifest.ts +0 -253
  153. package/src/kernel/query/executor.ts +0 -184
  154. package/src/kernel/query/registry.ts +0 -46
  155. package/src/kernel/result.ts +0 -33
  156. package/src/kernel/schema/extra-columns.ts +0 -37
  157. package/src/kernel/service-registry.ts +0 -76
  158. package/src/kernel/service-timing.ts +0 -89
  159. package/src/kernel/state-machine/machine.ts +0 -101
  160. package/src/modules/analytics/drizzle-adapter.ts +0 -426
  161. package/src/modules/analytics/hooks.ts +0 -11
  162. package/src/modules/analytics/models.ts +0 -125
  163. package/src/modules/analytics/repository/index.ts +0 -6
  164. package/src/modules/analytics/service.ts +0 -245
  165. package/src/modules/analytics/types.ts +0 -180
  166. package/src/modules/audit/hooks.ts +0 -78
  167. package/src/modules/audit/schema.ts +0 -33
  168. package/src/modules/audit/service.ts +0 -151
  169. package/src/modules/cart/access.ts +0 -27
  170. package/src/modules/cart/matcher.ts +0 -26
  171. package/src/modules/cart/repository/index.ts +0 -234
  172. package/src/modules/cart/schema.ts +0 -42
  173. package/src/modules/cart/schemas.ts +0 -38
  174. package/src/modules/cart/service.ts +0 -541
  175. package/src/modules/catalog/repository/index.ts +0 -772
  176. package/src/modules/catalog/schema.ts +0 -203
  177. package/src/modules/catalog/schemas.ts +0 -104
  178. package/src/modules/catalog/service.ts +0 -1544
  179. package/src/modules/customers/repository/index.ts +0 -327
  180. package/src/modules/customers/schema.ts +0 -64
  181. package/src/modules/customers/service.ts +0 -171
  182. package/src/modules/fulfillment/repository/index.ts +0 -426
  183. package/src/modules/fulfillment/schema.ts +0 -101
  184. package/src/modules/fulfillment/service.ts +0 -555
  185. package/src/modules/fulfillment/types.ts +0 -59
  186. package/src/modules/inventory/repository/index.ts +0 -509
  187. package/src/modules/inventory/schema.ts +0 -94
  188. package/src/modules/inventory/schemas.ts +0 -38
  189. package/src/modules/inventory/service.ts +0 -490
  190. package/src/modules/media/adapter.ts +0 -17
  191. package/src/modules/media/repository/index.ts +0 -274
  192. package/src/modules/media/schema.ts +0 -41
  193. package/src/modules/media/service.ts +0 -151
  194. package/src/modules/orders/repository/index.ts +0 -287
  195. package/src/modules/orders/schema.ts +0 -66
  196. package/src/modules/orders/service.ts +0 -619
  197. package/src/modules/orders/stale-order-cleanup.ts +0 -76
  198. package/src/modules/organization/service.ts +0 -191
  199. package/src/modules/payments/adapter.ts +0 -47
  200. package/src/modules/payments/repository/index.ts +0 -6
  201. package/src/modules/payments/service.ts +0 -107
  202. package/src/modules/pricing/repository/index.ts +0 -291
  203. package/src/modules/pricing/schema.ts +0 -71
  204. package/src/modules/pricing/schemas.ts +0 -38
  205. package/src/modules/pricing/service.ts +0 -494
  206. package/src/modules/promotions/repository/index.ts +0 -325
  207. package/src/modules/promotions/schema.ts +0 -62
  208. package/src/modules/promotions/schemas.ts +0 -38
  209. package/src/modules/promotions/service.ts +0 -598
  210. package/src/modules/search/adapter.ts +0 -57
  211. package/src/modules/search/hooks.ts +0 -12
  212. package/src/modules/search/repository/index.ts +0 -6
  213. package/src/modules/search/service.ts +0 -315
  214. package/src/modules/shipping/calculator.ts +0 -188
  215. package/src/modules/shipping/repository/index.ts +0 -6
  216. package/src/modules/shipping/service.ts +0 -51
  217. package/src/modules/tax/adapter.ts +0 -60
  218. package/src/modules/tax/repository/index.ts +0 -6
  219. package/src/modules/tax/service.ts +0 -53
  220. package/src/modules/webhooks/hook.ts +0 -34
  221. package/src/modules/webhooks/repository/index.ts +0 -278
  222. package/src/modules/webhooks/schema.ts +0 -56
  223. package/src/modules/webhooks/service.ts +0 -117
  224. package/src/modules/webhooks/signing.ts +0 -6
  225. package/src/modules/webhooks/ssrf-guard.ts +0 -71
  226. package/src/modules/webhooks/tasks.ts +0 -52
  227. package/src/modules/webhooks/worker.ts +0 -134
  228. package/src/runtime/commerce.ts +0 -145
  229. package/src/runtime/kernel.ts +0 -419
  230. package/src/runtime/logger.ts +0 -36
  231. package/src/runtime/server.ts +0 -349
  232. package/src/runtime/shutdown.ts +0 -43
  233. package/src/test-utils/create-pglite-adapter.ts +0 -129
  234. package/src/test-utils/create-plugin-test-app.ts +0 -128
  235. package/src/test-utils/create-repository-test-harness.ts +0 -16
  236. package/src/test-utils/create-test-config.ts +0 -190
  237. package/src/test-utils/create-test-kernel.ts +0 -7
  238. package/src/test-utils/create-test-plugin-context.ts +0 -75
  239. package/src/test-utils/rest-api-test-utils.ts +0 -265
  240. package/src/test-utils/test-actors.ts +0 -62
  241. package/src/test-utils/typed-hooks.ts +0 -54
  242. package/src/types/commerce-types.ts +0 -34
  243. package/src/utils/id.ts +0 -3
  244. package/src/utils/logger.ts +0 -18
  245. package/src/utils/pagination.ts +0 -22
@@ -1,515 +1,30 @@
1
- import { buildAnalyticsScope } from "../../modules/analytics/types.js";
2
1
  import { orderStateMachine } from "../../kernel/state-machine/machine.js";
3
- import { enrichEntityForAgent, enrichInventoryForAgent, enrichOrderForAgent, } from "./context-enrichment.js";
4
- function textContent(value) {
5
- return {
6
- content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
7
- };
2
+ import { coreTools } from "./tools/index.js";
3
+ import { registerToolsOnServer } from "./tools/registry.js";
4
+ // ─── Core Tool Registration ─────────────────────────────────────────────────
5
+ export function registerCoreTools(server, kernel) {
6
+ registerToolsOnServer(server, kernel, coreTools);
8
7
  }
9
- function asObject(params) {
10
- if (!params || typeof params !== "object" || Array.isArray(params))
11
- return {};
12
- return params;
13
- }
14
- function readString(params, key) {
15
- const value = params[key];
16
- return typeof value === "string" ? value : undefined;
17
- }
18
- function readNumber(params, key) {
19
- const value = params[key];
20
- return typeof value === "number" && Number.isFinite(value)
21
- ? value
22
- : undefined;
23
- }
24
- function readStringArray(params, key) {
25
- const value = params[key];
26
- if (!Array.isArray(value))
27
- return [];
28
- return value.filter((item) => typeof item === "string");
29
- }
30
- function validationError(message) {
31
- return {
32
- error: {
33
- code: "VALIDATION_FAILED",
34
- message,
35
- },
36
- };
37
- }
38
- export function registerMCPCapabilities(kernel) {
39
- return {
40
- tools: [
41
- {
42
- name: "catalog_search",
43
- description: "Search the catalog. Filter by type, status, category, brand, price range, free-text. Returns paginated results with pricing and availability.",
44
- inputSchema: {
45
- type: "object",
46
- properties: {
47
- query: { type: "string" },
48
- type: { type: "string" },
49
- status: { type: "string" },
50
- categorySlug: { type: "string" },
51
- brandSlug: { type: "string" },
52
- page: { type: "number", default: 1 },
53
- limit: { type: "number", default: 20 },
54
- },
55
- },
56
- handler: async (params) => {
57
- const input = asObject(params);
58
- const query = (readString(input, "query") ?? "").trim().toLowerCase();
59
- const page = readNumber(input, "page") ?? 1;
60
- const limit = readNumber(input, "limit") ?? 20;
61
- const type = readString(input, "type");
62
- const status = readString(input, "status");
63
- const categorySlug = readString(input, "categorySlug");
64
- const brandSlug = readString(input, "brandSlug");
65
- if (query.length > 0) {
66
- const searchResult = await kernel.services.search.query({
67
- query,
68
- page,
69
- limit,
70
- filters: {
71
- ...(type ? { type } : {}),
72
- ...(status ? { status } : {}),
73
- ...(categorySlug ? { category: categorySlug } : {}),
74
- ...(brandSlug ? { brand: brandSlug } : {}),
75
- },
76
- });
77
- if (!searchResult.ok)
78
- return { error: searchResult.error };
79
- const enrichedItems = await Promise.all(searchResult.value.hits.map(async (hit) => {
80
- const entityResult = await kernel.services.catalog.getById(hit.id);
81
- if (entityResult.ok) {
82
- return enrichEntityForAgent(entityResult.value, kernel);
83
- }
84
- return hit.document;
85
- }));
86
- return textContent({
87
- items: await Promise.all(enrichedItems),
88
- pagination: {
89
- page: searchResult.value.page,
90
- limit: searchResult.value.limit,
91
- total: searchResult.value.total,
92
- totalPages: Math.max(1, Math.ceil(searchResult.value.total / searchResult.value.limit)),
93
- },
94
- facets: searchResult.value.facets,
95
- });
96
- }
97
- const result = await kernel.services.catalog.list({
98
- filter: {
99
- ...(type ? { type } : {}),
100
- ...(status ? { status } : {}),
101
- ...(categorySlug ? { category: categorySlug } : {}),
102
- ...(brandSlug ? { brand: brandSlug } : {}),
103
- },
104
- pagination: {
105
- page,
106
- limit,
107
- },
108
- });
109
- if (!result.ok)
110
- return { error: result.error };
111
- return textContent({
112
- ...result.value,
113
- items: await Promise.all(result.value.items.map((item) => enrichEntityForAgent(item, kernel))),
114
- });
115
- },
116
- },
117
- {
118
- name: "catalog_create_entity",
119
- description: "Create a new catalog entity. Requires type, slug, title. Created in draft status.",
120
- inputSchema: {
121
- type: "object",
122
- required: ["type", "slug", "title"],
123
- properties: {
124
- type: { type: "string" },
125
- slug: { type: "string" },
126
- title: { type: "string" },
127
- description: { type: "string" },
128
- metadata: { type: "object" },
129
- },
130
- },
131
- handler: async (params) => {
132
- const input = asObject(params);
133
- const type = readString(input, "type");
134
- const slug = readString(input, "slug");
135
- const title = readString(input, "title");
136
- const description = readString(input, "description");
137
- if (!type || !slug || !title) {
138
- return validationError("type, slug, and title are required.");
139
- }
140
- const result = await kernel.services.catalog.create({
141
- type,
142
- slug,
143
- attributes: {
144
- locale: "en",
145
- title,
146
- ...(description !== undefined ? { description } : {}),
147
- },
148
- ...(input.metadata &&
149
- typeof input.metadata === "object" &&
150
- !Array.isArray(input.metadata)
151
- ? { metadata: input.metadata }
152
- : {}),
153
- }, kernel.getMCPActor());
154
- if (!result.ok)
155
- return { error: result.error };
156
- return textContent(await enrichEntityForAgent(result.value, kernel));
157
- },
158
- },
159
- {
160
- name: "inventory_check",
161
- description: "Check stock levels for one or more entities/variants.",
162
- inputSchema: {
163
- type: "object",
164
- required: ["entityIds"],
165
- properties: {
166
- entityIds: {
167
- type: "array",
168
- items: { type: "string" },
169
- },
170
- },
171
- },
172
- handler: async (params) => {
173
- const input = asObject(params);
174
- const entityIds = readStringArray(input, "entityIds");
175
- if (entityIds.length === 0) {
176
- return validationError("entityIds is required.");
177
- }
178
- const result = await kernel.services.inventory.checkMultiple(entityIds);
179
- if (!result.ok)
180
- return { error: result.error };
181
- const enriched = await Promise.all(Object.entries(result.value).map(async ([entityId, available]) => {
182
- const levelsResult = await kernel.services.inventory.getLevelsByEntityId(entityId);
183
- const levels = levelsResult.ok ? levelsResult.value : [];
184
- const reorderThreshold = levels[0]?.reorderThreshold;
185
- const reorderQuantity = levels[0]?.reorderQuantity;
186
- return enrichInventoryForAgent({
187
- entityId,
188
- available,
189
- ...(reorderThreshold !== undefined ? { reorderThreshold } : {}),
190
- ...(reorderQuantity !== undefined ? { reorderQuantity } : {}),
191
- });
192
- }));
193
- return textContent(enriched);
194
- },
195
- },
196
- {
197
- name: "inventory_adjust",
198
- description: "Adjust inventory. Positive adds stock, negative removes. Requires reason.",
199
- inputSchema: {
200
- type: "object",
201
- required: ["entityId", "adjustment", "reason"],
202
- properties: {
203
- entityId: { type: "string" },
204
- variantId: { type: "string" },
205
- adjustment: { type: "number" },
206
- reason: { type: "string" },
207
- },
208
- },
209
- handler: async (params) => {
210
- const input = asObject(params);
211
- const entityId = readString(input, "entityId");
212
- const adjustment = readNumber(input, "adjustment");
213
- const reason = readString(input, "reason");
214
- const variantId = readString(input, "variantId");
215
- if (!entityId || adjustment === undefined || !reason) {
216
- return validationError("entityId, adjustment, and reason are required.");
217
- }
218
- const result = await kernel.services.inventory.adjust({
219
- entityId,
220
- adjustment,
221
- reason,
222
- ...(variantId !== undefined ? { variantId } : {}),
223
- }, kernel.getMCPActor());
224
- if (!result.ok)
225
- return { error: result.error };
226
- const availableResult = await kernel.services.inventory.getAvailable(entityId, variantId);
227
- return textContent(enrichInventoryForAgent({
228
- entityId,
229
- available: availableResult.ok ? availableResult.value : 0,
230
- ...(result.value.reorderThreshold !== undefined
231
- ? { reorderThreshold: result.value.reorderThreshold }
232
- : {}),
233
- ...(result.value.reorderQuantity !== undefined
234
- ? { reorderQuantity: result.value.reorderQuantity }
235
- : {}),
236
- }));
237
- },
238
- },
239
- {
240
- name: "cart_create",
241
- description: "Create a new shopping cart. Returns cart ID for subsequent operations.",
242
- inputSchema: {
243
- type: "object",
244
- properties: {
245
- customerId: { type: "string" },
246
- currency: { type: "string", default: "USD" },
247
- },
248
- },
249
- handler: async (params) => {
250
- const input = asObject(params);
251
- const customerId = readString(input, "customerId");
252
- const currency = readString(input, "currency");
253
- const result = await kernel.services.cart.create({
254
- ...(customerId !== undefined ? { customerId } : {}),
255
- ...(currency !== undefined ? { currency } : {}),
256
- }, kernel.getMCPActor());
257
- if (!result.ok)
258
- return { error: result.error };
259
- return textContent(result.value);
260
- },
261
- },
262
- {
263
- name: "cart_add_item",
264
- description: "Add item to cart. If entity has variants and no variantId provided, fails with available variants.",
265
- inputSchema: {
266
- type: "object",
267
- required: ["cartId", "entityId"],
268
- properties: {
269
- cartId: { type: "string" },
270
- entityId: { type: "string" },
271
- variantId: { type: "string" },
272
- quantity: { type: "number", default: 1 },
273
- },
274
- },
275
- handler: async (params) => {
276
- const input = asObject(params);
277
- const cartId = readString(input, "cartId");
278
- const entityId = readString(input, "entityId");
279
- const variantId = readString(input, "variantId");
280
- const quantity = readNumber(input, "quantity");
281
- if (!cartId || !entityId) {
282
- return validationError("cartId and entityId are required.");
283
- }
284
- const result = await kernel.services.cart.addItem({
285
- cartId,
286
- entityId,
287
- ...(variantId !== undefined ? { variantId } : {}),
288
- quantity: quantity ?? 1,
289
- }, kernel.getMCPActor());
290
- if (!result.ok)
291
- return { error: result.error };
292
- return textContent(result.value);
293
- },
294
- },
295
- {
296
- name: "order_get",
297
- description: "Get order details by ID or order number. Includes line items, payment, fulfillment, and AI context.",
298
- inputSchema: {
299
- type: "object",
300
- properties: {
301
- orderId: { type: "string" },
302
- orderNumber: { type: "string" },
303
- },
304
- },
305
- handler: async (params) => {
306
- const input = asObject(params);
307
- const orderId = readString(input, "orderId");
308
- const orderNumber = readString(input, "orderNumber");
309
- if (!orderId && !orderNumber) {
310
- return validationError("Either orderId or orderNumber is required.");
311
- }
312
- const result = orderId
313
- ? await kernel.services.orders.getById(orderId, kernel.getMCPActor())
314
- : await kernel.services.orders.getByNumber(orderNumber ?? "", kernel.getMCPActor());
315
- if (!result.ok)
316
- return { error: result.error };
317
- const enriched = enrichOrderForAgent(result.value, kernel.getMCPActor().permissions);
318
- return textContent(enriched);
319
- },
320
- },
321
- {
322
- name: "order_list",
323
- description: "List orders with pagination and optional status filter.",
324
- inputSchema: {
325
- type: "object",
326
- properties: {
327
- page: { type: "number", default: 1 },
328
- limit: { type: "number", default: 20 },
329
- status: { type: "string" },
330
- },
331
- },
332
- handler: async (params) => {
333
- const input = asObject(params);
334
- const page = readNumber(input, "page");
335
- const limit = readNumber(input, "limit");
336
- const status = readString(input, "status");
337
- const result = await kernel.services.orders.list({
338
- ...(page !== undefined ? { page } : {}),
339
- ...(limit !== undefined ? { limit } : {}),
340
- ...(status !== undefined ? { status } : {}),
341
- }, kernel.getMCPActor());
342
- if (!result.ok)
343
- return { error: result.error };
344
- return textContent({
345
- ...result.value,
346
- items: result.value.items.map((order) => enrichOrderForAgent(order, kernel.getMCPActor().permissions)),
347
- });
348
- },
349
- },
350
- {
351
- name: "analytics_query",
352
- description: "Query analytics using semantic measures, dimensions, time dimensions, and filters.",
353
- inputSchema: {
354
- type: "object",
355
- required: ["measures"],
356
- properties: {
357
- measures: {
358
- type: "array",
359
- items: { type: "string" },
360
- },
361
- dimensions: {
362
- type: "array",
363
- items: { type: "string" },
364
- },
365
- timeDimensions: {
366
- type: "array",
367
- items: {
368
- type: "object",
369
- properties: {
370
- dimension: { type: "string" },
371
- granularity: {
372
- type: "string",
373
- enum: ["day", "week", "month", "year"],
374
- },
375
- dateRange: {
376
- oneOf: [
377
- { type: "string" },
378
- {
379
- type: "array",
380
- items: { type: "string" },
381
- minItems: 2,
382
- maxItems: 2,
383
- },
384
- ],
385
- },
386
- },
387
- required: ["dimension"],
388
- },
389
- },
390
- filters: {
391
- type: "array",
392
- items: {
393
- type: "object",
394
- properties: {
395
- member: { type: "string" },
396
- operator: {
397
- type: "string",
398
- enum: [
399
- "equals",
400
- "notEquals",
401
- "contains",
402
- "in",
403
- "notIn",
404
- "gt",
405
- "gte",
406
- "lt",
407
- "lte",
408
- "beforeDate",
409
- "afterDate",
410
- "inDateRange",
411
- ],
412
- },
413
- values: {
414
- type: "array",
415
- items: { type: "string" },
416
- },
417
- },
418
- required: ["member", "operator"],
419
- },
420
- },
421
- order: {
422
- type: "object",
423
- additionalProperties: {
424
- type: "string",
425
- enum: ["asc", "desc"],
426
- },
427
- },
428
- limit: { type: "number", default: 100 },
429
- },
430
- },
431
- handler: async (params) => {
432
- const input = asObject(params);
433
- const measures = readStringArray(input, "measures");
434
- const limit = readNumber(input, "limit");
435
- if (measures.length === 0) {
436
- return validationError("measures is required.");
437
- }
438
- const queryParams = {
439
- measures,
440
- ...(Array.isArray(input.dimensions)
441
- ? {
442
- dimensions: input.dimensions.filter((item) => typeof item === "string"),
443
- }
444
- : {}),
445
- ...(Array.isArray(input.timeDimensions)
446
- ? {
447
- timeDimensions: input.timeDimensions,
448
- }
449
- : {}),
450
- ...(Array.isArray(input.filters)
451
- ? {
452
- filters: input.filters,
453
- }
454
- : {}),
455
- ...(input.order &&
456
- typeof input.order === "object" &&
457
- !Array.isArray(input.order)
458
- ? {
459
- order: input.order,
460
- }
461
- : {}),
462
- ...(limit !== undefined ? { limit } : {}),
463
- };
464
- // Scope is always derived from the actor — never manually constructed.
465
- const analyticsScope = buildAnalyticsScope(kernel.getMCPActor());
466
- const result = await kernel.services.analytics.query(queryParams, analyticsScope);
467
- if (!result.ok)
468
- return { error: result.error };
469
- return textContent(result.value);
470
- },
471
- },
472
- {
473
- name: "analytics_meta",
474
- description: "List available analytics measures, dimensions, segments, and models.",
475
- inputSchema: {
476
- type: "object",
477
- },
478
- handler: async () => {
479
- const metaScope = buildAnalyticsScope(kernel.getMCPActor());
480
- const result = await kernel.services.analytics.getMeta();
481
- if (!result.ok)
482
- return { error: result.error };
483
- return textContent(result.value);
484
- },
485
- },
486
- ],
487
- resources: [
488
- {
489
- uri: "commerce://schema/entity-types",
490
- name: "Entity Type Schema",
491
- description: "Complete schema of all entity types, fields, variants, fulfillment strategies.",
8
+ // ─── Core Resource Registration ─────────────────────────────────────────────
9
+ export function registerCoreResources(server, kernel) {
10
+ server.registerResource("Entity Type Schema", "commerce://schema/entity-types", {
11
+ description: "Complete entity type schema including fields, variants, and fulfillment strategies.",
12
+ mimeType: "application/json",
13
+ }, async (uri) => ({
14
+ contents: [{
15
+ uri: uri.toString(),
16
+ text: JSON.stringify(kernel.config.entities ?? {}, null, 2),
492
17
  mimeType: "application/json",
493
- handler: async () => ({
494
- content: [
495
- {
496
- type: "text",
497
- text: JSON.stringify(kernel.config.entities ?? {}, null, 2),
498
- },
499
- ],
500
- }),
501
- },
502
- {
503
- uri: "commerce://schema/order-states",
504
- name: "Order State Machine",
505
- description: "All order states and valid transitions.",
18
+ }],
19
+ }));
20
+ server.registerResource("Order State Machine", "commerce://schema/order-states", {
21
+ description: "Valid order status transitions and the complete state machine definition.",
22
+ mimeType: "application/json",
23
+ }, async (uri) => ({
24
+ contents: [{
25
+ uri: uri.toString(),
26
+ text: JSON.stringify(orderStateMachine, null, 2),
506
27
  mimeType: "application/json",
507
- handler: async () => ({
508
- content: [
509
- { type: "text", text: JSON.stringify(orderStateMachine, null, 2) },
510
- ],
511
- }),
512
- },
513
- ],
514
- };
28
+ }],
29
+ }));
515
30
  }
@@ -0,0 +1,120 @@
1
+ /**
2
+ * Fluent builder for STRAP-pattern MCP tools.
3
+ *
4
+ * Produces a single MCPTool with an `action` enum from multiple
5
+ * action definitions. Each action has its own Zod schema and typed handler.
6
+ *
7
+ * @example
8
+ * ```typescript
9
+ * import { toolBuilder } from "@unifiedcommerce/core";
10
+ *
11
+ * mcpTools: (ctx) => {
12
+ * const t = toolBuilder("loyalty", "Manage loyalty points and rewards.");
13
+ *
14
+ * t.action("balance", "Check a customer's point balance and tier.")
15
+ * .input(z.object({ customerId: z.string().describe("Customer UUID") }))
16
+ * .handler(async ({ customerId }, { services }) =>
17
+ * (services as LoyaltyServices).loyalty.getPoints(customerId),
18
+ * );
19
+ *
20
+ * t.action("earn", "Award points to a customer.")
21
+ * .input(z.object({
22
+ * customerId: z.string().describe("Customer UUID"),
23
+ * amount: z.number().int().positive().describe("Points to award"),
24
+ * }))
25
+ * .handler(async ({ customerId, amount }, { services }) =>
26
+ * (services as LoyaltyServices).loyalty.earn(customerId, amount),
27
+ * );
28
+ *
29
+ * return t.build(ctx);
30
+ * },
31
+ * ```
32
+ */
33
+ import { z } from "zod";
34
+ import type { MCPTool } from "../../config/types.js";
35
+ import type { PluginContext } from "../../kernel/plugin/manifest.js";
36
+ interface ActionHandlerContext {
37
+ services: Record<string, unknown>;
38
+ db: unknown;
39
+ logger: {
40
+ info(msg: string, data?: unknown): void;
41
+ warn(msg: string, data?: unknown): void;
42
+ error(msg: string, data?: unknown): void;
43
+ };
44
+ }
45
+ interface ActionDefinition {
46
+ name: string;
47
+ description: string;
48
+ inputSchema: z.ZodObject<z.ZodRawShape>;
49
+ handler: (args: Record<string, unknown>, ctx: ActionHandlerContext) => Promise<unknown>;
50
+ }
51
+ /**
52
+ * Fluent chain returned by `t.action(name, description)`.
53
+ *
54
+ * Generic parameter `TArgs` tracks the inferred input type so that
55
+ * `.handler()` receives fully typed args — no manual casts needed.
56
+ * The type is carried as a plain object type (not z.infer) so consumers
57
+ * don't need `zod` types available at compile time.
58
+ */
59
+ declare class ActionChain<TArgs extends Record<string, unknown> = Record<string, unknown>> {
60
+ private _name;
61
+ private _description;
62
+ private _actions;
63
+ private _input;
64
+ private _handler;
65
+ constructor(_name: string, _description: string, _actions: ActionDefinition[]);
66
+ /**
67
+ * Define the Zod input schema for this action.
68
+ * Returns a new chain typed with the inferred output so `.handler()` gets typed args.
69
+ *
70
+ * The dual generic `TSchema` / `TOut` lets TypeScript:
71
+ * 1. Infer `TSchema` from the ZodObject's raw shape (for internal storage)
72
+ * 2. Infer `TOut` from the ZodObject's output type (for handler typing)
73
+ * Since `TOut` is a plain object type (not `z.infer`), the emitted `.d.ts`
74
+ * doesn't require consumers to have `zod` types at compile time.
75
+ */
76
+ input<TSchema extends z.ZodRawShape, TOut extends Record<string, unknown> = z.infer<z.ZodObject<TSchema>>>(schema: z.ZodObject<TSchema> & {
77
+ _zod: {
78
+ output: TOut;
79
+ };
80
+ }): ActionChain<TOut>;
81
+ /**
82
+ * Define the handler for this action.
83
+ * Receives typed args (inferred from `.input()`) and a context with services and db.
84
+ * Return any value — it is auto-wrapped in MCP result format.
85
+ */
86
+ handler(fn: (args: TArgs, ctx: ActionHandlerContext) => Promise<unknown>): void;
87
+ }
88
+ declare class ToolBuilderImpl {
89
+ private _name;
90
+ private _description;
91
+ private _actions;
92
+ constructor(_name: string, _description: string);
93
+ /**
94
+ * Define an action on this STRAP tool.
95
+ * Returns a chain where you call .input(schema).handler(fn).
96
+ */
97
+ action(name: string, description: string): ActionChain;
98
+ /**
99
+ * Build the MCPTool[] array (always 1 tool) from all registered actions.
100
+ *
101
+ * Automatically:
102
+ * - Creates the `action` enum from action names
103
+ * - Merges all action input schemas (fields become optional)
104
+ * - Generates description listing all actions
105
+ * - Generates switch/case dispatch
106
+ * - Wraps results in MCP content format
107
+ * - Handles errors consistently
108
+ */
109
+ build(ctx: PluginContext): MCPTool[];
110
+ }
111
+ /**
112
+ * Create a STRAP-pattern MCP tool builder.
113
+ *
114
+ * @param name - Tool name in snake_case (e.g., "loyalty", "pos_shift")
115
+ * @param description - Base description explaining the tool's domain.
116
+ * Action descriptions are appended automatically.
117
+ */
118
+ export declare function toolBuilder(name: string, description: string): ToolBuilderImpl;
119
+ export {};
120
+ //# sourceMappingURL=tool-builder.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tool-builder.d.ts","sourceRoot":"","sources":["../../../src/interfaces/mcp/tool-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAIrE,UAAU,oBAAoB;IAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAC;CACxI;AAED,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACxC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACzF;AAID;;;;;;;GAOG;AACH,cAAM,WAAW,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAK7E,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,QAAQ;IANlB,OAAO,CAAC,MAAM,CAA4C;IAC1D,OAAO,CAAC,QAAQ,CAA+F;gBAGrG,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,gBAAgB,EAAE;IAGtC;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC,WAAW,EAAE,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,EACvG,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG;QAAE,IAAI,EAAE;YAAE,MAAM,EAAE,IAAI,CAAA;SAAE,CAAA;KAAE,GACxD,WAAW,CAAC,IAAI,CAAC;IAQpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI;CAShF;AAID,cAAM,eAAe;IAIjB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,YAAY;IAJtB,OAAO,CAAC,QAAQ,CAA0B;gBAGhC,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM;IAG9B;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,WAAW;IAItD;;;;;;;;;;OAUG;IACH,KAAK,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,EAAE;CA8GrC;AAID;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,eAAe,CAE9E"}