@roilab/crm-cli 0.24.0 → 0.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -6,6 +6,46 @@ Todos los cambios notables se documentan aquí. El formato sigue
6
6
 
7
7
  ## [Sin publicar]
8
8
 
9
+ ## [0.25.0] — 2026-11-17
10
+
11
+ ### Added
12
+
13
+ - **`crm guide list` y `crm guide get <slug>`.** Leen las guías de la
14
+ biblioteca de Guías (internas de Roilab y de clientes) con el mismo filtro
15
+ que el web: un member ve las internas, las de todos los clientes y las de
16
+ sus clientes. `get` devuelve el texto en markdown en `data.body` (la versión
17
+ publicada, o el borrador con `--draft`) y avisa con `hasUnpublishedChanges`
18
+ si el borrador difiere. Leer por aquí no marca la guía como leída. Scope
19
+ nuevo `guides:read`, solo staff.
20
+ - **`crm site stock`.** Stock real de la tienda, leído en el momento del
21
+ webservice (solo lectura): de una ficha, unidades totales y por combinación
22
+ y qué pasa al agotarse; de una categoría, sus fichas activas con su stock,
23
+ primero las agotadas (las que más venden arriba) y con ventas de 90 días, y
24
+ sus combinaciones: cuántas tiene cada ficha y cuántas están agotadas, con el
25
+ total de la categoría y las fichas con stock que tienen algún pack a cero.
26
+ `--agotados`, `--combinaciones-agotadas` (fichas con alguna combinación
27
+ agotada), `--combinaciones` (nombre y unidades de cada combinación) e
28
+ `--inactivos`. Solo en tiendas con el stock activado en su
29
+ conexión (growbaratochile.cl); en growbarato.net no es real. `crm site get`
30
+ de una ficha trae el total en `stock`.
31
+
32
+ ### Changed
33
+
34
+ - **Tiendas con URLs sin id** (growbaratochile.cl: `/fertilizantes/`,
35
+ `/boom-nutrients/candy-tripack.html`). `crm site get`, `update`, `sales` y
36
+ `stock` reconocen la ficha, categoría o CMS abriendo la página publicada; los
37
+ números del slug ya no se leen como id (`60-day-wonder.html` no es la ficha
38
+ 60). Si la URL redirige, se usa la página final y sale en `warnings`. En las
39
+ tiendas con id en la URL, una ruta que no se reconoce también se resuelve
40
+ así en vez de fallar.
41
+ - `crm site sales` da las cifras en la moneda de la tienda (`currency`).
42
+
43
+ ### Fixed
44
+
45
+ - `crm site get` y `update` en tiendas PrestaShop con un solo idioma
46
+ (growbaratochile.cl) fallaban con "Server Error": su webservice devuelve los
47
+ textos como texto y no por idioma. Arreglado en el servidor.
48
+
9
49
  ## [0.24.0] — 2026-11-13
10
50
 
11
51
  ### Fixed
