@prismicio/manager 0.0.1

package/src/managers/telemetry/TelemetryManager.ts

@@ -0,0 +1,227 @@
+import { randomUUID } from "node:crypto";
+
+import {
+	Experiment,
+	RemoteEvaluationClient,
+	Variant,
+} from "@amplitude/experiment-node-server";
+import { Analytics, TrackParams } from "@segment/analytics-node";
+
+import { PrismicUserProfile } from "../../auth/PrismicAuthManager";
+import { API_TOKENS } from "../../constants/API_TOKENS";
+import { readPrismicrc } from "../../lib/prismicrc";
+import { BaseManager } from "../BaseManager";
+
+import {
+	HumanSegmentEventType,
+	HumanSegmentEventTypes,
+	SegmentEvents,
+} from "./types";
+
+type TelemetryManagerInitTelemetryArgs = {
+	appName: string;
+	appVersion: string;
+};
+
+type TelemetryManagerTrackArgs = SegmentEvents;
+
+type TelemetryManagerContext = {
+	app: {
+		name: string;
+		version: string;
+	};
+};
+
+function assertTelemetryInitialized(
+	segmentClient: (() => Analytics) | undefined,
+): asserts segmentClient is NonNullable<typeof segmentClient> {
+	if (segmentClient === undefined) {
+		throw new Error(
+			"Telemetry has not been initialized. Run `PrismicManager.telemetry.prototype.initTelemetry()` before re-calling this method.",
+		);
+	}
+}
+
+export class TelemetryManager extends BaseManager {
+	private _segmentClient: (() => Analytics) | undefined = undefined;
+	private _anonymousID: string | undefined = undefined;
+	private _userID: string | undefined = undefined;
+	private _context: TelemetryManagerContext | undefined = undefined;
+	private _experiment: RemoteEvaluationClient | undefined = undefined;
+
+	async initTelemetry(args: TelemetryManagerInitTelemetryArgs): Promise<void> {
+		const isTelemetryEnabled = await this.checkIsTelemetryEnabled();
+
+		this._segmentClient = () => {
+			const analytics = new Analytics({
+				writeKey: API_TOKENS.SegmentKey,
+				// Since it's a local app, we do not benefit from event batching the way a server would normally do, all tracking event will be awaited.
+				maxEventsInBatch: 1,
+				disable: !isTelemetryEnabled,
+			});
+
+			analytics.on("error", (error) => {
+				// noop - We don't care if the tracking event
+				// failed. Some users or networks intentionally
+				// block Segment, so we can't block the app if
+				// a tracking event is unsuccessful.
+				if (import.meta.env.DEV) {
+					console.error(`An error occurred with Segment`, error);
+				}
+			});
+
+			return analytics;
+		};
+
+		if (isTelemetryEnabled) {
+			this.initExperiment();
+		}
+
+		this._anonymousID = randomUUID();
+		this._context = { app: { name: args.appName, version: args.appVersion } };
+	}
+
+	async track(args: TelemetryManagerTrackArgs): Promise<void> {
+		const { event, repository, ...properties } = args;
+		let repositoryName = repository;
+
+		if (repositoryName === undefined) {
+			try {
+				repositoryName = await this.project.getRepositoryName();
+			} catch {
+				// noop, happen only when the user is not in a project
+			}
+		}
+
+		const payload: {
+			event: HumanSegmentEventTypes;
+			userId?: string;
+			anonymousId?: string;
+			properties?: Record<string, unknown>;
+			context?: Partial<TelemetryManagerContext> & {
+				groupId?: {
+					Repository?: string;
+				};
+			};
+		} = {
+			event: HumanSegmentEventType[event],
+			properties: {
+				nodeVersion: process.versions.node,
+				...properties,
+			},
+			context: { ...this._context },
+		};
+
+		// Always keep an anonymous ID to keep track of the user before and after identification
+		payload.anonymousId = this._anonymousID;
+
+		if (this._userID) {
+			payload.userId = this._userID;
+		}
+
+		if (repositoryName) {
+			payload.context ||= {};
+			payload.context.groupId ||= {};
+			payload.context.groupId.Repository = repositoryName;
+		}
+
+		return new Promise((resolve) => {
+			assertTelemetryInitialized(this._segmentClient);
+
+			this._segmentClient().track(
+				payload as TrackParams,
+				(maybeError?: unknown) => {
+					if (maybeError && import.meta.env.DEV) {
+						console.warn(
+							`An error occurred during Segment tracking`,
+							maybeError,
+						);
+					}
+
+					resolve();
+				},
+			);
+		});
+	}
+
+	async identify(userProfile: PrismicUserProfile): Promise<void> {
+		const payload = {
+			userId: userProfile.shortId,
+			anonymousId: this._anonymousID,
+			integrations: {
+				Intercom: {
+					user_hash: userProfile.intercomHash,
+				},
+			},
+			context: { ...this._context },
+		};
+
+		this._userID = userProfile.shortId;
+
+		return new Promise((resolve) => {
+			assertTelemetryInitialized(this._segmentClient);
+
+			this._segmentClient().identify(payload, (maybeError?: unknown) => {
+				if (maybeError && import.meta.env.DEV) {
+					console.warn(`An error occurred during Segment identify`, maybeError);
+				}
+
+				resolve();
+			});
+		});
+	}
+
+	async checkIsTelemetryEnabled(): Promise<boolean> {
+		let root: string;
+		try {
+			root = await this.project
+				.getRoot()
+				.catch(() => this.project.suggestRoot());
+
+			return readPrismicrc(root).telemetry !== false;
+		} catch {
+			return true;
+		}
+	}
+
+	private initExperiment(): void {
+		try {
+			this._experiment = Experiment.initializeRemote(API_TOKENS.AmplitudeKey);
+		} catch (error) {
+			if (import.meta.env.DEV) {
+				console.error("Error initializing experiment", error);
+			}
+		}
+	}
+
+	async getExperimentVariant(variantKey: string): Promise<Variant | undefined> {
+		if (this._experiment) {
+			try {
+				const repositoryName = await this.project.getRepositoryName();
+				const variants = await this._experiment.fetchV2({
+					user_id: this._userID,
+					user_properties: {
+						Repository: repositoryName,
+					},
+				});
+
+				const variantValue = variants[variantKey].value;
+				if (variantValue) {
+					await this.track({
+						event: "experiment:exposure",
+						flag_key: variantKey,
+						variant: variantValue,
+					});
+				}
+
+				return variants[variantKey];
+			} catch (error) {
+				if (import.meta.env.DEV) {
+					console.error("Error fetching experiment variant", error);
+				}
+			}
+		}
+
+		return undefined;
+	}
+}

