@surf-ai/sdk 0.1.5-beta → 1.0.0-alpha.0

package/README.md

@@ -1,6 +1,6 @@
 # @surf-ai/sdk
 
-Surf platform SDK — data API client, Express server runtime, React hooks, and database helpers.
+Surf SDK 1.0 for backend apps, typed Surf data access, and database helpers.
 
 ## Install
 
@@ -8,202 +8,136 @@ Surf platform SDK — data API client, Express server runtime, React hooks, and
 bun add @surf-ai/sdk
 ```
 
-## Usage
+## Configuration
 
-### Frontend (React hooks)
+SDK 1.0 uses a single direct-auth model.
 
-```tsx
-import { useMarketPrice, cn, useToast } from '@surf-ai/sdk/react'
+| Env Var | Default | Purpose |
+| --- | --- | --- |
+| `SURF_API_BASE_URL` | `https://api.ask.surf/gateway/v1` | Full Surf API base URL |
+| `SURF_API_KEY` | none | Bearer token used for upstream requests and protected runtime endpoints |
+| `PORT` | none | Express server port when `createServer({ port })` is not provided |
+
+All upstream SDK requests use:
 
-function App() {
-  const { data, isLoading } = useMarketPrice({ symbol: 'BTC', time_range: '1d' })
-  return (
-    <div className={cn('p-4', isLoading && 'opacity-50')}>
-      BTC: ${data?.data?.[0]?.value}
-    </div>
-  )
-}
+```http
+Authorization: Bearer <SURF_API_KEY>
 ```
 
-### Backend (data API)
+## Subpath exports
+
+| Import | What it provides |
+| --- | --- |
+| `@surf-ai/sdk/server` | `createServer()`, `dataApi` |
+| `@surf-ai/sdk/db` | `dbProvision()`, `dbQuery()`, `dbTables()`, `dbTableSchema()`, `dbStatus()` |
+
+## Data API usage
 
 ```js
 const { dataApi } = require('@surf-ai/sdk/server')
 
-// Typed methods grouped by category
 const btc = await dataApi.market.price({ symbol: 'BTC', time_range: '1d' })
-const holders = await dataApi.token.holders({ address: '0x...', chain: 'ethereum' })
-const trades = await dataApi.onchain.sql({ sql: 'SELECT ...', max_rows: 100 })
+const holders = await dataApi.token.holders({
+  address: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
+  chain: 'ethereum',
+})
 
-// Escape hatch for new endpoints
-const data = await dataApi.get('newcategory/endpoint', { foo: 'bar' })
+// Escape hatch for endpoints that do not have a typed helper yet.
+const custom = await dataApi.get('market/price', { symbol: 'ETH', time_range: '1d' })
 ```
 
-### Backend (Express server)
+Available categories include:
+
+- `market`
+- `token`
+- `wallet`
+- `onchain`
+- `social`
+- `project`
+- `news`
+- `exchange`
+- `fund`
+- `search`
+- `web`
+- `polymarket`
+- `kalshi`
+- `prediction_market`
+
+## Server runtime
 
 ```js
 const { createServer } = require('@surf-ai/sdk/server')
 
-// Starts Express with /proxy/*, route auto-loading, DB sync, cron, health check
 createServer({ port: 3001 }).start()
 ```
 
-Routes in `routes/*.js` are auto-mounted at `/api/{name}`:
-
-```js
-// routes/btc.js → /api/btc
-const { dataApi } = require('@surf-ai/sdk/server')
-const router = require('express').Router()
-
-router.get('/', async (req, res) => {
-  const data = await dataApi.market.price({ symbol: 'BTC' })
-  res.json(data)
-})
-
-module.exports = router
-```
-
-## Subpath Exports
-
-| Import | What |
-|--------|------|
-| `@surf-ai/sdk/server` | `createServer()`, `dataApi` — Express runtime + typed data API |
-| `@surf-ai/sdk/react` | `useMarketPrice()`, `cn()`, `useToast()` — React hooks + utilities |
-| `@surf-ai/sdk/db` | `dbQuery()`, `dbProvision()`, `dbTables()` — Drizzle/Neon database |
+`createServer()` provides:
 
-## Built-in Endpoints
+- Auto-loading of `routes/*.js` and `routes/*.ts` as `/api/{name}`
+- `GET /api/health`
+- `POST /api/__sync-schema`
+- `GET/POST/PATCH/DELETE /api/cron`
+- `POST /api/cron/:id/run`
+- Schema sync on startup and when `db/schema.js` changes
 