package/README.md CHANGED
@@ -1,197 +1,197 @@
1
- # @roilab/crm-cli
2
-
3
- > CLI for humans and AI agents to drive the ROILab SEO+CRM platform.
4
-
5
- CLI para el SEO + CRM de ROILab, pensado tanto para humanos como para agentes de
6
- IA (Claude Code, Cursor, Windsurf). Envoltura JSON siempre, exit codes numéricos,
7
- escrituras idempotentes y login sin pegar API keys en texto plano (flujo de
8
- dispositivo tipo OAuth).
9
-
10
- ## Instalación
11
-
12
- ### Agentes (recomendado)
13
-
14
- Sin instalación previa, siempre la última versión:
15
-
16
- ```bash
17
- npx -y @roilab/crm-cli@latest <comando>
18
- ```
19
-
20
- ### Humanos
21
-
22
- Para dejar `crm` en el PATH:
23
-
24
- ```bash
25
- npm i -g @roilab/crm-cli
26
- crm --help
27
- ```
28
-
29
- Actualiza con:
30
-
31
- ```bash
32
- crm update # = npm i -g @roilab/crm-cli@latest; --check solo compara
33
- ```
34
-
35
- No hace falta acordarse: el propio CLI comprueba una vez al día si hay una
36
- versión nueva en npm y el servidor lo recuerda en cada respuesta, siempre por
37
- stderr. Cambiar webs (`crm site update`) exige una versión mínima: por debajo,
38
- el servidor pide `crm update`.
39
-
40
- ## Primer login (30 segundos)
41
-
42
- ```bash
43
- crm auth login --device-name mi-portatil
44
- # Abre la URL que aparece en el navegador, aprueba.
45
- crm auth whoami
46
- crm doctor
47
- ```
48
-
49
- El CLI guarda tokens rotativos en `~/.config/crm/credentials.json` (modo `0600`).
50
- Nunca se escribe una API key en claro en disco por esta vía.
51
-
52
- ## Comandos
53
-
54
- ```bash
55
- crm recall https://example.com/pricing
56
- crm task list --status todo --domain dom_xyz --limit 20
57
- crm task create --title "Arreglar H1 en /pricing" --domain dom_xyz --shadow
58
- crm task update tsk_abc --status done --completed-at 2026-10-28
59
- crm review approve task tsk_abc # aprueba una propuesta o quita la marca REVISAR
60
- crm comment create --task tsk_abc --body "Desplegado en prod" --kind agent_log
61
- crm domain metrics dom_xyz --start 2026-03-01 --end 2026-04-01 --markdown
62
- crm review list --mine
63
- ```
64
-
65
- `crm --help` imprime todos los sustantivos; `crm <noun> --help` imprime los
66
- verbos; la documentación completa vive en la app, pestaña **Documentación**, que
67
- se auto-genera desde el registro de endpoints — siempre refleja la versión
68
- servida.
69
-
70
- ## Cambiar la tienda y el blog (`crm site`)
71
-
72
- Con las credenciales guardadas en el CRM (ficha del dominio → Conexiones con la
73
- web) se leen y cambian el H1, el meta title, la meta description, el contenido,
74
- el noindex y el canonical de la tienda PrestaShop y del blog WordPress. La
75
- credencial no sale del servidor y cada cambio queda en el registro de cambios de
76
- su tarea.
77
-
78
- ```bash
79
- crm site list # webs que puedes usar
80
- crm site rules --url https://www.tienda.com/ # reglas de publicación (obligatorio antes de escribir)
81
- crm site get --url https://www.tienda.com/598-cbd # valores actuales
82
- crm site update --task tsk_abc --url https://www.tienda.com/598-cbd \
83
- --meta-title-file title.txt --meta-desc-file desc.txt --dry-run
84
- crm site update --task tsk_abc --url https://www.tienda.com/598-cbd \
85
- --meta-title-file title.txt --meta-desc-file desc.txt --note "por qué"
86
-
87
- # Indexación: noindex exige --allow-noindex y enseña los clics de la URL en Search Console
88
- crm site update --task tsk_abc --url https://www.tienda.com/520-vacia --noindex noindex --allow-noindex --dry-run
89
- crm site update --task tsk_abc --url https://www.tienda.com/77-dup.html --canonical https://www.tienda.com/76-buena.html --dry-run
90
- ```
91
-
92
- Noindex y canonical: en WordPress hace falta el mu-plugin `roilab-seo-rest` 1.1
93
- (Rank Math o Yoast); en PrestaShop, el módulo SEO de Roilab (rlseourls) con sus
94
- recursos del webservice. Poner una página en noindex exige `--allow-noindex` y
95
- la respuesta trae `searchConsole` con sus clics e impresiones de 90 días. El
96
- canonical tiene que ser del mismo dominio y apuntar a una página que responda
97
- 200 y se pueda indexar; si no, se bloquea.
98
-
99
- ### Ventas de la tienda (`crm site sales`)
100
-
101
- Para decidir con dinero real, no con el stock ni con Analytics. El CRM suma
102
- cada noche las ventas de las tiendas PrestaShop conectadas (pedidos válidos y
103
- no cancelados de la tienda e idioma de la conexión, sin IVA; nada de datos de
104
- clientes). La clave del webservice necesita permiso de lectura (GET) en
105
- `orders` y `order_details`.
106
-
107
- ```bash
108
- crm site sales --url https://www.tienda.com/598-cbd # categoría: 28 y 90 días, interanual, top 10 fichas
109
- crm site sales --ref product:5090 --connection <id> # ficha: y su puesto en la categoría
110
- crm site sales --top 50 --connection <id> # ranking de fichas por facturación de 90 días
111
- crm site sales --top 20 --category 598 --days 28 --connection <id>
112
- ```
113
-
114
- Una categoría suma todas las fichas asociadas a ella o a sus subcategorías,
115
- como las lista la tienda, no solo las que la tienen por defecto. El interanual compara con las mismas fechas de hace 52 semanas.
116
- La revisión de métricas de una tarea añade las ventas de sus fichas y
117
- categorías antes y después.
118
-
119
- Para comportamiento (sesiones, interacción, tiempo en página) está
120
- `crm ga4 query --dimensions pagePath`; para dinero, siempre la tienda.
121
-
122
- Norma de trabajo: ningún cambio se aplica sin el OK explícito de la persona que
123
- hace la tarea. El agente enseña el `--dry-run`, espera un "sí, publica", aplica y
124
- deja la decisión en un comentario de la tarea (`--kind decision`).
125
-
126
- `update` escribe solo lo que cambia, vuelve a leer la página para confirmar lo
127
- guardado, comprueba la página publicada y registra el cambio con el antes y el
128
- después reales. No escribe si no has leído en las últimas 24 horas la versión
129
- vigente de las reglas de la web (perfil del dominio, normas, skills y documentos),
130
- y bloquea lo que las incumple de forma medible.
131
-
132
- ## Seguimiento de URLs (`crm task tracking`)
133
-
134
- Cada cambio registrado mete su URL en el seguimiento de la tarea; al
135
- completarla, la revisión de métricas se programa sola (28 días por defecto) y
136
- mide esas URLs en Search Console. Para medir un grupo o el dominio entero:
137
-
138
- ```bash
139
- crm task tracking get tsk_abc
140
- crm task tracking set tsk_abc --pattern '\.html$' # todas las fichas
141
- crm task tracking set tsk_abc --domain
142
- ```
143
-
144
- ## Adjuntar archivos (`--file`)
145
-
146
- `task create` / `task update` / `comment create` / `chat send` / `chat reply`
147
- aceptan `--file <ruta>` (repetible). Es **un flag, no un subcomando** — no
148
- existe `crm task attach` ni `crm upload`. El CLI sube cada archivo a Convex
149
- storage en dos pasos y manda los `attachments[]` en la misma escritura.
150
-
151
- ```bash
152
- crm task create --title "Migración H1" --domain dom_xyz \
153
- --file ./brief.pdf --file ./screenshot.png
154
-
155
- crm comment create --task tsk_abc --kind decision \
156
- --body "Cerrado, ver diff" --file ./after.png
157
-
158
- crm chat send "$TID" --body "captura del 404" --file ./bug.png
159
- ```
160
-
161
- Reglas:
162
-
163
- - Máx **10 MB por archivo** (rechazo local antes de tocar la red).
164
- - Aviso en stderr desde **2 MB** (`[AVISO] ... la subida puede tardar.`).
165
- - En `task update` la lista de adjuntos es **REEMPLAZO**, no merge. Usa
166
- `--clear-files` para vaciar; pasa los antiguos junto con los nuevos si
167
- quieres conservarlos.
168
- - `--body` se vuelve opcional cuando hay `--file`.
169
-
170
- ## Flags globales
171
-
172
- Disponibles en cada comando:
173
-
174
- - `--json` — envoltura JSON completa (por defecto).
175
- - `--quiet` — solo `data`.
176
- - `--ids-only` — un id por línea.
177
- - `--count` — un único entero.
178
- - `--markdown` — resumen legible (no es JSON).
179
- - `--jq <expr>` — jq mini (`.a`, `.a.b`, `.a[]`, `.a[].b`).
180
- - `--shadow` — fuerza que la escritura aterrice como propuesta pendiente de
181
- revisión humana.
182
- - `--wait-for-approval --timeout 30m` — bloquea hasta que un humano decida.
183
- - `--idempotency-key <key>` — idempotency key estable (automática en escrituras).
184
-
185
- ## Seguridad
186
-
187
- - Sin scripts `preinstall` / `postinstall` / `install` — nada que se ejecute al
188
- instalar el paquete.
189
- - Auth por flujo de dispositivo: no se comparten secretos entre máquinas; el
190
- access token caduca en 1 h y el refresh token rota en cada uso.
191
- - Archivo de credenciales con permisos `0600`, aislado por perfil.
192
- - Publicación con atestación de procedencia (`npm publish --provenance`) para
193
- que se pueda verificar el origen del tarball.
194
-
195
- ## Licencia
196
-
197
- MIT — ver [LICENSE](./LICENSE).
1
+ # @roilab/crm-cli
2
+
3
+ > CLI for humans and AI agents to drive the ROILab SEO+CRM platform.
4
+
5
+ CLI para el SEO + CRM de ROILab, pensado tanto para humanos como para agentes de
6
+ IA (Claude Code, Cursor, Windsurf). Envoltura JSON siempre, exit codes numéricos,
7
+ escrituras idempotentes y login sin pegar API keys en texto plano (flujo de
8
+ dispositivo tipo OAuth).
9
+
10
+ ## Instalación
11
+
12
+ ### Agentes (recomendado)
13
+
14
+ Sin instalación previa, siempre la última versión:
15
+
16
+ ```bash
17
+ npx -y @roilab/crm-cli@latest <comando>
18
+ ```
19
+
20
+ ### Humanos
21
+
22
+ Para dejar `crm` en el PATH:
23
+
24
+ ```bash
25
+ npm i -g @roilab/crm-cli
26
+ crm --help
27
+ ```
28
+
29
+ Actualiza con:
30
+
31
+ ```bash
32
+ crm update # = npm i -g @roilab/crm-cli@latest; --check solo compara
33
+ ```
34
+
35
+ No hace falta acordarse: el propio CLI comprueba una vez al día si hay una
36
+ versión nueva en npm y el servidor lo recuerda en cada respuesta, siempre por
37
+ stderr. Cambiar webs (`crm site update`) exige una versión mínima: por debajo,
38
+ el servidor pide `crm update`.
39
+
40
+ ## Primer login (30 segundos)
41
+
42
+ ```bash
43
+ crm auth login --device-name mi-portatil
44
+ # Abre la URL que aparece en el navegador, aprueba.
45
+ crm auth whoami
46
+ crm doctor
47
+ ```
48
+
49
+ El CLI guarda tokens rotativos en `~/.config/crm/credentials.json` (modo `0600`).
50
+ Nunca se escribe una API key en claro en disco por esta vía.
51
+
52
+ ## Comandos
53
+
54
+ ```bash
55
+ crm recall https://example.com/pricing
56
+ crm task list --status todo --domain dom_xyz --limit 20
57
+ crm task create --title "Arreglar H1 en /pricing" --domain dom_xyz --shadow
58
+ crm task update tsk_abc --status done --completed-at 2026-10-28
59
+ crm review approve task tsk_abc # aprueba una propuesta o quita la marca REVISAR
60
+ crm comment create --task tsk_abc --body "Desplegado en prod" --kind agent_log
61
+ crm domain metrics dom_xyz --start 2026-03-01 --end 2026-04-01 --markdown
62
+ crm review list --mine
63
+ ```
64
+
65
+ `crm --help` imprime todos los sustantivos; `crm <noun> --help` imprime los
66
+ verbos; la documentación completa vive en la app, pestaña **Documentación**, que
67
+ se auto-genera desde el registro de endpoints — siempre refleja la versión
68
+ servida.
69
+
70
+ ## Cambiar la tienda y el blog (`crm site`)
71
+
72
+ Con las credenciales guardadas en el CRM (ficha del dominio → Conexiones con la
73
+ web) se leen y cambian el H1, el meta title, la meta description, el contenido,
74
+ el noindex y el canonical de la tienda PrestaShop y del blog WordPress. La
75
+ credencial no sale del servidor y cada cambio queda en el registro de cambios de
76
+ su tarea.
77
+
78
+ ```bash
79
+ crm site list # webs que puedes usar
80
+ crm site rules --url https://www.tienda.com/ # reglas de publicación (obligatorio antes de escribir)
81
+ crm site get --url https://www.tienda.com/598-cbd # valores actuales
82
+ crm site update --task tsk_abc --url https://www.tienda.com/598-cbd \
83
+ --meta-title-file title.txt --meta-desc-file desc.txt --dry-run
84
+ crm site update --task tsk_abc --url https://www.tienda.com/598-cbd \
85
+ --meta-title-file title.txt --meta-desc-file desc.txt --note "por qué"
86
+
87
+ # Indexación: noindex exige --allow-noindex y enseña los clics de la URL en Search Console
88
+ crm site update --task tsk_abc --url https://www.tienda.com/520-vacia --noindex noindex --allow-noindex --dry-run
89
+ crm site update --task tsk_abc --url https://www.tienda.com/77-dup.html --canonical https://www.tienda.com/76-buena.html --dry-run
90
+ ```
91
+
92
+ Noindex y canonical: en WordPress hace falta el mu-plugin `roilab-seo-rest` 1.1
93
+ (Rank Math o Yoast); en PrestaShop, el módulo SEO de Roilab (rlseourls) con sus
94
+ recursos del webservice. Poner una página en noindex exige `--allow-noindex` y
95
+ la respuesta trae `searchConsole` con sus clics e impresiones de 90 días. El
96
+ canonical tiene que ser del mismo dominio y apuntar a una página que responda
97
+ 200 y se pueda indexar; si no, se bloquea.
98
+
99
+ ### Ventas de la tienda (`crm site sales`)
100
+
101
+ Para decidir con dinero real, no con Analytics. El CRM suma
102
+ cada noche las ventas de las tiendas PrestaShop conectadas (pedidos válidos y
103
+ no cancelados de la tienda e idioma de la conexión, sin IVA; nada de datos de
104
+ clientes). La clave del webservice necesita permiso de lectura (GET) en
105
+ `orders` y `order_details`.
106
+
107
+ ```bash
108
+ crm site sales --url https://www.tienda.com/598-cbd # categoría: 28 y 90 días, interanual, top 10 fichas
109
+ crm site sales --ref product:5090 --connection <id> # ficha: y su puesto en la categoría
110
+ crm site sales --top 50 --connection <id> # ranking de fichas por facturación de 90 días
111
+ crm site sales --top 20 --category 598 --days 28 --connection <id>
112
+ ```
113
+
114
+ Una categoría suma todas las fichas asociadas a ella o a sus subcategorías,
115
+ como las lista la tienda, no solo las que la tienen por defecto. El interanual compara con las mismas fechas de hace 52 semanas.
116
+ La revisión de métricas de una tarea añade las ventas de sus fichas y
117
+ categorías antes y después.
118
+
119
+ Para comportamiento (sesiones, interacción, tiempo en página) está
120
+ `crm ga4 query --dimensions pagePath`; para dinero, siempre la tienda.
121
+
122
+ Norma de trabajo: ningún cambio se aplica sin el OK explícito de la persona que
123
+ hace la tarea. El agente enseña el `--dry-run`, espera un "sí, publica", aplica y
124
+ deja la decisión en un comentario de la tarea (`--kind decision`).
125
+
126
+ `update` escribe solo lo que cambia, vuelve a leer la página para confirmar lo
127
+ guardado, comprueba la página publicada y registra el cambio con el antes y el
128
+ después reales. No escribe si no has leído en las últimas 24 horas la versión
129
+ vigente de las reglas de la web (perfil del dominio, normas, skills y documentos),
130
+ y bloquea lo que las incumple de forma medible.
131
+
132
+ ## Seguimiento de URLs (`crm task tracking`)
133
+
134
+ Cada cambio registrado mete su URL en el seguimiento de la tarea; al
135
+ completarla, la revisión de métricas se programa sola (28 días por defecto) y
136
+ mide esas URLs en Search Console. Para medir un grupo o el dominio entero:
137
+
138
+ ```bash
139
+ crm task tracking get tsk_abc
140
+ crm task tracking set tsk_abc --pattern '\.html$' # todas las fichas
141
+ crm task tracking set tsk_abc --domain
142
+ ```
143
+
144
+ ## Adjuntar archivos (`--file`)
145
+
146
+ `task create` / `task update` / `comment create` / `chat send` / `chat reply`
147
+ aceptan `--file <ruta>` (repetible). Es **un flag, no un subcomando** — no
148
+ existe `crm task attach` ni `crm upload`. El CLI sube cada archivo a Convex
149
+ storage en dos pasos y manda los `attachments[]` en la misma escritura.
150
+
151
+ ```bash
152
+ crm task create --title "Migración H1" --domain dom_xyz \
153
+ --file ./brief.pdf --file ./screenshot.png
154
+
155
+ crm comment create --task tsk_abc --kind decision \
156
+ --body "Cerrado, ver diff" --file ./after.png
157
+
158
+ crm chat send "$TID" --body "captura del 404" --file ./bug.png
159
+ ```
160
+
161
+ Reglas:
162
+
163
+ - Máx **10 MB por archivo** (rechazo local antes de tocar la red).
164
+ - Aviso en stderr desde **2 MB** (`[AVISO] ... la subida puede tardar.`).
165
+ - En `task update` la lista de adjuntos es **REEMPLAZO**, no merge. Usa
166
+ `--clear-files` para vaciar; pasa los antiguos junto con los nuevos si
167
+ quieres conservarlos.
168
+ - `--body` se vuelve opcional cuando hay `--file`.
169
+
170
+ ## Flags globales
171
+
172
+ Disponibles en cada comando:
173
+
174
+ - `--json` — envoltura JSON completa (por defecto).
175
+ - `--quiet` — solo `data`.
176
+ - `--ids-only` — un id por línea.
177
+ - `--count` — un único entero.
178
+ - `--markdown` — resumen legible (no es JSON).
179
+ - `--jq <expr>` — jq mini (`.a`, `.a.b`, `.a[]`, `.a[].b`).
180
+ - `--shadow` — fuerza que la escritura aterrice como propuesta pendiente de
181
+ revisión humana.
182
+ - `--wait-for-approval --timeout 30m` — bloquea hasta que un humano decida.
183
+ - `--idempotency-key <key>` — idempotency key estable (automática en escrituras).
184
+
185
+ ## Seguridad
186
+
187
+ - Sin scripts `preinstall` / `postinstall` / `install` — nada que se ejecute al
188
+ instalar el paquete.
189
+ - Auth por flujo de dispositivo: no se comparten secretos entre máquinas; el
190
+ access token caduca en 1 h y el refresh token rota en cada uso.
191
+ - Archivo de credenciales con permisos `0600`, aislado por perfil.
192
+ - Publicación con atestación de procedencia (`npm publish --provenance`) para
193
+ que se pueda verificar el origen del tarball.
194
+
195
+ ## Licencia
196
+
197
+ MIT — ver [LICENSE](./LICENSE).
package/SKILL.md CHANGED
@@ -232,7 +232,7 @@ Reglas:
232
232
  - **Cuándo NO usar noindex:** para arreglar una canibalización (se arregla con contenido y enlaces), en una página con clics que la tarea no dice expresamente que hay que quitar, ni "por si acaso". Sí: páginas vacías, duplicadas o de servicio que no deben salir, y siempre porque lo pide la tarea.
