Example Script

This example shell script demonstrates how to use the Corellium JavaScript v1 API to:

1. Search for a device with a specified instance ID.
2. If it's found, ensure the device is powered on.
3. If it's not found, create a new device with a desired hardware and firmware and wait for it to be ready.
4. Wait for the device to boot.

Pre-Requisites

1. Ensure the following npm dependencies are installed on your local environment:

   • @corellium/corellium-api

2. Set an environmental variable CORELLIUM_API_TOKEN with your API token.

3. Set another environmental variable CORELLIUM_API_ENDPOINT.

   • For On-Premise customers, use https://<your_hostname>/api, where <your_hostname> is either the hostname or IP address of your Corellium appliance.
   • For Business Cloud customers, use https://<your_domain>.enterprise.corellium.com/api, where <your_domain> is taken from the URL you use to access the Corellium web interface.
   • For Solo Cloud customers, use https://app.corellium.com/api.

Example Script

const { Corellium } = require("@corellium/corellium-api");

const CORELLIUM_API_ENDPOINT = process.env.CORELLIUM_API_ENDPOINT;
const CORELLIUM_API_TOKEN = process.env.CORELLIUM_API_TOKEN;
if (!CORELLIUM_API_ENDPOINT || !CORELLIUM_API_TOKEN) {
    handleError('Error: Environment variables CORELLIUM_API_ENDPOINT and CORELLIUM_API_TOKEN must be set.');
}
const CORELLIUM_API_ENDPOINT_ORIGIN = new URL(CORELLIUM_API_ENDPOINT).origin.toString();

// Define the default values
const DEFAULT_INSTANCE_ID = 'YOUR_INSTANCE_IDENTIFIER';
const DEFAULT_INSTANCE_FIRMWARE = '18.0';
const DEFAULT_INSTANCE_HARDWARE = 'iphone16pm';
const DEFAULT_INSTANCE_NAME = 'JavaScript_v1_API_demo_device';
const DEFAULT_PROJECT_ID = 'YOUR_PROJECT_IDENTIFIER';

// Define the time constants
const SLEEP_TIME_SECONDS = 60;

// Define the constants for instance states and task states
const INSTANCE_STATE_OFF = 'off';
const INSTANCE_STATE_ON = 'on';
const INSTANCE_STATE_BOOTING = 'booting';
const INSTANCE_STATE_CREATING = 'creating';
const INSTANCE_STATE_REBOOTING = 'rebooting';
const INSTANCE_TASK_STATE_NONE = 'none';

async function createNewInstance(corellium) {
    let project, instId;
    // Ensure the user has access to the project
    try {
        project = await corellium.getProject(DEFAULT_PROJECT_ID);
    } catch (projectError) {
        if (projectError.code === 403) {
            handleError(`User does not have access to project ${DEFAULT_PROJECT_ID}`, '');
        } else {
            handleError(projectError, 'Exception when getting project in createNewInstance.');
        }
    }
    // Create a new instance using the project object
    try {
        let instCreateOptions = {
            flavor: DEFAULT_INSTANCE_HARDWARE,
            os: DEFAULT_INSTANCE_FIRMWARE,
            name: DEFAULT_INSTANCE_NAME,
        };
        console.log(`Creating a new instance of ${instCreateOptions.flavor} hardware with ${instCreateOptions.os} firmware.`);
        const instance = await project.createInstance(instCreateOptions);
        if (instance) {
            console.log(`Instance ${instance.id} is creating.`);
            instId = instance.id;
            console.log(`Waiting for instance ${instance.id} to finish creating.`);
            await instance.finishRestore();
        } else {
            handleError('Instance failed to create', '');
        }
    } catch (createError) {
        if ((createError.code === 400 && createError.message === 'Domain does not have enough resources to complete, insufficient resource: cores') ||
            (createError.code === 404 && createError.message === 'project with project=' + DEFAULT_PROJECT_ID + ' not found')) {
            handleError(createError.message, '');
        } else {
            handleError(createError, 'Exception when creating instance in createNewInstance.');
        }
    }
    return instId;
}

function handleError(error, message = '') {
    (message)
        ? console.error('ERROR:', message, error)
        : console.error('ERROR:', error);
    process.exit(1);
}

async function handleUnexpectedState(instanceId, instanceState, instanceTaskState) {
    handleError(`Unexpected state - instance ${instanceId} is ${instanceState} with taskState ${instanceTaskState}.`);
}

async function sleepForSeconds(seconds) {
    await new Promise(resolve => setTimeout(resolve, seconds * 1000));
}

async function turnInstanceOnOrCreateNewInstance(corellium) {
    let instId;
    try {
        const instance = await corellium.getInstance(DEFAULT_INSTANCE_ID);
        if (instance) {
            instId = DEFAULT_INSTANCE_ID;
            if (instance.state === INSTANCE_STATE_OFF) {
                console.log(`Instance ${DEFAULT_INSTANCE_ID} is ${instance.state}.`);
                await instance.start();
                console.log(`Instance ${DEFAULT_INSTANCE_ID} is powering on.`);
            }
        }
    } catch (error) {
        if (error.code === 404) {
            console.log(`Instance ${DEFAULT_INSTANCE_ID} was not found.`);
            instId = await createNewInstance(corellium);
        } else {
            handleError(error, `Exception when getting instance.`);
        }
    }
    return instId;
}

async function waitForInstanceToTurnOn(corellium, instanceId) {
    let instanceState;
    let instanceTaskState;
    while (instanceState !== INSTANCE_STATE_ON || instanceTaskState !== INSTANCE_TASK_STATE_NONE) {
        try {
            const instance = await corellium.getInstance(instanceId);
            instanceState = instance.state;
            instanceTaskState = instance.taskState;
            if ([INSTANCE_STATE_BOOTING, INSTANCE_STATE_CREATING, INSTANCE_STATE_REBOOTING].includes(instanceState)) {
                console.log(`Waiting for instance to finish ${instanceState}.`);
                await sleepForSeconds(SLEEP_TIME_SECONDS);
            } else if (instanceState === INSTANCE_STATE_ON) {
                (instanceTaskState === INSTANCE_TASK_STATE_NONE)
                    ? console.log(`Instance ${instanceId} is ${instanceState}.`)
                    : handleUnexpectedState(instanceId, instanceState, instanceTaskState);
            } else {
                handleUnexpectedState(instanceId, instanceState, instanceTaskState);
            }
        } catch(error) {
            handleError(error, 'Exception in waitForInstanceToTurnOn().');
            process.exit(1);
        }
    }
}

async function main() {    
    try {
        console.log(`Starting the script at ${new Date().toISOString()}.`);
        const corellium = new Corellium({
            endpoint: CORELLIUM_API_ENDPOINT_ORIGIN,
            apiToken: CORELLIUM_API_TOKEN,
        });
        await corellium.login();

        const instanceId = await turnInstanceOnOrCreateNewInstance(corellium);
        await waitForInstanceToTurnOn(corellium, instanceId);
    } catch (error) {
        handleError(error, 'Exception in main,');
    }
}

main();