BaaS + AI cookbook

CREATE TABLE public.documents (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  source_id uuid NOT NULL,          -- the id returned by POST /api/sources/upload
  owner_id uuid NOT NULL DEFAULT auth.uid(),
  created_at timestamptz NOT NULL DEFAULT now()
);

ALTER TABLE public.documents ENABLE ROW LEVEL SECURITY;

CREATE POLICY own_documents ON public.documents
  FOR SELECT TO authenticated
  USING (owner_id = auth.uid());

// Runs on your backend. The browser sends its access token; it never
// chooses the source_ids itself.
async function retrieveContext(kbId: string, query: string, userToken: string) {
  const docsRes = await fetch(`${BASE_URL}/rest/v1/documents?select=source_id`, {
    headers: { apikey: ANON_KEY, Authorization: `Bearer ${userToken}` },
  });
  if (!docsRes.ok) throw new Error(`documents lookup failed: ${docsRes.status}`);
  const sourceIds = (await docsRes.json()).map((d: { source_id: string }) => d.source_id);
  if (sourceIds.length === 0) return [];

  const searchRes = await fetch(`${BASE_URL}/api/knowledge-bases/${kbId}/search`, {
    method: "POST",
    headers: {
      apikey: SERVICE_ROLE_KEY,
      Authorization: `Bearer ${SERVICE_ROLE_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query, top_k: 10, source_ids: sourceIds }),
  });
  const { results } = await searchRes.json();
  return results; // [{ chunk_id, text, score, source_id, meta }]
}

async function askAgent(agentId: string, message: string, contextItems: any[]) {
  // Also on your backend, with the Service Role key. The run doesn't check
  // who owns the chunks; the filtering happened in retrieveContext().
  const res = await fetch(`${BASE_URL}/api/agents/${agentId}/run`, {
    method: "POST",
    headers: {
      apikey: SERVICE_ROLE_KEY,
      Authorization: `Bearer ${SERVICE_ROLE_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message,
      context_items: contextItems.map((c) => ({
        text: c.text,
        meta: { ...c.meta, source_id: c.source_id },
      })),
    }),
  });
  return res.json();
}

// Runs in the browser, with the user's own access token. /run/stream is an
// end-user route, so this is allowed; knowledge-base and source routes aren't.
async function sendMessage(agentId: string, message: string, sessionId?: string) {
  return fetch(`${BASE_URL}/api/agents/${agentId}/run/stream`, {
    method: "POST",
    headers: {
      apikey: ANON_KEY,
      Authorization: `Bearer ${accessToken}`,  // the signed-in user's token
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message,
      // Omit on the first turn. Afterwards, reuse the session_id from the
      // start event; an end user can't name a new session id.
      ...(sessionId ? { session_id: sessionId } : {}),
    }),
  });
}

// Backend route. Express-style for illustration.
const serviceHeaders = {
  apikey: SERVICE_ROLE_KEY,
  Authorization: `Bearer ${SERVICE_ROLE_KEY}`,
  "Content-Type": "application/json",
};

app.post("/api/chat", requireUserAuth, async (req, res) => {
  const { userId } = req.user;  // from your own auth middleware
  const { message, sessionId } = req.body;
  const agentId = await getAgentForUser(userId);

  // First turn: create a session owned by this user. Only the Service Role
  // key may set user_id. On later turns, check the session is this user's
  // before using it: a service-role run can continue any session.
  const sid = sessionId && (await sessionBelongsTo(sessionId, userId))
    ? sessionId
    : (await (await fetch(`${POWABASE_URL}/api/agents/${agentId}/sessions`, {
        method: "POST",
        headers: serviceHeaders,
        body: JSON.stringify({ user_id: userId }),
      })).json()).session_id;

  const agentRes = await fetch(`${POWABASE_URL}/api/agents/${agentId}/run/stream`, {
    method: "POST",
    headers: serviceHeaders,
    body: JSON.stringify({
      message,
      session_id: sid,
      // Service-role runs may set knowledge_bases or context_items here.
      // See Recipe 1 for user-scoped context_items.
    }),
  });

  // Forward the SSE stream to the client.
  res.setHeader("Content-Type", "text/event-stream");
  res.setHeader("Cache-Control", "no-cache");
  res.setHeader("Connection", "keep-alive");
  agentRes.body.pipe(res);
});

