eptaadmin-sdk 0.1.2

package/README.md

@@ -0,0 +1,93 @@
+# eptaadmin-sdk
+
+A minimal JavaScript/TypeScript client for reading data out of your EptaAdmin workspaces from your own project — a script, a backend, a frontend build step, anywhere Node.js 18+ or a browser's `fetch` is available.
+
+This SDK is currently **read-only**: it fetches workspaces, data sources, and their values. It does not create, update, or delete data.
+
+## Install
+
+This package isn't published to the npm registry yet. Install it directly from the EptaAdmin repository, e.g. by copying `sdk/js/` into your project or adding it as a local/git dependency:
+
+```json
+{
+  "dependencies": {
+    "eptaadmin-sdk": "file:../path/to/EptaAdmin/sdk/js"
+  }
+}
+```
+
+## Getting an API key
+
+1. Log into your EptaAdmin instance.
+2. Go to **Mon profil** (top-right avatar menu).
+3. In the **Clés API** section, give the key a name and click **Générer une clé**.
+4. Copy the key immediately — it's shown once and cannot be recovered afterwards. If you lose it, revoke it and generate a new one.
+
+The key inherits exactly the same permissions as your account: it can only read workspaces and data sources you're already a member of.
+
+## Quick start
+
+```js
+import { EptaAdminClient } from "eptaadmin-sdk";
+
+const client = new EptaAdminClient({
+  apiKey: process.env.EPTAADMIN_API_KEY,
+  baseUrl: "https://your-eptaadmin-instance.example.com", // defaults to http://localhost:8080
+});
+
+const workspaces = await client.listWorkspaces();
+// [{ name: "Acme", slug: "acme", role: "owner" }]
+
+const dataSources = await client.listDataSources("acme");
+// [{ name: "Clients", slug: "clients" }]
+
+const clients = await client.getDataSource("acme", "clients");
+// { name: "Clients", slug: "clients", columns: { nom: ["Jean Dupont"], email: ["jean@example.com"] } }
+
+// Shortcut when you already know exactly what you want, addressed as a
+// single slash-separated path instead of separate arguments:
+const names = await client.getValue("acme/clients/nom");
+// ["Jean Dupont", "Marie Curie"]
+
+const firstName = await client.getValue("acme/clients/nom/0");
+// "Jean Dupont"
+```
+
+## Data model: independent columns
+
+EptaAdmin stores each column of a data source as its own independent list of values — there's no assumed row-to-row correspondence between columns. `getDataSource()` returns that shape directly:
+
+```js
+{
+  "columns": {
+    "nom": ["Jean Dupont", "Marie Curie"],
+    "email": ["jean@example.com", "marie@example.com"]
+  }
+}
+```
+
+If your project needs row-aligned records, build them yourself from the columns you know are meant to line up (e.g. by index), since EptaAdmin itself doesn't guarantee that alignment.
+
+## Error handling
+
+Failed requests reject with an `EptaAdminError` carrying the HTTP status and the server's error message:
+
+```js
+import { EptaAdminClient, EptaAdminError } from "eptaadmin-sdk";
+
+try {
+  await client.getDataSource("acme", "does-not-exist");
+} catch (err) {
+  if (err instanceof EptaAdminError) {
+    console.error(err.status, err.message); // 404 "Source de données introuvable."
+  }
+}
+```
+
+## API reference
+
+- `new EptaAdminClient({ apiKey, baseUrl? })`
+- `client.listWorkspaces(): Promise<{ name, slug, role }[]>`
+- `client.listDataSources(workspaceSlug): Promise<{ name, slug }[]>`
+- `client.getDataSource(workspaceSlug, dataSourceSlug): Promise<{ name, slug, columns }>`
+- `client.getValue(path): Promise<unknown>` — `path` is `"wsSlug/dsSlug/column"` (returns that column's full array) or `"wsSlug/dsSlug/column/index"` (returns one value)

package/index.d.ts

@@ -0,0 +1,42 @@
+export interface Workspace {
+  name: string;
+  slug: string;
+  role: string;
+}
+
+export interface DataSourceSummary {
+  name: string;
+  slug: string;
+}
+
+export interface DataSourceContent {
+  name: string;
+  slug: string;
+  /** Each column is an independent list of values — index i of one column has no assumed relation to index i of another. */
+  columns: Record<string, unknown[]>;
+}
+
+export declare class EptaAdminError extends Error {
+  status: number;
+  constructor(message: string, status: number);
+}
+
+export interface EptaAdminClientOptions {
+  /** A personal API key generated from the EptaAdmin profile page. */
+  apiKey: string;
+  /** The URL of your EptaAdmin instance. Defaults to http://localhost:8080. */
+  baseUrl?: string;
+}
+
+export declare class EptaAdminClient {
+  constructor(options: EptaAdminClientOptions);
+  listWorkspaces(): Promise<Workspace[]>;
+  listDataSources(workspaceSlug: string): Promise<DataSourceSummary[]>;
+  getDataSource(workspaceSlug: string, dataSourceSlug: string): Promise<DataSourceContent>;
+  /**
+   * One-parameter shortcut addressed by a slash-separated path:
+   *   - "wsSlug/dsSlug/column"       -> that column's full value[] list.
+   *   - "wsSlug/dsSlug/column/index" -> exactly one value at that index.
+   */
+  getValue(path: string): Promise<unknown>;
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "eptaadmin-sdk",
+  "version": "0.1.2",
+  "description": "Client SDK for reading your EptaAdmin workspace data from your own project.",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "index.d.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/src/index.js

@@ -0,0 +1,88 @@
+/**
+ * EptaAdmin SDK — a minimal client for the EptaAdmin public read-only API.
+ * Works in Node.js (18+, for global fetch) and in browsers.
+ */
+
+export class EptaAdminError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = "EptaAdminError";
+    this.status = status;
+  }
+}
+
+export class EptaAdminClient {
+  /**
+   * @param {{ apiKey: string, baseUrl?: string }} options
+   *   apiKey  — a personal API key generated from the EptaAdmin profile page.
+   *   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) {
+    const res = await fetch(this.baseUrl + path, {
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+    });
+    const body = await res.json().catch(() => null);
+    if (!res.ok) {
+      const message = (body && body.error) || `Request failed with status ${res.status}`;
+      throw new EptaAdminError(message, res.status);
+    }
+    return body;
+  }
+
+  /** Lists the workspaces this API key's user can access. */
+  listWorkspaces() {
+    return this._request("/api/v1/workspaces");
+  }
+
+  /** Lists the data sources in a workspace. */
+  listDataSources(workspaceSlug) {
+    return this._request(`/api/v1/workspaces/${encodeURIComponent(workspaceSlug)}/datasources`);
+  }
+
+  /**
+   * Fetches a data source's content. EptaAdmin stores each column as an
+   * independent list of values (no assumed row-to-row correspondence
+   * between columns), so the response mirrors that: `columns` is a plain
+   * object of `{ [columnKey]: value[] }`.
+   */
+  getDataSource(workspaceSlug, dataSourceSlug) {
+    return this._request(
+      `/api/v1/workspaces/${encodeURIComponent(workspaceSlug)}/datasources/${encodeURIComponent(dataSourceSlug)}`
+    );
+  }
+
+  /**
+   * One-parameter shortcut to a single column or a single value, addressed
+   * by a slash-separated path instead of separate arguments:
+   *   - `"wsSlug/dsSlug/column"`       -> that column's full value[] list.
+   *   - `"wsSlug/dsSlug/column/index"` -> exactly one value at that index.
+   *
+   * @param {string} path
+   */
+  async getValue(path) {
+    const segments = String(path).split("/").filter(Boolean);
+    if (segments.length !== 3 && segments.length !== 4) {
+      throw new Error(
+        `getValue expects "workspace/dataSource/column" or "workspace/dataSource/column/index", got "${path}"`
+      );
+    }
+    const [workspaceSlug, dataSourceSlug, column, index] = segments;
+    let url =
+      `/api/v1/workspaces/${encodeURIComponent(workspaceSlug)}` +
+      `/datasources/${encodeURIComponent(dataSourceSlug)}` +
+      `/columns/${encodeURIComponent(column)}`;
+    if (index !== undefined) {
+      url += `/${encodeURIComponent(index)}`;
+    }
+    const body = await this._request(url);
+    return index !== undefined ? body.value : body.values;
+  }
+}