@reactionary/source 0.0.52 → 0.2.16

package/documentation/1-purpose.md

@@ -0,0 +1,114 @@
+# Reactionary
+
+Reactionary is an oppinionated abstraction layer between UX developer and Backend developer in a Composable Commerce environment.
+
+In a composable commerce project, you will have a bag of services that together provide all the functionality you need on the site.
+And over time, you will probably decide to move from one such service, to another, if you want to, say, have better search, or better recommendations.
+
+Reactionary creates a vendor agnostic domain model, and set of providers towards those vendors, that will allow UX developers to focus on their own craft, rather than both having to learn NextJS/Nuxt/Svelte/Htmx, in addition to the 4-6 vendor apis that go into the site.
+
+To coin a term, we talk about a UX developer needing access to certain capabiltiies.
+
+These can be things like
+1. Cart
+1. Proile
+1. Product Data
+1. Product Search
+1. Order History
+
+Reactionary is intended to live on the server side of your frontend. It uses the publically available clients for known and services, and is not trying to optimize for backend bundle size. Instead, we try to optimize for developer speed.
+
+It is the intention, that Reactionary will serve as the lowest layer of communication between the UX developer and the associated vendors.
+This means, you are not really expected to use reactionary directly from your components or widgets or pages. 
+
+*Rather, Reactionary belongs behind your state-management system of choice.*
+
+For Angular, this might be a dependency injected service, that uses reactionary instead of HttpClient, or take place in a `resource`. For React, you might have a set of lib-functions to manage site state, and from there call Reactionary when needed. That lib would also host your site business logic. And for NextJS, it might be something triggered by React Query, or a Context.
+
+For this reason, we say that Reactionary is oppinionated on what your  domain model will look like, and how it should interact, but it is unopinionated as to how to you manage your state and business logic.
+
+In this document, we show various examples, using a mix of UI frameworks, or pseudo-ui frameworks, so here we might show Reactionary a bit closer to the widgets and components that it really belongs. This is only for brewity.
+
+
+## Audience
+This document is for UX developers who need to know abit about how reactionary works, and how the expected usage pattern should be. 
+It is also for Backend developers, who need to customize the providers and domain models, to match the specific domain of your site.
+
+## Goal
+
+The goal is 
+- To support any Node based frontend framework (NextJS, Rapi, Angular Universal, etc)
+- To provide the capabilities needed to build both B2C and B2B sites
+- To make it easy and natural to specialize/customize both the domain model, and provider
+- To provide cross transactional caching and cache management
+- To provide open telemetry data for proper monitoring and fault detection
+
+## Design criteria
+Reactionary will be a stateless framework. It will not keep or maintain any state between calls.
+The UX framework used for the presentation layer is responsible for storing and retrieving any session data that reactionary needs to operate. 
+
+This also means, reactionary does not do any client-state or UI-state management at all. In the Service => Provider => Factory setting, reactionary is the Provider and Factory layer.
+
+Each capability will have certain behavioral criteria that the UX designer can rely on. This means, occasioanlly there will be mandatory backend customizations required if a vendors product does not fully fit.
+
+Where this is noted, a reference implementation will be made available.
+
+Runtime is targeting modern ESM/ES6 systems.
+
+We strive to avoid unbounded requests. This means, we don't generally allow for nested lists of things of indeterminate size. Instead a paged getter will be available to fetch a page of sub-items.
+
+
+## FAQ
+
+### What do you mean by capability?
+Consider the product search of a regular/standard ecommerce site. It has a text field. When you type in it, it fetches a list of products, and a list of facets, each with a count. User can page the result list (directly, or virtually through endless scroll) , and maybe choose to sort. 
+
+This basic capabilitys UX journey can be tweaked and designed for mobile, and foldable, and ipads, and desktop, and once visually there, this is not likely to change.
+However, there is significant difference in how this would be done using Commercetools' product search, Algolias search, Klevu (now Athos Commerce), Constructor.io or Doofinder.
+
+By creating a unifying domain model you can have your UX work for any of the mentioned vendors without changing anything, aside from the configuration of which vendor to use.
+
+### But couldn't i just to that myself? In react i could just have a useHook and hide all the things in there?
+Sure, and on your next project you could do it again.... and on the next one, again, only here you had a different team, so its slightly different.. and so on. And the 4th project uses Svelte, so the hooks from earlier need to be rewritten. 
+
+Reactionary is targeting being that abstraction, so you can have consistent behavior between projects and between teams.
+
+### Why would you use this, over, say, just using the graphql endpoint of your ecommerce 
+In a composable commerce project, the ecommerce system is no longer automatically the master system. You might have a DXE strategy, or you might have any number of other systems involved. By using a bridge framework like reactionary, you break the vendor lock, and can later pick a new ecommerce platform, where the performance is better, and the promotions more closely match your requirements, without having to redo the entire frontend project.
+
+### Why dont i just create my own graphql server then, and aggregate all the vendors i use?
+GraphQL servers are hard to get right, when you consider security, performance, caching et al. 
+GraphQL is great, if your site is a client-side rendered application, that needs to run on the smallest of bandwidth, and you have the time to artisinally craft the perfect payload for each call. But as SSR and Partial SSR is becoming the new norm, and the precense of a BFF is now part of the equation in most commercial projects, you do not gain anything significant from having your backend save 40 bytes from fetching product data on your own graphql server right next to it.
+The BFF->Client protocol is typically page related, or feature related. Not a straight API forwarding.
+
+### My DXE/CMS allows merging/exposing other endpoints via their GraphQL, isnt that the same then?
+Even if you disregard that the DXE still has to fetch the data from your vendor, and this means somehow propagating some authentication information to the CMS, the exposed API is still the original API, meaning your frontend developers still need to learn Algolia vs Klevu vs Doofinder.
+
+### What do you mean about specializing the domain model?
+Consider a product with a descriptive set of attributes for "StorageRequirementCode" .
+It is used visually on the PDP to show the value of that attribute, but there is a special requirement that if a product iand requires cooling, it cannot be added to the cart, unless you have a special permit, or maybe it means you can't choose pickup-in-store,  and also it must be flagged on every page the product is shown, to alert the end customer that he needs to be aware of this.
+
+As attributes are optional, and multivalued, this means you end up with something like this:
+```
+  public requireRefrigeration = computed(() => {
+    const code = this.product()?.descriptiveAttributes?.find(
+      (attr) => attr.identifier === 'StorageRequirementCode'
+    );
+    return !!(
+      code &&
+      code.values &&
+      code.values.length > 0 &&
+      code.values[0].value === 'KØL'
+    );
+  });
+``` 
+if you are  lucky, or inlined directly in the `tsx` or `.html` of the component in every place this is used.
+
+This gets even worse, if you consider you might also have commandline utilities that pull out products for sitemap generation, or other things.
+
+Instead of doing this distributed all over the place, where things will break down once it turns out that they need to add an additional StorageRequirementCode to the check, these kinds of manifestations of the products domain should be moved onto the product itself.
+
+Ie, extend the schema with `requireRefrigeration` as a field on the product, with the logic applied centrally where the data is loaded, rather than where it is used. That way, all instances where this is accessed, looks like `product.requireRefrigiration` instead of the other thing, which makes the code infinetly more readable and maintainable, since your reactionary customizations are reused and shared between applications.
+
+
+

