@contrail/cli 3.3.3 → 3.5.0-alpha

package/dist/helpers/entities/items.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.throwIfInvalidItemLevel = exports.Roles = exports.getFamilyName = exports.getItemFamilies = exports.getManyItems = exports.getAllItemsUsingCacheFallback = exports.throwIfInvalidItemId = void 0;
+const sdk_1 = require("@contrail/sdk");
+async function throwIfInvalidItemId(itemId) {
+    if (!(await doesItemExistById(itemId))) {
+        throw new Error(`Item with ID ${itemId} does not exist`);
+    }
+}
+exports.throwIfInvalidItemId = throwIfInvalidItemId;
+async function doesItemExistById(id) {
+    const client = new sdk_1.Entities();
+    const item = await client.get({ entityName: 'item', id });
+    return !!item;
+}
+const ITEMS_CACHE_BY_ID = new Map();
+async function getAllItemsUsingCacheFallback() {
+    if (ITEMS_CACHE_BY_ID.size > 0) {
+        return Array.from(ITEMS_CACHE_BY_ID.values());
+    }
+    const items = await getManyItems();
+    items.forEach((item) => {
+        ITEMS_CACHE_BY_ID.set(item.id, item);
+    });
+    return items;
+}
+exports.getAllItemsUsingCacheFallback = getAllItemsUsingCacheFallback;
+async function getManyItems(maxCount = 10000) {
+    const client = new sdk_1.Entities();
+    // paginate to get all items
+    // Note: This will only return the first 100 assortments by default.
+    const items = [];
+    let nextPageKey = undefined;
+    while (true) {
+        const response = await client.get({
+            entityName: 'item',
+            apiVersion: sdk_1.API_VERSION.V2,
+            //      customParams: { propertySlugs: 'id,familyId,roles,name' }, // not compatible with V2 for some reason
+            nextPageKey,
+        });
+        nextPageKey = response.nextPageKey;
+        if (response.results.length === 0) {
+            break; // No more assortments to fetch
+        }
+        items.push(...response.results);
+        if (items.length >= maxCount) {
+            console.warn(`Reached maximum item limit of ${maxCount}. Some items may not be included.`);
+            break; // Stop if we reach the maximum limit
+        }
+    }
+    return items;
+}
+exports.getManyItems = getManyItems;
+async function getItemFamilies(count) {
+    return getItems({ roles: ['family'] }, count);
+}
+exports.getItemFamilies = getItemFamilies;
+async function getFamilyName(item) {
+    if (!item.roles.includes('option')) {
+        return undefined;
+    }
+    if (!item.familyId) {
+        return undefined;
+    }
+    await ensureItemCacheIsPopulated();
+    const family = ITEMS_CACHE_BY_ID.get(item.familyId);
+    return family ? [family.name] : ['placeholder']; // placeholder if family not found
+}
+exports.getFamilyName = getFamilyName;
+async function ensureItemCacheIsPopulated() {
+    if (ITEMS_CACHE_BY_ID.size === 0) {
+        await getAllItemsUsingCacheFallback();
+    }
+}
+exports.Roles = ['option', 'family'];
+function throwIfInvalidItemLevel(role) {
+    if (!exports.Roles.includes(role)) {
+        throw new Error(`Invalid role: ${role}. Valid roles are: ${exports.Roles.join(', ')}`);
+    }
+}
+exports.throwIfInvalidItemLevel = throwIfInvalidItemLevel;
+async function getItems(criteria, count = 100) {
+    const client = new sdk_1.Entities();
+    const items = [];
+    let nextPageKey = undefined;
+    do {
+        const response = await client.get({
+            entityName: 'item',
+            criteria,
+            nextPageKey,
+            apiVersion: sdk_1.API_VERSION.V2,
+        });
+        nextPageKey = response.nextPageKey;
+        if (response.results.length === 0) {
+            break; // No more items to fetch
+        }
+        const numItemsCanBeAdded = count - items.length;
+        const itemsToAdd = response.results.slice(0, numItemsCanBeAdded);
+        items.push(...itemsToAdd);
+    } while (nextPageKey && items.length < count);
+    return items;
+}

