# Avileo catalog agent integration

Use this context only for trusted server-side catalog automation with an avileo_sk_ Agent Key injected as AVILEO_AGENT_API_KEY.

# Agent integrations

URL: https://avileo.theelena.me/docs/agent-integration
Description: Connect a trusted server-side agent with read or mutate access.

# Agent integrations

Avileo has two credential boundaries:

| Credential                 | Use                                         | Storage                         |
| -------------------------- | ------------------------------------------- | ------------------------------- |
| `avileo_pk_...` Client Key | Public catalog, storefronts and public SDK  | Browser or public environment   |
| `avileo_sk_...` Agent Key  | Private business and catalog administration | Server-side secret manager only |

The public Client Key keeps the existing storefront contract. The Agent Key is
bound to one business and has two modes:

- **read**: business, profile, catalog, assets and inventory inspection;
- **mutate**: reads plus proposals for administrative changes.

Availability comes from the effective `agentCatalogAccessEnabled` business-mode
capability, including tenant overrides. It is not hardcoded to a rubro slug.

## Human approval

A mutate-mode key still cannot change data immediately:

1. The agent submits an allowlisted operation and exact payload.
2. Avileo generates the summary and diff and returns an approval URL.
3. An authorized staff user reviews and approves or rejects it.
4. The agent applies the same payload with that approval ID.
5. Avileo records the terminal result and prevents reuse for another payload.

Reads and import previews do not require approval. Product, variant, taxonomy,
asset, inventory and import-apply mutations do.

## Creating a web credential

A mutate-mode agent may propose creating a public Client Key. After staff
approval, the one-shot apply response returns `avileo_pk_...`; a coding agent
can place it in the web project's `.env` and use the public SDK. The secret
`avileo_sk_...` must never enter that project or a browser bundle.

## Manage the existing Agent Key

From Avileo settings, open the current Agent Key and switch it between **Solo
lectura** and **Lectura y mutación**. This updates the same credential; it does
not rotate or reveal its secret. Existing write-enabled keys appear as mutate.

See [Agent HTTP API](/docs/agent-http), [Agent SDK](/docs/agent-sdk), and
[Agent CLI](/docs/agent-cli) for concrete usage.

---

# Skill para agentes

URL: https://avileo.theelena.me/docs/agent-skill
Description: Instala la skill oficial para gestionar un catálogo Avileo con un agente confiable.

# Skill para agentes

La skill `avileo-catalog` enseña a un agente a evaluar y gestionar el perfil,
productos, variantes, categorías, imágenes e inventario con el flujo seguro de
Avileo. También puede revisar una muestra del catálogo y una web confirmada para
dar recomendaciones basadas en evidencia. Usa una Agent Key `avileo_sk_...`
desde un gestor de secretos y sólo funciona cuando el negocio tiene habilitada
la capacidad efectiva de acceso para agentes.

## Instalación

Instalación automática para el host detectado:

```sh
npx skills add leobar37/elena-tech --skill avileo-catalog
```

Para indicar el host explícitamente:

```sh
# Codex
npx skills add leobar37/elena-tech --skill avileo-catalog --agent codex

# Claude Code
npx skills add leobar37/elena-tech --skill avileo-catalog --agent claude-code
```

