@conexus-x/next-view 1.0.0 → 1.0.2

package/.env

@@ -0,0 +1,21 @@
+# ---------------------------------------------------------------------------
+# DEVELOPER MODE. None of this is used by your view in production.
+#
+# The values here power the dev preview at /dev, which frames your view the way
+# a Conexus X board does and feeds it REAL data from your workspace.
+# ---------------------------------------------------------------------------
+
+# Your Conexus X API key. Find it in the app under Settings > API.
+#
+# It is read by the dev server ONLY and never reaches the browser: requests go
+# to /api/conexus/* on this app, which attaches the key server-side and forwards
+# them. A permanent credential in client-side JavaScript is a permanent
+# credential in every browser devtools panel that ever opens your view.
+API_KEY=Conexus_x_api_key
+
+# Where the Conexus X API lives.
+CONEXUS_API_URL=http://localhost:4040/api
+
+# Which origins may frame this view, space or comma separated.
+# Add your tunnel's CRM origin here when previewing inside the real app.
+CONEXUS_ORIGINS=http://localhost:3000 https://conexus-x.vercel.app

package/.env.example

@@ -0,0 +1,21 @@
+# ---------------------------------------------------------------------------
+# DEVELOPER MODE. None of this is used by your view in production.
+#
+# The values here power the dev preview at /dev, which frames your view the way
+# a Conexus X board does and feeds it REAL data from your workspace.
+# ---------------------------------------------------------------------------
+
+# Your Conexus X API key. Find it in the app under Settings > API.
+#
+# It is read by the dev server ONLY and never reaches the browser: requests go
+# to /api/conexus/* on this app, which attaches the key server-side and forwards
+# them. A permanent credential in client-side JavaScript is a permanent
+# credential in every browser devtools panel that ever opens your view.
+API_KEY=Conexus_x_api_key
+
+# Where the Conexus X API lives.
+CONEXUS_API_URL=http://localhost:4040/api
+
+# Which origins may frame this view, space or comma separated.
+# Add your tunnel's CRM origin here when previewing inside the real app.
+CONEXUS_ORIGINS=http://localhost:3000 https://conexus-x.vercel.app

package/.gitignore

@@ -3,5 +3,6 @@ node_modules/
 out/
 next-env.d.ts
 *.tsbuildinfo
+.env
 .env*.local
 .vercel

package/README.md

@@ -26,6 +26,61 @@ cd -                 && npm link @conexus-x/sdk
 Nothing in this repo records the link, which is the point.
 
 
+## Developer mode
+
+You do not need a Conexus X board to start. Put your API key in `.env` and open
+the developer page — it lists the workspaces that key can see, which is the
+shortest proof that your key works and the API is reachable.
+
+```bash
+# .env — already in your project, just fill it in
+API_KEY=Conexus_x_api_key          # <- replace with your key (Settings > API)
+CONEXUS_API_URL=http://localhost:4040/api
+```
+
+```bash
+npm run dev
+```
+
+Then open **http://localhost:5173/dev**.
+
+**The key never reaches the browser.** The page is a React Server Component: `API_KEY` is read in Node and only the finished list is sent to the browser.
+A permanent credential in client-side JavaScript is one devtools panel away
+from being somebody else's.
+
+`.env` is gitignored, so your real key cannot be committed by accident. The
+committed copy is `.env.example`.
+
+The developer page is not part of a production build, and **your view never
+uses the API key** — a deployed view receives data through the SDK, with the
+permissions of whoever is looking at the board. The key is scaffolding for
+development only.
+
+## Previewing inside the real CRM
+
+To see your view running inside an actual Conexus X board while you develop,
+give it a public URL:
+
+```bash
+npm run dev        # leave this running
+npm run tunnel     # in a second terminal
+```
+
+That prints a `https://….trycloudflare.com` address. Then:
+
+1. Put it in `entry` in `conexus.manifest.json`.
+2. Add the CRM's origin to `CONEXUS_ORIGINS` in `.env` and restart the dev
+   server, so the view allows that origin to frame it.
+
+The tunnel is Cloudflare's free quick tunnel — no account, no signup. It is
+fetched on first use rather than installed with the project, because the binary
+is large and most runs never need it. Quick tunnels have no uptime guarantee and
+the URL changes every run; they are for previewing, not for shipping.
+
+Chosen over the other free options because it serves your page directly. Some
+tunnels show an interstitial "click to continue" page on first visit, which a
+board cannot click through — the view would render as a blank frame.
+
 ## Tailwind is already set up
 
 Tailwind v4 is installed and configured. There is no `tailwind.config.js` to

