@graph-knowledge/api 0.1.0

package/src/lib/operations/element-operations.js

@@ -0,0 +1,175 @@
+import { generateUuid } from "../utils/uuid";
+import { NotFoundError } from "../errors/api-errors";
+import { DEFAULT_ELEMENT_DIMENSIONS, DEFAULT_CUSTOM_SHAPE_DIMENSIONS } from "../constants/element-defaults";
+/**
+ * Implementation of element CRUD operations.
+ */
+export class ElementOperations {
+    firestore;
+    auth;
+    validatorRegistry;
+    constructor(firestore, auth, validatorRegistry) {
+        this.firestore = firestore;
+        this.auth = auth;
+        this.validatorRegistry = validatorRegistry;
+    }
+    async get(documentId, nodeId, elementId) {
+        this.auth.requireAuth();
+        const nodePath = `documents/${documentId}/nodes/${nodeId}`;
+        const node = await this.firestore.getDocument(nodePath);
+        if (!node) {
+            throw new NotFoundError(`Node ${nodeId} not found`);
+        }
+        const element = node.elements.find((e) => e.id === elementId);
+        if (!element) {
+            throw new NotFoundError(`Element ${elementId} not found`);
+        }
+        return element;
+    }
+    async list(documentId, nodeId) {
+        this.auth.requireAuth();
+        const nodePath = `documents/${documentId}/nodes/${nodeId}`;
+        const node = await this.firestore.getDocument(nodePath);
+        if (!node) {
+            throw new NotFoundError(`Node ${nodeId} not found`);
+        }
+        return node.elements || [];
+    }
+    async create(documentId, nodeId, input) {
+        this.auth.requireAuth();
+        // Custom shapes require premium
+        if (input.type.startsWith("custom:")) {
+            await this.auth.requirePremium();
+        }
+        this.validatorRegistry.validate(input);
+        const nodePath = `documents/${documentId}/nodes/${nodeId}`;
+        const node = await this.firestore.getDocument(nodePath);
+        if (!node) {
+            throw new NotFoundError(`Node ${nodeId} not found`);
+        }
+        const defaults = this.getDefaultDimensions(input.type);
+        // Connectors have optional x/y since their position is derived from connected elements
+        const x = input.x ?? 0;
+        const y = input.y ?? 0;
+        const element = {
+            id: generateUuid(),
+            elementType: input.type,
+            x,
+            y,
+            width: input.width ?? defaults.width,
+            height: input.height ?? defaults.height,
+            rotation: this.normalizeRotation(input.rotation ?? 0),
+            properties: this.buildProperties(input)
+        };
+        // Only add link properties if they have values (Firestore rejects undefined)
+        if (input.isLink !== undefined) {
+            element.isLink = input.isLink;
+        }
+        if (input.linkTarget !== undefined) {
+            element.linkTarget = input.linkTarget;
+        }
+        const updatedElements = [...(node.elements || []), element];
+        await this.firestore.updateDocument(nodePath, {
+            elements: updatedElements
+        });
+        return element;
+    }
+    async update(documentId, nodeId, elementId, input) {
+        this.auth.requireAuth();
+        const nodePath = `documents/${documentId}/nodes/${nodeId}`;
+        const node = await this.firestore.getDocument(nodePath);
+        if (!node) {
+            throw new NotFoundError(`Node ${nodeId} not found`);
+        }
+        const elementIndex = node.elements.findIndex((e) => e.id === elementId);
+        if (elementIndex === -1) {
+            throw new NotFoundError(`Element ${elementId} not found`);
+        }
+        const existingElement = node.elements[elementIndex];
+        const updatedElement = {
+            ...existingElement,
+            x: input.x ?? existingElement.x,
+            y: input.y ?? existingElement.y,
+            width: input.width ?? existingElement.width,
+            height: input.height ?? existingElement.height,
+            rotation: input.rotation !== undefined
+                ? this.normalizeRotation(input.rotation)
+                : existingElement.rotation,
+            properties: {
+                ...existingElement.properties,
+                ...(input.properties ?? {})
+            }
+        };
+        // Handle link properties - only set if defined (Firestore rejects undefined)
+        const newIsLink = input.isLink ?? existingElement.isLink;
+        const newLinkTarget = input.linkTarget ?? existingElement.linkTarget;
+        if (newIsLink !== undefined) {
+            updatedElement.isLink = newIsLink;
+        }
+        if (newLinkTarget !== undefined) {
+            updatedElement.linkTarget = newLinkTarget;
+        }
+        const updatedElements = [...node.elements];
+        updatedElements[elementIndex] = updatedElement;
+        await this.firestore.updateDocument(nodePath, {
+            elements: updatedElements
+        });
+    }
+    async delete(documentId, nodeId, elementId) {
+        this.auth.requireAuth();
+        const nodePath = `documents/${documentId}/nodes/${nodeId}`;
+        const node = await this.firestore.getDocument(nodePath);
+        if (!node) {
+            throw new NotFoundError(`Node ${nodeId} not found`);
+        }
+        const updatedElements = node.elements.filter((e) => e.id !== elementId);
+        await this.firestore.updateDocument(nodePath, {
+            elements: updatedElements
+        });
+    }
+    /**
+     * Gets default dimensions for an element type.
+     */
+    getDefaultDimensions(type) {
+        if (type.startsWith("custom:")) {
+            return DEFAULT_CUSTOM_SHAPE_DIMENSIONS;
+        }
+        return (DEFAULT_ELEMENT_DIMENSIONS[type] ?? DEFAULT_CUSTOM_SHAPE_DIMENSIONS);
+    }
+    /**
+     * Normalizes rotation to integer in range [0, 360).
+     */
+    normalizeRotation(rotation) {
+        let normalized = rotation % 360;
+        if (normalized < 0) {
+            normalized += 360;
+        }
+        return Math.round(normalized);
+    }
+    /**
+     * Builds properties object from element input.
+     * Extracts type-specific properties, excluding common fields.
+     */
+    buildProperties(input) {
+        const props = {
+            __schemaVersion: 1
+        };
+        // Exclude common fields, copy the rest as properties
+        const commonFields = new Set([
+            "type",
+            "x",
+            "y",
+            "width",
+            "height",
+            "rotation",
+            "isLink",
+            "linkTarget"
+        ]);
+        for (const [key, value] of Object.entries(input)) {
+            if (!commonFields.has(key) && value !== undefined) {
+                props[key] = value;
+            }
+        }
+        return props;
+    }
+}

