@graph-knowledge/api 0.1.0

package/src/lib/interfaces/firestore-client.interface.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Interface for Firestore batch write operations.
+ */
+export interface IBatchWriter {
+    /**
+     * Sets a document in the batch.
+     */
+    set<T extends object>(path: string, data: T): void;
+    /**
+     * Updates a document in the batch.
+     */
+    update<T extends object>(path: string, data: Partial<T>): void;
+    /**
+     * Deletes a document in the batch.
+     */
+    delete(path: string): void;
+    /**
+     * Commits all batched operations atomically.
+     */
+    commit(): Promise<void>;
+}
+/**
+ * Interface for Firestore operations.
+ * Abstracts Firebase Firestore for dependency inversion.
+ */
+export interface IFirestoreClient {
+    /**
+     * Gets a single document by path.
+     * @returns The document data or null if not found
+     */
+    getDocument<T>(path: string): Promise<(T & {
+        id: string;
+    }) | null>;
+    /**
+     * Sets a document at the given path.
+     */
+    setDocument<T extends object>(path: string, data: T): Promise<void>;
+    /**
+     * Updates a document at the given path.
+     */
+    updateDocument<T extends object>(path: string, data: Partial<T>): Promise<void>;
+    /**
+     * Deletes a document at the given path.
+     */
+    deleteDocument(path: string): Promise<void>;
+    /**
+     * Gets all documents in a collection.
+     */
+    getCollection<T>(path: string): Promise<(T & {
+        id: string;
+    })[]>;
+    /**
+     * Queries documents in a collection where a field equals a value.
+     */
+    queryCollection<T>(path: string, field: string, value: string): Promise<(T & {
+        id: string;
+    })[]>;
+    /**
+     * Creates a new batch writer for atomic operations.
+     */
+    batch(): IBatchWriter;
+}

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

@@ -0,0 +1,62 @@
+import { GraphNode } from "@graph-knowledge/domain";
+import { CreateNodeInput, UpdateNodeInput } from "../types/api-types";
+/**
+ * Interface for node CRUD operations.
+ */
+export interface INodeOperations {
+    /**
+     * Creates a new node within a document.
+     * @param documentId The parent document ID
+     * @param input Node creation parameters
+     * @returns The created node
+     * @throws AuthenticationError if not authenticated
+     * @throws NotFoundError if document doesn't exist
+     * @throws ValidationError if input is invalid
+     */
+    create(documentId: string, input: CreateNodeInput): Promise<GraphNode>;
+    /**
+     * Creates a new node with a specific ID.
+     * Useful when you need to reference the node ID before creation (e.g., for linking).
+     * @param documentId The parent document ID
+     * @param nodeId The specific ID to use for the node
+     * @param input Node creation parameters
+     * @returns The created node
+     * @throws AuthenticationError if not authenticated
+     * @throws NotFoundError if document doesn't exist
+     * @throws ValidationError if input is invalid
+     */
+    createWithId(documentId: string, nodeId: string, input: CreateNodeInput): Promise<GraphNode>;
+    /**
+     * Gets a node by ID.
+     * @param documentId The parent document ID
+     * @param nodeId The node ID
+     * @returns The node
+     * @throws AuthenticationError if not authenticated
+     * @throws NotFoundError if node doesn't exist
+     */
+    get(documentId: string, nodeId: string): Promise<GraphNode>;
+    /**
+     * Lists all nodes in a document.
+     * @param documentId The parent document ID
+     * @returns Array of nodes
+     * @throws AuthenticationError if not authenticated
+     */
+    list(documentId: string): Promise<GraphNode[]>;
+    /**
+     * Updates a node's properties.
+     * @param documentId The parent document ID
+     * @param nodeId The node ID
+     * @param input Fields to update
+     * @throws AuthenticationError if not authenticated
+     * @throws NotFoundError if node doesn't exist
+     * @throws ValidationError if input is invalid
+     */
+    update(documentId: string, nodeId: string, input: UpdateNodeInput): Promise<void>;
+    /**
+     * Deletes a node.
+     * @param documentId The parent document ID
+     * @param nodeId The node ID
+     * @throws AuthenticationError if not authenticated
+     */
+    delete(documentId: string, nodeId: string): Promise<void>;
+}

