@unifiedcommerce/core 0.1.0 → 0.2.0

package/dist/interfaces/mcp/tool-builder.js

@@ -0,0 +1,224 @@
+/**
+ * Fluent builder for STRAP-pattern MCP tools.
+ *
+ * Produces a single MCPTool with an `action` enum from multiple
+ * action definitions. Each action has its own Zod schema and typed handler.
+ *
+ * @example
+ * ```typescript
+ * import { toolBuilder } from "@unifiedcommerce/core";
+ *
+ * mcpTools: (ctx) => {
+ *   const t = toolBuilder("loyalty", "Manage loyalty points and rewards.");
+ *
+ *   t.action("balance", "Check a customer's point balance and tier.")
+ *     .input(z.object({ customerId: z.string().describe("Customer UUID") }))
+ *     .handler(async ({ customerId }, { services }) =>
+ *       (services as LoyaltyServices).loyalty.getPoints(customerId),
+ *     );
+ *
+ *   t.action("earn", "Award points to a customer.")
+ *     .input(z.object({
+ *       customerId: z.string().describe("Customer UUID"),
+ *       amount: z.number().int().positive().describe("Points to award"),
+ *     }))
+ *     .handler(async ({ customerId, amount }, { services }) =>
+ *       (services as LoyaltyServices).loyalty.earn(customerId, amount),
+ *     );
+ *
+ *   return t.build(ctx);
+ * },
+ * ```
+ */
+import { z } from "zod";
+// ─── Action Chain ───────────────────────────────────────────────────────────
+/**
+ * Fluent chain returned by `t.action(name, description)`.
+ *
+ * Generic parameter `TArgs` tracks the inferred input type so that
+ * `.handler()` receives fully typed args — no manual casts needed.
+ * The type is carried as a plain object type (not z.infer) so consumers
+ * don't need `zod` types available at compile time.
+ */
+class ActionChain {
+    _name;
+    _description;
+    _actions;
+    _input = z.object({});
+    _handler;
+    constructor(_name, _description, _actions) {
+        this._name = _name;
+        this._description = _description;
+        this._actions = _actions;
+    }
+    /**
+     * Define the Zod input schema for this action.
+     * Returns a new chain typed with the inferred output so `.handler()` gets typed args.
+     *
+     * The dual generic `TSchema` / `TOut` lets TypeScript:
+     * 1. Infer `TSchema` from the ZodObject's raw shape (for internal storage)
+     * 2. Infer `TOut` from the ZodObject's output type (for handler typing)
+     * Since `TOut` is a plain object type (not `z.infer`), the emitted `.d.ts`
+     * doesn't require consumers to have `zod` types at compile time.
+     */
+    input(schema) {
+        // oRPC pattern: return a new instance with narrowed generic instead of
+        // casting `this`. Eliminates the `as unknown as` variance cast.
+        const chain = new ActionChain(this._name, this._description, this._actions);
+        chain._input = schema;
+        return chain;
+    }
+    /**
+     * Define the handler for this action.
+     * Receives typed args (inferred from `.input()`) and a context with services and db.
+     * Return any value — it is auto-wrapped in MCP result format.
+     */
+    handler(fn) {
+        this._handler = fn;
+        this._actions.push({
+            name: this._name,
+            description: this._description,
+            inputSchema: this._input,
+            handler: this._handler,
+        });
+    }
+}
+// ─── Tool Builder ───────────────────────────────────────────────────────────
+class ToolBuilderImpl {
+    _name;
+    _description;
+    _actions = [];
+    constructor(_name, _description) {
+        this._name = _name;
+        this._description = _description;
+    }
+    /**
+     * Define an action on this STRAP tool.
+     * Returns a chain where you call .input(schema).handler(fn).
+     */
+    action(name, description) {
+        return new ActionChain(name, description, this._actions);
+    }
+    /**
+     * Build the MCPTool[] array (always 1 tool) from all registered actions.
+     *
+     * Automatically:
+     * - Creates the `action` enum from action names
+     * - Merges all action input schemas (fields become optional)
+     * - Generates description listing all actions
+     * - Generates switch/case dispatch
+     * - Wraps results in MCP content format
+     * - Handles errors consistently
+     */
+    build(ctx) {
+        if (this._actions.length === 0)
+            return [];
+        const actionNames = this._actions.map((a) => a.name);
+        // Build combined Zod schema from all action schemas.
+        // Each action's fields become optional (since they are only required for their specific action).
+        // Then use Zod v4's built-in z.toJSONSchema() for correct conversion.
+        const combinedShape = {
+            action: z.enum(actionNames).describe("Operation to perform"),
+        };
+        for (const action of this._actions) {
+            const shape = action.inputSchema.shape;
+            for (const [key, zodType] of Object.entries(shape)) {
+                if (key === "action")
+                    continue;
+                if (combinedShape[key] != null)
+                    continue;
+                // All action-specific fields are optional in the combined schema
+                combinedShape[key] = zodType.optional();
+            }
+        }
+        const combinedZodSchema = z.object(combinedShape);
+        const jsonSchema = z.toJSONSchema(combinedZodSchema);
+        const allProperties = (jsonSchema.properties ?? {});
+        // Generate description with action list
+        const actionDescriptions = this._actions
+            .map((a) => `${a.name} (${a.description})`)
+            .join(", ");
+        const fullDescription = `${this._description} Actions: ${actionDescriptions}.`;
+        // Build the dispatch handler
+        const actions = this._actions;
+        const handlerCtx = {
+            services: ctx.services,
+            db: ctx.database.db,
+            logger: ctx.logger,
+        };
+        const tool = {
+            name: this._name,
+            description: fullDescription,
+            inputSchema: {
+                type: "object",
+                properties: allProperties,
+                required: ["action"],
+            },
+            handler: async (params) => {
+                const args = (params != null && typeof params === "object" && !Array.isArray(params))
+                    ? params
+                    : {};
+                const actionName = args.action;
+                if (!actionName) {
+                    return {
+                        content: [{ type: "text", text: JSON.stringify({ error: "action is required" }) }],
+                    };
+                }
+                const matchedAction = actions.find((a) => a.name === actionName);
+                if (!matchedAction) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    error: `Unknown action: ${actionName}. Available: ${actionNames.join(", ")}`,
+                                }),
+                            }],
+                    };
+                }
+                try {
+                    // Validate input against action-specific schema
+                    const parsed = matchedAction.inputSchema.safeParse(args);
+                    const validatedArgs = parsed.success ? parsed.data : args;
+                    const result = await matchedAction.handler(validatedArgs, handlerCtx);
+                    // Check for Result<T> pattern (ok/error)
+                    if (result != null && typeof result === "object") {
+                        const r = result;
+                        if ("ok" in r && r.ok === false && "error" in r) {
+                            return {
+                                content: [{ type: "text", text: JSON.stringify({ error: r.error }, null, 2) }],
+                            };
+                        }
+                        if ("ok" in r && r.ok === true && "value" in r) {
+                            return {
+                                content: [{ type: "text", text: JSON.stringify(r.value, null, 2) }],
+                            };
+                        }
+                    }
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                    };
+                }
+                catch (err) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) }, null, 2),
+                            }],
+                    };
+                }
+            },
+        };
+        return [tool];
+    }
+}
+// ─── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Create a STRAP-pattern MCP tool builder.
+ *
+ * @param name - Tool name in snake_case (e.g., "loyalty", "pos_shift")
+ * @param description - Base description explaining the tool's domain.
+ *   Action descriptions are appended automatically.
+ */
+export function toolBuilder(name, description) {
+    return new ToolBuilderImpl(name, description);
+}

