@narrative.io/data-collaboration-sdk-ts 0.0.31 → 0.0.33

package/build/attributes/types.d.ts

@@ -1,19 +1,32 @@
-export interface Attribute {
+export type Attribute = PrimitiveAttribute | ArrayAttribute | ObjectAttribute;
+interface BaseAttribute {
     id: number;
     name: string;
+    display_name?: string;
     description?: string;
-    display_name: string;
     type: string;
-    enum?: string[] | number[];
     validations?: string[];
+}
+interface PrimitiveAttribute extends BaseAttribute {
+    type: 'string' | 'boolean' | 'double' | 'long' | 'timestamptz';
+    enum?: string[] | number[] | boolean[];
+    is_join_key?: boolean;
+}
+type SubAttribute = Partial<Omit<Attribute, 'name' | 'id'>> & {
+    type: string;
+    enum?: string[] | number[] | boolean[];
     is_join_key?: boolean;
-    properties?: Record<string, {
-        type: string;
-        description?: string;
-        validations?: string[];
-        enum?: string[];
-        items?: unknown;
-        is_join_key?: boolean;
-    }>;
+};
+interface RefAttribute {
+    $ref: number;
+}
+interface ArrayAttribute extends BaseAttribute {
+    type: 'array';
+    items: SubAttribute;
+}
+interface ObjectAttribute extends BaseAttribute {
+    type: 'object';
+    properties: Record<string, SubAttribute | RefAttribute>;
     required?: string[];
 }
+export {};

package/build/base-api.d.ts

@@ -1,3 +1,4 @@
+import { type MandeInstance } from 'mande';
 import { type Config } from './types';
 /**
  * BaseApi class provides basic functionality for making API requests.
@@ -6,12 +7,37 @@ export declare abstract class BaseApi {
     private readonly apiKey?;
     private readonly environment;
     private readonly base_api;
+    private readonly headers;
     /**
        * @param {Config} config - Configuration object.
        * @param {string} [config.apiKey] - API key.
        * @param {Environment} [config.environment='prod'] - Environment for the API (e.g. 'dev', 'prod').
        */
     constructor(config: Config);
+    /**
+     * Retrieves the headers associated with the API instance.
+     *
+     * @returns An object containing key-value pairs representing the headers.
+     */
+    getHeaders(): Record<string, string>;
+    /**
+       * Retrieves the base API instance created using Mande.
+       *
+       * @returns A MandeInstance object representing the base API instance.
+       */
+    getBaseApi(): MandeInstance;
+    /**
+       * Retrieves the API key associated with the API instance, if it exists.
+       *
+       * @returns The API key as a string if it is set, or undefined if not set.
+       */
+    getApiKey(): string | undefined;
+    /**
+       * Retrieves the environment associated with the API instance.
+       *
+       * @returns A string representing the environment (e.g., 'dev', 'prod').
+       */
+    getEnvironment(): string;
     /**
        * Makes a GET request to the given endpoint.
        *
@@ -52,12 +78,12 @@ export declare abstract class BaseApi {
       * @returns {string} - Base URL for the API.
       * @private
       */
-    private getBaseUrl;
+    getBaseUrl(): string;
     /**
        * Returns the headers for the API request.
        *
        * @returns {Object.<string, string>} - Headers for the API request.
        * @private
        */
-    private getHeaders;
+    private constructHeaders;
 }

package/build/base-api.js

