Kuunda Cloud Managed — Kuunda Docs

Kuunda Cloud Managed = BaaS Kuunda (API REST, Auth, Storage, Realtime) + Management API pour les outils de vibe coding (Lovable, Bolt, CI, scripts).

Deux plans

Plan	Hôte	Usage
Data plane	{ref}.kuunda-cloud.com	App générée : @kuunda/kuunda-js, clé anon, JWT utilisateurs
Control plane	https://api.kuunda-cloud.com/v1	Agents : PAT, DDL SQL, création projet

Authentification

Créez un Personal Access Token (kuunda_pat_*) dans la console : Compte → Access Tokens. Permissions :

database_query (opt-in, décoché par défaut) : POST /v1/projects/{ref}/database/query — SQL hors API REST/RLS, journalisé, 30 req/min. Sans cette permission : 403 pat_database_query_forbidden.
projects_create (opt-in) : POST /v1/projects (nouveau projet dans la même organisation)
edge_functions (opt-in) : déployer / lister / supprimer des Edge Functions via POST /v1/projects/{ref}/functions/deploy (console Edge Functions, ou CLI du dépôt packages/cli — le paquet npm @kuunda/cli n’est pas publié). Sans cette permission : 403 pat_edge_functions_forbidden.

Pour Lovable / CI : dans la console, bouton Préparer pour CI / Lovable, ou Activer SQL sur un PAT existant (le secret déjà en CI reste valable). Recréer un token seulement si le secret a été perdu.

Authorization: Bearer kuunda_pat_xxxxx

Découverte projet

GET https://api.kuunda-cloud.com/v1/projects/{ref}
→ ref, schema, rest_url, auth_url, anon_key, sdk…

Créer un projet (Managed)

POST https://api.kuunda-cloud.com/v1/projects
{ "name": "Mon app Lovable" }
→ project { ref, anon_key, rest_url, schema, … }

Exécuter du SQL (migrations)

Requiert un PAT avec database_query: true. Le SQL est validé (AST + lexer hors chaînes, fail-closed si illisible) et tourne sous le rôle {schema}_owner, pas en superuser. Journal d’audit + limite 30 req/min (Redis, partagée entre instances).

POST https://api.kuunda-cloud.com/v1/projects/{ref}/database/query
{ "query": "CREATE TABLE …; NOTIFY pgrst, 'reload schema';" }

Déployer une Edge Function (agents / CI)

Requiert un PAT avec edge_functions: true. Équivalent de supabase functions deploy. Fichiers locaux : kuunda/functions/<name>/index.ts et éventuellement kuunda/functions/_shared/ (bundlé automatiquement). Le runtime injecte KUUNDA_URL, KUUNDA_ANON_KEY, KUUNDA_SERVICE_ROLE_KEY, KUUNDA_DB_SCHEMA, KUUNDA_PROJECT_REF (aliases SUPABASE_* aussi).

# Management API (PAT edge_functions)
POST https://api.kuunda-cloud.com/v1/projects/{ref}/functions/deploy
{ "name": "hello", "source": "Deno.serve(() => new Response('ok'))", "files": { "_shared/cors.ts": "…" } }

# CLI depuis le monorepo (packages/cli) — @kuunda/cli n’est pas sur npm
# npx kuunda functions deploy hello

# Secrets métier (upsert)
PUT https://api.kuunda-cloud.com/v1/projects/{ref}/functions/secrets
{ "functionName": "hello", "key": "GENIUS_API_KEY", "value": "…" }

Dans Cursor, le serveur MCP du dépôt (packages/mcp-server) expose aussi deploy_edge_function (jeton kuunda_mcp_* généré dans Paramètres → API → MCP).

Contrat runtime Functions (tous les projets)

Handler : export default async (req: Request) => Response ou Deno.serve(handler). Imports HTTPS Deno (esm.sh, jsr, deno.land) autorisés. Échec compilation / import / timeout : HTTP 500 JSON { "error", "message", "request_id" } avec CORS. Un 502 gateway (infra) a aussi CORS + request_id. Le preflight OPTIONS echo Access-Control-Request-Headers (SDK : content-profile, x-project-ref, headers métier).

Realtime WebSocket

Pour un projet actif, Realtime partagé est joignable sans activation manuelle : wss://{ref}.kuunda-cloud.com/realtime/v1/websocket?apikey=…&vsn=1.0.0 (SDK kuunda.channel(…)). Les projets en base dédiée reçoivent un sidecar au premier abonnement. Tables : publication supabase_realtime (console Realtime ou import).

Client dans le code généré

npm install @kuunda/kuunda-js

import { createClient } from '@kuunda/kuunda-js';

const kuunda = createClient(
  process.env.NEXT_PUBLIC_KUUNDA_URL!,
  process.env.NEXT_PUBLIC_KUUNDA_ANON_KEY!,
  { dbSchema: process.env.KUUNDA_DB_SCHEMA! }
);

KUUNDA_DB_SCHEMA = proj_ + UUID projet (32 hex, sans tirets), pas la ref courte à 8 caractères.

Équivalence SDK et clés

Utilisez @kuunda/kuunda-js avec l’API Management https://api.kuunda-cloud.com/v1, et les clés kuunda_anon_* / kuunda_pat_*.