CLI merchant

@refcampaign/cli est un client en ligne de commande en lecture seule pour le reporting merchant. Il consulte les campagnes, affiliés, conversions, commissions et paiements sans modifier ces ressources.

Installation

Le CLI nécessite Node.js 22, 23 ou 24.

Installez-le globalement :

npm install --global @refcampaign/cli
refcampaign --version

Vous pouvez aussi exécuter le package publié sans installation globale :

npx @refcampaign/cli --version
npx @refcampaign/cli status --json

Exécutez refcampaign --help ou refcampaign <groupe> <commande> --help pour consulter l'aide livrée avec la version installée. Les exemples suivants utilisent l'exécutable global.

Authentification

Créez une clé API merchant dans Paramètres → Clés API, puis lancez la connexion interactive :

refcampaign auth login

Le prompt masque la clé pendant la saisie. La connexion valide la clé auprès de RefCampaign avant de l'enregistrer dans le keyring du système : Trousseau sur macOS, Secret Service sur Linux ou Gestionnaire d'informations d'identification sur Windows. Le CLI ne crée aucun fichier local d'identifiants. Les espaces en début ou fin de clé sont refusés.

Consultez ou retirez l'identifiant du keyring avec :

refcampaign auth status
refcampaign auth status --json
refcampaign auth logout

auth status indique environment ou keyring comme source active. auth logout retire uniquement l'entrée du keyring et peut être relancé sans risque.

Priorité en CI et dans l'environnement

Pour la CI, ajoutez REFCAMPAIGN_API_KEY comme secret masqué et protégé chez le fournisseur CI, puis exposez-le à l'environnement du job. Le CLI utilise un REFCAMPAIGN_API_KEY non vide avant de consulter le keyring ; les jobs headless n'ont donc pas besoin de connexion interactive. N'affichez pas la variable et ne l'écrivez pas dans un fichier du dépôt.

merchant-report:
  script:
    - refcampaign status --json
    - refcampaign conversions summary --period 30d --json

Commandes et filtres

Toutes les commandes de ressources sont en lecture seule. --json et --csv sont incompatibles. L'option globale --debug ajoute des diagnostics expurgés sur stderr.

Les options de liste communes sont --limit <number> (1–100, défaut 50), --offset <number> (indexé à partir de zéro, défaut 0), --all, --json et --csv. Les filtres de montant acceptent un nombre décimal positif ou nul avec deux décimales au maximum. Les filtres de date acceptent une date ISO 8601 réelle comme 2026-07-01, ou un timestamp avec les secondes et Z ou un décalage UTC.

Exemples de requêtes :

refcampaign status
refcampaign campaigns list --status ACTIVE
refcampaign campaigns get camp_123 --json
refcampaign affiliates list --campaign-id camp_123 --all
refcampaign affiliates get aff_123 --json
refcampaign conversions list --status APPROVED --from 2026-07-01 --to 2026-07-31 --csv
refcampaign conversions summary --period 30d --group-by campaign --json
refcampaign commissions list --status PAYABLE --min-amount 10.00 --all
refcampaign payouts list --method BANK_TRANSFER --status PAID --json
refcampaign payouts get pay_123 --csv

Contrats de sortie

La sortie par défaut est un tableau lisible. Les dates des tableaux utilisent la locale et le fuseau de la machine. Les listes affichent More records are available. Use --offset N to continue. lorsqu'une autre page existe.

Les modes machine-readable sont stables pour les scripts :

• --json émet un document JSON suivi d'un saut de ligne. Les commandes de détail et de synthèse utilisent { "data": ... } ; les listes utilisent { "data": [...], "pagination": ... }.
• --csv émet un header puis des enregistrements séparés par CRLF. Les textes pouvant être interprétés comme des formules de tableur sont préfixés par une apostrophe. Les champs des listes et détails sont indiqués ci-dessous.
• stdout contient uniquement la sortie réussie de la commande. Les erreurs, notifications de retry et diagnostics --debug vont sur stderr. Les secrets sont expurgés de stderr.

Exemple de liste JSON :

refcampaign campaigns list --limit 1 --json

