Feat/conscia package (#35)

* feat: create conscia package

* Update index.ts

* docs: updated README for conscia package

* conscia.ai integration docs

* fixes

* fixed links

---------

composable-ui/src/components/cms/commerce-connector.tsx

@@ -1,34 +1,9 @@
 import { Button, Container, Flex, HStack, Text } from '@chakra-ui/react'
+import { CommerceConnectorProps, PriceProps } from '@composable/types'
 import { ProductCard } from '@composable/ui'
 import { useRouter } from 'next/router'
 
-export interface GenericConnectorProps {
- title?: string
- ctaLabel?: string
- ctaHref?: string
- ctaHeight?: string
- ctaMaxWidth?: string
- ctaMinWidth?: string
- products?: {
- name: string
- slug: string
- brand?: string
- img?: {
- url?: string
- alt?: string
- }
- price?: PriceProps
- }[]
-}
-
-export interface PriceProps {
- current: number
- currentFormatted: string
- regular?: number
- regularFormatted?: string
-}
-
-export const CommerceConnector = (props: GenericConnectorProps) => {
+export const CommerceConnector = (props: CommerceConnectorProps) => {
  const {
  title,
  ctaLabel,

composable-ui/src/server/api/routers/cms.ts

@@ -1,12 +1,18 @@
-import { createTRPCRouter, publicProcedure } from '../trpc'
 import { getPage } from '@composable/cms-generic'
-import { PageProps } from '@composable/types'
+import { PageSchema } from '@composable/types'
 import { z } from 'zod'
+import { createTRPCRouter, publicProcedure } from '../trpc'
 
 export const cmsRouter = createTRPCRouter({
  getPage: publicProcedure
  .input(z.object({ slug: z.string() }))
  .query(async ({ input }) => {
- return getPage({ pageSlug: input.slug }) as PageProps
+ try {
+ const page = await getPage({ pageSlug: input.slug })
+ return PageSchema.parse(page)
+ } catch (err) {
+ console.log(err)
+ return null
+ }
  }),
 })

docs/docs/integrations/orchestration/_category_.json

@@ -0,0 +1,8 @@
+{
+ "label": "Orchestration",
+ "position": 7,
+ "link": {
+ "type": "generated-index",
+ "description": "Orchestration"
+ }
+}

docs/docs/integrations/orchestration/conscia.md

@@ -0,0 +1,46 @@
+# Conscia.ai Integration
+
+Conscia’s zero-code Digital Experience Orchestration (DXO) platform enables brands and organizations to fast-track the adoption of MACH and composable architecture into their existing tech stacks. For marketing, it offers centralized omnichannel control over the composable experience, with Personalization and A/B testing built in. For engineering teams, it offers zero code API and data orchestration, offloading the point to point integrations to the orchestration layer, simplifying the frontend code, and eliminating the need to build custom BFFs (Backend for Frontends). Conscia’s revolutionary approach embraces both legacy and modern backends, allowing it to act as the bridge between any backend and any frontend, and for this reason, justifiably claims the role of the ‘Brain’ of the Composable stack.
+
+This integration demonstrates Conscia's ability to orchestrate multiple data sources, stitch together data, transform data models, and enable switching out data sources by the business user without the front end being concerned. Using Salesforce Commere Cloud, Contentstack and Contentful as data sources, we have a created a Home Page Model template that recreates the Composable UI's homepage. 
+
+## Integration architecture
+
+To extend the storefront to pull in content from Conscia's DXO, a package called `conscia` has been created. This package contains a `getPage` data fetching function that queries the Conscia API and then extracts the data required from the response to drive the content components on the Composable UI homepage.
+
+## Integrating Conscia.ai with Composable UI
+
+### Set Up
+
+1. Gain access to a Conscia sandbox. (These are currently only available to SIs. Please talk to your partner manager about getting access to a sandbox.)
+1. Refer to the Conscia package [README](https://github.com/composable-com/composable-ui/blob/main/packages/conscia/README.md) to complete set up. 
+
+### Exploring the Conscia Sandbox
+
+The sandbox is pre-populated with the set of orchestration Components required to reproduce the Composable UI homepage. These Components are connected to Contentstack, Contentful, and Salesforce Commerce Cloud sandboxes. 
+
+Each Composable UI component data source is modeled with the same pattern of selector, mapper, and model. 
+- Selector Components pull data directly from a data source. 
+- Mapper Components transform the data as required. This could include remapping fields, stripping out extraneous data, and stitching together multiple data sources. 
+- Model Components provide the final response to the consumer.
+
+For example: 
+- `selector-contentstack-banner` connects to Contentstack's Banner content model. It also defines a number of Design Attributes that the business user is expected to supply values for via Experience Rules.
+- `mapper-contentstack-banner` takes the selector Component's response and maps only the necessary fields to the schema expected by Composable UI. It combines these fields with the Design Attributes into a single schema response.
+- `model-banner` provides a clean, agnostic final response, and includes logic to select either the Contenstack or Contentful banner mapper Component response based on the selection made in the `banner-picker` Component. 
+
+![alt_text](conscia-visualizer.png "Conscia Home Page Model Template")
+
+### Try this
+
+1. Go into Experience Rules
+2. Under Composable UI Storefront -> Home Page find the Hero Banner Source component
+3. Click Edit on the `**Default**` rule
+4. Change tabs to the Experience page
+5. Under `Attributes` -> `CMS Banner Selection`, select Contentstack (or Contentful, depending on which is already selected, choose the other one)
+6. Click Submit
+7. Reload the homepage and see a different hero banner has loaded
+
+## Related Resources
+
+- [Conscia.ai DXO Documentation](https://docs.conscia.ai/platform-overview)

packages/conscia/.eslintrc.js

@@ -0,0 +1,4 @@
+module.exports = {
+ root: true,
+ extends: ['custom'],
+}

packages/conscia/README.md

@@ -0,0 +1,38 @@
+# Integrating Conscia Components into Composable-UI
+
+Read more about the Conscia.ai composable orchestration integration with Composable UI and what it accomplishes [here](https://docs.composable.com/docs/integrations/orchestration/conscia).
+
+# Installation and Setup
+
+1. **Navigating to the Project Directory:** Open your terminal and navigate to your local `composable-ui` project directory and then move to `composable-ui` subfolder.
+ ```bash
+ cd path/to/composable-ui/composable-ui
+ ```
+1. **Install the @composable/conscia package**:
+ ```bash
+ pnpm install @composable/conscia
+ ```
+1. **Set the required environment variables:** 
+
+ ```shell
+ NEXT_PUBLIC_CONSCIA_BASE_URL=https://...conscia.io/api
+ NEXT_PUBLIC_CONSCIA_TOKEN=
+ NEXT_PUBLIC_CONSCIA_CUSTOMER_CODE=
+ ```
+1. **Update your storefront to use the Conscia data fetching service:**
+
+The `cmsRouter`, defined in `composable-ui/src/server/api/routers/cms.ts`, provides your storefront with a data fetching function called `getPage`, which retrieves the data that is used to populate the content on your storefront. By default this function returns data retrieved from a local file. 
+
+In order to use data from Conscia, the `cmsRouter` needs to use the `getPage` data fetching service defined in `@composable/conscia`, instead of from `@composable/cms-generic`. Change the code as follows:
+
+
+ ```javascript
+ // cms.ts - before changes
+ import { getPage } from '@composable/cms-generic'
+
+...
+
+ // cms.ts - after changes
+ import { getPage } from '@composable/conscia'
+ ```
+

packages/conscia/index.ts

@@ -0,0 +1 @@
+export * from './src'

packages/conscia/package.json

@@ -0,0 +1,22 @@
+{
+ "name": "@composable/conscia",
+ "version": "0.0.0",
+ "main": "./index.ts",
+ "types": "./index.ts",
+ "sideEffects": "false",
+ "scripts": {
+ "build": "echo \"Build script for @composable/conscia ...\"",
+ "lint": "eslint \"**/*.{js,ts,tsx}\" --max-warnings 0",
+ "ts": "tsc --noEmit --incremental"
+ },
+ "dependencies": {
+ "@composable/types": "workspace:*",
+ "axios": "0.26.1"
+ },
+ "devDependencies": {
+ "@types/node": "^18.6.3",
+ "eslint-config-custom": "workspace:*",
+ "tsconfig": "workspace:*",
+ "typescript": "^4.5.5"
+ }
+}

packages/conscia/src/index.ts

@@ -0,0 +1,3 @@
+export * from './service'
+export * from './utils'
+export * from './types'

packages/conscia/src/service/client.ts

@@ -0,0 +1,9 @@
+import axios from 'axios'
+
+export const consciaClient = axios.create({
+ baseURL: process.env.NEXT_PUBLIC_CONSCIA_BASE_URL,
+ headers: {
+ Authorization: `Bearer ${process.env.NEXT_PUBLIC_CONSCIA_TOKEN}`,
+ 'X-Customer-Code': process.env.NEXT_PUBLIC_CONSCIA_CUSTOMER_CODE ?? '',
+ },
+})

packages/conscia/src/service/index.ts

@@ -0,0 +1,3 @@
+export * from './client'
+export * from './page'
+export * from './templates'

packages/conscia/src/service/page.ts

@@ -0,0 +1,18 @@
+import { PageProps } from '@composable/types'
+import { ConsciaPageTemplateComponents } from '../types'
+import { getTemplateData } from './templates'
+import { transformPage } from '../utils'
+
+export const getPage = async ({
+ pageSlug,
+}: {
+ pageSlug: string
+}): Promise<PageProps | null> => {
+ if (!pageSlug) {
+ return null
+ }
+ const consciaPage = await getTemplateData<ConsciaPageTemplateComponents>({
+ templateCode: pageSlug,
+ })
+ return consciaPage ? transformPage({ consciaPage, pageSlug }) : null
+}

packages/conscia/src/service/templates.ts

@@ -0,0 +1,18 @@
+import { ConsciaComponent, ConsciaTemplate } from '../types'
+import { consciaClient } from './client'
+
+export const getTemplateData = async <
+ Components extends ConsciaComponent<any>
+>({
+ templateCode,
+}: {
+ templateCode: string
+}) => {
+ const response = await consciaClient.post<ConsciaTemplate<Components>>(
+ '/experience/template/_query',
+ {
+ templateCode,
+ }
+ )
+ return response.data
+}

packages/conscia/src/types.ts

@@ -0,0 +1,126 @@
+import {
+ BannerFullProps,
+ BannerSplitProps,
+ BannerTextOnlyProps,
+ CommerceConnectorProps,
+ CommerceProduct,
+ GridProps,
+ TextCardProps,
+} from '@composable/types'
+
+export interface ConsciaTemplate<ComponentTypes extends ConsciaComponent<any>> {
+ duration: number
+ components: Record<string, ComponentTypes>
+ errors: any[]
+}
+
+export interface ConsciaComponent<ComponentData> {
+ '@extras': {
+ rule: {
+ metadata: any[]
+ attributes: Record<string, any>
+ }
+ }
+ status: 'VALID' | 'INVALID'
+ response: ComponentData
+}
+
+export type ConsciaHeroBanner = {
+ __typename: BannerSplitProps['__typename']
+ containerMarginBottom?: number
+ containerMarginTop?: number
+ containerSize: BannerSplitProps['containerSize']
+ textPosition: string
+ theme: string
+ id: BannerSplitProps['id']
+ content: BannerSplitProps['content']
+ title: BannerSplitProps['title']
+ ctaAlphaHref: BannerSplitProps['ctaAlphaHref']
+ ctaAlphaLabel: BannerSplitProps['ctaAlphaLabel']
+ image: {
+ title: string
+ description: string
+ url: string
+ }
+}
+
+export type ConsciaCTABanner = {
+ __typename: BannerFullProps['__typename']
+ containerMarginBottom?: number
+ containerMarginTop?: number
+ containerSize: BannerFullProps['containerSize']
+ overlayBackground: BannerFullProps['overlayBackground']
+ textPosition: BannerFullProps['textPosition']
+ theme: BannerFullProps['theme']
+ id: BannerFullProps['id']
+ content: BannerFullProps['content']
+ title: BannerFullProps['title']
+ ctaAlphaLabel: BannerFullProps['ctaAlphaLabel']
+ ctaAlphaHref: BannerFullProps['ctaAlphaHref']
+ image: {
+ url: string
+ title: string
+ }
+ linkHref1: BannerFullProps['linkHref1']
+ linkLabel1: BannerFullProps['linkLabel1']
+}
+
+export type ConsciaFeatureCardsHeader = {
+ __typename: BannerTextOnlyProps['__typename']
+ centered: BannerTextOnlyProps['centered']
+ id: BannerTextOnlyProps['id']
+ content: BannerTextOnlyProps['content']
+ title: BannerTextOnlyProps['title']
+ ctaAlphaLabel: BannerTextOnlyProps['ctaAlphaLabel']
+ ctaAlphaHref: BannerTextOnlyProps['ctaAlphaHref']
+}
+
+export interface ConsciaFeaturedProducts {
+ __typename: CommerceConnectorProps['__typename']
+ id: CommerceConnectorProps['id']
+ title: CommerceConnectorProps['title']
+ containerMarginBottom?: number
+ containerMarginTop?: number
+ containerSize: CommerceConnectorProps['containerSize']
+ ctaMaxWidth: string
+ ctaMinWidth: string
+ ctaLabel: CommerceConnectorProps['ctaLabel']
+ ctaHref: CommerceConnectorProps['ctaHref']
+ products: (Omit<CommerceProduct, 'img'> & { image: CommerceProduct['img'] })[]
+}
+
+export type ConsciaGrid = {
+ __typename: GridProps['__typename']
+ id: GridProps['id']
+ columns: GridProps['columns']
+ containerMarginBottom?: number
+ containerMarginTop?: number
+ gridGap: GridProps['gridGap']
+ containerSize: GridProps['containerSize']
+ items: ConsciaTextCard[]
+}
+
+export type ConsciaTextCard = {
+ __typename: TextCardProps['__typename']
+ id: TextCardProps['id']
+ title: TextCardProps['title']
+ image: {
+ url: string
+ title: string
+ }
+ content: TextCardProps['content']
+ ctaLabel: TextCardProps['ctaLabel']
+ ctaHref: TextCardProps['ctaHref']
+ theme: TextCardProps['theme']
+ textAlign: TextCardProps['textAlign']
+}
+
+export type ConsciaPageTemplateComponents = ConsciaComponent<
+ | ConsciaHeroBanner
+ | ConsciaCTABanner
+ | ConsciaFeatureCardsHeader
+ | ConsciaFeaturedProducts
+ | ConsciaGrid
+>
+export type ConsciaPageTemplateResponse =
+ ConsciaTemplate<ConsciaPageTemplateComponents>

packages/conscia/src/utils/images.ts

@@ -0,0 +1,3 @@
+export const parseImageUrl = (imageUrl: string) => {
+ return imageUrl.startsWith('//') ? `https:${imageUrl}` : imageUrl
+}

packages/conscia/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './images'
+export * from './page'