@reactionary/source 0.0.52 → 0.2.16

package/.env-template

@@ -11,3 +11,22 @@ OTEL_SERVICE_NAME=reactionary
 OTEL_LOG_LEVEL=info
 OTEL_TRACES_EXPORTER=console
 OTEL_METRICS_EXPORTER=console
+
+
+
+MEILISEARCH_API_URL=
+MEILISEARCH_API_KEY=
+MEILISEARCH_INDEX=icecat_products
+MEILISEARCH_USE_AI_EMBEDDING=huggingface
+
+
+ALGOLIA_API_KEY=
+ALGOLIA_APP_ID=
+ALGOLIA_INDEX=icecat_products
+
+
+
+MEDUSA_PUBLISHABLE_KEY=
+MEDUSA_ADMIN_KEY=
+MEDUSA_API_URL=
+MEDUSA_DEFAULT_CURRENCY=EUR

package/.github/workflows/pull-request.yml

@@ -25,7 +25,7 @@ jobs:
 
       - uses: pnpm/action-setup@v4
 
-      - run: pnpm dlx nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"
+      - run: pnpm dlx nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="test"
 
       - uses: actions/setup-node@v4
         with:
@@ -37,3 +37,5 @@ jobs:
       - uses: nrwl/nx-set-shas@v4
 
       - run: pnpm exec nx affected -t lint build
+
+      - run: pnpm exec nx test core

package/.github/workflows/release.yml

@@ -2,9 +2,18 @@ name: release
 
 on:
   push:
+    paths-ignore:
+      - 'docs/**'
+      - '.gitignore'
+      - 'README.md'
+      - 'documentation/**'
+      - '**/*.md'
+
     branches:
       main
 
+
+
 permissions:
   actions: read
   contents: write

package/.vscode/extensions.json

@@ -1,9 +1,7 @@
 {
   "recommendations": [
-    "nrwl.angular-console",
     "esbenp.prettier-vscode",
     "dbaeumer.vscode-eslint",
-    "firsttris.vscode-jest-runner",
     "ms-playwright.playwright"
   ]
 }

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Solteq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -43,38 +43,190 @@ The following is a short list of commonly used terms and phrases, to keep guessi
 ## TODO:
 
 
+### Roadmap to V0.1
+Usecase: As a shopper i search for products, add to cart and check out.
+Vendors: Commercetools, Algolia, Medusa
+
+UX Pages and components supported:
+- PDP
+  - Product info
+  - Attribute table
+  - Variant selection
+  - Inventory display
+  - Price display (simple pricing)
+- PLP - Keyword Search + Facet
+- Minicart
+- Cart Page
+- Checkout - Address 
+- Checkout - Shipping
+- Checkout - Payment
+- Checkout - Confirmation
+- Account - Sign up (email, password)
+- Account - Log in (email, password)
+
+#### Tasks:
+- [X] Cart - Remove checkout related functions - AKJ
+- [X] Checkout - Receive full cart in input - MR
+- [X] Inventory - Model to use ProductVariantIdentifier instead of SKU - AKJ
+- [X] Price - Add Usage/Pricelist modifier for Queries to allow for List/Offer price. - MR
+- [X] Commercetools - Guest sesion race condition - MR
+- [X] Commercetools - Seperate temporary admin client from `Me` based client. - MR
+- [X] Medusa - Identity capability - AKJ
+- [X] Medusa - Price capability - AKJ
+- [X] Medusa - Category capability - AKJ
+- [X] Medusa - Inventory capability - AKJ
+- [X] Medusa - Checkout capability - AKJ
+- [X] Search Index Model Add information about number of variants on the main model (or directly if it can be added to cart or not) - AKJ
+- [X] CLI for importing icecat to all vendors - AKJ
+- [X] Unified Data Set for Products - AKJ
+- [X] Unified Data Set for Inventory - AKJ
+- [X] Unified Data Set for Prices - AKJ
+- [X] Unified test set for all vendors - AKJ
+- [X] Reactionary Decorator on all public Query and Mutation methods - MR
+- [X] Input validation via Zod.parse for all public Query and Mutation methods - MR
+- [X] Output validation via Zod.parse for all public Query and Mutation methods - MR
+- [X] Change Zod schema from looseObjects to .passthrough - MR
+- [X] Minor fixes from Angular Frontend - MR
 
