@reactionary/source 0.0.51 → 0.2.15

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.

package/documentation/5-cart-and-checkout.md

@@ -0,0 +1,211 @@
+# Dealing with carts and checkouts
+
+
+# Design decision
+It was decided to adopt a pattern where the cart is not the thing that you check out. Rather the cart is the data entity responsible for recording your product selections, and calculating your price.
+
+When you want to start the checkout process, you create a new checkout session, based on your cart, at which point the cart is considered read-only.
+
+While we have seen examples of cart pages where you can change quantity, remove items, or add upsells up until the second you press "pay", the new style of checkout focuses on getting you to pay, as fast as possible.
+
+This means, you can have all the upsell stuff on the "review cart page", but once you decide to "go to checkout", the focus is "Where, and how are you paying".
+
+
+# Initiating checkout
+The checkout takes as input a cart, any billing address you might have from being logged in, and returns a different object.
+
+```ts
+  const checkoutResponse = await client.checkout.initiateCheckoutForCart({
+    cart: cart.value,
+    billingAddress: address,
+    notificationEmail: email,
+    notificationPhone: phone,
+  });
+  if (!checkoutResponse.success) {
+      throw new Response("Error initiating checkout " + checkout.error, { status: 500 });
+  }
+
+  const routeId = checkoutResponse.value.identifier.key;
+
+```
+UI wise you can consider these values tied to this checkout, so its perfectly fine to have a flow where the address is edited later on. This is just the seed address/the billing address that allows us to make informed decisions about the kind of taxes and shipping you are going to be presented with.
+
+The checkout's id can then be used on your frontend url scheme to refer to this checkout session.
+
+
+## Setting a shipping address
+Depending on your flow, you might ask for a seperate shipping address (if not set, the billing address is assumed as the shipping address as well). 
+The shipping address might affect the ways in which you can get things shipped, so maybe set this before picking the shipping provider.
+
+```ts
+const shippingAddress = {...} satisifes Address;
+const updatedCheckoutResponse = await client.checkout.setShippingAddress({ checkout: { key: routeParams.checkoutId }, shippingAddress: shippingAddress });
+
+if (!updatedCheckoutResponse.success) {
+    throw new Response("Error setting shipping address on checkout " + checkout.error, { status: 500 });
+}
+```
+
+
+## Setting a shipping instruction
+A shipping instruction is to shipping like a payment instruction is to payment. It is the combined set of choices that define how this order is requested delivered. Ie, the method, the pickup point, and any instructions you might have for the carrier.
+
+To get the list of available shipping methods use
+
+```ts
+// lets double check that the checkout still exists...
+const checkout = await client.checkout.getById({ identifier: { key: checkoutId || "" } });
+if (!checkout.success) {
+    throw new Response("Checkout Not Found", { status: 404 });
+}
+
+const availableShippingMethodsResponse = await client.checkout.getAvailableShippingMethods({ checkout: checkout.value.identifier})
+if (availableShippingMethodsResponse.success) {
+  const availableShippingMethods = availableShippingMethodsResponse.value;
+  console.log(availableShippingMethods[0])
+}
+
+```
+Once picked, you can then set the full shipping instruction
+
+```ts
+  const formData = await request.formData();
+
+  const selectedMethod = formData.get("shippingMethod") as string;
+  const shippingInstructions = formData.get("shippingInstructions") as string;
+  const allowUnattendedDelivery = formData.get("allowUnattendedDelivery") === "on";
+
+
+// verify the checkout wasn't deleted in the mean time and that you can access it
+  const checkout = await client.checkout.getById({ identifier: { key: checkoutId || "" } });
+  if (!checkout.success) {
+      throw new Response("Checkout Not Found", { status: 404 });
+  }
+
+  const shippingInstruction: ShippingInstruction = {
+      shippingMethod: { key: selectedMethod },
+      instructions: shippingInstructions,
+      pickupPoint: "",
+      consentForUnattendedDelivery: allowUnattendedDelivery,
+  }
+  console.log('Selected shipping method in action:', shippingInstruction);
+  const updatedCheckout = await client.checkout.setShippingInstruction({
+    checkout: checkout.value.identifier,
+    shippingInstruction: shippingInstruction,
+  });
+  if (!updatedCheckout.success) {
+    throw new Response("Error setting shipping instruction", { status: 500 });
+  }
+```
+
+## Setting payment instruction
+A payment instruction consist of a choice of payment provider, and the amount of money to ask to authorize.
+A checkout can have multiple payment instructions. Sometimes for complicated purchases (use multiple credit cards, or some from mobilepay and rest on creditcard), or for more mundane purposes, like applying store-credit, or using an electronic gift-card.
+
+To get a list of available payment methods do something like 
+```ts
+    const checkoutId = params.checkoutId;
+  // verify the checkout wasn't deleted in the mean time and that you can access it
+    const checkout = await client.checkout.getById({ identifier: { key: checkoutId || "" } });
+    if (!checkout.success) {
+        throw new Response("Checkout Not Found", { status: 404 });
+    }
+    const paymentMethodResponse = await client.checkout.getAvailablePaymentMethods({
+      checkout: { key: checkoutId || "" },
+    });
+    if (!paymentMethodResponse.success) {
+      throw new Response("Error fetching payment methods", { status: 500 });
+    }
+    const paymentMethods = paymentMethodsResponse.value;
+
+```
+Add UI to display, and once picked, apply to checkout.
+
+```ts
+ const checkoutId = params.checkoutId;
+  const formData = await request.formData();
+
+  const selectedMethod = formData.get("paymentMethod") as string;
+
+  const session = await getSession(request.headers.get("Cookie"));
+  const reqCtx = await createReqContext(request, session);
+  const client = await createClient(reqCtx);
+
+  const checkout = await client.checkout.getById({ identifier: { key: checkoutId || "" } });
+  if (!checkout.success) {
+      throw new Response("Checkout Not Found", { status: 404 });
+  }
+  const paymentMethods = await client.checkout.getAvailablePaymentMethods({
+    checkout: checkout.value.identifier,
+  });
+  if (!paymentMethods.success) {
+    throw new Response("Error fetching payment methods", { status: 500 });
+  }
+
+  const paymentMethod = paymentMethods.value.find(
+    (method) => String(method.identifier.method) === selectedMethod
+  );
+  if (!paymentMethod) {
+    throw new Response("Invalid Payment Method", { status: 400 });
+  }
+
+
+  const updatedCheckout = await client.checkout.addPaymentInstruction({
+    checkout: checkout.value.identifier,
+    paymentInstruction: {
+      paymentMethod: paymentMethod.identifier,
+      amount: checkout.value.price.grandTotal,
+      protocolData: [],
+    },  
+  });
+  if (!updatedCheckout.success) {
+    throw new Response("Error adding payment instruction", { status: 500 });
+  }
+```
+
+At this point, your backend will have set up a payment intent with the PSP, and you can read out the data needed to either load the providers UI library and bootstrap it (stripe), or you will get a redirect url you can use to send the customer to the payment processor directly.
+
+In this example, we detect that we 
+```ts
+  const pendingPayment = updatedCheckout.value.paymentInstructions.find(x => x.status === 'pending');
+  if (pendingPayment?.paymentMethod.paymentProcessor === 'stripe') {
+    return redirect(`/checkout/${checkoutId}/payment/stripe`);
+  }
+```
+
+And on that subpage specifc to stripe, you might extract hte client secret required to feed their component.
+
+```ts
+  const clientSecretData = pendingPayment.protocolData.find(
+    (data) =>
+      data.key === "stripe_clientSecret" || data.key === "client_secret",
+  );
+```
+
+
+Finally, when the payment provider either returns (because you punched out, and provided a return url with the `checkoutId` in it), OR the inline component tells you everything is fine, it is time to close the deal
+
+```ts
+    const checkoutId = params.checkoutId;
+    const checkout = await client.checkout.getById({
+      identifier: { key: checkoutId || "" },
+    });
+
+    if (!checkout.success) {
+        throw new Response("Checkout Not Found", { status: 404 });
+    }
+    const finalizedCheckoutResponse = await client.checkout.finalizeCheckout({ checkout: checkout.value.identifier })
+
+```
+The checkout returned, contains the state of things as they were at checkout. It also has a reference to the created order. Wheter you want your order confirmation to be based on either is project dependent. In some setups the order might come from a secondary OMS system, and it might take a while for the order to exist there. 
+
+## FAQ
+
+### When you say the cart is readonly, what does that mean for the UX flow?
+Whether or not the cart is ACTUALLY read only doesn't matter. The point is, that changes to cart during checkout session is not automatically reflected into the checkout. This ensures you don't need to deal with situations where customer has opened two browser windows and try to add more stuff to the cart during checkout.
+
+The Checkout session contains all you need to render the UX flow. It has a snapshot of the carts contents at the time you initiated the login.
+
+
+
+

