@slicemachine/manager 0.1.1-dev-plugins.3

package/src/managers/telemetry/TelemetryManager.ts

@@ -0,0 +1,142 @@
+import { randomUUID } from "node:crypto";
+
+import SegmentClient from "analytics-node";
+
+import { readPrismicrc } from "../../lib/prismicrc";
+
+import { API_TOKENS } from "../../constants/API_TOKENS";
+
+import { BaseManager } from "../BaseManager";
+
+import {
+	HumanSegmentEventType,
+	HumanSegmentEventTypes,
+	SegmentEvents,
+} from "./types";
+
+type TelemetryManagerTrackArgs = SegmentEvents;
+
+type TelemetryManagerIdentifyArgs = {
+	userID: string;
+	intercomHash: string;
+};
+
+function assertTelemetryInitialized(
+	segmentClient: SegmentClient | undefined,
+): asserts segmentClient is NonNullable<typeof segmentClient> {
+	if (segmentClient == undefined) {
+		throw new Error(
+			"Telemetry has not been initialized. Run `SliceMachineManager.telemetry.prototype.initTelemetry()` before re-calling this method.",
+		);
+	}
+}
+
+export class TelemetryManager extends BaseManager {
+	private _enabled = false;
+	private _segmentClient: SegmentClient | undefined = undefined;
+	private _anonymousID: string | undefined = undefined;
+	private _userID: string | undefined = undefined;
+
+	async initTelemetry(): Promise<void> {
+		if (this._segmentClient) {
+			// Prevent subsequent initializations.
+			return;
+		}
+
+		let root: string;
+		try {
+			root = await this.project.getRoot();
+		} catch {
+			root = await this.project.suggestRoot();
+		}
+
+		this._enabled = readPrismicrc(root).telemetry !== false;
+		this._segmentClient = new SegmentClient(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.
+			flushAt: 1,
+			// TODO: Verify that this actually does not send data to Segment when false.
+			enable: this._enabled,
+		});
+		this._anonymousID = randomUUID();
+	}
+
+	// TODO: Should `userId` be automatically populated by the logged in
+	// user? We already have their info via UserRepository.
+	track(args: TelemetryManagerTrackArgs): Promise<void> {
+		const { event, repository, ...properties } = args;
+
+		const payload: {
+			event: HumanSegmentEventTypes;
+			userId?: string;
+			anonymousId?: string;
+			properties?: Record<string, unknown>;
+			context?: {
+				groupId?: {
+					Repository?: string;
+				};
+			};
+		} = {
+			event: HumanSegmentEventType[event],
+			properties: {
+				repo: repository,
+				...properties,
+			},
+		};
+
+		if (this._userID) {
+			payload.userId = this._userID;
+		} else {
+			payload.anonymousId = this._anonymousID;
+		}
+
+		if (args.repository) {
+			payload.context ||= {};
+			payload.context.groupId ||= {};
+			payload.context.groupId.Repository = repository;
+		}
+
+		return new Promise((resolve) => {
+			assertTelemetryInitialized(this._segmentClient);
+
+			// TODO: Make sure client fails gracefully when no internet connection
+			this._segmentClient.track(payload, (maybeError?: Error) => {
+				if (maybeError) {
+					// TODO: Not sure how we want to deal with that
+					console.warn(`An error occurred during Segment tracking`, maybeError);
+				}
+
+				resolve();
+			});
+		});
+	}
+
+	// TODO: Should `userID` and `intercomHash` be automatically populated
+	// by the logged in user? We already have their info via
+	// UserRepository.
+	identify(args: TelemetryManagerIdentifyArgs): Promise<void> {
+		return new Promise((resolve) => {
+			assertTelemetryInitialized(this._segmentClient);
+
+			const payload = {
+				userId: args.userID,
+				anonymousId: this._anonymousID,
+				integrations: {
+					Intercom: {
+						user_hash: args.intercomHash,
+					},
+				},
+			};
+			this._userID = args.userID;
+
+			// TODO: Make sure client fails gracefully when no internet connection
+			this._segmentClient.identify(payload, (maybeError?: Error) => {
+				if (maybeError) {
+					// TODO: Not sure how we want to deal with that
+					console.warn(`An error occurred during Segment identify`, maybeError);
+				}
+
+				resolve();
+			});
+		});
+	}
+}

package/src/managers/telemetry/types.ts

