@prismicio/e2e-tests-utils 1.2.0 → 1.3.1

package/src/clients/contentApi.ts

@@ -0,0 +1,235 @@
+import { APIResponse, request } from "@playwright/test";
+
+export interface ContentApiError {
+	type: string;
+	message: string;
+}
+export interface ContentApiSearchResponse {
+	page: number;
+	results_per_page: number;
+	results_size: number;
+	total_results_size: number;
+	total_pages: number;
+	next_page: string | null;
+	prev_page: string | null;
+	results: ContentApiDocument[];
+}
+
+export interface ContentApiDocument {
+	id: string;
+	uid: string | null;
+	url: string | null;
+	type: string;
+	href: string;
+	tags: string[];
+	first_publication_date: string;
+	last_publication_date: string;
+	slugs: string[];
+	linked_documents: unknown[];
+	lang: string;
+	alternate_languages: string[];
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	data: Record<string, any>;
+}
+
+export interface ContentApiGraphQLResponse {
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	data: Record<string, any>;
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	errors?: { message: string; locations: any }[];
+}
+
+export interface ContentApiRef {
+	id: string;
+	ref: string;
+	label: string;
+	isMasterRef?: boolean;
+}
+
+interface ContentApiRepoConfigResponse {
+	refs: ContentApiRef[];
+	bookmarks: Record<string, unknown>;
+	types: Record<string, string>;
+	languages: {
+		id: string;
+		name: string;
+		is_master: boolean;
+	}[];
+	oauth_initiate: string;
+	oauth_token: string;
+	tags: string[];
+	license: string;
+	version: string;
+}
+
+type SearchQueryParams = {
+	ref?: string;
+	query?: string;
+	q?: string;
+	graphQuery?: string;
+	fetchLinks?: string;
+	orderings?: string;
+	pageSize?: number;
+	page?: number;
+	lang?: string;
+	after?: string;
+	routes?: string;
+};
+
+type ApiVersions = "v1" | "v2";
+
+/**
+ * Client to query the Prismic content api. Uses Playwright to benefit from
+ * network request traces in your reports. The @prismicio/client package could
+ * have been used but had too many abstractions (caching, error handling) that
+ * we didn't want for test execution. See api docs:
+ * https://prismic.io/docs/rest-api-technical-reference
+ */
+export class ContentApiClient {
+	#version: ApiVersions;
+	#accessToken: string | undefined;
+
+	/**
+	 * @example To instantiate the class:
+	 *
+	 * ```js
+	 * new ContentApiClient("https://my-repo.cdn.prismic.io", {
+	 * 	version: "v2",
+	 * 	accessToken: "my-secret-token",
+	 * });
+	 * ```
+	 *
+	 * @param baseURL - the api base URL like https://my-repo.cdn.prismic.io
+	 * @param config - Optional configuration
+	 *
+	 *   - {@link config.version}: Api version, default is "v2"
+	 *   - {@link config.accessToken}: Access token for the content api -
+	 *       https://prismic.io/docs/access-token
+	 */
+	constructor(
+		private readonly baseURL: string,
+		config: { version?: ApiVersions; accessToken?: string } = {},
+	) {
+		this.#version = config.version || "v2";
+		this.#accessToken = config.accessToken;
+	}
+
+	#context() {
+		return request.newContext({
+			baseURL: this.baseURL,
+			// reset any Authorization header set globally with Playwright
+			// didn't find a way to delete it
+			extraHTTPHeaders: { Authorization: "" },
+		});
+	}
+
+	async get(
+		path: string,
+		params?: SearchQueryParams,
+		headers?: Record<string, string>,
+	): Promise<APIResponse> {
+		const context = await this.#context();
+		const securityParams = {
+			...(this.#accessToken ? { access_token: this.#accessToken } : {}),
+		};
+
+		return context.get(path, {
+			params: { ...securityParams, ...params },
+			headers,
+		});
+	}
+
+	async getAsJson<T>(
+		url: string,
+		params?: SearchQueryParams,
+		headers?: Record<string, string>,
+	): Promise<T> {
+		const response = await this.get(url, params, headers);
+
+		return response.json() as T;
+	}
+
+	/** Query the graphql api - https://prismic.io/docs/graphql-technical-reference */
+	async graphql(
+		ref: string,
+		query: string,
+	): Promise<ContentApiGraphQLResponse> {
+		return this.getAsJson<ContentApiGraphQLResponse>(
+			"/graphql",
+			{ query },
+			{ "Prismic-ref": ref },
+		);
+	}
+
+	async getRefs(): Promise<ContentApiRef[]> {
+		const data = await this.getAsJson<ContentApiRepoConfigResponse>(
+			`/api/${this.#version}`,
+		);
+
+		return data.refs;
+	}
+
+	async getMasterRef(): Promise<string> {
+		const refs = await this.getRefs();
+
+		const masterRef = refs.find(({ isMasterRef }) => isMasterRef === true);
+		if (!masterRef) {
+			throw "No master ref found";
+		}
+
+		return masterRef.ref;
+	}
+
+	async getRefByReleaseID(releaseID: string): Promise<string> {
+		const refs = await this.getRefs();
+		const release = refs.find(({ id }) => id === releaseID);
+		if (!release) {
+			throw `No ref found for release ${releaseID}`;
+		}
+
+		return release.ref;
+	}
+
+	/** Search documents from the `/api/v<version>/documents/search` endpoint. */
+	async search(filters?: SearchQueryParams): Promise<ContentApiSearchResponse> {
+		let ref = filters?.ref;
+		if (!ref) {
+			ref = await this.getMasterRef();
+		}
+
+		return this.getAsJson<ContentApiSearchResponse>(
+			`/api/${this.#version}/documents/search`,
+			{
+				...filters,
+				ref,
+			},
+		);
+	}
+
+	/**
+	 * Search for a single document by its it, using the
+	 * `/api/v<version>/documents/search` endpoint and a default filter.
+	 */
+	async searchByID(
+		id: string,
+		filters?: SearchQueryParams,
+	): Promise<ContentApiSearchResponse> {
+		return this.search({ ...filters, q: `[[at(document.id, "${id}")]]` });
+	}
+
+	/** Retrieve a single document or undefined if not found. */
+	async getDocumentByID(
+		id: string,
+		filters?: SearchQueryParams,
+	): Promise<ContentApiDocument | undefined> {
+		const data = await this.searchByID(id, filters);
+		switch (data.results_size) {
+			case 0:
+				return;
+			case 1:
+				return data.results[0];
+			default:
+				throw new Error(`Too many documents returned with the same id ${id}`);
+		}
+	}
+}

