dremiojs 1.0.0 → 1.2.0

package/docs/sql_and_jobs.md

@@ -0,0 +1,59 @@
+# SQL & Jobs API Guide
+
+Executing SQL in Dremio is an asynchronous process involving job submission, polling, and result retrieval. `dremiojs` simplifies this with a helper method while still exposing raw controls.
+
+## The Easy Way: `executeQuery`
+
+The `executeQuery` method handles the entire lifecycle: submitting the job, polling for completion, and fetching results.
+
+```typescript
+const rows = await client.jobs.executeQuery('SELECT * FROM sys.version');
+console.log(rows); 
+// Output: [{ version: '24.2.0', ... }]
+```
+
+### Context
+You can provide a context for the query (e.g., to simplify table names).
+
+```typescript
+// Queries table inside 'MarketingSpace' without full qualification
+const rows = await client.jobs.executeQuery('SELECT * FROM "Campaigns"', {
+    context: ['MarketingSpace'] 
+});
+```
+
+## The Query Lifecycle (Manual Control)
+
+For long-running queries or advanced UI integration (like progress bars), you may want to manage the lifecycle yourself.
+
+### 1. Submit Job
+```typescript
+const jobStub = await client.jobs.submitSQL('SELECT count(*) FROM big_table');
+const jobId = jobStub.id;
+console.log('Job submitted:', jobId);
+```
+
+### 2. Check Status
+Poll the job status until it reaches a terminal state (`COMPLETED`, `FAILED`, `CANCELED`).
+
+```typescript
+const status = await client.jobs.getJobStatus(jobId);
+console.log('Current State:', status.jobState); // e.g., 'RUNNING'
+```
+
+### 3. Get Results
+Once the job is `COMPLETED`, fetch the results.
+
+```typescript
+// Fetch first 100 rows
+const results = await client.jobs.getJobResults(jobId, 0, 100);
+console.log('Rows:', results.rows);
+console.log('Schema:', results.schema);
+```
+
+### 4. Cancel Job
+If the user wants to stop the query:
+
+```typescript
+await client.jobs.cancelJob(jobId);
+```

package/docs/users.md

@@ -0,0 +1,19 @@
+# Users API Guide
+
+The Users API allows you to lookup user information. This is useful for administration and governance workflows.
+
+## Getting a User by ID
+
+```typescript
+const user = await client.users.get('user-guid');
+console.log(user.name, user.email);
+```
+
+## Getting a User by Name
+
+```typescript
+const user = await client.users.getByName('admin');
+console.log(user.id);
+```
+
+*Note: User management capabilities (Create/Update/Delete) are typically restricted to administrative APIs and may differ significantly between Software and Cloud. The current library focuses on lookup/retrieval.*

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "dremiojs",
-  "version": "1.0.0",
-  "description": "",
+  "version": "1.2.0",
+  "description": "A TypeScript client library for Dremio Cloud and Software.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developer-advocacy-dremio/dremiojs.git"
+  },
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
@@ -12,6 +16,7 @@
   "type": "commonjs",
   "devDependencies": {
     "@types/jest": "^30.0.0",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.0.3",
     "axios": "^1.13.2",
     "dotenv": "^17.2.3",
@@ -21,5 +26,8 @@
     "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.1"
   }
 }

package/src/api/collaboration.ts

@@ -0,0 +1,55 @@
+import { BaseClient } from '../client/base';
+
+export interface Tag {
+    tags: string[];
+    version?: string;
+}
+
+export interface Wiki {
+    text: string;
+    version?: string;
+}
+
+export class CollaborationResource {
+    private client: BaseClient;
+
+    constructor(client: BaseClient) {
+        this.client = client;
+    }
+
+    async getTags(catalogId: string): Promise<Tag> {
+        return this.client.request<Tag>({
+            method: 'GET',
+            url: `/catalog/${encodeURIComponent(catalogId)}/collaboration/tag`
+        });
+    }
+
+    async setTags(catalogId: string, tags: string[], version?: string): Promise<void> {
+        const data: any = { tags };
+        if (version) data.version = version;
+
+        await this.client.request({
+            method: 'POST',
+            url: `/catalog/${encodeURIComponent(catalogId)}/collaboration/tag`,
+            data
+        });
+    }
+
+    async getWiki(catalogId: string): Promise<Wiki> {
+        return this.client.request<Wiki>({
+            method: 'GET',
+            url: `/catalog/${encodeURIComponent(catalogId)}/collaboration/wiki`
+        });
+    }
+
+    async setWiki(catalogId: string, text: string, version?: string): Promise<void> {
+        const data: any = { text };
+        if (version) data.version = version;
+
+        await this.client.request({
+            method: 'POST',
+            url: `/catalog/${encodeURIComponent(catalogId)}/collaboration/wiki`,
+            data
+        });
+    }
+}