@@ -0,0 +1,46 @@
+export const SegmentEventType = {
+	command_init_start: "command:init:start",
+	command_init_identify: "command:init:identify",
+	command_init_end: "command:init:end",
+} as const;
+type SegmentEventTypes = typeof SegmentEventType[keyof typeof SegmentEventType];
+
+export const HumanSegmentEventType = {
+	[SegmentEventType.command_init_start]: "SliceMachine Init Start",
+	[SegmentEventType.command_init_identify]: "SliceMachine Init Identify",
+	[SegmentEventType.command_init_end]: "SliceMachine Init 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 CommandInitStartSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.command_init_start
+>;
+
+// This event feels off, we have a dedicated `identify` method...
+type CommandInitIdentifySegmentEvent = SegmentEvent<
+	typeof SegmentEventType.command_init_identify
+>;
+
+type CommandInitEndSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.command_init_end,
+	{ framework: string; success: boolean; error?: string }
+>;
+
+export type SegmentEvents =
+	| CommandInitStartSegmentEvent
+	| CommandInitIdentifySegmentEvent
+	| CommandInitEndSegmentEvent;

package/src/managers/user/UserManager.ts

@@ -0,0 +1,27 @@
+import { BaseManager } from "../BaseManager";
+
+export class UserManager extends BaseManager {
+	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,
+	);
+	getAuthenticationCookies =
+		this.prismicAuthManager.getAuthenticationCookies.bind(
+			this.prismicAuthManager,
+		);
+	getProfile = this.prismicAuthManager.getProfile.bind(this.prismicAuthManager);
+}

package/src/managers/versions/VersionsManager.ts

@@ -0,0 +1,121 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import semver from "semver";
+
+import {
+	fetchGitHubReleaseBodyForRelease,
+	GitHubReleaseMetadata,
+} from "../../lib/fetchGitHubReleaseBodyForRelease";
+import { fetchNPMPackageVersions } from "../../lib/fetchNPMPackageVersions";
+
+import { SLICE_MACHINE_GITHUB_PACKAGE_NAME } from "../../constants/SLICE_MACHINE_GITHUB_PACKAGE_NAME";
+import { SLICE_MACHINE_GITHUB_REPOSITORY_NAME } from "../../constants/SLICE_MACHINE_GITHUB_REPOSITORY_NAME";
+import { SLICE_MACHINE_GITHUB_REPOSITORY_ORGANIZATION } from "../../constants/SLICE_MACHINE_GITHUB_REPOSITORY_ORGANIZATION";
+import { SLICE_MACHINE_NPM_PACKAGE_NAME } from "../../constants/SLICE_MACHINE_NPM_PACKAGE_NAME";
+import { VERSION_KIND } from "../../constants/VERSION_KIND";
+
+import { BaseManager } from "../BaseManager";
+
+import { Version } from "./types";
+
+const detectVersionBumpKind = (
+	to: string,
+	from?: string,
+): typeof VERSION_KIND[keyof typeof VERSION_KIND] => {
+	if (!from) {
+		return VERSION_KIND.FIRST;
+	}
+
+	if (semver.satisfies(to, `~${from}`)) {
+		return VERSION_KIND.PATCH;
+	} else if (semver.satisfies(to, `^${from}`)) {
+		return VERSION_KIND.MINOR;
+	} else {
+		return VERSION_KIND.MAJOR;
+	}
+};
+
+type SliceMachineManagerGetReleaseNotesForVersionArgs = {
+	version: string;
+};
+
+export class VersionsManager extends BaseManager {
+	/**
+	 * Record of version numbers mapped to their GitHub release metadata.
+	 */
+	gitHubSliceMachineReleaseMetadataCache: Record<
+		string,
+		GitHubReleaseMetadata | undefined
+	> = {};
+
+	async getRunningSliceMachineVersion(): Promise<string> {
+		const sliceMachineDir = await this.project.locateSliceMachineUIDir();
+
+		const sliceMachinePackageJSONContents = await fs.readFile(
+			path.join(sliceMachineDir, "package.json"),
+			"utf8",
+		);
+
+		// TODO: Validate the contents? This code currently assumes a
+		// well-formed document.
+		const json = JSON.parse(sliceMachinePackageJSONContents);
+
+		return json.version;
+	}
+
+	async getAllStableSliceMachineVersions(): Promise<string[]> {
+		const versions = await fetchNPMPackageVersions({
+			packageName: SLICE_MACHINE_NPM_PACKAGE_NAME,
+		});
+
+		const filteredVersions = versions.filter((version) => {
+			// Exclude tagged versions (e.g. `1.0.0-alpha.0`).
+			// Exclude versions < 0.1.0 (e.g. `0.0.1`).
+			return (
+				/^[1-9]\d*\.\d+\.\d+$/.test(version) ||
+				/^\d+\.[1-9]\d*\.\d+$/.test(version)
+			);
+		});
+
+		return semver.rsort(filteredVersions);
+	}
+
+	async getAllStableSliceMachineVersionsWithKind(): Promise<Version[]> {
+		const versions = await this.getAllStableSliceMachineVersions();
+
+		return versions.map((version, i) => {
+			const previousVersion = versions[i + 1];
+
+			return {
+				version,
+				kind: detectVersionBumpKind(version, previousVersion),
+			};
+		});
+	}
+
+	async getLatestNonBreakingSliceMachineVersion(): Promise<string | undefined> {
+		const versions = await this.getAllStableSliceMachineVersions();
+		const currentVersion = await this.getRunningSliceMachineVersion();
+
+		return semver.maxSatisfying(versions, `^${currentVersion}`) ?? undefined;
+	}
+
+	async checkIsUpdateAvailable(): Promise<boolean> {
+		const versions = await this.getAllStableSliceMachineVersions();
+		const currentVersion = await this.getRunningSliceMachineVersion();
+
+		return semver.gt(versions[0], currentVersion);
+	}
+
+	async getSliceMachineReleaseNotesForVersion(
+		args: SliceMachineManagerGetReleaseNotesForVersionArgs,
+	): Promise<string | undefined> {
+		return await fetchGitHubReleaseBodyForRelease({
+			repositoryOwner: SLICE_MACHINE_GITHUB_REPOSITORY_ORGANIZATION,
+			repositoryName: SLICE_MACHINE_GITHUB_REPOSITORY_NAME,
+			packageName: SLICE_MACHINE_GITHUB_PACKAGE_NAME,
+			version: args.version,
+			cache: this.gitHubSliceMachineReleaseMetadataCache,
+		});
+	}
+}

