@graph-knowledge/api 0.4.0 → 0.9.0

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

@@ -111,6 +111,40 @@ class TemplateOperations {
             nodes
         };
     }
+    async update(templateId, input) {
+        this.auth.requireAuth();
+        await this.auth.requireAdmin();
+        this.validator.validateUpdate(input);
+        const docData = await this.firestore.getDocument(`documents/${templateId}`);
+        if (!docData) {
+            throw new api_errors_1.NotFoundError(`Template ${templateId} not found`);
+        }
+        if (!docData.isTemplate) {
+            throw new api_errors_1.NotFoundError(`Document ${templateId} is not a template`);
+        }
+        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/${templateId}`, updates);
+        }
+    }
+    async delete(templateId) {
+        this.auth.requireAuth();
+        await this.auth.requireAdmin();
+        const docData = await this.firestore.getDocument(`documents/${templateId}`);
+        if (!docData) {
+            throw new api_errors_1.NotFoundError(`Template ${templateId} not found`);
+        }
+        if (!docData.isTemplate) {
+            throw new api_errors_1.NotFoundError(`Document ${templateId} is not a template`);
+        }
+        await this.firestore.deleteDocument(`documents/${templateId}`);
+        // Note: Sub-collection nodes are not automatically deleted
+        // A Cloud Function should handle cascading deletion
+    }
     async clone(templateId, title) {
         const userId = this.auth.requireAuth();
         // Require premium access for cloning
@@ -213,9 +247,13 @@ class TemplateOperations {
             level: node.level,
             owner: userId
         };
-        // Only include parentNodeId if it exists (Firestore doesn't allow undefined)
+        // Remap parentNodeId. Drop if the parent doesn't exist in the mapping
+        // (orphaned reference) rather than keeping stale IDs.
         if (node.parentNodeId) {
-            clonedNode.parentNodeId = idMapping.get(node.parentNodeId) || node.parentNodeId;
+            const mappedParentId = idMapping.get(node.parentNodeId);
+            if (mappedParentId) {
+                clonedNode.parentNodeId = mappedParentId;
+            }
         }
         return clonedNode;
     }
@@ -248,12 +286,17 @@ class TemplateOperations {
             rotation: element.rotation,
             properties: clonedProperties
         };
-        // Only include optional fields if they have values (Firestore doesn't allow undefined)
-        if (element.isLink !== undefined) {
-            clonedElement.isLink = element.isLink;
-        }
+        // Remap link target to new node ID. If the target doesn't exist in the
+        // mapping (e.g. orphaned link), drop the link rather than keeping stale IDs.
         if (element.linkTarget) {
-            clonedElement.linkTarget = idMapping.get(element.linkTarget) || element.linkTarget;
+            const mappedTarget = idMapping.get(element.linkTarget);
+            if (mappedTarget) {
+                clonedElement.isLink = element.isLink ?? true;
+                clonedElement.linkTarget = mappedTarget;
+            }
+        }
+        else if (element.isLink !== undefined) {
+            clonedElement.isLink = element.isLink;
         }
         return clonedElement;
     }

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

@@ -12,6 +12,7 @@ export declare class MockAuthClient implements IAuthClient {
         isAdmin?: boolean;
     });
     signIn(email: string, _password: string): Promise<void>;
+    signInWithCustomToken(_token: string): Promise<void>;
     signOut(): Promise<void>;
     get currentUserId(): string | null;
     requireAuth(): string;
@@ -31,4 +32,5 @@ export declare class MockAuthClient implements IAuthClient {
      * Sets the admin status for testing.
      */
     setAdmin(isAdmin: boolean): void;
+    destroy(): void;
 }

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

@@ -18,6 +18,10 @@ class MockAuthClient {
         // Simulate successful sign-in
         this._currentUserId = `mock-user-${email.split("@")[0]}`;
     }
+    async signInWithCustomToken(_token) {
+        // Simulate successful custom token sign-in
+        this._currentUserId = this._currentUserId ?? "mock-custom-token-user";
+    }
     async signOut() {
         this._currentUserId = null;
     }
@@ -66,5 +70,8 @@ class MockAuthClient {
     setAdmin(isAdmin) {
         this._isAdmin = isAdmin;
     }
+    destroy() {
+        // No-op for mock
+    }
 }
 exports.MockAuthClient = MockAuthClient;

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

@@ -1,4 +1,5 @@
-import { Document, GraphNode } from "../models";
+import { Document, GraphElement, GraphNode } from "../models";
+import { AnyElementInput } from "./element-input-types";
 /**
  * Input for creating a new document.
  */
@@ -22,10 +23,13 @@ export interface UpdateDocumentInput {
     content?: string;
 }
 /**
- * Result of document operations, extends Document with required id.
+ * Result of document operations.
+ * Always includes `id` and `rootNodeId` — every document has a root node created at document creation time.
+ * Use `rootNodeId` to add elements directly to the document's root canvas.
  */
 export type DocumentResult = Document & {
     id: string;
+    rootNodeId: string;
 };
 /**
  * Input for creating a new node.
@@ -59,6 +63,22 @@ export interface UpdateNodeInput {
 export type NodeResult = GraphNode & {
     id: string;
 };
+/**
+ * Input for creating a node with all its elements in a single atomic operation.
+ */
+export interface CreateNodeWithElementsInput extends CreateNodeInput {
+    /** Elements to create within the node */
+    elements: AnyElementInput[];
+}
+/**
+ * Result of creating a node with elements.
+ */
+export interface CreateNodeWithElementsResult {
+    /** The created node (includes elements in its elements array) */
+    node: GraphNode;
+    /** The created elements with their generated IDs */
+    elements: GraphElement[];
+}
 /**
  * Input for creating a new template (admin only).
  */
@@ -74,3 +94,94 @@ export interface CreateTemplateInput {
     /** Whether to publish immediately (defaults to false - draft) */
     isPublished?: boolean;
 }
+/**
+ * Input for updating an existing template (admin only).
+ */
+export interface UpdateTemplateInput {
+    title?: string;
+    content?: string;
+}
+/**
+ * ViewBox configuration for SVG scaling.
+ */
+export interface ViewBoxInput {
+    minX: number;
+    minY: number;
+    width: number;
+    height: number;
+}
+/**
+ * Input for creating a new custom shape.
+ */
+export interface CreateCustomShapeInput {
+    /** Shape display name (required) */
+    name: string;
+    /** Optional description for the store listing */
+    description?: string;
+    /** Material icon name for the toolbar button (defaults to "category") */
+    icon?: string;
+    /** Category for toolbar grouping (defaults to "Custom") */
+    category?: string;
+    /** The SVG path "d" attribute (required) */
+    svgPathData: string;
+    /** ViewBox for proper SVG scaling (required) */
+    viewBox: ViewBoxInput;
+    /** Default width when element is created (defaults to 120) */
+    defaultWidth?: number;
+    /** Default height when element is created (defaults to 120) */
+    defaultHeight?: number;
+    /** If true, aspect ratio is preserved on resize */
+    aspectRatioLocked?: boolean;
+    /** Default property values for new elements */
+    defaultProperties?: {
+        fillColor?: string;
+        strokeColor?: string;
+        strokeWidth?: number;
+    };
+}
+/**
+ * Input for updating an existing custom shape.
+ */
+export interface UpdateCustomShapeInput {
+    name?: string;
+    description?: string;
+    icon?: string;
+    category?: string;
+    svgPathData?: string;
+    viewBox?: ViewBoxInput;
+    defaultWidth?: number;
+    defaultHeight?: number;
+    aspectRatioLocked?: boolean;
+    defaultProperties?: {
+        fillColor?: string;
+        strokeColor?: string;
+        strokeWidth?: number;
+    };
+}
+/**
+ * Result of custom shape operations.
+ */
+export interface CustomShapeResult {
+    id: string;
+    name: string;
+    description?: string;
+    icon: string;
+    category: string;
+    authorId: string;
+    authorDisplayName?: string;
+    status: "draft" | "published";
+    createdAt: Date;
+    updatedAt?: Date;
+    publishedAt?: Date;
+    svgPathData: string;
+    viewBox: ViewBoxInput;
+    defaultWidth: number;
+    defaultHeight: number;
+    aspectRatioLocked?: boolean;
+    defaultProperties: {
+        fillColor: string;
+        strokeColor: string;
+        strokeWidth: number;
+    };
+    schemaVersion: number;
+}

package/src/lib/types/element-input-types.d.ts

@@ -1,11 +1,19 @@
 /**
  * Common properties for all element inputs.
+ *
+ * Position can be specified as either x/y (top-left) or centerX/centerY (center point).
+ * When centerX/centerY are used, x/y are computed as `centerX - width/2` and `centerY - height/2`.
+ * You cannot specify both x and centerX, or both y and centerY.
  */
 export interface BaseElementInput {
-    /** X position on canvas */
-    x: number;
-    /** Y position on canvas */
-    y: number;
+    /** X position on canvas (top-left corner). Cannot be used with centerX. */
+    x?: number;
+    /** Y position on canvas (top-left corner). Cannot be used with centerY. */
+    y?: number;
+    /** Center X position. Computes x as centerX - width/2. Cannot be used with x. */
+    centerX?: number;
+    /** Center Y position. Computes y as centerY - height/2. Cannot be used with y. */
+    centerY?: number;
     /** Element width (uses default if not specified) */
     width?: number;
     /** Element height (uses default if not specified) */
@@ -17,10 +25,26 @@ export interface BaseElementInput {
     /** Target node ID when isLink is true */
     linkTarget?: string;
 }
+/**
+ * Optional text label properties for basic shapes.
+ * Supported by: rectangle, triangle, diamond, hexagon, ellipse, block-arrow.
+ */
+export interface ShapeTextLabelProperties {
+    /** Text label displayed inside the shape */
+    text?: string;
+    /** Font size in pixels (default: 14) */
+    fontSize?: number;
+    /** Text color (hex, e.g., "#000000") */
+    textColor?: string;
+    /** Horizontal text alignment */
+    textAlign?: "left" | "center" | "right";
+    /** Vertical text alignment */
+    verticalAlign?: "top" | "middle" | "bottom";
+}
 /**
  * Input for creating a rectangle element.
  */
-export interface RectangleInput extends BaseElementInput {
+export interface RectangleInput extends BaseElementInput, ShapeTextLabelProperties {
     type: "rectangle";
     /** Fill color (hex, e.g., "#FF5733") */
     fillColor?: string;
@@ -206,7 +230,7 @@ export interface UmlNoteInput extends BaseElementInput {
 /**
  * Input for creating a triangle element.
  */
-export interface TriangleInput extends BaseElementInput {
+export interface TriangleInput extends BaseElementInput, ShapeTextLabelProperties {
     type: "triangle";
     /** Fill color (hex, e.g., "#FF5733") */
     fillColor?: string;
@@ -218,7 +242,7 @@ export interface TriangleInput extends BaseElementInput {
 /**
  * Input for creating a diamond element.
  */
-export interface DiamondInput extends BaseElementInput {
+export interface DiamondInput extends BaseElementInput, ShapeTextLabelProperties {
     type: "diamond";
     /** Fill color (hex, e.g., "#FF5733") */
     fillColor?: string;
@@ -230,7 +254,7 @@ export interface DiamondInput extends BaseElementInput {
 /**
  * Input for creating a hexagon element.
  */
-export interface HexagonInput extends BaseElementInput {
+export interface HexagonInput extends BaseElementInput, ShapeTextLabelProperties {
     type: "hexagon";
     /** Fill color (hex, e.g., "#FF5733") */
     fillColor?: string;
@@ -242,7 +266,7 @@ export interface HexagonInput extends BaseElementInput {
 /**
  * Input for creating an ellipse element.
  */
-export interface EllipseInput extends BaseElementInput {
+export interface EllipseInput extends BaseElementInput, ShapeTextLabelProperties {
     type: "ellipse";
     /** Fill color (hex, e.g., "#FF5733") */
     fillColor?: string;
@@ -262,6 +286,10 @@ export interface LineInput extends BaseElementInput {
     strokeWidth?: number;
     /** Line style (reuses LineStyle from connectors) */
     lineStyle?: LineStyle;
+    /** Marker at start of line */
+    startMarker?: MarkerType;
+    /** Marker at end of line */
+    endMarker?: MarkerType;
 }
 /**
  * Input for creating a cubic bezier curve element.
@@ -298,7 +326,7 @@ export type BlockArrowDirection = "right" | "left" | "up" | "down";
 /**
  * Input for creating a block arrow element.
  */
-export interface BlockArrowInput extends BaseElementInput {
+export interface BlockArrowInput extends BaseElementInput, ShapeTextLabelProperties {
     type: "block-arrow";
     /** Fill color (hex, e.g., "#FF5733") */
     fillColor?: string;

package/src/lib/utils/element-builder.d.ts

@@ -0,0 +1,63 @@
+import { GraphElement } from "../models";
+import { IElementValidatorRegistry } from "../interfaces/element-validator.interface";
+import { IFirestoreClient } from "../interfaces/firestore-client.interface";
+import { IAuthClient } from "../interfaces/auth-client.interface";
+import { AnyElementInput } from "../types/element-input-types";
+import { CustomShapeResult } from "../types/api-types";
+/**
+ * Builds GraphElement objects from AnyElementInput without persisting to Firestore.
+ *
+ * Handles: validation, default dimensions, centerX/centerY resolution,
+ * text auto-measurement, property building, custom shape enrichment.
+ *
+ * Shared by ElementOperations (single create) and NodeOperations (createWithElements).
+ */
+export declare class ElementBuilder {
+    private readonly validatorRegistry;
+    private readonly firestore;
+    private readonly auth;
+    private static _textMeasurementService;
+    constructor(validatorRegistry: IElementValidatorRegistry, firestore: IFirestoreClient, auth: IAuthClient);
+    /**
+     * Builds multiple GraphElements from inputs.
+     * Pre-fetches custom shape definitions with deduplication for efficiency.
+     */
+    buildMany(inputs: AnyElementInput[]): Promise<GraphElement[]>;
+    /**
+     * Builds a GraphElement from input.
+     * Validates, resolves defaults and center positioning, builds properties,
+     * enriches custom shapes. Does NOT write to Firestore.
+     */
+    build(input: AnyElementInput, shapeCache?: Map<string, CustomShapeResult>): Promise<GraphElement>;
+    /**
+     * Validates that centerX/centerY are not used together with x/y.
+     */
+    private validateCenterPosition;
+    /**
+     * Resolves x/y position, handling centerX/centerY conversion.
+     */
+    private resolvePosition;
+    /**
+     * Gets default dimensions for an element type.
+     */
+    private getDefaultDimensions;
+    /**
+     * Auto-measures text width for text elements created without explicit width/maxWidth.
+     */
+    private measureTextWidth;
+    /**
+     * Pre-fetches custom shape definitions from the shape store.
+     * Each unique shape is fetched only once for efficiency.
+     */
+    private _prefetchCustomShapes;
+    /**
+     * Enriches custom shape element properties with shape definition data
+     * from the published shape store or a pre-fetched cache.
+     */
+    private _enrichCustomShapeProperties;
+    /**
+     * Builds properties object from element input.
+     * Extracts type-specific properties, excluding common/positional fields.
+     */
+    private buildProperties;
+}

package/src/lib/utils/element-builder.js

@@ -0,0 +1,258 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ElementBuilder = void 0;
+const uuid_1 = require("./uuid");
+const api_errors_1 = require("../errors/api-errors");
+const element_defaults_1 = require("../constants/element-defaults");
+const text_measurement_service_1 = require("./text-measurement/text-measurement-service");
+const rotation_1 = require("./rotation");
+/**
+ * Builds GraphElement objects from AnyElementInput without persisting to Firestore.
+ *
+ * Handles: validation, default dimensions, centerX/centerY resolution,
+ * text auto-measurement, property building, custom shape enrichment.
+ *
+ * Shared by ElementOperations (single create) and NodeOperations (createWithElements).
+ */
+class ElementBuilder {
+    validatorRegistry;
+    firestore;
+    auth;
+    static _textMeasurementService = null;
+    constructor(validatorRegistry, firestore, auth) {
+        this.validatorRegistry = validatorRegistry;
+        this.firestore = firestore;
+        this.auth = auth;
+    }
+    /**
+     * Builds multiple GraphElements from inputs.
+     * Pre-fetches custom shape definitions with deduplication for efficiency.
+     */
+    async buildMany(inputs) {
+        // Pre-fetch custom shape definitions (one fetch per unique shape)
+        const shapeCache = await this._prefetchCustomShapes(inputs);
+        const elements = [];
+        for (const input of inputs) {
+            elements.push(await this.build(input, shapeCache));
+        }
+        return elements;
+    }
+    /**
+     * Builds a GraphElement from input.
+     * Validates, resolves defaults and center positioning, builds properties,
+     * enriches custom shapes. Does NOT write to Firestore.
+     */
+    async build(input, shapeCache) {
+        // Custom shapes require premium
+        if (input.type.startsWith("custom:")) {
+            await this.auth.requirePremium();
+        }
+        // Validate centerX/centerY conflicts before anything else
+        this.validateCenterPosition(input);
+        // Resolve default dimensions
+        const defaults = this.getDefaultDimensions(input.type);
+        // Resolve text width
+        let resolvedWidth = input.width;
+        if (input.type === "text" && resolvedWidth === undefined) {
+            const textInput = input;
+            if (textInput.maxWidth !== undefined) {
+                resolvedWidth = textInput.maxWidth;
+            }
+            else {
+                resolvedWidth = this.measureTextWidth(textInput);
+            }
+        }
+        const width = resolvedWidth ?? defaults.width;
+        const height = input.height ?? defaults.height;
+        // Resolve centerX/centerY → x/y (after defaults, since center depends on dimensions)
+        const { x, y } = this.resolvePosition(input, width, height);
+        // Create a resolved copy of the input with x/y set for validation
+        const resolvedInput = { ...input, x, y };
+        // Remove center fields so validators don't see unknown properties
+        delete resolvedInput["centerX"];
+        delete resolvedInput["centerY"];
+        // Validate the resolved input (validators expect x/y to be numbers)
+        this.validatorRegistry.validate(resolvedInput);
+        let properties = this.buildProperties(input);
+        // For custom shapes, bake shape definition into properties
+        if (input.type.startsWith("custom:")) {
+            properties = await this._enrichCustomShapeProperties(properties, shapeCache);
+        }
+        const element = {
+            id: (0, uuid_1.generateUuid)(),
+            elementType: input.type,
+            x,
+            y,
+            width,
+            height,
+            rotation: (0, rotation_1.normalizeRotation)(input.rotation ?? 0),
+            properties
+        };
+        // 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;
+        }
+        return element;
+    }
+    /**
+     * Validates that centerX/centerY are not used together with x/y.
+     */
+    validateCenterPosition(input) {
+        // ConnectorInput doesn't support center positioning
+        if (input.type === "connector") {
+            return;
+        }
+        const record = input;
+        const hasCenterX = record["centerX"] !== undefined;
+        const hasCenterY = record["centerY"] !== undefined;
+        if (hasCenterX && input.x !== undefined) {
+            throw new api_errors_1.ValidationError("Cannot specify both x and centerX", "centerX");
+        }
+        if (hasCenterY && input.y !== undefined) {
+            throw new api_errors_1.ValidationError("Cannot specify both y and centerY", "centerY");
+        }
+        // Validate types if provided
+        if (hasCenterX) {
+            const centerX = record["centerX"];
+            if (typeof centerX !== "number" || isNaN(centerX)) {
+                throw new api_errors_1.ValidationError("centerX must be a valid number", "centerX");
+            }
+        }
+        if (hasCenterY) {
+            const centerY = record["centerY"];
+            if (typeof centerY !== "number" || isNaN(centerY)) {
+                throw new api_errors_1.ValidationError("centerY must be a valid number", "centerY");
+            }
+        }
+    }
+    /**
+     * Resolves x/y position, handling centerX/centerY conversion.
+     */
+    resolvePosition(input, width, height) {
+        const record = input;
+        const centerX = record["centerX"];
+        const centerY = record["centerY"];
+        return {
+            x: centerX !== undefined
+                ? centerX - width / 2
+                : (input.x ?? 0),
+            y: centerY !== undefined
+                ? centerY - height / 2
+                : (input.y ?? 0)
+        };
+    }
+    /**
+     * Gets default dimensions for an element type.
+     */
+    getDefaultDimensions(type) {
+        if (type.startsWith("custom:")) {
+            return element_defaults_1.DEFAULT_CUSTOM_SHAPE_DIMENSIONS;
+        }
+        return (element_defaults_1.DEFAULT_ELEMENT_DIMENSIONS[type] ?? element_defaults_1.DEFAULT_CUSTOM_SHAPE_DIMENSIONS);
+    }
+    /**
+     * Auto-measures text width for text elements created without explicit width/maxWidth.
+     */
+    measureTextWidth(input) {
+        if (!ElementBuilder._textMeasurementService) {
+            ElementBuilder._textMeasurementService =
+                new text_measurement_service_1.TextMeasurementService();
+        }
+        const metrics = ElementBuilder._textMeasurementService.measureText(input.text, {
+            fontSize: input.fontSize,
+            fontFamily: input.fontFamily,
+            fontWeight: input.fontWeight,
+            textAlign: input.textAlign,
+            lineHeight: input.lineHeight
+        });
+        return Math.ceil(metrics.width);
+    }
+    /**
+     * Pre-fetches custom shape definitions from the shape store.
+     * Each unique shape is fetched only once for efficiency.
+     */
+    async _prefetchCustomShapes(inputs) {
+        const shapeIds = new Set();
+        for (const input of inputs) {
+            if (input.type.startsWith("custom:")) {
+                const shapeId = input["customShapeId"];
+                if (shapeId) {
+                    shapeIds.add(shapeId);
+                }
+            }
+        }
+        const cache = new Map();
+        await Promise.all(Array.from(shapeIds).map(async (shapeId) => {
+            const shape = await this.firestore.getDocument(`shapeStore/${shapeId}`);
+            if (shape) {
+                cache.set(shapeId, shape);
+            }
+        }));
+        return cache;
+    }
+    /**
+     * Enriches custom shape element properties with shape definition data
+     * from the published shape store or a pre-fetched cache.
+     */
+    async _enrichCustomShapeProperties(properties, shapeCache) {
+        const shapeId = properties["customShapeId"];
+        if (!shapeId) {
+            return properties;
+        }
+        // Skip if already has svgPathData (caller provided it explicitly)
+        if (properties["svgPathData"]) {
+            return properties;
+        }
+        // Use cache if available, otherwise fetch directly
+        const shape = shapeCache
+            ? shapeCache.get(shapeId) ?? null
+            : await this.firestore.getDocument(`shapeStore/${shapeId}`);
+        if (!shape) {
+            return properties;
+        }
+        return {
+            ...properties,
+            svgPathData: shape.svgPathData,
+            viewBox: shape.viewBox,
+            aspectRatioLocked: shape.aspectRatioLocked ?? false
+        };
+    }
+    /**
+     * Builds properties object from element input.
+     * Extracts type-specific properties, excluding common/positional fields.
+     */
+    buildProperties(input) {
+        const props = {
+            __schemaVersion: 1
+        };
+        // Exclude common fields, positional aliases, and convenience aliases
+        const commonFields = new Set([
+            "type",
+            "x",
+            "y",
+            "centerX",
+            "centerY",
+            "width",
+            "height",
+            "rotation",
+            "isLink",
+            "linkTarget",
+            "maxWidth"
+        ]);
+        for (const [key, value] of Object.entries(input)) {
+            if (!commonFields.has(key) && value !== undefined) {
+                props[key] = value;
+            }
+        }
+        // For text elements, set __usesTopLeft: true so the app knows
+        // that x/y is the bounding box top-left, not the text anchor point.
+        if (input.type === "text") {
+            props["__usesTopLeft"] = true;
+        }
+        return props;
+    }
+}
+exports.ElementBuilder = ElementBuilder;

package/src/lib/utils/rotation.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Normalizes rotation to integer in range [0, 360).
+ */
+export declare function normalizeRotation(rotation: number): number;