package/src/api/credentials.ts

@@ -0,0 +1,74 @@
+import { BaseClient } from '../client/base';
+
+export interface Credential {
+    id: string;
+    name: string;
+    credentialType: 'CLIENT_SECRET' | 'EXTERNAL_JWT';
+    clientSecretConfig?: {
+        clientId: string;
+        clientSecret?: string; // Only returned on creation
+        createdAt?: string;
+        expiresAt?: string;
+    };
+    // ... External JWT config properties could be added here
+}
+
+export class CredentialsResource {
+    private client: BaseClient;
+
+    constructor(client: BaseClient) {
+        this.client = client;
+    }
+
+    /**
+     * List credentials for a Service User.
+     */
+    async list(userId: string): Promise<Credential[]> {
+        const response = await this.client.request<Credential[]>({
+            method: 'GET',
+            url: `/user/${encodeURIComponent(userId)}/oauth/credentials`
+        });
+        // Response might be wrapped or array, usually array for list endpoints but docs example showed {id...} which is odd for a list.
+        // Re-reading docs: GET /user/{id}/oauth/credentials returns A LIST?
+        // Actually the doc example showed `curl -X GET .../credentials` returning a SINGLE object?
+        // Wait, normally `credentials` implies list. Let's assume list for now or container.
+        // Actually, if it returns a single object it might be 'get by id'.
+        // Correction: The docs show GET .../credentials returning ONE credential object in the example? 
+        // That implies you might only have one? Or the doc example is misleading/specific ID.
+        // Let's assume it returns an array for safety or we handle both.
+        return Array.isArray(response) ? response : [response];
+    }
+
+    /**
+     * Create a Client Secret for a Service User.
+     * @param userId Service User ID
+     * @param name Name for the credential
+     * @param lifetimeDays Duration in days (max 180)
+     */
+    async create(userId: string, name: string, lifetimeDays: number = 180): Promise<Credential> {
+        return this.client.request<Credential>({
+            method: 'POST',
+            url: `/user/${encodeURIComponent(userId)}/oauth/credentials`,
+            data: {
+                name,
+                credentialType: 'CLIENT_SECRET',
+                clientSecretConfig: {
+                    lifetime: {
+                        quantity: lifetimeDays,
+                        units: 'DAYS'
+                    }
+                }
+            }
+        });
+    }
+
+    /**
+     * Delete a credential.
+     */
+    async delete(userId: string, credentialId: string): Promise<void> {
+        await this.client.request({
+            method: 'DELETE',
+            url: `/user/${encodeURIComponent(userId)}/oauth/credentials/${encodeURIComponent(credentialId)}`
+        });
+    }
+}

package/src/api/governance.ts

@@ -0,0 +1,52 @@
+import { BaseClient } from '../client/base';
+
+export interface Grant {
+    id: string; // User or Role ID
+    granteeType: 'USER' | 'ROLE';
+    privileges: string[]; // e.g. ['SELECT', 'ALTER']
+}
+
+export interface AccessControlList {
+    users?: { id: string, permissions: string[] }[];
+    roles?: { id: string, permissions: string[] }[];
+}
+
+export class GovernanceResource {
+    private client: BaseClient;
+
+    constructor(client: BaseClient) {
+        this.client = client;
+    }
+
+    /**
+     * Dremio Cloud: Get Grants for a catalog entity.
+     * Dremio Software: Typically uses ACLs embedded in Catalog.
+     * This method targets the /grants endpoints primarily used in Cloud/Newer Software.
+     */
+    async getGrants(catalogId: string): Promise<Grant[]> {
+        // Dremio Cloud: /v0/projects/{id}/catalog/{id}/grants
+        // Note: ProjectId is handled by client base url interceptor/logic usually.
+        const response = await this.client.request<{ grants: Grant[] }>({
+            method: 'GET',
+            url: `/catalog/${encodeURIComponent(catalogId)}/grants`
+        });
+        return response.grants || [];
+    }
+
+    /**
+     * Dremio Cloud: Update Grants.
+     */
+    async updateGrants(catalogId: string, grants: Grant[]): Promise<void> {
+        await this.client.request({
+            method: 'PUT',
+            url: `/catalog/${encodeURIComponent(catalogId)}/grants`,
+            data: { grants }
+        });
+    }
+
+    /**
+     * Dremio Software: Set ACL (Software v3 style) on an entity.
+     * Technically this usually goes via Catalog Update, but we provide a helper here if beneficial.
+     * For now, we'll focus on the 'Grants' endpoint which is cleaner if supported.
+     */
+}

