@zonos/elements 1.3.18-alpha.2 → 1.3.18-alpha.3

package/README.md

@@ -1,101 +1,346 @@
-# Zonos Component UI for Stripe elements
-
-## Project build architecture:
-  - `/src/components` (**Will be bundled with Stencil**): stencil web component, separate folder into 4 types:
-    - `main`: component that will receive custom configuration from users, do all of the script and css injection into consumer page and also control how other components will show/hide by using stencil `store`.
-    - `checkout`: main components that will handle zonos checkout
-    - `hello`: main components that will handle zonos hello (currently holding the component placeholder)
-    - `store`: this is state management amongs all of the components. 
-    - `stripe`: the folder that will hold all of the stripe wrapper web components
-    - `utils`: folders that will hold all of the necessary utilities for all of the components in stencil
-    - `components.d.ts`: generated typed component that will have global types for all web components
-  - `/src/scripts` (**Will be bundled with regular rollup**): scripts that will be bundled into cdn and init global utility function when consumer inject cdn into their page. Consumer then can use to init zonos elements.
-    - `/src/scripts/demo`: base scripts for the demo. `setup.ts` is for how to setup configuration and `customer-site-interaction.ts` is just base interaction for website (add to cart behavior).
-  - `/src/styled`: folder that will hold all of the styling related for all web components
-    - `variables`: scss variables that will be used throughout the web components application (better to just have scss variables and should not have css) 
-    - `css`: folder that will hold all of the global css (this will be generated and inject into `<head>` consumer site)
-- Have environment `t3` setup, but currently it's only being used in `rollup` and `stencil` config for build time checking. It may be will remove this in the future if we don't have any severless api or api using related (right now using just native `process.env`, and have the rollup env plugin to transfer that env into actual value when building.
-- separate tsconfig for each bundling:
-  - `tsconfig`: will include all folders to have all of the intellisense throughout the project.
-  - `tsconfig.build`: stencil building process
-  - `tsconfig.demo-script`: script for demo script
-  - `tsconfig.scripts`: rollup bundling for loading script.
-
-## Developing/Release process
-**IMPORTANT: Be careful when updating the API. Changes, such as modifications to the API path or parameter requirements (like field name changes or making parameters optional or mandatory), could disrupt older versions of zonos-elements. To prevent this, consider keeping the existing endpoint and introducing a new one with the updates. This approach applies to both endpoint path changes and parameter updates. Gradually phase out the old endpoint once all lower CDN versions have migrated.**
-
-### Deprecating APIs Guide
-In our `demo-app`, we treat the API as version-less because it relies on other components (like the customer-graph and front-end graph), and GraphQL does not offer a straightforward method to version queries and mutations. Given this, versioning our API currently seems unnecessary. However, we've devised a strategy for deprecating APIs, acknowledging that it might not be the optimal solution available:
-1. Changing Endpoint Paths:
-   - When an endpoint's path changes, we recommend a structured approach to mark the old endpoint as deprecated:
-     - Create a `(deprecated)` folder next to the updated endpoint's directory.
-     - Within `(deprecated)`, create a subfolder named after the current version on the main branch.
-     - Move the original endpoint's directory to this new version-named folder.
-   Ex: If we update the endpoint from `/api/zonos-elements/calculate-landed-cost` to `/api/zonos-elements/calculate-super-landed-cost`, the directory structure would look like this:
-    ```
-    └── zonos-elements
-        ├── (deprecated)
-        │   └── (v1.2.3)
-        │       └── calculate-landed-cost
-        │           ├── CalculateLandedCost.graphql.customer.ts
-        │           ├── FulfillmentCenters.graphql.customer.ts
-        │           └── route.ts
-        ├── calculate-super-landed-cost
-        │   ├── CalculateLandedCost.graphql.customer.ts
-        │   ├── FulfillmentCenters.graphql.customer.ts
-        │   └── route.ts
+# Zonos Component UI Introduction
+This project offers web components designed primarily for Zonos Checkout, Zonos Hello, and other Zonos products, with a focus on React and Next.js integration. Although not yet tested with other JavaScript libraries and frameworks, the implementation principles for React and Next.js can be adapted for use with other frameworks. For more information about Zonos products, please visit the official [Zonos website](https://zonos.com).
+
+# Table of content
+- [Zonos Component UI Introduction](#zonos-component-ui-introduction)
+- [Table of content](#table-of-content)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+  - [Brief `Zonos.init` base configuration explanation:](#brief-zonosinit-base-configuration-explanation)
+  - [CDN](#cdn)
+    - [CDN when to use:](#cdn-when-to-use)
+    - [CDN usage:](#cdn-usage)
+  - [Npm](#npm)
+    - [Npm when to use:](#npm-when-to-use)
+    - [Npm usage:](#npm-usage)
+- [API references](#api-references)
+    - [Zonos instance definition](#zonos-instance-definition)
+    - [Single file definition for Zonos instance](#single-file-definition-for-zonos-instance)
+    - [Zonos.init - checkoutSettings available configurations](#zonosinit---checkoutsettings-available-configurations)
+    - [Zonos.init - helloSettings available configurations](#zonosinit---hellosettings-available-configurations)
+
+
+# Prerequisites
+- Node.js (v18 or higher)
+- An API key for Zonos Checkout/Hello (please contact our [support team](https://zonos.com/contact-support) for more information)
+
+# Installation
+There are two ways to initialize Zonos: via custom integration using a CDN or through npm installation.
+
+**Note**: All methods below are only using the base configuration to have the Checkout and Hello up and running. For a more secure way to build your cart, please check out our [docs](https://zonos.com/docs/global-ecommerce/integration/integrating-new-checkout/custom-integration#set-up-zonos-checkout) for more information.
+
+## Brief `Zonos.init` base configuration explanation:
+- `checkoutSettings.buildCartDetail`: This callback function retrieves cart item information from your web platform. It should return an array of cart item objects. For the expected type definition, please refer to the [`buildCartDetail`](./dist/types/types/checkout/CheckoutConfig.d.ts) and the [cart item](./dist/types/components/store/checkout/cart.d.ts) files.
+- `checkoutSettings.placeOrderButtonSelector`: This is used to find all matching selectors and attach an event to trigger the Checkout process. While you can configure this in our Zonos dashboard, it's recommended to set it here so that Zonos can disable your Checkout place order button while loading.
+- `zonosApiKey`: An API key for Zonos Checkout/Hello (please contact our [support team](https://zonos.com/contact-support) for more information).
+- `storeId`: Store id that your checkout would associate with (please contact our [support team](https://zonos.com/contact-support) for more information).
+
+## CDN
+
+### CDN when to use:
+This is suitable for you if you:
+- Use any non-JavaScript frameworks (e.g., PHP, Java, C#).
+- Have a static site with pure HTML, CSS, and JavaScript.
+- Do not need type references in the project.
+- Prefer to use a CDN even if you are using a JavaScript framework (e.g., React, Vue, Next.js).
+- Want to quickly test how Zonos functions on your site (e.g., easily drop the script snippet into the Console tab in your browser's developer tools).
+
+### CDN usage:
+
+
+- For non-JavaScript frameworks:
+  <details>
+  <summary>Copy and paste the following into your HTML or the "Console" tab of your browser's developer tool</summary>
+
+    Put the `<script>` tag below into the `<head>` tag of your HTML:
+    ```html
+    <script>
+      (async function () {
+        const zonosElementsUrl = 'https://js.zonos.com';
+        const timestamp = new Date().getTime();
+        const zonosScript = document.querySelector(
+          `script[src*="${zonosElementsUrl}/dist/scripts/loadZonos.js"]`,
+        );
+
+        if (!zonosScript) {
+          const script = document.createElement('script');
+          script.src = `${zonosElementsUrl}/dist/scripts/loadZonos.js?timestamp=${timestamp}`;
+          script.addEventListener(
+            'load',
+            () => {
+              const getCartItems = async () => {
+                const yourServerUrl = "https://your-server.com/api/get-cart-items";
+                const response = await fetch(yourServerUrl);
+                const json = await response.json();
+                return json;
+              };
+
+              // Initialize Zonos with your store's settings.
+              // Replace '<%= placeOrderButtonSelector %>', '<%= storeId %>', and '<%= credentialToken %>'
+              // with your actual values.
+              void window.Zonos.init({
+                checkoutSettings: {
+                  buildCartDetail: async () => {
+                    const allItems = getCartItems();
+                    return allItems;
+                  },
+                  placeOrderButtonSelector: '<%= placeOrderButtonSelector %>',
+                },
+                storeId: Number('<%= storeId %>'), // Contact support for this information.
+                zonosApiKey: '<%= credentialToken %>', // Contact support for this information
+              });
+            },
+            false,
+          );
+          document.head.appendChild(script);
+        }
+      })();
+    </script>
     ```
-   - This folder can be removed once no stores are using a version at or below the deprecated version.
-1. Parameter requirement changes (optional, mandatory and removal) and API response structure changes
-   - For changes in parameter requirements (whether making them optional, mandatory, or removing them), follow these steps:  
-     - Create a new markdown file named after the `current version on the main branch` within the endpoint's directory.
-     - In this markdown file, detail the changes required, such as fields becoming optional, mandatory, or being removed.  
-     **Note: When updating endpoint responses, it is okay to add new return fields, but removing fields (update mutation/query returns) may cause issues if an old version is expecting and using that old field from the response**
-   Ex:
+  </details>
+  <br>
+
+- For React, Next.js:
+  - Create a typescript file and import `@zonos/elements` to define types definition for `window` interface
+    <details>
+    <summary>Code example</summary>
+
+      ```typescript
+      import "@zonos/elements";
+      ```
+    </details>
+    <br>
+  - Create a `ContextProvider`
+    <details>
+    <summary>Code example</summary>
+
+      ```typescript
+        'use client';
+        import { type ReactNode, createContext, useMemo, useState } from 'react';
+
+        import Script from 'next/script';
+
+        type ZonosScriptProps = {
+          scriptLoaded: boolean;
+        };
+
+        export const ZonosScriptContext = createContext<ZonosScriptProps>({
+          scriptLoaded: false,
+        });
+
+        export const ZonosScriptContextProvider = ({
+          children,
+        }: {
+          children: ReactNode;
+        }) => {
+          const [scriptLoaded, setScriptLoaded] = useState(false);
+
+          const context: ZonosScriptProps = {
+            scriptLoaded,
+          };
+          const timestamp = useMemo(() => Date.now(), []);
+          return (
+            <ZonosScriptContext.Provider value={context}>
+              <Script
+                onLoad={() => setScriptLoaded(true)}
+                src={`https://js.zonos.com/dist/scripts/loadZonos.js?timestamp=${timestamp}`}
+              />
+              {children}
+            </ZonosScriptContext.Provider>
+          );
+        };
+      ```
+    </details>
+    <br>
+
+  - Wrap `ZonosScriptContextProvider` into root of your `layout.tsx`
+    <details>
+    <summary>Code example</summary>
+    
+    ```typescript
+    export default function Layout({ children }:{ children: ReactNode}) {
+      return (
+        <ZonosScriptContextProvider>
+          <main>
+            {children}
+          </main>
+        </ZonosScriptContextProvider>
+      )
+    }
     ```
-    └── zonos-elements
-        ├── calculate-super-landed-cost
-        │   ├── CalculateLandedCost.graphql.customer.ts
-        │   ├── FulfillmentCenters.graphql.customer.ts
-        │   ├── v1.2.3.md
-        │   └── route.ts
+    </details>
+    <br>
+
+  - Create a hook named `useZonosScript.ts` to use the context easier
+    <details>
+    <summary>Code example</summary>
+
+    ```typescript
+    import { useContext } from 'react';
+
+    import { ZonosScriptContext } from 'src/components/ZonosScriptContext';
+
+    export const useZonosScript = () => useContext(ZonosScriptContext);
     ```
-    In `v1.2.3.md`, you might have:
+    </details>
+    <br>
+  - Create component called `ZonosLayoutSetup.tsx` to initialize `Zonos`.
+    <details>
+      <summary>Code example</summary>
+
+      ```typescript
+      'use client';
+      import { type ReactNode, useEffect } from 'react';
+
+      import { useZonosScript } from 'src/utils/hooks/useZonosScript';
+
+      export const ZonosLayoutSetup = ({ children }: { children: ReactNode }) => {
+        const { scriptLoaded } = useZonosScript();
+
+        useEffect(() => {
+          // Only initialize Zonos when zonos script is fully loaded.
+          if (!scriptLoaded) {
+            return;
+          }
+          const getCartItems = async () => {
+            const yourServerUrl = "https://your-server.com/api/get-cart-items";
+            const response = await fetch(yourServerUrl);
+            const json = await response.json();
+            return json;
+          };
+
+          // Initialize Zonos with your store's settings.
+          // Replace '<%= placeOrderButtonSelector %>', '<%= storeId %>', and '<%= credentialToken %>'
+          // with your actual values.
+          void window.Zonos.init({
+            checkoutSettings: {
+              buildCartDetail: async () => {
+                const allItems = getCartItems();
+                return allItems;
+              },
+              placeOrderButtonSelector: '<%= placeOrderButtonSelector %>',
+            },
+            storeId: Number('<%= storeId %>'), // Contact support for this information.
+            zonosApiKey: '<%= credentialToken %>', // Contact support for this information
+          });
+        }, [scriptLoaded]);
+
+        return children;
+      };
+      ```
+    </details> 
+    <br>
+    
+  - Put component `ZonosLayoutSetup.tsx` right under `ZonosScriptContextProvider`
+    <details>
+      <summary>Code example</summary>
+
+      ```typescript
+      export default function Layout({ children }:{ children: ReactNode}) {
+        return (
+          <ZonosScriptContextProvider>
+            <ZonosLayoutSetup>
+              <main>
+                {children}
+              </main>
+            </ZonosLayoutSetup>
+          </ZonosScriptContextProvider>
+        )
+      }
+      ```
+    </details>
+    <br>
+- For javascript framework that's not React, Next.js:
+  - Create a typescript file and import `@zonos/elements` to define types definition for `window` interface. You will have access to `window.Zonos` through out of your project if you are using typescript.
+    <details>
+      <summary>Code example</summary>
+
+      ```typescript
+      import "@zonos/elements";
+      ```
+    </details>
+    <br>
+
+## Npm
+### Npm when to use:
+This method is ideal if you are using TypeScript with modern JavaScript frameworks, particularly React and Next.js. It provides strong typing for the window.Zonos.init function, making setup easier and enabling auto-completion in TypeScript-enabled environments.
+
+### Npm usage:
+Install `@zonos/elements`:
+
+| Package Manager | Command                       |
+|-----------------|-------------------------------|
+| pnpm            | `pnpm add @zonos/elements`    |
+| npm             | `npm install @zonos/elements` |
+| yarn            | `yarn add @zonos/elements`    |
+
+<br>
+
+React, Next.js:
+- Create a component called `ZonosLayoutSetup.tsx`
+  <details>
+    <summary>Code example</summary>
+    
+    ```typescript
+    'use client';
+    import { type ReactNode, useEffect } from 'react';
+
+    import { Zonos } from '@zonos/elements';
+
+    import { useZonosScript } from 'src/utils/hooks/useZonosScript';
+
+    export const ZonosLayoutSetup = ({ children }: { children: ReactNode }) => {
+      useEffect(() => {
+        // Initialize Zonos into `window` API.
+        window.Zonos = Zonos;
+
+        const getCartItems = async () => {
+          const yourServerUrl = "https://your-server.com/api/get-cart-items";
+          const response = await fetch(yourServerUrl);
+          const json = await response.json();
+          return json;
+        };
+        
+
+        // Initialize Zonos
+        void window.Zonos.init({
+          checkoutSettings: {
+            buildCartDetail: async () => {
+              const allItems = getCartItems();
+              return allItems;
+            },
+            placeOrderButtonSelector: '<%= placeOrderButtonSelector %>',
+          },
+          storeId: Number('<%= storeId %>'), // Contact support for this information.
+          zonosApiKey: '<%= credentialToken %>', // Contact support for this information
+        });
+      }, [scriptLoaded]);
+
+      return children;
+    };
     ```
-    ---
-    + Keep and make `storeId` optional, and add `zonosStoreId` (Change field name `storeId` to `zonosStoreId`)
-    + Make the `storeId` to accept both type `string` and `number` (Change field type of `storeId` from `string` to `number`)
-    + Make the field `storeSetting` optional (Remove `storeSetting` field)
+  </details>
+  <br>
+
+- Put component `ZonosLayoutSetup.tsx` at top level of your `layout.tsx`
+  <details>
+    <summary>Code example</summary>
+
+    ```typescript
+    export default function Layout({ children }:{ children: ReactNode}) {
+      return (
+        <ZonosLayoutSetup>
+          <main>
+            {children}
+          </main>
+        </ZonosLayoutSetup>
+      )
+    }
     ```
-    - Update the current (non-deprecated) endpoint based on the notes in the `.md` file when all stores have moved past the deprecated version and remove that file when all are done. 
-    Ex:
-      - For file changes, if the changes made were:  
-        - Change field type `storeId` from `string` to `number` ==> take `string` off of the union type (string | number), just leave `number`.  
-        - Change field name `storeId` to `zonosStoreId` ==> delete `storeId` field.  
-        - Remove `storeSetting` ==> remove the optional field `storeSetting`.
-
-### Merging strategy
-The github action would bump the version conditionally on qa and main branch merged event. 
-+ qa branch merge flow: Only bump, publish version and create CDN when the version has alpha word.
-+ main branch merge flow: Create a branch against qa and run pnpm version:[patch|major|minor], have it merged to qa, it would not trigger the publish version and create CDN until the changes on qa get merged to main.
-
-### Steps
-1. Each PR against qa will need to be prerelease pumped by running pnpm version:alpha.
-2. PR get merged to qa will trigger the github action to publish to npm with alpha tag and create a cdn domain alpha.js.zonos.com - alpha cdn doesn’t need to be versioned, so that when rolling back, the changes will be affected right away. 
-3. The release process would happen on qa. If we want to release, a new branch named build/v1.x.x will need to be checkout from qa. Bump the version (major, minor or patch), and then merge to qa.  
-4. Create a new branch with the same name build/v1.x.xoff of main, pull from qa and just create PR and merge to main. 
-5. PR get merged to `main` will trigger the github action to publish to npm with major, minor or patch tag and create a cdn domain v1.2.3.js.zonos.com.
-
-### Bumping version rule of thumbs
-Below is scenario when to bump version:
-- Alpha: 
-  - If you need to have types change in zonos-elements and want to use that types in the dashboard (for example: add a new function into instance Zonos). Bump alpha would result pushing new version to npm, then dashboard can install and use it.
-  - If we want to have a domain with pinned version to use (v1.2.3-alpha.1.js.zonos.com) and not gonna be used directly with major pin domain (v1.js.zonos.com)
-  **Note: If you merge changes with alpha version to main, new release domain will not be generated.**
-- Patch:
-  - Any bug fix and small api changes
-- Minor:
-  - Architecture changes but doesn't take too much effort to move store to newer version
-  - Big API refactor
-- Major:
-  - A lot of stores are using zonos-elements stably and have new breaking changes would lead to breaking chain for all stores
+  </details>
+
+# API references
+### [Zonos instance definition](./dist/types/scripts/_zonosBase.d.ts)
+### [Single file definition for Zonos instance](./dist/scripts/index.d.ts)
+### [Zonos.init - checkoutSettings available configurations](./dist/types/types/checkout/CheckoutConfig.d.ts)
+### [Zonos.init - helloSettings available configurations](./dist/types/types/hello/HelloConfig.d.ts)