package/dist/helpers/entities/project-items.d.ts

@@ -0,0 +1,3 @@
+import { Item } from '@contrail/entity-types';
+export declare function throwIfInvalidProjectId(projectId: string): Promise<void>;
+export declare function findItemsNotInProject(projectId: string): Promise<Item[]>;

package/dist/helpers/entities/project-items.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findItemsNotInProject = exports.throwIfInvalidProjectId = void 0;
+const sdk_1 = require("@contrail/sdk");
+const batchFetch_1 = require("./batchFetch");
+const items_1 = require("./items");
+const PROJECT_ITEMS_CACHE_BY_PROJECT_ID = new Map();
+const PROJECT_ITEMS_CACHE_BY_ITEM_ID = new Map();
+async function throwIfInvalidProjectId(projectId) {
+    if (!(await doesProjectExistById(projectId))) {
+        throw new Error(`Project with ID ${projectId} does not exist`);
+    }
+}
+exports.throwIfInvalidProjectId = throwIfInvalidProjectId;
+async function doesProjectExistById(id) {
+    const client = new sdk_1.Entities();
+    const project = await client
+        .get({
+        entityName: 'project',
+        id,
+        customParams: { propertySlugs: 'id' },
+    })
+        .catch((e) => {
+        console.error(e);
+        return null; // Return null if project does not exist
+    });
+    return !!project;
+}
+async function cacheProjectItemsByProjectId(projectId) {
+    if (PROJECT_ITEMS_CACHE_BY_PROJECT_ID.has(projectId)) {
+        return; // Already cached
+    }
+    const projectItems = await (0, batchFetch_1.batchFetch)('project-item', {
+        criteria: { projectId },
+        customParams: { propertySlugs: 'id,projectId,assortmentId' },
+    });
+    PROJECT_ITEMS_CACHE_BY_PROJECT_ID.set(projectId, projectItems);
+    projectItems.forEach((item) => {
+        if (!PROJECT_ITEMS_CACHE_BY_ITEM_ID.has(item.itemId)) {
+            PROJECT_ITEMS_CACHE_BY_ITEM_ID.set(item.itemId, []);
+        }
+        PROJECT_ITEMS_CACHE_BY_ITEM_ID.get(item.itemId).push(item);
+    });
+}
+async function getProjectItemsByProjectId(projectId) {
+    await cacheProjectItemsByProjectId(projectId);
+    const projectItems = PROJECT_ITEMS_CACHE_BY_PROJECT_ID.get(projectId);
+    if (!projectItems) {
+        throw new Error(`No project items found for project ID ${projectId}`);
+    }
+    return projectItems;
+}
+async function findItemsNotInProject(projectId) {
+    const [projectItemsInProject, allItems] = await Promise.all([
+        getProjectItemsByProjectId(projectId),
+        (0, items_1.getManyItems)(),
+    ]);
+    const projectItemIds = new Set(projectItemsInProject.map((item) => item.itemId));
+    const itemsNotInProject = allItems.filter((item) => !projectItemIds.has(item.id));
+    if (itemsNotInProject.length === 0) {
+        throw new Error(`All items are already in project ${projectId}`);
+    }
+    return itemsNotInProject.sort((a, b) => a.id.localeCompare(b.id)); // sorting ensures consistent order of response
+}
+exports.findItemsNotInProject = findItemsNotInProject;

package/dist/helpers/file-helpers.d.ts

@@ -1,2 +1,3 @@
 export declare function safeFileOverwrite(fileLocation: string, overwrite: boolean): Promise<boolean>;
 export declare function parseCSVData(data: string): any;
+export declare function parseFileAsJsonArray(fileName: string): any[];

package/dist/helpers/file-helpers.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseCSVData = exports.safeFileOverwrite = void 0;
+exports.parseFileAsJsonArray = exports.parseCSVData = exports.safeFileOverwrite = void 0;
 const tslib_1 = require("tslib");