233
233
  - **Canonical:** URL absoluta del mismo dominio que responda 200 sin redirigir y no tenga noindex; si no, se bloquea. Un canonical a la propia página equivale al automático. No mezcles noindex y canonical a otra URL en la misma página (se avisa).
234
234
  - Volver a `index` o `default` no pide permiso: la página tarda en volver a Google; puedes pedir la indexación en Search Console.
235
- - **Fuera de alcance:** cambiar la URL/slug, precios, stock, borrar. Eso va por tarea a quien corresponda. Las redirecciones 301 del blog sí se hacen desde aquí (abajo).
235
+ - **Fuera de alcance:** cambiar la URL/slug, precios, stock (se puede leer, no cambiar), borrar. Eso va por tarea a quien corresponda. Las redirecciones 301 del blog sí se hacen desde aquí (abajo).
236
236
 
237
237
  #### Redirecciones 301 del blog (`crm site redirect`)
238
238
 
@@ -265,6 +265,7 @@ Antes de proponer un cambio, mira qué dicen los datos de esa página. Tres fuen
265
265
  |---|---|---|
266
266
  | ¿Por qué búsquedas sale esta página y en qué posición? ¿Qué página gana una keyword? | Search Console | `crm gsc query --property <id> --dimension query --filters "page equals <url>; country equals esp; device equals mobile"` (y `--dimension page --filters "query equals <kw>; …"`) |
