eptaadmin-sdk 0.1.4 → 0.1.5

package/README.md

@@ -83,6 +83,48 @@ 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 (Vite, CRA, etc.), 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. The `eptaadmin-prefetch` CLI (installed alongside the SDK) fetches your data sources once, at **build time**, and writes them to plain JSON files your app imports like any other static asset.
+
+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" }
+  ]
+}
+```
+
+The API key itself is read from the environment variable named by `apiKeyEnv` (default `EPTAADMIN_API_KEY`) — never put the key in the config file, since that file is typically committed.
+
+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, so your app just does:
+
+```js
+import homeData from "./data/home.json";
+// homeData.hero_title[0], homeData.testimonial_author, ...
+```
+
+The command exits with a non-zero status if any source fails to fetch, so a broken EptaAdmin connection fails your CI 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/package.json

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