package/src/managers/telemetry/types.ts

@@ -0,0 +1,62 @@
+export type { Variant } from "@amplitude/experiment-node-server";
+
+export const SegmentEventType = {
+	experiment_exposure: "experiment:exposure",
+	prismic_cli_start: "prismic-cli:start",
+	prismic_cli_end: "prismic-cli:end",
+} as const;
+type SegmentEventTypes =
+	(typeof SegmentEventType)[keyof typeof SegmentEventType];
+
+export const HumanSegmentEventType = {
+	[SegmentEventType.experiment_exposure]: "$exposure",
+	[SegmentEventType.prismic_cli_start]: "Prismic CLI Start",
+	[SegmentEventType.prismic_cli_end]: "Prismic CLI End",
+} as const;
+
+export type HumanSegmentEventTypes =
+	(typeof HumanSegmentEventType)[keyof typeof HumanSegmentEventType];
+
+type SegmentEvent<
+	TType extends SegmentEventTypes,
+	TProperties extends Record<string, unknown> | void = void,
+> = TProperties extends void
+	? {
+			event: TType;
+			repository?: string;
+		}
+	: {
+			event: TType;
+			repository?: string;
+		} & TProperties;
+
+type ExperimentExposure = SegmentEvent<
+	typeof SegmentEventType.experiment_exposure,
+	{
+		flag_key: string;
+		variant: string;
+	}
+>;
+
+type PrismicCLIStartSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.prismic_cli_start,
+	{
+		commandType: "init" | "sync";
+		fullCommand: string;
+	}
+>;
+
+type PrismicCLIEndSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.prismic_cli_end,
+	{
+		commandType: "init" | "sync";
+		success: boolean;
+		error?: string;
+		fullCommand: string;
+	}
+>;
+
+export type SegmentEvents =
+	| ExperimentExposure
+	| PrismicCLIStartSegmentEvent
+	| PrismicCLIEndSegmentEvent;

package/src/managers/user/UserManager.ts

