@contrail/cli 3.3.3 → 3.5.0-alpha

package/dist/commands/entities/get.d.ts

@@ -0,0 +1,20 @@
+import { BaseCommand } from '../../basecommand';
+export default class GetEntity extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        outputFile: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        skipHydrateRelationships: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        relations: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        propertySlugs: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        paginated: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        take: import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        alwaysConfirmEnv: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        logLevel: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+    };
+    static args: {
+        typePath: import("@oclif/core/lib/interfaces/parser").Arg<string, Record<string, unknown>>;
+    };
+    static strict: boolean;
+    run(): Promise<void>;
+}

package/dist/commands/entities/get.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const fs_1 = tslib_1.__importDefault(require("fs"));
+const core_1 = require("@oclif/core");
+const basecommand_1 = require("../../basecommand");
+const sdk_1 = require("@contrail/sdk");
+const login_1 = require("../../auth/login");
+const types_1 = require("../../api/types");
+const propertySpecifications_1 = require("../../helpers/propertySpecifications/propertySpecifications");
+let SHOULD_USE_PAGINATED_FIND = false;
+let MAX_NUMBER_OF_ENTITIES_TO_FETCH = 1000;
+class GetEntity extends basecommand_1.BaseCommand {
+    static description = '(BETA) Get an entity';
+    static examples = [
+        'contrail entities get color -- id=123',
+        'contrail entities get loader-processes -- createdOn=2025-09-15..2025-09-16',
+        'contrail entities get orders -- updatedAt=2025-09-15T04:00:00Z..',
+        'contrail entities get events -- timestamp=..2025-09-16T23:59:59Z',
+    ];
+    static flags = {
+        ...basecommand_1.BaseCommand.baseFlags,
+        outputFile: core_1.Flags.string({
+            char: 'o',
+            description: 'File to save the output (optional)',
+            required: false,
+        }),
+        skipHydrateRelationships: core_1.Flags.boolean({
+            char: 's',
+            description: 'Skip hydrating relationships when fetching the entity',
+            required: false,
+            default: false,
+        }),
+        relations: core_1.Flags.string({
+            char: 'r',
+            description: 'Comma-separated list of relations to include in the output',
+            required: false,
+        }),
+        propertySlugs: core_1.Flags.string({
+            char: 'p',
+            description: 'Comma-separated list of property slugs to include in the output',
+            required: false,
+        }),
+        paginated: core_1.Flags.boolean({
+            char: 'P',
+            description: 'If true, fetches all entities in a paginated manner',
+            required: false,
+            default: false,
+        }),
+        take: core_1.Flags.integer({
+            char: 't',
+            description: 'Number of entities to fetch in a single request (default is 100)',
+            required: false,
+            default: MAX_NUMBER_OF_ENTITIES_TO_FETCH,
+        }),
+    };
+    static args = {
+        typePath: core_1.Args.string({
+            description: 'The name of the entity type to fetch',
+            required: true,
+        }),
+    };
+    static strict = false;
+    async run() {
+        this.log('🚨 This command is in BETA and may change or be removed at any time.');
+        await (0, login_1.authUser)();
+        const { args, flags, argv } = await this.parse(GetEntity);
+        const { typePath } = args;
+        const { outputFile, propertySlugs, relations: relationString, skipHydrateRelationships, paginated: shouldUsePaginatedFind, take: numToTake, } = flags;
+        SHOULD_USE_PAGINATED_FIND = shouldUsePaginatedFind;
+        MAX_NUMBER_OF_ENTITIES_TO_FETCH = numToTake;
+        this.log('Will limit output to', MAX_NUMBER_OF_ENTITIES_TO_FETCH, 'entities');
+        const propertySpecificationArgs = argv
+            .slice(1, argv.length)
+            .filter(propertySpecifications_1.isValidPropertySpecification);
+        const propertySpecBySlug = (0, propertySpecifications_1.parsePropertySpecificationsIntoMap)(propertySpecificationArgs);
+        const relations = relationString
+            ? relationString
+                .split(',')
+                .map((r) => r.trim())
+                .filter(Boolean)
+            : [];
+        const propertySlugsArray = propertySlugs
+            ? propertySlugs
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean)
+            : [];
+        try {
+            // TODO: Refactor this so it's easier to read. It was partially vibe-coded and Adam
+            // thinks it is hard to read. Consider breaking it into smaller functions.
+            if (SHOULD_USE_PAGINATED_FIND) {
+                const stream = streamPaginatedFind(typePath, {
+                    skipHydrateRelationships,
+                    relations,
+                    propertySlugs: propertySlugsArray,
+                    criteria: convertPropertySpecIntoCriteria(propertySpecBySlug),
+                });
+                const writer = outputFile ? fs_1.default.createWriteStream(outputFile) : process.stdout;
+                writer.write('[\n');
+                let first = true;
+                for await (const entity of stream) {
+                    if (!first)
+                        writer.write(',\n');
+                    writer.write(JSON.stringify(entity, null, 2));
+                    first = false;
+                }
+                writer.write('\n]\n');
+                if (outputFile)
+                    this.log(`Output saved to ${outputFile}`);
+            }
+            else {
+                const response = await getEntityByTypePath(typePath, propertySpecBySlug, {
+                    skipHydrateRelationships,
+                    relations,
+                    propertySlugs: propertySlugsArray,
+                });
+                if (outputFile) {
+                    fs_1.default.writeFileSync(outputFile, JSON.stringify(response, null, 2));
+                    this.log(`Output saved to ${outputFile}`);
+                }
+                else {
+                    this.log(JSON.stringify(response, null, 2));
+                }
+            }
+        }
+        catch (e) {
+            this.error(`Error fetching entity: ${e.message}`);
+        }
+    }
+}
+exports.default = GetEntity;
+async function getEntityByTypePath(typePath, propertySpec, options = {}) {
+    const { propertySlugs, relations, skipHydrateRelationships } = options;
+    const id = propertySpec?.get('id')?.toString() || undefined;
+    const { root: entityName } = (0, types_1.parseTypePath)(typePath);
+    let criteria = {};
+    if (entityName === 'custom-entity' && !id) {
+        criteria.typePath = typePath;
+    }
+    else {
+        criteria = convertPropertySpecIntoCriteria(propertySpec || new Map());
+    }
+    return find(entityName, { id, skipHydrateRelationships, relations, propertySlugs, criteria });
+}
+function convertPropertySpecIntoCriteria(propertySpec) {
+    const criteria = {};
+    propertySpec.forEach((value, slug) => {
+        criteria[slug] = value;
+    });
+    return criteria;
+}
+async function find(entityName, options = {}) {
+    const client = new sdk_1.Entities();
+    const { criteria, id, propertySlugs, skipHydrateRelationships, relations } = options;
+    const queryOptions = {
+        entityName,
+        skipHydrateRelationships,
+        relations,
+    };
+    if (propertySlugs && propertySlugs.length > 0) {
+        queryOptions.customParams = { propertySlugs: propertySlugs.join(',') };
+    }
+    return id ? client.get({ id, ...queryOptions }) : client.get({ criteria, ...queryOptions });
+}
+async function* streamPaginatedFind(typePath, options = {}) {
+    const client = new sdk_1.Entities();
+    let nextPageKey = undefined;
+    let count = 0;
+    const { root: entityName } = (0, types_1.parseTypePath)(typePath);
+    while (true) {
+        const opts = {
+            ...options,
+            entityName,
+            apiVersion: sdk_1.API_VERSION.V2,
+            nextPageKey,
+        };
+        if (options.propertySlugs?.length > 0) {
+            opts.customParams = {
+                propertySlugs: options.propertySlugs.join(','),
+            };
+        }
+        const response = await client.get(opts);
+        nextPageKey = response.nextPageKey;
+        const results = response.results || [];
+        for (const result of results) {
+            if (count >= MAX_NUMBER_OF_ENTITIES_TO_FETCH)
+                return;
+            yield result;
+            count++;
+        }
+        // Update progress
+        console.log(`Fetched ${count} entities so far out of ${MAX_NUMBER_OF_ENTITIES_TO_FETCH}`);
+        if (!nextPageKey || results.length === 0 || count >= MAX_NUMBER_OF_ENTITIES_TO_FETCH) {
+            return;
+        }
+    }
+}
+// Useful for troubleshooting
+function logMemoryUsage(entityCount) {
+    const used = process.memoryUsage();
+    const toMB = (bytes) => (bytes / 1024 / 1024).toFixed(2);
+    console.error(`[${entityCount} entities] Memory Usage → RSS: ${toMB(used.rss)} MB | Heap: ${toMB(used.heapUsed)} MB / ${toMB(used.heapTotal)} MB`);
+}

