@alephantai/n8n-nodes-alephant-analytics-ai 0.1.0

package/README.md

@@ -0,0 +1,82 @@
+# @alephantai/n8n-nodes-alephant-analytics-ai
+
+n8n community node package for using Alephant analytics as an AI Agent tool.
+
+This package adds the **Alephant-Analytics-AI** node to n8n. It reuses the Alephant analytics operations for usage summaries, budget status, costs, recent requests, and request log lookups, but exposes them as an AI tool connection for agent workflows.
+
+## Installation
+
+Install this package from n8n Community Nodes:
+
+1. Open n8n.
+2. Go to **Settings**.
+3. Open **Community Nodes**.
+4. Choose **Install**.
+5. Enter `@alephantai/n8n-nodes-alephant-analytics-ai`.
+6. Confirm the installation.
+
+For self-hosted n8n, restart the instance if your deployment requires it after installing community nodes.
+
+## Authentication
+
+The node uses **Alephant Virtual Key** credentials.
+
+Create or copy a Virtual Key from Alephant, then add a credential in n8n with:
+
+- Virtual Key
+- Optional SaaS Base URL
+- Optional Analytics Base URL
+- Optional Workspace ID
+
+The default production URLs are:
+
+- SaaS Base URL: `https://alephant.io`
+- Analytics Base URL: `https://analytics.alephant.io`
+
+The Alephant quickstart explains the same Virtual Key concept:
+
+https://developers.alephant.io/docs/overview/getting-started/quickstart-guide
+
+## AI Agent Usage
+
+Add **Alephant-Analytics-AI** to an n8n AI Agent workflow and connect it to the agent tool input.
+
+The node exposes `operation` and `period` options with a `filled by AI` choice so the agent can select the analytics operation and time window from the user prompt.
+
+Recommended default agent prompts include clear analytics intent, such as:
+
+- "Summarize AI usage for the last 7 days."
+- "Check whether the workspace is close to budget."
+- "Show recent AI gateway requests."
+- "Find details for this request log ID."
+
+## Operations
+
+The AI tool can run the same analytics operations as the standard Alephant analytics node:
+
+- Scope
+- Budget Status
+- Usage Summary
+- Daily Costs
+- Cost by Model
+- Recent Requests
+- Request Log Detail
+
+## Request Log Detail
+
+For request log lookups, provide a request log ID in the workflow item or let the AI Agent fill the parameter.
+
+The node resolves Workspace ID from:
+
+- Node parameter
+- Incoming item JSON
+- Credential Workspace ID
+- Alephant Scope response
+
+## Package Notes
+
+This package is intentionally separate from `@alephantai/n8n-nodes-alephant-analytics`.
+
+Use the standard analytics package for regular n8n workflow nodes.
+
+Use this package when you need the analytics capability as an AI Agent tool.

package/dist/credentials/AlephantVirtualKeyApi.credentials.d.ts

@@ -0,0 +1,8 @@
+import type { ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class AlephantVirtualKeyApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    test: ICredentialTestRequest;
+    properties: INodeProperties[];
+}