-`createServer()` provides these automatically:
+`GET /api/health` is public.
 
-| Endpoint | Method | Purpose |
-|----------|--------|---------|
-| `/api/health` | GET | Health check — `{ status: 'ok' }` |
-| `/api/__sync-schema` | POST | Sync `db/schema.js` tables to database |
-| `/api/cron` | GET | List cron jobs and status |
-| `/api/cron` | POST | Update cron.json and reload |
-| `/proxy/*` | ANY | Data API passthrough to hermod |
+These runtime endpoints require `Authorization: Bearer <SURF_API_KEY>`:
 
-Routes in `routes/*.js` are auto-loaded as `/api/{filename}`.
+- `POST /api/__sync-schema`
+- `GET /api/cron`
+- `POST /api/cron`
+- `PATCH /api/cron/:id`
+- `DELETE /api/cron/:id`
+- `POST /api/cron/:id/run`
 
-DB schema is auto-synced on startup and when `db/schema.js` changes (file watcher).
+Routes you define in `routes/*` stay public unless your app adds its own auth.
 
-## Environment Variables
+Example route:
 
-The SDK auto-detects the runtime mode from environment variables. New prefixed names take priority; legacy names are supported for backward compatibility.
-
-### Data API routing
+```js
+const router = require('express').Router()
+const { dataApi } = require('@surf-ai/sdk/server')
 
-| Env Var | Legacy | Mode | Set By |
-|---------|--------|------|--------|
-| `SURF_SANDBOX_PROXY_BASE` | `DATA_PROXY_BASE` | Sandbox | urania executor |
-| `SURF_DEPLOYED_GATEWAY_URL` | `GATEWAY_URL` | Deployed | Bifrost |
-| `SURF_DEPLOYED_APP_TOKEN` | `APP_TOKEN` | Deployed | Bifrost |
+router.get('/', async (_req, res) => {
+  const data = await dataApi.market.price({ symbol: 'BTC', time_range: '1d' })
+  res.json(data)
+})
 
-**Routing logic:**
-```
-if SURF_SANDBOX_PROXY_BASE  → sandbox (OutboundProxy handles auth)
-elif SURF_DEPLOYED_GATEWAY_URL + SURF_DEPLOYED_APP_TOKEN → deployed (hermod with Bearer)
-else → public (api.ask.surf, no auth)
+module.exports = router
 ```
 
-### Server
-
-| Env Var | Default | Purpose |
-|---------|---------|---------|
-| `PORT` | `3001` | Express listen port |
-
-### Vite dev server (scaffold, not SDK)
+## Database helpers
 
-| Env Var | Default | Purpose |
-|---------|---------|---------|
-| `VITE_PORT` | `5173` | Frontend dev server port |
-| `VITE_BACKEND_PORT` | `3001` | Backend port for Vite proxy target |
-
-### How routing works
+```js
+const { dbProvision, dbQuery, dbTables, dbTableSchema, dbStatus } = require('@surf-ai/sdk/db')
 
