@contrail/cli 3.6.0-alpha-8-alpha.7d24daa → 3.6.0-alpha-8-alpha.d292a3d

package/README.md

@@ -17,7 +17,7 @@ $ npm install -g @contrail/cli
 $ contrail COMMAND
 running command...
 $ contrail (--version)
-@contrail/cli/3.6.0-alpha-8-alpha.7d24daa linux-x64 node-v24.21.0
+@contrail/cli/3.6.0-alpha-8-alpha.d292a3d linux-x64 node-v24.21.0
 $ contrail --help [COMMAND]
 USAGE
   $ contrail COMMAND
@@ -548,7 +548,7 @@ Create entities
 ```
 USAGE
   $ contrail entities create PATH [-l error|warn|info|debug] [-e true|false] [-n <value>] [-d] [-i <value>] [-o
-    <value>] [-g] [-r] [-S] [--suffix <value>]
+    <value>] [-g] [-r] [-S] [--suffix <value>] [--apiVersion 1|2]
 
 ARGUMENTS
   PATH  Path of the entity type to create
@@ -568,6 +568,8 @@ FLAGS
   -n, --count=<value>              Number of random entities to create
   -o, --outputFile=<value>         File to save the output (optional)
   -r, --readableIds                If true, uses readable IDs for the created entities
+  --apiVersion=<option>            Api-Version header to send; selects the V1 or V2 variant of the endpoint
+                                   <options: 1|2>
   --suffix=<value>                 Append a sub-route to the entity endpoint (e.g. --suffix=synchronous targets
                                    /<entities>/synchronous)
 
@@ -601,7 +603,7 @@ Delete entities by id
 ```
 USAGE
   $ contrail entities delete ENTITYNAME [IDS] [-l error|warn|info|debug] [-e true|false] [-d] [-i <value>] [--suffix
-    <value>]
+    <value>] [--apiVersion 1|2]
 
 ARGUMENTS
   ENTITYNAME  The name of the entity type to delete
@@ -615,6 +617,8 @@ FLAGS
                                    entity in the file.
   -l, --logLevel=<option>          The Log Level
                                    <options: error|warn|info|debug>
+  --apiVersion=<option>            Api-Version header to send; selects the V1 or V2 variant of the endpoint
+                                   <options: 1|2>
   --suffix=<value>                 Append a sub-route to the entity endpoint (e.g. --suffix=synchronous targets
                                    /<entities>/synchronous)
 
@@ -636,7 +640,7 @@ Get an entity
 ```
 USAGE
   $ contrail entities get TYPEPATH [IDS] [-l error|warn|info|debug] [-e true|false] [-o <value>] [-p <value>] [-P]
-    [-s <value>] [-S] [-t <value>] [-r <value>] [--suffix <value>]
+    [-s <value>] [-S] [-t <value>] [-r <value>] [--suffix <value>] [--apiVersion 1|2]
 
 ARGUMENTS
   TYPEPATH  The name of the entity type to fetch
@@ -654,6 +658,8 @@ FLAGS
   -r, --relations=<value>          Comma-separated list of relations to include in the output
   -s, --skip=<value>               Number of entities to skip (used with paginated fetch)
   -t, --take=<value>               Number of entities to fetch in a single request (default is 100)
+  --apiVersion=<option>            Api-Version header to send; selects the V1 or V2 variant of the endpoint
+                                   <options: 1|2>
   --suffix=<value>                 Append a sub-route to the entity endpoint (e.g. --suffix=synchronous targets
                                    /<entities>/synchronous)
 
@@ -681,7 +687,7 @@ Update an entity
 ```
 USAGE
   $ contrail entities update ENTITYNAME [IDS] [-l error|warn|info|debug] [-e true|false] [-S] [-d] [-i <value>] [-F]
-    [--suffix <value>]
+    [--suffix <value>] [--apiVersion 1|2]
 
 ARGUMENTS
   ENTITYNAME  The name of the entity type to update
@@ -696,6 +702,8 @@ FLAGS
   -i, --inputFile=<value>          File containing properties to update the entity (optional)
   -l, --logLevel=<option>          The Log Level
                                    <options: error|warn|info|debug>
+  --apiVersion=<option>            Api-Version header to send; selects the V1 or V2 variant of the endpoint
+                                   <options: 1|2>
   --suffix=<value>                 Append a sub-route to the entity endpoint (e.g. --suffix=synchronous targets
                                    /<entities>/synchronous)
 

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

