@graph-knowledge/api 0.1.0

package/README.md

@@ -0,0 +1,396 @@
+# @graph-knowledge/api
+
+Headless Document API for Graph Knowledge - provides programmatic access to documents, nodes, and elements without requiring the Angular UI.
+
+## Installation
+
+### npm (for external use)
+
+```bash
+npm install @graph-knowledge/api firebase
+```
+
+### Monorepo (internal use)
+
+```typescript
+import { GraphKnowledgeAPI } from "@graph-knowledge/api";
+```
+
+## Quick Start
+
+```typescript
+import { GraphKnowledgeAPI } from "@graph-knowledge/api";
+
+// Initialize with your Firebase config
+const api = new GraphKnowledgeAPI({
+    firebaseConfig: {
+        apiKey: "your-api-key",
+        authDomain: "your-project.firebaseapp.com",
+        projectId: "your-project",
+        storageBucket: "your-project.appspot.com",
+        messagingSenderId: "123456789",
+        appId: "1:123456789:web:abc123"
+    }
+});
+
+// Sign in
+await api.signIn("user@example.com", "password");
+
+// Create a document
+const doc = await api.documents.create({
+    title: "My Document",
+    content: "Description"
+});
+
+// Create a node in the document
+const node = await api.nodes.create(doc.id, {
+    title: "My Node",
+    canvasWidth: 1920,
+    canvasHeight: 1080
+});
+
+// Add elements to the node
+await api.elements.create(doc.id, node.id, {
+    type: "rectangle",
+    x: 100,
+    y: 100,
+    width: 200,
+    height: 150,
+    fillColor: "#FF5733",
+    strokeColor: "#000000"
+});
+
+await api.elements.create(doc.id, node.id, {
+    type: "text",
+    x: 150,
+    y: 160,
+    text: "Hello World",
+    fontSize: 24
+});
+
+// Sign out
+await api.signOut();
+```
+
+## API Reference
+
+### GraphKnowledgeAPI
+
+Main entry point for the API.
+
+#### Constructor
+
+```typescript
+new GraphKnowledgeAPI(config: ApiConfig)
+```
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `signIn(email, password)` | Signs in with email and password |
+| `signOut()` | Signs out the current user |
+| `waitForAuthInit()` | Waits for Firebase Auth to initialize |
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `currentUserId` | `string \| null` | Current user's ID |
+| `documents` | `IDocumentOperations` | Document CRUD operations |
+| `nodes` | `INodeOperations` | Node CRUD operations |
+| `elements` | `IElementOperations` | Element CRUD operations |
+| `batch` | `IBatchOperations` | Batch element operations |
+| `authClient` | `IAuthClient` | Authentication client |
+
+### Document Operations
+
+```typescript
+// Create a document
+const doc = await api.documents.create({
+    title: "My Document",
+    content: "Optional description",
+    canvasWidth: 1920,  // Optional, default: 1920
+    canvasHeight: 1080  // Optional, default: 1080
+});
+
+// Get a document by ID
+const doc = await api.documents.get(documentId);
+
+// List all documents
+const docs = await api.documents.list();
+
+// Update a document
+await api.documents.update(documentId, {
+    title: "New Title",
+    content: "New description"
+});
+
+// Delete a document
+await api.documents.delete(documentId);
+
+// Share a document
+await api.documents.share(documentId, ["user-id-1", "user-id-2"]);
+```
+
+### Node Operations
+
+```typescript
+// Create a node
+const node = await api.nodes.create(documentId, {
+    title: "My Node",
+    content: "Optional description",
+    parentNodeId: "parent-node-id",  // Optional
+    canvasWidth: 1920,
+    canvasHeight: 1080
+});
+
+// Get a node
+const node = await api.nodes.get(documentId, nodeId);
+
+// List all nodes in a document
+const nodes = await api.nodes.list(documentId);
+
+// Update a node
+await api.nodes.update(documentId, nodeId, {
+    title: "New Title"
+});
+
+// Delete a node
+await api.nodes.delete(documentId, nodeId);
+```
+
+### Element Operations
+
+```typescript
+// Get an element by ID
+const element = await api.elements.get(documentId, nodeId, elementId);
+
+// List all elements in a node
+const elements = await api.elements.list(documentId, nodeId);
+
+// Create a rectangle
+const rect = await api.elements.create(documentId, nodeId, {
+    type: "rectangle",
+    x: 100,
+    y: 100,
+    width: 200,
+    height: 150,
+    fillColor: "#FF5733",
+    strokeColor: "#000000",
+    strokeWidth: 2,
+    cornerRadius: 10
+});
+
+// Create text
+await api.elements.create(documentId, nodeId, {
+    type: "text",
+    x: 100,
+    y: 100,
+    text: "Hello World",
+    fontSize: 24,
+    fontFamily: "Arial",
+    fillColor: "#000000",
+    textAlign: "center"
+});
+
+// Create a connector
+await api.elements.create(documentId, nodeId, {
+    type: "connector",
+    x: 0,
+    y: 0,
+    startElementId: "element-1",
+    endElementId: "element-2",
+    startAnchor: "right",
+    endAnchor: "left",
+    lineStyle: "solid",
+    endMarker: "arrow"
+});
+
+// Create a UML class
+await api.elements.create(documentId, nodeId, {
+    type: "uml-class",
+    x: 100,
+    y: 100,
+    width: 200,
+    height: 150,
+    name: "MyClass",
+    attributes: "+ name: string\n- id: number",
+    methods: "+ getName(): string\n+ setName(name: string): void"
+});
+
+// Update an element
+await api.elements.update(documentId, nodeId, elementId, {
+    x: 200,
+    y: 200,
+    properties: {
+        fillColor: "#00FF00"
+    }
+});
+
+// Delete an element
+await api.elements.delete(documentId, nodeId, elementId);
+```
+
+### Batch Operations
+
+For efficient bulk operations (ideal for AI agents and automation):
+
+```typescript
+// Create multiple elements atomically
+const elements = await api.batch.createElements(documentId, nodeId, [
+    { type: "rectangle", x: 100, y: 100 },
+    { type: "rectangle", x: 300, y: 100 },
+    { type: "text", x: 200, y: 200, text: "Connected" }
+]);
+
+// Update multiple elements atomically
+await api.batch.updateElements(documentId, nodeId, [
+    { elementId: "elem-1", x: 150, y: 150 },
+    { elementId: "elem-2", width: 300, height: 200 }
+]);
+
+// Delete multiple elements atomically
+await api.batch.deleteElements(documentId, nodeId, [
+    "elem-1",
+    "elem-2",
+    "elem-3"
+]);
+```
+
+## Supported Element Types
+
+| Type | Description |
+|------|-------------|
+| `rectangle` | Rectangle shape with fill, stroke, corner radius |
+| `text` | Text element with font customization |
+| `connector` | Line connecting two elements |
+| `uml-class` | UML class diagram element |
+| `uml-interface` | UML interface element |
+| `uml-component` | UML component element |
+| `uml-package` | UML package element |
+| `uml-artifact` | UML artifact element |
+| `uml-note` | UML note element |
+| `custom:{shapeId}` | Custom SVG shape (requires premium) |
+
+## Link Navigation
+
+Elements can act as links to other nodes:
+
+```typescript
+// Create an element that links to another node
+await api.elements.create(documentId, nodeId, {
+    type: "rectangle",
+    x: 100,
+    y: 100,
+    isLink: true,
+    linkTarget: "other-node-id"  // Node ID to navigate to
+});
+```
+
+## Error Handling
+
+The API throws typed errors for different failure cases:
+
+```typescript
+import {
+    GraphKnowledgeAPI,
+    AuthenticationError,
+    NotFoundError,
+    ValidationError,
+    PermissionError
+} from "@graph-knowledge/api";
+
+try {
+    await api.documents.get("non-existent");
+} catch (error) {
+    if (error instanceof NotFoundError) {
+        console.log("Document not found");
+    } else if (error instanceof AuthenticationError) {
+        console.log("Not authenticated");
+    } else if (error instanceof ValidationError) {
+        console.log("Invalid input:", error.field);
+    } else if (error instanceof PermissionError) {
+        console.log("Permission denied (e.g., premium required)");
+    }
+}
+```
+
+## Testing
+
+The library exports mock implementations for testing:
+
+```typescript
+import {
+    MockAuthClient,
+    MockFirestoreClient
+} from "@graph-knowledge/api";
+import { ElementOperations } from "@graph-knowledge/api";
+import { ElementValidatorRegistry } from "@graph-knowledge/api";
+
+describe("MyTest", () => {
+    let mockAuth: MockAuthClient;
+    let mockFirestore: MockFirestoreClient;
+
+    beforeEach(() => {
+        mockAuth = new MockAuthClient({ userId: "test-user" });
+        mockFirestore = new MockFirestoreClient();
+    });
+
+    it("should work with mocks", async () => {
+        // Seed test data
+        mockFirestore.seed("documents/doc-1/nodes/node-1", {
+            id: "node-1",
+            title: "Test Node",
+            elements: []
+        });
+
+        // Test your code...
+    });
+});
+```
+
+## Architecture
+
+The library follows SOLID principles:
+
+- **Single Responsibility**: Each class has one job
+- **Open/Closed**: Element validators use registry pattern for extensibility
+- **Liskov Substitution**: All implementations can be swapped via interfaces
+- **Interface Segregation**: Small, focused interfaces
+- **Dependency Inversion**: Operations depend on interfaces, not implementations
+
+```
+GraphKnowledgeAPI (Composition Root)
+    ├── FirebaseAuthClient : IAuthClient
+    ├── FirebaseFirestoreClient : IFirestoreClient
+    ├── DocumentOperations : IDocumentOperations
+    ├── NodeOperations : INodeOperations
+    ├── ElementOperations : IElementOperations
+    ├── BatchOperations : IBatchOperations
+    └── ElementValidatorRegistry : IElementValidatorRegistry
+            ├── RectangleValidator
+            ├── TextValidator
+            ├── ConnectorValidator
+            └── UmlValidators...
+```
+
+## Building
+
+```bash
+# Build
+nx build api
+
+# Test
+nx test api
+
+# Lint
+nx lint api
+
+# Publish to npm (after build)
+nx publish api
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@graph-knowledge/api",
+  "version": "0.1.0",
+  "description": "Headless Document API for Graph Knowledge - programmatic access to documents, nodes, and elements",
+  "license": "MIT",
+  "author": "Graph Knowledge Team",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iliedanila/knowledge-graph.git",
+    "directory": "libs/api"
+  },
+  "keywords": [
+    "graph",
+    "knowledge-graph",
+    "document-api",
+    "firebase",
+    "uml",
+    "diagram"
+  ],
+  "main": "./src/index.js",
+  "module": "./src/index.mjs",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.mjs",
+      "require": "./src/index.js"
+    }
+  },
+  "files": [
+    "src/**/*.js",
+    "src/**/*.mjs",
+    "src/**/*.d.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "firebase": ">=10.0.0 <13.0.0"
+  },
+  "sideEffects": false,
+  "type": "commonjs"
+}

package/src/index.d.ts

@@ -0,0 +1,18 @@
+export { GraphKnowledgeAPI } from "./lib/graph-knowledge-api";
+export type { ApiConfig, FirebaseConfig } from "./lib/config/api-config";
+export type { IAuthClient } from "./lib/interfaces/auth-client.interface";
+export type { IFirestoreClient, IBatchWriter } from "./lib/interfaces/firestore-client.interface";
+export type { IDocumentOperations } from "./lib/interfaces/document-operations.interface";
+export type { INodeOperations } from "./lib/interfaces/node-operations.interface";
+export type { IElementOperations } from "./lib/interfaces/element-operations.interface";
+export type { IBatchOperations, BatchUpdateElementInput } from "./lib/interfaces/batch-operations.interface";
+export type { IElementTypeValidator, IElementValidatorRegistry } from "./lib/interfaces/element-validator.interface";
+export type { CreateDocumentInput, UpdateDocumentInput, DocumentResult, CreateNodeInput, UpdateNodeInput, NodeResult } from "./lib/types/api-types";
+export type { BaseElementInput, RectangleInput, TextInput, ConnectorInput, ConnectorAnchor, LineStyle, MarkerType, UmlClassInput, UmlInterfaceInput, UmlComponentInput, UmlPackageInput, UmlArtifactInput, UmlNoteInput, CustomShapeInput, AnyElementInput, UpdateElementInput } from "./lib/types/element-input-types";
+export { GraphKnowledgeAPIError, AuthenticationError, NotFoundError, ValidationError, PermissionError } from "./lib/errors/api-errors";
+export type { Document, GraphNode, GraphElement } from "./lib/models";
+export { CURRENT_DOCUMENT_SCHEMA_VERSION } from "./lib/models";
+export { LinkLevelManager } from "./lib/utils/link-level-manager";
+export type { LevelChange, LinkState } from "./lib/utils/link-level-manager";
+export { MockAuthClient } from "./lib/testing/mock-auth-client";
+export { MockFirestoreClient } from "./lib/testing/mock-firestore-client";

package/src/index.js

@@ -0,0 +1,19 @@
+// =============================================================================
+// Graph Knowledge Headless Document API
+// =============================================================================
+// Main API Class
+export { GraphKnowledgeAPI } from "./lib/graph-knowledge-api";
+// =============================================================================
+// Errors
+// =============================================================================
+export { GraphKnowledgeAPIError, AuthenticationError, NotFoundError, ValidationError, PermissionError } from "./lib/errors/api-errors";
+export { CURRENT_DOCUMENT_SCHEMA_VERSION } from "./lib/models";
+// =============================================================================
+// Utilities
+// =============================================================================
+export { LinkLevelManager } from "./lib/utils/link-level-manager";
+// =============================================================================
+// Testing Utilities
+// =============================================================================
+export { MockAuthClient } from "./lib/testing/mock-auth-client";
+export { MockFirestoreClient } from "./lib/testing/mock-firestore-client";

package/src/lib/clients/firebase-auth-client.d.ts

@@ -0,0 +1,24 @@
+import { Auth } from "firebase/auth";
+import { Firestore } from "firebase/firestore";
+import { IAuthClient } from "../interfaces/auth-client.interface";
+/**
+ * Firebase Auth implementation of IAuthClient.
+ */
+export declare class FirebaseAuthClient implements IAuthClient {
+    private readonly auth;
+    private readonly firestore;
+    private _currentUser;
+    private _initialized;
+    private _initPromise;
+    constructor(auth: Auth, firestore: Firestore);
+    /**
+     * Waits for auth state to be initialized.
+     */
+    waitForInit(): Promise<void>;
+    signIn(email: string, password: string): Promise<void>;
+    signOut(): Promise<void>;
+    get currentUserId(): string | null;
+    requireAuth(): string;
+    isPremium(): Promise<boolean>;
+    requirePremium(): Promise<void>;
+}

package/src/lib/clients/firebase-auth-client.js

@@ -0,0 +1,76 @@
+import { signInWithEmailAndPassword, signOut as firebaseSignOut, onAuthStateChanged } from "firebase/auth";
+import { doc, getDoc } from "firebase/firestore";
+import { AuthenticationError, PermissionError } from "../errors/api-errors";
+/**
+ * Firebase Auth implementation of IAuthClient.
+ */
+export class FirebaseAuthClient {
+    auth;
+    firestore;
+    _currentUser = null;
+    _initialized = false;
+    _initPromise;
+    constructor(auth, firestore) {
+        this.auth = auth;
+        this.firestore = firestore;
+        this._initPromise = new Promise((resolve) => {
+            const unsubscribe = onAuthStateChanged(this.auth, (user) => {
+                this._currentUser = user;
+                if (!this._initialized) {
+                    this._initialized = true;
+                    unsubscribe();
+                    resolve();
+                }
+            });
+        });
+    }
+    /**
+     * Waits for auth state to be initialized.
+     */
+    async waitForInit() {
+        return this._initPromise;
+    }
+    async signIn(email, password) {
+        try {
+            const credential = await signInWithEmailAndPassword(this.auth, email, password);
+            this._currentUser = credential.user;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Sign in failed";
+            throw new AuthenticationError(message);
+        }
+    }
+    async signOut() {
+        await firebaseSignOut(this.auth);
+        this._currentUser = null;
+    }
+    get currentUserId() {
+        return this._currentUser?.uid ?? null;
+    }
+    requireAuth() {
+        if (!this._currentUser) {
+            throw new AuthenticationError("Not authenticated");
+        }
+        return this._currentUser.uid;
+    }
+    async isPremium() {
+        if (!this._currentUser) {
+            return false;
+        }
+        // Read premium status from user profile in Firestore
+        const userDoc = doc(this.firestore, `users/${this._currentUser.uid}`);
+        const snapshot = await getDoc(userDoc);
+        if (!snapshot.exists()) {
+            return false;
+        }
+        const profile = snapshot.data();
+        return profile?.["isPremium"] === true;
+    }
+    async requirePremium() {
+        this.requireAuth();
+        const premium = await this.isPremium();
+        if (!premium) {
+            throw new PermissionError("Premium subscription required");
+        }
+    }
+}

package/src/lib/clients/firebase-firestore-client.d.ts

@@ -0,0 +1,22 @@
+import { Firestore } from "firebase/firestore";
+import { IFirestoreClient, IBatchWriter } from "../interfaces/firestore-client.interface";
+/**
+ * Firebase Firestore implementation of IFirestoreClient.
+ */
+export declare class FirebaseFirestoreClient implements IFirestoreClient {
+    private readonly db;
+    constructor(db: Firestore);
+    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;
+}

package/src/lib/clients/firebase-firestore-client.js

@@ -0,0 +1,79 @@
+import { doc, getDoc, setDoc, updateDoc, deleteDoc, collection, getDocs, query, where, writeBatch } from "firebase/firestore";
+/**
+ * Firebase Firestore batch writer implementation.
+ */
+class FirestoreBatchWriter {
+    db;
+    batch;
+    constructor(db, batch) {
+        this.db = db;
+        this.batch = batch;
+    }
+    set(path, data) {
+        const docRef = doc(this.db, path);
+        this.batch.set(docRef, data);
+    }
+    update(path, data) {
+        const docRef = doc(this.db, path);
+        this.batch.update(docRef, data);
+    }
+    delete(path) {
+        const docRef = doc(this.db, path);
+        this.batch.delete(docRef);
+    }
+    async commit() {
+        await this.batch.commit();
+    }
+}
+/**
+ * Firebase Firestore implementation of IFirestoreClient.
+ */
+export class FirebaseFirestoreClient {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async getDocument(path) {
+        const docRef = doc(this.db, path);
+        const snapshot = await getDoc(docRef);
+        if (!snapshot.exists()) {
+            return null;
+        }
+        return {
+            id: snapshot.id,
+            ...snapshot.data()
+        };
+    }
+    async setDocument(path, data) {
+        const docRef = doc(this.db, path);
+        await setDoc(docRef, data);
+    }
+    async updateDocument(path, data) {
+        const docRef = doc(this.db, path);
+        await updateDoc(docRef, data);
+    }
+    async deleteDocument(path) {
+        const docRef = doc(this.db, path);
+        await deleteDoc(docRef);
+    }
+    async getCollection(path) {
+        const collectionRef = collection(this.db, path);
+        const snapshot = await getDocs(collectionRef);
+        return snapshot.docs.map((doc) => ({
+            id: doc.id,
+            ...doc.data()
+        }));
+    }
+    async queryCollection(path, field, value) {
+        const collectionRef = collection(this.db, path);
+        const q = query(collectionRef, where(field, "==", value));
+        const snapshot = await getDocs(q);
+        return snapshot.docs.map((doc) => ({
+            id: doc.id,
+            ...doc.data()
+        }));
+    }
+    batch() {
+        return new FirestoreBatchWriter(this.db, writeBatch(this.db));
+    }
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Firebase configuration required to initialize the API.
+ */
+export interface FirebaseConfig {
+    apiKey: string;
+    authDomain: string;
+    projectId: string;
+    storageBucket: string;
+    messagingSenderId: string;
+    appId: string;
+}
+/**
+ * Configuration options for GraphKnowledgeAPI.
+ */
+export interface ApiConfig {
+    /** Firebase project configuration */
+    firebaseConfig: FirebaseConfig;
+    /** Optional app name for multiple Firebase instances */
+    appName?: string;
+}