package/dist/interfaces/mcp/tools/analytics.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import type { ToolDefinition } from "./registry.js";
+export declare const analyticsQuery: ToolDefinition<z.ZodObject<{
+    measures: z.ZodArray<z.ZodString>;
+    dimensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    timeDimensions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        dimension: z.ZodString;
+        granularity: z.ZodOptional<z.ZodEnum<{
+            month: "month";
+            day: "day";
+            week: "week";
+            year: "year";
+        }>>;
+        dateRange: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodTuple<[z.ZodString, z.ZodString], null>]>>;
+    }, z.core.$strip>>>;
+    filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        member: z.ZodString;
+        operator: z.ZodEnum<{
+            in: "in";
+            gt: "gt";
+            gte: "gte";
+            lt: "lt";
+            lte: "lte";
+            contains: "contains";
+            equals: "equals";
+            notEquals: "notEquals";
+            notIn: "notIn";
+            beforeDate: "beforeDate";
+            afterDate: "afterDate";
+            inDateRange: "inDateRange";
+        }>;
+        values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    order: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>>;
+export declare const analyticsMeta: ToolDefinition<z.ZodObject<{}, z.core.$strip>>;
+export declare const analyticsTools: ToolDefinition[];
+//# sourceMappingURL=analytics.d.ts.map

