@graph-knowledge/api 0.1.0

package/src/lib/constants/element-defaults.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Default dimensions per element type.
+ * Shared between ElementOperations and BatchOperations.
+ */
+export declare const DEFAULT_ELEMENT_DIMENSIONS: Record<string, {
+    width: number;
+    height: number;
+}>;
+/**
+ * Default dimensions for custom shapes.
+ */
+export declare const DEFAULT_CUSTOM_SHAPE_DIMENSIONS: {
+    width: number;
+    height: number;
+};

package/src/lib/constants/element-defaults.js

@@ -0,0 +1,19 @@
+/**
+ * Default dimensions per element type.
+ * Shared between ElementOperations and BatchOperations.
+ */
+export const DEFAULT_ELEMENT_DIMENSIONS = {
+    rectangle: { width: 150, height: 120 },
+    text: { width: 100, height: 30 },
+    connector: { width: 0, height: 0 },
+    "uml-class": { width: 150, height: 120 },
+    "uml-interface": { width: 150, height: 100 },
+    "uml-component": { width: 150, height: 100 },
+    "uml-package": { width: 200, height: 150 },
+    "uml-artifact": { width: 100, height: 80 },
+    "uml-note": { width: 150, height: 100 }
+};
+/**
+ * Default dimensions for custom shapes.
+ */
+export const DEFAULT_CUSTOM_SHAPE_DIMENSIONS = { width: 100, height: 100 };

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

@@ -0,0 +1,33 @@
+/**
+ * Base error class for all API errors.
+ */
+export declare class GraphKnowledgeAPIError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Thrown when authentication fails or user is not authenticated.
+ */
+export declare class AuthenticationError extends GraphKnowledgeAPIError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a requested resource is not found.
+ */
+export declare class NotFoundError extends GraphKnowledgeAPIError {
+    constructor(message: string);
+}
+/**
+ * Thrown when input validation fails.
+ */
+export declare class ValidationError extends GraphKnowledgeAPIError {
+    readonly field?: string | undefined;
+    readonly details?: Record<string, string> | undefined;
+    constructor(message: string, field?: string | undefined, details?: Record<string, string> | undefined);
+}
+/**
+ * Thrown when the user lacks permission to perform an operation.
+ */
+export declare class PermissionError extends GraphKnowledgeAPIError {
+    constructor(message: string);
+}

package/src/lib/errors/api-errors.js

@@ -0,0 +1,51 @@
+/**
+ * Base error class for all API errors.
+ */
+export class GraphKnowledgeAPIError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "GraphKnowledgeAPIError";
+    }
+}
+/**
+ * Thrown when authentication fails or user is not authenticated.
+ */
+export class AuthenticationError extends GraphKnowledgeAPIError {
+    constructor(message) {
+        super(message, "AUTH_ERROR");
+        this.name = "AuthenticationError";
+    }
+}
+/**
+ * Thrown when a requested resource is not found.
+ */
+export class NotFoundError extends GraphKnowledgeAPIError {
+    constructor(message) {
+        super(message, "NOT_FOUND");
+        this.name = "NotFoundError";
+    }
+}
+/**
+ * Thrown when input validation fails.
+ */
+export class ValidationError extends GraphKnowledgeAPIError {
+    field;
+    details;
+    constructor(message, field, details) {
+        super(message, "VALIDATION_ERROR");
+        this.field = field;
+        this.details = details;
+        this.name = "ValidationError";
+    }
+}
+/**
+ * Thrown when the user lacks permission to perform an operation.
+ */
+export class PermissionError extends GraphKnowledgeAPIError {
+    constructor(message) {
+        super(message, "PERMISSION_DENIED");
+        this.name = "PermissionError";
+    }
+}

package/src/lib/graph-knowledge-api.d.ts