package/src/lib/models/document.model.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Domain models bundled for npm package self-containment.
+ * These are copies of the types from @graph-knowledge/domain.
+ */
+/**
+ * Current document schema version.
+ * Increment this when making breaking changes to Document, GraphNode, or GraphElement structure.
+ *
+ * Version History:
+ * - 0: Legacy documents (no schemaVersion field)
+ * - 1: Initial versioned schema (added schemaVersion tracking)
+ */
+export declare const CURRENT_DOCUMENT_SCHEMA_VERSION = 1;
+export interface Document {
+    id: string;
+    /**
+     * Schema version for migration support.
+     * Documents without this field are treated as version 0 (legacy).
+     */
+    schemaVersion?: number;
+    title: string;
+    content: string;
+    /**
+     * UID of the document owner.
+     * OWNER-ONLY: Only the owner can modify this field.
+     */
+    owner: string;
+    /**
+     * Email addresses of users with whom this document is shared.
+     * OWNER-ONLY: Only the owner can modify this field.
+     * Changes trigger Cloud Function to sync sharedWithUser arrays.
+     */
+    sharedWith: string[];
+    /**
+     * Document creation timestamp.
+     * OWNER-ONLY: Set on creation, cannot be modified by shared users.
+     */
+    createdAt: Date | {
+        seconds: number;
+        nanoseconds: number;
+    } | null;
+    nodes?: GraphNode[];
+    rootNodeId?: string;
+    isPremiumContent?: boolean;
+}
+export interface GraphNode {
+    id: string;
+    title: string;
+    content: string;
+    elements: GraphElement[];
+    parentNodeId?: string;
+    canvasWidth?: number;
+    canvasHeight?: number;
+    level?: number;
+    owner?: string;
+}
+export interface GraphElement {
+    id: string;
+    elementType: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /**
+     * Rotation in degrees, always an integer in the range [0, 360).
+     * This enables reliable grouping and comparison for snapping operations.
+     * Legacy documents with floating-point values are normalized during loading.
+     */
+    rotation: number;
+    properties: Record<string, any>;
+    isLink?: boolean;
+    linkTarget?: string;
+}

package/src/lib/models/document.model.js

@@ -0,0 +1,13 @@
+/**
+ * Domain models bundled for npm package self-containment.
+ * These are copies of the types from @graph-knowledge/domain.
+ */
+/**
+ * Current document schema version.
+ * Increment this when making breaking changes to Document, GraphNode, or GraphElement structure.
+ *
+ * Version History:
+ * - 0: Legacy documents (no schemaVersion field)
+ * - 1: Initial versioned schema (added schemaVersion tracking)
+ */
+export const CURRENT_DOCUMENT_SCHEMA_VERSION = 1;

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

@@ -0,0 +1,6 @@
+/**
+ * Domain models bundled for npm package.
+ * Re-exports types needed by the API.
+ */
+export { CURRENT_DOCUMENT_SCHEMA_VERSION } from "./document.model";
+export type { Document, GraphNode, GraphElement } from "./document.model";

package/src/lib/models/index.js

@@ -0,0 +1,5 @@
+/**
+ * Domain models bundled for npm package.
+ * Re-exports types needed by the API.
+ */
+export { CURRENT_DOCUMENT_SCHEMA_VERSION } from "./document.model";

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

@@ -0,0 +1,30 @@
+import { GraphElement } from "@graph-knowledge/domain";
+import { IBatchOperations, BatchUpdateElementInput } from "../interfaces/batch-operations.interface";
+import { IFirestoreClient } from "../interfaces/firestore-client.interface";
+import { IAuthClient } from "../interfaces/auth-client.interface";
+import { IElementValidatorRegistry } from "../interfaces/element-validator.interface";
+import { AnyElementInput } from "../types/element-input-types";
+/**
+ * Implementation of batch element operations.
+ */
+export declare class BatchOperations implements IBatchOperations {
+    private readonly firestore;
+    private readonly auth;
+    private readonly validatorRegistry;
+    constructor(firestore: IFirestoreClient, auth: IAuthClient, validatorRegistry: IElementValidatorRegistry);
+    createElements(documentId: string, nodeId: string, inputs: AnyElementInput[]): Promise<GraphElement[]>;
+    updateElements(documentId: string, nodeId: string, updates: BatchUpdateElementInput[]): Promise<void>;
+    deleteElements(documentId: string, nodeId: string, elementIds: string[]): Promise<void>;
+    /**
+     * Gets default dimensions for an element type.
+     */
+    private getDefaultDimensions;
+    /**
+     * Normalizes rotation to integer in range [0, 360).
+     */
+    private normalizeRotation;
+    /**
+     * Builds properties object from element input.
+     */
+    private buildProperties;
+}

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