-### Core
-- [ ] Figure a way to get a correlation id from the caller
-- [ ] Maybe rework session so its not languageContext but requestContext, and this could have the correlation id in it?
 
 
-### Search
-- [ ] Add support for filters, not just facets
+### Roadmap to V0.2
+Usecase: as a shopper i use the site navigation to find products, add to cart and checkout
+Vendors: Commercetools, Algolia, Medusa
 
-### Marketing
-- [ ] Add marketing provider (input: (name, url, user, segments, productid, categoryid) => output { Array<Product | Category | Image | Text>}
+- Menu navigation
+- CLP - Category Navigation  
+- Revise and review Schema usage patterns to reduce number of irrelevant default values.
+- Move to Errors as Values on base api, no null, no undefineds, no exceptions out of Reactionary
 
+### Roadmap to V0.3
+Usecase: As a registered user, i access my-account
+Vendors: Commercetools, Algolia, Medusa
 
-### Inventory
-- [ ] Invent and document some notational standard for cannel-key to purpose.
-- [ ] Be traced and cached
+- Profile - Address book
+- Orderhistory - List and Details
+- Consents - marketing, newsletters etc
+- Store location vs pickup points
 
-### Profile
-- [ ] Be able to register new account
-- [ ] Create profile provider
+### Roadmap to V0.4
+Usecase: As a seller i want to seed my recommendation and analytics with customer actions  (Analytics)
+Vendors:  Algolia, Google Analytics
 
+- PLP
+  - Attribution Tracking
+  - Facet Tracking
+- PDP
+  - Attribution Tracking
+- Checkout
+  - Conversion Tracking
 
-### Organization
-- [ ] Create organization provider
-- [ ] Create business user provider
-- [ ] Create role provider
 
-### Cart
-- [ ] Add B2B/organization identifier
+### Roadmap to V0.5
+Usecase: As a merchandiser i want to upsell
+Vendors: Algolia,  Commercetools
 
-### Price
-- [ ] Add list price
+- PDP
+  - Recommendations (Products, Categories)
+  - Associations (Spareparts, Accessories)
+  - Ratings and Reviews
+- Checkout
+  - Recommendations (Products)
 
-### Order
-- [ ] Add Order
+
+### Roadmap to V0.6
+Usecase: As a shopper i want to create shoppinglist/wishlist
+Vendors:  Commercetools, Medusa
+
+- Account - Shopping List, Listing and Details
+- PDP
+  - Add to Shopping List
+- PLP
+  - Add to Shopping List
+
+
+### Roadmap to V0.7
+Usecase: As a B2B user i want to shop using my own prices
+Vendors:  Commercetools
+
+- PDP / PLP
+  - External Pricing
+  - Organizational/Entitlement Context
+  - Multi currency/Multi lingual
+
+
+### Roadmap to V0.8
+Usecase: As a B2B user i want to see my organization data
+Vendors:  Commercetools
+
+- Account - My Organization(s) 
+- Account - Self management of users and roles
+
+
+### Roadmap to V0.9
+Usecase: As a B2B user i want have multiple carts and requisition lists
+Vendors:  Commercetools
+
+- Account - My Open Carts
+
+### Roadmap to V1.0
+Usecase: As a B2B user i want to see other peoples carts and orders
+Vendors:  Commercetools
+
+- Account - Organizational Order History
+
+
+
+
+
+
+
+
+
+### Roadmap V0.x
+- Additional vendors
+  - AthosCommerce (Klevu)
+  - ShopifyPlus
+  - HCL Commerce
+  - Adobe Commerce
+  - Lipscore
+- PDP
+  - Price display (tiered pricing, variant differential pricing)
+
+
+
+
+
+
+## Adding a new provider
+So, you want to add to the fun, and add a new provider.
+A new provider can be as partial or as complete as you need it to be, but each capability it undertakes, must be fully supported.
+
+## Step 0
+Make sure you have a clean test environment. Ie not some half-baked instance with broken test data. Ideally, you are able to spin up and preconfigure instances via scripts.
+
+## Step 1
+Populate your environment with the shared test-data set. Reactionarys providers all share a set of product information based on ICECAT. 
+
+If you are internal to Solteq, you can work off of https://github.com/Solteq/composable-commerce-base-workspace. If you are external, go to ICECAT.biz, and register an account.
+Then use their API to download the free dataset and all the various product-data files. Parse those, and import them in your system as appropriate.
+
+Consider, that you may not need to import all of it, if your capability doesn't need it. Ie if you are only implementing the CART capability, you don't really need the product images, or long descriptions.
+
+## Step 2
+Add your provider library here.
+
+```
+npx nx g lib providers/<vendor> --buildable --publishable TODO: Martin, fill in
+```
+
+Within each `src` folder, adhere to the naming convention of the existing providers:
+- `core` (capabilities and initalization)
+- `providers` (each capability in its own file, named for itself )
+- `schema` any vendor specific schema overrides
+- `test` any internal/specific test to that provider.
+
+## Step 3
+Create the initialization and capabilities schema, and start adding logic.
+
+## Step 4 
+As your new vendor lib contains the same test data that all other vendors do, you can run the `global-tests` suite. This will show if your capability implementation adheres to the expected behavior within reactionary.

package/core/package.json

@@ -6,8 +6,11 @@
   "dependencies": {
     "zod": "4.1.9",
     "@upstash/redis": "^1.34.9",
-    "node-object-hash": "^3.1.1",
-    "@opentelemetry/api": "^1.9.0"
+    "node-object-hash": "^3.1.1"
   },
-  "type": "module"
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.0.0"
+  },
+  "type": "module",
+  "sideEffects": false
 }

