Quick start

This guide builds a small todo app on your own data. The todos live in your Manta datastore. Your server writes them, your React app reads them with typed schemas, and the Manta chat in the same page answers questions about them.

You build three pieces:

• A vocabulary: the Todo class and its properties, in a namespace that you own.
• A server: it signs people in, gives the page a Manta token, and writes todos with SPARQL updates.
• A React app: a todo list that reads the datastore, and the Manta chat next to it.

The guide uses Vite and React for the app, and Hono on Node for the server. Any framework works: the server pieces speak standard Request and Response.

Get access

Manta sets up your organization by hand for now. Contact us for access, and send the redirect URL of your app: http://localhost:5173/callback for this guide. You get back:

• a Manta account, as a member of your new organization;
• a datastore for your data, and its id;
• a custom app with User access, Machine access and SPARQL writes, and its client ID and secret.

The custom app is how your code talks to Manta. Manta shows its secret once: keep it on your server. The custom apps guide explains each setting.

Set up the project

Describe your data

The datastore needs to know what a todo is. You declare it in a vocabulary and its SHACL shapes, both in a namespace that your app owns, and push them with the manta CLI.

The CLI readme lists every check the API runs on a push.

Write the server

The server does three things: it signs people in through your custom app, it hands the page a fresh access token, and it writes todos. The person’s token carries the app’s SPARQL writes permission, so the writes run as that person. The page holds the same token and could write by itself. Writing through your server keeps the checks on what goes into the graph in one place.

// server/index.ts
import { serve } from "@hono/node-server";
import { webLoginRoutes } from "@manta-eu/auth/web";
import { Hono } from "hono";
import { HTTPException } from "hono/http-exception";

const mantaUrl = "https://app.hiremanta.com";
const datastore = process.env.MANTA_DATASTORE!;
const vocab = "https://todos.example.com/vocab#";

const manta = webLoginRoutes({
  client: { clientId: process.env.MANTA_CLIENT_ID!, clientSecret: process.env.MANTA_CLIENT_SECRET! },
  appUrl: "http://localhost:5173",
  sessionSecret: process.env.SESSION_SECRET!,
  offlineAccess: true,
});

const app = new Hono();

app.on(
  ["GET", "POST"],
  ["/login", "/callback", "/logout"],
  async (c) => (await manta.handle(c.req.raw)) ?? c.notFound(),
);

app.get("/api/manta-token", async (c) => {
  const { accessToken, idToken, setCookies } = await manta.session(c.req.raw);
  for (const cookie of setCookies) c.header("set-cookie", cookie, { append: true });
  if (!accessToken || !idToken) return c.json({ error: "Sign in first" }, 401);
  return c.json({ accessToken, user: personOf(idToken) });
});

app.post("/api/todos", async (c) => {
  const { title } = await c.req.json();
  if (typeof title !== "string" || title.trim() === "") throw new HTTPException(400, { message: "Give a title." });
  const todo = `https://todos.example.com/todos/${crypto.randomUUID()}`;
  return update(
    c.req.raw,
    `INSERT DATA { <${todo}> a <${vocab}Todo> ;
    <${vocab}title> ${literal(title)} ; <${vocab}completed> false . }`,
  );
});

app.patch("/api/todos", async (c) => {
  const { todo, completed } = await c.req.json();
  checkTodoIri(todo);
  if (typeof completed !== "boolean") throw new HTTPException(400, { message: "Give completed as true or false." });
  return update(
    c.req.raw,
    `DELETE { <${todo}> <${vocab}completed> ?old }
    INSERT { <${todo}> <${vocab}completed> ${completed} }
    WHERE { <${todo}> <${vocab}completed> ?old }`,
  );
});

app.delete("/api/todos", async (c) => {
  const { todo } = await c.req.json();
  checkTodoIri(todo);
  return update(c.req.raw, `DELETE { <${todo}> ?property ?value } WHERE { <${todo}> ?property ?value }`);
});

async function update(request: Request, sparql: string): Promise<Response> {
  const { accessToken, setCookies } = await manta.session(request);
  const headers = new Headers();
  for (const cookie of setCookies) headers.append("set-cookie", cookie);
  if (!accessToken) return Response.json({ error: "Sign in first" }, { status: 401, headers });
  const response = await fetch(`${mantaUrl}/d/${datastore}/sparql-update`, {
    method: "POST",
    headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/sparql-update" },
    body: sparql,
  });
  if (response.ok) return new Response(null, { status: 204, headers });
  return new Response(await response.text(), { status: response.status, headers });
}

// JSON string escapes are valid SPARQL string escapes, so user input cannot end the literal.
function literal(value: string): string {
  return JSON.stringify(value);
}

function checkTodoIri(todo: unknown): asserts todo is string {
  const isTodoIri = typeof todo === "string" && /^https:\/\/todos\.example\.com\/todos\/[0-9a-f-]{36}$/.test(todo);
  if (!isTodoIri) throw new HTTPException(400, { message: "Give the IRI of one of your todos." });
}

function personOf(idToken: string): { id: string; email: string; name?: string } {
  const claims = JSON.parse(Buffer.from(idToken.split(".")[1], "base64url").toString());
  return { id: claims.sub, email: claims.email, name: claims.name };
}

serve({ fetch: app.fetch, port: 8787 });

Never put a value from a request into an update as it is. Check its type, build literals with literal(), and build IRIs only from a checked pattern, as above. Send the cookies that session() returns with every response: when it renews the session, the old refresh token works only once more.

Show the todos

The page gets its token from /api/manta-token. EmbeddedChatProviders sends it on every request to Manta, and gives the hooks below their SPARQL connection.

Add the chat

The chat runs as the person who signed in, on the same datastore. It reads the graph, so it can answer questions about the todos.

// src/App.tsx
import { EmbeddedChat } from "@manta-eu/react/components/embedded-chat";
import { useEffect, useState } from "react";
import { MantaProviders, datastoreId, mantaSession, type Person } from "./manta";
import { TodoList } from "./todo-list";

export default function App() {
  const [user, setUser] = useState<Person>();
  const [failure, setFailure] = useState<string>();

  useEffect(() => {
    mantaSession()
      .then((session) => setUser(session.user))
      .catch((error: Error) => setFailure(error.message));
  }, []);

  if (failure) return <p className="typography-body p-6">{failure}</p>;
  if (!user) return null;

  return (
    <MantaProviders>
      <main className="grid h-screen grid-cols-[1fr_420px] gap-6 bg-background p-6">
        <TodoList />
        <EmbeddedChat
          user={user}
          isOperator={false}
          datastore={{ id: datastoreId, name: "Todos" }}
          assistantName="Todo assistant"
          welcomeSubtitle="Ask about your todos."
        />
      </main>
    </MantaProviders>
  );
}

Run it

pnpm tsx --env-file=.env server/index.ts
pnpm dev

Open http://localhost:5173. The page sends you to Manta to sign in, then back. Add a few todos, then ask the chat “Which of my todos are still open?”.

What’s next

• Derive facts with rules. Datalog rules can keep counts, statuses and other facts up to date for you. For now an operator pushes them: contact us with your .dlog file. See Rules.
• Let the agent change your data. The chat in a custom app reads your data and can run your actions, but does not write raw facts.
• See every option for sign-in, tokens and limits in the custom apps guide.