@comenchi/shop-sdk

Version: 3.0.0-beta.11

SDK puro y liviano para interactuar con la API de Vendure de Comenchi. Este SDK maneja todas las operaciones GraphQL necesarias para e-commerce: productos, colecciones, órdenes, checkout, etc.

Características

• ✅ SDK puro sin dependencias de UI frameworks
• ✅ TypeScript con tipos generados automáticamente
• ✅ Soporte para SSR y CSR
• ✅ Manejo de autenticación y sesiones
• ✅ APIs completas para e-commerce

Instalación

pnpm add @comenchi/shop-sdk

Uso Básico

1. Inicializar el SDK

import { ComenchiShop } from "@comenchi/shop-sdk";

const sdk = new ComenchiShop({
  apiUrl: "https://api.example.com/graphql",
  channelToken: "your-channel-token",
});

2. Usar con React (Provider)

import { ComenchiProvider } from "@comenchi/shop-sdk";

function App() {
  return (
    <ComenchiProvider value={sdk}>
      <YourApp />
    </ComenchiProvider>
  );
}

// En componentes hijos
import { useComenchiShop } from "@comenchi/shop-sdk";

function ProductList() {
  const sdk = useComenchiShop();

  // Usar el SDK
  const products = await sdk.products.list({ take: 10 });
}

APIs Disponibles

Collections API (sdk.collections)

// Listar colecciones
const collections = await sdk.collections.list({ take: 20 });

// Obtener colección por slug
const collection = await sdk.collections.getBySlug("electronics");

Products API (sdk.products)

// Listar productos
const products = await sdk.products.list({ take: 10, skip: 0 });

// Buscar productos
const searchResults = await sdk.products.search({ term: "laptop" });

// Obtener producto por slug
const product = await sdk.products.getBySlug("macbook-pro");

Order API (sdk.order)

// Obtener orden activa
const activeOrder = await sdk.order.active();

// Agregar item al carrito
await sdk.order.addItem({
  productVariantId: "123",
  quantity: 2,
});

// Aplicar cupón
await sdk.order.applyCouponCode("DESCUENTO10");

// Establecer dirección de envío
await sdk.order.setShippingAddress({
  fullName: "Juan Pérez",
  streetLine1: "Av. Principal 123",
  city: "Lima",
  countryCode: "PE",
});

// Agregar pago
await sdk.order.addPayment({
  method: "stripe",
  metadata: { paymentIntentId: "pi_xxx" },
});

// Transicionar orden
await sdk.order.transitionTo("ArrangingPayment");

Customer API (sdk.customer)

// Obtener cliente activo
const customer = await sdk.customer.active();

// Obtener direcciones
const addresses = await sdk.customer.addresses();

// Crear dirección
await sdk.customer.createAddress({
  fullName: "Juan Pérez",
  streetLine1: "Av. Principal 123",
  city: "Lima",
  countryCode: "PE",
});

Extras API (sdk.extras)

// Búsqueda de ubigeo (Perú)
const departments = await sdk.extras.ubigeo({
  type: "department",
});

const provinces = await sdk.extras.ubigeo({
  type: "province",
  departmentCode: "15",
});

Channel API (sdk.channel)

// Obtener información del canal activo
const channel = await sdk.channel.active();

Assets API (sdk.assets)

// Obtener assets
const assets = await sdk.assets.list({ take: 20 });

WhatsApp API (sdk.wts)

// Enviar mensaje por WhatsApp
await sdk.wts.sendMessage({
  to: "+51999999999",
  message: "Hola desde Comenchi",
});

TypeScript

El SDK incluye tipos completos generados desde el schema GraphQL:

import type { Product, Collection, Order, Customer } from "@comenchi/shop-sdk";

SSR (Server-Side Rendering)

El SDK funciona tanto en cliente como en servidor:

// En loader de React Router
export async function loader() {
  const sdk = new ComenchiShop({
    apiUrl: process.env.API_URL,
    channelToken: process.env.CHANNEL_TOKEN,
  });

  const products = await sdk.products.list({ take: 10 });

  return { products };
}

Configuración Avanzada

import { ComenchiShop, InMemoryPersist } from "@comenchi/shop-sdk";

const sdk = new ComenchiShop({
  apiUrl: "https://api.example.com/graphql",
  channelToken: "your-channel-token",

  // Persister personalizado (por defecto: InMemoryPersist)
  persister: new InMemoryPersist(),

  // Headers adicionales
  headers: {
    "X-Custom-Header": "value",
  },
});

// Cambiar channel token dinámicamente
sdk.setChannelToken("new-channel-token");

// Clonar SDK con opciones diferentes
const clonedSdk = ComenchiShop.clone(sdk, {
  channelToken: "another-token",
});

Contribución

Este SDK es parte del monorepo de Comenchi. Para contribuir, revisa la guía de contribución.

Licencia

ISC