// One API, one object. On your server:
curl https://custardai.dev/api/public/v1/sessions \
  -H "Authorization: Bearer csk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "YOUR_STAFF_ID", "channels": ["chat", "voice", "video"],
        "user": { "userId": "u_123", "email": "ana@example.com" } }'

// Answer
{ "ok": true, "object": "session", "agentId": "...", "staff": "Sara",
  "channels": {
    "chat":  { "url": "https://custardai.dev/api/public/v1/chat", "conversationId": null },
    "voice": { "session": "vss_...", "endpoint": "wss://custardai.dev/api/live?session=1", "expiresIn": 300 },
    "video": { "embedUrl": "https://custardai.dev/embed/YOUR_STAFF_ID?card=1", "via": "embed" }
  },
  "abilities": ["live_lookup", "verify_identity"], "refused": [], "expiresIn": 300 }

// Every /v1 error looks the same:
{ "ok": false, "error": "staff_paused",
  "error_detail": { "type": "invalid_request_error", "code": "staff_paused", "message": "That staff member is paused" } }

curl https://custardai.dev/api/public/v1/chat \
  -H "Authorization: Bearer csk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "YOUR_STAFF_ID",
    "message": "Where is my transfer from this morning?",
    "conversationId": null,
    "user": { "userId": "u_123", "email": "ana@example.com", "fullName": "Ana Silva" }
  }'

// Answer
{ "ok": true, "reply": "Hi Ana, let me check that for you...", "conversationId": "7f1c..." }

// Voice from your own mic button (no widget). On your server:
curl https://custardai.dev/api/public/v1/voice/session \
  -H "Authorization: Bearer csk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "YOUR_STAFF_ID", "user": { "userId": "u_123", "email": "ana@example.com" } }'
// Answer: { "ok": true, "session": "vss_...", "endpoint": "wss://custardai.dev/api/live?session=1", "expiresIn": 300 }
// In your app: open the endpoint, create a WebRTC offer with the mic track, then send
// { "type": "app.start", "mode": "headless", "session": "vss_...", "agentId": "YOUR_STAFF_ID", "sdp": offer.sdp, "token": "" }
// Apply the SDP answer you receive, send { "type": "app.ready" } once audio plays, and { "type": "session.close" } to hang up.

// Product Copilot in your own app (chat and voice). Send the screens and buttons staff may use:
//   chat:  add "guide": { "pages": ["Transfer history"], "spots": ["Send money button"] } and "screen": { "id": "home", "title": "Home" }
//          the answer adds "guide": [{ "action": "highlight", "label": "Send money button" }]
//   voice: add the same "guide" when you create the session; when the customer changes screen send
//          { "type": "app.screen", "screen": "transfer_history", "title": "Transfer history" }
//          and listen for { "type": "app.guide", "action": "open_page" | "highlight", "label": "..." }
// Your app then opens that screen or shows its own spotlight. Staff only ever pick from your labels.

// Your server (Next.js route, Express, anything). The key never leaves it.
import { createCustardClient } from "@custardai/react";
const custard = createCustardClient({ apiKey: process.env.CUSTARD_API_KEY });

export async function POST(req) {
  const user = await getSignedInUser(req);          // your own login check
  const { message, conversationId } = await req.json();
  const result = await custard.chat({
    agentId: "YOUR_STAFF_ID",
    message,
    conversationId,                                  // null starts a new chat
    user: { userId: user.id, email: user.email, fullName: user.name, tier: user.tier },
  });
  return Response.json(result);
}

// Your existing chat screen
import { useCustardChat } from "@custardai/react";

function SupportChat() {
  const { messages, send, sending, error } = useCustardChat({ endpoint: "/api/support/chat" });
  return (
    <YourChatUI
      messages={messages}          // [{ role: "user" | "assistant", text }]
      onSend={(text) => send(text)}
      typing={sending}
      error={error}
    />
  );
}