package/documentation/6-product-search.md

@@ -0,0 +1,143 @@
+# Adding product search
+
+A common pattern on most ecommerce sites, is to allow the user to search / navigate your catalog. For this purpose Reactionary provides the `ProductSearchProvider`. 
+
+
+## Keyword search
+You can react to the user submitting a keyword search, or maybe routing to a special landing page where the page-part is a search term, by doing something like this
+
+```ts
+const searchresultResponse = await client.productSearch.queryByTerm(
+    {
+      search: {
+        facets: [],
+        paginationOptions: {
+          pageNumber: 1,
+          pageSize: 12,
+        },
+        term: 'glass',
+        filters: []
+      },
+    }
+  );
+
+if (!searchresultResponse.success) {
+    throw new Response("Error fetching products", { status: 500 });
+}
+```
+
+What you get back is a miniturazed/specialized product model, optimized for PLP purposes. 
+
+In the Product/Variant mindset, the search returns Products, with enough of each variant to make it identifiable. Ie Image and SKU.
+In addition, the variant part might also contain an indexed `Option`, which can be used to create swatches on the PLP if needed.
+
+The result of the search is a paged result set, but with some added fields for `facets`
+
+Since price and inventory are expected to be sourced from other areas, you have to look them up
+
+```ts
+{
+  const pricePromises = productPageResponse.value.items.map(async (product) => {
+    if (product.variants.length === 0) {
+      //skip
+      return null;
+    }
+    return client.price.getCustomerPrice({
+      variant: product.variants[0].variant,
+    }).then(priceResponse => {
+      if (priceResponse.success) {
+        return priceResponse.value;
+      }
+      return null;
+    }
+    );
+  });
+  const prices = (await Promise.all(pricePromises)).filter((price): price is Price => price !== null);
+
+```
+
+and then accessed further down like
+
+```ts
+  searchResult.items.map((product) => {
+        const imgUrl = product.variants[0].image[0].sourceUrl || 'assets/no-image.png'
+        const imgAlt = product.variants[0].iamge[0].altText || product.name;
+        const price = prices.find(x => x.variant.sku === product.variants[0].variant.sku )
+        return (
+          <div className={classnames("card")} key={product.identifier.key} sku={product.variants[0].variant.sku}>
+            <img
+              className={classnames("card__image")}
+              src={imgUrl}
+              alt="{imgAlt}"
+            />
+            <h5 className={classnames("card__title")}>{product.name}</h5>
+            <p>{price.value} {price.currency}</p>
+            <p className={classnames("card__desc")}>{product.description}</p>
+            if (product.directAddToCart) {
+              <button className={classnames("card__button")}>Add to Cart</button>
+            } else {
+              <button className={classnames("card__button")}>View variants</button>
+            }
+          </div>
+        );
+      })}
+}
+```
+
+
+Facets can be rendered in the same way. When a customer clicks a facet, you can redo the existing search, with that facet selected, because the original searchresult has the query information it was made for, as part of it.
+
+```ts
+// customer has clicked some facet-valie, and we are passed its identifier. The identifier should be considered opaque at this point...
+
+const existingSearchState = mySession.lastKeywordSearch;
+
+const updatedFacets = [...existingSearchState.facets, newlyClickedFacetValue];
+const paginationOptions = { ...existingPaginationOptions, pageNumber: 1 };
+
+// keep everything in our search the same, except add the new facet, and reset to page 1.
+const newSearchQuery = { search: { ...existingSearchState, facets: updatedFacets, paginationOptions };
+const newSearchState = client.productSearch.queryByTerm(newSearchQuery, requestContext);
+
+mySession.lastKeywordSearch = newSearchState.identifier;
+```
+
+The above example shows how the responsibility for state management is split between the UX framework and Reactionary. Reactionary has no insight into the routing patterns or page transitions that may have occured, and have no way of knowing if we are in a continuous interaction on the same search or not. 
+
+### Swatches / Variants on PLP
+
+Generally, for sites that are Mobile first, or where the vast majority of interaction is expected to come from mobile devices, anything that becomes fiddly, should be avoided. It is hard for users to click one of 12 color swathes on your 400x200 product tile, without accidentially clicking the product itself.
+
+But in some cases, where desktop is still the expected primary channel, you might want to add some indication that a product exists in various variations.
+
+To do this, the data model provides one `ProductVariantOption` pr variant from the search index.
+
+Note, that the search index Variants is expected to be a subset of the `Product` model variants. And only for the visually distinct variations.
+So, if your `Product` has 6 sizes (XXL through XS), and 5 colors (red, green, blue, yellow, black), your Product Model might have 30 variants. But your search index should only have 5, one for each color, as this is the visually distinctive set for this product.
+
+If your product has 20 variants, differing on some attribute `Length` or `Diameter`, those are not really good candidates for search index variations as they are not visually distinct. In this case the search index would contain only one variation, but, it would be marked as not directly addable to cart (`ProductSearchResultItemSchema#directAddToCart`).
+
+
+## Typeahead
+TBD
+
+
+
+## Design
+We consider category navigation just a special case of facetted filtering. Therefore, no dedicated function is available to do keyword search vs category search.
+
+We may later decide to add a category version, if only to make it easier to seperate the analytics of them both.
+
+The Variant of the SearchResultItem is set to only have one option, as that is what we see most frequently on sites. 
+These design patterns are well served under the current model:
+
+1. Products have 1 SKU, you can click Add to cart directly from PLP
+1. Products have multiple SKUs, you click tile, and get sent to PDP
+1. Products have multiple SKUs with one visually discerning attribute, you can click Add to cart directly from PLP
+1. Products have multiple SKUs,with one visually discerning attribute, and one or more non-visual. You click tile and gets sent to PDP with attribute selected
+1. Products have multiple SKUs, with no discerning attributes. You click tile and get sent to PDP
+
+The only pattern that isn't well supported is
+1. Products have multiple SKUs with multiple visually discerning attribute, you can click Add to cart directly from PLP
+
+It is felt that this is rare enough, that we can make that a specialization task if it comes up.

