@reactionary/core 0.10.26 → 0.10.28

package/capabilities/base.capability.js

@@ -1,5 +1,8 @@
 import {} from "../schemas/session.schema.js";
 import { hasher } from "node-object-hash";
+import {
+  REACTIONARY_ENTRYPOINT_METADATA
+} from "../decorators/reactionary.metadata.js";
 class BaseCapability {
   cache;
   context;
@@ -7,6 +10,9 @@ class BaseCapability {
     this.cache = cache;
     this.context = context;
   }
+  getReactionaryResourceName() {
+    return this.getResourceName();
+  }
   generateDependencyIdsForModel(model) {
     const identifier = model?.identifier;
     if (!identifier) {
@@ -22,6 +28,35 @@ class BaseCapability {
     return `${scope}:${queryHash}:${locale}:${currency}`;
   }
 }
+function getReactionaryEntrypoints(capability) {
+  const entrypoints = [];
+  const seenMethodNames = /* @__PURE__ */ new Set();
+  let prototype = Object.getPrototypeOf(capability);
+  while (prototype && prototype !== BaseCapability.prototype) {
+    for (const propertyName of Object.getOwnPropertyNames(prototype)) {
+      if (propertyName === "constructor" || seenMethodNames.has(propertyName)) {
+        continue;
+      }
+      const descriptor = Object.getOwnPropertyDescriptor(prototype, propertyName);
+      if (typeof descriptor?.value !== "function") {
+        continue;
+      }
+      seenMethodNames.add(propertyName);
+      const method = descriptor.value;
+      const metadata = method[REACTIONARY_ENTRYPOINT_METADATA];
+      if (!metadata) {
+        continue;
+      }
+      entrypoints.push({
+        ...metadata,
+        capabilityName: capability.getReactionaryResourceName()
+      });
+    }
+    prototype = Object.getPrototypeOf(prototype);
+  }
+  return entrypoints;
+}
 export {
-  BaseCapability
+  BaseCapability,
+  getReactionaryEntrypoints
 };

package/decorators/index.js

@@ -1 +1,2 @@
 export * from "./reactionary.decorator.js";
+export * from "./reactionary.metadata.js";

package/decorators/reactionary.decorator.js

@@ -1,5 +1,8 @@
 import { SpanStatusCode, trace } from "@opentelemetry/api";
 import * as z from "zod";
+import {
+  REACTIONARY_ENTRYPOINT_METADATA
+} from "./reactionary.metadata.js";
 import { getReactionaryMeter } from "../metrics/metrics.js";
 import { error, success } from "../schemas/result.js";
 const TRACER_NAME = "@reactionary";
@@ -37,6 +40,14 @@ class ReactionaryDecoratorOptions {
    * The schema for the primary output type, for validation purposes
    */
   outputSchema = z.unknown();
+  /**
+   * Optional human-readable title for external surfaces such as MCP tools.
+   */
+  title = void 0;
+  /**
+   * Optional human-readable description for external surfaces such as MCP tools.
+   */
+  description = void 0;
 }
 function Reactionary(options) {
   return function(target, propertyKey, descriptor) {
@@ -59,18 +70,26 @@ function Reactionary(options) {
       return traceSpan(scope, async () => {
         meter.requestInProgress.add(1, attributes);
         try {
-          const input = validateInput(args[0], configuration.inputSchema);
+          const input = validateInput(
+            args[0],
+            configuration.inputSchema
+          );
           if (!input.success) {
             return input;
           }
-          const localeCacheKey = options.localeDependentCaching ? this.context.languageContext?.locale ?? "all" : "all";
-          const currencyCacheKey = options.currencyDependentCaching ? this.context.languageContext?.currencyCode ?? "all" : "all";
-          const cacheKey = this.generateCacheKeyForQuery(scope, input.value, localeCacheKey, currencyCacheKey);
+          const localeCacheKey = configuration.localeDependentCaching ? this.context.languageContext?.locale ?? "all" : "all";
+          const currencyCacheKey = configuration.currencyDependentCaching ? this.context.languageContext?.currencyCode ?? "all" : "all";
+          const cacheKey = this.generateCacheKeyForQuery(
+            scope,
+            input.value,
+            localeCacheKey,
+            currencyCacheKey
+          );
           let fromCache = null;
-          if (options.cache) {
+          if (configuration.cache) {
             fromCache = await this.cache.get(
               cacheKey,
-              options.outputSchema
+              configuration.outputSchema
             );
           }
           let result;
@@ -79,7 +98,7 @@ function Reactionary(options) {
             const r = result;
             if (r.success) {
               const dependencyIds = this.generateDependencyIdsForModel(r.value);
-              if (options.cache) {
+              if (configuration.cache) {
                 this.cache.put(cacheKey, r.value, {
                   ttlSeconds: configuration.cacheTimeToLiveInSeconds,
                   dependencyIds
@@ -123,6 +142,17 @@ function Reactionary(options) {
         }
       });
     };
+    descriptor.value[REACTIONARY_ENTRYPOINT_METADATA] = {
+      methodName: propertyKey.toString(),
+      inputSchema: configuration.inputSchema,
+      outputSchema: configuration.outputSchema,
+      title: configuration.title,
+      description: configuration.description,
+      cache: configuration.cache,
+      localeDependentCaching: configuration.localeDependentCaching,
+      currencyDependentCaching: configuration.currencyDependentCaching,
+      cacheTimeToLiveInSeconds: configuration.cacheTimeToLiveInSeconds
+    };
     return descriptor;
   };
 }

package/decorators/reactionary.metadata.js

@@ -0,0 +1,6 @@
+const REACTIONARY_ENTRYPOINT_METADATA = /* @__PURE__ */ Symbol.for(
+  "@reactionary/entrypoint-metadata"
+);
+export {
+  REACTIONARY_ENTRYPOINT_METADATA
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reactionary/core",
-  "version": "0.10.26",
+  "version": "0.10.28",
   "type": "module",
   "main": "./index.js",
   "types": "./src/index.d.ts",

package/schemas/models/cost.model.js

@@ -1,18 +1,22 @@
 import * as z from "zod";
 import { MonetaryAmountSchema } from "./price.model.js";
+const EmptyMonetaryAmount = {
+  value: 0,
+  currency: "EUR"
+};
 const CostBreakDownSchema = z.looseObject({
-  totalTax: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The amount of tax paid on the cart. This may include VAT, GST, sales tax, etc."),
-  totalDiscount: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The amount of discount applied to the cart."),
-  totalSurcharge: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The amount of surcharge applied to the cart."),
-  totalShipping: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The amount of shipping fees for the cart."),
-  totalProductPrice: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The total price of products in the cart."),
-  grandTotal: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The total price for the cart including all taxes, discounts, and shipping.")
+  totalTax: MonetaryAmountSchema.default(EmptyMonetaryAmount).describe("The amount of tax paid on the cart. This may include VAT, GST, sales tax, etc."),
+  totalDiscount: MonetaryAmountSchema.default(EmptyMonetaryAmount).describe("The amount of discount applied to the cart."),
+  totalSurcharge: MonetaryAmountSchema.default(EmptyMonetaryAmount).describe("The amount of surcharge applied to the cart."),
+  totalShipping: MonetaryAmountSchema.default(EmptyMonetaryAmount).describe("The amount of shipping fees for the cart."),
+  totalProductPrice: MonetaryAmountSchema.default(EmptyMonetaryAmount).describe("The total price of products in the cart."),
+  grandTotal: MonetaryAmountSchema.default(EmptyMonetaryAmount).describe("The total price for the cart including all taxes, discounts, and shipping.")
 });
 const ItemCostBreakdownSchema = z.looseObject({
-  unitPrice: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The price per single unit of the item."),
-  unitDiscount: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The discount applied per single unit of the item."),
-  totalPrice: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The total price for all units of the item."),
-  totalDiscount: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The total discount applied to all units of the item.")
+  unitPrice: MonetaryAmountSchema.default(EmptyMonetaryAmount).describe("The price per single unit of the item."),
+  unitDiscount: MonetaryAmountSchema.default(EmptyMonetaryAmount).describe("The discount applied per single unit of the item."),
+  totalPrice: MonetaryAmountSchema.default(EmptyMonetaryAmount).describe("The total price for all units of the item."),
+  totalDiscount: MonetaryAmountSchema.default(EmptyMonetaryAmount).describe("The total discount applied to all units of the item.")
 });
 export {
   CostBreakDownSchema,

package/schemas/session.schema.js

@@ -5,7 +5,8 @@ import { IdentitySchema } from "./models/identity.model.js";
 import { PersonalizationProfileSchema } from "./models/personalization-profile.model.js";
 const LanguageContextSchema = z.looseObject({
   locale: z.string().default("en-US").meta({ description: "The locale for the current request, in IETF BCP 47 format (e.g. en-US, fr-FR). This can be used for localization and internationalization purposes." }),
-  currencyCode: CurrencySchema.default(() => CurrencySchema.parse({}))
+  // TODO: Replace this hardcoded fallback with a configured project/store currency.
+  currencyCode: CurrencySchema.default("EUR")
 });
 const IdentityContextSchema = z.looseObject({
   identity: IdentitySchema,

package/src/capabilities/base.capability.d.ts

@@ -1,5 +1,7 @@
 import type { Cache } from '../cache/cache.interface.js';
 import { type RequestContext } from '../schemas/session.schema.js';
+import { type ReactionaryEntrypointMetadata } from '../decorators/reactionary.metadata.js';
+export type { ReactionaryEntrypointMetadata, ReactionaryEntrypointMethod, } from '../decorators/reactionary.metadata.js';
 /**
  * Base capability abstraction, responsible for mutations (changes) and queries (fetches)
  * for a given business object domain.
@@ -8,6 +10,7 @@ export declare abstract class BaseCapability {
     protected cache: Cache;
     protected context: RequestContext;
     constructor(cache: Cache, context: RequestContext);
+    getReactionaryResourceName(): string;
     generateDependencyIdsForModel(model: unknown): Array<string>;
     protected generateCacheKeyForQuery(scope: string, query: object, locale: string, currency: string): string;
     /**
@@ -15,3 +18,4 @@ export declare abstract class BaseCapability {
      */
     protected abstract getResourceName(): string;
 }
+export declare function getReactionaryEntrypoints(capability: BaseCapability): ReactionaryEntrypointMetadata[];

package/src/decorators/index.d.ts

@@ -1 +1,2 @@
 export * from './reactionary.decorator.js';
+export * from './reactionary.metadata.js';

package/src/decorators/reactionary.decorator.d.ts

@@ -1,6 +1,6 @@
 import type { Tracer } from '@opentelemetry/api';
 import * as z from 'zod';
-import type { BaseCapability } from '../capabilities/index.js';
+import type { BaseCapability } from '../capabilities/base.capability.js';
 import { type Result } from '../schemas/result.js';
 export declare function getTracer(): Tracer;
 /**
@@ -37,6 +37,14 @@ export declare class ReactionaryDecoratorOptions {
      * The schema for the primary output type, for validation purposes
      */
     outputSchema: z.ZodType;
+    /**
+     * Optional human-readable title for external surfaces such as MCP tools.
+     */
+    title: string | undefined;
+    /**
+     * Optional human-readable description for external surfaces such as MCP tools.
+     */
+    description: string | undefined;
 }
 /**
  * Decorator for capability functions to provide functionality such as caching, tracing and type-checked

package/src/decorators/reactionary.metadata.d.ts

@@ -0,0 +1,17 @@
+import type * as z from 'zod';
+export declare const REACTIONARY_ENTRYPOINT_METADATA: unique symbol;
+export interface ReactionaryEntrypointMetadata {
+    capabilityName: string;
+    methodName: string;
+    inputSchema: z.ZodType;
+    outputSchema: z.ZodType;
+    title?: string;
+    description?: string;
+    cache: boolean;
+    localeDependentCaching: boolean;
+    currencyDependentCaching: boolean;
+    cacheTimeToLiveInSeconds: number;
+}
+export type ReactionaryEntrypointMethod = ((...args: unknown[]) => unknown) & {
+    [REACTIONARY_ENTRYPOINT_METADATA]?: Omit<ReactionaryEntrypointMetadata, 'capabilityName'>;
+};