@@ -0,0 +1,106 @@
+import { ApiConfig } from "./config/api-config";
+import { IAuthClient } from "./interfaces/auth-client.interface";
+import { IDocumentOperations } from "./interfaces/document-operations.interface";
+import { INodeOperations } from "./interfaces/node-operations.interface";
+import { IElementOperations } from "./interfaces/element-operations.interface";
+import { IBatchOperations } from "./interfaces/batch-operations.interface";
+/**
+ * Main entry point for the Graph Knowledge Headless API.
+ *
+ * Provides programmatic access to Graph Knowledge documents, nodes, and elements
+ * without requiring the Angular UI.
+ *
+ * @example
+ * ```typescript
+ * import { GraphKnowledgeAPI } from '@graph-knowledge/api';
+ *
+ * const api = new GraphKnowledgeAPI({
+ *     firebaseConfig: {
+ *         apiKey: "...",
+ *         authDomain: "...",
+ *         projectId: "...",
+ *         storageBucket: "...",
+ *         messagingSenderId: "...",
+ *         appId: "..."
+ *     }
+ * });
+ *
+ * await api.signIn("user@example.com", "password");
+ *
+ * const doc = await api.documents.create({ title: "My Document" });
+ * const node = await api.nodes.create(doc.id, { title: "My Node" });
+ * await api.elements.create(doc.id, node.id, {
+ *     type: "rectangle",
+ *     x: 100,
+ *     y: 100,
+ *     width: 200,
+ *     height: 100,
+ *     fillColor: "#FF5733"
+ * });
+ * ```
+ */
+export declare class GraphKnowledgeAPI {
+    private readonly app;
+    private readonly auth;
+    private readonly db;
+    private readonly _authClient;
+    private readonly _documents;
+    private readonly _nodes;
+    private readonly _elements;
+    private readonly _batch;
+    /**
+     * Creates a new GraphKnowledgeAPI instance.
+     * @param config Configuration including Firebase credentials
+     */
+    constructor(config: ApiConfig);
+    /**
+     * Authentication client for sign-in/sign-out operations.
+     */
+    get authClient(): IAuthClient;
+    /**
+     * Document operations (create, get, list, update, delete, share).
+     */
+    get documents(): IDocumentOperations;
+    /**
+     * Node operations (create, get, list, update, delete).
+     */
+    get nodes(): INodeOperations;
+    /**
+     * Element operations (create, get, list, update, delete).
+     */
+    get elements(): IElementOperations;
+    /**
+     * Batch element operations (createElements, updateElements, deleteElements).
+     */
+    get batch(): IBatchOperations;
+    /**
+     * Signs in with email and password.
+     * @param email User email
+     * @param password User password
+     */
+    signIn(email: string, password: string): Promise<void>;
+    /**
+     * Signs out the current user.
+     */
+    signOut(): Promise<void>;
+    /**
+     * Gets the current user's ID, or null if not authenticated.
+     */
+    get currentUserId(): string | null;
+    /**
+     * Waits for Firebase Auth to initialize.
+     * Call this before checking auth state if the API was just created.
+     */
+    waitForAuthInit(): Promise<void>;
+    /**
+     * Checks if the current user has premium status.
+     * @returns Promise resolving to true if user is premium
+     */
+    isPremium(): Promise<boolean>;
+    /**
+     * Requires the current user to have premium status.
+     * @throws AuthenticationError if not authenticated
+     * @throws PermissionError if not premium
+     */
+    requirePremium(): Promise<void>;
+}

package/src/lib/graph-knowledge-api.js