+const fs_1 = tslib_1.__importDefault(require("fs"));
 const inquirer_1 = tslib_1.__importDefault(require("inquirer"));
 const logger_1 = tslib_1.__importDefault(require("../logger"));
 const sync_1 = require("csv-parse/sync");
@@ -34,3 +35,20 @@ function parseCSVData(data) {
     });
 }
 exports.parseCSVData = parseCSVData;
+function parseFileAsJsonArray(fileName) {
+    if (!fs_1.default.existsSync(fileName)) {
+        throw new Error(`File not found: ${fileName}`);
+    }
+    const fileContent = fs_1.default.readFileSync(fileName, 'utf-8');
+    try {
+        const jsonArray = JSON.parse(fileContent);
+        if (!Array.isArray(jsonArray)) {
+            throw new Error(`File content is not a valid JSON array: ${fileName}`);
+        }
+        return jsonArray;
+    }
+    catch (error) {
+        throw new Error(`Error parsing JSON from file ${fileName}: ${error.message}`);
+    }
+}
+exports.parseFileAsJsonArray = parseFileAsJsonArray;

package/dist/helpers/propertySpecifications/dateRanges.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Date Range Parsing Utilities
+ *
+ * Handles parsing date range syntax like:
+ * - createdOn=2025-09-15..2025-09-16 (date range)
+ * - createdOn=2025-09-15T04:00:00Z..2025-09-16T03:59:59Z (timestamp range)
+ * - createdOn=2025-09-15.. (from date onwards)
+ * - createdOn=..2025-09-16 (until date)
+ */
+export type DateRange = {
+    start?: Date;
+    end?: Date;
+};
+export type DateRangeSpecification = {
+    slug: string;
+    range: DateRange;
+};
+/**
+ * Checks if a property specification contains date range syntax (..)
+ */
+export declare function isDateRangeSpecification(spec: string): boolean;
+/**
+ * Parses a date range specification into its components
+ * @param spec - The specification string (e.g., "createdOn=2025-09-15..2025-09-16")
+ */
+export declare function parseDateRangeSpecification(spec: string): DateRangeSpecification;
+/**
+ * Parses a date string, handling both date-only and full timestamp formats
+ * @param dateStr - Date string (e.g., "2025-09-15" or "2025-09-15T04:00:00Z")
+ * @param boundType - Whether this is the 'start' or 'end' of a range (affects date-only handling)
+ */
+export declare function parseDate(dateStr: string, boundType?: 'start' | 'end'): Date;
+/**
+ * Converts a date range to JSURL BETWEEN format
+ * @param range - The date range object
+ * @param isEndOfRange - Whether this date represents the end of a range (affects date-only handling)
+ */
+export declare function convertDateRangeToJSURL(range: DateRange): string;

