@squadbase/vantage-sdk

Server-side SDK for Squadbase Vantage apps. Import it from server/api/** handlers.

connection

connection resolves where to send a request and how to authenticate it. You send the request yourself with fetch.

import type { ApiContext } from "@squadbase/vantage/server";
import { HttpError } from "@squadbase/vantage/server";
import { connection } from "@squadbase/vantage-sdk/server";

const CONNECTION_ID = "...";
const QUERY_ID = "...";

export async function GET(ctx: ApiContext) {
  const { baseUrl, headers } = await connection(ctx, CONNECTION_ID);

  const res = await fetch(`${baseUrl}/queries/${QUERY_ID}`, {
    method: "POST",
    headers: { "Content-Type": "application/json", ...headers },
    body: JSON.stringify({ params: {} }),
  });
  if (!res.ok) {
    throw new HttpError(502, `query execution failed: ${res.status}`);
  }

  const { columns, rows } = await res.json();
  return Response.json({ columns, rows });
}

baseUrl already includes the version prefix and has no trailing slash, so append paths directly. Spread headers into the request headers.

Running a saved Query

A Query is addressed by its id alone: POST {baseUrl}/queries/{queryId}. The Connection is resolved from the Query, so never put a connection id in the path — pass it to connection.

SQL Queries take their arguments in params and return { columns, rows }:

body: JSON.stringify({ params: { since: "2026-01-01" } });
// → { columns: [{ name, type? }], rows: [{ ... }] }

HTTP Queries take the shape the Query itself declares — not wrapped in params — with query-string values on the URL, and pass the upstream service's response straight through (including non-2xx, so check res.ok):

const res = await fetch(`${baseUrl}/queries/${QUERY_ID}?since=2026-01-01`, {
  method: "POST",
  headers: { "Content-Type": "application/json", ...headers },
  body: JSON.stringify({ customerId: "c_123" }),
});

Notes

• The same code works in a preview and in a deployed app. Outside Squadbase, connection throws.
• Credentials, upstream URLs, and database connection details belong to the Connection and the Query. A handler never holds them, and never inlines SQL or imports a database client.