@amtp/protocol 1.0.1

package/dist/server/examples/basic-server.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Basic AMTP Server Example
+ *
+ * Run with: npm run server
+ */
+export {};

package/dist/server/examples/basic-server.js

@@ -0,0 +1,215 @@
+"use strict";
+/**
+ * Basic AMTP Server Example
+ *
+ * Run with: npm run server
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const amtp_server_js_1 = require("../amtp-server.js");
+const amtp_types_js_1 = require("../../types/amtp.types.js");
+const server = new amtp_server_js_1.AMTPServer({
+    port: parseInt(process.env.PORT || "3000", 10),
+    host: "0.0.0.0",
+    enableCORS: true,
+    enableCompression: true,
+    enableRateLimit: true,
+});
+// Register a simple product page
+server.register("GET", "/products/:id", (req, res) => {
+    const { id } = req.params;
+    const doc = {
+        type: "document",
+        version: "1.0",
+        title: `Product ${id}`,
+        path: `/products/${id}`,
+        nodes: [
+            { type: amtp_types_js_1.MarkdownNodeType.PARAGRAPH, content: `This is the AMTP representation of product ${id}.` },
+            { type: amtp_types_js_1.MarkdownNodeType.PARAGRAPH, content: "Details: Price $99.99 In stock Yes" },
+        ],
+        actions: [
+            { id: "BUY", label: "Buy Now", method: amtp_types_js_1.HTTPMethod.POST, endpoint: `/products/${id}/buy` },
+            { id: "ADD_TO_CART", label: "Add to Cart", method: amtp_types_js_1.HTTPMethod.POST, endpoint: `/products/${id}/cart` },
+        ],
+        links: [
+            { text: "Reviews", url: `/products/${id}/reviews`, type: amtp_types_js_1.LinkType.INTERNAL },
+            { text: "Related", url: "/products/related", type: amtp_types_js_1.LinkType.INTERNAL },
+        ],
+        metadata: { productId: id },
+        forms: [],
+        structured_data: [],
+    };
+    res.json(doc);
+});
+// Simple action handler
+server.register("POST", "/products/:id/buy", (req, res) => {
+    const { id } = req.params;
+    const { quantity = 1 } = req.body || {};
+    const doc = {
+        type: "document",
+        version: "1.0",
+        title: "Purchase Complete",
+        path: `/products/${id}/buy`,
+        nodes: [
+            { type: amtp_types_js_1.MarkdownNodeType.PARAGRAPH, content: `Thank you! Purchased ${quantity} of product ${id}.` },
+        ],
+        actions: [],
+        links: [{ text: "Back to product", url: `/products/${id}`, type: amtp_types_js_1.LinkType.INTERNAL }],
+        metadata: {},
+        forms: [],
+        structured_data: [],
+    };
+    // v2.0: Emit live notification (picked up by SSE and webhooks)
+    notifications_1.notificationBus.emitEvent({
+        id: `evt_${Date.now()}`,
+        type: "order.updated",
+        timestamp: new Date().toISOString(),
+        data: { productId: id, quantity, status: "purchased" },
+    });
+    res.status(201).json(doc);
+});
+// Batch action handler (v1.1 stub)
+server.register("POST", "/api/amtp/batch", (req, res) => {
+    const body = req.body || {};
+    const results = (body.actions || []).map((item, idx) => ({
+        actionId: item.action,
+        requestId: item.requestId || `req_${idx}`,
+        status: "success",
+        result: { processed: true, batch: true, echo: item.parameters || {} },
+    }));
+    const response = {
+        batchId: body.batchId || `batch_${Date.now()}`,
+        status: "success",
+        results,
+    };
+    res.json(response);
+});
+// AMTP-QL endpoint (v2.0) — query the document with a tiny GraphQL-like language
+server.register("POST", "/api/amtp/query", async (req, res) => {
+    const body = (req.body || {});
+    // Demo document rich enough to exercise all AMTP-QL projections
+    const demoDoc = {
+        type: "document",
+        version: "2.0",
+        title: "AMTP-QL Demo Product",
+        path: "/demo/ql",
+        nodes: [
+            { type: amtp_types_js_1.MarkdownNodeType.HEADING, content: "Overview" },
+            { type: amtp_types_js_1.MarkdownNodeType.PARAGRAPH, content: "This is a demonstration document for AMTP-QL." },
+            { type: amtp_types_js_1.MarkdownNodeType.PARAGRAPH, content: "It contains actions, forms, structured data and pagination." },
+        ],
+        actions: [
+            { id: "BUY", label: "Buy", method: amtp_types_js_1.HTTPMethod.POST, endpoint: "/demo/buy", description: "Purchase item" },
+            { id: "WISHLIST", label: "Add to Wishlist", method: amtp_types_js_1.HTTPMethod.POST, endpoint: "/demo/wishlist" },
+        ],
+        forms: [
+            { id: "review", action: "/demo/review", method: amtp_types_js_1.HTTPMethod.POST, endpoint: "/demo/review", fields: [
+                    { name: "rating", type: "number", required: true },
+                    { name: "comment", type: "string" },
+                ] },
+        ],
+        links: [
+            { text: "Docs", url: "/docs", type: amtp_types_js_1.LinkType.EXTERNAL },
+        ],
+        metadata: { pageType: "product", category: "demo" },
+        structured_data: [
+            { "@type": "Product", data: { price: 199, currency: "USD", inStock: true } },
+        ],
+        pagination: {
+            pageInfo: { hasNextPage: true, hasPreviousPage: false, startCursor: "c1", endCursor: "c2" },
+            nextCursor: "c2",
+            itemsPerPage: 10,
+            totalItems: 42,
+        },
+    };
+    const result = await server.handleAMTPQL(body, () => demoDoc);
+    res.json(result);
+});
+// =====================================================
+// v2.0: Webhook + SSE Push Notifications
+// =====================================================
+const notifications_1 = require("../notifications");
+const amtp_types_1 = require("../../types/amtp.types");
+// Register a webhook (agent provides URL to receive POSTs)
+server.register("POST", "/api/webhooks", (req, res) => {
+    const { url, events, secret, description } = req.body || {};
+    if (!url || !events?.length) {
+        return res.status(400).json({ error: "url and events are required" });
+    }
+    const sub = notifications_1.notificationBus.registerWebhook({
+        url,
+        events,
+        secret,
+        description,
+    });
+    res.status(201).json({
+        subscription: sub,
+        testCommand: `curl -X POST ${url} -H "Content-Type: application/json" -d '{"type":"test"}'`,
+    });
+});
+// List webhooks
+server.register("GET", "/api/webhooks", (_req, res) => {
+    res.json({ webhooks: notifications_1.notificationBus.listWebhooks() });
+});
+// Delete webhook
+server.register("DELETE", "/api/webhooks/:id", (req, res) => {
+    const ok = notifications_1.notificationBus.deleteWebhook(req.params.id);
+    res.json({ deleted: ok });
+});
+// SSE Stream - agents connect here for live updates
+// Example: GET /api/amtp/stream?events=order.updated,workspace.updated
+server.register("GET", "/api/amtp/stream", (req, res) => {
+    const requestedEvents = (req.query.events || "").split(",").filter(Boolean);
+    res.setHeader("Content-Type", "text/event-stream");
+    res.setHeader("Cache-Control", "no-cache");
+    res.setHeader("Connection", "keep-alive");
+    res.setHeader("X-Accel-Buffering", "no"); // disable nginx buffering
+    const sendEvent = (event) => {
+        res.write(`event: ${event.type}\n`);
+        res.write(`data: ${JSON.stringify(event)}\n\n`);
+    };
+    const unsubscribe = notifications_1.notificationBus.subscribeSSE(requestedEvents.length ? requestedEvents : Object.values(amtp_types_1.NotificationEventType), sendEvent);
+    // Send initial heartbeat
+    res.write(`: connected\n\n`);
+    req.on("close", () => {
+        unsubscribe();
+    });
+});
+// Demo: emit a notification when a buy happens (in the buy handler above, we can call this)
+// For demo, expose an endpoint to manually emit
+server.register("POST", "/api/demo/emit", (req, res) => {
+    const { type, data } = req.body || {};
+    const event = {
+        id: `evt_${Date.now()}`,
+        type: type || "order.updated",
+        timestamp: new Date().toISOString(),
+        data: data || { demo: true },
+    };
+    notifications_1.notificationBus.emitEvent(event);
+    res.json({ emitted: event });
+});
+// Health
+server.register("GET", "/health", (_req, res) => {
+    res.json({ status: "ok", protocol: "AMTP", version: "1.0" });
+});
+// Home
+server.register("GET", "/", (_req, res) => {
+    const doc = {
+        type: "document",
+        version: "1.0",
+        title: "AMTP Basic Server",
+        path: "/",
+        nodes: [
+            { type: amtp_types_js_1.MarkdownNodeType.PARAGRAPH, content: "Welcome to the basic AMTP reference server." },
+            { type: amtp_types_js_1.MarkdownNodeType.PARAGRAPH, content: "Try: GET /products/demo with Accept: text/amtp+markdown" },
+        ],
+        actions: [],
+        links: [{ text: "Product Demo", url: "/products/demo", type: amtp_types_js_1.LinkType.INTERNAL }],
+        metadata: {},
+        forms: [],
+        structured_data: [],
+    };
+    res.json(doc);
+});
+server.start().catch(console.error);
+console.log("Basic AMTP server example starting...");
+//# sourceMappingURL=basic-server.js.map

package/dist/server/examples/basic-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"basic-server.js","sourceRoot":"","sources":["../../../src/server/examples/basic-server.ts"],"names":[],"mappings":"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"}

package/dist/server/examples/saas-dashboard-server.d.ts

@@ -0,0 +1,44 @@
+/**
+ * AMTP — SaaS Multi-Tenant Workspace Dashboard  (Example Server)
+ *
+ * Demonstrates AMTP used as the primary API surface for a real
+ * SaaS application: shared-workspace project-management tool with
+ * SQLite persistence and JWT authentication.
+ *
+ * Schema (sqlite3)
+ * ┌────────────────────────────────────────────────┐
+ * │ tenants        │ users                          │
+ * │─────────────── │───────────────────────────────│
+ * │ id TEXT PK     │ id TEXT PK                    │
+ * │ name TEXT      │ tenantId TEXT FK → tenants    │
+ * │ plan TEXT      │ email TEXT UNIQUE             │
+ * │ createdAt TEXT │ passwordHash TEXT             │
+ * │               │ name TEXT                     │
+ * │               │ role TEXT (owner|admin|member) │
+ * │               │ createdAt TEXT                │
+ * ├───────────────┴───────────────────────────────┤
+ * │ workspaces                                          │
+ * │────────────────────────────────────────────────────│
+ * │ id TEXT PK                                         │
+ * │ tenantId TEXT FK → tenants                         │
+ * │ name TEXT                                          │
+ * │ description TEXT                                   │
+ * │ createdAt TEXT                                     │
+ * │ updatedAt TEXT                                     │
+ * │────────────────── ─ ──────────────────────────────│
+ * │ workspace_members                                   │
+ * │────────────────────────────────────────────────────│
+ * │ workspaceId TEXT FK → workspaces                    │
+ * │ userId TEXT FK → users                               │
+ * │ role TEXT (owner|editor|viewer)                      │
+ * │ joinedAt TEXT                                        │
+ * │ PRIMARY KEY (workspaceId, userId)                    │
+ * └────────────────────────────────────────────────────┘
+ *
+ * Run:
+ *   npm run server:saas
+ *   # or
+ *   ts-node src/server/examples/saas-dashboard-server.ts
+ */
+declare const app: import("express-serve-static-core").Express;
+export default app;