package/src/lib/operations/node-operations.d.ts

@@ -0,0 +1,22 @@
+import { GraphNode } from "@graph-knowledge/domain";
+import { INodeOperations } from "../interfaces/node-operations.interface";
+import { IFirestoreClient } from "../interfaces/firestore-client.interface";
+import { IAuthClient } from "../interfaces/auth-client.interface";
+import { NodeValidator } from "../validators/node-validator";
+import { CreateNodeInput, UpdateNodeInput } from "../types/api-types";
+/**
+ * Implementation of node CRUD operations.
+ */
+export declare class NodeOperations implements INodeOperations {
+    private readonly firestore;
+    private readonly auth;
+    private readonly validator;
+    constructor(firestore: IFirestoreClient, auth: IAuthClient, validator: NodeValidator);
+    create(documentId: string, input: CreateNodeInput): Promise<GraphNode>;
+    createWithId(documentId: string, nodeId: string, input: CreateNodeInput): Promise<GraphNode>;
+    private createNodeWithId;
+    get(documentId: string, nodeId: string): Promise<GraphNode>;
+    list(documentId: string): Promise<GraphNode[]>;
+    update(documentId: string, nodeId: string, input: UpdateNodeInput): Promise<void>;
+    delete(documentId: string, nodeId: string): Promise<void>;
+}

package/src/lib/operations/node-operations.js