@@ -0,0 +1,181 @@
+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 batch element operations.
+ */
+export class BatchOperations {
+    firestore;
+    auth;
+    validatorRegistry;
+    constructor(firestore, auth, validatorRegistry) {
+        this.firestore = firestore;
+        this.auth = auth;
+        this.validatorRegistry = validatorRegistry;
+    }
+    async createElements(documentId, nodeId, inputs) {
+        this.auth.requireAuth();
+        if (inputs.length === 0) {
+            return [];
+        }
+        // Validate ALL inputs first (before creating any)
+        for (const input of inputs) {
+            // 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`);
+        }
+        // Build all elements
+        const newElements = inputs.map((input) => {
+            const defaults = this.getDefaultDimensions(input.type);
+            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)
+            };
+            if (input.isLink !== undefined) {
+                element.isLink = input.isLink;
+            }
+            if (input.linkTarget !== undefined) {
+                element.linkTarget = input.linkTarget;
+            }
+            return element;
+        });
+        // Update node with all new elements atomically
+        const updatedElements = [...(node.elements || []), ...newElements];
+        await this.firestore.updateDocument(nodePath, {
+            elements: updatedElements
+        });
+        return newElements;
+    }
+    async updateElements(documentId, nodeId, updates) {
+        this.auth.requireAuth();
+        if (updates.length === 0) {
+            return;
+        }
+        const nodePath = `documents/${documentId}/nodes/${nodeId}`;
+        const node = await this.firestore.getDocument(nodePath);
+        if (!node) {
+            throw new NotFoundError(`Node ${nodeId} not found`);
+        }
+        // Create a map for quick lookup
+        const updateMap = new Map(updates.map((u) => [u.elementId, u]));
+        // Verify all elements exist before updating any
+        for (const update of updates) {
+            const exists = node.elements.some((e) => e.id === update.elementId);
+            if (!exists) {
+                throw new NotFoundError(`Element ${update.elementId} not found`);
+            }
+        }
+        // Apply all updates
+        const updatedElements = node.elements.map((element) => {
+            const update = updateMap.get(element.id);
+            if (!update) {
+                return element;
+            }
+            const updated = {
+                ...element,
+                x: update.x ?? element.x,
+                y: update.y ?? element.y,
+                width: update.width ?? element.width,
+                height: update.height ?? element.height,
+                rotation: update.rotation !== undefined
+                    ? this.normalizeRotation(update.rotation)
+                    : element.rotation,
+                properties: {
+                    ...element.properties,
+                    ...(update.properties ?? {})
+                }
+            };
+            // Handle link properties: only change if the property is present on the update
+            if ("isLink" in update) {
+                updated.isLink = update.isLink;
+            }
+            else if (element.isLink !== undefined) {
+                updated.isLink = element.isLink;
+            }
+            if ("linkTarget" in update) {
+                updated.linkTarget = update.linkTarget;
+            }
+            else if (element.linkTarget !== undefined) {
+                updated.linkTarget = element.linkTarget;
+            }
+            return updated;
+        });
+        await this.firestore.updateDocument(nodePath, {
+            elements: updatedElements
+        });
+    }
+    async deleteElements(documentId, nodeId, elementIds) {
+        this.auth.requireAuth();
+        if (elementIds.length === 0) {
+            return;
+        }
+        const nodePath = `documents/${documentId}/nodes/${nodeId}`;
+        const node = await this.firestore.getDocument(nodePath);
+        if (!node) {
+            throw new NotFoundError(`Node ${nodeId} not found`);
+        }
+        const idsToDelete = new Set(elementIds);
+        const updatedElements = node.elements.filter((e) => !idsToDelete.has(e.id));
+        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.
+     */
+    buildProperties(input) {
+        const props = {
+            __schemaVersion: 1
+        };
+        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/document-operations.d.ts

@@ -0,0 +1,20 @@
+import { IDocumentOperations } from "../interfaces/document-operations.interface";
+import { IFirestoreClient } from "../interfaces/firestore-client.interface";
+import { IAuthClient } from "../interfaces/auth-client.interface";
+import { DocumentValidator } from "../validators/document-validator";
+import { CreateDocumentInput, UpdateDocumentInput, DocumentResult } from "../types/api-types";
+/**
+ * Implementation of document CRUD operations.
+ */
+export declare class DocumentOperations implements IDocumentOperations {
+    private readonly firestore;
+    private readonly auth;
+    private readonly validator;
+    constructor(firestore: IFirestoreClient, auth: IAuthClient, validator: DocumentValidator);
+    create(input: CreateDocumentInput): Promise<DocumentResult>;
+    get(documentId: string): Promise<DocumentResult>;
+    list(): Promise<DocumentResult[]>;
+    update(documentId: string, input: UpdateDocumentInput): Promise<void>;
+    delete(documentId: string): Promise<void>;
+    share(documentId: string, userIds: string[]): Promise<void>;
+}

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

@@ -0,0 +1,108 @@
+import { CURRENT_DOCUMENT_SCHEMA_VERSION } from "@graph-knowledge/domain";
+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 document CRUD operations.
+ */
+export class DocumentOperations {
+    firestore;
+    auth;
+    validator;
+    constructor(firestore, auth, validator) {
+        this.firestore = firestore;
+        this.auth = auth;
+        this.validator = validator;
+    }
+    async create(input) {
+        const userId = this.auth.requireAuth();
+        this.validator.validateCreate(input);
+        const docId = generateUuid();
+        const rootNodeId = generateUuid();
+        const rootNode = {
+            id: rootNodeId,
+            title: input.title,
+            content: "",
+            elements: [],
+            canvasWidth: input.canvasWidth ?? DEFAULT_CANVAS_WIDTH,
+            canvasHeight: input.canvasHeight ?? DEFAULT_CANVAS_HEIGHT,
+            level: 0,
+            owner: userId
+        };
+        const document = {
+            schemaVersion: CURRENT_DOCUMENT_SCHEMA_VERSION,
+            title: input.title,
+            content: input.content ?? "",
+            owner: userId,
+            sharedWith: [],
+            createdAt: new Date(),
+            nodes: [], // Nodes stored in sub-collection
+            rootNodeId: rootNodeId,
+            isPremiumContent: input.isPremiumContent ?? false
+        };
+        const batch = this.firestore.batch();
+        batch.set(`documents/${docId}`, document);
+        batch.set(`documents/${docId}/nodes/${rootNodeId}`, rootNode);
+        await batch.commit();
+        return {
+            id: docId,
+            ...document,
+            nodes: [rootNode]
+        };
+    }
+    async get(documentId) {
+        this.auth.requireAuth();
+        const docData = await this.firestore.getDocument(`documents/${documentId}`);
+        if (!docData) {
+            throw new NotFoundError(`Document ${documentId} not found`);
+        }
+        const nodes = await this.firestore.getCollection(`documents/${documentId}/nodes`);
+        return {
+            ...docData,
+            nodes
+        };
+    }
+    async list() {
+        const userId = this.auth.requireAuth();
+        const documents = await this.firestore.queryCollection("documents", "owner", userId);
+        // Return shallow documents without nodes
+        return documents.map((doc) => ({
+            ...doc,
+            nodes: []
+        }));
+    }
+    async update(documentId, input) {
+        this.auth.requireAuth();
+        this.validator.validateUpdate(input);
+        const docData = await this.firestore.getDocument(`documents/${documentId}`);
+        if (!docData) {
+            throw new NotFoundError(`Document ${documentId} not found`);
+        }
+        const updates = {};
+        if (input.title !== undefined)
+            updates.title = input.title;
+        if (input.content !== undefined)
+            updates.content = input.content;
+        if (Object.keys(updates).length > 0) {
+            await this.firestore.updateDocument(`documents/${documentId}`, updates);
+        }
+    }
+    async delete(documentId) {
+        this.auth.requireAuth();
+        await this.firestore.deleteDocument(`documents/${documentId}`);
+        // Note: Sub-collection nodes are not automatically deleted
+        // A Cloud Function should handle cascading deletion
+    }
+    async share(documentId, userIds) {
+        this.auth.requireAuth();
+        const docData = await this.firestore.getDocument(`documents/${documentId}`);
+        if (!docData) {
+            throw new NotFoundError(`Document ${documentId} not found`);
+        }
+        await this.firestore.updateDocument(`documents/${documentId}`, {
+            sharedWith: userIds
+        });
+    }
+}

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

@@ -0,0 +1,33 @@
+import { GraphElement } from "@graph-knowledge/domain";
+import { IElementOperations } from "../interfaces/element-operations.interface";
+import { IFirestoreClient } from "../interfaces/firestore-client.interface";
+import { IAuthClient } from "../interfaces/auth-client.interface";
+import { IElementValidatorRegistry } from "../interfaces/element-validator.interface";
+import { AnyElementInput, UpdateElementInput } from "../types/element-input-types";
+/**
+ * Implementation of element CRUD operations.
+ */
+export declare class ElementOperations implements IElementOperations {
+    private readonly firestore;
+    private readonly auth;
+    private readonly validatorRegistry;
+    constructor(firestore: IFirestoreClient, auth: IAuthClient, validatorRegistry: IElementValidatorRegistry);
+    get(documentId: string, nodeId: string, elementId: string): Promise<GraphElement>;
+    list(documentId: string, nodeId: string): Promise<GraphElement[]>;
+    create(documentId: string, nodeId: string, input: AnyElementInput): Promise<GraphElement>;
+    update(documentId: string, nodeId: string, elementId: string, input: UpdateElementInput): Promise<void>;
+    delete(documentId: string, nodeId: string, elementId: string): Promise<void>;
+    /**
+     * Gets default dimensions for an element type.
+     */
+    private getDefaultDimensions;
+    /**
+     * Normalizes rotation to integer in range [0, 360).
+     */
+    private normalizeRotation;
+    /**
+     * Builds properties object from element input.
+     * Extracts type-specific properties, excluding common fields.
+     */
+    private buildProperties;
+}