package/documentation/2-getting-started.md

@@ -0,0 +1,229 @@
+# Getting started
+
+You can use Reactionary on any node-based project. It can be a NextJS BFF, or a commandline utility meant to create product-feeds for Google or OpenAI, or technically, in a ReactNative, or NativeScript application on your iPhone/Android app.
+
+In these examples i use `pnpm`, but you can use `yarn` or `npm` as you see fit.
+
+We assume you have a project ready, already...
+
+## Vendors
+For this example we assume you are using Commercetools as the ecom capability, and Algolia as the search provider. Both have free trial options, that can get you started.
+So, go ahead and set up new free trials for both of those, and generate API Clients and tokens for both. For Commercetools, you can use the "Storefront" preset.
+
+
+
+## Installing packages
+
+For our example we need to install providers for Commercetools and Algolia both.
+
+`pnpm install @reactionary/core @reactionary/provider-algolia @reactionary/provider-commercetools`
+
+We will also prepare for open telemetry reporting to NewRelic (also offers free trial, so go ahead and set that up)
+
+`pnpm install @reactionary/otel`
+
+
+
+## Errors as values
+We have decided to adopt the Errors-as-values paradigm seen in other server-side APIs, to encourage that all state returned, is inspected for error state, rather than simply allowing an unexpected thrown exception to alter the flow of things.
+
+This means generally, that calls follow this structure:
+
+```
+const cartResponse = await this.client.cart.getById({...});
+if (cartResponse.success) {
+  console.log('my cart is', cartResponse.value)
+}
+
+if (!cartResponse.success) {
+  console.log('Cart was not loadable due to ', cartResponse.error);
+}
+```
+
+This might seem verbose, over simply assuming the value is set when it gets back, but it encourages handling minor problems immediately, rather than starting out developing only the happy-path, and then promising yourself to circle back and deal with errors later.
+
+
+## Bootstrapping the client
+
+You use the `ClientBuilder` from `@reactionary/core` to create a new client, and then specify which capabilties you need. Only the capabilties you mention will be prepared for you.
+
+```ts
+  const client = new ClientBuilder()
+    .withCapability(
+      withCommercetoolsCapabilities(getCommercetoolsConfig(), 
+      {
+        product: true,
+        cart: true,
+        order: true
+      }
+    )
+    .withCapability(
+      withAlgoliaCapabilities(getAlgoliaConfig(), {
+        productSearch: true
+      })
+    )
+    .withCache(new NoOpCache())
+    .build();
+
+  ```
+
+
+
+  with `getCommercetoolsConfig` being a function like
+
+  ```ts
+  export function getCommercetoolsTestConfiguration() {
+  return CommercetoolsConfigurationSchema.parse({
+        apiUrl: process.env['CTP_API_URL'] || '',
+        authUrl: process.env['CTP_AUTH_URL'] || '',
+        clientId: process.env['CTP_CLIENT_ID'] || '',
+        clientSecret: process.env['CTP_CLIENT_SECRET'] || '',
+        projectKey: process.env['CTP_PROJECT_KEY'] || '',
+        scopes: (process.env['CTP_SCOPES'] || '').split(',').map(x => x.trim()).filter(x => x && x.length > 0),
+
+        paymentMethods: [
+          PaymentMethodSchema.parse({
+            identifier: PaymentMethodIdentifierSchema.parse({
+              paymentProvider: 'stripe',
+              method: 'stripe',
+              name: 'Stripe',
+            }),
+            description: 'Stripe payment gateway'
+          })
+        ]
+    })
+}
+
+```
+
+and `getAlgoliaConfig` being something like
+
+```ts
+ export function getCommercetoolsTestConfiguration() {
+  return AlgoliaConfigurationSchema.parse({
+      apiKey: process.env['ALGOLIA_API_KEY'] || '',
+      appId: process.env['ALGOLIA_APP_ID'] || '',
+      indexName: process.env['ALGOLIA_INDEX'] || '',
+    })
+}
+```
+
+and, then ofc, you need to provide all those values, in, say, a `.env` file (that you will not be adding to git)
+
+
+### Establishing state
+Before we can start calling vendors, we need to set up the context in which the requests will take place. This is information that is describing who the customer is,  what session data he has, some information about the current request, and so forth. All calls processed during the processing of one request from the frontend, share the same request data, so usually this can be established in some middleware function of your api-server.
+
+The expected lifecycle of a client created here, is for the duration of this single request. 
+
+```ts
+// we have to create a request context with all the information the underlying layer might need. 
+// We are responsible for the session object, and persisting it between requests.
+// This would normally be in a middleware
+
+// getSession here is a utility function from the frontend framework (nextjs,react-router,whatever) that stores your
+// users session data between calls. 
+  const session = await getSession(
+    request.headers.get("Cookie")
+  );
+
+  // from this we create a requestContext
+  
+  const reqCtx = createInitialRequestContext();
+
+  // optionally, set any locale settings from route or browser (or set it fixed,if there is only one language). 
+  reqCtx.languageContext = LanguageContextSchema.parse({
+    locale: 'en-US',
+    currency: 'USD'
+  });
+
+  reqCtx.session = JSON.parse(session.get('reactionarySession') || '{}');
+
+  // the reactionarySession object contains all the session data that reactionary controls.
+  // if it isn't there (new session? ) we create it
+  if (!session.has('reactionarySession')) {
+    session.set('reactionarySession', JSON.stringify({}));
+  }
+  
+  // we capture some information from the request, like some interesting headers and optional correlation ids sent from the frontend for
+  // traceability
+  reqCtx.clientIp = request.headers.get('X-Forwarded-For') || request.headers.get('Remote-Addr') || '';
+  reqCtx.userAgent = request.headers.get('User-Agent') || '';
+  reqCtx.isBot = /bot|crawler|spider|crawling/i.test(reqCtx.userAgent || '');
+  reqCtx.referrer = request.headers.get('Referer') || '';
+  reqCtx.correlationId = request.headers.get('X-Correlation-ID') || 'remix-' + Math.random().toString(36).substring(2, 15);
+
+  // we now have all we need to set up a client, so we pass the request context to the client builder.
+  // inlined here for clarity. Usually you would put this in a utility function called something like createClient
+  const client = new ClientBuilder(reqCtx)
+    .withCapability(
+      withCommercetoolsCapabilities(getCommercetoolsConfig(), 
+      {
+        product: true,
+        cart: true,
+        order: true
+      }
+    )
+    .withCapability(
+      withAlgoliaCapabilities(getAlgoliaConfig(), {
+        productSearch: true
+      })
+    )
+    .withCache(new NoOpCache())
+    .build();
+```
+
+Then in your page/component/context 
+
+```ts
+const meResponse = await client.identity.getSelf({});
+if (meResponse.success) {
+  if (meResponse.value.type === 'Registered') {
+    // do something only for registered customers...
+  }
+}
+```
+
+### Making calls to get data
+Let us assume the page we are rendering wants to include some minicart information. Given the client we created above, you can now call
+
+```ts
+// first, check if we have a cart id registered on the session
+let cartId = mySession.activeCartId;
+
+// if not, lets see if the system might have it for us
+if (!cartId) {
+  cartIdResponse = await client.cart.getActiveCartId();
+  if (cartIdResponse.success) {
+    cartId = cartIdResponse.value;
+  } else {
+    // we dont really care why it couldn't load.  We just reset to a safe value
+    cartId = '';
+  }
+  
+}
+
+// no? then lets just zero it out, and start over.
+if (!cartId) {
+  cartId = '';
+}
+const cartResponse = await client.cart.getById(cartId);
+
+let totalSum = 0;
+if (cartResponse.success) {
+  // store it for future reference
+  mySession.activeCartId = cartResponse.value.identifier.key;
+  totalSum = cartResponse.value.price.grandTotal.value;
+} 
+
+```
+
+
+
+
+## Design decisions
+We want Reactionary to be as unintrusive to the frontend frameworks best practice for state management. So we do not try to offer too many convenience methods that might slow down the site unnecessarily.
+
+This is why we don't offer a `cart.getActiveCart()`, because in some situations identifying the active cart id, might require an extra call for each operation.
+
+

