@conexus-x/next-view 1.0.1 → 1.0.3

package/.env

@@ -0,0 +1,31 @@
+# ---------------------------------------------------------------------------
+# DEVELOPER MODE ONLY — none of this ships with your extension.
+#
+# A deployed view holds no key and picks no workspace. It is framed by a board,
+# and the board tells it which workspace it is in and who is looking at it. The
+# values here exist so you can build against real data before that happens.
+# ---------------------------------------------------------------------------
+
+# Your Conexus X API key — find it in the app under Developer > API Key.
+#
+# Read by the dev server ONLY; it never reaches the browser. A permanent
+# credential in client-side JavaScript is one devtools panel away from being
+# somebody else's.
+API_KEY=Conexus_x_api_key
+
+# The workspace this extension is built for.
+#
+# An extension is written against a SHAPE — particular boards, particular
+# columns — and every workspace holds different ones, so a view built for one
+# is meaningless pointed at another. Naming it here makes the dev page show
+# that workspace's boards and nothing else.
+#
+# Leave it blank the first time: the dev page then lists your workspaces with
+# their ids so you can copy one in.
+WORKSPACE_ID=
+
+# Where the Conexus X API lives.
+CONEXUS_API_URL=http://localhost:4040/api
+
+# Which origins may frame this view, space or comma separated.
+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,71 @@ cd -                 && npm link @conexus-x/sdk
 Nothing in this repo records the link, which is the point.
 
 