@@ -0,0 +1,89 @@
+import { generateUuid } from "../utils/uuid";
+import { NotFoundError } from "../errors/api-errors";
+// Default canvas dimensions
+const DEFAULT_CANVAS_WIDTH = 1920;
+const DEFAULT_CANVAS_HEIGHT = 1080;
+/**
+ * Implementation of node CRUD operations.
+ */
+export class NodeOperations {
+    firestore;
+    auth;
+    validator;
+    constructor(firestore, auth, validator) {
+        this.firestore = firestore;
+        this.auth = auth;
+        this.validator = validator;
+    }
+    async create(documentId, input) {
+        const nodeId = generateUuid();
+        return this.createNodeWithId(documentId, nodeId, input);
+    }
+    async createWithId(documentId, nodeId, input) {
+        return this.createNodeWithId(documentId, nodeId, input);
+    }
+    async createNodeWithId(documentId, nodeId, input) {
+        const userId = this.auth.requireAuth();
+        this.validator.validateCreate(input);
+        // Determine level from parent if provided
+        let level = input.level ?? 0;
+        if (input.parentNodeId) {
+            const parentNode = await this.firestore.getDocument(`documents/${documentId}/nodes/${input.parentNodeId}`);
+            if (parentNode) {
+                level = (parentNode.level ?? 0) + 1;
+            }
+        }
+        const node = {
+            id: nodeId,
+            title: input.title,
+            content: input.content ?? "",
+            elements: [],
+            canvasWidth: input.canvasWidth ?? DEFAULT_CANVAS_WIDTH,
+            canvasHeight: input.canvasHeight ?? DEFAULT_CANVAS_HEIGHT,
+            level,
+            owner: userId
+        };
+        // Only set parentNodeId if defined (Firestore rejects undefined)
+        if (input.parentNodeId !== undefined) {
+            node.parentNodeId = input.parentNodeId;
+        }
+        await this.firestore.setDocument(`documents/${documentId}/nodes/${nodeId}`, node);
+        return node;
+    }
+    async get(documentId, nodeId) {
+        this.auth.requireAuth();
+        const node = await this.firestore.getDocument(`documents/${documentId}/nodes/${nodeId}`);
+        if (!node) {
+            throw new NotFoundError(`Node ${nodeId} not found`);
+        }
+        return node;
+    }
+    async list(documentId) {
+        this.auth.requireAuth();
+        return this.firestore.getCollection(`documents/${documentId}/nodes`);
+    }
+    async update(documentId, nodeId, input) {
+        this.auth.requireAuth();
+        this.validator.validateUpdate(input);
+        const node = await this.firestore.getDocument(`documents/${documentId}/nodes/${nodeId}`);
+        if (!node) {
+            throw new NotFoundError(`Node ${nodeId} not found`);
+        }
+        const updates = {};
+        if (input.title !== undefined)
+            updates.title = input.title;
+        if (input.content !== undefined)
+            updates.content = input.content;
+        if (input.canvasWidth !== undefined)
+            updates.canvasWidth = input.canvasWidth;
+        if (input.canvasHeight !== undefined)
+            updates.canvasHeight = input.canvasHeight;
+        if (Object.keys(updates).length > 0) {
+            await this.firestore.updateDocument(`documents/${documentId}/nodes/${nodeId}`, updates);
+        }
+    }
+    async delete(documentId, nodeId) {
+        this.auth.requireAuth();
+        await this.firestore.deleteDocument(`documents/${documentId}/nodes/${nodeId}`);
+    }
+}

package/src/lib/testing/index.d.ts

@@ -0,0 +1,2 @@
+export { MockAuthClient } from "./mock-auth-client";
+export { MockFirestoreClient } from "./mock-firestore-client";

package/src/lib/testing/index.js

@@ -0,0 +1,3 @@
+// Testing utilities for @graph-knowledge/api
+export { MockAuthClient } from "./mock-auth-client";
+export { MockFirestoreClient } from "./mock-firestore-client";

package/src/lib/testing/mock-auth-client.d.ts