package/core/src/cache/cache.interface.ts

@@ -1,5 +1,6 @@
 import type { z } from 'zod';
 import type { BaseModel } from '../schemas/models/index.js';
+import type { NotFoundError, Result } from '../schemas/index.js';
 
 export interface CacheEntryOptions {
   ttlSeconds: number;

package/core/src/cache/index.ts

@@ -0,0 +1,4 @@
+export * from './cache.interface.js';
+export * from './memory-cache.js';
+export * from './noop-cache.js';
+export * from './redis-cache.js';

package/core/src/cache/memory-cache.ts

@@ -1,31 +1,43 @@
+import { getReactionaryCacheMeter } from '../metrics/metrics.js';
+import { error, NotFoundErrorSchema, success, type NotFoundError } from '../schemas/index.js';
 import type { BaseModel } from '../schemas/models/index.js';
+import type { Result } from '../schemas/result.js';
 import type { Cache, CacheEntryOptions } from './cache.interface.js';
 import type z from 'zod';
 
+
 /**
  * Memory version of the cache. Primarily useful for local development.
  * This is NOT suited for production use.
  */
 export class MemoryCache implements Cache {
   protected entries = new Array<{ key: string; value: unknown, options: CacheEntryOptions }>();
+  protected meter = getReactionaryCacheMeter();
+
 
   public async get<T extends BaseModel>(key: string, schema: z.ZodType<T>): Promise<T | null> {
     const c = this.entries.find((x) => x.key === key);
 
     if (!c) {
+      this.meter.misses.add(1, {
+        'labels.cache_type': 'memory',
+      });
+      
       return null;
     }
 
     const parsed = schema.parse(c.value);
 
-    parsed.meta.cache.hit = true;
+    this.meter.hits.add(1, {
+      'labels.cache_type': 'memory',
+    });
 
     return parsed;
   }
 
   public async put(
     key: string,
-    value: unknown,
+    value: Result<unknown>,
     options: CacheEntryOptions
   ): Promise<void> {
     this.entries.push({
@@ -34,6 +46,10 @@ export class MemoryCache implements Cache {
         options
     });
 
+    this.meter.items.record(this.entries.length, {
+      'labels.cache_type': 'memory',
+    });
+
     return;
   }
 
@@ -48,9 +64,21 @@ export class MemoryCache implements Cache {
 
       index++;
     }
+
+    this.meter.items.record(this.entries.length, {
+      'labels.cache_type': 'memory',
+    });
+
+
   }
 
   public async clear(): Promise<void> {
     this.entries = [];
+
+    this.meter.items.record(this.entries.length, {
+      'labels.cache_type': 'memory',
+    });
+
+
   }
 }

package/core/src/cache/noop-cache.ts

@@ -1,3 +1,4 @@
+import { getReactionaryCacheMeter } from '../metrics/metrics.js';
 import type { Cache, CacheEntryOptions } from './cache.interface.js';
 import type z from 'zod';
 
@@ -6,19 +7,32 @@ import type z from 'zod';
  * Useful for testing or when caching should be disabled.
  */
 export class NoOpCache implements Cache {
+  protected meter = getReactionaryCacheMeter();
   public async get<T>(_key: string, _schema: z.ZodType<T>): Promise<T | null> {
+    this.meter.misses.add(1, {
+      'labels.cache_type': 'noop',
+    });
     return null;
   }
 
   public async put(_key: string, _value: unknown, options: CacheEntryOptions): Promise<void> {
+    this.meter.items.record(0, {
+      'labels.cache_type': 'noop',
+    });
     return;
   }
 
   public async invalidate(dependencyIds: Array<string>): Promise<void> {
+    this.meter.items.record(0, {
+      'labels.cache_type': 'noop',
+    });
     return;
   }
 
   public async clear(): Promise<void> {
+    this.meter.items.record(0, {
+      'labels.cache_type': 'noop',
+    });
     return;
   }
-}
+}