package/src/clients/coreApi.ts

@@ -12,6 +12,7 @@ type Language = {
 
 export type CoreClient = {
 	getLanguages(): Promise<Language[]>;
+	publishDraft(documentId: string): Promise<void>;
 };
 
 /** Client for interacting with the core API */
@@ -41,7 +42,7 @@ export const createCoreApiClient = (
 			"core/repository",
 		);
 
-		if (![200].includes(result.status) || !result.data.languages) {
+		if (200 !== result.status || !result.data.languages) {
 			logHttpResponse(result);
 			throw new Error("Could not get languages from the core api.");
 		}
@@ -51,7 +52,19 @@ export const createCoreApiClient = (
 		return result.data.languages;
 	}
 
+	async function publishDraft(documentId: string): Promise<void> {
+		const result = await client.patch(`core/documents/${documentId}/draft`, {
+			status: "published",
+		});
+
+		if (204 !== result.status) {
+			logHttpResponse(result);
+			throw new Error(`Could not publish document with id ${documentId}`);
+		}
+	}
+
 	return {
 		getLanguages,
+		publishDraft,
 	};
 };

package/src/clients/manageV2.ts

@@ -0,0 +1,178 @@
+import axios, { AxiosInstance, AxiosResponse } from "axios";
+import jwt from "jsonwebtoken";
+
+import { ManageV2Config } from "../types";
+
+import { extractCookie } from "../utils/cookies";
+
+const ManageV2StaticAuthor = "prismic-e2e-tests-utils";
+
+/**
+ * Client for interacting with ManageV2 routes to perform operations on
+ * repositories.
+ */
+export class ManageV2Client {
+	readonly client: AxiosInstance; // Not private to have it available on tests
+	private token: string | null = null;
+
+	/**
+	 * @param baseURL - The base URL of the Wroom app. ex: https://prismic.io
+	 * @param config - ManageV2 configuration variable to call ManageV2.
+	 */
+	constructor(baseUrl: string, config?: ManageV2Config | undefined) {
+		this.token = config ? this.generateToken(config) : null;
+
+		this.client = axios.create({
+			baseURL: `${baseUrl}/manageroutes/`,
+			withCredentials: true,
+			validateStatus: () => true,
+			headers: {
+				"User-Agent": "prismic-cli/prismic-e2e-tests-utils",
+				Authorization: `Bearer ${this.token}`,
+			},
+		});
+
+		// cookies are not forwarded automatically in a non-browser env
+		this.client.interceptors.response.use((response) => {
+			const cookies = response.headers["set-cookie"];
+			if (cookies && extractCookie(cookies, "SESSION")) {
+				this.client.defaults.headers["Cookie"] = cookies;
+			}
+
+			return response;
+		});
+	}
+
+	/**
+	 * The function generates a JWT token using the provided configuration
+	 * parameters.
+	 *
+	 * @param {ManageV2Config} config - The `config` parameter in the
+	 *   `generateToken` function is of type `ManageV2Config`. It contains the
+	 *   following properties:
+	 *
+	 * @returns A JSON Web Token (JWT) is being returned by the `generateToken`
+	 *   function. The token is signed using the provided `config.secret` with the
+	 *   HS256 algorithm and includes the specified audience and issuer values.
+	 */
+	private generateToken(config: ManageV2Config): string {
+		return jwt.sign({}, config.secret, {
+			algorithm: "HS256",
+			audience: config.audience,
+			issuer: "prismic.io",
+		});
+	}
+
+	/**
+	 * The function `assertTokenExist` checks if a token exists before executing a
+	 * given function.
+	 *
+	 * @param f - The `assertTokenExist` function takes a function `f` as a
+	 *   parameter. This function `f` should accept a parameter of type
+	 *   `Parameters` and return a Promise that resolves to an AxiosResponse. The
+	 *   `assertTokenExist` function ensures that a token is not null before
+	 *   calling the provided
+	 *
+	 * @returns A function is being returned that takes a parameter of type
+	 *   Parameters and checks if the token is null. If the token is null, an
+	 *   error is thrown. Otherwise, the function f is called with the provided
+	 *   parameters.
+	 */
+	private assertTokenExist<Parameters>(
+		f: (_: Parameters) => Promise<AxiosResponse>,
+	) {
+		return (params: Parameters) => {
+			if (this.token === null) {
+				throw new Error(
+					"Undefined configuration for ManageV2 while trying to use it's routes",
+				);
+			} else {
+				return f(params);
+			}
+		};
+	}
+
+	getBaseURL(): string {
+		return this.client.getUri();
+	}
+
+	/**
+	 * The function `toggleRolePerLocal` enable or disable the role per local
+	 * feature
+	 *
+	 * @param repository - The Repository name
+	 * @param enabled - The feature new status
+	 */
+	toggleRolePerLocal = this.assertTokenExist(
+		(params: { repository: string; enabled: boolean }) => {
+			return this.client.post("/repository/toggleRolesPerLocale", {
+				domain: params.repository,
+				enabled: params.enabled,
+				author: ManageV2StaticAuthor,
+			});
+		},
+	);
+
+	/**
+	 * The function `changePlan` changes the plan of a repository the database
+	 *
+	 * @param repository - The Repository name
+	 * @param newPlanId - The new planId
+	 * @param bypassManualBilling - Beware that using this will not verify that
+	 *   the database and Stripe are in sync
+	 */
+	changePlan = this.assertTokenExist(
+		({
+			repository,
+			newPlanId,
+			bypassManualBilling = false,
+		}: {
+			repository: string;
+			newPlanId: string;
+			bypassManualBilling?: boolean;
+		}) => {
+			return this.client.post(
+				`/repository/changePlan?bypassManualBilling=${bypassManualBilling}`,
+				{
+					domain: repository,
+					newPlan: newPlanId,
+					author: ManageV2StaticAuthor,
+				},
+			);
+		},
+	);
+
+	/**
+	 * The function `addUserToRepository` adds a user corresponding to the email
+	 * to the given repository
+	 *
+	 * @param repository - The Repository name
+	 * @param email - The user email
+	 */
+	addUserToRepository = this.assertTokenExist(
+		({ repository, email }: { repository: string; email: string }) => {
+			return this.client.post("/repository/addUser", {
+				domain: repository,
+				email: email,
+				author: ManageV2StaticAuthor,
+			});
+		},
+	);
+
+	/**
+	 * The function `removeUserFromRepository` removes a user corresponding to the
+	 * email from the given repository
+	 *
+	 * @param repository - The Repository name
+	 * @param email - The user email
+	 */
+	removeUserFromRepository = this.assertTokenExist(
+		({ repository, email }: { repository: string; email: string }) => {
+			return this.client.post("/repository/removeUser", {
+				domain: repository,
+				email: email,
+				author: ManageV2StaticAuthor,
+			});
+		},
+	);
+}

package/src/clients/migrationApi.ts

@@ -0,0 +1,69 @@
+import axios, { AxiosInstance } from "axios";
+
+import { logHttpResponse } from "../utils/log";
+
+import { AuthenticationClient } from "./authenticationApi";
+
+export type MigrationClient = {
+	createDocument(data: DocumentPayload): Promise<DocumentResponse>;
+};
+
+export type DocumentPayload = {
+	uid?: string | null;
+	lang: string;
+	title: string;
+	tags?: string[];
+	alternate_language_id?: string;
+	data: Record<string, unknown>;
+};
+
+export type DocumentResponse = {
+	id: string;
+	type: string;
+	lang: string;
+	title: string;
+	uid?: string;
+};
+
+export const createMigrationApiClient = (
+	baseURL: string,
+	repository: string,
+	authClient: AuthenticationClient,
+): MigrationClient => {
+	const client: AxiosInstance = axios.create({
+		baseURL,
+		headers: {
+			repository,
+		},
+		validateStatus: () => true, // Don't throw on 4XX errors
+	});
+
+	// Add an interceptor to authenticate requests
+	client.interceptors.request.use(async (config) => {
+		const auth = "Authorization";
+		if (!config.headers[auth]) {
+			const token = await authClient.getToken();
+			config.headers[auth] = `Bearer ${token}`;
+		}
+		config.headers["repository"] = repository;
+
+		return config;
+	});
+
+	async function createDocument(
+		data: DocumentPayload,
+	): Promise<DocumentResponse> {
+		const result = await client.post<DocumentResponse>("/documents", data);
+
+		if (201 !== result.status) {
+			logHttpResponse(result);
+			throw new Error("Could not create a document with the migration api.");
+		}
+
+		return result.data;
+	}
+
+	return {
+		createDocument,
+	};
+};

package/src/clients/wroom.ts

@@ -1,6 +1,6 @@
 import axios, { AxiosInstance, AxiosResponse } from "axios";
 
-import { Credentials } from "../types";
+import { AuthConfig } from "../types";
 
 import { extractCookie } from "../utils/cookies";
 import { logHttpResponse, logger } from "../utils/log";
@@ -20,7 +20,7 @@ export class WroomClient {
 	 */
 	constructor(
 		baseURL: string,
-		private readonly auth: Credentials,
+		private readonly auth: AuthConfig,
 	) {
 		this.client = axios.create({
 			baseURL,
@@ -84,6 +84,46 @@ export class WroomClient {
 		return response;
 	}
 
+	/**
+	 * Update the role of a user in the repository
+	 *
+	 * @param {string} repository - The repository name
+	 * @param {string} email - The email of the user
+	 * @param {string} role - The new role to be given
+	 *
+	 * @returns The Axios Reponse
+	 */
+	async updateRole(
+		repository: string,
+		email: string,
+		role: string,
+	): Promise<AxiosResponse> {
+		const params = new URLSearchParams({ email, profile: role });
+		const path = `/app/settings/users/profiles?${params.toString()}`;
+
+		return this.post(repository, path);
+	}
+
+	/**
+	 * Update the role of a user in the repository
+	 *
+	 * @param {string} repository - The repository name
+	 * @param {string} email - The email of the user
+	 * @param {string} rolePerLocal - The role per local object
+	 *
+	 * @returns The Axios Reponse
+	 */
+	async updateRolePerLocal(
+		repository: string,
+		email: string,
+		rolePerLocal: Record<string, string>,
+	): Promise<AxiosResponse> {
+		const params = new URLSearchParams({ email });
+		const path = `/app/settings/users/rolesperlocale?${params.toString()}`;
+
+		return this.post(repository, path, rolePerLocal);
+	}
+
 	/**
 	 * Authenticate Wroom to call Wroom unofficial endpoints.
 	 *

package/src/index.ts

@@ -1,3 +1,5 @@
 export * from "./managers/repositories";
 export * from "./managers/repository";
+export * from "./clients/contentApi";
+export * from "./clients/migrationApi";
 export * from "./types";