dremiojs 1.0.0

package/jest.config.js

@@ -0,0 +1,10 @@
+module.exports = {
+    preset: 'ts-jest',
+    testEnvironment: 'node',
+    testMatch: ['**/*.test.ts'],
+    verbose: true,
+    forceExit: true,
+    clearMocks: true,
+    resetMocks: true,
+    restoreMocks: true,
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "dremiojs",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.0.3",
+    "axios": "^1.13.2",
+    "dotenv": "^17.2.3",
+    "eslint": "^9.39.2",
+    "jest": "^30.2.0",
+    "prettier": "^3.7.4",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}

package/src/api/catalog.ts

@@ -0,0 +1,74 @@
+import { BaseClient } from '../client/base';
+import { CatalogItem } from '../types/catalog';
+
+export class CatalogResource {
+    private client: BaseClient;
+
+    constructor(client: BaseClient) {
+        this.client = client;
+    }
+
+    /**
+     * Get a catalog item by ID.
+     */
+    async get(id: string): Promise<CatalogItem> {
+        // Need access to protected request method of client. 
+        // Usually we'd expose a public 'request' or make CatalogResource extend BaseClient (but that's wrong inheritance).
+        // Or we pass a request function.
+        // For now, let's assume we can call a public method on client, or cast it to any.
+        // Better: Make `request` public on BaseClient but keep it low-level.
+        return this.client.request({
+            method: 'GET',
+            url: `/catalog/${encodeURIComponent(id)}`,
+        });
+    }
+
+    /**
+     * Get a catalog item by Path.
+     * Path should be an array of strings ['space', 'folder', 'dataset']
+     */
+    async getByPath(path: string[]): Promise<CatalogItem> {
+        if (path.length === 0) {
+            const response: any = await this.client.request({
+                method: 'GET',
+                url: '/catalog'
+            });
+            // Normalize root response which is usually { data: [...] }
+            const children = response.data || (Array.isArray(response) ? response : []);
+            return {
+                id: 'ROOT',
+                path: [],
+                type: 'CONTAINER',
+                containerType: 'HOME',
+                children: children
+            } as CatalogItem;
+        }
+        return this.client.request({
+            method: 'GET',
+            url: `/catalog/by-path/${path.map(p => encodeURIComponent(p)).join('/')}` // Note: formatting might vary
+        });
+    }
+
+    async create(item: Partial<CatalogItem>): Promise<CatalogItem> {
+        return this.client.request({
+            method: 'POST',
+            url: '/catalog',
+            data: item
+        });
+    }
+
+    async update(id: string, item: Partial<CatalogItem>): Promise<CatalogItem> {
+        return this.client.request({
+            method: 'PUT',
+            url: `/catalog/${encodeURIComponent(id)}`,
+            data: item
+        });
+    }
+
+    async delete(id: string): Promise<void> {
+        return this.client.request({
+            method: 'DELETE',
+            url: `/catalog/${encodeURIComponent(id)}`
+        });
+    }
+}

package/src/api/jobs.ts

