Communitygithub.com

d1-cli — Tiendas D1 depuis la ligne de commande

Interrogez Tiendas D1 (Colombie, d1.com.co) depuis le terminal : catalogue, magasin le plus proche, panier, devis et livraison. Exploite l'API publique de VTEX IO sans clé admin.

Qu'est-ce que d1-cli — Tiendas D1 depuis la ligne de commande ?

d1-cli est un outil en ligne de commande pour interagir avec Tiendas D1, la plus grande chaîne de hard-discount colombienne, en pilotant directement l'API publique de sa plateforme VTEX IO (compte `d1tiendas`). Il permet de rechercher des produits avec filtres par rayon et tri par prix unitaire, d'obtenir le devis d'un panier sans le créer, et de construire un panier réel avant de remettre une URL de paiement à un humain — le paiement n'est jamais effectué par la CLI. L'outil gère deux pièges majeurs : la disponibilité régionalisée (un catalogue national donne des résultats non achetable ; il faut d'abord définir une région via `d1 region`) et les prix en deux unités (la recherche affiche des pesos entiers, le checkout des centièmes, un facteur 100x). Il permet aussi de substituer un produit en rupture, de consulter l'historique des commandes (via code unique envoyé par email), et expose des codes de sortie contractuels (0, 1, 2, 3) pour une intégration fiable dans des agents. Le code est écrit en TypeScript (Bun) et inclut des tests unitaires pour la normalisation des prix, la géolocalisation, la rédaction des commandes et la liste blanche des endpoints.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/broomva/skills/tree/HEAD/skills/commerce/d1-cli

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait d1-cli — Tiendas D1 depuis la ligne de commande ?

D1 est la plus grande chaîne de hard-discount colombienne. Sa vitrine fonctionne sur VTEX IO (compte d1tiendas), ce qui signifie que l'API publique du site est la surface d'intégration — ni scraping, ni identifiants admin.

Invocation

cd skills/commerce/d1-cli

# 1. Définissez d'abord votre point de livraison — tout le reste en dépend
bun run src/cli.ts region --lat 4.6486 --lng=-74.0628

# 2. Ensuite, recherchez : les prix et le stock sont ceux de votre magasin, pas du pays
bun run src/cli.ts search leche entera --count 5
bun run src/cli.ts search --facets category-1/lacteos-y-huevos --sort price:asc

# 3. Devis d'un panier sans toucher à votre chariot
bun run src/cli.ts quote 262:2 892:1

# 3b. Ou laissez un budget décider — termes, pas SKU
bun run src/cli.ts basket --budget 30000 arroz leche aceite huevos

# 4. Ou construisez un vrai panier, puis confiez le paiement à un humain
bun run src/cli.ts cart add 262 --qty 2
bun run src/cli.ts cart deliver-to
bun run src/cli.ts cart checkout      # affiche une URL ; ne paie pas

Ajoutez --json à n'importe quelle commande pour une sortie lisible par agent. Les codes de sortie sont un contrat, et cette liste est la seule copie :

codesignificationréessayer ?
0ça a fonctionné—
1D1 a refusé ou était injoignable — point non livrable, SKU indisponible ou inconnu, panneoui, peut aider
2la commande a été mal invoquéene sert jamais à rien
3ça a fonctionné et la réponse est « vide » (substitute, basket)ne sert jamais à rien

Un agent qui ne peut pas faire la différence entre ces codes réessaiera une faute de frappe pour toujours ou abandonnera sur une panne temporaire. 3 existe car une catégorie vide n'est ni l'un ni l'autre.

Notez que cart add fixe la ligne à --qty ; il n'ajoute pas. C'est la sémantique de D1, vérifiée en direct.

Les deux choses qui rendent naïve l'automatisation de D1 erronée

