@graph-knowledge/api 0.3.2 → 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,38 @@ 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.
+ *
+ * The curve is defined by two endpoints and two control points:
+ * - Start point: (x, y)
+ * - End point: (x + width, y + height)
+ * - Control point 1: offset from start (controlPoint1X, controlPoint1Y)
+ * - Control point 2: offset from end (controlPoint2X, controlPoint2Y)
+ *
+ * If control points are omitted, a default S-curve is computed.
+ */
+export interface BezierCurveInput extends BaseElementInput {
+    type: "bezier-curve";
+    /** Stroke color (hex) */
+    strokeColor?: string;
+    /** Stroke width in pixels */
+    strokeWidth?: number;
+    /** Line style */
+    lineStyle?: LineStyle;
+    /** Control point 1 X offset from start */
+    controlPoint1X?: number;
+    /** Control point 1 Y offset from start */
+    controlPoint1Y?: number;
+    /** Control point 2 X offset from end */
+    controlPoint2X?: number;
+    /** Control point 2 Y offset from end */
+    controlPoint2Y?: number;
 }
 /**
  * Direction for block arrow elements.
@@ -270,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;
@@ -300,7 +356,7 @@ export interface CustomShapeInput extends BaseElementInput {
 /**
  * Union of all element input types.
  */
-export type AnyElementInput = RectangleInput | TextInput | ConnectorInput | UmlClassInput | UmlInterfaceInput | UmlComponentInput | UmlPackageInput | UmlArtifactInput | UmlNoteInput | TriangleInput | DiamondInput | HexagonInput | EllipseInput | LineInput | BlockArrowInput | CustomShapeInput;
+export type AnyElementInput = RectangleInput | TextInput | ConnectorInput | UmlClassInput | UmlInterfaceInput | UmlComponentInput | UmlPackageInput | UmlArtifactInput | UmlNoteInput | TriangleInput | DiamondInput | HexagonInput | EllipseInput | LineInput | BezierCurveInput | BlockArrowInput | CustomShapeInput;
 /**
  * Input for updating an existing element.
  */

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;
+}