nativescript-cloud

nativescript-cloud

Used for cloud support in NativeScript CLI

Public API

This section describes all methods that can be invoked when you have installed the nativescript-cloud extension and NativeScript CLI is required as library, i.e.:

const tns = require("nativescript");

Module cloudBuildService

The cloudBuildService allows build of applications in the cloud. You can call the following methods:

• build method - it validates passed arguments and tries to build the application in the cloud. In case of successful build, the build result (.apk, .ipa or .zip) is downloaded. The result contains information about the whole build process, path to the downloaded build result and information used to generate a QR code, pointing to the latest build result (in S3). During the build the cloudBuildService will emit buildOutput event which will contain parts of the current build output.
  Definition:

/**
 * Builds the specified application in the cloud and returns information about the whole build process.
 * @param {IProjectSettings} projectSettings Describes the current project - project dir, application identifier, name and nativescript data.
 * @param {string} platform The mobile platform for which the application should be built: Android or iOS.
 * @param {string} buildConfiguration The build configuration - Debug or Release.
 * @param {IAndroidBuildData} androidBuildData Android speicific information for the build.
 * @param {IIOSBuildData} iOSBuildData iOS speicific information for the build.
 * @returns {Promise<IBuildResultData>} Information about the build process. It is returned only on successfull build. In case the build fails, the Promise is rejected with the server information.
 */
build(projectSettings: IProjectSettings,
	platform: string, buildConfiguration: string,
	androidBuildData?: IAndroidBuildData,
	iOSBuildData?: IIOSBuildData): Promise<IBuildResultData>;

Detailed description of each parameter can be found here.
Usage:

const tns = require("nativescript");
const fs = require("fs");
const path = require("path");
const packageJsonContent = JSON.parse(fs.readFileSync("./package.json", "utf8").toString());

const projectSettings = {
	projectDir: process.cwd(),
	projectId: packageJsonContent.nativescript.id,
	projectName: path.dirname(process.cwd()),
	nativeScriptData: packageJsonContent.nativescript
};

const androidReleaseConfigurationData = {
	pathToCertificate: "./myCertificate.p12",
	certificatePassword: "123456"
};

const platform = "android";
const buildConfiguration = "release";

tns.cloudBuildService.on("buildOutput", (data) => {
	console.log(data);
	/*
		Sample data object:
		{
			"pipe": "stdout",
			"data": "Add platform ios with runtime version 2.5.*"
		}
	*/
});

tns.cloudBuildService
	.build(projectSettings, platform, buildConfiguration, androidReleaseConfigurationData)
	.then(buildResult => console.log(buildResult))
	.catch(err => console.error(err));

• validateBuildProperties - validates all properties required for specific platform. This includes a check if current application identifier matches the CodeSigning identity for iOS operations, a check if the specified device identifier (in case it is passed) is included in the mobile provision, validation of the password, etc.
  

Definition:

/**
 * Validates the build properties for specified platform (Android or iOS).
 * The result promise is rejected with the error found. In case everything is correct, the promise is resolved.
 * @param {string} platform The mobile platform for which the application should be built: Android or iOS.
 * @param {string} buildConfiguration The build configuration - Debug or Release.
 * @param {string} projectId Application identifier of the project.
 * @param {IAndroidBuildData} androidBuildData Android speicific information for the build.
 * @param {IIOSBuildData} iOSBuildData iOS speicific information for the build.
 * @returns {Promise<void>}
 */
validateBuildProperties(platform: string,
	buildConfiguration: string,
	projectId: string,
	androidBuildData?: IAndroidBuildData,
	iOSBuildData?: IIOSBuildData): Promise<void>;

Detailed description of each parameter can be found here.
Usage:

const tns = require("nativescript");
const fs = require("fs");
const path = require("path");
const packageJsonContent = JSON.parse(fs.readFileSync("./package.json", "utf8").toString());

const projectId = packageJsonContent.nativescript.id;

const androidReleaseConfigurationData = {
	pathToCertificate: "./myCertificate.p12",
	certificatePassword: "123456"
};

const platform = "android";
const buildConfiguration = "release";