267
267
  | ¿Cuánto vende esta ficha o categoría? ¿Qué fichas facturan más? | Ventas de la tienda | `crm site sales --url <url>` · `crm site sales --top 50 [--category <id>] --connection <id>` |
268
+ | ¿Hay stock de esta ficha? ¿Qué fichas de esta categoría están agotadas? ¿Qué packs faltan? (solo tiendas con stock real) | Stock de la tienda | `crm site stock --url <url>` · `crm site stock --url <categoría> --agotados` · `crm site stock --url <categoría> --combinaciones-agotadas --combinaciones` |
268
269
  | ¿Cómo se comporta la gente en la página (sesiones, interacción, tiempo)? | Analytics (GA4) | `crm ga4 query --property <id> --dimensions pagePath --metrics sessions,engagementRate,averageSessionDuration,userEngagementDuration,screenPageViews,bounceRate --filters "pagePath equals /ruta/"` |
269
270
 
270
271
  **Ventas (`crm site sales`).** Las suma el CRM cada noche desde el webservice de la tienda, sin datos de clientes:
@@ -272,10 +273,18 @@ Antes de proponer un cambio, mira qué dicen los datos de esa página. Tres fuen
272
273
  - De una ficha: 28 y 90 días (hasta ayer) con su interanual (mismas fechas de hace 52 semanas) y su puesto por facturación dentro de su categoría por defecto. De una categoría: la suma de todas las fichas asociadas a ella o a sus subcategorías, como las lista la tienda (no solo las que la tienen por defecto; cada ficha cuenta una vez), y sus 10 fichas que más facturan. `crm site get` de una ficha o categoría ya trae el resumen de 90 días en `sales`.