@@ -0,0 +1,26 @@
+import { IAuthClient } from "../interfaces/auth-client.interface";
+/**
+ * Mock authentication client for testing.
+ */
+export declare class MockAuthClient implements IAuthClient {
+    private _currentUserId;
+    private _isPremium;
+    constructor(options?: {
+        userId?: string;
+        isPremium?: boolean;
+    });
+    signIn(email: string, _password: string): Promise<void>;
+    signOut(): Promise<void>;
+    get currentUserId(): string | null;
+    requireAuth(): string;
+    /**
+     * Sets the current user ID for testing.
+     */
+    setUserId(userId: string | null): void;
+    isPremium(): Promise<boolean>;
+    requirePremium(): Promise<void>;
+    /**
+     * Sets the premium status for testing.
+     */
+    setPremium(isPremium: boolean): void;
+}

package/src/lib/testing/mock-auth-client.js

@@ -0,0 +1,49 @@
+import { AuthenticationError, PermissionError } from "../errors/api-errors";
+/**
+ * Mock authentication client for testing.
+ */
+export class MockAuthClient {
+    _currentUserId = null;
+    _isPremium = false;
+    constructor(options) {
+        this._currentUserId = options?.userId ?? null;
+        this._isPremium = options?.isPremium ?? false;
+    }
+    async signIn(email, _password) {
+        // Simulate successful sign-in
+        this._currentUserId = `mock-user-${email.split("@")[0]}`;
+    }
+    async signOut() {
+        this._currentUserId = null;
+    }
+    get currentUserId() {
+        return this._currentUserId;
+    }
+    requireAuth() {
+        if (!this._currentUserId) {
+            throw new AuthenticationError("Not authenticated");
+        }
+        return this._currentUserId;
+    }
+    /**
+     * Sets the current user ID for testing.
+     */
+    setUserId(userId) {
+        this._currentUserId = userId;
+    }
+    async isPremium() {
+        return this._isPremium;
+    }
+    async requirePremium() {
+        this.requireAuth();
+        if (!this._isPremium) {
+            throw new PermissionError("Premium subscription required");
+        }
+    }
+    /**
+     * Sets the premium status for testing.
+     */
+    setPremium(isPremium) {
+        this._isPremium = isPremium;
+    }
+}

package/src/lib/testing/mock-firestore-client.d.ts

@@ -0,0 +1,32 @@
+import { IFirestoreClient, IBatchWriter } from "../interfaces/firestore-client.interface";
+/**
+ * Mock Firestore client for testing.
+ */
+export declare class MockFirestoreClient implements IFirestoreClient {
+    private readonly store;
+    getDocument<T>(path: string): Promise<(T & {
+        id: string;
+    }) | null>;
+    setDocument<T extends object>(path: string, data: T): Promise<void>;
+    updateDocument<T extends object>(path: string, data: Partial<T>): Promise<void>;
+    deleteDocument(path: string): Promise<void>;
+    getCollection<T>(path: string): Promise<(T & {
+        id: string;
+    })[]>;
+    queryCollection<T>(path: string, field: string, value: string): Promise<(T & {
+        id: string;
+    })[]>;
+    batch(): IBatchWriter;
+    /**
+     * Clears all data from the mock store.
+     */
+    clear(): void;
+    /**
+     * Gets all stored data for testing assertions.
+     */
+    getAllData(): Map<string, unknown>;
+    /**
+     * Seeds data into the store for testing.
+     */
+    seed(path: string, data: Record<string, unknown>): void;
+}

package/src/lib/testing/mock-firestore-client.js