package/dist/server/examples/saas-dashboard-server.js

@@ -0,0 +1,387 @@
+"use strict";
+/**
+ * AMTP — SaaS Multi-Tenant Workspace Dashboard  (Example Server)
+ *
+ * Demonstrates AMTP used as the primary API surface for a real
+ * SaaS application: shared-workspace project-management tool with
+ * SQLite persistence and JWT authentication.
+ *
+ * Schema (sqlite3)
+ * ┌────────────────────────────────────────────────┐
+ * │ tenants        │ users                          │
+ * │─────────────── │───────────────────────────────│
+ * │ id TEXT PK     │ id TEXT PK                    │
+ * │ name TEXT      │ tenantId TEXT FK → tenants    │
+ * │ plan TEXT      │ email TEXT UNIQUE             │
+ * │ createdAt TEXT │ passwordHash TEXT             │
+ * │               │ name TEXT                     │
+ * │               │ role TEXT (owner|admin|member) │
+ * │               │ createdAt TEXT                │
+ * ├───────────────┴───────────────────────────────┤
+ * │ workspaces                                          │
+ * │────────────────────────────────────────────────────│
+ * │ id TEXT PK                                         │
+ * │ tenantId TEXT FK → tenants                         │
+ * │ name TEXT                                          │
+ * │ description TEXT                                   │
+ * │ createdAt TEXT                                     │
+ * │ updatedAt TEXT                                     │
+ * │────────────────── ─ ──────────────────────────────│
+ * │ workspace_members                                   │
+ * │────────────────────────────────────────────────────│
+ * │ workspaceId TEXT FK → workspaces                    │
+ * │ userId TEXT FK → users                               │
+ * │ role TEXT (owner|editor|viewer)                      │
+ * │ joinedAt TEXT                                        │
+ * │ PRIMARY KEY (workspaceId, userId)                    │
+ * └────────────────────────────────────────────────────┘
+ *
+ * Run:
+ *   npm run server:saas
+ *   # or
+ *   ts-node src/server/examples/saas-dashboard-server.ts
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = __importDefault(require("express"));
+const sqlite3_1 = require("sqlite3");
+const crypto_1 = __importDefault(require("crypto"));
+// @ts-ignore - bcryptjs has no types, used only in this demo server
+const bcryptjs_1 = __importDefault(require("bcryptjs"));
+// @ts-ignore - jsonwebtoken has no bundled types in this setup
+const jsonwebtoken_1 = require("jsonwebtoken");
+const amtp_server_js_1 = require("../amtp-server.js");
+const amtp_types_js_1 = require("../../types/amtp.types.js");
+/* ================================================================
+   CONFIGURATION
+   ================================================================ */
+const PORT = parseInt(process.env.AMTP_PORT || "3000", 10);
+const JWT_SECRET = process.env.JWT_SECRET || "amtp-saas-jwt-dev-change-me";
+const DB_PATH = process.env.DB_PATH || "./.workspace.db";
+/* ================================================================
+   DATABASE — SCHEMA + SEED
+   ================================================================ */
+const sqlite = new sqlite3_1.Database(DB_PATH);
+sqlite.serialize(() => {
+    // Tenants
+    sqlite.run(`
+    CREATE TABLE IF NOT EXISTS tenants (
+      id          TEXT PRIMARY KEY,
+      name        TEXT NOT NULL,
+      plan        TEXT NOT NULL DEFAULT 'free',
+      createdAt   TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+  `);
+    // Users (per tenant)
+    sqlite.run(`
+    CREATE TABLE IF NOT EXISTS users (
+      id              TEXT PRIMARY KEY,
+      tenantId        TEXT NOT NULL REFERENCES tenants(id),
+      email           TEXT NOT NULL UNIQUE,
+      passwordHash    TEXT NOT NULL,
+      name            TEXT NOT NULL,
+      role            TEXT NOT NULL CHECK(role IN ('owner','admin','member')),
+      createdAt       TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+  `);
+    // Workspaces
+    sqlite.run(`
+    CREATE TABLE IF NOT EXISTS workspaces (
+      id          TEXT PRIMARY KEY,
+      tenantId    TEXT NOT NULL REFERENCES tenants(id),
+      name        TEXT NOT NULL,
+      description TEXT DEFAULT '',
+      createdAt   TEXT NOT NULL DEFAULT (datetime('now')),
+      updatedAt   TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+  `);
+    // Workspace members
+    sqlite.run(`
+    CREATE TABLE IF NOT EXISTS workspace_members (
+      workspaceId TEXT NOT NULL REFERENCES workspaces(id),
+      userId      TEXT NOT NULL REFERENCES users(id),
+      role        TEXT NOT NULL CHECK(role IN ('owner','editor','viewer')),
+      joinedAt    TEXT NOT NULL DEFAULT (datetime('now')),
+      PRIMARY KEY (workspaceId, userId)
+    )
+  `);
+    // Seed a demo tenant + user if empty
+    sqlite.get("SELECT COUNT(*) AS c FROM tenants", (err, row) => {
+        if (err || row.c > 0)
+            return;
+        const tenantId = "t_demo";
+        sqlite.run(`INSERT INTO tenants (id, name, plan) VALUES (?, ?, ?)`, [
+            tenantId, "Demo Tenant", "pro",
+        ], () => {
+            const userId = "u_demo";
+            const pwd = "demo-password";
+            bcryptjs_1.default.hash(pwd, 10, (err2, hash) => {
+                if (err2)
+                    return console.error("BCRYPT ERROR", err2);
+                sqlite.run(`INSERT INTO users (id, tenantId, email, passwordHash, name, role) VALUES (?,?,?,?,?,?)`, [userId, tenantId, "demo@example.com", hash, "Demo User", "owner"], () => {
+                    const wsId = "w_main";
+                    sqlite.run(`INSERT INTO workspaces (id, tenantId, name, description) VALUES (?,?,?,?)`, [wsId, tenantId, "Main Workspace", "Primary demo workspace"], () => {
+                        sqlite.run(`INSERT INTO workspace_members (workspaceId, userId, role) VALUES (?,?,?)`, [wsId, userId, "owner"]);
+                    });
+                });
+            });
+        });
+    });
+});
+/* ================================================================
+   AUTH HELPERS
+   ================================================================ */
+function genId(prefix) {
+    return `${prefix}_${Date.now().toString(36)}_${crypto_1.default.randomBytes(4).toString("hex")}`;
+}
+function signJwt(userId, tenantId, role) {
+    return (0, jsonwebtoken_1.sign)({ userId, tenantId, role }, JWT_SECRET, { expiresIn: "24h" });
+}
+function requireAuth(req) {
+    const header = (req.header("authorization") || "").replace(/^Bearer\s+/, "");
+    if (!header)
+        return null;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const decoded = (0, jsonwebtoken_1.verify)(header, JWT_SECRET);
+        return decoded;
+    }
+    catch {
+        return null;
+    }
+}
+function tenantGuard(db, user, callback) {
+    db.get("SELECT role, tenantId FROM users WHERE id = ?", [user.userId], (err, row) => {
+        if (err || !row)
+            return callback("UNAUTHORIZED");
+        callback(row.tenantId);
+    });
+}
+/* ================================================================
+   REST API — AUTH & TENANT CRUD
+   ================================================================ */
+const app = (0, express_1.default)();
+app.use(express_1.default.json());
+/* ── Health ── */
+app.get("/health", (_req, res) => res.json({ status: "ok", service: "amtp-saas-dashboard" }));
+/* ── Register ── */
+app.post("/api/v1/auth/register", (req, res) => {
+    const { tenantName, email, password, name } = req.body || {};
+    if (!tenantName || !email || !password || !name) {
+        return res.status(400).json({ error: "tenantName, email, password, name are required" });
+    }
+    const tenantId = genId("t");
+    const userId = genId("u");
+    bcryptjs_1.default.hash(password, 10, (err, hash) => {
+        if (err)
+            return res.status(500).json({ error: "hasher error" });
+        sqlite.serialize(() => {
+            sqlite.run("INSERT INTO tenants (id, name) VALUES (?,?)", [tenantId, tenantName], () => {
+                sqlite.run("INSERT INTO users (id, tenantId, email, passwordHash, name, role) VALUES (?,?,?,?,?,?)", [userId, tenantId, email, hash, name, "owner"], () => {
+                    const wsId = genId("w");
+                    sqlite.run("INSERT INTO workspaces (id, tenantId, name) VALUES (?,?,?)", [wsId, tenantId, name], () => {
+                        sqlite.run("INSERT INTO workspace_members (workspaceId, userId, role) VALUES (?,?,?)", [wsId, userId, "owner"], () => {
+                            const token = signJwt(userId, tenantId, "owner");
+                            res.status(201).json({ token, tenantId, userId, name, role: "owner" });
+                        });
+                    });
+                });
+            });
+        });
+    });
+});
+/* ── Login ── */
+app.post("/api/v1/auth/login", (req, res) => {
+    const { email, password } = req.body || {};
+    if (!email || !password)
+        return res.status(400).json({ error: "email + password required" });
+    sqlite.get("SELECT * FROM users WHERE email = ?", [email], (err2, user) => {
+        if (err2 || !user)
+            return res.status(401).json({ error: "Invalid credentials" });
+        bcryptjs_1.default.compare(password, user.passwordHash, (err3, ok) => {
+            if (err3 || !ok)
+                return res.status(401).json({ error: "Invalid credentials" });
+            res.json({ token: signJwt(user.id, user.tenantId, user.role), userId: user.id, tenantId: user.tenantId, role: user.role });
+        });
+    });
+});
+/* ── Me ── */
+app.get("/api/v1/me", (req, res) => {
+    const user = requireAuth(req);
+    if (!user)
+        return res.status(401).json({ error: "Unauthorized" });
+    sqlite.get("SELECT id, email, name, role, createdAt FROM users WHERE id = ?", [user.userId], (err, row) => {
+        if (err || !row)
+            return res.status(404).json({ error: "Not found" });
+        res.json(row);
+    });
+});
+/* ── Workspaces ── */
+app.get("/api/v1/workspaces", (req, res) => {
+    const user = requireAuth(req);
+    if (!user)
+        return res.status(401).json({ error: "Unauthorized" });
+    const sql = `
+    SELECT w.*, wm.role AS myRole
+      FROM workspaces w
+      JOIN workspace_members wm ON w.id = wm.workspaceId
+     WHERE wm.userId = ?
+     ORDER BY w.updatedAt DESC
+  `;
+    sqlite.all(sql, [user.userId], (err, rows) => {
+        if (err)
+            return res.status(500).json({ error: err.message });
+        res.json(rows);
+    });
+});
+app.post("/api/v1/workspaces", (req, res) => {
+    const user = requireAuth(req);
+    if (!user)
+        return res.status(401).json({ error: "Unauthorized" });
+    const { name, description } = req.body || {};
+    if (!name)
+        return res.status(400).json({ error: "name is required" });
+    const wsId = genId("w");
+    sqlite.run("INSERT INTO workspaces (id, tenantId, name, description) VALUES (?,?,?,?)", [wsId, user.tenantId, name, description || ""], (err) => {
+        if (err)
+            return res.status(500).json({ error: err.message });
+        sqlite.run("INSERT INTO workspace_members (workspaceId, userId, role) VALUES (?,?,?)", [wsId, user.userId, "owner"], () => {
+            res.status(201).json({ id: wsId, name, description: description || "", myRole: "owner" });
+        });
+    });
+});
+app.get("/api/v1/workspaces/:id", (req, res) => {
+    const user = requireAuth(req);
+    if (!user)
+        return res.status(401).json({ error: "Unauthorized" });
+    const { id } = req.params;
+    sqlite.get(`SELECT w.*, wm.role AS myRole
+       FROM workspaces w
+       JOIN workspace_members wm ON w.id = wm.workspaceId
+      WHERE w.id = ? AND wm.userId = ?`, [id, user.userId], (err, row) => {
+        if (err)
+            return res.status(500).json({ error: err.message });
+        if (!row)
+            return res.status(404).json({ error: "Workspace not found" });
+        res.json(row);
+    });
+});
+app.delete("/api/v1/workspaces/:id", (req, res) => {
+    const user = requireAuth(req);
+    if (!user)
+        return res.status(401).json({ error: "Unauthorized" });
+    const { id } = req.params;
+    sqlite.run("DELETE FROM workspaces WHERE id = ?", [id], (err) => {
+        if (err)
+            return res.status(500).json({ error: err.message });
+        res.status(204).send("");
+    });
+});
+/* ── Members ── */
+app.get("/api/v1/workspaces/:wId/members", (req, res) => {
+    const user = requireAuth(req);
+    if (!user)
+        return res.status(401).json({ error: "Unauthorized" });
+    const { wId } = req.params;
+    sqlite.get("SELECT 1 AS ok FROM workspace_members WHERE workspaceId=? AND userId=?", [wId, user.userId], (err, row) => {
+        if (err || !row)
+            return res.status(403).json({ error: "Access denied" });
+        sqlite.all(`SELECT u.id, u.email, u.name, u.role, wm.role AS memberRole, wm.joinedAt
+         FROM workspace_members wm
+         JOIN users u ON wm.userId = u.id
+        WHERE wm.workspaceId = ?`, [wId], (err2, rows) => { if (err2)
+            return res.status(500).json({ error: err2.message }); res.json(rows); });
+    });
+});
+/* ── AMTP HTML muxer ── */
+app.get("/amtp/*", (req, res) => {
+    const authHeader = (req.header("authorization") || "");
+    const accept = (req.header("accept") || "");
+    const isAmtp = accept.includes("amtp") || accept.includes("markdown");
+    if (isAmtp && authHeader) {
+        const me = requireAuth(req);
+        if (!me)
+            return res.status(401).json({ error: "Unauthorized" });
+        sqlite.all(`SELECT w.*, wm.role AS myRole
+         FROM workspaces w
+         JOIN workspace_members wm ON w.id = wm.workspaceId
+        WHERE w.tenantId = ?
+        ORDER BY w.updatedAt DESC LIMIT 20`, [me.tenantId], (_err, rows) => {
+            if (_err)
+                return res.status(500).json({ error: _err.message });
+            const lines = [
+                `# Workspaces`,
+                "",
+                `Welcome back — ${rows.length} workspace(s)`,
+                "",
+                ...["", "## Actions", "[CREATE_WORKSPACE] — Create a new workspace", "", "## Workspaces"]
+                    .concat(rows.map((w) => `[${w.name}](/api/v1/workspaces/${w.id})`))
+                    .concat([""]),
+            ].join("\n");
+            const builder = new amtp_server_js_1.AMTPResponseBuilder();
+            const { headers, body } = builder.build(lines, {
+                sessionId: `sess_${me.userId}`,
+            });
+            res.setHeader("content-type", amtp_types_js_1.MIMEType.AMTP_MARKDOWN);
+            for (const [k, v] of Object.entries(headers)) {
+                if (v !== undefined)
+                    res.setHeader(k, v);
+            }
+            res.send(body);
+        });
+    }
+    else {
+        const simpleHTML = `<!DOCTYPE html><html><body><h1>AMTP SaaS Dashboard</h1><p>Use the <tt>Accept: text/amtp+markdown</tt> header to get AMTP documents, or open the <a href="/amtp/workspaces">AMTP overview</a>.</p></body></html>`;
+        res.setHeader("content-type", "text/html");
+        res.send(simpleHTML);
+    }
+});
+/* ── Root landing with content negotiation ── */
+app.get("/", (req, res) => {
+    const accept = (req.header("accept") || "");
+    const isAmtp = accept.includes("amtp") || accept.includes("markdown");
+    if (isAmtp) {
+        const md = `# AMTP SaaS Dashboard\n\nMulti-tenant workspace demo powered by AMTP.\n\nUse Authorization: Bearer <token> for authenticated AMTP routes under /amtp/*\n\n## Demo\n\n- Login: POST /api/v1/auth/login\n- AMTP Workspaces: GET /amtp/workspaces\n\n## Actions\n\n[LOGIN] [VIEW_WORKSPACES]`;
+        const builder = new amtp_server_js_1.AMTPResponseBuilder();
+        const { headers, body } = builder.build(md);
+        res.setHeader("content-type", amtp_types_js_1.MIMEType.AMTP_MARKDOWN);
+        for (const [k, v] of Object.entries(headers)) {
+            if (v !== undefined)
+                res.setHeader(k, v);
+        }
+        res.send(body);
+    }
+    else {
+        res.setHeader("content-type", "text/html");
+        res.send(`<!DOCTYPE html><html><body><h1>AMTP SaaS Dashboard</h1><p>AMTP-enabled demo. <a href="/amtp/workspaces">Try AMTP view</a> (use Accept header for full experience).</p></body></html>`);
+    }
+});
+/* ================================================================
+   START
+   ================================================================ */
+app.listen(PORT, () => {
+    sqlite.serialize(() => {
+        sqlite.each("SELECT * FROM tenants", (_err, _row) => { });
+    });
+    const tenantRows = [
+        "╔════════════════════════════════════════════════════════════════╗",
+        "║       AMTP SaaS Dashboard — Dev Server (SQLite)               ║",
+        "╠════════════════════════════════════════════════════════════════╣",
+    ];
+    console.log(tenantRows.join("\n"));
+    console.log(`║  🚀  Server     : http://localhost:${PORT}/                            ║`);
+    console.log(`║  📊  Workspaces : GET http://localhost:${PORT}/amtp/workspaces      ║`);
+    console.log(`║  🔑  Login      : POST http://localhost:${PORT}/api/v1/auth/login     ║`);
+    console.log(`║                                                                 ║`);
+    console.log(`║  Demo user : demo@example.com / demo-password                  ║`);
+    console.log(`╚════════════════════════════════════════════════════════════════╝\n`);
+});
+process.on("SIGINT", () => {
+    console.log("\n[amtp-saas] Shutting down...");
+    sqlite.close();
+    process.exit(0);
+});
+exports.default = app;
+//# sourceMappingURL=saas-dashboard-server.js.map