Third-Party Lattice Sample App

The minimal sample app lives with the TypeScript compute client examples and uses only public SDK behavior. It models the backend portion of a user-authorized integration:

1. Obtain an OAuth access token from your Sign in with Lovelace token provider.
2. Create a Lattice Cloud compute client with { kind: "oauth", accessToken }.
3. List reachable personal runtimes.
4. Dispatch a chat request to the selected runtime.
5. Map structured errors to user-facing reconnect, reauthorize, retry, or support states.

Read the quickstart first if you still need to set up OAuth scopes or understand why this code uses an OAuth credential instead of a developer API key. Use personal runtimes when you need to create or bootstrap the runtime records this sample consumes.

import { ComputeClient, ComputeError } from "@lovelace-ai/compute-client";

async function runOnFirstReachableRuntime(accessToken: string, prompt: string) {
  const compute = new ComputeClient({
    credential: { kind: "oauth", accessToken },
  });

  const [runtime] = await compute.listReachablePersonalRuntimes();
  if (!runtime) {
    return { state: "select_runtime" as const };
  }

  try {
    const response = await compute.chatCompleteForPersonalRuntime(runtime, {
      messages: [{ role: "user", content: prompt }],
    });
    return { state: "completed" as const, runtime, response };
  } catch (error) {
    if (!(error instanceof ComputeError)) {
      return { state: "support" as const };
    }
    if (
      error.code === "revoked_grant" ||
      error.code === "insufficient_scopes"
    ) {
      return { state: "reauthorize" as const, runtime };
    }
    if (
      error.code === "personal_lattice_not_found" ||
      error.code === "personal_lattice_execution_timeout"
    ) {
      return { state: "reconnect_runtime" as const, runtime };
    }
    return { state: "retry_later" as const, runtime };
  }
}

The sample deliberately does not introduce an example package export or a new client abstraction. Runtime creation and bootstrap are elevated setup operations; ordinary third-party apps should read and use existing authorized runtimes through the public SDK.

For developer-paid traffic, construct ComputeClient with { kind: "apiKey", apiKey } at your backend boundary. The dispatch code can stay the same, but billing and authorization belong to your developer account rather than the signed-in user's grant.

Failure States

This app shape maps SDK errors into app states:

These states keep product behavior stable while the underlying message text remains free to improve.

Related

• Quickstart
• Personal runtimes
• OpenAI-compatible API
• Sign in with Lovelace