package/dist/credentials/AlephantVirtualKeyApi.credentials.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlephantVirtualKeyApi = void 0;
+const constants_1 = require("../shared/constants");
+class AlephantVirtualKeyApi {
+    constructor() {
+        this.name = 'alephantVirtualKeyApi';
+        this.displayName = 'Alephant Virtual Key';
+        this.documentationUrl = 'https://developers.alephant.io/n8n';
+        this.test = {
+            request: {
+                baseURL: '={{$credentials.gatewayBaseUrl}}',
+                url: '/models',
+                headers: {
+                    Authorization: '=Bearer {{$credentials.virtualKey}}',
+                },
+            },
+        };
+        this.properties = [
+            {
+                displayName: 'Virtual Key',
+                name: 'virtualKey',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                required: true,
+                description: 'Alephant Virtual Key used for AI Gateway and VK-scoped usage APIs',
+            },
+            {
+                displayName: 'Workspace ID',
+                name: 'workspaceId',
+                type: 'string',
+                default: '',
+                required: false,
+                description: 'Required for request-log detail lookups with Virtual Key credentials.',
+            },
+            {
+                displayName: 'Gateway Base URL',
+                name: 'gatewayBaseUrl',
+                type: 'string',
+                default: constants_1.DEFAULT_GATEWAY_BASE_URL,
+                required: false,
+                description: 'Optional. Override for staging, local, or self-hosted Gateway testing.',
+            },
+            {
+                displayName: 'SaaS Base URL',
+                name: 'saasBaseUrl',
+                type: 'string',
+                default: constants_1.DEFAULT_SAAS_BASE_URL,
+                required: false,
+                description: 'Optional. Override for staging, local, or self-hosted SaaS API testing.',
+            },
+            {
+                displayName: 'Analytics Base URL',
+                name: 'analyticsBaseUrl',
+                type: 'string',
+                default: constants_1.DEFAULT_ANALYTICS_BASE_URL,
+                required: false,
+                description: 'Optional. Override for staging, local, or self-hosted analytics API testing.',
+            },
+        ];
+    }
+}
+exports.AlephantVirtualKeyApi = AlephantVirtualKeyApi;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/nodes/AlephantAnalyticsAi/AlephantAnalyticsAi.node.d.ts

@@ -0,0 +1,5 @@
+import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
+export declare class AlephantAnalyticsAi implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}

package/dist/nodes/AlephantAnalyticsAi/AlephantAnalyticsAi.node.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlephantAnalyticsAi = void 0;
+const n8n_workflow_1 = require("n8n-workflow");
+const usage_1 = require("../../shared/usage");
+class AlephantAnalyticsAi {
+    constructor() {
+        this.description = {
+            displayName: 'Alephant-Analytics-AI',
+            name: 'alephantAnalyticsAi',
+            icon: {
+                light: 'file:alephant.light.svg',
+                dark: 'file:alephant.dark.svg',
+            },
+            group: ['transform'],
+            version: 1,
+            subtitle: '={{$parameter["operation"]}}',
+            description: 'Alephant AI Analytics provides visibility into AI usage, cost, latency, model/provider performance, agent sessions, and request-level traces across your organization.',
+            defaults: { name: 'Alephant-Analytics-AI' },
+            usableAsTool: true,
+            inputs: [],
+            outputs: [n8n_workflow_1.NodeConnectionTypes.AiTool],
+            credentials: [{ name: 'alephantVirtualKeyApi', required: true }],
+            properties: [
+                {
+                    displayName: 'Operation',
+                    name: 'operation',
+                    type: 'options',
+                    default: 'usageSummary',
+                    description: 'Choose which Alephant analytics operation to run. In AI tool mode, let the model select this from the user prompt.',
+                    options: [
+                        { name: 'filled by AI', value: 'usageSummary' },
+                        { name: 'Budget Status', value: 'budgetStatus' },
+                        { name: 'Cost by Model', value: 'costByModel' },
+                        { name: 'Daily Costs', value: 'dailyCosts' },
+                        { name: 'Recent Requests', value: 'recentRequests' },
+                        { name: 'Request Log Detail', value: 'requestLogDetail' },
+                        { name: 'Scope', value: 'scope' },
+                        { name: 'Usage Summary', value: 'usageSummary' },
+                    ],
+                },
+                {
+                    displayName: 'Period',
+                    name: 'period',
+                    type: 'options',
+                    default: '7d',
+                    options: [
+                        { name: 'filled by AI', value: '7d' },
+                        { name: '24 Hours', value: '24h' },
+                        { name: '7 Days', value: '7d' },
+                        { name: '30 Days', value: '30d' },
+                        { name: '90 Days', value: '90d' },
+                    ],
+                    displayOptions: {
+                        show: {
+                            operation: ['budgetStatus', 'usageSummary', 'dailyCosts', 'costByModel'],
+                        },
+                    },
+                },
+                {
+                    displayName: 'Limit',
+                    name: 'limit',
+                    type: 'number',
+                    default: 50,
+                    typeOptions: { minValue: 1 },
+                    displayOptions: { show: { operation: ['recentRequests'] } },
+                },
+                {
+                    displayName: 'Offset',
+                    name: 'offset',
+                    type: 'number',
+                    default: 0,
+                    typeOptions: { minValue: 0 },
+                    displayOptions: { show: { operation: ['recentRequests'] } },
+                },
+                {
+                    displayName: 'Request Log ID',
+                    name: 'requestLogId',
+                    type: 'string',
+                    default: '={{$json.requestLogId || $json.requestId || ""}}',
+                    required: true,
+                    displayOptions: { show: { operation: ['requestLogDetail'] } },
+                },
+                {
+                    displayName: 'Workspace ID',
+                    name: 'workspaceId',
+                    type: 'string',
+                    default: '={{$json.workspaceId || $json.workspace_id || $json.xWorkspaceId || ""}}',
+                    description: 'Workspace ID for analytics request log lookups. Overrides the Workspace ID in credentials when set.',
+                    displayOptions: { show: { operation: ['requestLogDetail'] } },
+                },
+                {
+                    displayName: 'Request Log Max Attempts',
+                    name: 'requestLogMaxAttempts',
+                    type: 'number',
+                    default: 6,
+                    typeOptions: { minValue: 1 },
+                    description: 'Maximum number of consecutive request log lookup attempts',
+                    displayOptions: { show: { operation: ['requestLogDetail'] } },
+                },
+            ],
+        };
+    }
+    async execute() {
+        return usage_1.executeUsageNode.call(this);
+    }
+}
+exports.AlephantAnalyticsAi = AlephantAnalyticsAi;