La disponibilité est régionalisée. Interrogez le catalogue sans région et D1 répond depuis le catalogue national, signalant un confortable 10 000 unités pour le vendeur fictif 1. Passez le même SKU dans une simulation de commande pour une adresse réelle et il revient withoutStock, car le magasin physique qui le livrerait ne l'a pas en stock. Toujours d1 region d'abord ; la CLI prévient en texte clair chaque fois qu'elle affiche les prix nationaux.

Définir une région est aussi la partie la moins intuitive de l'API : les coordonnées s'envoient en geoCoordinates={lon};{lat} — séparé par un point-virgule, longitude en premier. Une virgule, ce que les propres corps JSON de VTEX utilisent pour la même paire, est rejetée par CHK0119 (« les adresses doivent avoir un code postal ou des géocoordonnées ») — un message qui donne l'impression que le paramètre manque plutôt qu'il n'est mal formé. test/region.test.ts verrouille ce comportement pour qu'un nettoyage ne puisse pas le défaire.

Les prix arrivent dans deux unités. Pour SKU 262 (Leche Entera Latti 900 ml, COP 3 500 en rayon) :

APIChampValeurUnité
intelligent-searchPrice3500pesos entiers
catalog_systemPrice3500.0pesos entiers
checkout orderFormsellingPrice350000centièmes

Aucun ne libelle son unité. catalog.ts normalise tout en centièmes à la frontière pour que le reste du code ait exactement une unité, et un test vérifie qu'un prix issu de la recherche s'affiche identique à un prix issu du checkout.

Ce qu'il ne fera pas

d1 construit et tarife des paniers. Il ne paie pas. d1 cart checkout affiche l'URL où un humain examine le total et finalise le paiement.

Cette limite est vérifiée à deux endroits à partir d'une seule liste (src/endpoints.ts) : à l'exécution, D1Client.request refuse toute requête dont l'URL résolue n'est pas l'origine de D1 plus un des 18 chemins approuvés avant que la requête ne quitte le processus ; statiquement, test/safety.test.ts échoue si un littéral /api/ sous src/ n'est pas approuvé. Ajouter un endpoint — paiement ou autre — échoue tant qu'il n'est pas listé, donc la décision est prise plutôt que prise par défaut.

La partie à l'exécution est critique et a été ajoutée après qu'une revue a montré qu'une analyse statique seule ne suffit pas : --facets '../../../..' résolvait hors de l'endpoint de recherche vers le règlement des commandes alors que tous les littéraux source restaient approuvés.

Dit précisément, car les versions précédentes de ce fichier exagéraient : rien ici n'empêche un contributeur ayant un accès en écriture de modifier la liste blanche. Aucun test dans le dépôt ne le peut.

Le seul identifiant qu'il stocke est un token de session de la boutique — la même chose qu'un navigateur connecté possède, limité aux propres commandes et panier de son propriétaire — écrit dans ~/.config/d1-cli/session.json avec le mode 0600. Aucune appKey/appToken admin VTEX n'est lue nulle part. La connexion se fait par code unique envoyé par email ; l'authentification par mot de passe n'est intentionnellement pas implémentée.

La porte de sortie du checkout — terminez toujours ici

Terminez chaque panier par d1 cart checkout et agissez sur son code de sortie. Pas comme une formalité : c'est la seule commande qui revérifie tout le panier auprès de D1 tel qu'il est maintenant, et les paniers deviennent obsolètes d'une manière qu'aucune autre commande ne révèle.

0  chaque ligne est livrable — l'URL peut être remise en toute sécurité
1  au moins une ligne NE PEUT PAS être livrée ; l'URL est imprimée mais le panier est cassé
2  la commande a été mal invoquée

Ceci existe parce que chacun de ces cas est arrivé sur un vrai panier :

  • Une ligne s'est vendue pendant la nuit. PAN ARTESANAL INTEGRAL est devenu no tiene inventario des heures après avoir été ajouté. Le panier s'affichait toujours, avait toujours un total — un total qui était silencieusement inférieur de 6.490 COP, car la ligne morte avait disparu.
  • Un changement d'adresse a bloqué chaque ligne. Neuf articles sont revenus cannotBeDelivered alors que chacun portait encore un SLA valide et que le panier affichait toujours un total payable.
  • La livraison a été sous-estimée de 12 fois par une allocation par ligne qui ressemblait à un total.