package/dist/helpers/propertySpecifications/dateRanges.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Date Range Parsing Utilities
+ *
+ * Handles parsing date range syntax like:
+ * - createdOn=2025-09-15..2025-09-16 (date range)
+ * - createdOn=2025-09-15T04:00:00Z..2025-09-16T03:59:59Z (timestamp range)
+ * - createdOn=2025-09-15.. (from date onwards)
+ * - createdOn=..2025-09-16 (until date)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertDateRangeToJSURL = exports.parseDate = exports.parseDateRangeSpecification = exports.isDateRangeSpecification = void 0;
+/**
+ * Checks if a property specification contains date range syntax (..)
+ */
+function isDateRangeSpecification(spec) {
+    return spec.includes('=') && spec.includes('..');
+}
+exports.isDateRangeSpecification = isDateRangeSpecification;
+/**
+ * Parses a date range specification into its components
+ * @param spec - The specification string (e.g., "createdOn=2025-09-15..2025-09-16")
+ */
+function parseDateRangeSpecification(spec) {
+    const equalsIndex = spec.indexOf('=');
+    if (equalsIndex === -1) {
+        throw new Error(`Invalid date range specification: ${spec}`);
+    }
+    const slug = spec.substring(0, equalsIndex);
+    const rangeValue = spec.substring(equalsIndex + 1);
+    if (!slug || !rangeValue || !rangeValue.includes('..')) {
+        throw new Error(`Invalid date range specification: ${spec}`);
+    }
+    const [startStr, endStr] = rangeValue.split('..');
+    const range = {
+        start: startStr.trim() ? parseDate(startStr.trim(), 'start') : undefined,
+        end: endStr.trim() ? parseDate(endStr.trim(), 'end') : undefined,
+    };
+    // At least one bound must be specified
+    if (!range.start && !range.end) {
+        throw new Error(`Date range must have at least one bound: ${spec}`);
+    }
+    return { slug, range };
+}
+exports.parseDateRangeSpecification = parseDateRangeSpecification;
+/**
+ * Parses a date string, handling both date-only and full timestamp formats
+ * @param dateStr - Date string (e.g., "2025-09-15" or "2025-09-15T04:00:00Z")
+ * @param boundType - Whether this is the 'start' or 'end' of a range (affects date-only handling)
+ */
+function parseDate(dateStr, boundType = 'start') {
+    if (!dateStr.includes('T')) {
+        if (boundType === 'start') {
+            dateStr = `${dateStr}T00:00:00.000Z`;
+        }
+        else {
+            dateStr = `${dateStr}T23:59:59.999Z`;
+        }
+    }
+    const date = new Date(dateStr);
+    if (isNaN(date.getTime())) {
+        throw new Error(`Invalid date format: ${dateStr}`);
+    }
+    return date;
+}
+exports.parseDate = parseDate;
+/**
+ * Converts a date range to JSURL BETWEEN format
+ * @param range - The date range object
+ * @param isEndOfRange - Whether this date represents the end of a range (affects date-only handling)
+ */
+function convertDateRangeToJSURL(range) {
+    if (!range.start && !range.end) {
+        throw new Error('Date range must have at least one bound');
+    }
+    if (range.start && range.end) {
+        const startISO = range.start.toISOString();
+        const endISO = range.end.toISOString();
+        return `BETWEEN ${startISO} and ${endISO}`;
+    }
+    else if (range.start) {
+        return `>= ${range.start.toISOString()}`;
+    }
+    else {
+        const endISO = range.end.toISOString();
+        return `<= ${endISO}`;
+    }
+}
+exports.convertDateRangeToJSURL = convertDateRangeToJSURL;

package/dist/helpers/propertySpecifications/dateRanges.spec.d.ts

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

