@bridevmx/clip-ify

v0.1.10

Published

7 months ago

A unofficial JavaScript client for the Clip API.

0High
0Medium
0Low

bridevmx

clip api ecommerce client

clip-ify

clip-ify es una biblioteca JavaScript ligera y fácil de usar, diseñada para interactuar con las APIs de e-commerce y descuentos de Clip. Proporciona una interfaz sencilla para obtener configuraciones de tiendas, categorías, productos y cupones.

Tabla de Contenidos

Instalación

Puedes instalar clip-ify usando npm o yarn:

npm i @bridevmx/clip-ify
# o
yarn add @bridevmx/clip-ify

Uso

Inicialización

Primero, importa la clase Clipify y crea una instancia.

// En un entorno de módulo (Node.js, React, Vue, Angular, etc.)
import Clipify from '@bridevmx/clip-ify';

// Si usas CDN (la clase Clipify estará disponible globalmente)
// <script src="http://unpkg.com/@bridevmx/clip-ify@latest"></script>

const clipClient = new Clipify();
// Puedes especificar un baseUrl personalizado si es necesario:
// const clipClient = new Clipify({ baseUrl: "https://tu-api-personalizada.com" });

Obtener Configuración de la Tienda

Obtiene la información de configuración de una tienda específica. Esta acción es crucial ya que de ella se obtiene el proxyMerchantToken necesario para otras operaciones.

let proxyMerchantToken = null; // Variable para almacenar el token

try {
    const shopName = 'Abarrotes123'; // Reemplaza con el nombre de tu tienda (slug)
    const response = await clipClient.getConfig(shopName);

    if (response.success && response.config) {
        console.log('Configuración de la tienda:', response.config);
        proxyMerchantToken = response.config.proxyMerchantToken;
        console.log('Proxy Merchant Token obtenido:', proxyMerchantToken);

        // Ejemplo: ahora puedes usar proxyMerchantToken en otras llamadas
        // if (proxyMerchantToken) {
        //     const categoriesResponse = await clipClient.getCategories(shopName);
        //     console.log('Categorías para la tienda:', categoriesResponse.items);
        // }

    } else {
        console.error('Error al obtener la configuración:', response.error);
    }
} catch (error) {
    console.error('Error en la solicitud de configuración:', error.message);
}

Obtener Categorías

Obtiene una lista de categorías disponibles para una tienda.

const shopName = 'Abarrotes123'; // Reemplaza con el nombre de tu tienda

try {
    const response = await clipClient.getCategories(shopName);

    if (response.success) {
        console.log('Categorías:', response.items);
    } else {
        console.error('Error al obtener categorías:', response.error);
    }
} catch (error) {
    console.error('Error en la solicitud de categorías:', error.message);
}

Obtener Productos por Categoría

Recupera una lista de productos para una categoría específica, usando el proxyMerchantToken y opcionalmente un limit.

Nota: En esta respuesta, los objetos ProductModifier solo contendrán modifierId y modifierName. Para obtener los detalles completos de los modificadores (incluyendo options), debes usar el método getProduct.

// Asegúrate de que proxyMerchantToken ya haya sido obtenido de getConfig()
if (proxyMerchantToken) {
    try {
        const categoryId = 'ID_DE_LA_CATEGORIA'; // e.g., '603925d0-58a8-49ed-b5de-80a20185a5d2'
        const limit = 10; // Opcional: número máximo de productos a retornar

        const response = await clipClient.getProducts(categoryId, proxyMerchantToken, limit);

        if (response.success) {
            console.log('Productos:', response.items);
        } else {
            console.error('Error al obtener productos:', response.error);
        }
    } catch (error) {
        console.error('Error en la solicitud de productos:', error.message);
    }
} else {
    console.warn('proxyMerchantToken no disponible. No se pueden obtener productos.');
}

Obtener un Producto Específico

Obtiene los detalles completos de un solo producto por su ID. Esta respuesta incluye información detallada sobre modificadores (con sus opciones) y variantes.

// Asegúrate de que proxyMerchantToken ya haya sido obtenido de getConfig()
if (proxyMerchantToken) {
    try {
        const productId = 'ID_DEL_PRODUCTO'; // e.g., 'd2be2730-d352-4506-b0a4-fe145ce293d3'

        const response = await clipClient.getProduct(productId, proxyMerchantToken);

        if (response.success) {
            console.log('Detalles del producto:', response.item);
        } else {
            console.error('Error al obtener el producto:', response.error);
        }
    } catch (error) {
        console.error('Error en la solicitud de un solo producto:', error.message);
    }
} else {
    console.warn('proxyMerchantToken no disponible. No se puede obtener el producto.');
}

Obtener Cupones

Recupera una lista de cupones activos para una tienda.

// Asegúrate de que proxyMerchantToken ya haya sido obtenido de getConfig()
if (proxyMerchantToken) {
    try {
        const response = await clipClient.getCoupons(proxyMerchantToken);

        if (response.success) {
            console.log('Cupones activos:', response.items);
        } else {
            console.error('Error al obtener cupones:', response.error);
        }
    } catch (error) {
        console.error('Error en la solicitud de cupones:', error.message);
    }
} else {
    console.warn('proxyMerchantToken no disponible. No se pueden obtener cupones.');
}