package/dist/nodes/AlephantAnalyticsAi/alephant.dark.svg

@@ -0,0 +1,3 @@
+<svg width="193" height="151" viewBox="0 0 193 151" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M34.0762 116.501H67.8613V150.868H124.364V116.501H158.149V150.868H192.226C192.226 150.868 192.226 126.225 192.226 110.21C192.226 101.942 192.304 79.6343 189.078 59.71C184.127 29.1287 162.518 9.71512 131.762 3.32031C125.879 2.09709 113.938 0.582581 106.831 0.174805L103.103 0L75.1426 55.6875H64.6572L92.6172 0C92.5562 0.00105286 85.7861 0.118271 82.1328 0.408203C52.3673 2.50519 31.1642 10.7184 17.126 25.5137C8.62149 34.5424 3.61155 45.2025 1.16504 59.6484C0.0602955 65.8117 0.000214214 108.598 0 108.753V150.868H34.0762V116.501ZM158.522 78.4717C155.076 78.4714 152.282 75.6772 152.282 72.2305C152.282 68.7838 155.076 65.9895 158.522 65.9893C161.969 65.9893 164.764 68.7837 164.764 72.2305C164.764 75.6773 161.969 78.4717 158.522 78.4717Z" fill="white"/>
+</svg>

package/dist/nodes/AlephantAnalyticsAi/alephant.light.svg

@@ -0,0 +1,3 @@
+<svg width="193" height="151" viewBox="0 0 193 151" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M34.0762 116.501H67.8613V150.868H124.364V116.501H158.149V150.868H192.226C192.226 150.868 192.226 126.225 192.226 110.21C192.226 101.942 192.304 79.6343 189.078 59.71C184.127 29.1287 162.518 9.71512 131.762 3.32031C125.879 2.09709 113.938 0.582581 106.831 0.174805L103.103 0L75.1426 55.6875H64.6572L92.6172 0C92.5562 0.00105286 85.7861 0.118271 82.1328 0.408203C52.3673 2.50519 31.1642 10.7184 17.126 25.5137C8.62149 34.5424 3.61155 45.2025 1.16504 59.6484C0.0602955 65.8117 0.000214214 108.598 0 108.753V150.868H34.0762V116.501ZM158.522 78.4717C155.076 78.4714 152.282 75.6772 152.282 72.2305C152.282 68.7838 155.076 65.9895 158.522 65.9893C161.969 65.9893 164.764 68.7837 164.764 72.2305C164.764 75.6773 161.969 78.4717 158.522 78.4717Z" fill="#202020"/>
+</svg>

package/dist/nodes/AlephantAnalyticsAi/alephant.svg