Dans les trois cas, le panier semblait correct. Un devis pris plus tôt dans une session n'est pas une preuve sur le panier actuel, donc ne remettez jamais une URL de checkout que vous avez obtenue avant la dernière mutation — relancez la porte.

Quand elle retourne 1, --json donne undeliverable[] nommant les lignes, et readyToCheckout: false. Supprimez ou remplacez ces lignes et relancez.

Remplacer une ligne que D1 ne peut pas fournir

d1 substitute 192 --limit 5        # classe les produits en stock de la même catégorie

Le code 0 signifie qu'il y a quelque chose à proposer ; 3 signifie qu'il n'y a rien — une des deux commandes qui utilisent 3, aux côtés de d1 basket.

Trois, pas un, et la distinction est le point : 1 signifie « D1 a refusé, ou n'a pas pu être joint » partout ailleurs dans cette CLI, et invite à réessayer. Une catégorie vide ne devient jamais non vide en réessayant, donc un agent avec une politique de réessai sur 1 bouclerait indéfiniment. Le code 0 avec une liste vide est l'autre mauvaise réponse — il se lit comme un succès et déclenche une action.

Chaque candidat nomme ce qui change : marque, taille d'emballage, $/kg ou $/L, prix de l'emballage, et tout avertissement Ley 2120 gagné ou perdu. C'est la sortie, pas le score. Un -12% par litre pour les mêmes 900 ml et la même étiquette est une proposition différente de celle qui arrive avec Exceso en Azúcares attaché, et seuls les écarts les distinguent.

Proposez-le ; ne l'acceptez pas. substitute n'écrit jamais — il imprime la commande d1 cart add pour approbation humaine. Ce n'est pas de la prudence gratuite : le client a préféré à deux fois supprimer une ligne plutôt qu'un mauvais substitut, l'a dit explicitement, et avait raison les deux fois. Présentez les candidats et les compromis ; laissez la personne décider, et soyez prêt à supprimer la ligne.

Trois choses qu'il vous dira qui valent la peine d'être lues :

  • « Ce produit est encore en stock dans votre magasin. » La disponibilité est par magasin, donc une ligne qui a échoué ailleurs peut être acceptable ici. Vérifiez avant de remplacer quoi que ce soit. Sans --lat/--lng, il le dit plutôt que de deviner — il n'y a pas de magasin pour lequel faire une déclaration par magasin.
  • « élargi au niveau 2 sur 3 » — la catégorie feuille n'avait rien en stock, donc les suggestions viennent d'un rayon plus large et sont donc moins pertinentes.
  • « seuls N ont été comparés » — la catégorie est plus grande qu'une page. Augmentez --count. Ceci s'affiche aussi sur le résultat vide, car « rien ici n'est en stock » affirmé sur un balayage partiel a encore plus besoin de cette nuance.

Trouver des trucs quand la demande est vague

Pour « il nous faut du riz » plutôt que « acheter SKU 1092 », deux axes comptent et aucun n'est le défaut :

Classez par prix unitaire, pas par prix d'emballage. --sort per-unit utilise les données PUM que la loi colombienne oblige D1 à publier. Les deux classements divergent véritablement : ARROZ ESTÁNDAR 500 GRS est l'emballage le moins cher à 1 550 $ et coûte 3 100 $/kg, tandis que la meilleure valeur dans les mêmes résultats est à 2 775 $/kg — dans un sac de 5 550 $ qui n'apparaît nulle part dans le top cinq des prix d'emballage. Classer par prix d'emballage donne une mauvaise réponse tout en ayant l'air correct.