@@ -0,0 +1,154 @@
+import { initializeApp } from "firebase/app";
+import { getAuth } from "firebase/auth";
+import { getFirestore } from "firebase/firestore";
+import { FirebaseAuthClient } from "./clients/firebase-auth-client";
+import { FirebaseFirestoreClient } from "./clients/firebase-firestore-client";
+import { DocumentOperations } from "./operations/document-operations";
+import { NodeOperations } from "./operations/node-operations";
+import { ElementOperations } from "./operations/element-operations";
+import { BatchOperations } from "./operations/batch-operations";
+import { DocumentValidator } from "./validators/document-validator";
+import { NodeValidator } from "./validators/node-validator";
+import { ElementValidatorRegistry } from "./validators/element-validator-registry";
+/**
+ * Main entry point for the Graph Knowledge Headless API.
+ *
+ * Provides programmatic access to Graph Knowledge documents, nodes, and elements
+ * without requiring the Angular UI.
+ *
+ * @example
+ * ```typescript
+ * import { GraphKnowledgeAPI } from '@graph-knowledge/api';
+ *
+ * const api = new GraphKnowledgeAPI({
+ *     firebaseConfig: {
+ *         apiKey: "...",
+ *         authDomain: "...",
+ *         projectId: "...",
+ *         storageBucket: "...",
+ *         messagingSenderId: "...",
+ *         appId: "..."
+ *     }
+ * });
+ *
+ * await api.signIn("user@example.com", "password");
+ *
+ * const doc = await api.documents.create({ title: "My Document" });
+ * const node = await api.nodes.create(doc.id, { title: "My Node" });
+ * await api.elements.create(doc.id, node.id, {
+ *     type: "rectangle",
+ *     x: 100,
+ *     y: 100,
+ *     width: 200,
+ *     height: 100,
+ *     fillColor: "#FF5733"
+ * });
+ * ```
+ */
+export class GraphKnowledgeAPI {
+    app;
+    auth;
+    db;
+    _authClient;
+    _documents;
+    _nodes;
+    _elements;
+    _batch;
+    /**
+     * Creates a new GraphKnowledgeAPI instance.
+     * @param config Configuration including Firebase credentials
+     */
+    constructor(config) {
+        // Initialize Firebase
+        this.app = initializeApp(config.firebaseConfig, config.appName ?? `graph-knowledge-api-${Date.now()}`);
+        this.auth = getAuth(this.app);
+        this.db = getFirestore(this.app);
+        // Create clients
+        const firestoreClient = new FirebaseFirestoreClient(this.db);
+        this._authClient = new FirebaseAuthClient(this.auth, this.db);
+        // Create validators
+        const documentValidator = new DocumentValidator();
+        const nodeValidator = new NodeValidator();
+        const elementValidatorRegistry = new ElementValidatorRegistry();
+        // Create operations (dependency injection)
+        this._documents = new DocumentOperations(firestoreClient, this._authClient, documentValidator);
+        this._nodes = new NodeOperations(firestoreClient, this._authClient, nodeValidator);
+        this._elements = new ElementOperations(firestoreClient, this._authClient, elementValidatorRegistry);
+        this._batch = new BatchOperations(firestoreClient, this._authClient, elementValidatorRegistry);
+    }
+    /**
+     * Authentication client for sign-in/sign-out operations.
+     */
+    get authClient() {
+        return this._authClient;
+    }
+    /**
+     * Document operations (create, get, list, update, delete, share).
+     */
+    get documents() {
+        return this._documents;
+    }
+    /**
+     * Node operations (create, get, list, update, delete).
+     */
+    get nodes() {
+        return this._nodes;
+    }
+    /**
+     * Element operations (create, get, list, update, delete).
+     */
+    get elements() {
+        return this._elements;
+    }
+    /**
+     * Batch element operations (createElements, updateElements, deleteElements).
+     */
+    get batch() {
+        return this._batch;
+    }
+    // =========================================================================
+    // Convenience methods delegating to authClient
+    // =========================================================================
+    /**
+     * Signs in with email and password.
+     * @param email User email
+     * @param password User password
+     */
+    async signIn(email, password) {
+        return this._authClient.signIn(email, password);
+    }
+    /**
+     * Signs out the current user.
+     */
+    async signOut() {
+        return this._authClient.signOut();
+    }
+    /**
+     * Gets the current user's ID, or null if not authenticated.
+     */
+    get currentUserId() {
+        return this._authClient.currentUserId;
+    }
+    /**
+     * Waits for Firebase Auth to initialize.
+     * Call this before checking auth state if the API was just created.
+     */
+    async waitForAuthInit() {
+        return this._authClient.waitForInit();
+    }
+    /**
+     * Checks if the current user has premium status.
+     * @returns Promise resolving to true if user is premium
+     */
+    async isPremium() {
+        return this._authClient.isPremium();
+    }
+    /**
+     * Requires the current user to have premium status.
+     * @throws AuthenticationError if not authenticated
+     * @throws PermissionError if not premium
+     */
+    async requirePremium() {
+        return this._authClient.requirePremium();
+    }
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Interface for authentication operations.
+ * Abstracts Firebase Auth for dependency inversion.
+ */
+export interface IAuthClient {
+    /**
+     * Signs in with email and password.
+     * @throws AuthenticationError if sign in fails
+     */
+    signIn(email: string, password: string): Promise<void>;
+    /**
+     * Signs out the current user.
+     */
+    signOut(): Promise<void>;
+    /**
+     * Gets the current user's ID, or null if not authenticated.
+     */
+    get currentUserId(): string | null;
+    /**
+     * Gets the current user's ID, throwing if not authenticated.
+     * @throws AuthenticationError if not authenticated
+     */
+    requireAuth(): string;
+    /**
+     * Checks if the current user has premium status.
+     * @returns Promise resolving to true if user is premium
+     */
+    isPremium(): Promise<boolean>;
+    /**
+     * Requires the current user to have premium status.
+     * @throws AuthenticationError if not authenticated
+     * @throws PermissionError if not premium
+     */
+    requirePremium(): Promise<void>;
+}

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

@@ -0,0 +1,46 @@
+import { GraphElement } from "@graph-knowledge/domain";
+import { AnyElementInput, UpdateElementInput } from "../types/element-input-types";
+/**
+ * Update input for batch element updates.
+ * Includes elementId to identify which element to update.
+ */
+export interface BatchUpdateElementInput extends UpdateElementInput {
+    elementId: string;
+}
+/**
+ * Interface for batch element operations.
+ * Enables efficient bulk operations for AI agents and automation.
+ */
+export interface IBatchOperations {
+    /**
+     * Creates multiple elements atomically.
+     * All elements are validated before any are created.
+     * @param documentId The parent document ID
+     * @param nodeId The parent node ID
+     * @param inputs Array of element creation parameters
+     * @returns Array of created elements
+     * @throws AuthenticationError if not authenticated
+     * @throws NotFoundError if node doesn't exist
+     * @throws ValidationError if any input is invalid (none created)
+     */
+    createElements(documentId: string, nodeId: string, inputs: AnyElementInput[]): Promise<GraphElement[]>;
+    /**
+     * Updates multiple elements atomically.
+     * @param documentId The parent document ID
+     * @param nodeId The parent node ID
+     * @param updates Array of element updates (with elementId)
+     * @throws AuthenticationError if not authenticated
+     * @throws NotFoundError if node or any element doesn't exist
+     */
+    updateElements(documentId: string, nodeId: string, updates: BatchUpdateElementInput[]): Promise<void>;
+    /**
+     * Deletes multiple elements atomically.
+     * Non-existent element IDs are silently skipped.
+     * @param documentId The parent document ID
+     * @param nodeId The parent node ID
+     * @param elementIds Array of element IDs to delete
+     * @throws AuthenticationError if not authenticated
+     * @throws NotFoundError if node doesn't exist
+     */
+    deleteElements(documentId: string, nodeId: string, elementIds: string[]): Promise<void>;
+}

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

@@ -0,0 +1,51 @@
+import { CreateDocumentInput, UpdateDocumentInput, DocumentResult } from "../types/api-types";
+/**
+ * Interface for document CRUD operations.
+ */
+export interface IDocumentOperations {
+    /**
+     * Creates a new document with a root node.
+     * @param input Document creation parameters
+     * @returns The created document with its ID
+     * @throws AuthenticationError if not authenticated
+     * @throws ValidationError if input is invalid
+     */
+    create(input: CreateDocumentInput): Promise<DocumentResult>;
+    /**
+     * Gets a document by ID, including all its nodes.
+     * @param documentId The document ID
+     * @returns The document with all nodes
+     * @throws AuthenticationError if not authenticated
+     * @throws NotFoundError if document doesn't exist
+     */
+    get(documentId: string): Promise<DocumentResult>;
+    /**
+     * Lists all documents owned by the current user.
+     * @returns Array of documents (shallow, without nodes)
+     * @throws AuthenticationError if not authenticated
+     */
+    list(): Promise<DocumentResult[]>;
+    /**
+     * Updates a document's metadata.
+     * @param documentId The document ID
+     * @param input Fields to update
+     * @throws AuthenticationError if not authenticated
+     * @throws NotFoundError if document doesn't exist
+     * @throws ValidationError if input is invalid
+     */
+    update(documentId: string, input: UpdateDocumentInput): Promise<void>;
+    /**
+     * Deletes a document.
+     * @param documentId The document ID
+     * @throws AuthenticationError if not authenticated
+     */
+    delete(documentId: string): Promise<void>;
+    /**
+     * Shares a document with other users.
+     * @param documentId The document ID
+     * @param userIds Array of user IDs to share with
+     * @throws AuthenticationError if not authenticated
+     * @throws NotFoundError if document doesn't exist
+     */
+    share(documentId: string, userIds: string[]): Promise<void>;
+}

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

@@ -0,0 +1,57 @@
+import { GraphElement } from "@graph-knowledge/domain";
+import { AnyElementInput, UpdateElementInput } from "../types/element-input-types";
+/**
+ * Interface for element CRUD operations.
+ */
+export interface IElementOperations {
+    /**
+     * Creates a new element within a node.
+     * @param documentId The parent document ID
+     * @param nodeId The parent node ID
+     * @param input Element creation parameters (type-specific)
+     * @returns The created element
+     * @throws AuthenticationError if not authenticated
+     * @throws NotFoundError if node doesn't exist
+     * @throws ValidationError if input is invalid
+     */
+    create(documentId: string, nodeId: string, input: AnyElementInput): Promise<GraphElement>;
+    /**
+     * Gets an element by ID.
+     * @param documentId The parent document ID
+     * @param nodeId The parent node ID
+     * @param elementId The element ID
+     * @returns The element
+     * @throws AuthenticationError if not authenticated
+     * @throws NotFoundError if node or element doesn't exist
+     */
+    get(documentId: string, nodeId: string, elementId: string): Promise<GraphElement>;
+    /**
+     * Lists all elements in a node.
+     * @param documentId The parent document ID
+     * @param nodeId The parent node ID
+     * @returns Array of elements
+     * @throws AuthenticationError if not authenticated
+     * @throws NotFoundError if node doesn't exist
+     */
+    list(documentId: string, nodeId: string): Promise<GraphElement[]>;
+    /**
+     * Updates an element's properties.
+     * @param documentId The parent document ID
+     * @param nodeId The parent node ID
+     * @param elementId The element ID
+     * @param input Fields to update
+     * @throws AuthenticationError if not authenticated
+     * @throws NotFoundError if element doesn't exist
+     * @throws ValidationError if input is invalid
+     */
+    update(documentId: string, nodeId: string, elementId: string, input: UpdateElementInput): Promise<void>;
+    /**
+     * Deletes an element.
+     * @param documentId The parent document ID
+     * @param nodeId The parent node ID
+     * @param elementId The element ID
+     * @throws AuthenticationError if not authenticated
+     * @throws NotFoundError if element doesn't exist
+     */
+    delete(documentId: string, nodeId: string, elementId: string): Promise<void>;
+}

package/src/lib/interfaces/element-validator.interface.d.ts

@@ -0,0 +1,42 @@
+import { AnyElementInput } from "../types/element-input-types";
+/**
+ * Interface for element type validators.
+ * Each element type (rectangle, text, etc.) has its own validator.
+ * Implements the Strategy pattern for extensibility.
+ */
+export interface IElementTypeValidator {
+    /**
+     * The element type this validator handles (e.g., "rectangle", "text").
+     */
+    readonly elementType: string;
+    /**
+     * Validates element input.
+     * @param input The element input to validate
+     * @throws ValidationError if input is invalid
+     */
+    validate(input: AnyElementInput): void;
+}
+/**
+ * Interface for the element validator registry.
+ * Implements Open/Closed principle - new validators can be registered
+ * without modifying existing code.
+ */
+export interface IElementValidatorRegistry {
+    /**
+     * Registers a validator for an element type.
+     * @param validator The validator to register
+     */
+    register(validator: IElementTypeValidator): void;
+    /**
+     * Gets the validator for an element type.
+     * @param elementType The element type
+     * @returns The validator or undefined if not found
+     */
+    getValidator(elementType: string): IElementTypeValidator | undefined;
+    /**
+     * Validates an element input using the appropriate validator.
+     * @param input The element input to validate
+     * @throws ValidationError if input is invalid or no validator found
+     */
+    validate(input: AnyElementInput): void;
+}