package/core/src/cache/redis-cache.ts

@@ -1,9 +1,12 @@
 import { Redis } from '@upstash/redis';
 import type { Cache, CacheEntryOptions } from './cache.interface.js';
 import type z from 'zod';
+import { getReactionaryCacheMeter } from '../metrics/metrics.js';
 
 export class RedisCache implements Cache {
   protected redis: Redis;
+  protected meter = getReactionaryCacheMeter();
+
 
   constructor() {
     this.redis = Redis.fromEnv();
@@ -18,6 +21,11 @@ export class RedisCache implements Cache {
     const parsed = schema.safeParse(unvalidated);
 
     if (parsed.success) {
+      this.meter.hits.add(1, {
+        'labels.cache_type': 'redis',
+      });
+
+
       return parsed.data;
     }
 
@@ -42,6 +50,10 @@ export class RedisCache implements Cache {
       multi.sadd(`dep:${depId}`, key);
     }
 
+    this.meter.items.record(await this.redis.dbsize(), {
+      'labels.cache_type': 'redis',
+    });
+
     await multi.exec();
   }
 
@@ -56,9 +68,17 @@ export class RedisCache implements Cache {
 
       await this.redis.del(depKey);
     }
+
+    this.meter.items.record(await this.redis.dbsize(), {
+      'labels.cache_type': 'redis',
+    });
+
   }
 
   public async clear(): Promise<void> {
+    this.meter.items.record(await this.redis.dbsize(), {
+      'labels.cache_type': 'redis',
+    });
     // Not sure about supporting this on Redis.
   }
 }

package/core/src/client/client-builder.ts

@@ -1,63 +1,80 @@
-import type { Cache } from "../cache/cache.interface.js";
-import { NoOpCache } from "../cache/noop-cache.js";
-import type { Client } from "./client.js";
-import type { AnalyticsProvider } from "../providers/analytics.provider.js";
+import type { Cache } from '../cache/cache.interface.js';
+import { NoOpCache } from '../cache/noop-cache.js';
+import type { Client } from './client.js';
+import type { AnalyticsProvider } from '../providers/analytics.provider.js';
+import {
+  RequestContextSchema,
+  type RequestContext,
+} from '../schemas/session.schema.js';
 