Comme la recherche de D1 ne peut pas trier sur ce critère, --sort per-unit ordonne la page que vous avez récupérée, pas l'ensemble des résultats. Augmentez --count (max 50) pour l'élargir. La sortie le dit plutôt que d'impliquer un superlatif qu'elle ne peut pas soutenir, et nomme combien de résultats ne publient pas de taille et ne peuvent donc pas être comparés du tout.

La taille déclarée d'un multipack est celle de l'emballage, pas d'un article — ne la « corrigez » pas. Un recensement de tous les 1 600 produits a trouvé que parmi les multipacks identifiables par nom, 44 des 46 où D1 en dit assez pour décider déclarent le total de l'emballage. Analyser N UN dans un nom de produit et multiplier corromprait ces 44 pour en corriger 2. Le nombre dans un nom n'est pas une preuve de ce que signifie le PUM.

resolvePackSize lit donc les descriptions plutôt que les noms. Sur les 1 548 produits portant un PUM, il agit sur les 10 dont la description indique à la fois une taille par article et un nombre : trois sont corrigés (SKU 718, 510, 1008), sept sont confirmés comme indiquant déjà l'emballage, et tout le reste reste tel que déclaré.

Lisez les étiquettes d'avertissement. Les produits portent les avertissements colombiens sur le devant de l'emballage (Exceso en Azúcares, Exceso en sodio, Exceso en grasas saturadas, Exceso en grasas trans, Contiene Edulcorantes) dans warnings[] avec --json. La couverture est partielle — environ 70–90 % par catégorie — donc l'absence signifie « non déclaré », jamais « sûr ».

Ensuite, affinez avec d1 facets <query> (catégorie, marque, sous-catégorie avec décomptes) avant de paginer : la recherche est limitée à 50 pages, donc une requête large est mieux réduite par facette que parcourue.

Commandes