Agrega `--global` cuando quieras instalarla para todos los proyectos del usuario.
La fuente pública y host-neutral está en
[`leobar37/elena-tech`](https://github.com/leobar37/elena-tech/tree/main/skills/avileo-catalog).

En desarrollo local, la skill conserva un comando o wrapper ya configurado y
usa el SDK del workspace cuando existe un checkout confirmado. La fuente del
paquete y la URL de la API se eligen por separado. La CLI pública está
verificada en npm (`@tarileo/avileo-catalog-cli@0.3.4`); instálala con npx
cuando el host no aporte un comando local y no cambies silenciosamente de
destino.

## Configura la credencial

La conexión requiere un cliente compatible verificado y un despliegue
habilitado. El origen seleccionado para esta guía es https://avileo.theelena.me.
Sin ese cliente, detente en la lectura de documentación: no solicites claves
ni vinculación.

Cuando el cliente esté disponible, el humano deberá autorizar explícitamente
el negocio y los permisos. La Agent Key permanece en el host de confianza;
no la escribas en prompts, argumentos, URLs, archivos JSON, logs ni repositorios.
Una credencial sin origen o con otro destino no autoriza el acceso a esta API.

## Verifica el contexto

Antes de cualquier acceso con un cliente compatible, comprueba que su origen
persistido coincide con el seleccionado; no reenvíes una clave a otro destino.

Continúa únicamente si confirma el negocio, la capacidad efectiva y las acciones
necesarias. Para una evaluación, ejecuta también `business profile show --json`
y revisa una muestra acotada de productos antes de recomendar. Antes de modificar
algo, lee el recurso, ejecuta el preview sin `--apply`, presenta el cambio y
solicita aprobación explícita. Usa `--apply` sólo para crear esa propuesta y
aplica únicamente el identificador aprobado.

Consulta también [Integraciones de agentes](/docs/agent-integration),
[Agent CLI](/docs/agent-cli), [Agent SDK](/docs/agent-sdk) y
[Agent HTTP API](/docs/agent-http).

---

# Agent SDK

URL: https://avileo.theelena.me/docs/agent-sdk
Description: Use Avileo's typed server-only SDK with human-approved mutations.

# Agent SDK

```ts
import { createAvileoAgent } from '@tarileo/avileo-sdk/agent';

const agent = createAvileoAgent({
  apiKey: process.env.AVILEO_AGENT_API_KEY!,
});
```

The key remains inside the transport closure and identifies one business.
Availability is capability-based rather than tied to a rubro slug.

## Reads

```ts
const business = await agent.business.get();
const profile = await agent.business.profile();
const products = await agent.products.list({ limit: 50 });
```

## Proposal and approved apply

```ts
const proposal = await agent.operations.propose({
  operationName: 'catalog.products.update',
  payload: {
    productId,
    body: { name: 'Café reserva' },
  },
});

// Show proposal.summary, proposal.diff and proposal.approvalUrl.
// After an authorized user approves it in Avileo:
const product = await agent.products.update(productId, { name: 'Café reserva' }, proposal.id);
```

Every catalog write accepts an explicit approval ID. The SDK never fabricates
human consent and never derives idempotency keys on its own: automatic
retries are plain requests. Pass an explicit `idempotencyKey` when a mutation
must be replay-safe — a replayed payment-link create returns `replayed: true`
with `url: null` and keeps the one-time pay URL secret.

## Create a Client Key

```ts
const proposal = await agent.operations.proposeClientKey('Web del cliente');
// Approve proposal.approvalUrl in Avileo.
const applied = await agent.operations.apply(proposal.id);
const publicClientKey = applied.result.clientKey.key;
```

The public Client Key is returned once and may be written to the web project's
public environment. Later operation status reads redact that secret.

## Resources

```ts
agent.business;
agent.operations;
agent.products;
agent.variants;
agent.categories;
agent.tags;
agent.assets;
agent.inventory;
agent.imports;
agent.paymentLinks;
```

Never import the Agent SDK into a browser bundle or place
`AVILEO_AGENT_API_KEY` in frontend environment variables.

For headless payments — the QR rendered in your own UI and gateway-side
confirmation — see [Links de pago](/docs/payment-links).

For the complete server-to-server contract, see [Agent HTTP API](/docs/agent-http).

---

# Links de pago

URL: https://avileo.theelena.me/docs/payment-links
Description: Crea cobros headless desde tu backend con el Agent SDK — QR propio, confirmación por gateway y polling del estado.

# Links de pago

Cobra desde tu propio backend sin enviar al pagador a una página de Avileo:
tu sistema crea el link, muestra el QR del negocio en su propia UI y espera la
confirmación del gateway.

## Requisitos

- Negocio **Tienda** con `paymentLinksEnabled` (activo por default).
- Al menos un método de cobro configurado con datos válidos: QR de Yape/Plin o
  transferencia con banco y número de cuenta (Configuración → Métodos de pago).
- Una Agent Key con `payments:write` (ve
  [Agent integrations](/docs/agent-integration)).
- Para confirmación automática sin comprobante: gateway Yape activo.

## Crear el link y mostrar el QR

```ts
import { createAvileoAgent } from '@tarileo/avileo-sdk/agent';

const avileo = createAvileoAgent({ apiKey: process.env.AVILEO_AGENT_API_KEY! });

const link = await avileo.paymentLinks.create({
  amount: 3, // soles; el backend convierte a céntimos
  concept: 'Anticipo pedido #123',
  expectedMethod: 'yape', // o 'any' para dejar elegir al pagador
});
// Sin idempotencyKey: cada create es un link nuevo. Ver
// "Idempotencia y URL de un solo uso" antes de usarla.

if (!link.replayed) {
  // link.url es el enlace de pago público (one-time): /pagar/<token>
  const token = link.url!.split('/').pop()!;
  const view = await avileo.paymentLinks.getPublicView(token);
  const yape = view.methods.yape;
  // <img src={yape.qrUrl} /> — el QR del asset vinculado al método,
  // resuelto por el backend. Además: yape.phone, yape.accountName,
  // yape.accountNumber, yape.bank, yape.cci.
}
```

`getPublicView` consulta el endpoint público por token: no requiere la Agent
Key y nunca expone evidencia interna ni el token mismo.

## Confirmación

| Origen                  | Cómo confirma                                                                                                                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Gateway Yape            | Una detección de monto exacto sin intent de venta reclama al único link abierto compatible → `confirmed` con `confirmedBy: 'gateway'`. Sin comprobante ni visita del pagador.              |
| Comprobante del pagador | El pagador sube la captura en `link.url`; la IA la valida y confirma automáticamente si el monto entra en la auto-aprobación (default S/200); si no, queda `under_review` para el negocio. |

Polling del estado desde tu backend:

```ts
const payment = await avileo.paymentLinks.get(link.id);
// payment.status: awaiting_payment → verifying → confirmed
//   | under_review | rejected | expired | cancelled
if (payment.status === 'confirmed') {
  // payment.confirmedBy: 'gateway' | 'ai' | 'manual'
  // payment.extraction: proveedor, monto detectado, número de operación…
}
```

No hay webhook todavía: el patrón soportado es polling (5 segundos es
razonable) o listar con filtros
(`avileo.paymentLinks.list({ status: 'confirmed', from })`).

## Idempotencia y URL de un solo uso

- La URL con el token viaja **solo** en la respuesta del create inicial.
- **En el flujo headless no mandes `idempotencyKey`.** Si un replay ocurre,
  el backend responde `replayed: true` con `url: null`: el link queda
  huérfano y el QR es irrecuperable por API (solo el negocio puede rotarlo
  con "Links de pago → Reenviar"). Un timeout ambiguo es mejor duplicar el
  link que perder el token.
- Úsala solo si tu lado garantiza no reintentar un create cuya respuesta
  perdiste, y sabes que `replayed: true` significa "ya existe, recupera la
  referencia por tus propios registros", nunca por la URL.
- El transporte del SDK no genera claves de idempotencia ni reenvía una en
  reintentos: ninguna key sale del SDK salvo la que pongas explícitamente en
  el body.

## Errores comunes

- `AgentUnsupportedCapabilityError`: el negocio no tiene links de pago
  habilitados (solo Tienda hoy).
- Validación al crear: monto fuera de S/0.01–S/1,000,000, vigencia mayor a 30
  días, o método esperado sin datos de cobro válidos.
- `409` en la subida del comprobante: ya hay un intento verificándose o el
  link ya está confirmado o rechazado.

## Reglas

- Server-side only: nunca importes el Agent SDK en el navegador ni expongas
  `AVILEO_AGENT_API_KEY`.
- No mezcles la Agent Key con la Client Key de un storefront
  ([Client Key](/docs/client-key)).
- La vigencia va de 1 hora a 30 días (`expiresInHours`, default 24).

Para el contrato HTTP completo sin SDK, ve [Agent HTTP API](/docs/agent-http).

---

# Agent CLI

URL: https://avileo.theelena.me/docs/agent-cli
Description: Operate Avileo through durable, human-approved agent mutations.

# Agent CLI

## Instalación y conexión

La CLI pública está verificada en npm: `@tarileo/avileo-catalog-cli@0.3.4`
incluye el contrato de selección de origen. Ejecútala sin instalación global:

```sh
npx --yes @tarileo/avileo-catalog-cli@0.3.4 auth login --base-url https://avileo.theelena.me --json
```

Abre el enlace de verificación, inicia sesión en Avileo y elige un modo: **Solo
lectura** o **Lectura y mutación**. La CLI imprime solo la URI de verificación,
el código de usuario y el origen fijado; guarda la Agent Key localmente con
permisos `0600` y nunca la imprime ni la coloca en una URL. Usa
`auth status --json` para revisar el origen fijado sin revelar la clave y
`auth logout --json` para retirar la credencial local; la revocación remota es
una acción de Avileo.

No uses una versión anterior de la CLI como sustituto: su contrato de
credenciales y destino es distinto. Si el host aporta un checkout o wrapper
local compatible y verificado, consérvalo y confirma que el origen guardado
coincide con el seleccionado antes de acceder al negocio. No cambies de
despliegue ni reenvíes una clave ante un conflicto o una credencial sin origen.
Sin un cliente compatible, detente en la lectura de documentación: no solicites
vinculación ni credenciales.

## Evalúa el perfil y el catálogo

```sh
avileo business profile show --json
avileo catalog product list --limit 25 --offset 0 --json
```

El perfil devuelve campos, valores reales, faltantes y porcentaje de
completitud según el rubro. Para mejorarlo, prepara únicamente valores
confirmados, revisa primero el diff local y luego crea la propuesta:

```sh
avileo business profile update --from profile-update.json --json
avileo business profile update --from profile-update.json --apply --json
# Después de aprobar la propuesta en Avileo
avileo operation apply "$APPROVAL_ID" --json
```

Una evaluación puede recomendar cambios sin aplicarlos. No confundas una
recomendación con autorización.

## Read and mutate modes

A read key can inspect resources. A mutate key can create proposals, but every
effective write still requires approval in Avileo.

```sh
# Local preview
avileo catalog product update "$PRODUCT_ID" --from changes.json --json

# Create proposal; returns approvalUrl
avileo catalog product update "$PRODUCT_ID" --from changes.json --apply --json

Capture the complete JSON response and copy its literal `.data.approvalUrl`.
Never rebuild the link from the operation ID or replace its origin; local,
preview and production environments can advertise different app hosts.

# Execute only after approval
avileo catalog product update "$PRODUCT_ID" \
  --from changes.json --apply --approval-id "$APPROVAL_ID" --json
```

The same flow applies to products, variants, categories, tags, assets,
inventory and import apply. `catalog import preview` remains direct and safe.

## Operations

```sh
avileo operation status "$APPROVAL_ID" --json
avileo operation apply "$APPROVAL_ID" --json
```

## Create a Client Key for a web

```sh
avileo catalog-key create --name "Web del cliente" --json
# Approve the returned URL
avileo operation apply "$APPROVAL_ID" --json
```

The successful apply response returns the new public `avileo_pk_...` once. It
may be saved as `AVILEO_CLIENT_KEY` in the customer web project. Never save the
secret `AVILEO_AGENT_API_KEY` there.

For the underlying server-to-server contract, see [Agent HTTP API](/docs/agent-http).

## Output and redaction

Success uses stdout and failure uses stderr, each with one versioned JSON
envelope. Agent keys, API keys, authorization, tokens, passwords and secrets
are redacted. The only intentional exception is the one-shot public Client Key
returned by an approved create operation.

---

# Agent HTTP API

URL: https://avileo.theelena.me/docs/agent-http
Description: Server-to-server reads and human-approved mutations for Avileo agents.

# Agent HTTP API

The API base URL is `https://avileo.theelena.me`; agent routes live under
`/api/v1/agent`.

```http
x-avileo-agent-key: avileo_sk_...
```

The credential derives the business. Never send `businessId` and never expose
an Agent Key to a browser.

## Modes and capability

Agent access requires the effective `agentCatalogAccessEnabled` capability.
Keys are managed as `read` or `mutate`; route-level actions remain enforced
server-side. A mutate key may propose writes but cannot bypass human approval.

## Reads

```http
GET /api/v1/agent/business
GET /api/v1/agent/business/profile
GET /api/v1/agent/catalog/products
POST /api/v1/agent/catalog/assets/upload
```

## Propose an operation

```http
POST /api/v1/agent/operations
x-avileo-agent-key: avileo_sk_...
content-type: application/json

{
  "operationName": "catalog.products.update",
  "payload": {
    "productId": "...",
    "body": { "name": "Café reserva" }
  }
}
```

Avileo validates the allowlisted operation, generates the summary/diff and
returns an `approvalUrl`. The proposal expires after ten minutes.

An authorized staff user approves or rejects it through the protected Avileo
page. A direct HTTP consumer can poll:

```http
GET /api/v1/agent/operations/:approvalId
```

## Apply a catalog mutation

Use the original endpoint and exact payload with both UUID headers:

```http
PATCH /api/v1/agent/catalog/products/:productId
x-avileo-agent-key: avileo_sk_...
x-avileo-approval-id: <approval UUID>
idempotency-key: <operation UUID>
content-type: application/json

{ "name": "Café reserva" }
```

The approval is tenant-, credential-, operation- and payload-bound. Pending,
rejected, expired, mismatched or consumed approvals never execute. Finalized
idempotency replays return the stored result without executing again.

`POST /catalog/imports/preview` is approval-exempt. Import apply and all other
effective catalog writes require approval.

## Profile and Client Key operations

Special approved operations execute through:

```http
POST /api/v1/agent/operations/:approvalId/apply
```

Supported special operations include `business.profile.update` and
`catalog.client_keys.create`. Client Key creation returns the public
`avileo_pk_...` once; later status responses redact it.

## Conexión de dispositivo

El artefacto público de la CLI con selección explícita de origen está pendiente.
No se ofrece aquí un comando de instalación ni de conexión ejecutable y una
versión anterior no sustituye ese contrato.

Origen seleccionado: https://avileo.theelena.me. Un checkout o wrapper local solo puede
usarse si el host ya lo aporta como cliente compatible verificado y el despliegue
está habilitado. Antes de acceder al negocio, confirma que la credencial conserva
ese mismo origen; ante un conflicto o un origen ausente, detente sin reenviar
la clave.

La conexión requiere autorización explícita del usuario sobre el negocio y los
permisos. La Agent Key se entrega al cliente de confianza, nunca al chat.
No incluyas claves ni códigos de dispositivo en URLs, logs o prompts.

## Errors and retries

Responses use `{ success, data }` or `{ success:false, error }`. Common statuses
are 400 validation, 401 authentication, 403 permission/capability, 404 not
found, 409 state/payload conflict and 429 rate limit. Retry a mutation only with
the same idempotency key, approval ID and payload.