+await dbProvision()
+const result = await dbQuery('SELECT * FROM users WHERE id = $1', [123], { arrayMode: true })
+const tables = await dbTables()
+const schema = await dbTableSchema('users')
+const status = await dbStatus()
 ```
-Sandbox (urania preview):
-  Frontend hook: useMarketPrice()
-    → fetch /proxy/market/price (same-origin to Vite)
-      → Vite proxy → Express /proxy/* → OutboundProxy (JWT) → hermod
-
-  Backend route: dataApi.market.price()
-    → fetch SURF_SANDBOX_PROXY_BASE/market/price
-      → OutboundProxy (JWT) → hermod
-
-Deployed (surf.computer):
-  Frontend hook: useMarketPrice()
-    → fetch /proxy/market/price (same-origin to Express)
-      → Express /proxy/* → hermod (APP_TOKEN)
-
-  Backend route: dataApi.market.price()
-    → fetch http://127.0.0.1:PORT/proxy/market/price (loopback)
-      → Express /proxy/* → hermod (APP_TOKEN)
-
-Public (local dev):
-  Frontend hook: useMarketPrice()
-    → fetch /proxy/market/price (same-origin to Vite)
-      → Vite proxy → Express /proxy/* → hermod (GATEWAY_URL + APP_TOKEN)
-
-  Backend route: dataApi.market.price()
-    → fetch SURF_DEPLOYED_GATEWAY_URL/gateway/v1/market/price (Bearer APP_TOKEN)
-```
-
-## Available Categories
-
-| Category | Example Methods |
-|----------|----------------|
-| `market` | `price`, `ranking`, `etf`, `futures`, `options`, `fear_greed` |
-| `token` | `holders`, `transfers`, `dex_trades`, `tokenomics` |
-| `wallet` | `detail`, `net_worth`, `labels_batch`, `transfers` |
-| `onchain` | `sql`, `tx`, `gas_price`, `schema`, `structured_query` |
-| `social` | `detail`, `mindshare`, `tweets`, `user`, `ranking` |
-| `project` | `detail`, `defi_metrics`, `defi_ranking` |
-| `news` | `detail`, `feed` |
-| `exchange` | `price`, `depth`, `klines`, `funding_history`, `perp` |
-| `fund` | `detail`, `portfolio`, `ranking` |
-| `search` | `project`, `news`, `wallet`, `web` |
-| `web` | `fetch` |
-| `polymarket` | `events`, `markets`, `prices`, `volumes` |
-| `kalshi` | `events`, `markets`, `prices`, `volumes` |
-| `prediction_market` | `category_metrics` |
-
-## Codegen
-
-API methods and React hooks are auto-generated from hermod's OpenAPI spec via the surf CLI:
 
-```bash
-# Regenerate all endpoints
-python scripts/gen_sdk.py
-
-# Regenerate specific endpoints
-python scripts/gen_sdk.py --ops market-price token-holders
-
-# Build
-bun run build
-```
+Define tables in `db/schema.js` and the runtime will provision the database and create missing tables and columns during startup.
 
-Requires `surf` CLI installed and authenticated (`surf login`).
+Example schema:
 
-## Development
+```js
+const { pgTable, serial, text, timestamp } = require('drizzle-orm/pg-core')
 
-```bash
-bun install
-bun run build        # compile TypeScript
-bun test             # run tests
-bun run codegen      # regenerate from OpenAPI spec
+exports.users = pgTable('users', {
+  id: serial('id').primaryKey(),
+  name: text('name').notNull(),
+  email: text('email'),
+  created_at: timestamp('created_at', { withTimezone: true }).defaultNow(),
+})
 ```
 
-## Testing
-
-```bash
-# Unit tests
-bun test ./tests/data-client.test.ts
+## 1.0 migration notes
 
