Guide développeur

Intégrer GrinGhost

GrinGhost est un provider OIDC custom + intermédiaire de paiement. Tu listes tes produits dans le dashboard, GrinGhost valide chaque action et gère les crédits via Stripe Connect.

Exemple de catalogue :
  analyze_image     → 5 crédits   (Analyser une image)
  generate_text     → 3 crédits   (Générer du texte)
  summarize         → 2 crédits   (Résumer un document)

import { createClient } from '@/lib/supabase/client'

const supabase = createClient()

await supabase.auth.signInWithOAuth({
  provider: 'custom:gringhost',
  options: {
    redirectTo: window.location.origin + '/auth/callback',
  },
})

// app/auth/callback/route.ts
import { createClient } from '@/lib/supabase/server'
import { NextRequest, NextResponse } from 'next/server'

export async function GET(request: NextRequest) {
  const { searchParams, origin } = new URL(request.url)
  const code = searchParams.get('code')
  if (code) {
    const supabase = await createClient()
    await supabase.auth.exchangeCodeForSession(code)
  }
  return NextResponse.redirect(origin + '/dashboard')
}

// lib/gringhost.ts
import type { User } from '@supabase/supabase-js'

export function getGringhostUserId(user: User): string | null {
  return user.identities?.find(i => i.provider === 'custom:gringhost')?.id ?? null
}

// Dans une route API
const { data: { user } } = await supabase.auth.getUser()
const gringhostId = getGringhostUserId(user)
// ↑ UUID GrinGhost — différent de user.id (UUID de TON projet Supabase)

// Côté client — déclenché au clic du bouton
async function getActionToken(accessToken: string, appId: string, productId: string) {
  const res = await fetch('https://gringhost.com/api/v1/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`,   // GrinGhost access_token
    },
    body: JSON.stringify({ app_id: appId, product_id: productId }),
  })
  const { action_token } = await res.json()
  return action_token  // string hex 64 chars, TTL 2 min, usage unique
}

// Côté client — après avoir obtenu l'action_token
const actionToken = await getActionToken(accessToken, APP_ID, 'analyze_image')

const res = await fetch('/api/analyze', {
  method: 'POST',
  body: JSON.stringify({ imageUrl, action_token: actionToken }),
})

// Côté serveur (ta route /api/analyze)
const res = await fetch('https://gringhost.com/api/v1/deduct', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.GRINGHOST_API_KEY,
  },
  body: JSON.stringify({
    user_id:      gringhostId,       // getGringhostUserId(user)
    product_id:   'analyze_image',
    action_token: actionToken,       // reçu du browser
  }),
})

const data = await res.json()
// data.remaining_credits = solde mis à jour

const res = await fetch(`https://gringhost.com/api/v1/credits?user_id=${gringhostId}`, {
  headers: { 'x-api-key': process.env.GRINGHOST_API_KEY },
})
const { credits, expires_at } = await res.json()
// credits    = solde disponible sur ton app
// expires_at = date d'expiration (null si aucun achat)

const APP_ID = process.env.NEXT_PUBLIC_GRINGHOST_APP_ID  // UUID de ton app

if (res.status === 402) {
  window.open(`https://gringhost.com/buy?app=${APP_ID}`, '_blank')
}

Conseil à communiquer à tes utilisateurs

Achète uniquement les crédits dont tu as besoin dans les 12 prochains mois. Les crédits non utilisés expirent, et acheter plus que nécessaire revient à exposer inutilement son argent. Consulter les tarifs →

// Exemple d'affichage avant action
<button onClick={handleAnalyze}>
  Analyser l'image — <span style={{ color: '#fbbf24' }}>5 crédits</span>
</button>

// Succès (200)
{
  "action_token": "a3f8b2...",   // 64 chars hex, usage unique
  "expires_at":   "2026-06-12T10:32:00.000Z",
  "credit_cost":  5
}

// Token GrinGhost invalide ou expiré (401)
{ "error": "invalid_token" }

// app_id ne correspond pas au token (403)
{ "error": "app_mismatch" }

