@reactionary/source 0.0.41 → 0.0.48

package/.claude/settings.local.json

@@ -0,0 +1,28 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx nx build:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npx nx lint:*)",
+      "Bash(npx nx test:*)",
+      "Bash(npx nx run:*)",
+      "Bash(npx ts-node:*)",
+      "Bash(npx tsx:*)",
+      "Bash(grep:*)",
+      "Bash(pnpm list:*)",
+      "Bash(npx nx affected:build:*)",
+      "Bash(npx nx affected:lint:*)",
+      "Bash(cat:*)",
+      "Bash(npx nx show projects:*)",
+      "Bash(npx nx g:*)",
+      "Bash(pnpm add:*)",
+      "Bash(npx nx show project:*)",
+      "Bash(npx nx reset:*)",
+      "WebSearch",
+      "Bash(node:*)",
+      "Bash(npm view:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/.env-template

@@ -1,8 +1,11 @@
-COMMERCETOOLS_API_URL=https://api.europe-west1.gcp.commercetools.com
-COMMERCETOOLS_AUTH_URL=https://auth.europe-west1.gcp.commercetools.com
-COMMERCETOOLS_CLIENT_ID=
-COMMERCETOOLS_CLIENT_SECRET=
-COMMERCETOOLS_PROJECT_KEY=
+CTP_PROJECT_KEY=
+CTP_CLIENT_SECRET=
+CTP_CLIENT_ID=
+CTP_AUTH_URL=https://auth.europe-west1.gcp.commercetools.com
+CTP_API_URL=https://api.europe-west1.gcp.commercetools.com
+CTP_SCOPES=
+
+
 
 OTEL_SERVICE_NAME=reactionary
 OTEL_LOG_LEVEL=info

package/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "typescript.preferences.importModuleSpecifierEnding": "auto",
+  "typescript.preferences.importModuleSpecifier": "relative",
+  "typescript.preferences.preferTypeOnlyAutoImports": true
+}

package/README.md

@@ -37,3 +37,44 @@ The following is a short list of commonly used terms and phrases, to keep guessi
 - *Fake:* an implementation that provides a functional response, but with in a limited capacity. A fake provider may, for example, provide *Cart* functionality, but only store it in-memory and throw it away on a whim. As such it can be used for prototyping, but never for a production scenario.
 - *Product Analytics:* structured analytics that relate to how the the product is being used.
 - *Microsite:* an application of a limited scope. It may focus solely on this limited functionality, making it ideal for demonstration purposes.
+
+
+
+## TODO:
+
+
+
+### 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
+
+### Marketing
+- [ ] Add marketing provider (input: (name, url, user, segments, productid, categoryid) => output { Array<Product | Category | Image | Text>}
+
+
+### Inventory
+- [ ] Invent and document some notational standard for cannel-key to purpose.
+- [ ] Be traced and cached
+
+### Profile
+- [ ] Be able to register new account
+- [ ] Create profile provider
+
+
+### Organization
+- [ ] Create organization provider
+- [ ] Create business user provider
+- [ ] Create role provider
+
+### Cart
+- [ ] Add B2B/organization identifier
+
+### Price
+- [ ] Add list price
+
+### Order
+- [ ] Add Order

package/core/package.json

@@ -5,6 +5,8 @@
   "types": "src/index.d.ts",
   "dependencies": {
     "zod": "4.1.9",
-    "@upstash/redis": "^1.34.9"
+    "@upstash/redis": "^1.34.9",
+    "@reactionary/otel": "0.0.1",
+    "node-object-hash": "^3.1.1"
   }
 }

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

@@ -1,4 +1,10 @@
-import { z } from 'zod';
+import type { z } from 'zod';
+import type { BaseModel } from '../schemas/models';
+
+export interface CacheEntryOptions {
+  ttlSeconds: number;
+  dependencyIds: Array<string>;
+}
 
 /**
  * Generic cache interface that can be implemented by different cache backends
@@ -8,31 +14,21 @@ export interface Cache {
   /**
    * Retrieves a value from cache and validates it against the provided schema
    */
-  get<T>(key: string, schema: z.ZodType<T>): Promise<T | null>;
+  get<T extends BaseModel>(key: string, schema: z.ZodType<T>): Promise<T | null>;
 
   /**
    * Stores a value in cache with optional expiration time
    */