tns.cloudBuildService
	.validateBuildProperties(platform, buildConfiguration, projectId, androidReleaseConfigurationData)
	.then(buildResult => console.log("Data is valid"))
	.catch(err => console.error("Data is invalid:", err));

• getBuildOutputDirectory - Returns the path to the directory where the build output may be found.
  

Definition:

/**
 * Returns the path to the directory where the build output may be found.
 * @param {ICloudBuildOutputDirectoryOptions} options Options that are used to determine the build output directory.
 * @returns {string} The build output directory.
 */
getBuildOutputDirectory(options: ICloudBuildOutputDirectoryOptions): string;

Detailed description of the parameter can be found here.
Usage:

const tns = require("nativescript");
const cloudBuildOutputDirectory = tns.cloudBuildService
									.getBuildOutputDirectory({
										platform: "ios",
										projectDir: "/tmp/myProject"
										emulator: false
									});

Module cloudEmulatorLauncher

The cloudEmulatorLauncher provides a way for initial interaction with cloud emulators. You can call the following methods:

• startEmulator method - starts an cloud emulator and returns a url where an html page is located, containing an iframe with the actual emulator.
  Definition:

/**
 * Describes options that can be passed when starting a cloud emulator.
 */
interface ICloudEmulatorStartData {
	/**
	 * Path to the package file (.apk or .zip) to load - can either be a local path or a url.
	 */
	packageFile: string;
	/**
	 * Platform for the emulator - android or ios
	 */
	platform: string;
	/**
	 * Model of the emulator - for example nexus5, iphone5s, iphone6 - etc
	 */
	model: string;
}

/**
 * Describes service for initial interaction with cloud emulators.
 */
interface ICloudEmulatorLauncher {
	/**
	 * Starts a cloud emulator.
	 * @param {ICloudEmulatorStartData} data Options for starting emulator.
	 * @param optional {IConfigOptions} options The config options.
	 * @returns {string} A url containing an html page with the emulator inside an iframe. The url's host is localhost.
	 */
	startEmulator(data: ICloudEmulatorStartData): Promise<string>;
}

Usage:

const tns = require("nativescript");

tns.cloudEmulatorLauncher.startEmulator({
			packageFile: "test.apk",
			platform: "android",
			model: "nexus5"
		}).then(address => {
			console.log("address is", address);
			// http://localhost:56760/?publicKey=somekey&device=nexus5
		});

Module authenticationService

The authenticationService is used for authentication related operations (login, logout etc.). You can call the following methods

• login - Starts localhost server on which the login response will be returned. After that if there is options.openAction it will be used to open the login url. If this option is not defined the default opener will be used. After successful login returns the user information.
  

Definition:

/**
 * Opens login page and after successfull login saves the user information.
 * If options.openAction is provided, it will be used to open the login url instead of the default opener.
 * @param {ILoginOptions} options Optional settings for the login method.
 * @returns {Promise<IUser>} Returns the user information after successful login.
 */
login(options?: ILoginOptions): Promise<IUser>;

Detailed description of each parameter can be found here.
Usage:

const tns = require("nativescript");

tns.authenticationService
	.login()
	.then(userInfo => console.log(userInfo))
	.catch(err => console.error(err));

const tns = require("nativescript");
const childProcess = require("child_process");

const openAction = url => {
	const isWin = /^win/.test(process.platform);
	const openCommand = isWin ? "start" : "open";
	childProcess.execSync(`${openCommand} ${url}`);
};
const loginOptions = { openAction: openAction };

tns.authenticationService
	.login(loginOptions)
	.then(userInfo => console.log(userInfo))
	.catch(err => console.error(err));

• logout - Invalidates the current user authentication data.
  

Definition:

/**
 * Invalidates the current user authentication data.
 * If options.openAction is provided, it will be used to open the logout url instead of the default opener.
 * @param {IOpenActionOptions} options Optional settings for the logout method.
 * @returns {void}
 */
logout(options?: IOpenActionOptions): void;

Usage:

const tns = require("nativescript");

tns.authenticationService.logout();

const tns = require("nativescript");
const childProcess = require("child_process");