package/dist/helpers/propertySpecifications/dateRanges.spec.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const dateRanges_1 = require("./dateRanges");
+describe('Date Range Specifications', () => {
+    describe('isDateRangeSpecification', () => {
+        it('should identify valid date range specifications', () => {
+            expect((0, dateRanges_1.isDateRangeSpecification)('createdOn=2025-09-15..2025-09-16')).toBe(true);
+            expect((0, dateRanges_1.isDateRangeSpecification)('updatedAt=2025-09-15T04:00:00Z..2025-09-16T03:59:59Z')).toBe(true);
+            expect((0, dateRanges_1.isDateRangeSpecification)('date=2025-09-15..')).toBe(true);
+            expect((0, dateRanges_1.isDateRangeSpecification)('date=..2025-09-16')).toBe(true);
+        });
+        it('should reject non-date-range specifications', () => {
+            expect((0, dateRanges_1.isDateRangeSpecification)('id=123')).toBe(false);
+            expect((0, dateRanges_1.isDateRangeSpecification)('name=test')).toBe(false);
+            expect((0, dateRanges_1.isDateRangeSpecification)('invalid')).toBe(false);
+            expect((0, dateRanges_1.isDateRangeSpecification)('field=value')).toBe(false);
+        });
+    });
+    describe('parseDate', () => {
+        it('should parse ISO timestamps correctly', () => {
+            const date = (0, dateRanges_1.parseDate)('2025-09-15T04:00:00Z');
+            expect(date.toISOString()).toBe('2025-09-15T04:00:00.000Z');
+        });
+        it('should parse date-only strings as start of day', () => {
+            const date = (0, dateRanges_1.parseDate)('2025-09-15', 'start');
+            expect(date.toISOString()).toBe('2025-09-15T00:00:00.000Z');
+        });
+        it('should parse date-only strings as end of day for end bound', () => {
+            const date = (0, dateRanges_1.parseDate)('2025-09-15', 'end');
+            expect(date.toISOString()).toBe('2025-09-15T23:59:59.999Z');
+        });
+        it('should throw for invalid date strings', () => {
+            expect(() => (0, dateRanges_1.parseDate)('invalid-date')).toThrow('Invalid date format');
+            expect(() => (0, dateRanges_1.parseDate)('2025-13-50')).toThrow('Invalid date format');
+        });
+    });
+    describe('parseDateRangeSpecification', () => {
+        it('should parse full date ranges', () => {
+            const result = (0, dateRanges_1.parseDateRangeSpecification)('createdOn=2025-09-15..2025-09-16');
+            expect(result.slug).toBe('createdOn');
+            expect(result.range.start).toEqual(new Date('2025-09-15T00:00:00.000Z'));
+            expect(result.range.end).toEqual(new Date('2025-09-16T23:59:59.999Z'));
+        });
+        it('should parse open-ended start ranges', () => {
+            const result = (0, dateRanges_1.parseDateRangeSpecification)('createdOn=2025-09-15..');
+            expect(result.slug).toBe('createdOn');
+            expect(result.range.start).toEqual(new Date('2025-09-15T00:00:00.000Z'));
+            expect(result.range.end).toBeUndefined();
+        });
+        it('should parse open-ended end ranges', () => {
+            const result = (0, dateRanges_1.parseDateRangeSpecification)('createdOn=..2025-09-16');
+            expect(result.slug).toBe('createdOn');
+            expect(result.range.start).toBeUndefined();
+            expect(result.range.end).toEqual(new Date('2025-09-16T23:59:59.999Z'));
+        });
+        it('should parse timestamp ranges', () => {
+            const result = (0, dateRanges_1.parseDateRangeSpecification)('createdOn=2025-09-15T04:00:00Z..2025-09-16T03:59:59Z');
+            expect(result.slug).toBe('createdOn');
+            expect(result.range.start).toEqual(new Date('2025-09-15T04:00:00.000Z'));
+            expect(result.range.end).toEqual(new Date('2025-09-16T03:59:59.000Z'));
+        });
+        it('should throw for invalid specifications', () => {
+            expect(() => (0, dateRanges_1.parseDateRangeSpecification)('invalid')).toThrow('Invalid date range specification');
+            expect(() => (0, dateRanges_1.parseDateRangeSpecification)('field=..')).toThrow('Date range must have at least one bound');
+            expect(() => (0, dateRanges_1.parseDateRangeSpecification)('field=invalid..date')).toThrow('Invalid date format');
+        });
+    });
+    describe('convertDateRangeToJSURL', () => {
+        it('should convert full ranges to BETWEEN format', () => {
+            const range = {
+                start: new Date('2025-09-15T00:00:00.000Z'),
+                end: new Date('2025-09-16T23:59:59.999Z'),
+            };
+            const result = (0, dateRanges_1.convertDateRangeToJSURL)(range);
+            expect(result).toBe('BETWEEN 2025-09-15T00:00:00.000Z and 2025-09-16T23:59:59.999Z');
+        });
+        it('should convert start-only ranges to >= format', () => {
+            const range = {
+                start: new Date('2025-09-15T00:00:00.000Z'),
+            };
+            const result = (0, dateRanges_1.convertDateRangeToJSURL)(range);
+            expect(result).toBe('>= 2025-09-15T00:00:00.000Z');
+        });
+        it('should convert end-only ranges to <= format', () => {
+            const range = {
+                end: new Date('2025-09-16T23:59:59.999Z'),
+            };
+            const result = (0, dateRanges_1.convertDateRangeToJSURL)(range);
+            expect(result).toBe('<= 2025-09-16T23:59:59.999Z');
+        });
+        it('should throw for empty ranges', () => {
+            expect(() => (0, dateRanges_1.convertDateRangeToJSURL)({})).toThrow('Date range must have at least one bound');
+        });
+    });
+});

