@slicemachine/manager 0.0.0-alpha.dev-new-release-process.1

package/src/managers/snippets/SnippetsManager.ts

@@ -0,0 +1,45 @@
+import * as t from "io-ts";
+import {
+	HookError,
+	Snippet,
+	SnippetReadHookData,
+} from "@slicemachine/plugin-kit";
+
+import { DecodeError } from "../../lib/DecodeError";
+import { assertPluginsInitialized } from "../../lib/assertPluginsInitialized";
+import { decodeHookResult } from "../../lib/decodeHookResult";
+
+import { BaseManager } from "../BaseManager";
+
+const snippetCodec = t.type({
+	label: t.string,
+	language: t.string,
+	code: t.string,
+});
+
+type SnippetsMangerUpdateSliceReturnType = {
+	snippets: Snippet[];
+	errors: (DecodeError | HookError)[];
+};
+
+export class SnippetsManager extends BaseManager {
+	async readSnippets(
+		args: SnippetReadHookData,
+	): Promise<SnippetsMangerUpdateSliceReturnType> {
+		assertPluginsInitialized(this.sliceMachinePluginRunner);
+
+		const hookResult = await this.sliceMachinePluginRunner.callHook(
+			"snippet:read",
+			args,
+		);
+		const { data, errors } = decodeHookResult(
+			t.union([snippetCodec, t.array(snippetCodec)]),
+			hookResult,
+		);
+
+		return {
+			snippets: data.flat(),
+			errors,
+		};
+	}
+}

package/src/managers/telemetry/TelemetryManager.ts