package/dist/commands/entities/update.d.ts

@@ -0,0 +1,18 @@
+import { BaseCommand } from '../../basecommand';
+export default class UpdateEntity extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        skipHydrateRelationships: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        dryRun: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        inputFile: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        alwaysConfirmEnv: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        logLevel: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+    };
+    static args: {
+        entityName: import("@oclif/core/lib/interfaces/parser").Arg<string, Record<string, unknown>>;
+        id: import("@oclif/core/lib/interfaces/parser").Arg<string, Record<string, unknown>>;
+    };
+    static strict: boolean;
+    run(): Promise<void>;
+}

package/dist/commands/entities/update.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const p_limit_1 = tslib_1.__importDefault(require("p-limit"));
+const core_1 = require("@oclif/core");
+const basecommand_1 = require("../../basecommand");
+const sdk_1 = require("@contrail/sdk");
+const login_1 = require("../../auth/login");
+const propertySpecifications_1 = require("../../helpers/propertySpecifications/propertySpecifications");
+const file_helpers_1 = require("../../helpers/file-helpers");
+class UpdateEntity extends basecommand_1.BaseCommand {
+    static description = '(BETA) Update an entity';
+    static examples = ['contrail entities update color 123 -- name=obsidian hex=000000'];
+    static flags = {
+        ...basecommand_1.BaseCommand.baseFlags,
+        skipHydrateRelationships: core_1.Flags.boolean({
+            char: 's',
+            description: 'Skip hydrating relationships when updating the entity',
+            required: false,
+            default: false,
+        }),
+        dryRun: core_1.Flags.boolean({
+            char: 'd',
+            description: 'If true, does not create the entity but simulates the creation',
+            required: false,
+            default: false,
+        }),
+        inputFile: core_1.Flags.string({
+            char: 'i',
+            description: 'File containing properties to update the entity (optional)',
+            required: false,
+        }),
+    };
+    static args = {
+        entityName: core_1.Args.string({
+            description: 'The name of the entity type to update',
+            required: true,
+        }),
+        id: core_1.Args.string({
+            description: 'The unique identifier of the entity',
+            required: true,
+        }),
+    };
+    static strict = false;
+    async run() {
+        this.log('🚨 This command is in BETA and may change or be removed at any time.');
+        await (0, login_1.authUser)();
+        const { args, argv } = await this.parse(UpdateEntity);
+        const { id, entityName } = args;
+        const { dryRun: isDryRun, inputFile: inputFilename, skipHydrateRelationships } = this.flags;
+        const propertySpecArgs = argv.slice(1, argv.length).filter(propertySpecifications_1.isValidPropertySpecification);
+        const propertySpec = (0, propertySpecifications_1.parsePropertySpecificationsIntoMap)(propertySpecArgs);
+        if (propertySpec.size === 0) {
+            throw new Error('No valid properties provided for update');
+        }
+        if (inputFilename && id) {
+            throw new Error('You cannot use --input and --id together. Please specify one or the other.');
+        }
+        const partialEntitiesArray = inputFilename
+            ? (0, file_helpers_1.parseFileAsJsonArray)(inputFilename).map(({ id }) => ({ id }))
+            : [{ id }];
+        const results = {
+            idsSuccessfullyUpdated: new Set(),
+            idsFailedToUpdate: new Set(),
+            numEntriesSkipped: partialEntitiesArray.filter(({ id }) => !id).length,
+        };
+        const idsToUpdate = partialEntitiesArray.map(({ id }) => id).filter(Boolean);
+        propertySpec.delete('id'); // Remove 'id' from the property spec if it exists
+        const changes = [...propertySpec.entries()].reduce((acc, [key, value]) => {
+            acc[key] = value;
+            return acc;
+        }, {});
+        try {
+            async function updateEntity(id) {
+                const promise = isDryRun
+                    ? mockUpdateById(entityName, id, changes, { skipHydrateRelationships })
+                    : updateEntityById(entityName, id, changes, { skipHydrateRelationships });
+                promise
+                    .catch(() => {
+                    results.idsFailedToUpdate.add(id);
+                })
+                    .then(() => {
+                    results.idsSuccessfullyUpdated.add(id);
+                });
+                return promise;
+            }
+            const limit = (0, p_limit_1.default)(5); // Limit concurrency to 5
+            const responses = await Promise.all(idsToUpdate.map((id) => limit(() => updateEntity(id))));
+            const messagePrefix = isDryRun
+                ? 'Dry run. Update skipped. Changes would be:'
+                : 'Entity updated successfully:';
+            this.log(`${messagePrefix}\n\n${JSON.stringify(responses, null, 2)}`);
+            this.log(`\nIDs successfully updated: ${Array.from(results.idsSuccessfullyUpdated).join(', ')}`);
+            this.log(`IDs failed to update: ${Array.from(results.idsFailedToUpdate).join(', ')}`);
+            this.log(`Number of entries skipped due to missing IDs: ${results.numEntriesSkipped}`);
+        }
+        catch (e) {
+            this.error(`Error fetching entity: ${e.message}`);
+        }
+    }
+}
+exports.default = UpdateEntity;
+async function updateEntityById(entityName, id, changes, options = {}) {
+    const client = new sdk_1.Entities();
+    const { skipHydrateRelationships } = options;
+    return client.update({ entityName, id, object: changes, skipHydrateRelationships });
+}
+async function mockUpdateById(entityName, id, changes, options = {}) {
+    const client = new sdk_1.Entities();
+    const { skipHydrateRelationships } = options;
+    const entity = await client.get({ entityName, id, skipHydrateRelationships });
+    if (!entity) {
+        return null;
+    }
+    return { ...entity, ...changes };
+}

