Guide développeur

Intégrer GrinGhost

GrinGhost est un provider OIDC custom + intermédiaire de paiement. Crée un site dans le dashboard, liste tes actions, GrinGhost valide chaque débit et gère les crédits universels.

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

npm install @gringhost/react

// app/providers.tsx
'use client'
import { GrinGhostProvider } from '@gringhost/react'
import { createClient } from '@/lib/supabase/client'

const supabase = createClient()
export default function Providers({ children }: { children: React.ReactNode }) {
  return <GrinGhostProvider supabase={supabase}>{children}</GrinGhostProvider>
}

// app/layout.tsx — importe Providers
// Puis dans ton header :
import { GrinGhostButton } from '@gringhost/react'
<GrinGhostButton />  // pas de props — gère tout

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 + '/')
}

// Dans toutes tes routes serveur (prepare, execute, credits…)
import { createClient } from '@/lib/supabase/server'

const supabase       = await createClient()
const { data: { user } }    = await supabase.auth.getUser()    // vérifie auth
const { data: { session } } = await supabase.auth.getSession()
const providerToken  = session?.provider_token  // JWT GrinGhost → body de /api/site/session-token

// app/api/internal/mon-action/prepare/route.ts
import { createClient } from '@/lib/supabase/server'
import { NextResponse } from 'next/server'