273
274
  - En sumas de varias fichas, `orders` cuenta pedidos por ficha; la facturación y las unidades son exactas.
274
275
  - Si `previousYear.complete` es `false`, la tienda no tiene cargado el año pasado entero para esa ventana y el interanual sale `null`: no lo calcules a mano con datos a medias.
275
- - **Nunca decidas con el stock** (en algunas tiendas no es real) ni con la facturación de Analytics. Para dinero, la tienda.
276
+ - **Nunca decidas con la facturación de Analytics.** Para dinero, la tienda.
276
277
  - Úsalas para priorizar (qué fichas o categorías trabajar primero), para elegir el destino de un enlace cuando dos páginas compiten y para medir: la revisión de métricas de la tarea añade las ventas de sus fichas y categorías antes y después, con el interanual.
277
278
  - Si `available: false`, la tienda no da permiso de lectura de pedidos o aún no se han cargado: dilo en la tarea y sigue con Search Console.
278
279
 
280
+ **Stock (`crm site stock`).** Solo en tiendas donde el stock es real y su conexión lo tiene activado (growbaratochile.cl). En growbarato.net no lo es: el comando lo dice y no devuelve nada. Se lee en el momento, no se guarda:
281
+ - De una ficha: unidades totales, unidades por combinación (formato, tamaño, pack de semillas…), `combinationCounts` (cuántas combinaciones y cuántas agotadas) y `outOfStock.policy` (`deny`: agotada no se puede comprar; `allow`: se puede comprar sin stock; `default`: lo de la tienda). `crm site get` de una ficha ya trae el total en `stock`.
282
+ - De una categoría: sus fichas activas con su stock total y `combinations` (total, con stock y agotadas), primero las agotadas (las que más venden arriba, con las ventas de 90 días si están cargadas) y luego de menos a más stock. El resumen cuenta las combinaciones de la categoría, las agotadas y las fichas que tienen stock pero algún pack a cero.
283
+ - Filtros de categoría: `--agotados` deja solo las fichas sin stock; `--combinaciones-agotadas`, las que tienen alguna combinación agotada (incluidas las agotadas del todo); `--combinaciones` añade a cada ficha sus combinaciones con nombre y unidades; `--inactivos` añade las desactivadas.
284
+ - **Una ficha con stock puede tener packs agotados** (en semillas es lo normal): si la acción empuja un formato concreto, mira sus combinaciones, no solo el total.
285
+ - **Mira el stock antes de proponer una acción sobre una ficha o categoría** (enlazarla, destacarla, optimizarla, empujarla en un post): una ficha agotada no es buen destino. Si la ficha clave de la tarea está agotada, dilo en la tarea antes de seguir.
286
+ - Solo lectura: cambiar el stock no es cosa del CRM.
287
+
279
288
  **Analytics (`crm ga4 query`).** Para comportamiento, no para dinero:
280
289
  - Sirve para ver si una página con tráfico engancha (tasa de interacción, tiempo de interacción, páginas vistas) y comparar antes y después de un cambio de contenido.
281
290
  - Páginas con muchas sesiones y poca interacción son candidatas a mejorar el contenido o la intención; páginas con buena interacción y pocas sesiones, a mejorar el title o el enlazado.
@@ -667,6 +676,11 @@ crm skill push my-playbook --note "primera revisión" --publish # body+frontma
667
676
  crm skill archive my-playbook # hide from library
668
677
  crm skill restore my-playbook # un-archive
669
678
 
679
+ # Work guides — the /dashboard/guias library (Roilab internal + per client). Read-only, staff only
680
+ crm guide list --q traductor --quiet # search title, summary and body
681
+ crm guide list --area contenido # by library area (partial match)
682
+ crm guide get <slug> --jq .data.body # published markdown; --draft for the draft
683
+
670
684
  # Chat — read threads, post messages, react, attach files (max 10 MB each)
671
685
  crm chat list --scope client --client cli_abc
672
686
  crm chat get <threadId> --message-limit 50 # metadata + recent msgs