@@ -0,0 +1,3 @@
+<svg width="193" height="151" viewBox="0 0 193 151" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M34.0762 116.501H67.8613V150.868H124.364V116.501H158.149V150.868H192.226C192.226 150.868 192.226 126.225 192.226 110.21C192.226 101.942 192.304 79.6343 189.078 59.71C184.127 29.1287 162.518 9.71512 131.762 3.32031C125.879 2.09709 113.938 0.582581 106.831 0.174805L103.103 0L75.1426 55.6875H64.6572L92.6172 0C92.5562 0.00105286 85.7861 0.118271 82.1328 0.408203C52.3673 2.50519 31.1642 10.7184 17.126 25.5137C8.62149 34.5424 3.61155 45.2025 1.16504 59.6484C0.0602955 65.8117 0.000214214 108.598 0 108.753V150.868H34.0762V116.501ZM158.522 78.4717C155.076 78.4714 152.282 75.6772 152.282 72.2305C152.282 68.7838 155.076 65.9895 158.522 65.9893C161.969 65.9893 164.764 68.7837 164.764 72.2305C164.764 75.6773 161.969 78.4717 158.522 78.4717Z" fill="#202020"/>
+</svg>

package/dist/shared/constants.d.ts

@@ -0,0 +1,19 @@
+export declare const DEFAULT_GATEWAY_BASE_URL = "https://ai.alephant.io/v1";
+export declare const DEFAULT_SAAS_BASE_URL = "https://alephant.io";
+export declare const DEFAULT_ANALYTICS_BASE_URL = "https://analytics.alephant.io";
+export declare const ENDPOINTS: {
+    chatCompletions: string;
+    cockpitScope: string;
+    cockpitBudgetStatus: string;
+    cockpitUsageSummary: string;
+    cockpitDailyCosts: string;
+    cockpitCostByModel: string;
+    cockpitRecentRequests: string;
+    analyticsRequestLogs: string;
+    agents: string;
+    virtualKeys: string;
+    models: string;
+    analyticsOverview: string;
+    analyticsUsage: string;
+    analyticsModels: string;
+};

package/dist/shared/constants.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENDPOINTS = exports.DEFAULT_ANALYTICS_BASE_URL = exports.DEFAULT_SAAS_BASE_URL = exports.DEFAULT_GATEWAY_BASE_URL = void 0;
+exports.DEFAULT_GATEWAY_BASE_URL = 'https://ai.alephant.io/v1';
+exports.DEFAULT_SAAS_BASE_URL = 'https://alephant.io';
+exports.DEFAULT_ANALYTICS_BASE_URL = 'https://analytics.alephant.io';
+exports.ENDPOINTS = {
+    chatCompletions: '/chat/completions',
+    cockpitScope: '/api/v1/cockpit/scope',
+    cockpitBudgetStatus: '/api/v1/cockpit/budget-status',
+    cockpitUsageSummary: '/api/v1/cockpit/usage-summary',
+    cockpitDailyCosts: '/api/v1/cockpit/daily-costs',
+    cockpitCostByModel: '/api/v1/cockpit/cost-by-model',
+    cockpitRecentRequests: '/api/v1/cockpit/recent-requests',
+    analyticsRequestLogs: '/v1/analytics/request-logs',
+    agents: '/api/v1/agents',
+    virtualKeys: '/api/v1/virtual-keys',
+    models: '/api/v1/models',
+    analyticsOverview: '/api/v1/analytics/overview',
+    analyticsUsage: '/api/v1/analytics/usage',
+    analyticsModels: '/api/v1/analytics/models',
+};

package/dist/shared/credentials.d.ts

@@ -0,0 +1,3 @@
+import type { AlephantManagerCredentials, AlephantVirtualKeyCredentials } from './types';
+export declare function resolveVirtualKeyCredentials(raw: AlephantVirtualKeyCredentials): Required<AlephantVirtualKeyCredentials>;
+export declare function resolveManagerCredentials(raw: AlephantManagerCredentials): Required<AlephantManagerCredentials>;