+## Developer mode
+
+An extension is built for **one workspace**. Every workspace holds different
+boards and different columns, so a view written for Sales is meaningless
+pointed at Marketing — you name the one you mean, once, in `.env`.
+
+```bash
+# .env — the only env file in this project. Fill in two values.
+API_KEY=Conexus_x_api_key   # <- your key: Conexus X > Developer > API Key
+WORKSPACE_ID=               # <- leave blank the first time
+```
+
+```bash
+npm run dev
+```
+
+Open **http://localhost:5173/dev**.
+
+With `WORKSPACE_ID` blank it lists your workspaces **with their ids**. Copy the
+one you are building for into `.env`, reload, and the page then shows that
+workspace and its boards — and only those.
+
+**The pin is development only, and it has to be.** In production the board
+decides which workspace your view is mounted in and hands it over as context. A
+view that chose its own workspace would be a view that could read one it was
+never mounted in. This page mirrors what the host will give you; it does not
+override it.
+
+**The key never reaches the browser.** The dev page is a React Server Component: `API_KEY` is read in Node and only the finished list is sent down.
+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 — and it
+still ships inside the npm package, so a scaffolded project always has one
+ready to fill in.
+
+The dev 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.
+
+## 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,273 @@
+import { notFound } from "next/navigation";
+
+/**
+ * DEVELOPER MODE — http://localhost:5173/dev
+ *
+ * Put your API key and the workspace you are building for in .env, reload, and
+ * this shows that workspace's boards. It is the shortest proof that your key
+ * works, the API is reachable, and you are pointed at the right data — which is
+ * what is actually wrong the first time nothing renders.
+ *
+ * WHY A WORKSPACE IS PINNED IN .env: an extension is written against a SHAPE —
+ * particular boards, particular columns — and every workspace holds different
+ * ones. A view built for Sales is meaningless pointed at Marketing, so the
+ * developer names the one they mean instead of browsing all of them.
+ *
+ * THAT PIN IS DEVELOPMENT ONLY, and it has to be. In production the BOARD
+ * decides which workspace a view is mounted in and hands it over as context; a
+ * view that chose its own would be a view that could read a workspace it was
+ * never mounted in. This file mirrors what the host will hand you. It does not
+ * override it.
+ *
+ * A SERVER COMPONENT, deliberately. The key is read here, in Node, and only the
+ * finished list is sent to the browser — so it never appears in a bundle, a
+ * network tab, or anybody's devtools.
+ */
+
+// Never prerendered: it reads .env and the network at request time.
+export const dynamic = "force-dynamic";
+
+const PLACEHOLDER = "Conexus_x_api_key";
+
+interface Workspace {
+    _id: string;
+    name?: string;
+    totalModules?: number;
+}
+
+interface WorkspaceMembership {
+    _id: string;
+    role?: string;
+    workspace?: Workspace | null;
+}
+
+interface Board {
+    _id: string;
+    name?: string;
+    description?: string;
+    visibility?: string;
+    totalRecords?: number;
+}
+
+type DevState =
+    | { kind: "error"; title: string; detail: string }
+    /** No WORKSPACE_ID yet — show what is available so one can be copied in. */
+    | { kind: "pick"; workspaces: WorkspaceMembership[] }
+    | { kind: "pinned"; workspace: Workspace; role: string | undefined; boards: Board[] };
+
+const apiUrl = () =>
+    (process.env.CONEXUS_API_URL ?? "http://localhost:4040/api").replace(/\/$/, "");
+
+const load = async (): Promise<DevState> => {
+    const apiKey = process.env.API_KEY;
+    const workspaceId = (process.env.WORKSPACE_ID ?? "").trim();
+
+    if (!apiKey) {
+        return {
+            kind: "error",
+            title: "No API key",
+            detail: "Add API_KEY to .env in this project, then reload.",
+        };
+    }
+
+    if (apiKey === PLACEHOLDER) {
+        return {
+            kind: "error",
+            title: "The API key is still the placeholder",
+            detail: `Replace API_KEY=${PLACEHOLDER} in .env with your own key from Conexus X (Developer › API Key), then reload.`,
+        };
+    }
+
+    const call = async (path: string) => {
+        const response = await fetch(`${apiUrl()}${path}`, {
+            headers: { "x-api-key": apiKey },
+            cache: "no-store",
+        });
+
+        if (response.status === 401) {
+            throw new Error(
+                "The API answered 401. Check the key, and that the account it belongs to is still active."
+            );
+        }
+
+        if (!response.ok) {
+            throw new Error(`The API answered ${response.status}: ${(await response.text()).slice(0, 200)}`);
+        }
+
+        return response.json() as Promise<Record<string, unknown>>;
+    };
+
+    try {
+        const body = await call("/workspaces");
+        const memberships = (body["workspaces"] as WorkspaceMembership[] | undefined) ?? [];
+
+        if (!workspaceId) {
+            return { kind: "pick", workspaces: memberships };
+        }
+
+        const mine = memberships.find((row) => row.workspace?._id === workspaceId);
+
+        // A pinned id that is not one of yours is the single most confusing
+        // failure here — every call succeeds and the page is simply empty — so
+        // it is named rather than left to look like "no boards".
+        if (!mine?.workspace) {
+            return {
+                kind: "error",
+                title: "WORKSPACE_ID does not match a workspace you are in",
+                detail:
+                    `.env points at ${workspaceId}, which is not among the ${memberships.length} ` +
+                    "workspace(s) this key can see. Clear WORKSPACE_ID to list them again.",
+            };
+        }
+
+        const boardsBody = await call(`/modules/${workspaceId}`);
+
+        return {
+            kind: "pinned",
+            workspace: mine.workspace,
+            role: mine.role,
+            boards: (boardsBody["modules"] as Board[] | undefined) ?? [],
+        };
+    } catch (error) {
+        return {
+            kind: "error",
+            title: "Could not reach the API",
+            detail:
+                `${error instanceof Error ? error.message : String(error)}\n\n` +
+                `Tried ${apiUrl()}. 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 state = await load();
+
+    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">
+                    {state.kind === "pinned"
+                        ? "The workspace this extension is built for, and its boards."
+                        : "Reading the API key in .env."}
+                </p>
+            </header>
+
+            {state.kind === "error" ? (
+                <div className="rounded-lg border border-danger bg-danger-soft px-4 py-3 text-danger">
+                    <strong className="font-semibold">{state.title}</strong>
+                    <p className="mt-1.5 text-[13px] whitespace-pre-wrap">{state.detail}</p>
+                </div>
+            ) : state.kind === "pick" ? (
+                <>
+                    <div className="mb-4 rounded-lg border border-line bg-accent-soft px-4 py-3">
+                        <strong className="font-semibold">Pick the workspace you are building for</strong>
+                        <p className="mt-1 text-[13px]">
+                            Copy its id into <code>WORKSPACE_ID</code> in <code>.env</code> and
+                            reload. This view will then show that workspace&apos;s boards — and
+                            only those.
+                        </p>
+                    </div>
+
+                    {state.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">
+                            {state.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>
+                    )}
+                </>
+            ) : (
+                <>
+                    <div className="mb-4 flex items-center gap-3 rounded-lg border border-line px-4 py-3">
+                        <div className="min-w-0 flex-1">
+                            <div className="truncate text-[15px] font-semibold">
+                                {state.workspace.name ?? "Untitled workspace"}
+                            </div>
+                            <div className="mt-0.5 font-mono text-[12px] text-muted">
+                                {state.workspace._id}
+                            </div>
+                        </div>
+
+                        {state.role ? (
+                            <span className="shrink-0 rounded-md border border-line px-2 py-0.5 text-[12px] text-muted">
+                                {state.role}
+                            </span>
+                        ) : null}
+                    </div>
+
+                    {state.boards.length === 0 ? (
+                        <p className="text-[13px] text-muted">
+                            This workspace has no boards yet. Create one in Conexus X and
+                            reload.
+                        </p>
+                    ) : (
+                        <ul className="rounded-lg border border-line">
+                            {state.boards.map((board) => (
+                                <li
+                                    key={board._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">
+                                            {board.name ?? "Untitled board"}
+                                        </div>
+                                        <div className="mt-0.5 font-mono text-[12px] text-muted">
+                                            {board._id}
+                                        </div>
+                                    </div>
+
+                                    {board.visibility ? (
+                                        <span className="shrink-0 rounded-md border border-line px-2 py-0.5 text-[12px] text-muted">
+                                            {board.visibility}
+                                        </span>
+                                    ) : null}
+
+                                    <span className="shrink-0 text-[12px] text-muted">
+                                        {board.totalRecords ?? 0} records
+                                    </span>
+                                </li>
+                            ))}
+                        </ul>
+                    )}
+                </>
+            )}
+
+            <p className="mt-5 text-[12px] text-muted">
+                Development-only, and returns 404 in a production build. Your view itself
+                never uses the API key and never chooses a workspace — the board it is
+                mounted in tells it which one, with the permissions of whoever is looking.
+            </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.1",
+    "version": "1.0.3",
     "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,7 @@
         "postcss.config.mjs",
         "tsconfig.json",
         "conexus.manifest.json",
+        ".env",
         "README.md",
         ".gitignore"
     ]