@@ -0,0 +1,105 @@
+import { BaseClient } from '../client/base';
+import { JobState, JobStatus, JobSubmissionResponse, JobResultsResponse } from '../types/job';
+
+export class JobResource {
+    private client: BaseClient;
+
+    constructor(client: BaseClient) {
+        this.client = client;
+    }
+
+    /**
+     * Submit a SQL query for execution.
+     */
+    async submitSQL(sql: string, context?: string[]): Promise<JobSubmissionResponse> {
+        const payload: any = { sql };
+        if (context) {
+            payload.context = context;
+        }
+
+        return this.client.request({
+            method: 'POST',
+            url: '/sql',
+            data: payload
+        });
+    }
+
+    /**
+     * Get the status of a job.
+     */
+    async getJobStatus(jobId: string): Promise<JobStatus> {
+        return this.client.request({
+            method: 'GET',
+            url: `/job/${encodeURIComponent(jobId)}`
+        });
+    }
+
+    /**
+     * Get results of a completed job.
+     */
+    async getJobResults(jobId: string, offset = 0, limit = 100): Promise<JobResultsResponse> {
+        return this.client.request({
+            method: 'GET',
+            url: `/job/${encodeURIComponent(jobId)}/results`,
+            params: {
+                offset,
+                limit
+            }
+        });
+    }
+
+    /**
+     * Cancel a job.
+     */
+    async cancelJob(jobId: string): Promise<void> {
+        // NOTE: Cancellation endpoint varies. 
+        // Software: POST /api/v3/job/{id}/cancel
+        // Cloud: POST /v0/projects/{id}/job/{id}/cancel (verify?)
+
+        // Usually Cloud uses delete method or cancel action?
+        // Documentation check: "Cancel Job"
+
+        // Let's assume standard POST /job/{id}/cancel pattern works for both relative to base/project.
+        // If it doesn't, we might need correction.
+        return this.client.request({
+            method: 'POST',
+            url: `/job/${encodeURIComponent(jobId)}/cancel`
+        });
+    }
+
+    /**
+     * Helper: Execute SQL and wait for completion.
+     * Polls every 1s by default.
+     */
+    async executeQuery(sql: string, options: { context?: string[], pollIntervalMs?: number } = {}): Promise<any[]> {
+        // 1. Submit
+        const submission = await this.submitSQL(sql, options.context);
+        const jobId = submission.id;
+
+        // 2. Poll
+        const pollInterval = options.pollIntervalMs || 1000;
+        let jobState: JobState = 'STARTING';
+
+        while (true) {
+            const status = await this.getJobStatus(jobId);
+            jobState = status.jobState;
+
+            if (jobState === 'COMPLETED') {
+                break;
+            }
+
+            if (jobState === 'FAILED' || jobState === 'CANCELED') {
+                throw new Error(`Job ${jobId} failed with state ${jobState}: ${status.errorMessage}`);
+            }
+
+            // Wait
+            await new Promise(resolve => setTimeout(resolve, pollInterval));
+        }
+
+        // 3. fetch results
+        // TODO: Handle pagination if needed? executeQuery usually returns all or iterator.
+        // For simplicity/safety, let's fetch first 500 rows.
+        const results = await this.getJobResults(jobId, 0, 500);
+        return results.rows;
+    }
+}

package/src/api/reflection.ts

@@ -0,0 +1,77 @@
+import { BaseClient } from '../client/base';
+import { Reflection, ReflectionSummary } from '../types/reflection';
+
+export class ReflectionResource {
+    private client: BaseClient;
+
+    constructor(client: BaseClient) {
+        this.client = client;
+    }
+
+    async list(options: { datasetId?: string } = {}): Promise<ReflectionSummary[]> {
+        const params: any = {};
+        // Filter by datasetId if provided (common use case, though client-side filtering might be needed if API doesn't support it directly on list)
+        // Dremio API docs v3 suggest /reflection endpoint returns all? Or supports filter?
+        // Convention usually supports 'filter' query param.
+        // Dremio Cloud: /reflection?filter=datasetId=="..."
+        // Software: similar.
+
+        // Let's assume we return raw list and let the user filter, or try to use `filter` param if we can construct RQL.
+        // For now, simpler is creating a filtered list if possible or just returning all.
+        // NOTE: Listing ALL reflections can be heavy.
+
+        // Checking `dremio_api_integration_patterns`: "When listing, applications often need to filter by `datasetId` locally".
+
+        const response = await this.client.request<{ data?: ReflectionSummary[], dataCount?: number }>({
+            method: 'GET',
+            url: '/reflection'
+        });
+
+        // Software/Cloud return list in different structure?
+        // Software v3 returns { data: [...] }
+        // Cloud v0 returns { data: [...] } ?
+
+        let allReflections: ReflectionSummary[] = [];
+        if (Array.isArray(response)) {
+            allReflections = response;
+        } else if (response.data && Array.isArray(response.data)) {
+            allReflections = response.data;
+        }
+
+        if (options.datasetId) {
+            return allReflections.filter(r => r.datasetId === options.datasetId);
+        }
+        return allReflections;
+    }
+
+    async get(id: string): Promise<Reflection> {
+        return this.client.request({
+            method: 'GET',
+            url: `/reflection/${encodeURIComponent(id)}`
+        });
+    }
+
+    async create(reflection: Partial<Reflection>): Promise<Reflection> {
+        return this.client.request({
+            method: 'POST',
+            url: '/reflection',
+            data: reflection
+        });
+    }
+
+    async update(id: string, reflection: Partial<Reflection>): Promise<Reflection> {
+        // Optimistic locking? Usually requires `tag`.
+        return this.client.request({
+            method: 'PUT',
+            url: `/reflection/${encodeURIComponent(id)}`,
+            data: reflection
+        });
+    }
+
+    async delete(id: string): Promise<void> {
+        return this.client.request({
+            method: 'DELETE',
+            url: `/reflection/${encodeURIComponent(id)}`
+        });
+    }
+}