package/dist/shared/credentials.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveVirtualKeyCredentials = resolveVirtualKeyCredentials;
+exports.resolveManagerCredentials = resolveManagerCredentials;
+const constants_1 = require("./constants");
+const url_1 = require("./url");
+function resolveVirtualKeyCredentials(raw) {
+    return {
+        virtualKey: raw.virtualKey,
+        workspaceId: raw.workspaceId?.trim() || '',
+        gatewayBaseUrl: (0, url_1.trimTrailingSlash)(raw.gatewayBaseUrl || constants_1.DEFAULT_GATEWAY_BASE_URL),
+        saasBaseUrl: (0, url_1.trimTrailingSlash)(raw.saasBaseUrl || constants_1.DEFAULT_SAAS_BASE_URL),
+        analyticsBaseUrl: (0, url_1.trimTrailingSlash)(raw.analyticsBaseUrl || constants_1.DEFAULT_ANALYTICS_BASE_URL),
+    };
+}
+function resolveManagerCredentials(raw) {
+    return {
+        pat: raw.pat,
+        workspaceId: raw.workspaceId,
+        saasBaseUrl: (0, url_1.trimTrailingSlash)(raw.saasBaseUrl || constants_1.DEFAULT_SAAS_BASE_URL),
+        analyticsBaseUrl: (0, url_1.trimTrailingSlash)(raw.analyticsBaseUrl || constants_1.DEFAULT_ANALYTICS_BASE_URL),
+    };
+}

package/dist/shared/errors.d.ts

@@ -0,0 +1,3 @@
+import { NodeApiError } from 'n8n-workflow';
+import type { IExecuteFunctions, IHttpRequestMethods } from 'n8n-workflow';
+export declare function toNodeApiError(ctx: IExecuteFunctions, error: unknown, method: IHttpRequestMethods, url: string, itemIndex?: number): NodeApiError;

package/dist/shared/errors.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toNodeApiError = toNodeApiError;
+const n8n_workflow_1 = require("n8n-workflow");
+function isObjectLike(value) {
+    return typeof value === 'object' && value !== null;
+}
+function toNodeApiError(ctx, error, method, url, itemIndex) {
+    if (error instanceof n8n_workflow_1.NodeApiError) {
+        if (itemIndex !== undefined && error.context.itemIndex === undefined) {
+            error.context.itemIndex = itemIndex;
+        }
+        return error;
+    }
+    const description = `${method} ${url}`;
+    if (isObjectLike(error)) {
+        const nodeApiError = new n8n_workflow_1.NodeApiError(ctx.getNode(), error, { description, itemIndex });
+        nodeApiError.description = description;
+        return nodeApiError;
+    }
+    const message = typeof error === 'string' ? error : 'Alephant request failed';
+    return new n8n_workflow_1.NodeApiError(ctx.getNode(), { message }, { description, itemIndex });
+}

package/dist/shared/http.d.ts

@@ -0,0 +1,13 @@
+import type { IDataObject, IExecuteFunctions, IHttpRequestMethods } from 'n8n-workflow';
+export interface AlephantRequestOptions {
+    method: IHttpRequestMethods;
+    baseUrl: string;
+    path: string;
+    token: string;
+    workspaceId?: string;
+    headers?: IDataObject;
+    qs?: IDataObject;
+    body?: IDataObject;
+    itemIndex?: number;
+}
+export declare function alephantRequest<T>(ctx: IExecuteFunctions, options: AlephantRequestOptions): Promise<T>;

package/dist/shared/http.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.alephantRequest = alephantRequest;
+const errors_1 = require("./errors");
+const url_1 = require("./url");
+const TRANSIENT_NETWORK_ERROR_CODES = new Set([
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'ECONNABORTED',
+    'EPIPE',
+]);
+function isObjectLike(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isTransientNetworkError(error) {
+    if (!isObjectLike(error) || 'response' in error) {
+        return false;
+    }
+    const code = typeof error.code === 'string' ? error.code : '';
+    if (TRANSIENT_NETWORK_ERROR_CODES.has(code)) {
+        return true;
+    }
+    const message = typeof error.message === 'string' ? error.message : '';
+    return message.includes('Client network socket disconnected before secure TLS connection');
+}
+async function alephantRequest(ctx, options) {
+    const url = `${(0, url_1.trimTrailingSlash)(options.baseUrl)}${options.path}`;
+    const request = {
+        method: options.method,
+        url,
+        json: true,
+        headers: {
+            Authorization: `Bearer ${options.token}`,
+            'Content-Type': 'application/json',
+            ...(options.workspaceId ? { 'X-Workspace-Id': options.workspaceId } : {}),
+            ...(options.headers || {}),
+        },
+        qs: options.qs,
+        body: options.body,
+    };
+    let lastError;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            return (await ctx.helpers.httpRequest(request));
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt === 0 && isTransientNetworkError(error)) {
+                continue;
+            }
+            break;
+        }
+    }
+    throw (0, errors_1.toNodeApiError)(ctx, lastError, options.method, url, options.itemIndex);
+}