package/dist/commands/types/uploadUsageInfo.js

@@ -115,20 +115,8 @@ async function uploadUsageInfoObjects(loadedUsageInfo) {
                     entityName: 'type-property-usage-info',
                     id: found.id,
                     object: {
-                        editable: loadedUI?.editable,
-                        used: loadedUI?.used,
-                        formulaFunction: loadedUI?.formulaFunction,
-                        validationFunction: loadedUI?.validationFunction,
-                        numberFormat: loadedUI?.numberFormat,
-                        defaultValue: loadedUI?.defaultValue,
-                        label: loadedUI?.label,
-                        required: loadedUI?.required,
-                        searchable: loadedUI?.searchable,
-                        isUniqueProperty: loadedUI?.isUniqueProperty,
-                        isUniquePropertyInFamily: loadedUI?.isUniquePropertyInFamily,
-                        copyBehavior: loadedUI?.copyBehavior,
-                        copyDefault: loadedUI?.copyDefault,
-                        propertyLevel: loadedUI?.propertyLevel,
+                        editable: loadedUI.editable,
+                        used: loadedUI.used,
                     },
                 });
             }

package/dist/common.d.ts

@@ -1,4 +1,4 @@
 /// <reference types="node" />
 export declare function getSeparatorByPlatform(): string;
 export declare function delay(ms: number): Promise<NodeJS.Timeout>;
