webc-miam 5.0.0 → 6.0.0

package/interfaces/comparable-product.ts

@@ -0,0 +1,24 @@
+/**
+ * An interface used to represent a product when Miam synchronizes the client's cart with
+ * Miam's basket, and need to compare products present in each one.
+ */
+export interface ComparableProduct {
+  /**
+   * Id of the product in the client's database (called ext-id on Miam's end).
+   */
+  id: string;
+  /**
+   * When client side sends an array of ComparableProduct to Miam, the SDK expects quantities
+   * to match the quantity of each product in the cart of the client.
+   *
+   * When Miam sends an array of ComparableProducts to the client, quantities represent the quantity
+   * of products to add to the client's cart, and as such can be negatives if products need to be
+   * removed from the cart.
+   */
+  quantity: number;
+  /**
+   * The client can add attributes if they need when sending ComparableProducts to the SDK.
+   * Miam will send the attributes back if changes are to be made about those products.
+   */
+  additionalInfos?: any;
+}

package/interfaces/miam-interface.ts

@@ -0,0 +1,236 @@
+import { Observable } from 'rxjs';
+import { ComparableProduct } from './comparable-product';
+
+export interface MiamInterface  {
+  /**
+   * Method to call when the user begins the payment procedure (typically when they click
+   * on a "Confirm my cart" button)
+   * @param totalPrice the total price of your basket (can be a floating or integer number)
+   */
+  paymentStarted: (totalPrice: number) => void;
+
+  // ---------------------------------------------------------------------------------------------------
+
+  analytics: {
+    /**
+     * Initialize Analytics
+     *
+     * @param domain Plausible domain
+     * @param optimizeKey Google Optimize key
+     */
+    init: (domain: string, optimizeKey: string) => void;
+  };
+
+  // ---------------------------------------------------------------------------------------------------
+
+  basket: {
+    /**
+     * Emits true when Miam's basket has succesfully loaded for the first time.
+     * Does not emit anything before or after that.
+     */
+    basketIsReady$: Observable<boolean>;
+    /**
+     * Fetch the first GroceriesList & Basket early (before any action requires it on Miam's
+     * side), so you can start the basket-sync earlier
+     */
+    initialize: () => void;
+  };
+
+  basketSync: {
+    /**
+     * The callback parameter is called when Miam's basket changes to update the user's cart accordingly
+     *
+     * @param pushProductsToBasket a method that updates the user's cart with the pruducts passed in parameter, by adding
+     * products if their quantity is positive, and removing them if their quantity is negative
+     */
+    definePushProductsToBasket: (pushProductsToBasket: (products: ComparableProduct[]) => void) => void;
+    /**
+     * Call to notify Miam that the user's cart has been updated
+     *
+     * @param comparableProducts The products in the user's cart
+     */
+    retailerBasketChanged: (comparableProducts: ComparableProduct[]) => void;
+    /**
+     * Call to notify Miam that the user's cart was paid
+     * Miam then refreshes the groceries-list and basket for the next user's cart
+     *
+     * @param total The total price of the cart paid
+     */
+     handlePayment: (total: number) => void
+  };
+
+  // ---------------------------------------------------------------------------------------------------
+
+  features: {
+    /**
+     * Call to enable recipes to display a video instead of their picture, if there is a video for the recipe
+     */
+    enableVideoRecipes: () => void;
+    /**
+     * Call to enable the catalog to display articles, if their are packages that contain any articles
+     */
+    enableArticlesInCatalog: () => void;
+    /**
+     * Call to authorize Miam to ask for user preferences the first time users view the recipe catalog
+     */
+    enableUserPreferences: () => void;
+    /**
+     * Call to enable tags displaying on recipe-details
+     */
+    enableTagsOnRecipes: () => void;
+    /**
+     * Call to enable personal recipes on recipe-catalog
+     */
+    enablePersonalRecipes: () => void;
+  };
+
+  // ---------------------------------------------------------------------------------------------------
+
+  hook: {
+    /**
+     * Set up a callback which Miam will call before adding a recipe to the user's cart
+     *
+     * @param callback a method that will be called passing two parameters :
+     *  - isLogged, true if the user is logged (according to Miam, see user.loadWithExtId for more)
+     *  - isPosValid true if the PointOfSale is recognized by Miam
+     * Typically you might want to use this to show your connexion page if the user tries to add a recipe while logged out
+     * or to show your point of sale picker if the user has not chosen one
+     */
+    setHookCallback: (callback: (isLogged, isPosValid) => boolean) => void;
+  };
+
+  // ---------------------------------------------------------------------------------------------------
+
+  list: {
+    /**
+     * Resets Miam's GroceriesList & empties all products & recipes added by the user
+     * /!\ We heavily recommend not to use this method outside of the web console for testing purposes /!\
+     */
+    reset: () => void;
+    /**
+     * Adds a recipe to Miam's basket
+     * /!\ We heavily recommend not to use this method outside of the web console for testing purposes /!\
+     */
+    addRecipe: (recipeId: string, guests: number) => Observable<object>;
+    /**
+     * Returns an observable that will emit true if the recipe passed in parameter is in Miam's GroceriesList
+     */
+    hasRecipe: (recipeId: string) => Observable<boolean>;
+  };
+
+  // ---------------------------------------------------------------------------------------------------
+
+  pos: {
+    /**
+     * Call to inform Miam of the point of sale the user is currently on. Do not forget to call the method
+     * if it changes after user loads the page
+     *
+     * @param extId the id of the PointOfSale in client's database
+     */
+    loadWithExtId: (extId) => void;
+  };
+
+  // ---------------------------------------------------------------------------------------------------
+
+  recipes: {
+    /**
+     * An observable that emits a value when the recipe-modal is closed
+     */
+    hidden: Observable<boolean>;
+    /**
+     * If called with a parameter to true, recipe-details will show a picture next to the ingredients
+     */
+    shouldDisplayIngredientPicturesOnRecipeCards: (should: boolean) => void;
+    /**
+     * Call with an url of a picture to change the default picture displayed if an ingredient doesn't have a picture
+     * and if ingredients picture have been enabled with recipes.shouldDisplayIngredientPicturesOnRecipeCards(true)
+     */
+    setDefaultIngredientPicture: (url: string) => void;
+    /**
+     * Override default labels for difficulty levels
+     *
+     * @param levels The list of labels to override for each difficulty (difficulties are respectively 1: Easy, 2: Medium, 3: Hard)
+     * example : [{value: 1, label: "Beginner"}] to update the label of easy recipes to "Beginner"
+     */
+    setDifficultyLevels: (levels: { value: number, label: string }[]) => void;
+
+    // /**
+    //  * /!\ DEPRECATED: DO NOT USE /!\
+    //  */
+    //  setRecipesPrimaryButtonActions: (display: boolean, addToBasket: boolean) => void;
+    // /**
+    //  * /!\ DEPRECATED: DO NOT USE /!\
+    //  */
+    // setSuggestionsPrimaryButtonActions: (display: boolean, addToBasket: boolean) => void;
+  };
+
+  // ---------------------------------------------------------------------------------------------------
+
+  router: {
+    /**
+     * Inform Miam of the url where the catalog is for the redirection link of recipe-details
+     */
+    setRecipeCatalogUrl: (url: string) => void;
+    /**
+     * Inform Miam of the url where the onboarding section of the catalog should redirect
+     */
+    setRecipeInfoLink: (url: string) => void;
+  };
+
+  // ---------------------------------------------------------------------------------------------------
+
+  supplier: {
+    /**
+     * Call to inform Miam of the supplier the user is currently on. Do not forget to call the method
+     * if it changes after user loads the page (should not happen escept in very specific cases)
+     *
+     * @param supplierId the Supplier id in Miam's database
+     */
+    load: (supplierId: number | string) => void;
+  };
+
+  // ---------------------------------------------------------------------------------------------------
+
+  user: {
+    /**
+     * Call to inform Miam of the id of the user.
+     *
+     * @param id a string unique identifier to the user
+     * @param forbidProfiling if set to true, desactivate personalized content (personalized recipes & products)
+     * @param initBasket DEPRECATED - if set to true, fetch the GroceriesList & Basket of the user (recommanded as
+     * it saves time later)
+     */
+    loadWithExtId: (id: string, forbidProfiling: boolean, initBasket: boolean) => Observable<object>;
+    /**
+     * Call to inform Miam that the user has logged out
+     */
+    reset: () => void;
+    /**
+     * If your website has a "favorite products" feature, you can pass the ids of all products
+     * which the user has marked as favorites, so they can be prioritized when adding a recipe
+     * to their cart, if one of them is returned as a matching product for the recipe.
+     *
+     * @param favoriteProductIds an array of product ids, passed as string
+     */
+    setFavoriteItems: (favoriteProductIds: string[]) => Observable<object>;
+  };
+
+  // ---------------------------------------------------------------------------------------------------
+
+  view: {
+    /**
+     * Call to notify Miam of the scrollable element of the client's page, if it is not <body>
+     * This is necessary to prevent the page to scroll in the backgroud when Miam opens a popup/modal/drawer
+     */
+    setGlobalScrollableElement: (element: HTMLElement) => void;
+  };
+
+  // ---------------------------------------------------------------------------------------------------
+
+  /**
+   * Override two times will not be considered (DEPRECATED)
+   * @param icon have to be a knowed icon name see section 'Custom icons' in read me
+   * @param url of the new icon
+   */
+  overrideIcon: (icon, url: string) => void;
+}