package/app/dev/page.tsx

@@ -0,0 +1,162 @@
+import { notFound } from "next/navigation";
+
+/**
+ * DEVELOPER MODE — http://localhost:5173/dev
+ *
+ * Put your API key in .env, reload, and this lists the workspaces that key can
+ * see. It is the shortest possible proof that your key works and the API is
+ * reachable, which is the thing that is actually wrong the first time nothing
+ * renders.
+ *
+ * A SERVER COMPONENT, deliberately. The key is read here, in Node, and only the
+ * finished list is sent to the browser — so the key never appears in a bundle,
+ * a network tab, or anybody's devtools. Fetching this from the browser would
+ * put a permanent credential in client-side JavaScript, and a permanent
+ * credential in client-side JavaScript is one screenshot away from being
+ * somebody else's.
+ *
+ * Your VIEW does not work this way and must not: it runs framed by a board and
+ * receives data through the SDK, with the signed-in person's own permissions.
+ * This page is scaffolding for development, nothing more.
+ */
+
+// Never prerendered: it reads .env and the network at request time.
+export const dynamic = "force-dynamic";
+
+const PLACEHOLDER = "Conexus_x_api_key";
+
+interface WorkspaceMembership {
+    _id: string;
+    role?: string;
+    status?: string;
+    workspace?: {
+        _id: string;
+        name?: string;
+        description?: string;
+        totalModules?: number;
+    } | null;
+}
+
+type LoadResult =
+    | { ok: true; workspaces: WorkspaceMembership[] }
+    | { ok: false; title: string; detail: string };
+
+const loadWorkspaces = async (): Promise<LoadResult> => {
+    const apiKey = process.env.API_KEY;
+    const apiUrl = (process.env.CONEXUS_API_URL ?? "http://localhost:4040/api").replace(/\/$/, "");
+
+    if (!apiKey) {
+        return {
+            ok: false,
+            title: "No API key",
+            detail: "Add API_KEY to .env in this project, then reload."
+        };
+    }
+
+    if (apiKey === PLACEHOLDER) {
+        return {
+            ok: false,
+            title: "The API key is still the placeholder",
+            detail: `Replace API_KEY=${PLACEHOLDER} in .env with your own key from Conexus X (Settings › API), then reload.`
+        };
+    }
+
+    try {
+        const response = await fetch(`${apiUrl}/workspaces`, {
+            headers: { "x-api-key": apiKey },
+            cache: "no-store"
+        });
+
+        if (response.status === 401) {
+            return {
+                ok: false,
+                title: "That key was rejected",
+                detail: "The API answered 401. Check the key, and that the account it belongs to is still active."
+            };
+        }
+
+        if (!response.ok) {
+            return {
+                ok: false,
+                title: `The API answered ${response.status}`,
+                detail: (await response.text()).slice(0, 300)
+            };
+        }
+
+        const body = (await response.json()) as { workspaces?: WorkspaceMembership[] };
+
+        return { ok: true, workspaces: body.workspaces ?? [] };
+    } catch (error) {
+        return {
+            ok: false,
+            title: "Could not reach the API",
+            detail:
+                `Tried ${apiUrl}/workspaces — ${error instanceof Error ? error.message : String(error)}. ` +
+                "Is the Conexus X API running, and is CONEXUS_API_URL right?"
+        };
+    }
+};
+
+export default async function DevPage() {
+    // This page reads a secret and exists only to help you build. It has no
+    // business in a deployed view, so it is not there.
+    if (process.env.NODE_ENV === "production") notFound();
+
+    const result = await loadWorkspaces();
+
+    return (
+        <main className="mx-auto max-w-2xl p-6">
+            <header className="mb-5">
+                <h1 className="text-lg font-semibold">Developer mode</h1>
+                <p className="mt-1 text-[13px] text-muted">
+                    Workspaces visible to the API key in <code>.env</code>.
+                </p>
+            </header>
+
+            {!result.ok ? (
+                <div className="rounded-lg border border-danger bg-danger-soft px-4 py-3 text-danger">
+                    <strong className="font-semibold">{result.title}</strong>
+                    <p className="mt-1.5 text-[13px] whitespace-pre-wrap">{result.detail}</p>
+                </div>
+            ) : result.workspaces.length === 0 ? (
+                <p className="text-[13px] text-muted">
+                    The key works — this account is not a member of any workspace yet.
+                </p>
+            ) : (
+                <ul className="rounded-lg border border-line">
+                    {result.workspaces.map((membership) => (
+                        <li
+                            key={membership._id}
+                            className="flex items-center gap-3 border-b border-line px-4 py-3 last:border-b-0"
+                        >
+                            <div className="min-w-0 flex-1">
+                                <div className="truncate font-medium">
+                                    {membership.workspace?.name ?? "Untitled workspace"}
+                                </div>
+                                <div className="mt-0.5 font-mono text-[12px] text-muted">
+                                    {membership.workspace?._id}
+                                </div>
+                            </div>
+
+                            {membership.role ? (
+                                <span className="shrink-0 rounded-md border border-line px-2 py-0.5 text-[12px] text-muted">
+                                    {membership.role}
+                                </span>
+                            ) : null}
+
+                            <span className="shrink-0 text-[12px] text-muted">
+                                {membership.workspace?.totalModules ?? 0} boards
+                            </span>
+                        </li>
+                    ))}
+                </ul>
+            )}
+
+            <p className="mt-5 text-[12px] text-muted">
+                This page is development-only and returns 404 in a production build.
+                Your view itself never uses the API key — it receives data through
+                the SDK, with the permissions of whoever is looking at the board.
+            </p>
+        </main>
+    );
+}