Modelos de Datos de Respuesta

Aquí se detallan las estructuras de los objetos principales que la biblioteca devuelve, incluyendo los campos opcionales.

ShopConfig (Configuración de la Tienda)

Representa la configuración detallada de una tienda.

CategoryItem (Elemento de Categoría)

Representa una categoría de productos.

ProductItem (Elemento de Producto)

Representa un producto individual. Los detalles (attributes, categories, modifiers.options, variants) se completan completamente al usar getProduct. Al usar getProducts, solo se incluyen modifierId y modifierName en el array modifiers.

| Propiedad | Tipo | Descripción | | :---------------- | :------------------------ | :-------------------------------------------------------------------------- | | attributes | Array<object> \| undefined | Opcional: Atributos del producto (ej. [{name: "Tamaño", values: ["Chico", "Grande"]}]). Presente en getProduct. | | basePrice | string \| null | Precio base del producto antes de variantes o descuentos. Puede ser null. | | categories | Array<object> \| undefined | Opcional: Lista de categorías a las que pertenece el producto. Presente en getProduct. | | ct | string | Hash de contenido o rastreador de cambios del producto. | | description | string | Descripción detallada del producto. | | enabled | boolean | Indica si el producto está activo/habilitado. | | image | string | URL de la imagen principal del producto. | | images | Array<string> | Array de todas las URLs de imágenes del producto. | | modifiers | Array<object> | Lista de modificadores para el producto. | | modifiers[].modifierId | string | ID único del modificador. | | modifiers[].modifierName | string | Nombre del modificador. | | modifiers[].options | Array<object> \| undefined | Opcional: Opciones detalladas del modificador (presente en getProduct). | | modifiers[].options[].modifierOptionId | string | ID de la opción del modificador. | | modifiers[].options[].modifierOptionName | string | Nombre de la opción del modificador. | | modifiers[].options[].price | string | Precio base de la opción del modificador. | | modifiers[].options[].extraPrice | string \| null | Precio adicional si se selecciona esta opción. Puede ser null. | | modifiers[].required | boolean \| undefined | Opcional: Indica si se debe seleccionar al menos una opción de este modificador (presente en getProduct). | | modifiers[].selectionLimit | number \| undefined | Opcional: Número máximo de opciones que se pueden seleccionar de este modificador (presente en getProduct). | | numberOfModifiers | number | Cantidad de modificadores asociados al producto. | | numberOfVariants | number | Cantidad de variantes para el producto. | | price | string | Precio actual del producto (puede ser el precio base o el de la variante más económica). | | productId | string | ID único del producto. | | productName | string | Nombre del producto. | | sku | string \| null | SKU (Stock Keeping Unit) del producto. Puede ser null. | | stock | number | Nivel de stock actual del producto (o de la variante por defecto). | | stockAlert | string \| null \| undefined | Opcional: Mensaje de alerta sobre el stock. Puede ser null. Presente en getProduct. | | stockStatus | string | Estado del stock del producto (ej. "AVAILABLE", "SOLD_OUT"). | | variants | Array<object> \| undefined | Opcional: Array de variantes del producto (presente en getProduct). | | variants[].variantId | string | ID único de la variante del producto. | | variants[].variantName | string | Nombre de la variante (ej. "Chico", "Mediano"). | | variants[].price | number | Precio de la variante. | | variants[].stock | number | Nivel de stock de la variante. | | variants[].stockStatus | string | Estado del stock de la variante (ej. "AVAILABLE"). | | variants[].isAvailable | boolean | Indica si esta variante está disponible. | | variants[].isDefault | boolean | Indica si esta es la variante por defecto. | | variants[].description | string | Descripción de la variante (a menudo coincide con variantName). | | variants[].options | Array<object> | Pares clave-valor que describen los atributos de la variante. | | variants[].sku | string \| null | SKU de la variante. Puede ser null. | | variants[].images | Array<string> \| null | Imágenes específicas para esta variante. Puede ser null. | | version | string \| null | Versión de los datos del producto. Puede ser null. |

CouponItem (Elemento de Cupón)

Representa un cupón de descuento activo.

Manejo de Errores

Todos los métodos de clip-ify que realizan solicitudes de red son async y devuelven una Promise. Es crucial envolver las llamadas en bloques try...catch para manejar posibles errores de red, timeouts o respuestas de API con códigos de estado no exitosos.

La biblioteca lanzará un Error si:

Faltan parámetros requeridos en los métodos (ej. shopName, proxyMerchantToken).
La solicitud de red falla (ej. problemas de conexión, timeout).
La API de tu backend devuelve un código de estado HTTP no exitoso (4xx, 5xx). En este caso, el mensaje de error del Error contendrá el mensaje de la API si está disponible, o un mensaje genérico como Request failed with status 404.

Las respuestas de la API (response.success: false) indicarán errores específicos de la lógica de negocio de tu API (ej. tienda no encontrada, datos no parseados).

Contribución

¡Las contribuciones son bienvenidas! Si encuentras un error o tienes una sugerencia de mejora, por favor abre un issue o envía un pull request en el repositorio de GitHub.

Contacto

[email protected]

Licencia

Este proyecto está bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.