@@ -15,6 +15,7 @@ export default class CreateEntity extends BaseCommand {
         readableIds: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         skipHydrateRelationships: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         suffix: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        apiVersion: 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>;
     };

package/dist/commands/entities/create.js

@@ -204,6 +204,11 @@ class CreateEntity extends basecommand_1.BaseCommand {
             description: 'Append a sub-route to the entity endpoint (e.g. --suffix=synchronous targets /<entities>/synchronous)',
             required: false,
         }),
+        apiVersion: core_1.Flags.string({
+            description: 'Api-Version header to send; selects the V1 or V2 variant of the endpoint',
+            options: ['1', '2'],
+            required: false,
+        }),
     };
     static args = {
         path: core_1.Args.string({
@@ -217,7 +222,7 @@ class CreateEntity extends basecommand_1.BaseCommand {
         (0, common_1.routeConsoleLogToStderr)();
         await (0, login_1.authUser)();
         const { flags, argv, args } = await this.parse(CreateEntity);
-        const { count, dryRun: isDryRun, inputFile: inputFilename, outputFile: outputFilename, generateValues: shouldGenerateMissingValues, readableIds: shouldUseReadableIds, skipHydrateRelationships, suffix, } = flags;
+        const { count, dryRun: isDryRun, inputFile: inputFilename, outputFile: outputFilename, generateValues: shouldGenerateMissingValues, readableIds: shouldUseReadableIds, skipHydrateRelationships, suffix, apiVersion, } = flags;
         const { path: entityTypePath } = args;
         // Global flags is a little hacky, but it was easier
         // and it doesn't see *that* bad because they are only valid
@@ -263,7 +268,10 @@ class CreateEntity extends basecommand_1.BaseCommand {
         }
         try {
             const entitiesToCreate = await buildEntitiesToCreate(entityTypePath, partialEntities, propertySpecBySlug);
-            const summary = await createEntities(entityName, entitiesToCreate, suffix);
+            const summary = await createEntities(entityName, entitiesToCreate, {
+                suffix,
+                apiVersion: apiVersion,
+            });
             if (outputFilename) {
                 fs_1.default.writeFileSync(outputFilename, JSON.stringify(summary, null, 2));
                 console.error(`Output saved to ${outputFilename}`);
@@ -298,13 +306,13 @@ function summarizeSettledCreates(inputs, settled) {
     return { created, failed };
 }
 exports.summarizeSettledCreates = summarizeSettledCreates;
-async function createEntities(entityName, entities, suffix) {
+async function createEntities(entityName, entities, routing = {}) {
     if (IS_DRY_RUN) {
         console.error(`Dry run mode: not creating entities, but simulating creation for ${entityName}`);
         return { created: entities, failed: [] };
     }
     const limit = (0, p_limit_1.default)(20);
-    const settled = await Promise.allSettled(entities.map(async (e) => limit(() => createEntity(entityName, e, suffix))));
+    const settled = await Promise.allSettled(entities.map(async (e) => limit(() => createEntity(entityName, e, routing))));
     return summarizeSettledCreates(entities, settled);
 }
 async function buildEntitiesToCreate(entityTypePath, entities, propertySpecificationBySlug) {
@@ -544,9 +552,10 @@ function castValueToPropertyType(value, propertyType) {
     }
 }
 exports.castValueToPropertyType = castValueToPropertyType;
-async function createEntity(entityName, entity, suffix) {
+async function createEntity(entityName, entity, routing = {}) {
     const client = new sdk_1.Entities();
     const skipHydrateRelationships = SHOULD_SKIP_HYDRATE_RELATIONSHIPS;
+    const { suffix, apiVersion } = routing;
     if (entityName === 'assortment-item' && !suffix)
         return (0, entities_1.createAssortmentItem)(entity, { skipHydrateRelationships }); // special case
     const response = await client.create({
@@ -554,6 +563,7 @@ async function createEntity(entityName, entity, suffix) {
         object: entity,
         skipHydrateRelationships,
         suffix,
+        apiVersion,
     });
     return response;
 }

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

@@ -6,6 +6,7 @@ export default class DeleteEntity extends BaseCommand {
         dryRun: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         inputFile: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
         suffix: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        apiVersion: 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>;
     };

package/dist/commands/entities/delete.js

@@ -34,6 +34,11 @@ class DeleteEntity extends basecommand_1.BaseCommand {
             description: 'Append a sub-route to the entity endpoint (e.g. --suffix=synchronous targets /<entities>/synchronous)',
             required: false,
         }),
+        apiVersion: core_1.Flags.string({
+            description: 'Api-Version header to send; selects the V1 or V2 variant of the endpoint',
+            options: ['1', '2'],
+            required: false,
+        }),
     };
     static args = {
         entityName: core_1.Args.string({
@@ -51,7 +56,7 @@ class DeleteEntity extends basecommand_1.BaseCommand {
         await (0, login_1.authUser)();
         const { args, flags, argv } = await this.parse(DeleteEntity);
         const { entityName } = args;
-        const { inputFile: inputFilename, suffix } = flags;
+        const { inputFile: inputFilename, suffix, apiVersion } = flags;
         if (flags.dryRun) {
             IS_DRY_RUN = true;
             console.error('Running in dry run mode. No entities will be deleted.');
@@ -75,7 +80,10 @@ class DeleteEntity extends basecommand_1.BaseCommand {
         }
         const ids = rowsWithId ? rowsWithId.map((item) => item.id) : positionalIds;
         try {
-            const response = await deleteEntityByIds(entityName, ids, suffix);
+            const response = await deleteEntityByIds(entityName, ids, {
+                suffix,
+                apiVersion: apiVersion,
+            });
             if (IS_DRY_RUN) {
                 console.error('simulated deletion of entities:');
             }
@@ -94,12 +102,12 @@ class DeleteEntity extends basecommand_1.BaseCommand {
     }
 }
 exports.default = DeleteEntity;
-async function deleteEntityByIds(entityName, ids, suffix) {
+async function deleteEntityByIds(entityName, ids, routing = {}) {
     const idsDeleted = new Set();
     const idsNotFound = new Set();
     const idsErrored = new Set();
     const limit = (0, p_limit_1.default)(10);
-    const deletePromises = ids.map((id) => limit(() => deleteEntityById(entityName, id, suffix).then((entity) => {
+    const deletePromises = ids.map((id) => limit(() => deleteEntityById(entityName, id, routing).then((entity) => {
         if (!entity) {
             idsNotFound.add(id);
             return null;
@@ -122,12 +130,15 @@ async function deleteEntityByIds(entityName, ids, suffix) {
         idsErrored: Array.from(idsErrored),
     };
 }
-async function deleteEntityById(entityName, id, suffix) {
+async function deleteEntityById(entityName, id, routing = {}) {
     const client = new sdk_1.Entities();
     if (IS_DRY_RUN) {
         return client.get({ entityName, id, ignore404: true }).catch(throwIfNot404);
     }
-    return client.delete({ entityName, id, ignore404: true, suffix }).catch(throwIfNot404);
+    const { suffix, apiVersion } = routing;
+    return client
+        .delete({ entityName, id, ignore404: true, suffix, apiVersion })
+        .catch(throwIfNot404);
 }
 function throwIfNot404(e) {
     const { statusCode } = parseSDKErrorMessage(e);

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

@@ -11,6 +11,7 @@ export default class GetEntity extends BaseCommand {
         take: import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
         relations: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
         suffix: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        apiVersion: 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>;
     };

package/dist/commands/entities/get.js

@@ -66,6 +66,11 @@ class GetEntity extends basecommand_1.BaseCommand {
             description: 'Append a sub-route to the entity endpoint (e.g. --suffix=synchronous targets /<entities>/synchronous)',
             required: false,
         }),
+        apiVersion: core_1.Flags.string({
+            description: 'Api-Version header to send; selects the V1 or V2 variant of the endpoint',
+            options: ['1', '2'],
+            required: false,
+        }),
     };
     static args = {
         typePath: core_1.Args.string({
@@ -83,7 +88,7 @@ class GetEntity extends basecommand_1.BaseCommand {
         await (0, login_1.authUser)();
         const { args, flags, argv } = await this.parse(GetEntity);
         const { typePath } = args;
-        const { outputFile, paginated: shouldUsePaginatedFind, propertySlugs, relations: relationString, skip, skipHydrateRelationships, suffix, take, } = flags;
+        const { outputFile, paginated: shouldUsePaginatedFind, propertySlugs, relations: relationString, skip, skipHydrateRelationships, suffix, apiVersion, take, } = flags;
         SHOULD_USE_PAGINATED_FIND = shouldUsePaginatedFind;
         MAX_NUMBER_OF_ENTITIES_TO_FETCH = take;
         if (MAX_NUMBER_OF_ENTITIES_TO_FETCH)
@@ -125,6 +130,7 @@ class GetEntity extends basecommand_1.BaseCommand {
                     skipHydrateRelationships,
                     skip,
                     suffix,
+                    apiVersion: apiVersion,
                     relations,
                     propertySlugs: propertySlugsArray,
                 });
@@ -148,6 +154,7 @@ class GetEntity extends basecommand_1.BaseCommand {
                     propertySlugs: propertySlugsArray,
                     skip,
                     suffix,
+                    apiVersion: apiVersion,
                     take,
                 });
                 if (outputFile) {
@@ -166,7 +173,7 @@ class GetEntity extends basecommand_1.BaseCommand {
 }
 exports.default = GetEntity;
 async function getEntityByTypePath(typePath, propertySpec, options = {}) {
-    const { propertySlugs, relations, skipHydrateRelationships, skip, suffix, take } = options;
+    const { propertySlugs, relations, skipHydrateRelationships, skip, suffix, apiVersion, take } = options;
     const id = propertySpec?.get('id')?.toString() || undefined;
     const criteria = convertPropertySpecIntoCriteria(propertySpec || new Map());
     const { root: entityName } = (0, types_1.parseTypePath)(typePath);
@@ -181,6 +188,7 @@ async function getEntityByTypePath(typePath, propertySpec, options = {}) {
         criteria,
         skip,
         suffix,
+        apiVersion,
         take,
     });
 }
@@ -193,13 +201,14 @@ function convertPropertySpecIntoCriteria(propertySpec) {
 }
 async function find(entityName, options = {}) {
     const client = new sdk_1.Entities();
-    const { criteria, id, propertySlugs, skipHydrateRelationships, relations, skip, suffix, take } = options;
+    const { criteria, id, propertySlugs, skipHydrateRelationships, relations, skip, suffix, apiVersion, take, } = options;
     const queryOptions = {
         entityName,
         skipHydrateRelationships,
         relations,
         skip,
         suffix,
+        apiVersion,
         take,
     };
     if (propertySlugs && propertySlugs.length > 0) {
@@ -223,7 +232,8 @@ async function* streamPaginatedFind(typePath, options = {}) {
         const opts = {
             ...options,
             entityName,
-            apiVersion: sdk_1.API_VERSION.V2,
+            // paginated reads require the V2 response shape unless overridden
+            apiVersion: options.apiVersion ?? sdk_1.API_VERSION.V2,
             nextPageKey,
         };
         if (options.propertySlugs?.length > 0) {

package/dist/commands/entities/grammar.spec.js

@@ -71,5 +71,10 @@ describe('entities command grammar: entities <verb> <typePath> [ID...]', () => {
             expect(update_1.default.flags.suffix).toBeDefined();
             expect(delete_1.default.flags.suffix).toBeDefined();
         });
+        it('should expose --apiVersion on every verb, constrained to 1 or 2', () => {
+            for (const command of [create_1.default, get_1.default, update_1.default, delete_1.default]) {
+                expect(command.flags.apiVersion.options).toEqual(['1', '2']);
+            }
+        });
     });
 });

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

@@ -8,6 +8,7 @@ export default class UpdateEntity extends BaseCommand {
         inputFile: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
         force: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         suffix: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        apiVersion: 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>;
     };

package/dist/commands/entities/update.js

@@ -45,6 +45,11 @@ class UpdateEntity extends basecommand_1.BaseCommand {
             description: 'Append a sub-route to the entity endpoint (e.g. --suffix=synchronous targets /<entities>/synchronous)',
             required: false,
         }),
+        apiVersion: core_1.Flags.string({
+            description: 'Api-Version header to send; selects the V1 or V2 variant of the endpoint',
+            options: ['1', '2'],
+            required: false,
+        }),
     };
     static args = {
         entityName: core_1.Args.string({
@@ -62,7 +67,7 @@ class UpdateEntity extends basecommand_1.BaseCommand {
         await (0, login_1.authUser)();
         const { args, argv } = await this.parse(UpdateEntity);
         const { entityName } = args;
-        const { dryRun: isDryRun, inputFile: inputFilename, skipHydrateRelationships, suffix, force, } = this.flags;
+        const { dryRun: isDryRun, inputFile: inputFilename, skipHydrateRelationships, suffix, apiVersion, force, } = this.flags;
         const { ids: positionalIds, specs } = (0, propertySpecifications_1.partitionIdsAndSpecs)(argv.slice(1));
         const propertySpec = (0, propertySpecifications_1.parsePropertySpecificationsIntoMap)(specs);
         if (propertySpec.has('id') || propertySpec.has('ids')) {
@@ -95,6 +100,7 @@ class UpdateEntity extends basecommand_1.BaseCommand {
                 : updateEntityById(entityName, id, newEntityState, {
                     skipHydrateRelationships,
                     suffix,
+                    apiVersion: apiVersion,
                     force,
                 });
         }
@@ -138,8 +144,15 @@ function summarizeSettledUpdates(inputs, settled, skipped) {
 exports.summarizeSettledUpdates = summarizeSettledUpdates;
 async function updateEntityById(entityName, id, changes, options = {}) {
     const client = new sdk_1.Entities();
-    const { skipHydrateRelationships, suffix, force } = options;
-    return client.update({ entityName, id, object: changes, skipHydrateRelationships, suffix });
+    const { skipHydrateRelationships, suffix, apiVersion, force } = options;
+    return client.update({
+        entityName,
+        id,
+        object: changes,
+        skipHydrateRelationships,
+        suffix,
+        apiVersion,
+    });
 }
 async function mockUpdateById(entityName, id, changes, options = {}) {
     const client = new sdk_1.Entities();

package/oclif.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.6.0-alpha-8-alpha.7d24daa",
+  "version": "3.6.0-alpha-8-alpha.d292a3d",
   "commands": {
     "app:create": {
       "id": "app:create",
@@ -782,6 +782,17 @@
           "description": "Append a sub-route to the entity endpoint (e.g. --suffix=synchronous targets /<entities>/synchronous)",
           "required": false,
           "multiple": false
+        },
+        "apiVersion": {
+          "name": "apiVersion",
+          "type": "option",
+          "description": "Api-Version header to send; selects the V1 or V2 variant of the endpoint",
+          "required": false,
+          "multiple": false,
+          "options": [
+            "1",
+            "2"
+          ]
         }
       },
       "args": {
@@ -855,6 +866,17 @@
           "description": "Append a sub-route to the entity endpoint (e.g. --suffix=synchronous targets /<entities>/synchronous)",
           "required": false,
           "multiple": false
+        },
+        "apiVersion": {
+          "name": "apiVersion",
+          "type": "option",
+          "description": "Api-Version header to send; selects the V1 or V2 variant of the endpoint",
+          "required": false,
+          "multiple": false,
+          "options": [
+            "1",
+            "2"
+          ]
         }
       },
       "args": {
@@ -976,6 +998,17 @@
           "description": "Append a sub-route to the entity endpoint (e.g. --suffix=synchronous targets /<entities>/synchronous)",
           "required": false,
           "multiple": false
+        },
+        "apiVersion": {
+          "name": "apiVersion",
+          "type": "option",
+          "description": "Api-Version header to send; selects the V1 or V2 variant of the endpoint",
+          "required": false,
+          "multiple": false,
+          "options": [
+            "1",
+            "2"
+          ]
         }
       },
       "args": {
@@ -1070,6 +1103,17 @@
           "description": "Append a sub-route to the entity endpoint (e.g. --suffix=synchronous targets /<entities>/synchronous)",
           "required": false,
           "multiple": false
+        },
+        "apiVersion": {
+          "name": "apiVersion",
+          "type": "option",
+          "description": "Api-Version header to send; selects the V1 or V2 variant of the endpoint",
+          "required": false,
+          "multiple": false,
+          "options": [
+            "1",
+            "2"
+          ]
         }
       },
       "args": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/cli",
-  "version": "3.6.0-alpha-8-alpha.7d24daa",
+  "version": "3.6.0-alpha-8-alpha.d292a3d",
   "description": "VibeIQ's Contrail Platform CLI.",
   "bin": {
     "contrail-cli": "./bin/run",