package/dist/interfaces/mcp/tools/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/mcp/tools/analytics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAIpD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAkDzB,CAAC;AAEH,eAAO,MAAM,aAAa,gDAYxB,CAAC;AAEH,eAAO,MAAM,cAAc,EAAE,cAAc,EAG1C,CAAC"}

package/dist/interfaces/mcp/tools/analytics.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { defineTool } from "./registry.js";
+import { buildAnalyticsScope } from "../../../modules/analytics/types.js";
+export const analyticsQuery = defineTool({
+    name: "analytics_query",
+    description: "Query analytics using semantic measures, dimensions, time dimensions, " +
+        "and filters. Use when the user asks about revenue, sales trends, order " +
+        "metrics, or any business intelligence question. Always call analytics_meta " +
+        "first to discover available measures.",
+    inputSchema: z.object({
+        measures: z.array(z.string()).min(1).describe("Measure names (e.g. Orders.totalRevenue)"),
+        dimensions: z.array(z.string()).optional().describe("Dimension names to group by"),
+        timeDimensions: z.array(z.object({
+            dimension: z.string().describe("Time dimension name"),
+            granularity: z.enum(["day", "week", "month", "year"]).optional().describe("Time granularity"),
+            dateRange: z.union([
+                z.string(),
+                z.tuple([z.string(), z.string()]),
+            ]).optional().describe("Date range: preset string or [from, to] tuple"),
+        })).optional().describe("Time dimensions for trend analysis"),
+        filters: z.array(z.object({
+            member: z.string().describe("Measure or dimension to filter on"),
+            operator: z.enum([
+                "equals", "notEquals", "contains", "in", "notIn",
+                "gt", "gte", "lt", "lte", "beforeDate", "afterDate", "inDateRange",
+            ]).describe("Comparison operator"),
+            values: z.array(z.string()).optional().describe("Filter values"),
+        })).optional().describe("Query filters"),
+        order: z.record(z.string(), z.enum(["asc", "desc"])).optional().describe("Sort order by measure/dimension"),
+        limit: z.number().int().positive().default(100).describe("Max rows to return"),
+    }),
+    async handler({ measures, dimensions, timeDimensions, filters, order, limit }, kernel) {
+        const queryParams = {
+            measures,
+            ...(dimensions != null ? { dimensions } : {}),
+            ...(timeDimensions != null
+                ? { timeDimensions: timeDimensions }
+                : {}),
+            ...(filters != null
+                ? { filters: filters }
+                : {}),
+            ...(order != null
+                ? { order: order }
+                : {}),
+            ...(limit !== undefined ? { limit } : {}),
+        };
+        const analyticsScope = buildAnalyticsScope(kernel.getMCPActor());
+        const result = await kernel.services.analytics.query(queryParams, analyticsScope);
+        if (!result.ok)
+            return { _error: result.error };
+        return result.value;
+    },
+});
+export const analyticsMeta = defineTool({
+    name: "analytics_meta",
+    description: "List available analytics measures, dimensions, segments, and models. " +
+        "Use this before analytics_query to discover what measures and dimensions " +
+        "you can query. Call this first when the user asks analytics questions.",
+    inputSchema: z.object({}),
+    async handler(_args, kernel) {
+        const result = await kernel.services.analytics.getMeta();
+        if (!result.ok)
+            return { _error: result.error };
+        return result.value;
+    },
+});
+export const analyticsTools = [
+    analyticsQuery,
+    analyticsMeta,
+];