package/src/api/source.ts

@@ -0,0 +1,61 @@
+import { BaseClient } from '../client/base';
+import { Source } from '../types/catalog';
+
+export class SourceResource {
+    private client: BaseClient;
+
+    constructor(client: BaseClient) {
+        this.client = client;
+    }
+
+    async list(): Promise<Source[]> {
+        // Sources are catalog items with type=SOURCE
+        // Dremio API doesn't always support filtering by type in top level listing easily without ?include=...
+        // but /catalog root usually returns top level spaces and sources.
+        // Dremio Cloud: /v0/projects/{id}/catalog returns sources and spaces.
+
+        const response = await this.client.request<{ data?: any[] }>({
+            method: 'GET',
+            url: '/catalog'
+        });
+
+        let items: any[] = [];
+        if (Array.isArray(response)) {
+            items = response;
+        } else if (response.data && Array.isArray(response.data)) {
+            items = response.data;
+        }
+
+        return items.filter(item => item.type === 'SOURCE' || item.containerType === 'SOURCE');
+    }
+
+    async get(id: string): Promise<Source> {
+        return this.client.request({
+            method: 'GET',
+            url: `/catalog/${encodeURIComponent(id)}`
+        });
+    }
+
+    async create(source: Source): Promise<Source> {
+        return this.client.request({
+            method: 'POST',
+            url: '/catalog',
+            data: source
+        });
+    }
+
+    async update(id: string, source: Partial<Source>): Promise<Source> {
+        return this.client.request({
+            method: 'PUT',
+            url: `/catalog/${encodeURIComponent(id)}`,
+            data: source
+        });
+    }
+
+    async delete(id: string): Promise<void> {
+        return this.client.request({
+            method: 'DELETE',
+            url: `/catalog/${encodeURIComponent(id)}`
+        });
+    }
+}

package/src/api/user.ts

@@ -0,0 +1,32 @@
+import { BaseClient } from '../client/base';
+
+export interface User {
+    id: string;
+    name: string;
+    firstName?: string;
+    lastName?: string;
+    email?: string;
+    roles?: any[];
+}
+
+export class UserResource {
+    private client: BaseClient;
+
+    constructor(client: BaseClient) {
+        this.client = client;
+    }
+
+    async get(id: string): Promise<User> {
+        return this.client.request({
+            method: 'GET',
+            url: `/user/${encodeURIComponent(id)}`
+        });
+    }
+
+    async getByName(name: string): Promise<User> {
+        return this.client.request({
+            method: 'GET',
+            url: `/user/by-name/${encodeURIComponent(name)}`
+        });
+    }
+}

package/src/client/base.ts

