@flowtasks/sdk 0.2.0

package/README.md

@@ -0,0 +1,107 @@
+# Flow SDK for JavaScript / TypeScript
+
+Official client for the [Flow Intelligence Engine](https://flowtasks.io) API.
+
+## Installation
+
+```bash
+npm install @flowtasks/sdk
+```
+
+## Quick Start
+
+```typescript
+import { FlowClient } from "@flowtasks/sdk";
+
+const client = new FlowClient({
+  baseUrl: "https://flowtasks.io",
+  apiKey: "YOUR_API_KEY",
+  organizationId: "YOUR_ORG_ID",
+});
+
+// Chat with your documents
+const answer = await client.chat("What are the termination conditions?");
+console.log(answer);
+
+// Search the knowledge graph
+const results = await client.searchGraph("termination clause");
+console.log(results);
+
+// Ask the knowledge graph (LLM-powered)
+const response = await client.askGraph("Which contracts allow termination without cause?");
+console.log(response.answer);
+
+// Legal analysis
+const clauses = await client.legalQuery("indemnity clauses", { mode: "deterministic" });
+console.log(clauses);
+```
+
+## Available Methods
+
+### Documents
+- `listDocuments()` -- List all documents
+- `getDocument(id)` -- Get document metadata
+- `deleteDocument(id)` -- Delete a document
+
+### Chat / RAG
+- `chat(message, options?)` -- AI-powered query with source citations
+
+### Knowledge Graph
+- `searchGraph(query)` -- Search entities and relationships
+- `getGraphStats()` -- Node and edge counts
+- `askGraph(question)` -- Natural-language graph query (LLM)
+- `reasonGraph(question, options?)` -- Intent-aware reasoning
+- `getGraphVisualization(limit?)` -- Full graph data for rendering
+- `getEntityNeighbors(name, depth?)` -- Explore entity connections
+
+### Legal Analysis
+- `legalClauseTypes()` -- Available clause types
+- `legalClauses(docId)` -- Extract clauses from a document
+- `legalDiff(docA, docB)` -- Compare clauses between documents
+- `legalQuery(query, options?)` -- Query across all clauses
+
+### Ontology
+- `listDomains()` -- Built-in domain ontologies
+- `createOntology(params)` -- Create custom ontology
+- `listCustomOntologies()` -- List custom ontologies
+- `getResolvedOntology(domain)` -- Merged core + custom ontology
+
+### Agent
+- `agentRun(params?)` -- Trigger an agent run
+- `listAgentRuns()` -- Past agent runs
+- `listRiskSignals()` -- Detected risk signals
+
+### Workflows
+- `listWorkflows()` / `createWorkflow(params)` / `runWorkflow(id)`
+
+### Compliance
+- `listComplianceChecks()` / `runComplianceScan(params?)`
+
+### Webhooks
+- `listWebhooks()` / `createWebhook(params)`
+
+### Usage
+- `getUsage()` -- Current usage and quota
+
+## Error Handling
+
+```typescript
+import { FlowClient, FlowAPIError } from "@flowtasks/sdk";
+
+try {
+  const result = await client.chat("Summarize the agreement");
+} catch (err) {
+  if (err instanceof FlowAPIError) {
+    console.error(`API error ${err.statusCode}: ${err.detail}`);
+  }
+}
+```
+
+## Links
+
+- [Interactive API Docs](https://flowtasks.io/docs)
+- [OpenAPI Schema](https://flowtasks.io/openapi.json)
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Flow SDK — JavaScript/TypeScript client for the Flowtasks Intelligence Engine API.
+ *
+ * @example
+ * ```ts
+ * import { FlowClient } from "@flowtasks/sdk";
+ *
+ * const client = new FlowClient({
+ *   baseUrl: "https://api.flowtasks.io",
+ *   apiKey: "your-api-key",
+ *   organizationId: "org-123",
+ * });
+ *
+ * const answer = await client.chat("What are the key contract terms?");
+ * const clauses = await client.legalQuery("termination clauses", { mode: "deterministic" });
+ * ```
+ */
+export interface FlowClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    organizationId?: string;
+    timeout?: number;
+}
+export declare class FlowAPIError extends Error {
+    statusCode: number;
+    detail: string;
+    constructor(statusCode: number, detail: string);
+}
+export declare class FlowClient {
+    private baseUrl;
+    private apiKey;
+    private organizationId?;
+    private timeout;
+    constructor(config: FlowClientConfig);
+    private request;
+    health(): Promise<any>;
+    listDocuments(params?: {
+        skip?: number;
+        limit?: number;
+        organizationId?: string;
+    }): Promise<any>;
+    getDocument(documentId: string): Promise<any>;
+    deleteDocument(documentId: string): Promise<void>;
+    chat(message: string, options?: {
+        sessionId?: string;
+        organizationId?: string;
+        useMultiAgent?: boolean;
+    }): Promise<any>;
+    searchGraph(query: string, organizationId?: string): Promise<any>;
+    getGraphStats(organizationId?: string): Promise<any>;
+    askGraph(question: string): Promise<any>;
+    reasonGraph(question: string, options?: {
+        category?: string;
+    }): Promise<any>;
+    getGraphVisualization(limit?: number): Promise<any>;
+    getEntityNeighbors(entityName: string, depth?: number): Promise<any>;
+    agentRun(params?: {
+        query?: string;
+        triggerType?: string;
+        context?: Record<string, any>;
+    }): Promise<any>;
+    listAgentRuns(skip?: number, limit?: number): Promise<any>;
+    listRiskSignals(skip?: number, limit?: number): Promise<any>;
+    listDomains(): Promise<any>;
+    getDomain(domain: string): Promise<any>;
+    createOntology(params: {
+        name: string;
+        description?: string;
+        entityTypes?: string[];
+        relationshipTypes?: string[];
+        relationRules?: Array<{
+            relationship_type: string;
+            allowed_source_types: string[];
+            allowed_target_types: string[];
+            symmetric?: boolean;
+        }>;
+    }): Promise<any>;
+    listCustomOntologies(): Promise<any>;
+    getCustomOntology(ontologyId: string): Promise<any>;
+    updateOntology(ontologyId: string, fields: Record<string, any>): Promise<any>;
+    deleteOntology(ontologyId: string): Promise<void>;
+    getResolvedOntology(domain: string): Promise<any>;
+    legalClauseTypes(): Promise<any>;
+    legalClauses(documentId: string): Promise<any>;
+    legalDiff(docA: string, docB: string): Promise<any>;
+    legalQuery(query: string, options?: {
+        mode?: "auto" | "deterministic" | "hybrid";
+        clauseTypes?: string[];
+        conditionFilters?: Record<string, string>;
+        hasObligations?: boolean;
+    }): Promise<any>;
+    listWorkflows(): Promise<any>;
+    createWorkflow(params: {
+        name: string;
+        description?: string;
+        steps: Array<Record<string, any>>;
+        isActive?: boolean;
+    }): Promise<any>;
+    runWorkflow(workflowId: string, inputData?: Record<string, any>): Promise<any>;
+    listComplianceChecks(): Promise<any>;
+    runComplianceScan(params?: {
+        documentId?: string;
+        framework?: string;
+    }): Promise<any>;
+    listWebhooks(): Promise<any>;
+    createWebhook(params: {
+        url: string;
+        events: string[];
+        name?: string;
+    }): Promise<any>;
+    getUsage(organizationId?: string): Promise<any>;
+}

package/dist/client.js

@@ -0,0 +1,263 @@
+"use strict";
+/**
+ * Flow SDK — JavaScript/TypeScript client for the Flowtasks Intelligence Engine API.
+ *
+ * @example
+ * ```ts
+ * import { FlowClient } from "@flowtasks/sdk";
+ *
+ * const client = new FlowClient({
+ *   baseUrl: "https://api.flowtasks.io",
+ *   apiKey: "your-api-key",
+ *   organizationId: "org-123",
+ * });
+ *
+ * const answer = await client.chat("What are the key contract terms?");
+ * const clauses = await client.legalQuery("termination clauses", { mode: "deterministic" });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowClient = exports.FlowAPIError = void 0;
+class FlowAPIError extends Error {
+    constructor(statusCode, detail) {
+        super(`HTTP ${statusCode}: ${detail}`);
+        this.statusCode = statusCode;
+        this.detail = detail;
+        this.name = "FlowAPIError";
+    }
+}
+exports.FlowAPIError = FlowAPIError;
+class FlowClient {
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, "") + "/api/v1";
+        this.apiKey = config.apiKey;
+        this.organizationId = config.organizationId;
+        this.timeout = config.timeout ?? 60000;
+    }
+    async request(method, path, options) {
+        let url = `${this.baseUrl}${path}`;
+        if (options?.params) {
+            const qs = new URLSearchParams();
+            for (const [k, v] of Object.entries(options.params)) {
+                if (v !== undefined && v !== null)
+                    qs.set(k, String(v));
+            }
+            const qsStr = qs.toString();
+            if (qsStr)
+                url += `?${qsStr}`;
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        const headers = {
+            "X-API-Key": this.apiKey,
+            "Content-Type": "application/json",
+        };
+        if (this.organizationId) {
+            headers["X-Organization-ID"] = this.organizationId;
+        }
+        try {
+            const resp = await fetch(url, {
+                method,
+                headers,
+                body: options?.body ? JSON.stringify(options.body) : undefined,
+                signal: controller.signal,
+            });
+            if (!resp.ok) {
+                let detail;
+                try {
+                    const json = await resp.json();
+                    detail = json.detail ?? resp.statusText;
+                }
+                catch {
+                    detail = resp.statusText;
+                }
+                throw new FlowAPIError(resp.status, detail);
+            }
+            if (resp.status === 204)
+                return undefined;
+            return (await resp.json());
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    // ── Health ──────────────────────────────────────────────────────────
+    async health() {
+        return this.request("GET", "/health");
+    }
+    // ── Documents ──────────────────────────────────────────────────────
+    async listDocuments(params) {
+        return this.request("GET", "/documents", {
+            params: {
+                skip: params?.skip ?? 0,
+                limit: params?.limit ?? 50,
+                ...(params?.organizationId && { organization_id: params.organizationId }),
+            },
+        });
+    }
+    async getDocument(documentId) {
+        return this.request("GET", `/documents/${documentId}`);
+    }
+    async deleteDocument(documentId) {
+        await this.request("DELETE", `/documents/${documentId}`);
+    }
+    // ── Chat / RAG ─────────────────────────────────────────────────────
+    async chat(message, options) {
+        return this.request("POST", "/chat", {
+            body: {
+                message,
+                ...(options?.sessionId && { session_id: options.sessionId }),
+                ...(options?.organizationId && { organization_id: options.organizationId }),
+                ...(options?.useMultiAgent && { use_multi_agent: true }),
+            },
+        });
+    }
+    // ── Knowledge Graph ────────────────────────────────────────────────
+    async searchGraph(query, organizationId) {
+        return this.request("GET", "/knowledge-graph/search", {
+            params: { q: query, ...(organizationId && { organization_id: organizationId }) },
+        });
+    }
+    async getGraphStats(organizationId) {
+        return this.request("GET", "/knowledge-graph/stats", {
+            params: organizationId ? { organization_id: organizationId } : {},
+        });
+    }
+    async askGraph(question) {
+        return this.request("POST", "/knowledge-graph/ask", {
+            body: { question },
+        });
+    }
+    async reasonGraph(question, options) {
+        return this.request("POST", "/knowledge-graph/reason", {
+            body: { question, ...(options?.category && { category: options.category }) },
+        });
+    }
+    async getGraphVisualization(limit = 500) {
+        return this.request("GET", "/knowledge-graph/visualization", {
+            params: { limit },
+        });
+    }
+    async getEntityNeighbors(entityName, depth = 1) {
+        return this.request("GET", `/knowledge-graph/neighbors/${encodeURIComponent(entityName)}`, {
+            params: { depth },
+        });
+    }
+    // ── Agent ──────────────────────────────────────────────────────────
+    async agentRun(params) {
+        return this.request("POST", "/agent/run", {
+            body: {
+                trigger_type: params?.triggerType ?? "manual",
+                ...(params?.query && { query: params.query }),
+                ...(params?.context && { context: params.context }),
+            },
+        });
+    }
+    async listAgentRuns(skip = 0, limit = 50) {
+        return this.request("GET", "/agent/runs", { params: { skip, limit } });
+    }
+    async listRiskSignals(skip = 0, limit = 50) {
+        return this.request("GET", "/agent/risk-signals", { params: { skip, limit } });
+    }
+    // ── Ontology ───────────────────────────────────────────────────────
+    async listDomains() {
+        return this.request("GET", "/ontology/domains");
+    }
+    async getDomain(domain) {
+        return this.request("GET", `/ontology/domains/${domain}`);
+    }
+    async createOntology(params) {
+        return this.request("POST", "/ontology/custom", {
+            body: {
+                name: params.name,
+                description: params.description ?? "",
+                entity_types: (params.entityTypes ?? []).map((name) => ({ name })),
+                relationship_types: params.relationshipTypes ?? [],
+                relation_rules: params.relationRules ?? [],
+            },
+        });
+    }
+    async listCustomOntologies() {
+        return this.request("GET", "/ontology/custom");
+    }
+    async getCustomOntology(ontologyId) {
+        return this.request("GET", `/ontology/custom/${ontologyId}`);
+    }
+    async updateOntology(ontologyId, fields) {
+        return this.request("PUT", `/ontology/custom/${ontologyId}`, { body: fields });
+    }
+    async deleteOntology(ontologyId) {
+        await this.request("DELETE", `/ontology/custom/${ontologyId}`);
+    }
+    async getResolvedOntology(domain) {
+        return this.request("GET", `/ontology/resolved/${domain}`);
+    }
+    // ── Legal Analysis ─────────────────────────────────────────────────
+    async legalClauseTypes() {
+        return this.request("GET", "/legal/clause-types");
+    }
+    async legalClauses(documentId) {
+        return this.request("GET", `/legal/clauses/${documentId}`);
+    }
+    async legalDiff(docA, docB) {
+        return this.request("GET", "/legal/diff", { params: { doc_a: docA, doc_b: docB } });
+    }
+    async legalQuery(query, options) {
+        return this.request("POST", "/legal/query", {
+            body: {
+                query,
+                mode: options?.mode ?? "auto",
+                ...(options?.clauseTypes && { clause_types: options.clauseTypes }),
+                ...(options?.conditionFilters && { condition_filters: options.conditionFilters }),
+                ...(options?.hasObligations !== undefined && { has_obligations: options.hasObligations }),
+            },
+        });
+    }
+    // ── Workflows ──────────────────────────────────────────────────────
+    async listWorkflows() {
+        return this.request("GET", "/workflows");
+    }
+    async createWorkflow(params) {
+        return this.request("POST", "/workflows", {
+            body: {
+                name: params.name,
+                description: params.description ?? "",
+                steps_json: params.steps,
+                is_active: params.isActive ?? true,
+            },
+        });
+    }
+    async runWorkflow(workflowId, inputData) {
+        return this.request("POST", `/workflows/${workflowId}/run`, {
+            body: inputData ? { input_data: inputData } : {},
+        });
+    }
+    // ── Compliance ─────────────────────────────────────────────────────
+    async listComplianceChecks() {
+        return this.request("GET", "/compliance/checks");
+    }
+    async runComplianceScan(params) {
+        return this.request("POST", "/compliance/scan", {
+            body: {
+                framework: params?.framework ?? "general",
+                ...(params?.documentId && { document_id: params.documentId }),
+            },
+        });
+    }
+    // ── Webhooks ───────────────────────────────────────────────────────
+    async listWebhooks() {
+        return this.request("GET", "/webhooks");
+    }
+    async createWebhook(params) {
+        return this.request("POST", "/webhooks", {
+            body: { url: params.url, events: params.events, name: params.name ?? "" },
+        });
+    }
+    // ── Usage ──────────────────────────────────────────────────────────
+    async getUsage(organizationId) {
+        return this.request("GET", "/usage", {
+            params: organizationId ? { organization_id: organizationId } : {},
+        });
+    }
+}
+exports.FlowClient = FlowClient;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { FlowClient, FlowClientConfig } from "./client";
+export { FlowAPIError } from "./client";

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowAPIError = exports.FlowClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "FlowClient", { enumerable: true, get: function () { return client_1.FlowClient; } });
+var client_2 = require("./client");
+Object.defineProperty(exports, "FlowAPIError", { enumerable: true, get: function () { return client_2.FlowAPIError; } });

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@flowtasks/sdk",
+  "version": "0.2.0",
+  "description": "JavaScript/TypeScript SDK for the Flowtasks Intelligence Engine API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "author": "Flow Tasks <dev@flowtasks.io>",
+  "license": "MIT",
+  "homepage": "https://flowtasks.io",
+  "keywords": ["rag", "ai", "knowledge-graph", "legal", "compliance", "api", "flowtasks"]
+}