-  put(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
-
-  /**
-   * Removes one or more keys from cache
-   * Supports wildcard patterns (implementation dependent)
-   */
-  del(keys: string | string[]): Promise<void>;
-
-  /**
-   * Finds all keys matching a pattern (implementation dependent)
-   */
-  keys(pattern: string): Promise<string[]>;
+  put(key: string, value: unknown, options: CacheEntryOptions): Promise<void>;
 
   /**
-   * Clears all cache entries or entries matching a pattern
+   * Removes entries from the cache based on a set of dependency
+   * ids
    */
-  clear(pattern?: string): Promise<void>;
+  invalidate(dependencyIds: Array<string>): Promise<void>;
 
   /**
-   * Gets basic cache statistics (implementation dependent)
+   * Removes all entries from cache, wiping it completely
    */
-  getStats(): Promise<{ hits: number; misses: number; size: number }>;
+  clear(): Promise<void>;
 }

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

@@ -0,0 +1,56 @@
+import type { BaseModel } from '../schemas/models';
+import type { Cache, CacheEntryOptions } from './cache.interface';
+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 }>();
+
+  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) {
+      return null;
+    }
+
+    const parsed = schema.parse(c.value);
+
+    parsed.meta.cache.hit = true;
+
+    return parsed;
+  }
+
+  public async put(
+    key: string,
+    value: unknown,
+    options: CacheEntryOptions
+  ): Promise<void> {
+    this.entries.push({
+        key,
+        value,
+        options
+    });
+
+    return;
+  }
+
+  public async invalidate(dependencyIds: Array<string>): Promise<void> {
+    let index = 0;
+    for (const entry of this.entries) {
+      for (const entryDependency of entry.options.dependencyIds) {
+        if (dependencyIds.indexOf(entryDependency) > -1) {
+          this.entries.splice(index, 1);
+        }
+      }
+
+      index++;
+    }
+  }
+
+  public async clear(): Promise<void> {
+    this.entries = [];
+  }
+}

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