package/dist/interfaces/mcp/tools/cart.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import type { ToolDefinition } from "./registry.js";
+export declare const cartCreate: ToolDefinition<z.ZodObject<{
+    customerId: z.ZodOptional<z.ZodString>;
+    currency: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>>;
+export declare const cartAddItem: ToolDefinition<z.ZodObject<{
+    cartId: z.ZodString;
+    entityId: z.ZodString;
+    variantId: z.ZodOptional<z.ZodString>;
+    quantity: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>>;
+export declare const cartTools: ToolDefinition[];
+//# sourceMappingURL=cart.d.ts.map

package/dist/interfaces/mcp/tools/cart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cart.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/mcp/tools/cart.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,eAAO,MAAM,UAAU;;;kBAoBrB,CAAC;AAEH,eAAO,MAAM,WAAW;;;;;kBAyBtB,CAAC;AAEH,eAAO,MAAM,SAAS,EAAE,cAAc,EAGrC,CAAC"}

package/dist/interfaces/mcp/tools/cart.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { defineTool } from "./registry.js";
+export const cartCreate = defineTool({
+    name: "cart_create",
+    description: "Create a new shopping cart. Use when the user wants to start a new order " +
+        "or add items for purchase. Returns the cart ID for subsequent operations.",
+    inputSchema: z.object({
+        customerId: z.string().optional().describe("Customer UUID to associate the cart with"),
+        currency: z.string().default("USD").describe("Cart currency (ISO 4217)"),
+    }),
+    async handler({ customerId, currency }, kernel) {
+        const result = await kernel.services.cart.create({
+            ...(customerId !== undefined ? { customerId } : {}),
+            ...(currency !== undefined ? { currency } : {}),
+        }, kernel.getMCPActor());
+        if (!result.ok)
+            return { _error: result.error };
+        return result.value;
+    },
+});
+export const cartAddItem = defineTool({
+    name: "cart_add_item",
+    description: "Add an item to a cart. Use when the user wants to add a product to their " +
+        "cart. If the entity has variants and no variantId is provided, the call " +
+        "fails and returns available variants for selection.",
+    inputSchema: z.object({
+        cartId: z.string().describe("UUID of the cart"),
+        entityId: z.string().describe("UUID of the catalog entity to add"),
+        variantId: z.string().optional().describe("Variant UUID (required if entity has variants)"),
+        quantity: z.number().int().positive().default(1).describe("Quantity to add"),
+    }),
+    async handler({ cartId, entityId, variantId, quantity }, kernel) {
+        const result = await kernel.services.cart.addItem({
+            cartId,
+            entityId,
+            ...(variantId !== undefined ? { variantId } : {}),
+            quantity,
+        }, kernel.getMCPActor());
+        if (!result.ok)
+            return { _error: result.error };
+        return result.value;
+    },
+});
+export const cartTools = [
+    cartCreate,
+    cartAddItem,
+];

package/dist/interfaces/mcp/tools/catalog.d.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import type { ToolDefinition } from "./registry.js";
+export declare const catalogSearch: ToolDefinition<z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodString>;
+    categorySlug: z.ZodOptional<z.ZodString>;
+    brandSlug: z.ZodOptional<z.ZodString>;
+    page: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>>;
+export declare const catalogCreate: ToolDefinition<z.ZodObject<{
+    type: z.ZodString;
+    slug: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>>;
+export declare const catalogGet: ToolDefinition<z.ZodObject<{
+    entityId: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+    locale: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>>;
+export declare const catalogManage: ToolDefinition<z.ZodObject<{
+    action: z.ZodEnum<{
+        delete: "delete";
+        update: "update";
+        publish: "publish";
+        archive: "archive";
+        discontinue: "discontinue";
+        set_attributes: "set_attributes";
+        assign_category: "assign_category";
+        unassign_category: "unassign_category";
+        assign_brand: "assign_brand";
+        unassign_brand: "unassign_brand";
+        create_variant: "create_variant";
+    }>;
+    entityId: z.ZodString;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    isVisible: z.ZodOptional<z.ZodBoolean>;
+    locale: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    subtitle: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    richDescription: z.ZodOptional<z.ZodString>;
+    seoTitle: z.ZodOptional<z.ZodString>;
+    seoDescription: z.ZodOptional<z.ZodString>;
+    categoryId: z.ZodOptional<z.ZodString>;
+    brandId: z.ZodOptional<z.ZodString>;
+    sku: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export declare const catalogTools: ToolDefinition[];
+//# sourceMappingURL=catalog.d.ts.map

package/dist/interfaces/mcp/tools/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/mcp/tools/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAKpD,eAAO,MAAM,aAAa;;;;;;;;kBA+ExB,CAAC;AAEH,eAAO,MAAM,aAAa;;;;;;kBA+BxB,CAAC;AAEH,eAAO,MAAM,UAAU;;;;kBA8CrB,CAAC;AAEH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA0HxB,CAAC;AAEH,eAAO,MAAM,YAAY,EAAE,cAAc,EAKxC,CAAC"}