package/dist/shared/json.d.ts

@@ -0,0 +1 @@
+export declare function parseJsonObjectInput(value: unknown, fieldName: string): Record<string, unknown>;

package/dist/shared/json.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseJsonObjectInput = parseJsonObjectInput;
+function parseJsonObjectInput(value, fieldName) {
+    if (value === undefined || value === null || value === '') {
+        return {};
+    }
+    let parsed = value;
+    if (typeof value === 'string') {
+        try {
+            parsed = JSON.parse(value);
+        }
+        catch {
+            throw new Error(`${fieldName} must be valid JSON`);
+        }
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`${fieldName} must be a JSON object`);
+    }
+    return parsed;
+}

package/dist/shared/output.d.ts

@@ -0,0 +1,3 @@
+import type { NormalizedChatCompletion } from './types';
+export { trimTrailingSlash } from './url';
+export declare function normalizeChatCompletion(raw: any, requestId?: string): NormalizedChatCompletion;

package/dist/shared/output.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trimTrailingSlash = void 0;
+exports.normalizeChatCompletion = normalizeChatCompletion;
+var url_1 = require("./url");
+Object.defineProperty(exports, "trimTrailingSlash", { enumerable: true, get: function () { return url_1.trimTrailingSlash; } });
+function normalizeChatCompletion(raw, requestId) {
+    const firstChoice = Array.isArray(raw?.choices) ? raw.choices[0] : undefined;
+    const content = firstChoice?.message?.content ??
+        firstChoice?.text ??
+        '';
+    const text = typeof content === 'string' ? content : String(content);
+    return {
+        raw,
+        text,
+        usage: raw?.usage ?? {},
+        model: raw?.model,
+        requestId,
+        requestLogId: requestId,
+        finishReason: firstChoice?.finish_reason ?? firstChoice?.finishReason,
+    };
+}

package/dist/shared/types.d.ts

@@ -0,0 +1,27 @@
+export type InputMode = 'prompt' | 'messages';
+export interface AlephantVirtualKeyCredentials {
+    virtualKey: string;
+    workspaceId?: string;
+    gatewayBaseUrl?: string;
+    saasBaseUrl?: string;
+    analyticsBaseUrl?: string;
+}
+export interface AlephantManagerCredentials {
+    pat: string;
+    workspaceId: string;
+    saasBaseUrl?: string;
+    analyticsBaseUrl?: string;
+}
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+}
+export interface NormalizedChatCompletion {
+    raw: unknown;
+    text: string;
+    usage: Record<string, unknown>;
+    model: string | undefined;
+    requestId: string | undefined;
+    requestLogId: string | undefined;
+    finishReason: string | undefined;
+}

package/dist/shared/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/shared/url.d.ts

@@ -0,0 +1 @@
+export declare function trimTrailingSlash(value: string): string;

package/dist/shared/url.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trimTrailingSlash = trimTrailingSlash;
+function trimTrailingSlash(value) {
+    return value.replace(/\/+$/, '');
+}

package/dist/shared/usage.d.ts