-# E2E (auto-detects mode from env vars)
-bun test ./tests/e2e-all-envs.test.ts
-
-# E2E with specific mode:
-SURF_SANDBOX_PROXY_BASE=http://127.0.0.1:9999/s/<session>/proxy bun test ./tests/e2e-all-envs.test.ts
-SURF_DEPLOYED_GATEWAY_URL=https://api.ask.surf SURF_DEPLOYED_APP_TOKEN=<token> bun test ./tests/e2e-all-envs.test.ts
-```
+- `SURF_API_BASE_URL` and `SURF_API_KEY` are the only supported SDK auth variables.
+- The runtime no longer mounts `/proxy/*`.
+- The `@surf-ai/sdk/react` subpath has been removed.
+- Route modules must export the handler directly with `module.exports = router`.
+- `createServer()` requires a port from `options.port` or `process.env.PORT`.

package/dist/chunk-4NA3GKVD.js

@@ -0,0 +1,100 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/core/config.ts
+var DEFAULT_API_BASE_URL = "https://api.ask.surf/gateway/v1";
+function trimTrailingSlashes(value) {
+  return String(value || "").replace(/\/+$/, "");
+}
+function readSurfApiConfig() {
+  return {
+    baseUrl: trimTrailingSlashes(process.env.SURF_API_BASE_URL || DEFAULT_API_BASE_URL),
+    apiKey: process.env.SURF_API_KEY
+  };
+}
+function requireSurfApiConfig() {
+  const config = readSurfApiConfig();
+  if (!config.apiKey) {
+    throw new Error("SURF_API_KEY is required");
+  }
+  return { baseUrl: config.baseUrl, apiKey: config.apiKey };
+}
+function readAdminApiKey() {
+  return process.env.SURF_API_KEY;
+}
+
+// src/core/transport.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function normalizePath(path) {
+  return String(path || "").replace(/^\/+/, "");
+}
+function buildUrl(path, params) {
+  const { baseUrl } = requireSurfApiConfig();
+  const url = new URL(`${baseUrl}/${normalizePath(path)}`);
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      if (value != null) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+  }
+  return url.toString();
+}
+function buildHeaders(extra) {
+  const { apiKey } = requireSurfApiConfig();
+  const headers = new Headers(extra);
+  headers.set("Authorization", `Bearer ${apiKey}`);
+  return headers;
+}
+async function fetchJson(url, init, retries = 1) {
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    const res = await fetch(url, init);
+    if (!res.ok) {
+      const text2 = await res.text();
+      throw new Error(`API error ${res.status}: ${text2.slice(0, 200)}`);
+    }
+    const text = await res.text();
+    if (text) {
+      return JSON.parse(text);
+    }
+    if (attempt < retries) {
+      await sleep(1e3);
+    }
+  }
+  throw new Error(`Empty response from ${url}`);
+}
+async function getJson(path, params) {
+  return fetchJson(buildUrl(path, params), {
+    headers: buildHeaders()
+  });
+}
+async function postJson(path, body) {
+  return fetchJson(buildUrl(path), {
+    method: "POST",
+    headers: buildHeaders({
+      "Content-Type": "application/json"
+    }),
+    body: body ? JSON.stringify(body) : void 0
+  });
+}
+
+// src/data/client.ts
+async function get(path, params) {
+  return getJson(path, params);
+}
+async function post(path, body) {
+  return postJson(path, body);
+}
+
+export {
+  __require,
+  readAdminApiKey,
+  get,
+  post
+};

package/dist/{client-3YMIRPDV.js → client-Z45B2GYT.js}

@@ -1,7 +1,7 @@
 import {
   get,
   post
-} from "./chunk-J4OMYO3F.js";
+} from "./chunk-4NA3GKVD.js";
 export {
   get,
   post

package/dist/db/index.cjs

@@ -28,28 +28,49 @@ __export(db_exports, {
 });
 module.exports = __toCommonJS(db_exports);
 
-// src/data/client.ts
-var DEFAULT_PUBLIC_URL = "https://api.ask.surf/gateway/v1";
-function env(surfName, legacyName) {
-  return process.env[surfName] || process.env[legacyName];
-}
-function resolveConfig() {
-  const proxyBase = env("SURF_SANDBOX_PROXY_BASE", "DATA_PROXY_BASE");
-  if (proxyBase) {
-    return { baseUrl: proxyBase, headers: {} };
-  }
-  const gatewayUrl = env("SURF_DEPLOYED_GATEWAY_URL", "GATEWAY_URL");
-  const appToken = env("SURF_DEPLOYED_APP_TOKEN", "APP_TOKEN");
-  if (gatewayUrl && appToken) {
-    return {
-      baseUrl: `${gatewayUrl.replace(/\/$/, "")}/gateway/v1`,
-      headers: { Authorization: `Bearer ${appToken}` }
-    };
+// src/core/config.ts
+var DEFAULT_API_BASE_URL = "https://api.ask.surf/gateway/v1";
+function trimTrailingSlashes(value) {
+  return String(value || "").replace(/\/+$/, "");
+}
+function readSurfApiConfig() {
+  return {
+    baseUrl: trimTrailingSlashes(process.env.SURF_API_BASE_URL || DEFAULT_API_BASE_URL),
+    apiKey: process.env.SURF_API_KEY
+  };
+}
+function requireSurfApiConfig() {
+  const config = readSurfApiConfig();
+  if (!config.apiKey) {
+    throw new Error("SURF_API_KEY is required");
   }
-  return { baseUrl: DEFAULT_PUBLIC_URL, headers: {} };
+  return { baseUrl: config.baseUrl, apiKey: config.apiKey };
+}
+
+// src/core/transport.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function normalizePath(path) {
-  return String(path || "").replace(/^\/+/, "").replace(/^(?:proxy\/)+/, "");
+  return String(path || "").replace(/^\/+/, "");
+}
+function buildUrl(path, params) {
+  const { baseUrl } = requireSurfApiConfig();
+  const url = new URL(`${baseUrl}/${normalizePath(path)}`);
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      if (value != null) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+  }
+  return url.toString();
+}
+function buildHeaders(extra) {
+  const { apiKey } = requireSurfApiConfig();
+  const headers = new Headers(extra);
+  headers.set("Authorization", `Bearer ${apiKey}`);
+  return headers;
 }
 async function fetchJson(url, init, retries = 1) {
   for (let attempt = 0; attempt <= retries; attempt++) {
@@ -59,39 +80,44 @@ async function fetchJson(url, init, retries = 1) {
       throw new Error(`API error ${res.status}: ${text2.slice(0, 200)}`);
     }
     const text = await res.text();
-    if (text) return JSON.parse(text);
-    if (attempt < retries) await new Promise((r) => setTimeout(r, 1e3));
+    if (text) {
+      return JSON.parse(text);
+    }
+    if (attempt < retries) {
+      await sleep(1e3);
+    }
   }
   throw new Error(`Empty response from ${url}`);
 }
-async function get(path, params) {
-  const config = resolveConfig();
-  const cleaned = {};
-  if (params) {
-    for (const [k, v] of Object.entries(params)) {
-      if (v != null) cleaned[k] = String(v);
-    }
-  }
-  const qs = Object.keys(cleaned).length ? "?" + new URLSearchParams(cleaned).toString() : "";
-  return fetchJson(`${config.baseUrl}/${normalizePath(path)}${qs}`, {
-    headers: config.headers
+async function getJson(path, params) {
+  return fetchJson(buildUrl(path, params), {
+    headers: buildHeaders()
   });
 }
-async function post(path, body) {
-  const config = resolveConfig();
-  return fetchJson(`${config.baseUrl}/${normalizePath(path)}`, {
+async function postJson(path, body) {
+  return fetchJson(buildUrl(path), {
     method: "POST",
-    headers: { ...config.headers, "Content-Type": "application/json" },
+    headers: buildHeaders({
+      "Content-Type": "application/json"
+    }),
     body: body ? JSON.stringify(body) : void 0
   });
 }
 
+// src/data/client.ts
+async function get(path, params) {
+  return getJson(path, params);
+}
+async function post(path, body) {
+  return postJson(path, body);
+}
+
 // src/db/index.ts
 async function dbProvision() {
   return post("db/provision");
 }
 async function dbQuery(sql, params, options) {
-  return post("db/query", { sql, params, method: options?.arrayMode ? "all" : "execute" });
+  return post("db/query", { sql, params, arrayMode: options?.arrayMode ?? false });
 }
 async function dbTables() {
   return get("db/tables");

package/dist/db/index.d.cts

@@ -13,7 +13,7 @@
  *   const result = await dbQuery('SELECT * FROM users WHERE id = $1', [userId])
  */
 /**
- * Provision a database for the current user via /proxy/db/provision.
+ * Provision a database for the current user via db/provision.
  * Returns connection metadata. Neon auto-creates the DB if it doesn't exist.
  */
 declare function dbProvision(): Promise<{
@@ -23,8 +23,11 @@ declare function dbProvision(): Promise<{
     password: string;
 }>;
 /**
- * Execute a SQL query via /proxy/db/query.
+ * Execute a SQL query via db/query.
  * Uses pg-proxy driver under the hood — Drizzle ORM calls this automatically.
+ *
+ * @param options.arrayMode - When true, rows are returned as positional arrays
+ *   instead of objects. Required for Drizzle ORM pg-proxy compatibility.
  */
 declare function dbQuery(sql: string, params?: any[], options?: {
     arrayMode?: boolean;

package/dist/db/index.d.ts

@@ -13,7 +13,7 @@
  *   const result = await dbQuery('SELECT * FROM users WHERE id = $1', [userId])
  */
 /**
- * Provision a database for the current user via /proxy/db/provision.
+ * Provision a database for the current user via db/provision.
  * Returns connection metadata. Neon auto-creates the DB if it doesn't exist.
  */
 declare function dbProvision(): Promise<{
@@ -23,8 +23,11 @@ declare function dbProvision(): Promise<{
     password: string;
 }>;
 /**
- * Execute a SQL query via /proxy/db/query.
+ * Execute a SQL query via db/query.
  * Uses pg-proxy driver under the hood — Drizzle ORM calls this automatically.
+ *
+ * @param options.arrayMode - When true, rows are returned as positional arrays
+ *   instead of objects. Required for Drizzle ORM pg-proxy compatibility.
  */
 declare function dbQuery(sql: string, params?: any[], options?: {
     arrayMode?: boolean;