@vitrion/zentria-mcp 1.0.0

package/dist/zentria/client.js

@@ -0,0 +1,90 @@
+import { PACKAGE_NAME, PACKAGE_VERSION } from "../version.js";
+import { ZentriaError, ZentriaRateLimitError, parseRetryAfter, zentriaErrorFromResponse, } from "./errors.js";
+import { appendQueryParams } from "./query.js";
+export const DEFAULT_BASE_URL = "https://app.zentria.nl";
+export const USER_AGENT = `${PACKAGE_NAME}/${PACKAGE_VERSION}`;
+export function normalizeBaseUrl(raw) {
+    return raw
+        .replace(/\/+$/, "")
+        .replace(/\/api\/public$/i, "")
+        .replace(/\/api\/v1$/i, "");
+}
+export class ZentriaClient {
+    apiKey;
+    baseUrl;
+    fetchImpl;
+    meCache = null;
+    constructor(options = {}) {
+        const apiKey = options.apiKey ?? process.env.ZENTRIA_API_KEY ?? process.env.ZENTRIA_API_TOKEN;
+        if (!apiKey) {
+            throw new Error("ZENTRIA_API_KEY environment variable is required");
+        }
+        this.apiKey = apiKey;
+        this.baseUrl = normalizeBaseUrl(options.baseUrl ?? process.env.ZENTRIA_BASE_URL ?? DEFAULT_BASE_URL);
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async request(options) {
+        return this.executeRequest(options, false);
+    }
+    async getMe(force = false) {
+        if (!force && this.meCache) {
+            return this.meCache;
+        }
+        const me = (await this.request({ path: "/api/public/me" }));
+        this.meCache = me;
+        return me;
+    }
+    async getBoundTeamId() {
+        const me = await this.getMe();
+        const teamId = me.currentTeam?.id;
+        if (teamId === undefined || teamId === null) {
+            throw new Error("API key is not bound to a team — GET /api/public/me returned no currentTeam.id");
+        }
+        return teamId;
+    }
+    async executeRequest(options, isRetry) {
+        const method = options.method ?? "GET";
+        const path = appendQueryParams(options.path, options.query);
+        const url = `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: options.accept ?? "application/json",
+            "User-Agent": USER_AGENT,
+        };
+        let body;
+        if (options.body !== undefined && method !== "GET") {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(options.body);
+        }
+        const response = await this.fetchImpl(url, { method, headers, body });
+        if (response.status === 429 && !isRetry) {
+            const retryAfter = parseRetryAfter(response.headers) ?? 1;
+            await sleep(retryAfter * 1000);
+            return this.executeRequest(options, true);
+        }
+        if (!response.ok) {
+            const errorBody = await readResponseBody(response);
+            throw zentriaErrorFromResponse(response.status, errorBody, response.headers);
+        }
+        if (response.status === 204) {
+            return { ok: true };
+        }
+        return readResponseBody(response);
+    }
+}
+async function readResponseBody(response) {
+    const text = await response.text();
+    if (!text) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export { ZentriaError, ZentriaRateLimitError };

package/dist/zentria/errors.js

@@ -0,0 +1,93 @@
+export class ZentriaError extends Error {
+    status;
+    details;
+    constructor(status, message, details) {
+        super(message);
+        this.name = "ZentriaError";
+        this.status = status;
+        this.details = details;
+    }
+}
+export class ZentriaUnauthorizedError extends ZentriaError {
+    constructor(message = "Unauthorized — check ZENTRIA_API_KEY") {
+        super(401, message);
+        this.name = "ZentriaUnauthorizedError";
+    }
+}
+export class ZentriaForbiddenError extends ZentriaError {
+    constructor(message = "Forbidden — check API key scopes, modules, or team permissions") {
+        super(403, message);
+        this.name = "ZentriaForbiddenError";
+    }
+}
+export class ZentriaNotFoundError extends ZentriaError {
+    constructor(message = "Resource not found") {
+        super(404, message);
+        this.name = "ZentriaNotFoundError";
+    }
+}
+export class ZentriaValidationError extends ZentriaError {
+    constructor(message, details) {
+        super(422, message, details);
+        this.name = "ZentriaValidationError";
+    }
+}
+export class ZentriaRateLimitError extends ZentriaError {
+    retryAfter;
+    constructor(message, retryAfter) {
+        super(429, message);
+        this.name = "ZentriaRateLimitError";
+        this.retryAfter = retryAfter;
+    }
+}
+export function zentriaErrorFromResponse(status, body, headers) {
+    const messageFromBody = extractErrorMessage(body);
+    switch (status) {
+        case 401:
+            return new ZentriaUnauthorizedError(messageFromBody);
+        case 403:
+            return new ZentriaForbiddenError(messageFromBody);
+        case 404:
+            return new ZentriaNotFoundError(messageFromBody);
+        case 422:
+            return new ZentriaValidationError(messageFromBody ?? "Validation failed", body);
+        case 429: {
+            const retryAfter = parseRetryAfter(headers);
+            return new ZentriaRateLimitError(messageFromBody ?? "Rate limit exceeded", retryAfter);
+        }
+        default:
+            return new ZentriaError(status, messageFromBody ?? `Zentria API request failed with status ${status}`, body);
+    }
+}
+function extractErrorMessage(body) {
+    if (typeof body === "string" && body.trim()) {
+        return body;
+    }
+    if (!body || typeof body !== "object") {
+        return undefined;
+    }
+    const record = body;
+    if (typeof record.detail === "string") {
+        return record.detail;
+    }
+    if (typeof record.message === "string") {
+        return record.message;
+    }
+    if (typeof record.title === "string") {
+        return record.title;
+    }
+    if (typeof record.error === "string") {
+        return record.error;
+    }
+    return undefined;
+}
+export function parseRetryAfter(headers) {
+    const retryAfter = headers.get("Retry-After");
+    if (retryAfter) {
+        const seconds = Number.parseInt(retryAfter, 10);
+        if (!Number.isNaN(seconds)) {
+            return Math.min(seconds, 60);
+        }
+    }
+    return undefined;
+}

package/dist/zentria/query.js

@@ -0,0 +1,28 @@
+export function appendQueryParams(path, query) {
+    if (!query) {
+        return path;
+    }
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined && value !== null && value !== "") {
+            params.set(key, String(value));
+        }
+    }
+    const qs = params.toString();
+    return qs ? `${path}?${qs}` : path;
+}
+export function collectionItems(body) {
+    if (Array.isArray(body)) {
+        return body;
+    }
+    if (body && typeof body === "object") {
+        const record = body;
+        if (Array.isArray(record.member)) {
+            return record.member;
+        }
+        if (Array.isArray(record["hydra:member"])) {
+            return record["hydra:member"];
+        }
+    }
+    return [];
+}

package/dist/zentria/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@vitrion/zentria-mcp",
+  "version": "1.0.0",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "description": "Zentria MCP server — public team API for AI assistants via Model Context Protocol",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "zentria-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "inspector": "npx @modelcontextprotocol/inspector node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "zentria",
+    "crm",
+    "sales",
+    "api"
+  ],
+  "author": {
+    "name": "Vitrion",
+    "email": "hello@vitrion.nl"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vitrionbv/zentria-mcp.git"
+  },
+  "homepage": "https://github.com/vitrionbv/zentria-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/vitrionbv/zentria-mcp/issues"
+  }
+}