const openAction = url => {
	const isWin = /^win/.test(process.platform);
	const openCommand = isWin ? "start" : "open";
	childProcess.execSync(`${openCommand} ${url}`);
};
const logoutOptions = { openAction: openAction };

tns.authenticationService.logout(logoutOptions);

• isUserLoggedIn - Checks if the access token of the current user is valid. If it is - the method will return true. If it isn't - the method will try to issue new access token. If the method can't issue new token it will return false.
  

Definition:

/**
 * CheChecks if there is user info and the access token of the current user is valid. The method will try to issue new access token if the current is not valid.
 * @returns {Promise<boolean>} Returns true if the user is logged in.
 */
isUserLoggedIn(): Promise<boolean>;

Usage:

const tns = require("nativescript");

tns.authenticationService
	.isUserLoggedIn()
	.then(isLoggedIn => console.log(isLoggedIn))
	.catch(err => console.error(err));

• refreshCurrentUserToken - Uses the refresh token of the current user to issue new access token.
  

Definition:

/**
 * Uses the refresh token of the current user to issue new access token.
 */
refreshCurrentUserToken(): Promise<void>;

Usage:

const tns = require("nativescript");

tns.authenticationService.refreshCurrentUserToken()
	.then(() => console.log("Success"))
	.catch(err => console.error(err));

• cancelLogin - Stops the current login process and rejects the login promise with an error.
  

Definition:

/**
 * Stops the current login process and rejects the login promise with an error.
 * @returns {void}
 */
cancelLogin(): void;

Usage:

const tns = require("nativescript");

tns.authenticationService
	.login()
	.then(userInfo => console.log(userInfo))
	.catch(err => console.error(err));

tns.authenticationService.cancelLogin();

Interfaces:

interface IUser {
	email: string;
	firstName: string;
	lastName: string;
}

interface IAuthenticationService {
	/**
	 * Uses username and password for login and after successfull login saves the user information.
	 * @param {string} username The username of the user.
	 * @param {string} password The password of the user.
	 * @returns {Promise<IUser>} Returns the user information after successful login.
	 */
	devLogin(username: string, password: string): Promise<IUser>;

	/**
	 * Opens login page and after successfull login saves the user information.
	 * If options.openAction is provided, it will be used to open the login url instead of the default opener.
	 * @param {ILoginOptions} options Optional settings for the login method.
	 * @returns {Promise<IUser>} Returns the user information after successful login.
	 */
	login(options?: ILoginOptions): Promise<IUser>;


	/**
	 * Invalidates the current user authentication data.
	 * If options.openAction is provided, it will be used to open the logout url instead of the default opener.
	 * @param {IOpenActionOptions} options Optional settings for the logout method.
	 * @returns {void}
	 */
	logout(options?: IOpenActionOptions): void;

	/**
	 * Uses the refresh token of the current user to issue new access token.
	 */
	refreshCurrentUserToken(): Promise<void>;

	/**
	 * Checks the token state of the current user.
	 * @returns {Promise<ITokenState>} Returns the token state
	 */
	getCurrentUserTokenState(): Promise<ITokenState>;

	/**
	 * Stops the current login process and rejects the login promise with an error.
	 * @returns {void}
	 */
	cancelLogin(): void;
}

interface IOpenActionOptions {
	/**
	 * Action which will receive url and decide how to open it.
	 */
	openAction?: (url: string) => void;
}

interface ILoginOptions extends IOpenActionOptions {
	/**
	 * Sets the ammount of time which the login method will wait for login response in non-interactive terminal.
	 */
	timeout?: string;
}

interface ITokenState {
	/**
	 * True if the access token is valid.
	 */
	isTokenValid: boolean;

	/**
	 * The expiration timestamp. (1494.923982727)
	 */
	expirationTimestamp: number;
}

Module userService

The userService is used to get information aboud the current user or modify it. You can call the following methods

• hasUser - Checks if there is user information.
  

Definition:

/**
 * Checks if there is user information.
 * @returns {boolean} Returns true if there is user information.
 */
hasUser(): boolean;

Usage:

const tns = require("nativescript");

const hasUser = tns.userService.hasUser();
console.log(hasUser);

• getUser - Returns the current user information.
  

Definition:

