Quickstart: Build and Deploy Your First App

npm install -g tsx          # or: npx tsx quickstart.ts
export TOTALUM_API_KEY=tlm_sk_your_key
npx tsx quickstart.ts

/**
 * Totalum App Builder API — end-to-end quickstart.
 * Creates a project, builds it with the AI agent, and deploys it to production.
 *
 * Run:  TOTALUM_API_KEY=tlm_sk_your_key npx tsx quickstart.ts
 */

const API_KEY = process.env.TOTALUM_API_KEY;

// 4-35 chars, lowercase letters/numbers/hyphens, must start with a letter.
const PROJECT_ID = "my-first-app";
const PROMPT =
  "Build a task tracker: a landing page explaining the product, and a dashboard " +
  "where a logged-in user can create, complete and delete tasks.";

if (!API_KEY) {
  console.error("Missing TOTALUM_API_KEY. Get one at https://platform.totalum.app/api");
  process.exit(1);
}

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

/** Every call goes through here. Unwraps `{ errors, data }`; throws on failure. */
async function api(method: string, path: string, body?: unknown) {
  const res = await fetch(`https://api-accounts.totalum.app/api/v1/vcaas${path}`, {
    method,
    // The key is a server-side secret. Never ship it to a browser.
    headers: { "api-key": API_KEY!, "Content-Type": "application/json" },
    body: body ? JSON.stringify(body) : undefined,
  });

  const r = await res.json();
  // Check the status too, not just `errors`: a rejected API key answers 401 with
  // a bare { error } instead of the envelope, which would otherwise slip through
  // as a success with `data: undefined`.
  if (!res.ok || r.errors) {
    throw Object.assign(new Error(r.errors?.errorMessage ?? r.error ?? res.statusText), {
      code: r.errors?.errorCode ?? res.status,
    });
  }
  return r.data;
}

async function main() {
  // 1. Create the project AND start building it, in one call.
  //    A taken name is not an error: launch appends random characters and tells
  //    you what it created, so always use the id it returns from here on.
  const launched = await api("POST", "/projects/launch", {
    projectId: PROJECT_ID,
    prompt: PROMPT,
    description: "My first app",
  });
  const projectId: string = launched.projectId;
  if (launched.requestedProjectId) {
    console.log(`"${launched.requestedProjectId}" was taken — created "${projectId}" instead`);
  } else {
    console.log(`Created project "${projectId}"`);
  }

  // A 200 means the PROJECT exists — not that every step happened. Anything that
  // did not is in `warnings`, and each message names the endpoint that retries it.
  for (const w of launched.warnings ?? []) console.warn(`[${w.step}] ${w.errorMessage}`);
  if (!launched.agent?.started) {
    await api("POST", `/projects/${projectId}/agent/start`, { prompt: PROMPT });
  }
  console.log("Agent started. This takes 10 to 30 minutes.\n");

  // 2. Poll until it finishes, printing each new message. Status reads are free.
  for (let printed = 0; ; ) {
    await sleep(12_000);
    const s = await api("GET", `/projects/${projectId}/agent/status`);

    for (const m of s.realtimeConversation.slice(printed)) {
      console.log(`  [${m.messageType}] ${m.message}`);
      // The agent tells you here if it needs a secret from you (a Stripe key, etc).
      for (const [key, info] of Object.entries(m.secretKeysNeeded ?? {}) as any) {
        if (!info.isProvided) console.log(`  ! Needs secret: ${key} — ${info.description}`);
      }
    }
    printed = s.realtimeConversation.length;

    if (s.status === "done") {
      console.log(`\nAgent finished. Credits spent: ${s.creditsSpent ?? "n/a"}`);
      break;
    }
  }

  // 3. Read the preview URL. Re-read it after every run — it can change, and the
  //    field that holds it is named by developmentUrlFieldToUse.
  const p = await api("GET", `/projects/${projectId}`);
  const preview = p[p.developmentUrlFieldToUse ?? "temporalDevelopmentProjectUrl"];
  console.log(`Preview:  ${preview ?? "(no dev server running yet)"}`);

  // 4. Deploy. If the dev server was archived it auto-starts, so retry while it wakes.
  for (;;) {
    try {
      await api("POST", `/projects/${projectId}/deployments/deploy`);
      break;
    } catch (e: any) {
      if (e.code !== "SERVER_NOT_READY") throw e;
      console.log("Server waking up, retrying in 20s...");
      await sleep(20_000);
    }
  }
  console.log("Deploying. This takes 2 to 5 minutes.");

  // 5. Poll the deploy until it goes live.
  for (;;) {
    await sleep(12_000);
    const d = await api("GET", `/projects/${projectId}/deployments/status`);
    if (d.status === "success") break;
    if (d.status === "error") throw new Error("Deployment failed — check the build logs");
  }

  // 6. The production URL lives on the project, not on the deployment.
  const done = await api("GET", `/projects/${projectId}`);
  console.log(`\nLive:     ${done.productionProjectUrl}`);
  console.log(`Credits:  ${done.totalCreditsSpent} spent on this project`);
}

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

Created project "my-first-app"
Agent started. This takes 10 to 30 minutes.

  [starting] Analyzing your request...
  [building] Creating the tasks table...
  [building] Building the dashboard page...
  [finished] Done! Your task tracker is ready.

Agent finished. Credits spent: 23
Preview:  https://dev-my-first-app.totalum-project.com
Deploying. This takes 2 to 5 minutes.

Live:     https://my-first-app.totalum-project.com
Credits:  31 spent on this project