CommandeCe qu'elle fait
region --lat --lngrésoudre et mémoriser le point de livraison
search <query>trouver des produits (--facets --sort --count --page --available)
suggest <partial> · trendingautocomplétion · ce que la Colombie recherche
categories · facets [query]arbre des rayons · filtres pour une requête
substitute <sku>quoi acheter à la place, et ce qui change (--limit --count)
quote <sku>[:qty]...tarifer un panier, sans modifier le chariot
`cart [showadd
login --email / --from-cookie · whoami · logoutcompte
orders · order <id>historique des commandes (les détails sont réduits à une liste blanche ; --raw opte pour le brut)
stores nearmagasins D1 près d'un point — emplacements seulement, D1 ne propose pas de retrait

Tests

bun test        # unités monétaires, le piège du point-virgule, la quantité dans le devis,
                # vacuité SKU inconnu, normalisation du panier, rédaction des commandes, et
                # la liste blanche des endpoints qui limite la surface de paiement
bun run lint && bun run typecheck

Les codes de sortie sont un contrat, pas une décoration — le tableau sous Invocation ci-dessus est la seule copie.

Voir README.md pour la carte complète des endpoints, le comportement des niveaux de livraison, et ce que l'API publique ne vous donnera pas.

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

broomva/skills

Local TTS, voice cloning, voice design, and video dubbing via the OmniVoice Studio MCP server (open-source ElevenLabs alternative; nothing leaves the machine, runs on MPS/CUDA/CPU). Use when: (1) generating speech from text in any of 646 languages, (2) cloning a voice from a 3-second reference clip, (3) designing a voice by gender/age/accent/pitch/style, (4) dubbing a video into another language, (5) listing voice profiles or personality presets, (6) producing narration where privacy, cost, or absent API keys matter, (7) non-English narration where Edge TTS/kokoro fall short, (8) batch audio for blog posts or content pipelines. Triggers: 'omnivoice', 'voice clone', 'clone this voice', 'tts', 'narrate', 'generate speech', 'voice synthesis', 'dub video', 'voice design', 'local tts', 'multilingual voice', 'narrate this post', 'elevenlabs alternative'.

broomva/skills

>- Speak an explanation out loud while working in any project — tiered text-to-speech with a pluggable backend (ElevenLabs by default and quota-guarded, macOS `say` via `--fast` for free instant local speech, local OmniVoice as an unlimited private tier). Markdown-aware, so code fences, URLs and deep paths collapse to short spoken placeholders instead of being dictated character by character, while snake_case identifiers survive intact so the listener can still search for them. Every utterance is saved to disk for later replay. Also carries a **talk mode** toggle: turn it on and the agent speaks a full readback of every turn, for as long as that session lasts — the whole response, not a summary of it, with `brief` and `marker` levels for when you want less. Talk mode is off by default and scoped to the single session that enabled it, so parallel agents in other worktrees stay silent. Use when the user asks to hear something rather than read it — an explanation of a change, a walkthrough of what just happen...

broomva/skills

Stateful, local-first household toxics inventory + swap engine. Identify the items in a home that carry endocrine disruptors and persistent chemicals (BPA/BPS, phthalates, PFAS/PTFE, parabens, flame retardants, VOCs, microplastics), score each by *real* exposure (severity x presence x how it's used x condition), and track the swap to a safer alternative from "flagged" -> "sourced" -> "swapped". Ships a grounded, cited knowledge graph of ~20 hazards, ~40 item-classes, and ~40 alternatives. Hands sourcing off to the `procurer` skill. The skill's state is the source of truth — the agent is the app.

broomva/skills

Tekton — the shared architecture-intent substrate for co-designing systems with the agent. One typed graph across six tiers (system / journey / data / infra / decisions / qualities); views are queries, not separate diagrams. The canonical artifact is a diff-friendly YAML model both human and agent read and write; it renders to Mermaid (agent-legible, GitHub-native) and a self-contained tabbed HTML viewer (human-visual). Cross-tier traceability (`tekton query <from> <to>`) answers "which infra does this user-journey step touch?" as a path query. USE WHEN: designing or thinking deeply about architecture, a system, a data model, user journeys/flows, or a technical plan WITH the agent; when a Category-C HTML doc isn't enough because you need to see AND edit AND traverse the design across tiers; "let's design X", "architect this", "model the system", "draw the flow", "how does this fit together", "diagram this", "/tekton". NOT FOR: a one-off throwaway diagram (use Mermaid inline); prose-only ADRs (write the ADR...

broomva/skills

Generate a polished Remotion video and X thread showcasing the full agent skills inventory. Use when creating social media content about skills, rendering category-based skill visualizations, or producing animated showcases of agent capabilities. Triggers on "skills video", "showcase skills", "skills thread", "render skills", "social content for skills", or requests to visualize the skills inventory.

broomva/skills

OpenCaptions extension for Content Engine — adds intent-driven CWI (Caption With Intent) captions to the post-production pipeline. Hooks into the grade → caption → final stage. Generates captions that understand video intent (pitch, volume, emotion, emphasis) and style themselves accordingly with variable font weight, size, and color. Uses the OpenCaptions CLI or MCP server. Triggers on: 'add captions', 'opencaptions', 'CWI captions', 'intent captions'.

broomva/skills

Produce polished product launch videos using the Liquid Glass aesthetic — dark void backgrounds, 3D perspective floating UI panels, particle effects, spring animations, and cinematic pacing. Built on Remotion with Imagen 4.0 for frames and Veo 3.1 for B-roll. Use when: (1) creating a product demo or launch video, (2) showcasing a UI/app/tool with cinematic polish, (3) building a social-ready video from screenshots and renders, (4) applying the liquid glass floating panel style, (5) composing Remotion videos with 3D transforms and spring animations. Triggers on: 'launch video', 'product video', 'liquid glass video', 'demo video', 'showcase video', 'remotion video', 'floating panel', 'glass aesthetic'.

Skills associés