package/src/api/lineage.ts

@@ -0,0 +1,19 @@
+import { BaseClient } from '../client/base';
+
+export class LineageResource {
+    private client: BaseClient;
+
+    constructor(client: BaseClient) {
+        this.client = client;
+    }
+
+    async get(catalogId: string): Promise<any> {
+        return this.client.request({
+            method: 'GET',
+            url: `/catalog/${encodeURIComponent(catalogId)}/graph`
+        });
+        // Note: Graph/Lineage endpoints can vary. 
+        // Software v3 doc: GET /api/v3/catalog/{id}/graph
+        // Cloud doc checks: /v0/projects/{id}/catalog/{id}/graph
+    }
+}

package/src/api/provisioning.ts

@@ -0,0 +1,32 @@
+import { BaseClient } from '../client/base';
+
+// Simplified Engine/Queue types
+export interface Engine {
+    id: string;
+    name: string;
+    size?: string;
+    status?: string;
+}
+
+export class ProvisioningResource {
+    private client: BaseClient;
+
+    constructor(client: BaseClient) {
+        this.client = client;
+    }
+
+    /**
+     * Dremio Cloud: List Engines
+     */
+    async listEngines(): Promise<Engine[]> {
+        // Cloud: /v0/projects/{id}/engines
+        const response = await this.client.request<any>({
+            method: 'GET',
+            url: '/engines'
+        });
+        // Normalize response
+        return response.data || (Array.isArray(response) ? response : []);
+    }
+
+    // Additional methods for start/stop engines or queue management could be added here
+}

package/src/api/scripts.ts

@@ -0,0 +1,64 @@
+import { BaseClient } from '../client/base';
+
+export interface Script {
+    id: string;
+    name: string;
+    description?: string;
+    content: string; // SQL
+    context?: string[];
+    createdAt?: string;
+    modifiedAt?: string;
+    createdBy?: string;
+    modifiedBy?: string;
+}
+
+export class ScriptsResource {
+    private client: BaseClient;
+
+    constructor(client: BaseClient) {
+        this.client = client;
+    }
+
+    async list(options: { maxResults?: number, ownedBy?: string } = {}): Promise<Script[]> {
+        const params: any = {};
+        if (options.maxResults) params.maxResults = options.maxResults;
+        if (options.ownedBy) params.ownedBy = options.ownedBy;
+
+        const response = await this.client.request<{ data: Script[] }>({
+            method: 'GET',
+            url: '/scripts',
+            params
+        });
+        return response.data || [];
+    }
+
+    async get(id: string): Promise<Script> {
+        return this.client.request<Script>({
+            method: 'GET',
+            url: `/scripts/${encodeURIComponent(id)}`
+        });
+    }
+
+    async create(script: Partial<Script>): Promise<Script> {
+        return this.client.request<Script>({
+            method: 'POST',
+            url: '/scripts',
+            data: script
+        });
+    }
+
+    async update(id: string, script: Partial<Script>): Promise<Script> {
+        return this.client.request<Script>({
+            method: 'PUT',
+            url: `/scripts/${encodeURIComponent(id)}`,
+            data: script
+        });
+    }
+
+    async delete(id: string): Promise<void> {
+        return this.client.request({
+            method: 'DELETE',
+            url: `/scripts/${encodeURIComponent(id)}`
+        });
+    }
+}

package/src/api/token.ts