/**
 * Returns the current user information.
 * @returns {IUser} The current user information.
 */
getUser(): IUser;

Usage:

const tns = require("nativescript");

const user = tns.userService.getUser();
console.log(user);

Sample result for user will be:

{
	"email": "[e-mail]",
	"firstName": "First",
	"lastName": "Last"
}

• getUserData - Returns the user information and the authentication data for the current user.
  

Definition:

/**
 * Returns the user information and the authentication data for the current user.
 * @returns {IUserData} The user information and the authentication data for the current user.
 */
getUserData(): IUserData;

Usage:

const tns = require("nativescript");

const userData = tns.userService.getUserData();
console.log(userData);

Sample result for userData will be:

{
	"accessToken": "some token",
	"refreshToken": "some refresh token",
	"userInfo": {
		"email": "[e-mail]",
		"firstName": "First",
		"lastName": "Last"
	}
}

• setUserData - Sets the user information and the authentication data for the current user.
  

Definition:

/**
 * Sets the user information and the authentication data for the current user.
 * @param {IUserdata} userData The user data to set.
 * @returns {void}
 */
setUserData(userData: IUserData): void;

Detailed description of each parameter can be found here.

Usage:

const tns = require("nativescript");

const userData = {
	accessToken: "some token",
	refreshToken: "some refresh token",
	userInfo: {
		email: "[e-mail]",
		firstName: "First",
		lastName: "Last"
	}
};

tns.userService.setUserData(userData);

• setToken - Sets only the token of the current user.
  

Definition:

/**
 * Sets only the token of the current user.
 * @param {ITokenData} token The token data.
 * @returns void
 */
setToken(token: ITokenData): void;

Detailed description of each parameter can be found here.

Usage:

const tns = require("nativescript");

const token = {
	accessToken: "some token"
};

tns.userService.setToken(token);

• clearUserData - Removes the current user data.
  

Definition:

/**
 * Removes the current user data.
 */
clearUserData(): void;

Usage:

const tns = require("nativescript");

tns.userService.clearUserData();

• getUserAvatar - Return the URL where the avatar picture can be downloaded from.
  

Definition:

/**
* Return the URL where the avatar picture can be downloaded from.
* @returns {Promise<string>} Return the URL where the avatar picture can be downloaded from. It will return null if the user does not have avatar or it is not logged in.
*/
getUserAvatar(): Promise<string>;

Usage:

const tns = require("nativescript");

tns.userService.hasUser()
	.then(userAvatar => console.log(userAvatar));

Interfaces:

interface IUserService {
	/**
	 * Checks if there is user information.
	 * @returns {boolean} Returns true if there is user information.
	 */
	hasUser(): boolean;

	/**
	 * Returns the current user information.
	 * @returns {IUser} The current user information.
	 */
	getUser(): IUser;

	/**
	 * Returns the user information and the authentication data for the current user.
	 * @returns {IUserData} The user information and the authentication data for the current user.
	 */
	getUserData(): IUserData;

	/**
	 * Sets the user information and the authentication data for the current user.
	 * @param {IUserdata} userData The user data to set.
	 * @returns {void}
	 */
	setUserData(userData: IUserData): void;

	/**
	 * Sets only the token of the current user.
	 * @param {ITokenData} token The token data.
	 * @returns void
	 */
	setToken(token: ITokenData): void;

	/**
	 * Removes the current user data.
	 */
	clearUserData(): void;

	/**
	 * Return the URL where the avatar picture can be downloaded from.
	 * @returns {Promise<string>} Return the URL where the avatar picture can be downloaded from. It will return null if the user does not have avatar or it is not logged in.
	 */
	getUserAvatar(): Promise<string>;
}

Development

The project is written in TypeScript. After cloning it, you can set it up by executing the following commands in your terminal:

• $ npm i --ignore-scripts - NOTE: --ignore-scripts is a must.
• $ npm i -g grunt-cli (only in case you do not have it installed globally)
• $ grunt test (first execution of this command might take a little bit longer, consecutive calls will work much faster)

After that you can make changes in the code. In order to transpile them, just execute:

• $ grunt

You can pack a new version of the library by executing:

• $ grunt pack