// Utilisateur n'a pas autorisé l'app (403)
{ "error": "not_authorized" }

// product_id absent du catalogue (400)
{ "error": "product_not_found" }

// Trop de tokens générés — attendre avant de réessayer (429)
// Header: Retry-After: 60
{ "error": "rate_limited", "message": "Trop de tokens générés. Limite : 10 par minute." }

// app/auth/callback/route.ts — stocker le token
const { data } = await supabase.auth.exchangeCodeForSession(code)
const accessToken = data.session?.provider_token   // GrinGhost access_token

// Ou depuis le client après auth
const { data: { session } } = await supabase.auth.getSession()
const accessToken = session?.provider_token

# .env.local
GRINGHOST_BASE_URL=https://gringhost.com
GRINGHOST_API_KEY=<sandbox_api_key>

Pour les stacks sans Supabase (Laravel, Express, Django…). Flow basé sur décodage direct du JWT. En attendant, utilise le Cas 1 avec Supabase.

// Succès (200)
{ "success": true, "remaining_credits": 490 }

// action_token manquant (400)
{ "error": "action_token_required" }

// Token invalide, expiré ou déjà utilisé (403)
{ "error": "invalid_action_token" }

// Crédits insuffisants (402)
{ "error": "insufficient_credits", "remaining_credits": 3 }

// Produit absent du catalogue (400)
{ "error": "product_not_found" }

// Utilisateur n'a pas autorisé l'app (403)
{ "error": "user_not_authorized" }

// Limite quotidienne atteinte (429)
{ "error": "daily_limit_exceeded" }

// Clé API invalide (401)
{ "error": "unauthorized" }

// GET /api/v1/credits?user_id=xxx
// Header: x-api-key: ...

{
  "credits":    50000,
  "expires_at": "2027-06-12T14:32:00.000Z"
}
// credits    = solde disponible sur ton app
// expires_at = null si l'utilisateur n'a pas encore acheté de crédits

// Calculer le prix d'une action
// 1 crédit = 0.0001 $ payé par l'utilisateur → tu reçois ~0.000085 $
const coutReel = 0.00005   // $ — ce que tu paies à l'API IA (ex: GPT-4o-mini court)
const marge    = 2         // ×2 par rapport à ton coût
const credits  = Math.ceil(coutReel * marge / 0.0001)  // = 1 (minimum 1 entier)

// Erreurs de /api/v1/token (appelé depuis le browser)
if (tokenRes.status === 429) {
  // Rate limit — 10 tokens/min dépassés
  // Header Retry-After: 60 → attendre avant de réessayer
  showError('Trop de requêtes — réessaie dans quelques secondes')
}
if (tokenRes.status === 403 && tokenData.error === 'not_authorized') {
  // L'utilisateur n'a plus l'app autorisée → relancer le flux OAuth
}

// Erreurs de /api/v1/deduct (appelé depuis ton backend)
if (res.status === 402) {
  // Crédits insuffisants → rediriger vers la page d'achat (app_id obligatoire)
  window.open(`https://gringhost.com/buy?app=${APP_ID}`, '_blank')
}
if (res.status === 400 && data.error === 'product_not_found') {
  // product_id absent du catalogue → vérifier le dashboard
}
if (res.status === 400 && data.error === 'action_token_required') {
  // action_token non fourni → toujours appeler /api/v1/token avant deduct
}
if (res.status === 403 && data.error === 'invalid_action_token') {
  // token expiré (>2 min) ou déjà utilisé → régénérer un nouveau token
  const newToken = await getActionToken(accessToken, APP_ID, productId)
}
if (res.status === 429) {
  showError('Limite quotidienne atteinte — réessaie demain')
}

npm install -g @anthropic-ai/claude-code
cd gringhost-nextjs-starter
claude

"Ajoute un assistant de rédaction SEO. L'utilisateur entre un sujet,
reçoit 5 titres. Coût : 3 crédits (product_id: generate_titles)."

"Crée une page /summarize. L'utilisateur colle un texte, clique Résumer.
Coût : 2 crédits (product_id: summarize)."