@@ -6,6 +6,7 @@ export class BaseApi {
     apiKey;
     environment;
     base_api;
+    headers;
     /**
        * @param {Config} config - Configuration object.
        * @param {string} [config.apiKey] - API key.
@@ -14,10 +15,43 @@ export class BaseApi {
     constructor(config) {
         this.apiKey = config.apiKey;
         this.environment = config.environment ?? 'prod';
+        this.headers = config.headers ?? {};
         this.base_api = mande(`${this.getBaseUrl()}`, {
-            headers: this.getHeaders()
+            headers: this.constructHeaders()
         });
     }
+    /**
+     * Retrieves the headers associated with the API instance.
+     *
+     * @returns An object containing key-value pairs representing the headers.
+     */
+    getHeaders() {
+        return this.constructHeaders();
+    }
+    /**
+       * Retrieves the base API instance created using Mande.
+       *
+       * @returns A MandeInstance object representing the base API instance.
+       */
+    getBaseApi() {
+        return this.base_api;
+    }
+    /**
+       * Retrieves the API key associated with the API instance, if it exists.
+       *
+       * @returns The API key as a string if it is set, or undefined if not set.
+       */
+    getApiKey() {
+        return this.apiKey;
+    }
+    /**
+       * Retrieves the environment associated with the API instance.
+       *
+       * @returns A string representing the environment (e.g., 'dev', 'prod').
+       */
+    getEnvironment() {
+        return this.environment;
+    }
     /**
        * Makes a GET request to the given endpoint.
        *
@@ -85,11 +119,12 @@ export class BaseApi {
        * @returns {Object.<string, string>} - Headers for the API request.
        * @private
        */
-    getHeaders() {
+    constructHeaders() {
         const headers = {
-            'Content-type': 'application/json'
+            ...this.headers,
+            'Content-Type': this.headers['Content-Type'] ?? 'application/json'
         };
-        if (this.apiKey != null) {
+        if (!('Authorization' in headers) && (this.apiKey != null)) {
             headers.Authorization = `Bearer ${this.apiKey}`;
         }
         return headers;

package/build/datasets/index.d.ts

@@ -1,6 +1,7 @@
 import { type ApiRecords } from '../types';
 import { BaseApi } from '../base-api';
-import { type Dataset, type DatasetTableSummaryAPIResponse } from './types';
+import { type FilePerSnapshotResponse, type Dataset, type DatasetTableSummaryAPIResponse } from './types';
+export { type FilePerSnapshotResponse, type Dataset, type DatasetTableSummaryAPIResponse };
 /**
  * @module DatasetApi
  * @description This module provides methods for fetching datasets.
@@ -42,4 +43,32 @@ export declare class DatasetApi extends BaseApi {
     const records = await getDatasetSample(datasetId, size);
     */
     getDatasetSample(datasetId: number, size?: number): Promise<ApiRecords<Record<string, string>>>;
+    /**
+     * Fetches a list of dataset files based on the provided parameters.
+     *
+     * @param {number} datasetId - The ID of the dataset to fetch files for.
+     * @param {number} [size] - The number of snapshots to return. Optional.
+     * @param {number} [offset] - The starting index of the file list. Optional.
+     * @param {string} [afterTimestamp] - Fetch files with a timestamp greater than or equal to the given value. Optional.
+     * @param {number} [fromSnapshotId] - Fetch files from the specified snapshot ID. Optional.
+     * @returns {Promise<FilePerSnapshotResponse>} A Promise that resolves with the fetched dataset files.
+     * @throws {Error} If there is an issue with the request or the response.
+     * @memberof DatasetApi
+     * @public
+   */
+    getDatasetFiles(datasetId: number, size?: number, offset?: number, afterTimestamp?: string, fromSnapshotId?: number): Promise<FilePerSnapshotResponse>;
+    /**
+     * Fetches the download URL for a specific dataset file.
+     *
+     * @param {number} datasetId - The ID of the dataset to fetch the file download URL for.
+     * @param {number} snapshotId - The ID of the snapshot the file is associated with.
+     * @param {string} fileId - The ID of the file to fetch the download URL for.
+     * @returns {Promise<{ download_url: string }>} A Promise that resolves with an object containing the download URL.
+     * @throws {Error} If there is an issue with the request or the response.
+     * @memberof DatasetApi
+     * @public
+     */
+    getDatasetFileDownloadUrl(datasetId: number, snapshotId: number, fileId: string): Promise<{
+        download_url: string;
+    }>;
 }

package/build/datasets/index.js

@@ -49,4 +49,43 @@ export class DatasetApi extends BaseApi {
     async getDatasetSample(datasetId, size = 1000) {
         return await this.get(`${resourceName}/${datasetId}/sample?size=${size}`);
     }
+    /**
+     * Fetches a list of dataset files based on the provided parameters.
+     *
+     * @param {number} datasetId - The ID of the dataset to fetch files for.
+     * @param {number} [size] - The number of snapshots to return. Optional.
+     * @param {number} [offset] - The starting index of the file list. Optional.
+     * @param {string} [afterTimestamp] - Fetch files with a timestamp greater than or equal to the given value. Optional.
+     * @param {number} [fromSnapshotId] - Fetch files from the specified snapshot ID. Optional.
+     * @returns {Promise<FilePerSnapshotResponse>} A Promise that resolves with the fetched dataset files.
+     * @throws {Error} If there is an issue with the request or the response.
+     * @memberof DatasetApi
+     * @public
+   */
+    async getDatasetFiles(datasetId, size, offset, afterTimestamp, fromSnapshotId) {
+        const params = new URLSearchParams();
+        if (size != null)
+            params.append('per_page', String(size));
+        if (offset != null)
+            params.append('offset', String(offset));
+        if (afterTimestamp != null)
+            params.append('timestamp.gte', afterTimestamp);
+        if (fromSnapshotId != null)
+            params.append('from_snapshot_id', String(fromSnapshotId));
+        return await this.get(`${resourceName}/${datasetId}/find-files?${params.toString()}`);
+    }
+    /**
+     * Fetches the download URL for a specific dataset file.
+     *
+     * @param {number} datasetId - The ID of the dataset to fetch the file download URL for.
+     * @param {number} snapshotId - The ID of the snapshot the file is associated with.
+     * @param {string} fileId - The ID of the file to fetch the download URL for.
+     * @returns {Promise<{ download_url: string }>} A Promise that resolves with an object containing the download URL.
+     * @throws {Error} If there is an issue with the request or the response.
+     * @memberof DatasetApi
+     * @public
+     */
+    async getDatasetFileDownloadUrl(datasetId, snapshotId, fileId) {
+        return await this.get(`${resourceName}/${datasetId}/snapshots/${snapshotId}/files-added/${fileId}/download`);
+    }
 }

package/build/datasets/types.d.ts

@@ -74,4 +74,18 @@ interface Schema {
     required: string[];
     primary: string;
 }
+interface File {
+    path: string;
+    size: number;
+}
+interface Snapshot {
+    files: File[];
+    snapshot_id: number;
+    timestamp: string;
+}
+export interface FilePerSnapshotResponse {
+    files_per_snapshot: Snapshot[];
+    has_next: boolean;
+    next_snapshot: number | null;
+}
 export {};

package/build/index.d.ts

@@ -3,7 +3,7 @@ import { DatasetApi } from './datasets';
 import { HealthCheckApi } from './health';
 import { RosettaStoneApi } from './rosetta-stone';
 import { type Environment, type Config, type ApiRecords, type MonetaryAmount } from './types';
-import { type DatasetTableSummaryAPIResponse, type Dataset, type DatasetTableSummary } from './datasets/types';
+import { type DatasetTableSummaryAPIResponse, type Dataset, type DatasetTableSummary, type FilePerSnapshotResponse } from './datasets/types';
 import { type HealthCheckResult } from './health/types';
 import { type SampleRecords } from './rosetta-stone/types';
 import { AttributeApi } from './attributes';
@@ -19,4 +19,4 @@ declare class NarrativeApi extends BaseApi {
 }
 interface NarrativeApi extends BaseApi, HealthCheckApi, DatasetApi, RosettaStoneApi, AttributeApi, PingApi, CompanyInfoApi, InstallationsApi, UploadsApi {
 }
-export { NarrativeApi, AttributeApi, HealthCheckApi, DatasetApi, PingApi, ProductsApi, CompanyInfoApi, InstallationsApi, UploadsApi, type UploadsResponse, type PingStatus, type Attribute, type Environment, type Config, type ApiRecords, type Dataset, type HealthCheckResult, type SampleRecords, type DatasetTableSummary, type DatasetTableSummaryAPIResponse, type Product, type MonetaryAmount, type CompanyInfo, type Installation };
+export { NarrativeApi, AttributeApi, HealthCheckApi, DatasetApi, PingApi, ProductsApi, CompanyInfoApi, InstallationsApi, UploadsApi, type UploadsResponse, type PingStatus, type Attribute, type Environment, type Config, type ApiRecords, type Dataset, type HealthCheckResult, type SampleRecords, type DatasetTableSummary, type DatasetTableSummaryAPIResponse, type Product, type MonetaryAmount, type CompanyInfo, type Installation, type FilePerSnapshotResponse };

package/build/nql/index.d.ts

@@ -0,0 +1,19 @@
+import { type Config } from 'src/types';
+import { BaseApi } from '../base-api';
+import { type NqlResult } from './types';
+/**
+ * A class for accessing the NQL API.
+ * @extends BaseApi
+ */
+declare class NqlApi extends BaseApi {
+    constructor(config: Config);
+    /**
+       * Executes an NQL query and returns the result.
+       *
+       * @param {string} token - The bearer token for authorization.
+       * @param {string} nqlQuery - The NQL query to execute.
+       * @returns {Promise<object>} A promise that resolves with the result of the NQL query.
+       */
+    executeNql(token: string, nqlQuery: string): Promise<object>;
+}
+export { NqlApi, type NqlResult };

package/build/nql/index.js

@@ -0,0 +1,35 @@
+import { BaseApi } from '../base-api';
+/**
+ * The name of the resource to be used in API requests.
+ * @constant
+ * @private
+ * @type {string}
+ */
+const resourceName = 'nql';
+/**
+ * A class for accessing the NQL API.
+ * @extends BaseApi
+ */
+class NqlApi extends BaseApi {
+    constructor(config) {
+        super({
+            ...config,
+            headers: {
+                ...config.headers,
+                'Content-Type': 'application/vnd.nql'
+            }
+        });
+    }
+    /**
+       * Executes an NQL query and returns the result.
+       *
+       * @param {string} token - The bearer token for authorization.
+       * @param {string} nqlQuery - The NQL query to execute.
+       * @returns {Promise<object>} A promise that resolves with the result of the NQL query.
+       */
+    async executeNql(token, nqlQuery) {
+        const response = await this.post(resourceName, nqlQuery);
+        return response;
+    }
+}
+export { NqlApi };

package/build/nql/types.d.ts

@@ -0,0 +1,28 @@
+export interface NqlResult {
+    id: string;
+    company_id: number;
+    completed_at: string;
+    created_at: string;
+    failures: any[];
+    idempotency_key: string;
+    input: {
+        nql: string;
+    };
+    request_source: {
+        type: string;
+        company_id: number;
+        user_id: number;
+    };
+    result: {
+        success: {
+            result: {
+                forecast: {
+                    rows: number;
+                    cost: number;
+                };
+            };
+        };
+    };
+    state: string;
+    updated_at: string;
+}

package/build/nql/types.js

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

package/build/types.d.ts

@@ -14,6 +14,7 @@ export type Environment = 'dev' | 'prod' | string;
 export interface Config {
     apiKey?: string;
     environment?: Environment;
+    headers?: Record<string, string>;
 }
 export interface ApiRecords<T> {
     records: T[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@narrative.io/data-collaboration-sdk-ts",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "main": "build/index.js",
   "repository": "github:narrative-io/data-collaboration-sdk-ts",
   "source": "src/index.ts",
@@ -9,13 +9,12 @@
   "scripts": {
     "build": "tsc",
     "lint": "npx eslint . --fix",
-    "prepare": "npx eslint . --fix && npm run build",
+    "prepare": "npx eslint . --fix && npm run build && husky install",
     "prepublishOnly": "npm test && npm run lint",
     "preversion": "npm run lint",
     "version": "npm run && git add -A src",
     "postversion": "git push && git push --tags",
-    "test": "jest",
-    "coverage": "jest --coverage"
+    "test": "jest --coverage"
   },
   "keywords": [],
   "author": "",
@@ -36,7 +35,8 @@
     "eslint-plugin-promise": "^6.1.1",
     "jest": "^29.4.3",
     "ts-jest": "^29.0.5",
-    "typescript": "^4.9.5"
+    "typescript": "^5.0.2",
+    "husky": "^8.0.0"
   },
   "dependencies": {
     "mande": "^2.0.3"