{
  "data": [
    {
      "id": "camp_123",
      "name": "Partner program",
      "description": null,
      "status": "ACTIVE",
      "commissionRate": 20,
      "commissionType": "PERCENTAGE",
      "startDate": "2026-07-01T00:00:00.000Z",
      "endDate": null,
      "createdAt": "2026-06-20T08:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 3,
    "limit": 1,
    "offset": 0,
    "hasMore": true,
    "page": 1,
    "totalPages": 3
  }
}

Exemple CSV :

refcampaign campaigns list --limit 1 --csv

id,name,status,commission_rate,commission_type,start,end
camp_123,Partner program,ACTIVE,20,PERCENTAGE,2026-07-01T00:00:00.000Z,

Pagination et retries

Sans --all, une commande de liste demande une seule page. Utilisez l'offset suivant affiché, ou choisissez une page avec --limit et --offset. Avec --all, le CLI part de l'offset demandé et suit toutes les pages jusqu'à ce que l'API renvoie hasMore: false ; les sorties JSON et CSV contiennent alors les lignes combinées.

Chaque requête HTTP a un timeout de 10 secondes et trois tentatives au maximum. Le CLI retente les timeouts, les échecs DNS/connexion transitoires, HTTP 429 et HTTP 5xx. Il respecte un header Retry-After valide ; sinon, les délais sont d'environ 1 seconde puis 2 secondes, avec jusqu'à 999 ms de jitter. Les notifications de retry apparaissent sur stderr dans un terminal interactif ou lorsque --debug est actif. Les autres réponses HTTP 4xx ne sont pas retentées.

Surcharge avancée de l'URL API

REFCAMPAIGN_API_URL est une surcharge avancée de l'origine API par l'environnement du processus. L'origine sélectionnée reçoit le header Authorization: Bearer : elle doit donc être digne de confiance. La valeur par défaut est https://app.refcampaign.com. La valeur doit viser la racine de l'origine : un / final est accepté, mais un nom d'utilisateur, un mot de passe, un path, une requête ou un fragment est rejeté. HTTPS est obligatoire sauf si l'hôte est exactement localhost, 127.0.0.1 ou [::1] ; les ports sont autorisés. Le CLI ne persiste jamais cette surcharge. N'envoyez jamais une clé de production vers une origine surchargée.

Utilisez la surcharge uniquement pour un environnement hors production contrôlé :

REFCAMPAIGN_API_URL=https://app.test.refcampaign.com refcampaign status --json

Codes de sortie

Résolution des problèmes

• No API key configured : exécutez refcampaign auth login ou exposez REFCAMPAIGN_API_KEY depuis le coffre de secrets de la CI.
• Clé indiquée comme invalide ou révoquée : sans afficher sa valeur, vérifiez directement si REFCAMPAIGN_API_KEY est défini dans le shell ou le coffre CI. S'il est défini, remplacez-le ou retirez-le à cet endroit ; refcampaign auth login modifie uniquement le keyring et ne peut pas remplacer la source d'environnement. Si REFCAMPAIGN_API_KEY est absent, le keyring est la source à traiter : utilisez refcampaign auth logout pour retirer une ancienne entrée si nécessaire, puis refcampaign auth login pour valider et enregistrer la nouvelle clé. Retirez les espaces autour de la clé avant de la soumettre.
• Clé sans le scope read : générez une clé API avec le scope read. Remplacez ou retirez REFCAMPAIGN_API_KEY lorsque l'environnement est la source active ; sinon, exécutez refcampaign auth login avec la nouvelle clé destinée au keyring.
• Stockage sécurisé indisponible : déverrouillez le keyring du système et réessayez. Dans une CI headless, utilisez le secret d'environnement.
• HTTP 429 ou 5xx : le CLI effectue déjà trois tentatives au maximum. Attendez avant de réessayer si la dernière échoue.
• Timeout ou échec réseau : vérifiez le DNS, le proxy, le pare-feu et l'origine API sélectionnée. Ajoutez l'option globale --debug pour des diagnostics expurgés.
• Date, montant, page ou filtre invalide : relancez la commande exacte avec --help ; les erreurs d'usage renvoient le code de sortie 2.
• Format de réponse inattendu : mettez @refcampaign/cli à jour ; le CLI refuse les réponses qui ne respectent pas son contrat livré.