Quickstart: Build and Deploy Your First App

export TOTALUM_API_KEY=tlm_sk_your_key
npx tsx quickstart.ts

/**
 * Totalum App Builder API — end-to-end quickstart.
 * Launch a project, follow the agent live, publish it.
 * Run:  TOTALUM_API_KEY=tlm_sk_your_key npx tsx quickstart.ts
 */
const API = "https://builder-api.totalum.app/api/v1/vcaas";
const API_KEY = process.env.TOTALUM_API_KEY;
const PROMPT =
  "Build a task tracker: a landing page explaining the product, and a dashboard " +
  "where a signed-in user can create, complete and delete tasks.";

if (!API_KEY) throw new Error("Missing TOTALUM_API_KEY. Get one at https://platform.totalum.app/api");
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

/** Every call goes through here: unwraps `{ errors, data }` and throws on failure. */
async function api(method: string, path: string, body?: unknown) {
  const res = await fetch(`${API}${path}`, {
    method,
    headers: { "api-key": API_KEY!, "Content-Type": "application/json" }, // server-side only
    body: body ? JSON.stringify(body) : undefined,
  });
  const r = await res.json();
  if (!res.ok || r.errors) {
    throw Object.assign(new Error(r.errors?.errorMessage ?? r.error ?? res.statusText), {
      code: r.errors?.errorCode ?? r.code ?? res.status,
    });
  }
  return r.data;
}

async function main() {
  // 1. Create the project AND run the first prompt. A taken id gets a suffix: use the returned one.
  const launched = await api("POST", "/projects/launch", { projectId: "task-tracker", prompt: PROMPT });
  const id: string = launched.projectId;
  console.log(`Project "${id}" — ${launched.agent.message}`);
  for (const w of launched.warnings) console.warn(`[${w.step}] ${w.errorMessage}`);
  if (!launched.agent.started) await api("POST", `/projects/${id}/agent/start`, { prompt: PROMPT });

  // 2. Follow the run: the stage and the files it touches, then its final message.
  for (let stage = ""; ; ) {
    await sleep(10_000);
    const progress = await api("GET", `/projects/${id}/agent/progress`);
    if (progress && progress.stage !== stage) console.log(`  … ${(stage = progress.stage)} (${progress.files.length} files)`);
    const status = await api("GET", `/projects/${id}/agent/status`);
    if (status.status === "done") {
      for (const m of status.realtimeConversation) if (m.messageType === "finished") console.log(`\n${m.message}`);
      console.log(`Credits: ${status.creditsSpent}`);
      break;
    }
  }

  // 3. The development preview (read it again after every prompt).
  const project = await api("GET", `/projects/${id}`);
  console.log(`Preview: ${project.temporalDevelopmentProjectUrl}`);

  // 4–5. Publish, then wait for it to go live.
  await api("POST", `/projects/${id}/deployments/deploy`);
  for (;;) {
    await sleep(10_000);
    const d = await api("GET", `/projects/${id}/deployments/status`);
    if (d.status === "success") break;
    if (d.status === "error") throw new Error(d.errorDetails?.fixSummary ?? "Publish failed");
    console.log(`  publishing… ${d.step ?? ""}`);
  }

  // 6. The live address (your custom domain once you add one).
  const live = await api("GET", `/projects/${id}`);
  console.log(`Live: https://${live.productionProjectUrl}`);
}

main().catch((e) => {
  console.error(e.code ? `API error [${e.code}]: ${e.message}` : e);
  process.exit(1);
});

Project "task-tracker" — Process started. Estimated time: about 8 minutes…
  … starting (0 files)
  … working (6 files)
  … build (11 files)
  … deploy (11 files)

Done: a landing page and a dashboard where signed-in users manage their tasks. I signed up a test user and created, completed and deleted a task: all 200.
Credits: 14.2
Preview: https://task-tracker-dev-temporal-link-preview-k3y9x2ab.totalum-project.com
  publishing… build
  publishing… migration
Live: https://task-tracker.totalum-project.com