@@ -0,0 +1,66 @@
+import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios';
+import { BaseDremioConfig } from '../types/config';
+import { CatalogResource } from '../api/catalog';
+import { JobResource } from '../api/jobs';
+import { ReflectionResource } from '../api/reflection';
+import { SourceResource } from '../api/source';
+import { UserResource } from '../api/user';
+
+export abstract class BaseClient {
+    protected axiosInstance: AxiosInstance;
+    protected config: BaseDremioConfig;
+    public catalog: CatalogResource;
+    public jobs: JobResource;
+    public reflections: ReflectionResource;
+    public sources: SourceResource;
+    public users: UserResource;
+
+    constructor(config: BaseDremioConfig) {
+        this.config = config;
+        this.axiosInstance = axios.create({
+            baseURL: config.baseUrl,
+            timeout: config.timeout || 30000,
+            headers: {
+                'Content-Type': 'application/json',
+            },
+        });
+
+        this.catalog = new CatalogResource(this);
+        this.jobs = new JobResource(this);
+        this.reflections = new ReflectionResource(this);
+        this.sources = new SourceResource(this);
+        this.users = new UserResource(this);
+
+        // Add generic interceptors if needed
+        this.axiosInstance.interceptors.response.use(
+            (response) => response,
+            (error) => {
+                // Enhance error handling here
+                return Promise.reject(error);
+            }
+        );
+    }
+
+    protected abstract getAuthHeaders(): Record<string, string> | Promise<Record<string, string>>;
+
+    public async request<T = any>(config: AxiosRequestConfig): Promise<T> {
+        const authHeaders = await this.getAuthHeaders();
+        const mergedConfig = {
+            ...config,
+            headers: {
+                ...config.headers,
+                ...authHeaders,
+            },
+        };
+
+        try {
+            const response: AxiosResponse<T> = await this.axiosInstance.request(mergedConfig);
+            return response.data;
+        } catch (error: any) {
+            if (error.response) {
+                throw new Error(`Dremio API Error: ${error.response.status} ${error.response.statusText} - ${JSON.stringify(error.response.data)}`);
+            }
+            throw error;
+        }
+    }
+}

package/src/client/cloud.ts

@@ -0,0 +1,37 @@
+import { BaseClient } from './base';
+import { DremioCloudConfig } from '../types/config';
+
+export class DremioCloudClient extends BaseClient {
+    protected config: DremioCloudConfig;
+
+    constructor(config: DremioCloudConfig) {
+        if (!config.authToken) {
+            throw new Error('Auth token is required for Dremio Cloud.');
+        }
+        if (!config.projectId) {
+            throw new Error('Project ID is required for Dremio Cloud.');
+        }
+
+        // Adjust BaseUrl to include project context
+        const configWithProject = { ...config };
+        if (!configWithProject.baseUrl.includes('/projects/')) {
+            // Remove trailing slash if present
+            const cleanBase = configWithProject.baseUrl.replace(/\/$/, '');
+            configWithProject.baseUrl = `${cleanBase}/projects/${config.projectId}`;
+        }
+
+        super(configWithProject);
+        this.config = config;
+    }
+
+    protected getAuthHeaders(): Record<string, string> {
+        return {
+            Authorization: `Bearer ${this.config.authToken}`,
+        };
+    }
+
+    // Cloud specific methods can go here or generic methods can use projectId from config
+    getProjectId(): string {
+        return this.config.projectId;
+    }
+}

package/src/client/software.ts