package/dist/helpers/propertySpecifications/propertySpecifications.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Property Specification
+ *
+ * Property Specifications is an argument pattern used to express that
+ * a specific property has a specific value. In GET requests, this is used
+ * to specify the query parameters. In PUT requests, this is used to
+ * specify the properties to update.
+ *
+ * Each follows the format: slug=value
+ *
+ * It is typically used as the argv in a command.
+ *
+ * Examples:
+ *
+ * contrail entities get color -- id=123
+ * contrail entities update color 123 -- name=obsidian hex=000000
+ * contrail entities get loader-processes -- createdOn=2025-09-15..2025-09-16
+ */
+export type PropertySpecification = {
+    slug: string;
+    value: string;
+};
+export type PropertySpecificationBySlug = Map<string, string | number | string[] | number[]>;
+export type PropertySpecificationString = `${string}=${string}`;
+export declare function parsePropertySpecification(spec: PropertySpecificationString): PropertySpecification;
+export declare function parsePropertySpecificationsIntoMap(propertySpecifications: PropertySpecificationString[]): PropertySpecificationBySlug;
+export declare function isValidPropertySpecification(maybeSpec: string): maybeSpec is PropertySpecificationString;

package/dist/helpers/propertySpecifications/propertySpecifications.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Property Specification
+ *
+ * Property Specifications is an argument pattern used to express that
+ * a specific property has a specific value. In GET requests, this is used
+ * to specify the query parameters. In PUT requests, this is used to
+ * specify the properties to update.
+ *
+ * Each follows the format: slug=value
+ *
+ * It is typically used as the argv in a command.
+ *
+ * Examples:
+ *
+ * contrail entities get color -- id=123
+ * contrail entities update color 123 -- name=obsidian hex=000000
+ * contrail entities get loader-processes -- createdOn=2025-09-15..2025-09-16
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidPropertySpecification = exports.parsePropertySpecificationsIntoMap = exports.parsePropertySpecification = void 0;
+const dateRanges_1 = require("./dateRanges");
+function parsePropertySpecification(spec) {
+    const equalsIndex = spec.indexOf('=');
+    if (equalsIndex === -1) {
+        throw new Error(`Invalid property specification: ${spec}`);
+    }
+    const slug = spec.substring(0, equalsIndex);
+    const value = spec.substring(equalsIndex + 1);
+    if (!slug || !value) {
+        throw new Error(`Invalid property specification: ${spec}`);
+    }
+    return { slug, value };
+}
+exports.parsePropertySpecification = parsePropertySpecification;
+function parsePropertySpecificationsIntoMap(propertySpecifications) {
+    const propertySpecBySlug = new Map();
+    for (const spec of propertySpecifications) {
+        if ((0, dateRanges_1.isDateRangeSpecification)(spec)) {
+            const { slug, range } = (0, dateRanges_1.parseDateRangeSpecification)(spec);
+            const jsUrlValue = (0, dateRanges_1.convertDateRangeToJSURL)(range);
+            propertySpecBySlug.set(slug, jsUrlValue);
+            continue;
+        }
+        const { slug, value } = parsePropertySpecification(spec);
+        if (slug === 'roles') {
+            // Special handling for roles, which can be an array
+            const rolesArray = value.split(',').map((role) => role.trim());
+            propertySpecBySlug.set(slug, rolesArray);
+            continue;
+        }
+        propertySpecBySlug.set(slug, value);
+    }
+    return propertySpecBySlug;
+}
+exports.parsePropertySpecificationsIntoMap = parsePropertySpecificationsIntoMap;
+function isValidPropertySpecification(maybeSpec) {
+    try {
+        if ((0, dateRanges_1.isDateRangeSpecification)(maybeSpec)) {
+            (0, dateRanges_1.parseDateRangeSpecification)(maybeSpec);
+            return true;
+        }
+        const { slug, value } = parsePropertySpecification(maybeSpec);
+        return !!slug && !!value;
+    }
+    catch (e) {
+        return false;
+    }
+}
+exports.isValidPropertySpecification = isValidPropertySpecification;

package/dist/helpers/propertySpecifications/propertySpecifications.spec.d.ts

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