export async function POST() {
  const supabase = await createClient()
  const { data: { user } } = await supabase.auth.getUser()
  if (!user) return NextResponse.json({ error: 'unauthorized' }, { status: 401 })

  const { data: { session } } = await supabase.auth.getSession()
  const providerToken = session?.provider_token
  if (!providerToken) return NextResponse.json({ error: 'no_gringhost_token' }, { status: 403 })

  const res = await fetch(`${process.env.GRINGHOST_BASE_URL}/api/site/session-token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': process.env.GRINGHOST_API_KEY! },
    body: JSON.stringify({ action_id: process.env.GRINGHOST_ACTION_ID, user_access_token: providerToken }),
  })
  const data = await res.json()
  if (res.status === 402) return NextResponse.json({ error: 'insufficient_credits' }, { status: 402 })
  if (res.status === 401) return NextResponse.json({ error: 'session_expired' }, { status: 401 })
  if (!res.ok)            return NextResponse.json({ error: 'session_token_failed' }, { status: 500 })

  return NextResponse.json({ token: data.token, credits_cost: data.credits_cost, action_name: data.action_name })
}

// app/api/internal/mon-action/route.ts
import { createClient } from '@/lib/supabase/server'
import { NextRequest, NextResponse } from 'next/server'

export async function POST(request: NextRequest) {
  const supabase = await createClient()
  const { data: { user } } = await supabase.auth.getUser()
  if (!user) return NextResponse.json({ error: 'unauthorized' }, { status: 401 })

  const { input, session_token } = await request.json()

  const debitRes = await fetch(`${process.env.GRINGHOST_BASE_URL}/api/site/debit`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': process.env.GRINGHOST_API_KEY! },
    body: JSON.stringify({ session_token, idempotency_key: crypto.randomUUID() }),
  })
  if (debitRes.status === 402) return NextResponse.json({ error: 'insufficient_credits' }, { status: 402 })
  if (!debitRes.ok)            return NextResponse.json({ error: 'debit_failed' }, { status: 500 })

  // Appel IA ici
  return NextResponse.json({ result: '...' })
}

'use client'
import { useGrinGhost, useGrinGhostAction } from '@gringhost/react'

const { loadCredits } = useGrinGhost()
const { prepare } = useGrinGhostAction('/api/internal/mon-action/prepare')

const result = await prepare()   // affiche la confirmation (prix vérifié, countdown 28s)
if (!result) return              // annulé ou timeout

const res = await fetch('/api/internal/mon-action', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ input, session_token: result.sessionToken }),
})

if (res.status === 402) { window.open('https://www.gringhost.com/buy', '_blank'); return }
loadCredits()  // rafraîchit le solde dans GrinGhostButton

'use client'
import { useGrinGhost } from '@gringhost/react'

const { credits, loadCredits } = useGrinGhost()
// credits est mis à jour automatiquement après chaque action
// loadCredits() force un rechargement depuis /api/internal/credits

// Via l'endpoint wallet
const res = await fetch('https://www.gringhost.com/api/wallet', {
  headers: { 'Authorization': `Bearer ${gringhostAccessToken}` },
})
const { credits, sandbox_credits } = await res.json()

// Via userinfo
const res = await fetch('https://www.gringhost.com/api/oauth/userinfo', {
  headers: { 'Authorization': `Bearer ${gringhostAccessToken}` },
})
const { sub, email, credits, sandbox_credits } = await res.json()

if (res.status === 402) {
  window.open('https://www.gringhost.com/buy', '_blank')
}

// Exemple : une requête chatbot côté serveur
export async function POST(request: NextRequest) {
  const { message } = await request.json()

  const debitRes = await fetch(`${process.env.GRINGHOST_BASE_URL}/api/site/debit`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': process.env.GRINGHOST_API_KEY! },
    body: JSON.stringify({
      service_token:    process.env.GRINGHOST_SERVICE_TOKEN, // ghsvc_xxx
      action_id:        process.env.GRINGHOST_ACTION_ID,     // UUID de l'action "chatbot_query"
      idempotency_key:  crypto.randomUUID(),
    }),
  })

  if (debitRes.status === 402) {
    const { error } = await debitRes.json()
    if (error === 'budget_exceeded')     return NextResponse.json({ error: 'budget_épuisé' }, { status: 402 })
    if (error === 'insufficient_credits') return NextResponse.json({ error: 'crédits_insuffisants' }, { status: 402 })
  }
  if (!debitRes.ok) return NextResponse.json({ error: 'debit_failed' }, { status: 500 })

  // Appel IA
  return NextResponse.json({ result: '...' })
}

// Succès (200)
{ "success": true, "remaining_budget": 485000 }

// Budget épuisé (402)
{ "error": "budget_exceeded", "remaining": 0 }

// Crédits insuffisants dans le wallet (402)
{ "error": "insufficient_credits", "remaining": 1200 }

// Token révoqué (403)
{ "error": "service_token_revoked" }

// Action introuvable ou inactive (404 / 403)
{ "error": "action_not_found" }
{ "error": "action_inactive" }

# .env.local
GRINGHOST_BASE_URL=https://www.gringhost.com
GRINGHOST_API_KEY=<sandbox_api_key>    # sandbox_api_key en dev, api_key en prod
GRINGHOST_IS_SANDBOX=true              # false en prod

// Remet le sandbox_credits à 1 000 000
const res = await fetch('https://www.gringhost.com/api/site/sandbox/reset', {
  method: 'POST',
  headers: { 'x-api-key': process.env.GRINGHOST_API_KEY! },
  body: JSON.stringify({ user_access_token: gringhostAccessToken }),
})

Pour les stacks sans Supabase (Laravel, Express, Django…). Même flux OAuth standard. En attendant, utilise le Cas 1 avec Supabase.

// Succès (200)
{
  "token":        "uuid-du-session-token",  // TTL 30 secondes
  "credits_cost": 500,
  "action_name":  "Analyser une image",
  "expires_at":   "2026-06-14T10:32:30.000Z",
  "user_balance": 4500
}

// Crédits insuffisants (402)
{ "error": "insufficient_credits", "user_balance": 200 }

// Token utilisateur invalide (401)
{ "error": "invalid_token" }

// Action inactive ou introuvable (404 / 400)
{ "error": "action_not_found" }
{ "error": "action_inactive" }

GET /api/public/session-token-info?token=<session_token>

// Succès (200)
{
  "credits_cost": 1,
  "action_name":  "Chat IA",
  "expires_at":   "2026-06-15T10:32:30.000Z"
}

// Token introuvable ou expiré (404)
{ "error": "not_found" }

// Succès mode session (200)
{ "success": true }

// Succès mode service (200)
{ "success": true, "remaining_budget": 485000 }

// Token expiré — mode session (400)
{ "error": "token_expired" }

// Token déjà utilisé — mode session (409)
{ "error": "token_already_used" }

// Crédits insuffisants (402)
{ "error": "insufficient_credits", "remaining": 1200 }

// Budget service épuisé (402)
{ "error": "budget_exceeded", "remaining": 0 }

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

{
  "credits":         4500,   // wallet prod (universel)
  "sandbox_credits": 985000, // wallet sandbox
  "updated_at":      "2026-06-14T09:15:00.000Z"
}

{
  "ledger": [
    { "id": "...", "user_id": "...", "action_id": "...", "credits": 500,
      "dev_share": 450, "platform_share": 50, "is_sandbox": false,
      "idempotency_key": "...", "created_at": "..." }
  ],
  "is_sandbox": false
}

{
  "site_id": "...", "site_name": "Mon Site",
  "pending_credits":      12500,  // crédits accumulés depuis le dernier payout
  "total_earned_credits": 85000,  // total historique
  "last_payout_at":       "2026-05-01T..."
}

// Calculer le coût en crédits d'une action
// 1 crédit = 0.0001 $ payé par l'utilisateur → tu reçois 0.000090 $
const coutReel = 0.00005   // $ — ton coût API (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)

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 : 300 crédits (action: generate_titles)."

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