POST /api/tools
{
  "name": "search_user_articles",
  "description": "Searches the user's saved articles for relevant content.",
  "type": "http",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "session_token": { "type": "string" }
    },
    "required": ["query", "session_token"]
  },
  "config": {
    "endpoint": "https://your-app.example.com/internal/tools/search-articles",
    "method": "POST"
  }
}

app.post("/internal/tools/search-articles", async (req, res) => {
  const { query, session_token } = req.body;

  // Look up the user from your opaque session_token — NOT from any header
  // because the platform doesn't forward auth to custom tools.
  const userId = await sessionStore.lookup(session_token);
  if (!userId) return res.status(401).end();

  // Now run the query against your DB with the user's identity applied.
  const results = await db.searchArticles(userId, query);
  res.json({ results });
});

// Runs on your backend: the Sources and knowledge-base routes require the
// Service Role key, so the browser sends the file to you, not to Powabase.
async function uploadAndChat(file: Blob, userId: string) {
  // Step 1: Upload to Sources (will be indexed).
  const sourceRes = await fetch(`${BASE_URL}/api/sources/upload`, {
    method: "POST",
    headers: {
      apikey: SERVICE_ROLE_KEY,
      Authorization: `Bearer ${SERVICE_ROLE_KEY}`,
    },
    body: (() => {
      const fd = new FormData();
      fd.append("file", file);
      return fd;
    })(),
  });
  const { id: sourceId } = await sourceRes.json();

  // Step 2: Record ownership (so RLS can scope future reads)
  await postgrest("documents", { source_id: sourceId, owner_id: userId });

  // Step 3: Poll for extraction completion (see Sources Reference for shape)
  await pollUntilExtracted(sourceId);

  // Step 4: Add to a user-specific KB
  const kbId = await getUserKb(userId);
  await fetch(`${BASE_URL}/api/knowledge-bases/${kbId}/sources`, {
    method: "POST",
    headers: { apikey: SERVICE_ROLE_KEY, Authorization: `Bearer ${SERVICE_ROLE_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ source_id: sourceId }),
  });

  // Step 5: Chat about the PDF. The KB is chosen per user, so this is an
  // Option B run from Recipe 2: Service Role key, knowledge_bases in the run
  // body, in a session created with this user's user_id.
  return runChat(kbId, userId);
}

async function streamAndBroadcast(agentId: string, userId: string, message: string) {
  // Open the agent SSE stream
  const agentRes = await fetch(`${POWABASE_URL}/api/agents/${agentId}/run/stream`, { ... });
  const reader = agentRes.body!.getReader();

  // The Realtime topic this user is subscribed to
  const topic = `chat:${userId}`;

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    const text = decoder.decode(value);
    for (const line of text.split("\n")) {
      if (!line.startsWith("data: ")) continue;
      const event = JSON.parse(line.slice(6));

      // Persist for chat history
      if (event.event === "chunk" || event.event === "complete") {
        await db.chatMessages.insert({ user_id: userId, payload: event });
      }

      // Broadcast for live UIs
      await broadcast({
        topic,
        event: event.event,
        payload: event,
      });
    }
  }
}

CREATE OR REPLACE FUNCTION broadcast_chat_message()
RETURNS trigger
LANGUAGE plpgsql
AS $$
BEGIN
  PERFORM realtime.send(
    payload  => jsonb_build_object('message_id', NEW.id, 'event', NEW.payload),
    event    => 'chat_event',
    topic    => 'chat:' || NEW.user_id::text,
    private  => true
  );
  RETURN NEW;
END;
$$;

CREATE TRIGGER chat_realtime
  AFTER INSERT ON public.chat_messages
  FOR EACH ROW EXECUTE FUNCTION broadcast_chat_message();