-export declare function removeSlash(string: any): string;
+export declare function removeSlash(string: string): string;

package/dist/helpers/app/app-deployer.js

@@ -107,7 +107,6 @@ class AppDeployer {
         if (appDeclaration?.accessGrants) {
             accessGrants = await app_template_parsers_1.AccessGrantsParser.buildAccessGrants(appDeclaration);
         }
-        // eslint-disable-next-line no-prototype-builtins
         if (appDeclaration.hasOwnProperty('dockerImageRef')) {
             throw new Error('Docker apps are no longer supported. Please use a node app.');
         }
@@ -202,11 +201,7 @@ async function createNodePackage(appIdentifier, debug, dryRun) {
         logger_1.default.info('Installing production dependencies done.');
         logger_1.default.info('Building package...');
         try {
-            // Check for tsconfig.build.json first, fallback to tsconfig.json
-            const buildConfigPath = fs_1.default.existsSync('tsconfig.build.json')
-                ? 'tsconfig.build.json'
-                : 'tsconfig.json';
-            child_process_1.default.execSync(`npx tsc --project ${buildConfigPath} --outDir tmp/dist`);
+            child_process_1.default.execSync('npx tsc --outDir tmp/dist');
         }
         catch (e) {
             logger_1.default.error(`${chalk_1.default.red.bold('APP')}      Failed to build package.`);
@@ -233,7 +228,7 @@ async function createNodePackage(appIdentifier, debug, dryRun) {
             return {};
         }
         logger_1.default.info('Uploading package to S3...');
-        const apps = await entitiesClient.get({ entityName: 'app' });
+        let apps = await entitiesClient.get({ entityName: 'app' });
         const thisApp = apps.find((x) => x.identifier === appIdentifier);
         if (!thisApp) {
             throw new Error('App not found');
@@ -243,7 +238,8 @@ async function createNodePackage(appIdentifier, debug, dryRun) {
             object: { appId: thisApp.id },
         });
         // upload an s3 object using a signed url with an https put request
-        const postBody = fs_1.default.readFileSync('tmp.zip');
+        const readStream = fs_1.default.readFileSync('tmp.zip');
+        const postBody = Buffer.from(readStream);
         // await axios.put(uploadUrlObject.signedUrl, postBody.toString());
         await axios_1.default.request({
             method: 'PUT',

package/dist/helpers/app/extension-package-deployer.js

@@ -119,7 +119,7 @@ async function createExtensionPackage(appId, extensionDir, options) {
     await uploadExtensionPackage(appExtensionPackage, tmpDir, options);
     logger_1.default.info(`${chalk_1.default.green.bold('COMPLETE')} Extension packaged and uploaded.`);
     if (options.debug) {
-        logger_1.default.debug('debug mode enabled. Not cleaning up tmp dir.');
+        logger_1.default.debug("debug mode enabled. Not cleaning up tmp dir.");
     }
     else {
         cleanUp(tmpDir);

package/dist/helpers/config/config.js

@@ -103,13 +103,13 @@ exports.writeConfig = writeConfig;
 async function getConfig() {
     let fileContent;
     try {
-        fileContent = (await node_fs_1.promises.readFile(configFileLocation)).toString();
+        fileContent = await (await node_fs_1.promises.readFile(configFileLocation)).toString();
     }
     catch {
         logger_1.default.debug(`failed to open config file (${configFileLocation}) for reading.`);
         logger_1.default.debug('trying to initialize config file');
         await initializeVibeIQConfig();
-        fileContent = (await node_fs_1.promises.readFile(configFileLocation)).toString();
+        fileContent = await (await node_fs_1.promises.readFile(configFileLocation)).toString();
     }
     try {
         const configFileJSON = JSON.parse(fileContent);
@@ -156,7 +156,7 @@ async function getConfigContent(fileName) {
     const configFilePath = (0, node_path_1.join)(configDirectoryLocation, `${fileName}.json`);
     let fileContent;
     try {
-        fileContent = (await node_fs_1.promises.readFile(configFilePath)).toString();
+        fileContent = await (await node_fs_1.promises.readFile(configFilePath)).toString();
         return JSON.parse(fileContent);
     }
     catch (error) {

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

@@ -0,0 +1,10 @@
+import { Item } from '@contrail/entity-types';
+export declare function throwIfInvalidAssortmentId(assortmentId: string): Promise<void>;
+export declare function createAssortmentItem(assortmentItem: {
+    assortmentId: string;
+    itemId: string;
+    [key: string]: any;
+}, { skipHydrateRelationships }?: {
+    skipHydrateRelationships: boolean;
+}): Promise<any>;
+export declare function findItemsNotInAssortment(assortmentId: string, count?: number): Promise<Item[]>;

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

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findItemsNotInAssortment = exports.createAssortmentItem = exports.throwIfInvalidAssortmentId = void 0;
+const sdk_1 = require("@contrail/sdk");
+const batchFetch_1 = require("./batchFetch");
+const items_1 = require("./items");
+async function throwIfInvalidAssortmentId(assortmentId) {
+    if (!(await doesAssortmentExistById(assortmentId))) {
+        throw new Error(`Assortment with ID ${assortmentId} does not exist`);
+    }
+}
+exports.throwIfInvalidAssortmentId = throwIfInvalidAssortmentId;
+async function doesAssortmentExistById(id) {
+    const client = new sdk_1.Entities();
+    const assortment = await client.get({ entityName: 'assortment', id });
+    return !!assortment;
+}
+async function createAssortmentItem(assortmentItem, { skipHydrateRelationships } = { skipHydrateRelationships: false }) {
+    const client = new sdk_1.Entities();
+    const { assortmentId, itemId } = assortmentItem;
+    // add item to assortment
+    await client.create({
+        entityName: 'assortment',
+        id: assortmentId,
+        relation: 'items',
+        object: { itemIds: [itemId] },
+    });
+    // Update assortment item with properties
+    const updated = await client.update({
+        entityName: 'assortment-item',
+        id: `${assortmentId}:${itemId}`,
+        object: assortmentItem,
+        skipHydrateRelationships,
+    });
+    return updated;
+}
+exports.createAssortmentItem = createAssortmentItem;
+// Methods to find an item not in the assortment
+const ASSORTMENT_ITEMS_CACHE_BY_ASSORTMENT_ID = new Map();
+const ASSORTMENT_ITEMS_CACHE_BY_ITEM_ID = new Map();
+async function cacheAssortmentItemsByAssortmentId(assortmentId) {
+    if (!assortmentId) {
+        throw new Error('Assortment ID is required to cache assortment items');
+    }
+    if (ASSORTMENT_ITEMS_CACHE_BY_ASSORTMENT_ID.has(assortmentId)) {
+        return; // Already cached
+    }
+    const assortmentItems = await (0, batchFetch_1.batchFetch)('assortment-item', {
+        criteria: { assortmentId },
+        customParams: { propertySlugs: 'id,assortmentId,itemId' },
+    });
+    ASSORTMENT_ITEMS_CACHE_BY_ASSORTMENT_ID.set(assortmentId, assortmentItems);
+    assortmentItems.forEach((item) => {
+        if (!ASSORTMENT_ITEMS_CACHE_BY_ITEM_ID.has(item.itemId)) {
+            ASSORTMENT_ITEMS_CACHE_BY_ITEM_ID.set(item.itemId, []);
+        }
+        ASSORTMENT_ITEMS_CACHE_BY_ITEM_ID.get(item.itemId).push(item);
+    });
+}
+async function getAssortmentItemsByAssortmentId(assortmentId) {
+    if (!assortmentId) {
+        throw new Error('Assortment ID is required to get assortment items');
+    }
+    await cacheAssortmentItemsByAssortmentId(assortmentId);
+    const assortmentItems = ASSORTMENT_ITEMS_CACHE_BY_ASSORTMENT_ID.get(assortmentId);
+    if (!assortmentItems) {
+        throw new Error(`No assortment items found for assortment ID ${assortmentId}`);
+    }
+    return assortmentItems;
+}
+async function findItemsNotInAssortment(assortmentId, count) {
+    if (!assortmentId) {
+        throw new Error('Assortment ID is required to find items not in assortment');
+    }
+    const assortmentItemsInAssortment = await getAssortmentItemsByAssortmentId(assortmentId);
+    const items = await (0, items_1.getManyItems)(count + assortmentItemsInAssortment.length);
+    const assortmentItemIds = new Set(assortmentItemsInAssortment.map((ai) => ai.itemId));
+    const itemsNotInAssortment = items.filter((item) => !assortmentItemIds.has(item.id));
+    if (itemsNotInAssortment.length === 0) {
+        throw new Error(`All items are already in assortment ${assortmentId}`);
+    }
+    return itemsNotInAssortment.sort((a, b) => a.id.localeCompare(b.id)); // sorting ensures consistent order of response
+}
+exports.findItemsNotInAssortment = findItemsNotInAssortment;

package/dist/helpers/entities/batchFetch.d.ts

@@ -0,0 +1,8 @@
+import { AssortmentItem, Item, ProjectItem } from '@contrail/entity-types';
+import { EntitiesClientGetOptions } from '@contrail/sdk';
+export interface BatchFetchableEntityMap {
+    item: Item;
+    'project-item': ProjectItem;
+    'assortment-item': AssortmentItem;
+}
+export declare function batchFetch<K extends keyof BatchFetchableEntityMap>(entityName: K, options: EntitiesClientGetOptions): Promise<BatchFetchableEntityMap[K][]>;

package/dist/helpers/entities/batchFetch.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.batchFetch = void 0;
+const sdk_1 = require("@contrail/sdk");
+const util_1 = require("@contrail/util");
+async function batchFetch(entityName, options) {
+    const response = await requestBatchFetch(entityName, options);
+    return parseBatchFetchResponse(response);
+}
+exports.batchFetch = batchFetch;
+async function requestBatchFetch(entityName, options) {
+    const client = new sdk_1.Entities();
+    // NOTE: There is probably a helper somewhere else that manages this conversion
+    const optionsClone = { ...options };
+    if (optionsClone.criteria) {
+        optionsClone.where = optionsClone.criteria;
+    }
+    return client.create({
+        entityName: entityName,
+        suffix: 'batch-fetch',
+        object: optionsClone,
+    });
+}
+async function parseBatchFetchResponse(response) {
+    if ('results' in response) {
+        return response.results;
+    }
+    else if ('resultsCompressedString' in response) {
+        const compressedString = response.resultsCompressedString;
+        const jsonData = (0, util_1.decompressFromString)(compressedString);
+        return jsonData;
+    }
+    else if ('resultsDownloadUrl' in response) {
+        const downloadUrl = response.resultsDownloadUrl;
+        const data = await fetch(downloadUrl).then((res) => res.json());
+        return data;
+    }
+    else {
+        throw new Error('Invalid batch fetch response format');
+    }
+}

package/dist/helpers/entities/index.d.ts

@@ -0,0 +1,3 @@
+export * from './assortment-items';
+export * from './items';
+export * from './project-items';

package/dist/helpers/entities/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./assortment-items"), exports);
+tslib_1.__exportStar(require("./items"), exports);
+tslib_1.__exportStar(require("./project-items"), exports);

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

@@ -0,0 +1,10 @@
+import { Item } from '@contrail/entity-types';
+export declare function throwIfInvalidItemId(itemId: string): Promise<void>;
+export type SparseItem = Pick<Item, 'id' | 'familyId' | 'roles' | 'name'>;
+export declare function getAllItemsUsingCacheFallback(): Promise<SparseItem[]>;
+export declare function getManyItems(maxCount?: number): Promise<SparseItem[]>;
+export declare function getItemFamilies(count: number): Promise<SparseItem[] | undefined>;
+export declare function getFamilyName(item: SparseItem): Promise<string[] | undefined>;
+export declare const Roles: readonly ["option", "family"];
+export type Role = (typeof Roles)[number];
+export declare function throwIfInvalidItemLevel(role: string): asserts role is Role;