package/next.config.ts

@@ -19,6 +19,22 @@ const conexusOrigins =
     "http://localhost:3000 https://conexus-x.vercel.app";
 
 const nextConfig: NextConfig = {
+    /**
+     * Let a tunnel reach the dev server.
+     *
+     * Next refuses cross-origin dev requests it was not told about, which is
+     * the reason `npm run tunnel` would otherwise serve a broken page through
+     * the public URL — the HTML arrives and the dev assets behind it do not.
+     *
+     * Development only; a production build ignores this entirely.
+     */
+    allowedDevOrigins: [
+        "*.trycloudflare.com",
+        "*.loca.lt",
+        "*.ngrok-free.app",
+        "*.ngrok.io"
+    ],
+
     /**
      * NOT pinning `turbopack.root` here, deliberately.
      *

package/package.json

@@ -1,13 +1,14 @@
 {
     "name": "@conexus-x/next-view",
-    "version": "1.0.0",
+    "version": "1.0.2",
     "private": false,
     "description": "Custom view for Conexus X — Next.js starter, wired to @conexus-x/sdk.",
     "scripts": {
         "dev": "next dev --port 5173",
         "build": "next build",
         "start": "next start --port 5173",
-        "lint": "eslint"
+        "lint": "eslint",
+        "tunnel": "npx -y cloudflared tunnel --url http://localhost:5173"
     },
     "dependencies": {
         "@conexus-x/sdk": "^0.1.0",
@@ -33,6 +34,8 @@
         "postcss.config.mjs",
         "tsconfig.json",
         "conexus.manifest.json",
+        ".env",
+        ".env.example",
         "README.md",
         ".gitignore"
     ]