@@ -0,0 +1,248 @@
+import { randomUUID } from "node:crypto";
+
+import { Analytics, GroupParams, TrackParams } from "@segment/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 TelemetryManagerInitTelemetryArgs = {
+	appName: string;
+	appVersion: string;
+};
+
+type TelemetryManagerTrackArgs = SegmentEvents;
+
+type TelemetryManagerIdentifyArgs = {
+	userID: string;
+	intercomHash: string;
+};
+
+type TelemetryManagerGroupArgs = {
+	manualLibsCount: number;
+	downloadedLibsCount: number;
+	npmLibsCount: number;
+	downloadedLibs: string[];
+};
+
+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 `SliceMachineManager.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;
+
+	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,
+				// TODO: Verify that this actually does not send data to Segment when false.
+				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.
+				console.error(`An error occurred with Segment`, error);
+			});
+
+			return analytics;
+		};
+
+		this._anonymousID = randomUUID();
+		this._context = { app: { name: args.appName, version: args.appVersion } };
+	}
+
+	// TODO: Should `userId` be automatically populated by the logged in
+	// user? We already have their info via UserRepository.
+	async track(args: TelemetryManagerTrackArgs): Promise<void> {
+		const { event, repository, ...properties } = args;
+		let repositoryName = repository;
+
+		if (repositoryName === undefined) {
+			try {
+				repositoryName = await this.project.getRepositoryName();
+			} catch (error) {
+				// 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 },
+		};
+
+		if (this._userID) {
+			payload.userId = this._userID;
+		} else {
+			payload.anonymousId = this._anonymousID;
+		}
+
+		if (repositoryName) {
+			payload.context ||= {};
+			payload.context.groupId ||= {};
+			payload.context.groupId.Repository = repositoryName;
+		}
+
+		return new Promise((resolve) => {
+			assertTelemetryInitialized(this._segmentClient);
+
+			// TODO: Make sure client fails gracefully when no internet connection
+			this._segmentClient().track(
+				payload as TrackParams,
+				(maybeError?: unknown) => {
+					if (maybeError && import.meta.env.DEV) {
+						// 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> {
+		const payload = {
+			userId: args.userID,
+			anonymousId: this._anonymousID,
+			integrations: {
+				Intercom: {
+					user_hash: args.intercomHash,
+				},
+			},
+			context: { ...this._context },
+		};
+
+		this._userID = args.userID;
+
+		return new Promise((resolve) => {
+			assertTelemetryInitialized(this._segmentClient);
+
+			// TODO: Make sure client fails gracefully when no internet connection
+			this._segmentClient().identify(payload, (maybeError?: unknown) => {
+				if (maybeError && import.meta.env.DEV) {
+					// TODO: Not sure how we want to deal with that
+					console.warn(`An error occurred during Segment identify`, maybeError);
+				}
+
+				resolve();
+			});
+		});
+	}
+
+	async group(args: TelemetryManagerGroupArgs): Promise<void> {
+		let repositoryName;
+
+		try {
+			repositoryName = await this.project.getRepositoryName();
+		} catch (error) {
+			// noop, happen only when the user is not in a project
+		}
+
+		const payload: {
+			groupId?: string;
+			userId?: string;
+			anonymousId?: string;
+			traits?: Record<string, unknown>;
+			context?: Partial<TelemetryManagerContext> & {
+				groupId?: {
+					Repository?: string;
+				};
+			};
+		} = {
+			traits: args,
+			context: { ...this._context },
+		};
+
+		if (this._userID) {
+			payload.userId = this._userID;
+		} else {
+			payload.anonymousId = this._anonymousID;
+		}
+
+		if (repositoryName) {
+			payload.groupId = repositoryName;
+			payload.context ||= {};
+			payload.context.groupId ||= {};
+			payload.context.groupId.Repository = repositoryName;
+		}
+
+		return new Promise((resolve) => {
+			assertTelemetryInitialized(this._segmentClient);
+
+			this._segmentClient().group(
+				payload as GroupParams,
+				(maybeError?: unknown) => {
+					if (maybeError && import.meta.env.DEV) {
+						// TODO: Not sure how we want to deal with that
+						console.warn(`An error occurred during Segment group`, maybeError);
+					}
+
+					resolve();
+				},
+			);
+		});
+	}
+
+	async checkIsTelemetryEnabled(): Promise<boolean> {
+		let root: string;
+		try {
+			root = await this.project.getRoot();
+		} catch {
+			root = await this.project.suggestRoot();
+		}
+
+		return readPrismicrc(root).telemetry !== false;
+	}
+}

package/src/managers/telemetry/types.ts

@@ -0,0 +1,283 @@
+import { CustomTypeFormat } from "../customTypes/types";
+import type { LimitType } from "../prismicRepository/types";
+
+export const SegmentEventType = {
+	command_init_start: "command:init:start",
+	command_init_identify: "command:init:identify",
+	command_init_end: "command:init:end",
+	review: "review",
+	sliceSimulator_setup: "slice-simulator:setup",
+	sliceSimulator_open: "slice-simulator:open",
+	sliceSimulator_isNotRunning: "slice-simulator:is-not-running",
+	pageView: "page-view",
+	users_invite_button_clicked: "users-invite-button-clicked",
+	openVideoTutorials: "open-video-tutorials",
+	customType_created: "custom-type:created",
+	customType_fieldAdded: "custom-type:field-added",
+	customType_sliceZoneUpdated: "custom-type:slice-zone-updated",
+	customType_openAddFromTemplates: "custom-type:open-add-from-templates",
+	customType_saved: "custom-type:saved",
+	slice_created: "slice:created",
+	legacySlice_converted: "legacy-slice:converted",
+	screenshotTaken: "screenshot-taken",
+	changes_pushed: "changes:pushed",
+	changes_limitReach: "changes:limit-reach",
+	editor_widgetUsed: "editor:widget-used",
+	open_page_snippet: "page-type:open-snippet",
+	copy_page_snippet: "page-type:copy-snippet",
+	switch_environment: "environment:switch",
+} 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",
+	[SegmentEventType.review]: "SliceMachine Review",
+	[SegmentEventType.sliceSimulator_setup]: "SliceMachine Slice Simulator Setup",
+	[SegmentEventType.sliceSimulator_open]: "SliceMachine Slice Simulator Open",
+	[SegmentEventType.sliceSimulator_isNotRunning]:
+		"SliceMachine Slice Simulator is not running",
+	[SegmentEventType.pageView]: "SliceMachine Page View",
+	[SegmentEventType.users_invite_button_clicked]:
+		"Slice Machine Users Invite Button Clicked",
+	[SegmentEventType.openVideoTutorials]: "SliceMachine Open Video Tutorials",
+	[SegmentEventType.customType_created]: "SliceMachine Custom Type Created",
+	[SegmentEventType.customType_fieldAdded]:
+		"SliceMachine Custom Type Field Added",
+	[SegmentEventType.customType_sliceZoneUpdated]:
+		"SliceMachine Slicezone Updated",
+	[SegmentEventType.customType_openAddFromTemplates]:
+		"SliceMachine Open Add from templates",
+	[SegmentEventType.customType_saved]: "SliceMachine Custom Type Saved",
+	[SegmentEventType.slice_created]: "SliceMachine Slice Created",
+	[SegmentEventType.legacySlice_converted]:
+		"SliceMachine Legacy Slice Converted",
+	[SegmentEventType.screenshotTaken]: "SliceMachine Screenshot Taken",
+	[SegmentEventType.changes_pushed]: "SliceMachine Changes Pushed",
+	[SegmentEventType.changes_limitReach]: "SliceMachine Changes Limit Reach",
+	[SegmentEventType.editor_widgetUsed]: "SliceMachine Editor Widget Used",
+	[SegmentEventType.open_page_snippet]:
+		"SliceMachine Opens Page Type Snippet Dialog",
+	[SegmentEventType.copy_page_snippet]:
+		"Slice Machine page code snippet copied",
+	[SegmentEventType.switch_environment]: "SliceMachine environment switch",
+} 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 }
+>;
+
+type ReviewSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.review,
+	{
+		rating: number;
+		comment: string;
+		type: "onboarding" | "advanced repository";
+	}
+>;
+
+type SliceSimulatorSetupSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.sliceSimulator_setup
+>;
+
+type SliceSimulatorOpenSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.sliceSimulator_open
+>;
+
+type SliceSimulatorIsNotRunningSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.sliceSimulator_isNotRunning
+>;
+
+type PageViewSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.pageView,
+	{
+		url: string;
+		path: string;
+		search: string;
+		title: string;
+		referrer: string;
+		adapter: string;
+		/*
+		 * We are tracking outer sizes instead of inner sizes as with the latter, we
+		 * can't differentiate between users with a high-density screen and those
+		 * zooming in/out with ⌘ + / ⌘ -. Indeed, when users zoom in/out, some
+		 * browsers (like Google Chrome) will update `window.devicePixelRatio` while
+		 * others (like Safari) will keep it unchanged so that it always reflects
+		 * the ratio of physical pixels to CSS pixels.
+		 */
+		outerWidth: number;
+		outerHeight: number;
+		screenWidth: number;
+		screenHeight: number;
+	}
+>;
+
+type OpenPageSnippetSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.open_page_snippet,
+	{ framework: string }
+>;
+
+type CopyPageSnippetSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.copy_page_snippet,
+	{ framework: string }
+>;
+
+type SwitchEnvironmentSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.switch_environment,
+	{ domain: string }
+>;
+
+type UsersInviteButtonClickedSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.users_invite_button_clicked
+>;
+
+type OpenVideoTutorialsSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.openVideoTutorials,
+	{ video: string }
+>;
+
+type CustomTypeCreatedSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.customType_created,
+	{
+		id: string;
+		name: string;
+		format: CustomTypeFormat;
+		type: "repeatable" | "single";
+		origin: "onboarding" | "table";
+	}
+>;
+
+type CustomTypeFieldAddedSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.customType_fieldAdded,
+	{
+		id: string; // field id
+		name: string; // custom type id
+		zone: "static" | "repeatable";
+		type: string;
+	}
+>;
+
+type CustomTypeSliceZoneUpdatedSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.customType_sliceZoneUpdated,
+	{ customTypeId: string }
+>;
+
+type CustomTypeOpenAddFromTemplatesEvent = SegmentEvent<
+	typeof SegmentEventType.customType_openAddFromTemplates,
+	{ customTypeId: string; customTypeFormat: CustomTypeFormat }
+>;
+
+type CustomTypeSavedSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.customType_saved,
+	{
+		id: string;
+		name: string;
+		format: CustomTypeFormat;
+		type: "repeatable" | "single";
+	}
+>;
+
+type SliceCreatedSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.slice_created,
+	{ id: string; name: string; library: string; sliceTemplate?: string }
+>;
+
+type LegacySliceConvertedSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.legacySlice_converted,
+	{
+		id: string;
+		variation: string;
+		library: string;
+		conversionType:
+			| "as_new_slice"
+			| "as_new_variation"
+			| "merge_with_identical";
+	}
+>;
+
+type ScreenshotTakenSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.screenshotTaken,
+	{
+		type: "custom";
+		method: "upload" | "dragAndDrop";
+	}
+>;
+
+type ChangesPushedSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.changes_pushed,
+	{
+		customTypesCreated: number;
+		customTypesModified: number;
+		customTypesDeleted: number;
+		slicesCreated: number;
+		slicesModified: number;
+		slicesDeleted: number;
+		missingScreenshots: number;
+		total: number;
+		duration: number;
+		hasDeletedDocuments: boolean;
+	}
+>;
+
+type ChangesLimitReachSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.changes_limitReach,
+	{ limitType: LimitType }
+>;
+
+type EditorWidgetUsedSegmentEvent = SegmentEvent<
+	typeof SegmentEventType.editor_widgetUsed,
+	{ sliceId: string }
+>;
+
+export type SegmentEvents =
+	| CommandInitStartSegmentEvent
+	| CommandInitIdentifySegmentEvent
+	| CommandInitEndSegmentEvent
+	| ReviewSegmentEvent
+	| SliceSimulatorSetupSegmentEvent
+	| SliceSimulatorOpenSegmentEvent
+	| SliceSimulatorIsNotRunningSegmentEvent
+	| PageViewSegmentEvent
+	| OpenVideoTutorialsSegmentEvent
+	| CustomTypeCreatedSegmentEvent
+	| CustomTypeFieldAddedSegmentEvent
+	| CustomTypeSliceZoneUpdatedSegmentEvent
+	| CustomTypeOpenAddFromTemplatesEvent
+	| CustomTypeSavedSegmentEvent
+	| SliceCreatedSegmentEvent
+	| LegacySliceConvertedSegmentEvent
+	| ScreenshotTakenSegmentEvent
+	| ChangesPushedSegmentEvent
+	| ChangesLimitReachSegmentEvent
+	| EditorWidgetUsedSegmentEvent
+	| OpenPageSnippetSegmentEvent
+	| CopyPageSnippetSegmentEvent
+	| UsersInviteButtonClickedSegmentEvent
+	| SwitchEnvironmentSegmentEvent;

package/src/managers/user/UserManager.ts

@@ -0,0 +1,39 @@
+import { SliceMachineError } from "../../errors";
+import { BaseManager } from "../BaseManager";
+import { SliceMachineManager } from "../SliceMachineManager";
+
+export class UserManager extends BaseManager {
+	constructor(sliceMachineManager: SliceMachineManager) {
+		super(sliceMachineManager);
+
+		if (!sliceMachineManager.getPrismicAuthManager()) {
+			throw new SliceMachineError(
+				"SliceMachineManager._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,
+	);
+	getAuthenticationCookies =
+		this.prismicAuthManager.getAuthenticationCookies.bind(
+			this.prismicAuthManager,
+		);
+	getProfile = this.prismicAuthManager.getProfile.bind(this.prismicAuthManager);
+}