package/documentation/3-querying-and-changing-data.md

@@ -0,0 +1,74 @@
+# Querying and Changing data
+
+All reactionary calls take an object-based parameter set, and can access the  `RequestContext` from the client in which the call is made.
+
+For getters, this parameter object is called a Query, and for functions that change state, they are called Mutations. This is the chosen termnology.
+
+The naming convention states, that your query must be called
+`<Noun>Query<NameOfQuery>Schema`
+
+We strive to have all queries be named for what they constrain the dataset by, making the most frequent pattern `<Noun>QueryBy<Fields>Schema`
+
+Examples of this are (Query)
+```ts
+export const CategoryQueryBySlugSchema = BaseQuerySchema.extend({
+    slug: z.string().default(''),
+});
+```
+
+
+Other variations exist where the Query has mulitple parameters
+```ts
+export const CategoryQueryForChildCategoriesSchema = BaseQuerySchema.extend({
+    parentId: CategoryIdentifierSchema.default(() => CategoryIdentifierSchema.parse({})),
+    paginationOptions: PaginationOptionsSchema.default(() => PaginationOptionsSchema.parse({})),
+});
+```
+
+Likewise for changing data, you will see that the mutator object has a naming convention of `<Noun>Mutation<Operation>Schema`, example
+
+```ts
+export const CartMutationItemAddSchema = BaseMutationSchema.extend({
+    cart: CartIdentifierSchema.nonoptional(),
+    variant: ProductVariantIdentifierSchema.nonoptional(),
+    quantity: z.number()
+});
+```
+
+
+
+## Paging
+All getters that return lists, are by design paginated, with a maximum of 50 items returned pr page.
+
+All pages are indexed with 1 being the first page. This makes it easier to render, and since Reactionary provides all the relevant numbers, you are not really expected to do math on the data yourself.
+
+Pagination options are always set as a nested object on the Query, called `paginationOptions`, and the result object, always reflects both `pageNumber`, `pageSize`, `totalCount` and `totalPages` back out.
+
+
+
+
+## Design Decisions
+We want all aspects of Reactionary to be custommizable and extendable. It is for this reason, we are using the object-payloads for parameters, as this allows you to specialize and extend the query for your own purpose, without violating any of the underlying mechanisms.
+
+Ie, if your site operated on mulitple catalogs, and you needed to load some catalog specific information in the `getBySlug` call, you can add the extra query parameters by extending the `CategoryQueryBySlugSchema`, and likewise for mutations, if you need to send more data to `add-to-cart`, you can extend the `CartMutationItemAddSchema`.
+
+
+All data and parameters is validated by `Zod` on the recieving end. This means, we adhere to the schema definitions very strictly, and you will get runtime errors if you provide bad or faulty data. This is intentional, as it requires you to fix the data, or fix your logic when certain invariants are not met. While this might seem annoying at first, it helps make things alot more maintainable over time, and has the added benefit of incentivising data-integrity checks at more levels.
+
+
+To ensure you also get compile time errors you can use the `satisfies` construct.
+
+ie
+```ts
+const clickedCategory = <the id of the category the user just clicked>
+const childCategoriesResponse = await client.category.findChildCategories({
+  parId: clickedCategory,
+  paginationOptions: {
+    pageNumber: 1,
+    pageSize: 40
+  }
+} satisfies CategoryQueryForChildCategories)
+```
+
+this will give a compile time error that the `parentId` is missing.
+