@@ -0,0 +1,73 @@
+import { BaseClient } from './base';
+import { DremioSoftwareConfig } from '../types/config';
+
+interface LoginResponse {
+    token: string;
+    // Add other fields if necessary
+}
+
+export class DremioSoftwareClient extends BaseClient {
+    protected config: DremioSoftwareConfig;
+    private token: string | null = null;
+
+    constructor(config: DremioSoftwareConfig) {
+        super(config);
+        this.config = config;
+        if (config.authToken) {
+            this.token = config.authToken;
+        }
+    }
+
+    protected async getAuthHeaders(): Promise<Record<string, string>> {
+        if (!this.token) {
+            await this.login();
+        }
+        return {
+            Authorization: `Bearer ${this.token}`,
+        };
+    }
+
+    private async login(): Promise<void> {
+        if (!this.config.username || !this.config.password) {
+            throw new Error('Username and password are required for login if no token is provided.');
+        }
+
+        // Heuristic to handle base URL variations for login
+        // If base URL is .../api/v3, login is often at .../apiv2/login
+        let loginUrl = '/apiv2/login';
+        if (this.config.baseUrl.endsWith('/api/v3')) {
+            const baseUrlRoot = this.config.baseUrl.replace('/api/v3', '');
+            // We will perform a direct axios call to the root + /apiv2/login
+            // But since our instance is bound to baseUrl, we might need a separate call or specific path
+            // Actually, axios instance is bound to /api/v3 usually.
+
+            // Let's rely on the user providing a correct Base URL. 
+            // IMPLEMENTATION NOTE: Dremio Software V3 API usually sits at /api/v3. 
+            // Login is at /apiv2/login.
+            // We need to construct the login URL relative to the server root, not the V3 API root.
+            // For simplicity, we will try to infer the root.
+        }
+
+        // Workaround: create a new axios request for login that overrides the baseURL if necessary
+        // or just use absolute URL if we can derive it.
+
+        // Simplest approach: Assume config.baseUrl is the API base.
+        // We'll strip the API part for the login call.
+        const apiBase = this.config.baseUrl;
+        const rootUrl = apiBase.replace(/\/api\/v3\/?$/, '');
+
+        try {
+            // Direct call using imported axios (not the instance) to avoid prefix issues if needed,
+            // or just re-config the instance call.
+            const response = await this.axiosInstance.post<LoginResponse>(`${rootUrl}/apiv2/login`, {
+                userName: this.config.username,
+                password: this.config.password,
+            });
+
+            this.token = response.data.token;
+        } catch (error) {
+            console.error('Login failed');
+            throw error;
+        }
+    }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+// Clients
+export { DremioCloudClient } from './client/cloud';
+export { DremioSoftwareClient } from './client/software';
+
+// Types
+export * from './types/config';
+export * from './types/catalog';
+export * from './types/job';
+export * from './types/reflection';
+
+// Resources (if needed directly, though usually accessed via client)
+export * from './api/catalog';
+export * from './api/jobs';
+export * from './api/reflection';
+export * from './api/source';
+export * from './api/user';

package/src/types/catalog.ts

@@ -0,0 +1,31 @@
+export type CatalogType = 'CONTAINER' | 'DATASET' | 'FILE' | 'HOME' | 'SPACE' | 'SOURCE' | 'FOLDER';
+
+export interface CatalogItem {
+    id: string;
+    path: string[];
+    tag?: string;
+    type: CatalogType;
+    containerType?: string; // HOME, SPACE, SOURCE, FOLDER
+    createdAt?: string;
+    children?: CatalogItem[];
+}
+
+export interface Dataset extends CatalogItem {
+    type: 'DATASET';
+    fields?: any[];
+    sql?: string;
+    format?: any;
+}
+
+export interface Source extends CatalogItem {
+    type: 'SOURCE';
+    config?: any;
+}
+
+export interface Space extends CatalogItem {
+    type: 'SPACE';
+}
+
+export interface Folder extends CatalogItem {
+    type: 'FOLDER';
+}

package/src/types/config.ts

@@ -0,0 +1,18 @@
+export interface BaseDremioConfig {
+    baseUrl: string;
+    timeout?: number;
+}
+
+export interface DremioCloudConfig extends BaseDremioConfig {
+    authToken: string;
+    projectId: string;
+}
+
+export interface DremioSoftwareConfig extends BaseDremioConfig {
+    authToken?: string;
+    username?: string;
+    password?: string;
+    checkSSLCerts?: boolean;
+}
+
+export type DremioConfig = DremioCloudConfig | DremioSoftwareConfig;

package/src/types/job.ts

@@ -0,0 +1,18 @@
+export type JobState = 'NOT_SUBMITTED' | 'STARTING' | 'RUNNING' | 'COMPLETED' | 'CANCELED' | 'FAILED' | 'QUEUED' | 'PLANNING' | 'ENGINE_START' | 'EXECUTION_PLANNING';
+
+export interface JobStatus {
+    id: string;
+    jobState: JobState;
+    errorMessage?: string;
+    rowCount?: number;
+}
+
+export interface JobSubmissionResponse {
+    id: string;
+}
+
+export interface JobResultsResponse {
+    rowCount: number;
+    schema: any[];
+    rows: any[];
+}

package/src/types/reflection.ts

@@ -0,0 +1,29 @@
+export type ReflectionType = 'RAW' | 'AGGREGATION';
+
+export interface Reflection {
+    id: string;
+    type: ReflectionType;
+    name: string;
+    datasetId: string;
+    enabled: boolean;
+    status?: {
+        availability: string;
+        config: string;
+        refresh: string;
+    };
+    dimensionFields?: any[]; // Simplified
+    measureFields?: any[];   // Simplified
+    distributionFields?: any[];
+    partitionFields?: any[];
+    tag?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+
+export interface ReflectionSummary {
+    id: string;
+    name: string;
+    type: ReflectionType;
+    datasetId: string;
+    status: string;
+}