-type CapabilityFactory<T> = (cache: Cache) => T;
+type CapabilityFactory<T> = (cache: Cache, context: RequestContext) => T;
 
 type MergeCapabilities<Acc, New> = Omit<Acc, keyof New> & New;
 
-export class ClientBuilder<TClient = object> {
-    private factories: Array<CapabilityFactory<Partial<Client>>> = [];
-    private cache: Cache | undefined;
-
-    withCapability<TNew extends Partial<Client>>(
-        factory: CapabilityFactory<TNew>
-    ): ClientBuilder<MergeCapabilities<TClient, TNew>> {
-        const newBuilder = new ClientBuilder<MergeCapabilities<TClient, TNew>>();
-        newBuilder.factories = [...this.factories, factory];
-        newBuilder.cache = this.cache;
-        return newBuilder;
+export class ClientBuilder<TClient = Client> {
+  private factories: Array<CapabilityFactory<Partial<Client>>> = [];
+  private cache: Cache | undefined;
+  private context: RequestContext;
+
+  constructor(context: RequestContext) {
+    this.context = context;
+  }
+
+  withCapability<TNew extends Partial<Client>>(
+    factory: CapabilityFactory<TNew>
+  ): ClientBuilder<MergeCapabilities<TClient, TNew>> {
+    const newBuilder = new ClientBuilder<MergeCapabilities<TClient, TNew>>(this.context);
+    newBuilder.factories = [...this.factories, factory];
+    newBuilder.cache = this.cache;
+    newBuilder.context = this.context;
+    return newBuilder;
+  }
+
+  withCache(cache: Cache): ClientBuilder<TClient> {
+    const newBuilder = new ClientBuilder<TClient>(this.context);
+    newBuilder.factories = [...this.factories];
+    newBuilder.cache = cache;
+    newBuilder.context = this.context;
+    return newBuilder;
+  }
+
+  build(): TClient & { cache: Cache } {
+    let client = {} as TClient;
+
+    // Default to no-op cache if none is provided
+    const sharedCache = this.cache || new NoOpCache();
+    const validatedContext = RequestContextSchema.safeParse(this.context);
+
+    // Avoid returning the parsed result for context, to preserve object equality at the top level
+    if (!validatedContext.success) {
+      throw new Error('Invalid context: ' + validatedContext.error);
     }
 
-    withCache(cache: Cache): ClientBuilder<TClient> {
-        const newBuilder = new ClientBuilder<TClient>();
-        newBuilder.factories = [...this.factories];
-        newBuilder.cache = cache;
-        return newBuilder;
+    const mergedAnalytics: AnalyticsProvider[] = [];
+
+    for (const factory of this.factories) {
+      const provider = factory(sharedCache, this.context);
+      client = {
+        ...client,
+        ...provider,
+      };
+
+      if (provider.analytics) {
+        mergedAnalytics.push(...provider.analytics);
+      }
     }
 
-    build(): TClient & { cache: Cache } {
-        let client = {} as TClient;
-        
-        // Use provided cache or default to NoOpCache
-        const sharedCache = this.cache || new NoOpCache();
-        
-        const mergedAnalytics: AnalyticsProvider[] = [];
-        
-        for (const factory of this.factories) {
-            const provider = factory(sharedCache);
-            client = {
-                ...client,
-                ...provider
-            };
-            
-            if (provider.analytics) {
-                mergedAnalytics.push(...provider.analytics);
-            }
-        }
-        
-        // Add merged analytics if any were collected
-        if (mergedAnalytics.length > 0) {
-            (client as Record<string, unknown>)['analytics'] = mergedAnalytics;
-        }
-        
-        // Add cache to complete the client
-        const completeClient = {
-            ...client,
-            cache: sharedCache
-        } as TClient & { cache: Cache };
-        
-        return completeClient;
+    // Add merged analytics if any were collected
+    if (mergedAnalytics.length > 0) {
+      (client as Record<string, unknown>)['analytics'] = mergedAnalytics;
     }
-}
+
+    // Add cache to complete the client
+    const completeClient = {
+      ...client,
+      cache: sharedCache,
+    } as TClient & { cache: Cache };
+
+    return completeClient;
+  }
+}