package/src/managers/versions/types.ts

@@ -0,0 +1,6 @@
+import { VERSION_KIND } from "../../constants/VERSION_KIND";
+
+export type Version = {
+	version: string;
+	kind: typeof VERSION_KIND[keyof typeof VERSION_KIND];
+};

package/src/test/createSliceMachineManagerMSWHandler.ts

@@ -0,0 +1,41 @@
+import { handleRPCRequest } from "r19";
+import { rest, DefaultBodyType, MockedRequest, RestHandler } from "msw";
+import { Readable } from "node:stream";
+
+import { SliceMachineManager } from "../managers/SliceMachineManager";
+import { getSliceMachineManagerProcedures } from "../managers/createSliceMachineManagerMiddleware";
+
+const streamToString = async (stream: Readable) => {
+	const chunks: Buffer[] = [];
+
+	for await (const chunk of stream) {
+		chunks.push(Buffer.from(chunk));
+	}
+
+	return Buffer.concat(chunks).toString("utf-8");
+};
+
+export type CreateSliceMachineManagerMSWHandlerArgs = {
+	sliceMachineManager: SliceMachineManager;
+	url: string;
+};
+
+export const createSliceMachineManagerMSWHandler = (
+	args: CreateSliceMachineManagerMSWHandlerArgs,
+): RestHandler<MockedRequest<DefaultBodyType>> => {
+	return rest.post(args.url, async (req, res, ctx) => {
+		const rpcResponse = await handleRPCRequest({
+			body: await req.text(),
+			contentTypeHeader: req.headers.get("Content-Type"),
+			procedures: getSliceMachineManagerProcedures({
+				sliceMachineManager: args.sliceMachineManager,
+			}),
+		});
+
+		return res(
+			ctx.body(await streamToString(rpcResponse.stream)),
+			ctx.set(rpcResponse.headers),
+			ctx.status(rpcResponse.statusCode || 200),
+		);
+	});
+};

package/src/test/index.ts

@@ -0,0 +1,4 @@
+export {
+	createSliceMachineManagerMSWHandler,
+	CreateSliceMachineManagerMSWHandlerArgs,
+} from "./createSliceMachineManagerMSWHandler";

package/src/types.ts

@@ -0,0 +1,59 @@
+import { HookError, SliceMachinePluginOptions } from "@slicemachine/plugin-kit";
+import { VERSION_KIND } from "./constants/VERSION_KIND";
+
+export type PackageManager = "npm" | "yarn";
+
+export type PackageChangelog = {
+	currentVersion: string;
+	updateAvailable: boolean;
+	latestNonBreakingVersion: string | null;
+	versions: PackageVersion[];
+};
+
+export type PackageVersion = {
+	versionNumber: string;
+	releaseNote: string | null;
+	kind: typeof VERSION_KIND[keyof typeof VERSION_KIND] | null;
+};
+
+/**
+ * A string, object, or instance representing a registered plugin.
+ *
+ * @typeParam TSliceMachinePluginOptions - User-provided options for the plugin.
+ */
+export type SliceMachineConfigPluginRegistration<
+	TSliceMachinePluginOptions extends SliceMachinePluginOptions = SliceMachinePluginOptions,
+> =
+	| string
+	| {
+			resolve: string;
+			options?: TSliceMachinePluginOptions;
+	  };
+
+/**
+ * Slice Machine configuration from `slicemachine.config.js`.
+ */
+export type SliceMachineConfig = {
+	// TODO: Is `_latest` necessary? Can we deprecate it?
+	_latest: string;
+	// TODO: Can we make `apiEndpoint` optional?
+	apiEndpoint?: string;
+	// NOTE: This is a new property.
+	repositoryName: string;
+	localSliceSimulatorURL?: string;
+	libraries?: string[];
+	adapter: SliceMachineConfigPluginRegistration;
+	plugins?: SliceMachineConfigPluginRegistration[];
+};
+
+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;
+};