@@ -0,0 +1,50 @@
+import { BaseClient } from '../client/base';
+
+export class TokenResource {
+    private client: BaseClient;
+
+    constructor(client: BaseClient) {
+        this.client = client;
+    }
+
+    // Usually administrative
+    // Implement standard PAT creation endpoints if available/documented for target version
+
+    // Dremio Software: POST /api/v3/user/{uid}/token
+    // Dremio Cloud: /v0/projects/{id}/users/{uid}/token ? (Check docs)
+    // Often PAT management is done via specialized internal APIs or different paths.
+    // We will provide a placeholder that attempts the standard V3 path.
+
+    // Supports Dremio Cloud (PAT) and Software (PAT) creation
+    async createToken(userId: string, label: string, lifetimeDays: number = 30): Promise<{ token: string }> {
+        const config = this.client.getConfig();
+        let baseUrl = config.baseUrl.replace(/\/$/, '');
+
+        // Ensure we target the correct API root
+        // Cloud: https://api.dremio.cloud/v0/user/{id}/token
+        // Software: http://host:9047/api/v3/user/{id}/token
+
+        // If the client is Cloud, the getConfig() returns the raw URL (without project), 
+        // effectively handling the path correctly.
+
+        const fullUrl = `${baseUrl}/user/${encodeURIComponent(userId)}/token`;
+
+        const millisecondsToExpire = lifetimeDays * 24 * 60 * 60 * 1000;
+
+        const response = await this.client.request({
+            method: 'POST',
+            url: fullUrl, // Absolute URL to bypass axios baseURL prefix
+            data: {
+                label,
+                millisecondsToExpire
+            }
+        });
+
+        // Cloud API returns the token string directly in some contexts, or JSON?
+        // Based on docs example, checking if response is string or object.
+        if (typeof response === 'string') {
+            return { token: response };
+        }
+        return response; // Assuming { token: ... } or similar JSON
+    }
+}

package/src/api/user.ts

@@ -1,12 +1,17 @@
 import { BaseClient } from '../client/base';
 