@@ -0,0 +1,15 @@
+import type { IDataObject, IExecuteFunctions, INodeExecutionData } from 'n8n-workflow';
+export type UsageOperation = 'scope' | 'budgetStatus' | 'usageSummary' | 'dailyCosts' | 'costByModel' | 'recentRequests' | 'requestLogDetail';
+export interface UsageRequestParams {
+    period?: string | null;
+    limit?: number | null;
+    offset?: number | null;
+    requestLogId?: string | null;
+}
+export interface UsageRequest {
+    host?: 'saas' | 'analytics';
+    path: string;
+    qs?: IDataObject;
+}
+export declare function buildUsageRequest(operation: UsageOperation, params: UsageRequestParams): UsageRequest;
+export declare function executeUsageNode(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;

package/dist/shared/usage.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildUsageRequest = buildUsageRequest;
+exports.executeUsageNode = executeUsageNode;
+const n8n_workflow_1 = require("n8n-workflow");
+const constants_1 = require("./constants");
+const credentials_1 = require("./credentials");
+const http_1 = require("./http");
+function withQs(path, qs) {
+    const sanitized = Object.fromEntries(Object.entries(qs).filter(([, value]) => value !== undefined && value !== null && value !== ''));
+    return Object.keys(sanitized).length > 0 ? { path, qs: sanitized } : { path };
+}
+function isPositiveNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}
+function isNonNegativeNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+function requireRequestLogId(value) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error('Request Log ID is required');
+    }
+    return encodeURIComponent(value.trim());
+}
+function normalizeOptionalString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function readPath(source, path) {
+    return path.split('.').reduce((current, key) => {
+        if (typeof current !== 'object' || current === null) {
+            return undefined;
+        }
+        return current[key];
+    }, source);
+}
+function extractWorkspaceIdFromScope(scope) {
+    const paths = [
+        'workspaceId',
+        'workspace_id',
+        'xWorkspaceId',
+        'workspace.id',
+        'workspace.uuid',
+        'data.workspaceId',
+        'data.workspace_id',
+        'data.workspace.id',
+        'data.workspace.uuid',
+        'scope.workspaceId',
+        'scope.workspace_id',
+        'scope.workspace.id',
+        'scope.workspace.uuid',
+    ];
+    for (const path of paths) {
+        const workspaceId = normalizeOptionalString(readPath(scope, path));
+        if (workspaceId !== '') {
+            return workspaceId;
+        }
+    }
+    return '';
+}
+function normalizeAttemptCount(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0
+        ? Math.floor(value)
+        : 6;
+}
+function isRequestLogNotFoundError(error) {
+    const httpCode = normalizeOptionalString(readPath(error, 'httpCode'));
+    const status = readPath(error, 'response.status') ?? readPath(error, 'status');
+    const code = readPath(error, 'context.data.code') ?? readPath(error, 'response.data.code');
+    const message = normalizeOptionalString(readPath(error, 'context.data.message')) ||
+        normalizeOptionalString(readPath(error, 'response.data.message')) ||
+        normalizeOptionalString(readPath(error, 'message'));
+    return ((httpCode === '404' || status === 404) &&
+        (code === 40401 || message.toLowerCase().includes('request not found')));
+}
+async function requestWithLogPolling(ctx, options, maxAttempts) {
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await (0, http_1.alephantRequest)(ctx, options);
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= maxAttempts || !isRequestLogNotFoundError(error)) {
+                throw error;
+            }
+        }
+    }
+    throw lastError;
+}
+function buildUsageRequest(operation, params) {
+    switch (operation) {
+        case 'scope':
+            return { path: constants_1.ENDPOINTS.cockpitScope };
+        case 'budgetStatus':
+            return withQs(constants_1.ENDPOINTS.cockpitBudgetStatus, { period: params.period });
+        case 'usageSummary':
+            return withQs(constants_1.ENDPOINTS.cockpitUsageSummary, { period: params.period });
+        case 'dailyCosts':
+            return withQs(constants_1.ENDPOINTS.cockpitDailyCosts, { period: params.period });
+        case 'costByModel':
+            return withQs(constants_1.ENDPOINTS.cockpitCostByModel, { period: params.period });
+        case 'recentRequests':
+            return withQs(constants_1.ENDPOINTS.cockpitRecentRequests, {
+                limit: isPositiveNumber(params.limit) ? params.limit : undefined,
+                offset: isNonNegativeNumber(params.offset) ? params.offset : undefined,
+            });
+        case 'requestLogDetail':
+            return {
+                host: 'analytics',
+                path: `${constants_1.ENDPOINTS.analyticsRequestLogs}/${requireRequestLogId(params.requestLogId)}`,
+            };
+    }
+}
+async function executeUsageNode() {
+    const items = this.getInputData();
+    const credentials = (0, credentials_1.resolveVirtualKeyCredentials)((await this.getCredentials('alephantVirtualKeyApi')));
+    const returnData = [];
+    for (let itemIndex = 0; itemIndex < items.length; itemIndex++) {
+        const operation = this.getNodeParameter('operation', itemIndex);
+        let request;
+        try {
+            request = buildUsageRequest(operation, {
+                period: this.getNodeParameter('period', itemIndex, '7d'),
+                limit: this.getNodeParameter('limit', itemIndex, 50),
+                offset: this.getNodeParameter('offset', itemIndex, 0),
+                requestLogId: this.getNodeParameter('requestLogId', itemIndex, ''),
+            });
+        }
+        catch (error) {
+            throw new n8n_workflow_1.NodeOperationError(this.getNode(), error instanceof Error ? error.message : 'Invalid Alephant Usage input', { itemIndex });
+        }
+        let workspaceId = request.host === 'analytics'
+            ? normalizeOptionalString(this.getNodeParameter('workspaceId', itemIndex, '')) ||
+                normalizeOptionalString(items[itemIndex]?.json?.workspaceId) ||
+                normalizeOptionalString(items[itemIndex]?.json?.workspace_id) ||
+                normalizeOptionalString(items[itemIndex]?.json?.xWorkspaceId) ||
+                credentials.workspaceId
+            : undefined;
+        if (request.host === 'analytics' && workspaceId === '') {
+            const scope = await (0, http_1.alephantRequest)(this, {
+                method: 'GET',
+                baseUrl: credentials.saasBaseUrl,
+                path: constants_1.ENDPOINTS.cockpitScope,
+                token: credentials.virtualKey,
+                itemIndex,
+            });
+            workspaceId = extractWorkspaceIdFromScope(scope);
+        }
+        if (request.host === 'analytics' && workspaceId === '') {
+            throw new n8n_workflow_1.NodeOperationError(this.getNode(), 'Workspace ID is required for request log detail lookups and could not be resolved from Alephant Scope', { itemIndex });
+        }
+        const requestOptions = {
+            method: 'GET',
+            baseUrl: request.host === 'analytics' ? credentials.analyticsBaseUrl : credentials.saasBaseUrl,
+            path: request.path,
+            token: credentials.virtualKey,
+            workspaceId,
+            qs: request.qs,
+            itemIndex,
+        };
+        const data = request.host === 'analytics'
+            ? await requestWithLogPolling(this, requestOptions, normalizeAttemptCount(this.getNodeParameter('requestLogMaxAttempts', itemIndex, 6)))
+            : await (0, http_1.alephantRequest)(this, requestOptions);
+        returnData.push({
+            json: data,
+            pairedItem: { item: itemIndex },
+        });
+    }
+    return [returnData];
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@alephantai/n8n-nodes-alephant-analytics-ai",
+  "version": "0.1.0",
+  "description": "n8n AI tool node for Alephant analytics",
+  "license": "MIT",
+  "homepage": "https://alephant.io",
+  "author": {
+    "name": "Alephant",
+    "email": "dev@alephant.io",
+    "url": "https://alephant.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlephantAI/alephant-n8n.git",
+    "directory": "packages/alephant-analytics-ai"
+  },
+  "keywords": [
+    "n8n-community-node-package",
+    "n8n",
+    "alephant",
+    "analytics",
+    "ai",
+    "agent",
+    "tool",
+    "finops"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json && node ../../scripts/copy-package-assets.cjs dist AlephantAnalyticsAi",
+    "lint": "npm --prefix ../.. run lint",
+    "test": "npm --prefix ../.. run test",
+    "prepublishOnly": "npm run lint && npm run test && npm run build"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "package.json"
+  ],
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "credentials": [
+      "dist/credentials/AlephantVirtualKeyApi.credentials.js"
+    ],
+    "nodes": [
+      "dist/nodes/AlephantAnalyticsAi/AlephantAnalyticsAi.node.js"
+    ]
+  },
+  "peerDependencies": {
+    "n8n-workflow": "*"
+  },
+  "devDependencies": {
+    "n8n-workflow": "*",
+    "typescript": "^5.6.3"
+  }
+}