@@ -0,0 +1,126 @@
+/**
+ * Mock batch writer for testing.
+ */
+class MockBatchWriter {
+    store;
+    operations = [];
+    constructor(store) {
+        this.store = store;
+    }
+    set(path, data) {
+        this.operations.push({
+            type: "set",
+            path,
+            data: data
+        });
+    }
+    update(path, data) {
+        this.operations.push({
+            type: "update",
+            path,
+            data: data
+        });
+    }
+    delete(path) {
+        this.operations.push({ type: "delete", path });
+    }
+    async commit() {
+        for (const op of this.operations) {
+            const id = op.path.split("/").pop() ?? "";
+            switch (op.type) {
+                case "set":
+                    this.store.set(op.path, { id, ...(op.data ?? {}) });
+                    break;
+                case "update": {
+                    const existing = this.store.get(op.path);
+                    if (existing) {
+                        this.store.set(op.path, {
+                            ...existing,
+                            ...(op.data ?? {})
+                        });
+                    }
+                    break;
+                }
+                case "delete":
+                    this.store.delete(op.path);
+                    break;
+            }
+        }
+        this.operations = [];
+    }
+    /**
+     * Gets the pending operations for testing assertions.
+     */
+    getPendingOperations() {
+        return [...this.operations];
+    }
+}
+/**
+ * Mock Firestore client for testing.
+ */
+export class MockFirestoreClient {
+    store = new Map();
+    async getDocument(path) {
+        const data = this.store.get(path);
+        if (!data) {
+            return null;
+        }
+        return data;
+    }
+    async setDocument(path, data) {
+        const id = path.split("/").pop() ?? "";
+        this.store.set(path, { id, ...data });
+    }
+    async updateDocument(path, data) {
+        const existing = this.store.get(path);
+        if (existing) {
+            this.store.set(path, { ...existing, ...data });
+        }
+    }
+    async deleteDocument(path) {
+        this.store.delete(path);
+    }
+    async getCollection(path) {
+        const results = [];
+        const prefix = path + "/";
+        for (const [key, value] of this.store) {
+            if (key.startsWith(prefix)) {
+                // Only include direct children (not nested sub-collections)
+                const remainder = key.substring(prefix.length);
+                if (!remainder.includes("/")) {
+                    results.push(value);
+                }
+            }
+        }
+        return results;
+    }
+    async queryCollection(path, field, value) {
+        const all = await this.getCollection(path);
+        return all.filter((item) => {
+            const record = item;
+            return record[field] === value;
+        });
+    }
+    batch() {
+        return new MockBatchWriter(this.store);
+    }
+    /**
+     * Clears all data from the mock store.
+     */
+    clear() {
+        this.store.clear();
+    }
+    /**
+     * Gets all stored data for testing assertions.
+     */
+    getAllData() {
+        return new Map(this.store);
+    }
+    /**
+     * Seeds data into the store for testing.
+     */
+    seed(path, data) {
+        const id = path.split("/").pop() ?? "";
+        this.store.set(path, { id, ...data });
+    }
+}

package/src/lib/types/api-types.d.ts

@@ -0,0 +1,61 @@
+import { Document, GraphNode } from "@graph-knowledge/domain";
+/**
+ * Input for creating a new document.
+ */
+export interface CreateDocumentInput {
+    /** Document title (required) */
+    title: string;
+    /** Document description/content */
+    content?: string;
+    /** Root node canvas width (defaults to 1920) */
+    canvasWidth?: number;
+    /** Root node canvas height (defaults to 1080) */
+    canvasHeight?: number;
+    /** Mark as premium content */
+    isPremiumContent?: boolean;
+}
+/**
+ * Input for updating an existing document.
+ */
+export interface UpdateDocumentInput {
+    title?: string;
+    content?: string;
+}
+/**
+ * Result of document operations, extends Document with required id.
+ */
+export type DocumentResult = Document & {
+    id: string;
+};
+/**
+ * Input for creating a new node.
+ */
+export interface CreateNodeInput {
+    /** Node title (required) */
+    title: string;
+    /** Node description/content */
+    content?: string;
+    /** Parent node ID for hierarchical structure */
+    parentNodeId?: string;
+    /** Canvas width (defaults to 1920) */
+    canvasWidth?: number;
+    /** Canvas height (defaults to 1080) */
+    canvasHeight?: number;
+    /** Hierarchical level (auto-calculated from parent) */
+    level?: number;
+}
+/**
+ * Input for updating an existing node.
+ */
+export interface UpdateNodeInput {
+    title?: string;
+    content?: string;
+    canvasWidth?: number;
+    canvasHeight?: number;
+}
+/**
+ * Result of node operations.
+ */
+export type NodeResult = GraphNode & {
+    id: string;
+};