package/documentation/7-marketing.md

@@ -0,0 +1,3 @@
+# Adding the personal touch
+
+

package/eslint.config.mjs

@@ -9,6 +9,7 @@ export default [
       '**/dist',
       '**/vite.config.*.timestamp*',
       '**/vitest.config.*.timestamp*',
+      '**/vitest.config.ts'
     ],
   },
   {

package/examples/node/eslint.config.mjs

@@ -8,10 +8,7 @@ export default [
       '@nx/dependency-checks': [
         'error',
         {
-          ignoredFiles: [
-            '{projectRoot}/eslint.config.{js,cjs,mjs}',
-            '{projectRoot}/esbuild.config.{js,ts,mjs,mts}',
-          ],
+          ignoredFiles: ['{projectRoot}/eslint.config.{js,cjs,mjs}'],
         },
       ],
     },

package/examples/node/package.json

@@ -1,6 +1,14 @@
 {
   "name": "@reactionary/examples-node",
-  "version": "0.0.1",
-  "private": true,
-  "dependencies": {}
+  "version": "0.2.15",
+  "main": "index.js",
+  "types": "src/index.d.ts",
+  "dependencies": {
+    "@reactionary/core": "0.2.15",
+    "@reactionary/provider-commercetools": "0.2.15",
+    "@reactionary/provider-algolia": "0.2.15",
+    "@reactionary/provider-medusa": "0.2.15",
+    "@reactionary/provider-meilisearch": "0.2.15"
+  },
+  "type": "module"
 }

package/examples/node/project.json

@@ -5,6 +5,7 @@
   "projectType": "library",
   "tags": [],
   "targets": {
+
     "build": {
       "executor": "@nx/esbuild:esbuild",
       "outputs": ["{options.outputPath}"],
@@ -13,8 +14,10 @@
         "main": "examples/node/src/index.ts",
         "tsConfig": "examples/node/tsconfig.lib.json",
         "assets": ["examples/node/*.md"],
-        "format": ["esm"]
+        "format": ["esm"],
+        "bundle": false
       }
     }
+
   }
 }