SDK @clione/seo

@clione/seo es un paquete npm agnóstico de framework para ir a buscar las señales SEO/AEO/GEO enriquecidas de Clione en storefronts headless. Cero dependencias, dos modos (API o metafield), con adaptadores de framework para Next.js, Hydrogen y Nuxt / Vue Storefront.

Si estás enviando un frontend a medida (Catalyst, Hydrogen, Vue Storefront, Next.js Commerce, lo tuyo), este SDK es la manera recomendada de consumir señales de Clione.

Para tiendas no-headless (BC Stencil, temas Liquid de Shopify), prefiere el Schema Injector (BC) o el theme app block (Shopify) — gestionan la misma entrega server-side sin que tu frontend haga nada.

---

Instalar

npm install @clione/seo
# o
pnpm add @clione/seo
# o
yarn add @clione/seo

El paquete está publicado como @clione/seo. No tiene dependencias en runtime (usa el fetch de la plataforma).

---

Dos modos

Modo	Cuándo usarlo
Modo API (getSignals)	Quieres señales frescas en tiempo de petición. Llama a la SEO Signals API.
Modo metafield (extractSignals)	Ya estás descargando el producto desde Shopify GraphQL y el metafield clione.jsonld está en la respuesta. Extrae señales de ahí, sin petición extra.

El modo API es el por defecto y funciona en ambas plataformas. El modo metafield es solo Shopify hoy (el modo metafield headless de BC está planeado).

---

Modo API

import { getSignals } from '@clione/seo'

const { signals, entity } = await getSignals('product', productId, {
  apiKey: process.env.CLIONE_API_KEY,
  storeId: process.env.CLIONE_STORE_ID,
  platform: 'shopify', // o 'bigcommerce'
  baseUrl: 'https://api.clione.ai', // opcional — por defecto api.clione.ai
})

Devuelve la misma forma que GET /api/v1/public/seo-signals/... documentado en SEO Signals API.

Tipos de entidad

type EntityType = 'product' | 'category' | 'collection' | 'page'

Usa category en BigCommerce, collection en Shopify. Código mixto de plataformas debería bifurcar en platform para elegir el tipo de entidad correcto.

---

Modo metafield (solo Shopify)

Si ya estás descargando el producto desde la Storefront API de Shopify con metafields, extrae el JSON-LD directamente:

import { extractSignals } from '@clione/seo'

const product = await shopifyClient.query(/* GraphQL con metafield clione.jsonld */)
const { signals } = extractSignals(product)

Esto evita una segunda llamada de red a Clione. Útil cuando:

• Ya pagas el coste de descargar el producto desde Shopify.
• Quieres que las señales sean consistentes con la versión del producto que acabas de renderizar.
• Estás en el edge y quieres menos llamadas fan-out.

El metafield debe ser legible en los scopes permitidos del token de Storefront API.

---

Adaptadores de framework

Next.js (App Router)

// app/products/[handle]/page.tsx
import { getSignals } from '@clione/seo'

export async function generateMetadata({ params }) {
  const { signals } = await getSignals('product', params.handle, {
    apiKey: process.env.CLIONE_API_KEY,
    storeId: process.env.CLIONE_STORE_ID,
    platform: 'shopify',
  })

  return {
    title: signals.metaTitle,
    description: signals.metaDescription,
    alternates: { canonical: signals.canonicalUrl },
    openGraph: signals.ogTags,
  }
}

export default async function ProductPage({ params }) {
  const { signals } = await getSignals('product', params.handle, /* ... */)
  return (
    <>
      <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(signals.jsonLd) }} />
      {/* resto de página */}
    </>
  )
}

También está @clione/seo/react con hooks (useSignals) para fetches client-side.

Hydrogen (Shopify)

// app/routes/products.$handle.tsx
import { useLoaderData } from '@remix-run/react'
import { extractSignals } from '@clione/seo'

export async function loader({ params, context }) {
  const product = await context.storefront.query(PRODUCT_QUERY_WITH_METAFIELD, {
    variables: { handle: params.handle },
  })
  const { signals } = extractSignals(product)
  return { product, signals }
}

export function meta({ data }) {
  return [
    { title: data.signals.metaTitle },
    { name: 'description', content: data.signals.metaDescription },
  ]
}

Nuxt / Vue Storefront / Alokai

// pages/products/[handle].vue
<script setup>
import { useClioneSignals } from '@clione/seo/nuxt'

const route = useRoute()
const { signals } = await useClioneSignals('product', route.params.handle, {
  platform: 'shopify',
})

useHead({
  title: signals.metaTitle,
  meta: [{ name: 'description', content: signals.metaDescription }],
  script: [{ type: 'application/ld+json', innerHTML: JSON.stringify(signals.jsonLd) }],
})
</script>

---

Configuración

La llamada getSignals acepta:

Opción	Por defecto	Notas
apiKey	(env: CLIONE_API_KEY)	Obligatorio.
storeId	(env: CLIONE_STORE_ID)	Opcional. Desambigua cuando una org tiene varias tiendas en la misma plataforma.
platform	inferido	Opcional. Inferido de storeId si se proporciona.
baseUrl	https://api.clione.ai	Override para Clione self-hosted.
fetch	fetch global	Override para fetch personalizado (raro).
cache	default	Pasado al fetch. Configura a 'no-store' para saltarte la caché de edge.

---

Caché

• getSignals respeta el header de respuesta Cache-Control: public, max-age=60 de la API. En el edge (Cloudflare Workers, Vercel Edge Functions), esto cachea 60 segundos automáticamente.
• Para TTLs de caché más largos, envuelve la llamada tú mismo con la primitiva de caché de tu framework (unstable_cache de Next.js, withCache de Hydrogen, etc.).
• Clione invalida las cachés server-side en cada enriquecimiento, así que puedes cachear agresivamente sin preocuparte por staleness.

---

TypeScript

El paquete trae tipos TS completos:

import type { Signals, Entity, EntityType, Platform } from '@clione/seo'

---

Notas por plataforma

	BigCommerce	Shopify
Modo API (getSignals)	Sí (product, category, page)	Sí (product, collection, page)
Modo metafield (extractSignals)	Planeado	Sí (metafield clione.jsonld)
JSON-LD para productos	Sí	Sí (schema completo)
JSON-LD para categorías/colecciones	Aún no	Aún no
OG tags	Sí	Sí

---

Solución de problemas

Error: Clione SEO Signals: 401 — API key incorrecta o ausente. Revisa la variable de entorno CLIONE_API_KEY.

Error: Clione SEO Signals: 403 — API key válida pero el header Origin no coincide con la lista de dominios permitidos. Actualiza la lista blanca en Store → Settings → API Keys.

Error: Clione SEO Signals: 404 — Entidad no sincronizada o no enriquecida, O plataforma / storeId equivocados. Revisa que la entidad existe en tu dashboard de Clione.

El modo metafield devuelve señales vacías — El metafield clione.jsonld está vacío (producto no enriquecido), o tu token de Storefront API no puede leer el namespace clione. Añade clione a los namespaces de metafield en la config de tu app de Shopify.

Latencia de cold start — La primera llamada a api.clione.ai desde una región fría puede ser de 200–400ms. Cachea agresivamente para amortizar.