@@ -0,0 +1,35 @@
+import { PrismicError } from "../../errors";
+import { BaseManager } from "../BaseManager";
+import { PrismicManager } from "../PrismicManager";
+
+export class UserManager extends BaseManager {
+	constructor(prismicManager: PrismicManager) {
+		super(prismicManager);
+
+		if (!prismicManager.getPrismicAuthManager()) {
+			throw new PrismicError(
+				"PrismicManager._prismicAuthManager must be set with a PrismicAuthManager instance before instantiating UserManager.",
+			);
+		}
+	}
+
+	login = this.prismicAuthManager.login.bind(this.prismicAuthManager);
+	getLoginSessionInfo = this.prismicAuthManager.getLoginSessionInfo.bind(
+		this.prismicAuthManager,
+	);
+	nodeLoginSession = this.prismicAuthManager.nodeLoginSession.bind(
+		this.prismicAuthManager,
+	);
+	logout = this.prismicAuthManager.logout.bind(this.prismicAuthManager);
+	checkIsLoggedIn = this.prismicAuthManager.checkIsLoggedIn.bind(
+		this.prismicAuthManager,
+	);
+	refreshAuthenticationToken =
+		this.prismicAuthManager.refreshAuthenticationToken.bind(
+			this.prismicAuthManager,
+		);
+	getAuthenticationToken = this.prismicAuthManager.getAuthenticationToken.bind(
+		this.prismicAuthManager,
+	);
+	getProfile = this.prismicAuthManager.getProfile.bind(this.prismicAuthManager);
+}

package/src/managers/versions/VersionsManager.ts

@@ -0,0 +1,53 @@
+import semver from "semver";
+
+import { PRISMIC_CLI_NPM_PACKAGE_NAME } from "../../constants/PRISMIC_CLI_NPM_PACKAGE_NAME";
+import { fetchNPMPackageVersions } from "../../lib/fetchNPMPackageVersions";
+import { BaseManager } from "../BaseManager";
+
+type CheckCLIVersionLatestArgs = {
+	currentVersion: string;
+};
+
+export class VersionsManager extends BaseManager {
+	/**
+	 * Fetches the latest stable version of the Prismic CLI from npm.
+	 *
+	 * @returns The latest stable version string.
+	 */
+	async getLatestCLIVersion(): Promise<string> {
+		const versions = await fetchNPMPackageVersions({
+			packageName: PRISMIC_CLI_NPM_PACKAGE_NAME,
+		});
+
+		// Filter out pre-release versions (alpha, beta, rc, etc.)
+		const stableVersions = versions.filter((version) => {
+			return semver.prerelease(version) === null;
+		});
+
+		if (stableVersions.length === 0) {
+			throw new Error(
+				"No stable versions found for the package on the npm registry.",
+			);
+		}
+
+		// Sort versions in descending order and return the latest
+		const sortedVersions = semver.rsort(stableVersions);
+
+		return sortedVersions[0];
+	}
+
+	/**
+	 * Checks if the current CLI version is the latest available version.
+	 *
+	 * @param args - Arguments object containing the current version.
+	 *
+	 * @returns `true` if the current version is the latest, `false` otherwise.
+	 */
+	async checkIsCLIVersionLatest(
+		args: CheckCLIVersionLatestArgs,
+	): Promise<boolean> {
+		const latestVersion = await this.getLatestCLIVersion();
+
+		return semver.eq(args.currentVersion, latestVersion);
+	}
+}

package/src/types.ts

@@ -0,0 +1,41 @@
+import { detect as niDetect } from "@antfu/ni";
+import { HookError, PluginOptions } from "@prismicio/plugin-kit";
+
+export type PackageManager = NonNullable<Awaited<ReturnType<typeof niDetect>>>;
+export type { APIEndpoints } from "./constants/API_ENDPOINTS";
+
+/**
+ * A string, object, or instance representing a registered plugin.
+ *
+ * @typeParam TPluginOptions - User-provided options for the plugin.
+ */
+export type PrismicConfigPluginRegistration<
+	TPluginOptions extends PluginOptions = PluginOptions,
+> =
+	| string
+	| {
+			resolve: string;
+			options?: TPluginOptions;
+	  };
+
+/**
+ * Prismic configuration from `prismic.config.js`.
+ */
+export type PrismicConfig = {
+	apiEndpoint?: string;
+	repositoryName: string;
+	libraries?: string[];
+	adapter: PrismicConfigPluginRegistration;
+};
+
+export type OnlyHookErrors<
+	THookResult extends
+		| { errors: HookError[] }
+		| Promise<{ errors: HookError[] }>,
+> = Pick<Awaited<THookResult>, "errors">;
+
+export type S3ACL = {
+	uploadEndpoint: string;
+	requiredFormDataFields: Record<string, string>;
+	imgixEndpoint: string;
+};