@squadbase/vantage-sdk 0.1.0-dev.0

package/README.md

@@ -0,0 +1,66 @@
+# @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`.
+
+```ts
+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 }`:
+
+```ts
+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`):
+
+```ts
+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.

package/dist/server.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Vantage の API ハンドラが受け取るコンテキストのうち、この SDK が読む部分。
+ * `ApiContext` はこの形を満たすのでそのまま渡せる。
+ */
+interface RequestContext {
+    request: Request;
+    env?: Record<string, string | undefined>;
+}
+interface Connection {
+    /** コネクションを読むエンドポイントのベース URL。末尾にスラッシュは付かない。 */
+    baseUrl: string;
+    /** 認証とルーティングのために、このコネクション宛のリクエストへ載せるヘッダー。 */
+    headers: Record<string, string>;
+}
+/**
+ * コネクションを読むための宛先と認証情報を解決する。リクエストの送信は呼び出し側が行う。
+ *
+ * ```ts
+ * 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: {} }),
+ * })
+ * ```
+ */
+declare function connection(ctx: RequestContext, connectionId: string): Promise<Connection>;
+
+export { type Connection, type RequestContext, connection };

package/dist/server.js

@@ -0,0 +1,38 @@
+// src/server/connection.ts
+var CREDENTIAL_HEADER = "x-squadbase-machine-credential";
+var CREDENTIAL_ENV = "INTERNAL_SQUADBASE_MACHINE_CREDENTIAL";
+var BASE_URL_ENV = "INTERNAL_SQUADBASE_CONNECTOR_GATEWAY_URL";
+var readEnv = (ctx, name) => {
+  const value = ctx.env?.[name] ?? process.env[name];
+  return value != null && value !== "" ? value : void 0;
+};
+var resolveCredential = (ctx) => {
+  const fromHeader = ctx.request.headers.get(CREDENTIAL_HEADER);
+  if (fromHeader != null && fromHeader !== "") {
+    return fromHeader;
+  }
+  return readEnv(ctx, CREDENTIAL_ENV);
+};
+async function connection(ctx, connectionId) {
+  if (!connectionId) {
+    throw new Error("connection() requires a connection id.");
+  }
+  const credential = resolveCredential(ctx);
+  const baseUrl = readEnv(ctx, BASE_URL_ENV);
+  if (credential == null || baseUrl == null) {
+    throw new Error(
+      "Connections are unavailable here. Run this app in a Squadbase preview or a deployed project."
+    );
+  }
+  return {
+    baseUrl: baseUrl.replace(/\/+$/, ""),
+    headers: {
+      Authorization: `Bearer ${credential}`,
+      // コネクション単位で同じ worker へ振り分けさせ、接続プールを使い回す。
+      "x-tenant": connectionId
+    }
+  };
+}
+export {
+  connection
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@squadbase/vantage-sdk",
+  "version": "0.1.0-dev.0",
+  "description": "Server-side SDK for Squadbase Vantage apps",
+  "type": "module",
+  "exports": {
+    "./server": {
+      "import": "./dist/server.js",
+      "types": "./dist/server.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsup",
+    "type-check": "tsc",
+    "test": "vitest run"
+  },
+  "author": "Squadbase",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsup": "^8.4.0",
+    "typescript": "~5.7.0",
+    "vitest": "^4.1.6"
+  }
+}