package/documentation/4-product-data.md

@@ -0,0 +1,107 @@
+# Product data
+
+Reactionary uses a Product/Variant model for product data.
+
+The product is the carrier of organizational data (`seoslug`, `parentCategory`, etc), and shared marketing data `description`, `sharedAttributes`, etc.
+
+All products will have at least one variant.  Variants represent the buyable version of the product, or more commonly called the `SKU`.
+
+It is mainly when navigating to the PDP you will need to load the product directly.
+
+
+
+## Navigating to the PDP
+The PDP will be accessible by seo slug. From talking to our internal PIM people, it is apparent that virtually noone expects to be able to have a product-description seperate from all its variants, so for that reason, the assumption is that when you look at a PDP, you are looking at the Product + one of its variants.
+
+The `Product` model has a `.mainVariant` sub-field that contains the variant specific information (`sku`, `ean`, `name`, `images` etc)
+
+There is no guarantees which variant (if you have multiple) that will be returned in the call to `ProductProvider#getBySlug`.
+
+If you want to allow navigating to a specific variant, you have to add your own url-scheme that includes the `sku`. This would typically be, if you want to persist your attribute selection to the url, so customer can copy/paste url and send to someone.
+
+```ts
+// assume route contains the current url..
+const productResponse = await client.product.getBySlug({ slug: route.url }, reqCtx);
+
+if (productResponse.success) {
+   const product = productResponse.value;
+   const desc = product.description
+   const mainImage = product.mainVariant.images[0].sourceUrl
+}
+
+```
+
+## Get SKU
+If you need to show some data for your cart items, or checkout items, you can use the `ProductProvider#getBySKU` call. It will return a `Product`, but with the `mainVariant` set to the variant with the `sku` you passed as argument.
+
+```ts
+for(const item of cart.items) {
+  const productResponse = await client.product.getBySKU({ variant: item.variant });
+  if (productResponse.success) {
+    const cartVariant = productResponse.value.mainVariant;
+    const cartVariantImage = productResponse.value.mainVariant.images[0].sourceUrl;
+  }
+}
+```
+
+## Getting category information for breadcrumbs or megamenus
+You use the `CategoryProvider#getBreadcrumbPathToCategory` to get the full navigational path from a products parent category to the root of the site.
+
+```ts
+const breadcrumbResponse = await client.category.getBreadcrumbPathToCategory({ id: product.parentCategories[0] });
+if (breadcrumbResponse.success) {
+  const breadcrumb = breadcrumbResponse.value;
+}
+```
+
+To render site menus, you can use this call
+```ts
+const topCategoriesResponse = await client.category.findTopCategories({ paginationOptions: { pageNumber: 1, pageSize: 15 }});
+if (topCategoriesResponse.success) {
+  const topCategories = topCategoriesResponse.value;
+}
+```
+
+Note, both for topCategories and childCategories you have to use pagination options. By design, we do not allow for unbounded calls. The maximum pageSize is 50, but the recommended pageSize is 20. 
+On some sites you might WANT to load everything in one go, but it should be considered a code-smell. Why would the customer want to wait to load 1000 categories. He can't reasonably do anything with it anyway.
+
+
+
+
+## Specializing the product
+When you get to know your project and customers domain, you will want to add logic to make the domain model more specialized to your field.
+This helps make the code easier to read later on.
+
+See `basic-node-provider-model-extension.spec.ts` for an example of how to do this.
+
+It is *highly* recommended that you take the time to do this. 
+
+```ts
+  const PharmacyProductSchema = ProductSchema.extend({
+    // if true, the product is an RX product, and cant be buyable unless you have a prescription
+    isPrescriptionProduct: z.boolean().default(false)
+  });
+  type PharmacyProduct = z.infer<typeof PharmacyProductSchema>;
+
+  class PharmacyProductProvider extends MedusaProductProvider<PharmacyProduct> {
+
+    protected override parseSingle(_body: StoreProduct, reqCtx: RequestContext): T {
+      const model = super.parseSingle(body);
+
+      if (_body.metaData['rx-product'] === 'true') {
+        model.isPrescriptionProduct = true;
+      }
+    }
+  }
+```
+
+
+## Design decisions
+Since , in some frameworks, the entirety of the object can be serialized between BFF and Client, we have decided not to include a list of all variants directly on the `Product` model. 
+
+The products identifier is meaningless, and no semantic meaning is assigned to it, except it should be something that is very unlikely to change in the upstream PIM
+
+## FAQ about products
+
+### What should I do, if i dont want to load all variants at once
+Consider adding a specialized `getSKUList` function, that returns a paged result set of variants. This can be helpful if the number of skus are unbounded.