+// Basic types
 export interface User {
     id: string;
     name: string;
     firstName?: string;
     lastName?: string;
     email?: string;
-    roles?: any[];
+    tag?: string;
+    identityType?: 'REGULAR_USER' | 'SERVICE_USER';
+    active?: boolean;
+    roles?: { id: string, name: string, type: string }[];
+    oauthClientId?: string; // For Service Users
 }
 
 export class UserResource {
@@ -17,16 +22,47 @@ export class UserResource {
     }
 
     async get(id: string): Promise<User> {
-        return this.client.request({
+        return this.client.request<User>({
             method: 'GET',
             url: `/user/${encodeURIComponent(id)}`
         });
     }
 
     async getByName(name: string): Promise<User> {
-        return this.client.request({
+        return this.client.request<User>({
             method: 'GET',
             url: `/user/by-name/${encodeURIComponent(name)}`
         });
     }
+
+    /**
+     * Create a new user (Regular or Service).
+     * @param user User definition. For Service Users, set identityType to 'SERVICE_USER'.
+     */
+    async create(user: Partial<User>): Promise<User> {
+        return this.client.request<User>({
+            method: 'POST',
+            url: '/user',
+            data: user
+        });
+    }
+
+    async update(id: string, user: Partial<User>): Promise<User> {
+        return this.client.request<User>({
+            method: 'PUT',
+            url: `/user/${encodeURIComponent(id)}`,
+            data: user
+        });
+    }
+
+    async delete(id: string, versionTag?: string): Promise<void> {
+        const config: any = {
+            method: 'DELETE',
+            url: `/user/${encodeURIComponent(id)}`
+        };
+        if (versionTag) {
+            config.params = { version: versionTag };
+        }
+        await this.client.request(config);
+    }
 }

package/src/client/base.ts

@@ -5,6 +5,13 @@ import { JobResource } from '../api/jobs';
 import { ReflectionResource } from '../api/reflection';
 import { SourceResource } from '../api/source';
 import { UserResource } from '../api/user';
+import { GovernanceResource } from '../api/governance';
+import { CollaborationResource } from '../api/collaboration';
+import { ScriptsResource } from '../api/scripts';
+import { LineageResource } from '../api/lineage';
+import { ProvisioningResource } from '../api/provisioning';
+import { TokenResource } from '../api/token';
+import { CredentialsResource } from '../api/credentials';
 
 export abstract class BaseClient {
     protected axiosInstance: AxiosInstance;
@@ -14,6 +21,13 @@ export abstract class BaseClient {
     public reflections: ReflectionResource;
     public sources: SourceResource;
     public users: UserResource;
+    public governance: GovernanceResource;
+    public collaboration: CollaborationResource;
+    public scripts: ScriptsResource;
+    public lineage: LineageResource;
+    public provisioning: ProvisioningResource;
+    public tokens: TokenResource;
+    public credentials: CredentialsResource;
 
     constructor(config: BaseDremioConfig) {
         this.config = config;
@@ -30,6 +44,13 @@ export abstract class BaseClient {
         this.reflections = new ReflectionResource(this);
         this.sources = new SourceResource(this);
         this.users = new UserResource(this);
+        this.governance = new GovernanceResource(this);
+        this.collaboration = new CollaborationResource(this);
+        this.scripts = new ScriptsResource(this);
+        this.lineage = new LineageResource(this);
+        this.provisioning = new ProvisioningResource(this);
+        this.tokens = new TokenResource(this);
+        this.credentials = new CredentialsResource(this);
 
         // Add generic interceptors if needed
         this.axiosInstance.interceptors.response.use(
@@ -41,6 +62,10 @@ export abstract class BaseClient {
         );
     }
 
+    public getConfig(): BaseDremioConfig {
+        return this.config;
+    }
+
     protected abstract getAuthHeaders(): Record<string, string> | Promise<Record<string, string>>;
 
     public async request<T = any>(config: AxiosRequestConfig): Promise<T> {

package/src/client/cloud.ts

@@ -1,18 +1,25 @@
 import { BaseClient } from './base';
 import { DremioCloudConfig } from '../types/config';
+import axios from 'axios';
 
 export class DremioCloudClient extends BaseClient {
     protected config: DremioCloudConfig;
+    private sessionToken: string | null = null;
 
     constructor(config: DremioCloudConfig) {
-        if (!config.authToken) {
-            throw new Error('Auth token is required for Dremio Cloud.');
-        }
+        // Validation: Must have Project ID, and EITHER authToken OR auth.type='pat'
         if (!config.projectId) {
             throw new Error('Project ID is required for Dremio Cloud.');
         }
+        const hasLegacyToken = !!config.authToken;
+        const hasAuthObj = config.auth && config.auth.type === 'pat';
+        
+        if (!hasLegacyToken && !hasAuthObj) {
+            throw new Error('Auth token (PAT) is required for Dremio Cloud.');
+        }
 
         // Adjust BaseUrl to include project context
+        // We do this for the main axios instance, but we keep original config for login
         const configWithProject = { ...config };
         if (!configWithProject.baseUrl.includes('/projects/')) {
             // Remove trailing slash if present
@@ -24,14 +31,53 @@ export class DremioCloudClient extends BaseClient {
         this.config = config;
     }
 
-    protected getAuthHeaders(): Record<string, string> {
+    protected async getAuthHeaders(): Promise<Record<string, string>> {
+        if (!this.sessionToken) {
+            await this.login();
+        }
         return {
-            Authorization: `Bearer ${this.config.authToken}`,
+            Authorization: `Bearer ${this.sessionToken}`,
         };
     }
 
+    private async login(): Promise<void> {
+        const pat = this.config.auth?.type === 'pat' ? this.config.auth.token : this.config.authToken;
+        
+        if (!pat) {
+            throw new Error('No PAT available for login.');
+        }
+
+        // Try to exchange PAT for Session Token
+        try {
+            // Original Base URL (e.g. https://api.dremio.cloud/v0)
+            const cleanBase = this.config.baseUrl.replace(/\/$/, '');
+            const loginUrl = `${cleanBase}/login`;
+
+            const response = await axios.post(loginUrl, { token: pat }, {
+                headers: { 'Content-Type': 'application/json' },
+                timeout: this.config.timeout || 10000
+            });
+
+            if (response.data && response.data.token) {
+                this.sessionToken = response.data.token;
+            } else {
+                // Unexpected response structure
+                console.warn('Login response did not contain token, falling back to PAT/Legacy mode.');
+                this.sessionToken = pat;
+            }
+        } catch (error) {
+            console.warn('PAT Exchange failed, falling back to raw PAT usage. Error:', (error as any).message);
+            // Fallback to using PAT directly
+            this.sessionToken = pat;
+        }
+    }
+
     // Cloud specific methods can go here or generic methods can use projectId from config
     getProjectId(): string {
         return this.config.projectId;
     }
+
+    public getConfig(): DremioCloudConfig {
+        return this.config;
+    }
 }