@@ -1,5 +1,5 @@
-import { Cache } from './cache.interface';
-import z from 'zod';
+import type { Cache, CacheEntryOptions } from './cache.interface';
+import type z from 'zod';
 
 /**
  * No-op cache implementation that never stores or returns data.
@@ -7,36 +7,18 @@ import z from 'zod';
  */
 export class NoOpCache implements Cache {
   public async get<T>(_key: string, _schema: z.ZodType<T>): Promise<T | null> {
-    // Always return null - never a cache hit
     return null;
   }
 
-  public async put(_key: string, _value: unknown, _ttlSeconds?: number): Promise<void> {
-    // No-op - silently ignore cache write requests
+  public async put(_key: string, _value: unknown, options: CacheEntryOptions): Promise<void> {
     return;
   }
 
-  public async del(_keys: string | string[]): Promise<void> {
-    // No-op - silently ignore delete requests
+  public async invalidate(dependencyIds: Array<string>): Promise<void> {
     return;
   }
 
-  public async keys(_pattern: string): Promise<string[]> {
-    // Always return empty array
-    return [];
-  }
-
-  public async clear(_pattern?: string): Promise<void> {
-    // No-op - silently ignore clear requests
+  public async clear(): Promise<void> {
     return;
   }
-
-  public async getStats(): Promise<{ hits: number; misses: number; size: number }> {
-    // Always return zeros
-    return {
-      hits: 0,
-      misses: 0,
-      size: 0
-    };
-  }
 }

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

@@ -1,6 +1,6 @@
 import { Redis } from '@upstash/redis';
-import { Cache } from './cache.interface';
-import z from 'zod';
+import type { Cache, CacheEntryOptions } from './cache.interface';
+import type z from 'zod';
 
 export class RedisCache implements Cache {
   protected redis: Redis;
@@ -13,62 +13,52 @@ export class RedisCache implements Cache {
     if (!key) {
       return null;
     }
-    
+
     const unvalidated = await this.redis.get(key);
     const parsed = schema.safeParse(unvalidated);
 
     if (parsed.success) {
       return parsed.data;
     }
-    
+
     return null;
   }
 
-  public async put(key: string, value: unknown, ttlSeconds?: number): Promise<void> {
+  public async put(
+    key: string,
+    value: unknown,
+    options: CacheEntryOptions
+  ): Promise<void> {
     if (!key) {
       return;
     }
 
-    const options = ttlSeconds ? { ex: ttlSeconds } : undefined;
-    await this.redis.set(key, value, options);
-  }
+    const serialized = JSON.stringify(value);
+    const multi = this.redis.multi();
 
-  public async del(keys: string | string[]): Promise<void> {
-    const keyArray = Array.isArray(keys) ? keys : [keys];
-    
-    for (const key of keyArray) {
-      if (key.includes('*')) {
-        // Handle wildcard patterns
-        const matchingKeys = await this.redis.keys(key);
-        if (matchingKeys.length > 0) {
-          await this.redis.del(...matchingKeys);
-        }
-      } else {
-        // Delete specific key
-        await this.redis.del(key);
-      }
+    multi.set(key, serialized, { ex: options.ttlSeconds });
+
+    for (const depId of options.dependencyIds) {
+      multi.sadd(`dep:${depId}`, key);
     }
-  }
 
-  public async keys(pattern: string): Promise<string[]> {
-    return await this.redis.keys(pattern);
+    await multi.exec();
   }
 
-  public async clear(pattern?: string): Promise<void> {
-    const searchPattern = pattern || '*';
-    const keys = await this.redis.keys(searchPattern);
-    if (keys.length > 0) {
-      await this.redis.del(...keys);
+  public async invalidate(dependencyIds: Array<string>): Promise<void> {
+    for (const id of dependencyIds) {
+      const depKey = `dep:${id}`;
+      const keys = await this.redis.smembers(depKey);
+
+      if (keys.length > 0) {
+        await this.redis.del(...keys);
+      }
+
+      await this.redis.del(depKey);
     }
   }
 
-  public async getStats(): Promise<{ hits: number; misses: number; size: number }> {
-    // Basic cache statistics (could be enhanced with actual Redis metrics)
-    const keys = await this.redis.keys('*');
-    return {
-      hits: 0, // Would need to track this separately
-      misses: 0, // Would need to track this separately  
-      size: keys.length
-    };
+  public async clear(): Promise<void> {
+    // Not sure about supporting this on Redis.
   }
 }

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

@@ -1,7 +1,7 @@
-import { Cache } from "../cache/cache.interface";
+import type { Cache } from "../cache/cache.interface";
 import { NoOpCache } from "../cache/noop-cache";
-import { Client } from "./client";
-import { AnalyticsProvider } from "../providers/analytics.provider";
+import type { Client } from "./client";
+import type { AnalyticsProvider } from "../providers/analytics.provider";
 
 type CapabilityFactory<T> = (cache: Cache) => T;
 

package/core/src/client/client.ts

@@ -1,13 +1,14 @@
-import { AnalyticsProvider } from "../providers/analytics.provider";
-import { ProductProvider } from "../providers/product.provider";
-import { SearchProvider } from "../providers/search.provider";
-import { IdentityProvider } from '../providers/identity.provider';
-import { CartProvider } from "../providers/cart.provider";
-import { PriceProvider } from "../providers/price.provider";
-import { InventoryProvider } from "../providers/inventory.provider";
-import { Cache } from "../cache/cache.interface";
+import type { AnalyticsProvider } from "../providers/analytics.provider";
+import type { ProductProvider } from "../providers/product.provider";
+import type { SearchProvider } from "../providers/search.provider";
+import type { IdentityProvider } from '../providers/identity.provider';
+import type { CartProvider } from "../providers/cart.provider";
+import type { PriceProvider } from "../providers/price.provider";
+import type { InventoryProvider } from "../providers/inventory.provider";
+import type { Cache } from "../cache/cache.interface";
 import { RedisCache } from "../cache/redis-cache";
-import { CategoryProvider } from "../providers/category.provider";
+import type { CategoryProvider } from "../providers/category.provider";
+import type { CartPaymentProvider } from "../providers";
 
 export interface Client {
     product: ProductProvider,
@@ -15,6 +16,7 @@ export interface Client {
     identity: IdentityProvider,
     cache: Cache,
     cart: CartProvider,
+    cartPayment: CartPaymentProvider,
     analytics: Array<AnalyticsProvider>,
     price: PriceProvider,
     inventory: InventoryProvider,

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

@@ -1,16 +1,88 @@
-export function Reactionary(options: unknown): MethodDecorator {
+import type { BaseProvider } from '../providers';
+import { getTracer, SpanKind } from '@reactionary/otel';
+
+/**
+ * The options associated with annotating a provider function and marking
+ * it as a reactionary entrypoint to be called
+ */
+export class ReactionaryDecoratorOptions {
+  /**
+   * Whether or not the query is eligible for caching. Queries that depend
+   * heavily on personalization, for example, are likely to be a poor fit
+   * for caching.
+   */
+  public cache = false;
+
+  /**
+   * Whether or not the cache entry should be variable based on the locale
+   * of the context in which it is querried.
+   */
+  public localeDependentCaching = false;
+
+  /**
+   * Whether or not the cache entry should be variable based on the currency
+   * of the context in which it is querried.
+   */
+  public currencyDependentCaching = false;
+
+  /**
+   * The number of seconds which a cache entry should be considered valid for the
+   * given query.
+   */
+  public cacheTimeToLiveInSeconds = 60;
+
+};
+
+/**
+ * Decorator for provider functions to provide functionality such as caching, tracing and type-checked
+ * assertion through Zod. It should only be used with publically accessible queries or mutations on
+ * providers.
+ */
+export function Reactionary(options: Partial<ReactionaryDecoratorOptions>) {
   return function (
-    target: any,
+    target: BaseProvider,
     propertyKey: string | symbol,
     descriptor: PropertyDescriptor
   ): PropertyDescriptor {
     const original = descriptor.value;
-    
-    descriptor.value = function (...args: any[]) {
-      console.log('calling through reactionary decoration!');
-      return original.apply(this, args);
+    const scope = `${target.constructor.name}.${propertyKey.toString()}`;
+    const configuration = { ...new ReactionaryDecoratorOptions(), ...options };
+
+    if (!original) {
+      throw new Error(
+        '@Reactionary decorator may only be applied to methods on classes extending BaseProvider.'
+      );
+    }
+
+    descriptor.value = async function (this: BaseProvider, ...args: any[]) {
+      const tracer = getTracer();
+
+      return tracer.startActiveSpan(
+        propertyKey.toString(),
+        { kind: SpanKind.SERVER },
+        async (span) => {
+          const cacheKey = this.generateCacheKeyForQuery(scope, args[0]);
+
+          const fromCache = await this.cache.get(cacheKey, this.schema);
+          let result = fromCache;
+
+          if (!result) {
+            result = await original.apply(this, args);
+
+            const dependencyIds = this.generateDependencyIdsForModel(result);
+
+            this.cache.put(cacheKey, result, {
+              ttlSeconds: configuration.cacheTimeToLiveInSeconds,
+              dependencyIds: dependencyIds
+            });
+          }
+
+          span.end();
+          return this.assert(result as any);
+        }
+      );
     };
-    
+
     return descriptor;
   };
-}
+}

package/core/src/index.ts

@@ -1,6 +1,6 @@
 export * from './cache/cache.interface';
-export * from './cache/cache-evaluation.interface';
 export * from './cache/redis-cache';
+export * from './cache/memory-cache';
 export * from './cache/noop-cache';
 
 export * from './client/client';
@@ -8,36 +8,12 @@ export * from './client/client-builder';
 
 export * from './decorators/reactionary.decorator';
 
-export * from './providers/analytics.provider';
-export * from './providers/base.provider';
-export * from './providers/cart.provider';
-export * from './providers/identity.provider';
-export * from './providers/inventory.provider';
-export * from './providers/price.provider';
-export * from './providers/product.provider';
-export * from './providers/search.provider';
-export * from './providers/category.provider';
+export * from './providers/'
 
 export * from './schemas/capabilities.schema';
 export * from './schemas/session.schema';
 
-export * from './schemas/models/base.model';
-export * from './schemas/models/cart.model';
-export * from './schemas/models/currency.model';
-export * from './schemas/models/identifiers.model';
-export * from './schemas/models/identity.model';
-export * from './schemas/models/inventory.model';
-export * from './schemas/models/price.model';
-export * from './schemas/models/product.model';
-export * from './schemas/models/search.model';
-export * from './schemas/models/category.model';
-
-export * from './schemas/mutations/base.mutation';
-export * from './schemas/mutations/cart.mutation';
-export * from './schemas/mutations/identity.mutation';
-export * from './schemas/mutations/inventory.mutation';
-export * from './schemas/mutations/price.mutation';
-export * from './schemas/mutations/product.mutation';
-export * from './schemas/mutations/search.mutation';
-
+export * from './schemas/models/';
+export * from './schemas/mutations/';
 export * from './schemas/queries';
+export * from './initialization';

package/core/src/initialization.ts

@@ -0,0 +1,43 @@
+import type { RequestContext } from "./schemas/session.schema";
+
+export function createInitialRequestContext(): RequestContext {
+  return {
+    id: '',
+    identity: {
+      type: 'Anonymous',
+      meta: {
+        cache: { hit: false, key: '' },
+        placeholder: false,
+      },
+      id: { userId: 'anonymous' },
+      token: undefined,
+      issued: new Date(),
+      expiry: new Date(new Date().getTime() + 3600 * 1000),
+      logonId: '',
+      createdAt: '',
+      updatedAt: '',
+      keyring: [],
+      currentService: undefined,
+    },
+    languageContext: {
+      locale: 'en-US',
+      currencyCode: 'USD',
+    },
+    storeIdentifier: {
+      key: 'the-good-store',
+    },
+    taxJurisdiction: {
+      countryCode: 'US',
+      stateCode: '',
+      countyCode: '',
+      cityCode: '',
+    },
+    session: {},
+
+    correlationId: '',
+    isBot: false,
+    clientIp: '',
+    userAgent: '',
+    referrer: '',
+  };
+}

package/core/src/providers/analytics.provider.ts

@@ -1,4 +1,4 @@
-import { AnalyticsEvent } from '../schemas/models/analytics.model';
+import type { AnalyticsEvent } from '../schemas/models/analytics.model';
 import { BaseProvider } from './base.provider';
 
 export abstract class AnalyticsProvider<