eptaadmin-sdk 0.1.4 → 0.1.6

package/README.md

@@ -83,6 +83,105 @@ const avatars = await client.getValue("acme/clients/avatar");
 // ["https://your-eptaadmin-instance.example.com/api/v1/workspaces/acme/uploads/6f2dff985af5d290.png"]
 ```
 
+## Build-time prefetch (for static/SPA builds)
+
+If you're shipping a static single-page app, you usually don't want the production bundle calling out to your EptaAdmin instance at runtime — that means exposing your API key client-side, an extra network round-trip, and a hard runtime dependency on EptaAdmin staying up. There are two ways to prefetch data at **build time** instead; pick based on your bundler.
+
+### Option A — Vite plugin (recommended for Vite): identical code in dev and prod
+
+Your app code always calls `client.getDataSource(...)` / `client.getValue(...)` — never anything special-cased per environment, and **you don't list what to prefetch**: the plugin scans your source code for those calls (literal-string arguments only) and prefetches exactly what it finds. The plugin makes those calls resolve from build-time-fetched data with zero network request in the production bundle, while `vite` (the dev server) leaves them as real, live requests. Same code, same config, either way.
+
+```js
+// vite.config.js
+import { eptaadminPrefetch } from "eptaadmin-sdk/vite";
+
+export default {
+  plugins: [
+    eptaadminPrefetch({
+      baseUrl: "https://admin.example.com",
+      apiKeyEnv: "EPTAADMIN_API_KEY", // env var read only at build time, never bundled
+      // scanDir: "src",             // defaults to "src" — where to look for SDK calls
+    }),
+  ],
+};
+```
+
+```js
+// anywhere in your app — identical in dev and prod, nothing to register anywhere
+import { EptaAdminClient } from "eptaadmin-sdk";
+
+const client = new EptaAdminClient({
+  // In dev this needs a real key (e.g. from import.meta.env.VITE_EPTAADMIN_API_KEY)
+  // so the live fallback request can authenticate. In a prod build that only
+  // reads prefetched sources, this can be left undefined entirely — the
+  // apiKey is never read unless a call actually misses the prefetch cache.
+  apiKey: import.meta.env.VITE_EPTAADMIN_API_KEY,
+  baseUrl: "https://admin.example.com",
+});
+
+const home = await client.getDataSource("acme", "home");
+const title = await client.getValue("acme/home/hero_title/0");
+```
+
+Run `EPTAADMIN_API_KEY=eak_your_key npm run build` — the plugin finds both calls above by scanning `src/`, fetches `acme/home` once, and bakes the result into the bundle, throwing (failing the build) if the key is missing or a fetch fails. `vite` / `vite dev` are untouched, so nothing changes about your normal dev workflow.
+
+Scanning only sees **literal string arguments** — `getDataSource("acme", "home")`, not `getDataSource(ws, ds)` with variables. This is an inherent limit of static analysis, not something a smarter regex can fix — a scanner can't know a variable's value without running the code. Rather than silently prefetching nothing for those calls, the plugin **flags every one it finds but can't resolve**, with the exact file and line, at build time:
+
+```
+[eptaadmin-prefetch] src/pages/Home.jsx:42 — getDataSource(ws, ds) has non-literal arguments, can't be scanned; add it via "sources" if it should be prefetched.
+```
+
+Add exactly the pairs it points out via `sources`:
+
+```js
+eptaadminPrefetch({
+  baseUrl: "https://admin.example.com",
+  sources: [{ workspace: "acme", dataSource: "home" }], // merged with whatever scanning finds
+});
+```
+
+### Option B — CLI (any bundler): static JSON file you import yourself
+
+If you're not on Vite, or you'd rather have an explicit static JSON file, the `eptaadmin-prefetch` CLI (installed alongside the SDK) does the fetching and writes plain JSON files instead of hooking into a bundler.
+
+Add a config file (`eptaadmin.config.json`, resolved from your current working directory):
+
+```json
+{
+  "baseUrl": "https://admin.example.com",
+  "apiKeyEnv": "EPTAADMIN_API_KEY",
+  "sources": [
+    { "workspace": "acme", "dataSource": "home", "out": "src/data/home.json" }
+  ]
+}
+```
+
+Run it before your build, e.g. as a `prebuild` script in `package.json`:
+
+```json
+{
+  "scripts": {
+    "prebuild": "eptaadmin-prefetch",
+    "build": "vite build"
+  }
+}
+```
+
+```sh
+EPTAADMIN_API_KEY=eak_your_key npm run build
+```
+
+Each output file matches `getDataSource()`'s `columns` shape exactly:
+
+```js
+import homeData from "./data/home.json";
+// homeData.hero_title[0], homeData.testimonial_author, ...
+```
+
+Unlike Option A, this means writing a plain `import` instead of an `EptaAdminClient` call, so dev and prod aren't using identical code — the tradeoff for working with any build tool, not just Vite.
+
+Both options exit non-zero (Option A: the build fails outright; Option B: the CLI process fails) if a source can't be fetched or the API key is missing, so a broken EptaAdmin connection fails your build loudly instead of silently shipping stale or missing data.
+
 ## Error handling
 
 Failed requests reject with an `EptaAdminError` carrying the HTTP status and the server's error message:

package/bin/prefetch.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * eptaadmin-prefetch — fetches EptaAdmin data sources at BUILD time and
+ * writes them to static JSON files, so a production SPA build never calls
+ * out to your EptaAdmin instance at runtime. Import the generated file(s)
+ * like any other static asset instead of calling EptaAdminClient in the
+ * shipped bundle.
+ *
+ * Usage:
+ *   npx eptaadmin-prefetch [--config eptaadmin.config.json]
+ *
+ * Typical setup: add a "prebuild" script to package.json —
+ *   "prebuild": "eptaadmin-prefetch"
+ * — so it always runs right before "build".
+ *
+ * Config file (JSON), resolved relative to the current working directory:
+ * {
+ *   "baseUrl": "https://admin.example.com",
+ *   "apiKeyEnv": "EPTAADMIN_API_KEY",   // env var holding the API key — never put the key itself in this file
+ *   "sources": [
+ *     { "workspace": "acme", "dataSource": "home", "out": "src/data/home.json" }
+ *   ]
+ * }
+ *
+ * Each output file is the same shape as EptaAdminClient#getDataSource()'s
+ * "columns" object: { "columnKey": [value, ...] }.
+ */
+
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { EptaAdminClient } from "../src/index.js";
+
+function parseArgs(argv) {
+  const args = { config: "eptaadmin.config.json" };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--config" && argv[i + 1]) {
+      args.config = argv[++i];
+    }
+  }
+  return args;
+}
+
+async function loadConfig(path) {
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (err) {
+    throw new Error(`could not read config file "${path}": ${err.message}`);
+  }
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`config file "${path}" is not valid JSON: ${err.message}`);
+  }
+  if (!config.baseUrl) throw new Error(`config is missing "baseUrl"`);
+  if (!Array.isArray(config.sources) || config.sources.length === 0) {
+    throw new Error(`config must list at least one entry under "sources"`);
+  }
+  return config;
+}
+
+async function main() {
+  const { config: configPath } = parseArgs(process.argv.slice(2));
+  const config = await loadConfig(configPath);
+
+  const apiKeyEnv = config.apiKeyEnv || "EPTAADMIN_API_KEY";
+  const apiKey = process.env[apiKeyEnv];
+  if (!apiKey) {
+    throw new Error(`environment variable "${apiKeyEnv}" is not set (or empty) — it must hold a personal API key from your EptaAdmin profile page`);
+  }
+
+  const client = new EptaAdminClient({ apiKey, baseUrl: config.baseUrl });
+
+  let failures = 0;
+  for (const source of config.sources) {
+    const { workspace, dataSource, out } = source;
+    if (!workspace || !dataSource || !out) {
+      console.error(`✗ skipping invalid source entry (needs "workspace", "dataSource" and "out"): ${JSON.stringify(source)}`);
+      failures++;
+      continue;
+    }
+    try {
+      const data = await client.getDataSource(workspace, dataSource);
+      const outPath = resolve(process.cwd(), out);
+      await mkdir(dirname(outPath), { recursive: true });
+      await writeFile(outPath, JSON.stringify(data.columns, null, 2) + "\n", "utf8");
+      console.log(`✓ ${workspace}/${dataSource} → ${out}`);
+    } catch (err) {
+      console.error(`✗ ${workspace}/${dataSource}: ${err.message}`);
+      failures++;
+    }
+  }
+
+  if (failures > 0) {
+    console.error(`\neptaadmin-prefetch: ${failures} source(s) failed — failing the build rather than shipping stale or missing data.`);
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(`eptaadmin-prefetch: ${err.message}`);
+  process.exit(1);
+});

package/index.d.ts

@@ -22,8 +22,13 @@ export declare class EptaAdminError extends Error {
 }
 
 export interface EptaAdminClientOptions {
-  /** A personal API key generated from the EptaAdmin profile page. */
-  apiKey: string;
+  /**
+   * A personal API key generated from the EptaAdmin profile page. Only
+   * required for calls that actually reach the network — a call fully
+   * served from build-time-prefetched data (see eptaadmin-sdk/vite) never
+   * needs one.
+   */
+  apiKey?: string;
   /** The URL of your EptaAdmin instance. Defaults to http://localhost:8080. */
   baseUrl?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eptaadmin-sdk",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Client SDK for reading your EptaAdmin workspace data from your own project.",
   "type": "module",
   "main": "src/index.js",
@@ -9,13 +9,31 @@
     ".": {
       "types": "./index.d.ts",
       "import": "./src/index.js"
+    },
+    "./vite": {
+      "types": "./vite-plugin.d.ts",
+      "import": "./vite-plugin.js"
     }
   },
   "files": [
     "src",
+    "bin",
     "index.d.ts",
+    "vite-plugin.js",
+    "vite-plugin.d.ts",
     "README.md"
   ],
+  "bin": {
+    "eptaadmin-prefetch": "./bin/prefetch.js"
+  },
+  "peerDependencies": {
+    "vite": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=18"
   },

package/src/index.js

@@ -31,21 +31,35 @@ function resolveImageURLs(value, baseUrl) {
   return Array.isArray(value) ? value.map((v) => resolveImageURL(v, baseUrl)) : resolveImageURL(value, baseUrl);
 }
 
+// Populated by build tooling (see eptaadmin-sdk/vite) via a bundler `define`
+// so the exact same `client.getDataSource()` / `client.getValue()` calls
+// resolve from build-time-fetched data in a production bundle, with zero
+// runtime request — while resolving live in dev, where that identifier is
+// either undefined or defined as `{}`. `typeof` is deliberate: it's the one
+// operator that never throws on an identifier no bundler has declared at
+// all, so the SDK works unmodified outside of Vite too.
+const PREFETCHED = typeof __EPTAADMIN_PREFETCH_DATA__ !== "undefined" ? __EPTAADMIN_PREFETCH_DATA__ : {};
+
 export class EptaAdminClient {
   /**
-   * @param {{ apiKey: string, baseUrl?: string }} options
+   * @param {{ apiKey?: string, baseUrl?: string }} options
    *   apiKey  — a personal API key generated from the EptaAdmin profile page.
+   *             Only required for calls that actually reach the network —
+   *             a call fully served from build-time-prefetched data (see
+   *             eptaadmin-sdk/vite) never needs one, so it's fine to leave
+   *             unset in a production bundle that only reads prefetched
+   *             sources.
    *   baseUrl — the URL of your EptaAdmin instance (default: http://localhost:8080).
    */
   constructor({ apiKey, baseUrl = "http://localhost:8080" } = {}) {
-    if (!apiKey) {
-      throw new Error("EptaAdminClient requires an apiKey");
-    }
     this.apiKey = apiKey;
     this.baseUrl = baseUrl.replace(/\/$/, "");
   }
 
   async _request(path) {
+    if (!this.apiKey) {
+      throw new Error("EptaAdminClient requires an apiKey for this call (it wasn't served from prefetched data)");
+    }
     const res = await fetch(this.baseUrl + path, {
       headers: { Authorization: `Bearer ${this.apiKey}` },
     });
@@ -74,9 +88,12 @@ export class EptaAdminClient {
    * object of `{ [columnKey]: value[] }`.
    */
   async getDataSource(workspaceSlug, dataSourceSlug) {
-    const body = await this._request(
-      `/api/v1/workspaces/${encodeURIComponent(workspaceSlug)}/datasources/${encodeURIComponent(dataSourceSlug)}`
-    );
+    const cached = PREFETCHED[`${workspaceSlug}/${dataSourceSlug}`];
+    const body = cached
+      ? { name: cached.name, slug: cached.slug, columns: { ...cached.columns } }
+      : await this._request(
+          `/api/v1/workspaces/${encodeURIComponent(workspaceSlug)}/datasources/${encodeURIComponent(dataSourceSlug)}`
+        );
     for (const key of Object.keys(body.columns || {})) {
       body.columns[key] = resolveImageURLs(body.columns[key], this.baseUrl);
     }
@@ -99,6 +116,20 @@ export class EptaAdminClient {
       );
     }
     const [workspaceSlug, dataSourceSlug, column, index] = segments;
+
+    const cached = PREFETCHED[`${workspaceSlug}/${dataSourceSlug}`];
+    if (cached) {
+      const values = (cached.columns || {})[column];
+      if (values === undefined) {
+        throw new EptaAdminError(`column "${column}" not found`, 404);
+      }
+      const result = index !== undefined ? values[Number(index)] : values;
+      if (index !== undefined && result === undefined) {
+        throw new EptaAdminError(`index ${index} out of range for column "${column}"`, 404);
+      }
+      return resolveImageURLs(result, this.baseUrl);
+    }
+
     let url =
       `/api/v1/workspaces/${encodeURIComponent(workspaceSlug)}` +
       `/datasources/${encodeURIComponent(dataSourceSlug)}` +

package/vite-plugin.d.ts

@@ -0,0 +1,31 @@
+import type { Plugin } from "vite";
+
+export interface EptaadminPrefetchSource {
+  workspace: string;
+  dataSource: string;
+}
+
+export interface EptaadminPrefetchOptions {
+  /** The URL of your EptaAdmin instance. */
+  baseUrl: string;
+  /** Env var holding the API key used at build time. Defaults to "EPTAADMIN_API_KEY". */
+  apiKeyEnv?: string;
+  /** Directory (relative to Vite's root) scanned for getDataSource()/getValue() calls. Defaults to "src". */
+  scanDir?: string;
+  /**
+   * Extra data sources to prefetch on top of whatever scanning finds —
+   * for calls whose arguments aren't literal strings (e.g. a variable),
+   * which static scanning can't see.
+   */
+  sources?: EptaadminPrefetchSource[];
+}
+
+/**
+ * A Vite plugin that scans your source code for `getDataSource()` /
+ * `getValue()` calls, fetches exactly those data sources once at
+ * `vite build` time, and injects them so those same calls resolve from
+ * that static data — with zero runtime request in the production bundle.
+ * Has no effect during `vite` (dev server): the same client code keeps
+ * making live requests there.
+ */
+export declare function eptaadminPrefetch(options: EptaadminPrefetchOptions): Plugin;

package/vite-plugin.js

@@ -0,0 +1,175 @@
+/**
+ * Vite plugin: scans your project's source code for `client.getDataSource(...)`
+ * / `client.getValue(...)` calls, fetches exactly those data sources once at
+ * `vite build` time, and bakes the result into the bundle — so those same
+ * calls resolve from static data with zero runtime request in production,
+ * with no config listing what to prefetch and nothing to keep in sync by
+ * hand. `vite` (dev server) is left untouched, so the exact same client
+ * code keeps making live requests during development.
+ */
+import { readFile, readdir } from "node:fs/promises";
+import { join, extname } from "node:path";
+import { EptaAdminClient } from "./src/index.js";
+
+const SCANNABLE_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".vue", ".svelte"]);
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".vite", ".next", "coverage"]);
+
+// Matches getDataSource("ws", "ds") / getDataSource('ws', "ds") with any
+// quote style, tolerant of whitespace — literal string arguments only,
+// since this is static source scanning, not a real JS parser.
+const GET_DATA_SOURCE_RE = /getDataSource\s*\(\s*(['"`])([^'"`]+)\1\s*,\s*(['"`])([^'"`]+)\3\s*\)/g;
+// Matches getValue("ws/ds/column") / getValue("ws/ds/column/index") —
+// only the workspace/dataSource prefix is needed to know what to prefetch.
+const GET_VALUE_RE = /getValue\s*\(\s*(['"`])([^'"`]+)\1\s*\)/g;
+
+// Broader "any call, any arguments" versions of the two above, used only to
+// flag calls scanning *can't* resolve (e.g. variables) — doesn't handle
+// arguments containing nested parens/commas, but that's fine for a warning
+// whose job is just to point a human at the right line.
+const ANY_GET_DATA_SOURCE_CALL_RE = /getDataSource\s*\(([^)]*)\)/g;
+const ANY_GET_VALUE_CALL_RE = /getValue\s*\(([^)]*)\)/g;
+const LITERAL_STRING_ARG_RE = /^\s*['"`][^'"`]*['"`]\s*$/;
+
+function lineNumberAt(text, index) {
+  let line = 1;
+  for (let i = 0; i < index; i++) {
+    if (text.charCodeAt(i) === 10) line++;
+  }
+  return line;
+}
+
+async function collectFiles(dir, out) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return; // missing/unreadable dir — nothing to scan there
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      await collectFiles(join(dir, entry.name), out);
+    } else if (SCANNABLE_EXTENSIONS.has(extname(entry.name))) {
+      out.push(join(dir, entry.name));
+    }
+  }
+}
+
+/** Scans every source file under `scanDir` for SDK calls with literal
+ * string arguments, returning the unique {workspace, dataSource} pairs
+ * actually referenced in the code, plus a warning for every call scanning
+ * found but couldn't resolve (non-literal arguments) — so a developer can
+ * fix each one by adding it to `sources` instead of it failing silently. */
+async function scanForSources(scanDir) {
+  const files = [];
+  await collectFiles(scanDir, files);
+
+  const found = new Map(); // "workspace/dataSource" -> {workspace, dataSource}
+  const warnings = [];
+
+  for (const file of files) {
+    let text;
+    try {
+      text = await readFile(file, "utf8");
+    } catch {
+      continue;
+    }
+
+    const resolvedCallOffsets = new Set();
+    for (const m of text.matchAll(GET_DATA_SOURCE_RE)) {
+      const [, , workspace, , dataSource] = m;
+      found.set(`${workspace}/${dataSource}`, { workspace, dataSource });
+      resolvedCallOffsets.add(m.index);
+    }
+    for (const m of text.matchAll(GET_VALUE_RE)) {
+      const segments = m[2].split("/").filter(Boolean);
+      if (segments.length >= 3) {
+        const [workspace, dataSource] = segments;
+        found.set(`${workspace}/${dataSource}`, { workspace, dataSource });
+      }
+      resolvedCallOffsets.add(m.index);
+    }
+
+    for (const m of text.matchAll(ANY_GET_DATA_SOURCE_CALL_RE)) {
+      if (resolvedCallOffsets.has(m.index)) continue;
+      const args = m[1].split(",");
+      const isLiteral = args.length === 2 && args.every((a) => LITERAL_STRING_ARG_RE.test(a));
+      if (!isLiteral) {
+        warnings.push(`${file}:${lineNumberAt(text, m.index)} — getDataSource(${m[1].trim()}) has non-literal arguments, can't be scanned; add it via "sources" if it should be prefetched.`);
+      }
+    }
+    for (const m of text.matchAll(ANY_GET_VALUE_CALL_RE)) {
+      if (resolvedCallOffsets.has(m.index)) continue;
+      if (!LITERAL_STRING_ARG_RE.test(m[1])) {
+        warnings.push(`${file}:${lineNumberAt(text, m.index)} — getValue(${m[1].trim()}) has a non-literal argument, can't be scanned; add its {workspace, dataSource} via "sources" if it should be prefetched.`);
+      }
+    }
+  }
+
+  return { sources: [...found.values()], warnings };
+}
+
+/**
+ * @param {{
+ *   baseUrl: string,
+ *   apiKeyEnv?: string,
+ *   scanDir?: string,
+ *   sources?: { workspace: string, dataSource: string }[],
+ * }} options
+ *   scanDir — directory to scan for SDK calls, relative to Vite's root.
+ *             Defaults to "src".
+ *   sources — extra {workspace, dataSource} pairs to prefetch on top of
+ *             whatever scanning finds — for calls whose arguments aren't
+ *             literal strings (e.g. a variable), which scanning can't see.
+ */
+export function eptaadminPrefetch(options = {}) {
+  const { baseUrl, apiKeyEnv = "EPTAADMIN_API_KEY", scanDir = "src", sources: extraSources = [] } = options;
+  if (!baseUrl) throw new Error("eptaadminPrefetch: \"baseUrl\" is required");
+
+  return {
+    name: "eptaadmin-prefetch",
+    async config(config, { command }) {
+      // Dev server: leave the injected data empty so every client call in
+      // this mode falls through to a real, live fetch — same code path,
+      // just not pre-resolved.
+      let data = {};
+
+      if (command === "build") {
+        const apiKey = process.env[apiKeyEnv];
+        if (!apiKey) {
+          throw new Error(
+            `eptaadmin-prefetch: environment variable "${apiKeyEnv}" is not set — it must hold a personal API key from your EptaAdmin profile page to prefetch data at build time`
+          );
+        }
+
+        const root = config.root || process.cwd();
+        const { sources: scanned, warnings } = await scanForSources(join(root, scanDir));
+        for (const w of warnings) console.warn(`[eptaadmin-prefetch] ${w}`);
+
+        const byKey = new Map(scanned.map((s) => [`${s.workspace}/${s.dataSource}`, s]));
+        for (const s of extraSources) byKey.set(`${s.workspace}/${s.dataSource}`, s);
+        const sources = [...byKey.values()];
+
+        if (sources.length === 0) {
+          console.warn(
+            `[eptaadmin-prefetch] found no getDataSource()/getValue() calls with literal arguments under "${scanDir}" — nothing to prefetch. ` +
+              `If your calls use variables instead of string literals, list them explicitly via the "sources" option.`
+          );
+        }
+
+        const client = new EptaAdminClient({ apiKey, baseUrl });
+        for (const { workspace, dataSource } of sources) {
+          const result = await client.getDataSource(workspace, dataSource);
+          data[`${workspace}/${dataSource}`] = result;
+          console.log(`[eptaadmin-prefetch] ✓ ${workspace}/${dataSource}`);
+        }
+      }
+
+      return {
+        define: {
+          __EPTAADMIN_PREFETCH_DATA__: JSON.stringify(data),
+        },
+      };
+    },
+  };
+}