mcp-grampsweb 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# mcp-grampsweb
+
+An MCP (Model Context Protocol) server for interacting with [Gramps Web](https://www.grampsweb.org/) genealogy API. This allows AI assistants like Claude to search, retrieve, and create genealogical records in your Gramps Web instance.
+
+## Installation
+
+```bash
+npx mcp-grampsweb
+```
+
+Or install globally:
+
+```bash
+npm install -g mcp-grampsweb
+```
+
+## Configuration
+
+The server requires the following environment variables:
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `GRAMPS_API_URL` | Base URL of your Gramps Web instance (e.g., `https://gramps.example.com`) | Yes |
+| `GRAMPS_USERNAME` | Your Gramps Web username | Yes |
+| `GRAMPS_PASSWORD` | Your Gramps Web password | Yes |
+| `GRAMPS_TREE_ID` | Tree ID for multi-tree instances (requests use `/api/trees/{id}/...`) | No |
+
+## Usage with Claude Desktop
+
+Add the following to your Claude Desktop configuration file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "grampsweb": {
+      "command": "npx",
+      "args": ["mcp-grampsweb"],
+      "env": {
+        "GRAMPS_API_URL": "https://your-gramps-web.com",
+        "GRAMPS_USERNAME": "your-username",
+        "GRAMPS_PASSWORD": "your-password",
+        "GRAMPS_TREE_ID": "optional-tree-id"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Search & Retrieval
+
+| Tool | Description |
+|------|-------------|
+| `gramps_search` | GQL-based search for any entity type (people, families, events, places, etc.) |
+| `gramps_find` | Full-text search across all records |
+| `gramps_get` | Get full entity details by handle or Gramps ID |
+
+### Data Management
+
+| Tool | Description |
+|------|-------------|
+| `gramps_create_person` | Create a new person record |
+| `gramps_create_family` | Create a new family unit |
+| `gramps_create_event` | Create a new life event (birth, death, marriage, etc.) |
+| `gramps_create_place` | Create a new geographic location |
+| `gramps_create_source` | Create a new source document |
+| `gramps_create_citation` | Create a new citation |
+| `gramps_create_note` | Create a new textual note |
+| `gramps_create_media` | Create a new media object |
+| `gramps_create_repository` | Create a new repository |
+
+### Analysis
+
+| Tool | Description |
+|------|-------------|
+| `gramps_tree_stats` | Get tree statistics (counts of all entity types) |
+| `gramps_get_ancestors` | Find ancestors of a person (up to 10 generations) |
+| `gramps_get_descendants` | Find descendants of a person (up to 10 generations) |
+| `gramps_recent_changes` | Get recently modified records |
+
+## Examples
+
+### Search for people with a specific surname
+
+```
+Use gramps_search to find people with surname "Smith"
+```
+
+### Get ancestors of a person
+
+```
+Find the ancestors of person with handle "abc123" going back 4 generations
+```
+
+### Create a new person
+
+```
+Create a person named John Smith, male gender
+```
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/nikkoxgonzales/mcp-grampsweb.git
+cd mcp-grampsweb
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Run in development mode
+npm run dev
+```
+
+### Testing with MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,37 @@
+/**
+ * JWT Authentication singleton for Gramps Web API
+ */
+import type { Config } from "./config.js";
+declare class AuthManager {
+    private token;
+    private tokenExpiry;
+    private config;
+    private refreshPromise;
+    /**
+     * Initialize the auth manager with configuration
+     */
+    initialize(config: Config): void;
+    /**
+     * Get a valid access token, refreshing if necessary
+     */
+    getToken(): Promise<string>;
+    /**
+     * Force a token refresh
+     */
+    refreshToken(): Promise<string>;
+    /**
+     * Extract expiry time from JWT token
+     */
+    private extractExpiry;
+    /**
+     * Clear the cached token
+     */
+    clearToken(): void;
+    /**
+     * Check if we have a valid token
+     */
+    hasValidToken(): boolean;
+}
+export declare const authManager: AuthManager;
+export {};
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C,cAAM,WAAW;IACf,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,cAAc,CAAgC;IAEtD;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAMhC;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IA0BjC;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAwCrC;;OAEG;IACH,OAAO,CAAC,aAAa;IA2BrB;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;OAEG;IACH,aAAa,IAAI,OAAO;CAGzB;AAGD,eAAO,MAAM,WAAW,aAAoB,CAAC"}

package/dist/auth.js

@@ -0,0 +1,119 @@
+/**
+ * JWT Authentication singleton for Gramps Web API
+ */
+import { API_ENDPOINTS, TOKEN_EXPIRY_BUFFER_MS } from "./constants.js";
+import { AuthenticationError } from "./utils/errors.js";
+class AuthManager {
+    token = null;
+    tokenExpiry = 0;
+    config = null;
+    refreshPromise = null;
+    /**
+     * Initialize the auth manager with configuration
+     */
+    initialize(config) {
+        this.config = config;
+        this.token = null;
+        this.tokenExpiry = 0;
+    }
+    /**
+     * Get a valid access token, refreshing if necessary
+     */
+    async getToken() {
+        if (!this.config) {
+            throw new AuthenticationError("Auth manager not initialized");
+        }
+        // Return cached token if still valid
+        if (this.token && Date.now() < this.tokenExpiry) {
+            return this.token;
+        }
+        // If already refreshing, wait for that promise
+        if (this.refreshPromise) {
+            return this.refreshPromise;
+        }
+        // Refresh the token
+        this.refreshPromise = this.refreshToken();
+        try {
+            const token = await this.refreshPromise;
+            return token;
+        }
+        finally {
+            this.refreshPromise = null;
+        }
+    }
+    /**
+     * Force a token refresh
+     */
+    async refreshToken() {
+        if (!this.config) {
+            throw new AuthenticationError("Auth manager not initialized");
+        }
+        const url = `${this.config.apiUrl}/api${API_ENDPOINTS.TOKEN}`;
+        // Gramps Web expects form-urlencoded data for token endpoint
+        const body = new URLSearchParams({
+            username: this.config.username,
+            password: this.config.password,
+        });
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: body.toString(),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new AuthenticationError(`Failed to authenticate: ${response.status} ${response.statusText}. ${errorText}`);
+        }
+        const data = (await response.json());
+        if (!data.access_token) {
+            throw new AuthenticationError("No access token in response");
+        }
+        this.token = data.access_token;
+        this.tokenExpiry = this.extractExpiry(data.access_token);
+        return this.token;
+    }
+    /**
+     * Extract expiry time from JWT token
+     */
+    extractExpiry(token) {
+        try {
+            // JWT format: header.payload.signature
+            const parts = token.split(".");
+            if (parts.length !== 3) {
+                // Can't decode, use default expiry (1 hour)
+                return Date.now() + 60 * 60 * 1000 - TOKEN_EXPIRY_BUFFER_MS;
+            }
+            // Decode the payload (base64url)
+            const payload = parts[1];
+            const decoded = Buffer.from(payload, "base64url").toString("utf-8");
+            const parsed = JSON.parse(decoded);
+            if (parsed.exp) {
+                // exp is in seconds, convert to ms and subtract buffer
+                return parsed.exp * 1000 - TOKEN_EXPIRY_BUFFER_MS;
+            }
+            // No exp claim, use default
+            return Date.now() + 60 * 60 * 1000 - TOKEN_EXPIRY_BUFFER_MS;
+        }
+        catch {
+            // Failed to parse, use default expiry
+            return Date.now() + 60 * 60 * 1000 - TOKEN_EXPIRY_BUFFER_MS;
+        }
+    }
+    /**
+     * Clear the cached token
+     */
+    clearToken() {
+        this.token = null;
+        this.tokenExpiry = 0;
+    }
+    /**
+     * Check if we have a valid token
+     */
+    hasValidToken() {
+        return this.token !== null && Date.now() < this.tokenExpiry;
+    }
+}
+// Export singleton instance
+export const authManager = new AuthManager();
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

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

package/dist/client.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Gramps Web API Client
+ */
+import type { Config } from "./config.js";
+export interface RequestOptions {
+    method?: "GET" | "POST" | "PUT" | "DELETE";
+    body?: unknown;
+    params?: Record<string, string | number | boolean | undefined>;
+    timeout?: number;
+}
+declare class GrampsClient {
+    private baseUrl;
+    /**
+     * Initialize the client with configuration
+     */
+    initialize(config: Config): void;
+    /**
+     * Make an authenticated request to the Gramps API
+     */
+    request<T>(endpoint: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Handle error responses
+     */
+    private handleErrorResponse;
+    /**
+     * GET request helper
+     */
+    get<T>(endpoint: string, params?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    /**
+     * POST request helper
+     */
+    post<T>(endpoint: string, body?: unknown): Promise<T>;
+    /**
+     * PUT request helper
+     */
+    put<T>(endpoint: string, body?: unknown): Promise<T>;
+    /**
+     * DELETE request helper
+     */
+    delete<T>(endpoint: string): Promise<T>;
+}
+export declare const grampsClient: GrampsClient;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC3C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,cAAM,YAAY;IAChB,OAAO,CAAC,OAAO,CAAc;IAE7B;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQhC;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;IA6F5E;;OAEG;YACW,mBAAmB;IAwBjC;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAI1G;;OAEG;IACG,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAI3D;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAI1D;;OAEG;IACG,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;CAG9C;AAGD,eAAO,MAAM,YAAY,cAAqB,CAAC"}

package/dist/client.js

@@ -0,0 +1,153 @@
+/**
+ * Gramps Web API Client
+ */
+import { authManager } from "./auth.js";
+import { GrampsAPIError, NotFoundError } from "./utils/errors.js";
+import { DEFAULT_TIMEOUT_MS } from "./constants.js";
+class GrampsClient {
+    baseUrl = "";
+    /**
+     * Initialize the client with configuration
+     */
+    initialize(config) {
+        if (config.treeId) {
+            this.baseUrl = `${config.apiUrl}/api/trees/${config.treeId}`;
+        }
+        else {
+            this.baseUrl = `${config.apiUrl}/api`;
+        }
+    }
+    /**
+     * Make an authenticated request to the Gramps API
+     */
+    async request(endpoint, options = {}) {
+        const { method = "GET", body, params, timeout = DEFAULT_TIMEOUT_MS } = options;
+        // Build URL with query params
+        let url = `${this.baseUrl}${endpoint}`;
+        if (params) {
+            const searchParams = new URLSearchParams();
+            for (const [key, value] of Object.entries(params)) {
+                if (value !== undefined) {
+                    searchParams.append(key, String(value));
+                }
+            }
+            const queryString = searchParams.toString();
+            if (queryString) {
+                url += `?${queryString}`;
+            }
+        }
+        // Get auth token
+        const token = await authManager.getToken();
+        // Prepare headers
+        const headers = {
+            Authorization: `Bearer ${token}`,
+            Accept: "application/json",
+        };
+        if (body) {
+            headers["Content-Type"] = "application/json";
+        }
+        // Create abort controller for timeout
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const response = await fetch(url, {
+                method,
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            // Handle 401 - try refreshing token once
+            if (response.status === 401) {
+                authManager.clearToken();
+                const newToken = await authManager.refreshToken();
+                headers.Authorization = `Bearer ${newToken}`;
+                const retryResponse = await fetch(url, {
+                    method,
+                    headers,
+                    body: body ? JSON.stringify(body) : undefined,
+                    signal: controller.signal,
+                });
+                if (!retryResponse.ok) {
+                    await this.handleErrorResponse(retryResponse, endpoint);
+                }
+                return (await retryResponse.json());
+            }
+            if (!response.ok) {
+                await this.handleErrorResponse(response, endpoint);
+            }
+            // Handle empty responses
+            const text = await response.text();
+            if (!text) {
+                return {};
+            }
+            return JSON.parse(text);
+        }
+        catch (error) {
+            if (error instanceof GrampsAPIError) {
+                throw error;
+            }
+            if (error instanceof Error) {
+                if (error.name === "AbortError") {
+                    throw new GrampsAPIError(`Request timeout after ${timeout}ms`, undefined, endpoint);
+                }
+                throw new GrampsAPIError(error.message, undefined, endpoint);
+            }
+            throw new GrampsAPIError(String(error), undefined, endpoint);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Handle error responses
+     */
+    async handleErrorResponse(response, endpoint) {
+        let message = `${response.status} ${response.statusText}`;
+        try {
+            const errorBody = await response.text();
+            if (errorBody) {
+                const parsed = JSON.parse(errorBody);
+                if (parsed.detail) {
+                    message = parsed.detail;
+                }
+                else if (parsed.message) {
+                    message = parsed.message;
+                }
+            }
+        }
+        catch {
+            // Ignore JSON parse errors
+        }
+        if (response.status === 404) {
+            throw new NotFoundError("Resource", endpoint);
+        }
+        throw new GrampsAPIError(message, response.status, endpoint);
+    }
+    /**
+     * GET request helper
+     */
+    async get(endpoint, params) {
+        return this.request(endpoint, { method: "GET", params });
+    }
+    /**
+     * POST request helper
+     */
+    async post(endpoint, body) {
+        return this.request(endpoint, { method: "POST", body });
+    }
+    /**
+     * PUT request helper
+     */
+    async put(endpoint, body) {
+        return this.request(endpoint, { method: "PUT", body });
+    }
+    /**
+     * DELETE request helper
+     */
+    async delete(endpoint) {
+        return this.request(endpoint, { method: "DELETE" });
+    }
+}
+// Export singleton instance
+export const grampsClient = new GrampsClient();
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Environment configuration with validation
+ */
+export interface Config {
+    apiUrl: string;
+    username: string;
+    password: string;
+    treeId?: string;
+}
+export declare function loadConfig(): Config;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,MAAM;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,UAAU,IAAI,MAAM,CA+BnC"}

package/dist/config.js

@@ -0,0 +1,32 @@
+/**
+ * Environment configuration with validation
+ */
+export function loadConfig() {
+    const apiUrl = process.env.GRAMPS_API_URL;
+    const username = process.env.GRAMPS_USERNAME;
+    const password = process.env.GRAMPS_PASSWORD;
+    const treeId = process.env.GRAMPS_TREE_ID;
+    const missing = [];
+    if (!apiUrl)
+        missing.push("GRAMPS_API_URL");
+    if (!username)
+        missing.push("GRAMPS_USERNAME");
+    if (!password)
+        missing.push("GRAMPS_PASSWORD");
+    if (missing.length > 0 || !apiUrl || !username || !password) {
+        throw new Error(`Missing required environment variables: ${missing.join(", ")}\n\n` +
+            "Please configure the following environment variables:\n" +
+            "  GRAMPS_API_URL  - Base URL of your Gramps Web instance (e.g., https://gramps.example.com)\n" +
+            "  GRAMPS_USERNAME - Your Gramps Web username\n" +
+            "  GRAMPS_PASSWORD - Your Gramps Web password");
+    }
+    // Normalize the API URL (remove trailing slash)
+    const normalizedUrl = apiUrl.replace(/\/+$/, "");
+    return {
+        apiUrl: normalizedUrl,
+        username,
+        password,
+        treeId,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,MAAM,UAAU,UAAU;IACxB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAC1C,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IAC7C,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IAC7C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAE1C,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,IAAI,CAAC,MAAM;QAAE,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;IAC5C,IAAI,CAAC,QAAQ;QAAE,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAC/C,IAAI,CAAC,QAAQ;QAAE,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAE/C,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC5D,MAAM,IAAI,KAAK,CACb,2CAA2C,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM;YACjE,yDAAyD;YACzD,+FAA+F;YAC/F,gDAAgD;YAChD,8CAA8C,CACjD,CAAC;IACJ,CAAC;IAED,gDAAgD;IAChD,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAEjD,OAAO;QACL,MAAM,EAAE,aAAa;QACrB,QAAQ;QACR,QAAQ;QACR,MAAM;KACP,CAAC;AACJ,CAAC"}

package/dist/constants.d.ts

@@ -0,0 +1,24 @@
+/**
+ * API endpoint definitions for Gramps Web
+ */
+export declare const API_ENDPOINTS: {
+    readonly TOKEN: "/token/";
+    readonly PEOPLE: "/people/";
+    readonly FAMILIES: "/families/";
+    readonly EVENTS: "/events/";
+    readonly PLACES: "/places/";
+    readonly SOURCES: "/sources/";
+    readonly CITATIONS: "/citations/";
+    readonly REPOSITORIES: "/repositories/";
+    readonly MEDIA: "/media/";
+    readonly NOTES: "/notes/";
+    readonly SEARCH: "/search/";
+    readonly METADATA: "/metadata/";
+    readonly TREES: "/trees/";
+    readonly RECENT: "/recent/";
+};
+export type APIEndpoint = (typeof API_ENDPOINTS)[keyof typeof API_ENDPOINTS];
+export declare const ENTITY_ENDPOINT_MAP: Record<string, string>;
+export declare const TOKEN_EXPIRY_BUFFER_MS: number;
+export declare const DEFAULT_TIMEOUT_MS: number;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;CA0BhB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AAG7E,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAkBtD,CAAC;AAGF,eAAO,MAAM,sBAAsB,QAAY,CAAC;AAGhD,eAAO,MAAM,kBAAkB,QAAY,CAAC"}

package/dist/constants.js

@@ -0,0 +1,50 @@
+/**
+ * API endpoint definitions for Gramps Web
+ */
+export const API_ENDPOINTS = {
+    // Authentication
+    TOKEN: "/token/",
+    // Entity endpoints (append handle for specific entity)
+    PEOPLE: "/people/",
+    FAMILIES: "/families/",
+    EVENTS: "/events/",
+    PLACES: "/places/",
+    SOURCES: "/sources/",
+    CITATIONS: "/citations/",
+    REPOSITORIES: "/repositories/",
+    MEDIA: "/media/",
+    NOTES: "/notes/",
+    // Search
+    SEARCH: "/search/",
+    // Metadata
+    METADATA: "/metadata/",
+    // Trees (for multi-tree setups)
+    TREES: "/trees/",
+    // Recent changes
+    RECENT: "/recent/",
+};
+// Map entity type to endpoint
+export const ENTITY_ENDPOINT_MAP = {
+    people: API_ENDPOINTS.PEOPLE,
+    person: API_ENDPOINTS.PEOPLE,
+    families: API_ENDPOINTS.FAMILIES,
+    family: API_ENDPOINTS.FAMILIES,
+    events: API_ENDPOINTS.EVENTS,
+    event: API_ENDPOINTS.EVENTS,
+    places: API_ENDPOINTS.PLACES,
+    place: API_ENDPOINTS.PLACES,
+    sources: API_ENDPOINTS.SOURCES,
+    source: API_ENDPOINTS.SOURCES,
+    citations: API_ENDPOINTS.CITATIONS,
+    citation: API_ENDPOINTS.CITATIONS,
+    repositories: API_ENDPOINTS.REPOSITORIES,
+    repository: API_ENDPOINTS.REPOSITORIES,
+    media: API_ENDPOINTS.MEDIA,
+    notes: API_ENDPOINTS.NOTES,
+    note: API_ENDPOINTS.NOTES,
+};
+// Token expiration buffer (30 seconds before actual expiry)
+export const TOKEN_EXPIRY_BUFFER_MS = 30 * 1000;
+// Default request timeout
+export const DEFAULT_TIMEOUT_MS = 30 * 1000;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,iBAAiB;IACjB,KAAK,EAAE,SAAS;IAEhB,uDAAuD;IACvD,MAAM,EAAE,UAAU;IAClB,QAAQ,EAAE,YAAY;IACtB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,UAAU;IAClB,OAAO,EAAE,WAAW;IACpB,SAAS,EAAE,aAAa;IACxB,YAAY,EAAE,gBAAgB;IAC9B,KAAK,EAAE,SAAS;IAChB,KAAK,EAAE,SAAS;IAEhB,SAAS;IACT,MAAM,EAAE,UAAU;IAElB,WAAW;IACX,QAAQ,EAAE,YAAY;IAEtB,gCAAgC;IAChC,KAAK,EAAE,SAAS;IAEhB,iBAAiB;IACjB,MAAM,EAAE,UAAU;CACV,CAAC;AAIX,8BAA8B;AAC9B,MAAM,CAAC,MAAM,mBAAmB,GAA2B;IACzD,MAAM,EAAE,aAAa,CAAC,MAAM;IAC5B,MAAM,EAAE,aAAa,CAAC,MAAM;IAC5B,QAAQ,EAAE,aAAa,CAAC,QAAQ;IAChC,MAAM,EAAE,aAAa,CAAC,QAAQ;IAC9B,MAAM,EAAE,aAAa,CAAC,MAAM;IAC5B,KAAK,EAAE,aAAa,CAAC,MAAM;IAC3B,MAAM,EAAE,aAAa,CAAC,MAAM;IAC5B,KAAK,EAAE,aAAa,CAAC,MAAM;IAC3B,OAAO,EAAE,aAAa,CAAC,OAAO;IAC9B,MAAM,EAAE,aAAa,CAAC,OAAO;IAC7B,SAAS,EAAE,aAAa,CAAC,SAAS;IAClC,QAAQ,EAAE,aAAa,CAAC,SAAS;IACjC,YAAY,EAAE,aAAa,CAAC,YAAY;IACxC,UAAU,EAAE,aAAa,CAAC,YAAY;IACtC,KAAK,EAAE,aAAa,CAAC,KAAK;IAC1B,KAAK,EAAE,aAAa,CAAC,KAAK;IAC1B,IAAI,EAAE,aAAa,CAAC,KAAK;CAC1B,CAAC;AAEF,4DAA4D;AAC5D,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,GAAG,IAAI,CAAC;AAEhD,0BAA0B;AAC1B,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,GAAG,IAAI,CAAC"}