@prismicio/plugin-kit 0.0.1

package/src/fs/writeCustomTypeModel.ts

@@ -0,0 +1,31 @@
+import TypesInternal from "@prismicio/types-internal/lib/customtypes/index.js";
+
+import { CUSTOM_TYPE_MODEL_FILENAME } from "./constants";
+import {
+	writeCustomTypeFile,
+	WriteCustomTypeFileArgs,
+} from "./writeCustomTypeFile";
+
+export type WriteCustomTypeModelArgs = Omit<
+	WriteCustomTypeFileArgs,
+	"customTypeID" | "filename" | "contents"
+> & {
+	model: TypesInternal.CustomType;
+};
+
+/**
+ * Writes a CustomType model to the file system in the CustomType's CustomType
+ * library.
+ *
+ * @returns The file path to the written model.
+ */
+export const writeCustomTypeModel = async (
+	args: WriteCustomTypeModelArgs,
+): Promise<string> => {
+	return await writeCustomTypeFile({
+		...args,
+		customTypeID: args.model.id,
+		filename: CUSTOM_TYPE_MODEL_FILENAME,
+		contents: JSON.stringify(args.model, null, 2),
+	});
+};

package/src/fs/writeProjectFile.ts

@@ -0,0 +1,39 @@
+import * as path from "node:path";
+
+import { PluginSystemHelpers } from "../createPluginSystemHelpers";
+
+import * as fs from "./lib/fsLimit";
+
+export type WriteProjectFileArgs = {
+	filename: string;
+	contents: Parameters<typeof fs.writeFile>[1];
+	format?: boolean;
+	formatOptions?: Parameters<PluginSystemHelpers["format"]>[2];
+	helpers: PluginSystemHelpers;
+};
+
+/**
+ * Writes a file to the project with optional formatting.
+ *
+ * @returns The file path to the written file.
+ */
+export const writeProjectFile = async (
+	args: WriteProjectFileArgs,
+): Promise<string> => {
+	const filePath = args.helpers.joinPathFromRoot(args.filename);
+
+	let contents = args.contents;
+
+	if (args.format) {
+		contents = await args.helpers.format(
+			contents.toString(),
+			filePath,
+			args.formatOptions,
+		);
+	}
+
+	await fs.mkdir(path.dirname(filePath), { recursive: true });
+	await fs.writeFile(filePath, contents);
+
+	return filePath;
+};

package/src/fs/writeSliceFile.ts

@@ -0,0 +1,30 @@
+import {
+	buildSliceFilePath,
+	BuildSliceFilePathArgs,
+} from "./buildSliceFilePath";
+import { writeProjectFile, WriteProjectFileArgs } from "./writeProjectFile";
+
+export type WriteSliceFileArgs = Omit<WriteProjectFileArgs, "filePath"> &
+	BuildSliceFilePathArgs;
+
+/**
+ * Writes a Slice model to the file system in the Slice's Slice library.
+ *
+ * @returns The file path to the written file.
+ */
+export const writeSliceFile = async (
+	args: WriteSliceFileArgs,
+): Promise<string> => {
+	const filePath = await buildSliceFilePath(args);
+	const relativeFilePath = await buildSliceFilePath({
+		...args,
+		absolute: false,
+	});
+
+	await writeProjectFile({
+		...args,
+		filename: relativeFilePath,
+	});
+
+	return filePath;
+};

package/src/fs/writeSliceModel.ts

@@ -0,0 +1,26 @@
+import TypesInternal from "@prismicio/types-internal/lib/customtypes/index.js";
+
+import { SHARED_SLICE_MODEL_FILENAME } from "./constants";
+import { writeSliceFile, WriteSliceFileArgs } from "./writeSliceFile";
+
+export type WriteSliceModelArgs = Omit<
+	WriteSliceFileArgs,
+	"filename" | "contents" | "sliceID"
+> & {
+	model: TypesInternal.SharedSlice;
+};
+
+/**
+ * Writes a Slice model to the file system in the Slice's Slice library.
+ *
+ * @returns The file path to the written model.
+ */
+export const writeSliceModel = async (
+	args: WriteSliceModelArgs,
+): Promise<string> => {
+	return await writeSliceFile({
+		...args,
+		filename: SHARED_SLICE_MODEL_FILENAME,
+		contents: JSON.stringify(args.model, null, 2),
+	});
+};

package/src/hooks/customType-create.ts

@@ -0,0 +1,42 @@
+import TypesInternal from "@prismicio/types-internal/lib/customtypes/index.js";
+
+import type {
+	ExtendPluginSystemHook,
+	PluginOptions,
+	PluginHook,
+} from "../types";
+
+/**
+ * Data provided to `custom-type:create` hook handlers.
+ */
+export type CustomTypeCreateHookData = {
+	model: TypesInternal.CustomType;
+};
+
+/**
+ * Return value for `custom-type:create` hook handlers.
+ */
+export type CustomTypeCreateHookReturnType = void;
+
+/**
+ * Base version of `custom-type:create` without plugin runner context.
+ *
+ * @internal
+ */
+export type CustomTypeCreateHookBase = PluginHook<
+	CustomTypeCreateHookData,
+	CustomTypeCreateHookReturnType
+>;
+
+/**
+ * Handler for the `custom-type:create` hook. The hook is called when a Custom
+ * Type is created.
+ *
+ * `custom-type:create` is only called the first time a Custom Type is saved.
+ * Subsequent saves will call the `custom-type:update` hook.
+ *
+ * @typeParam TPluginOptions - User-provided options for the hook's plugin.
+ */
+export type CustomTypeCreateHook<
+	TPluginOptions extends PluginOptions = PluginOptions,
+> = ExtendPluginSystemHook<CustomTypeCreateHookBase, TPluginOptions>;

package/src/hooks/customType-delete.ts

@@ -0,0 +1,40 @@
+import TypesInternal from "@prismicio/types-internal/lib/customtypes/index.js";
+
+import type {
+	ExtendPluginSystemHook,
+	PluginOptions,
+	PluginHook,
+} from "../types";
+
+/**
+ * Data provided to `custom-type:delete` hook handlers.
+ */
+export type CustomTypeDeleteHookData = {
+	model: TypesInternal.CustomType;
+};
+
+/**
+ * Return value for `custom-type:delete` hook handlers.
+ */
+export type CustomTypeDeleteHookReturnType = void;
+
+/**
+ * Base version of a `custom-type:delete` hook handler without plugin runner
+ * context.
+ *
+ * @internal
+ */
+export type CustomTypeDeleteHookBase = PluginHook<
+	CustomTypeDeleteHookData,
+	CustomTypeDeleteHookReturnType
+>;
+
+/**
+ * Handler for the `custom-type:delete` hook. The hook is called when a Custom
+ * Type is deleted.
+ *
+ * @typeParam TPluginOptions - User-provided options for the hook's plugin.
+ */
+export type CustomTypeDeleteHook<
+	TPluginOptions extends PluginOptions = PluginOptions,
+> = ExtendPluginSystemHook<CustomTypeDeleteHookBase, TPluginOptions>;

package/src/hooks/customType-read.ts

@@ -0,0 +1,46 @@
+import TypesInternal from "@prismicio/types-internal/lib/customtypes/index.js";
+
+import type {
+	ExtendPluginSystemHook,
+	PluginOptions,
+	PluginHook,
+} from "../types";
+
+/**
+ * Data provided to `custom-type:read` hook handlers.
+ */
+export type CustomTypeReadHookData = {
+	id: string;
+};
+
+/**
+ * Return value for `custom-type:read` hook handlers.
+ */
+export type CustomTypeReadHookReturnType = {
+	model: TypesInternal.CustomType;
+};
+
+/**
+ * Base version of a `custom-type:read` hook handler without plugin runner
+ * context.
+ *
+ * @internal
+ */
+export type CustomTypeReadHookBase = PluginHook<
+	CustomTypeReadHookData,
+	CustomTypeReadHookReturnType
+>;
+
+/**
+ * Handler for the `custom-type:read` hook. The hook is called when a Custom
+ * Type's model is needed.
+ *
+ * This hook is **required** to be implemented by adapters.
+ *
+ * This hook will only be called in adapters.
+ *
+ * @typeParam TPluginOptions - User-provided options for the hook's plugin.
+ */
+export type CustomTypeReadHook<
+	TPluginOptions extends PluginOptions = PluginOptions,
+> = ExtendPluginSystemHook<CustomTypeReadHookBase, TPluginOptions>;

package/src/hooks/customType-rename.ts

@@ -0,0 +1,43 @@
+import TypesInternal from "@prismicio/types-internal/lib/customtypes/index.js";
+
+import type {
+	ExtendPluginSystemHook,
+	PluginOptions,
+	PluginHook,
+} from "../types";
+
+/**
+ * Data provided to `custom-type:rename` hook handlers.
+ */
+export type CustomTypeRenameHookData = {
+	model: TypesInternal.CustomType;
+};
+
+/**
+ * Return value for `custom-type:rename` hook handlers.
+ */
+export type CustomTypeRenameHookReturnType = void;
+
+/**
+ * Base version of a `custom-type:rename` hook handler without plugin runner
+ * context.
+ *
+ * @internal
+ */
+export type CustomTypeRenameHookBase = PluginHook<
+	CustomTypeRenameHookData,
+	CustomTypeRenameHookReturnType
+>;
+
+/**
+ * Handler for the `custom-type:rename` hook. The hook is called when a Custom
+ * Type is renamed.
+ *
+ * `custom-type:rename` is not called the first time a Custom Type is saved. The
+ * `custom-type:create` hook is called instead.
+ *
+ * @typeParam TPluginOptions - User-provided options for the hook's plugin.
+ */
+export type CustomTypeRenameHook<
+	TPluginOptions extends PluginOptions = PluginOptions,
+> = ExtendPluginSystemHook<CustomTypeRenameHookBase, TPluginOptions>;

package/src/hooks/customType-update.ts

@@ -0,0 +1,43 @@
+import TypesInternal from "@prismicio/types-internal/lib/customtypes/index.js";
+
+import type {
+	ExtendPluginSystemHook,
+	PluginOptions,
+	PluginHook,
+} from "../types";
+
+/**
+ * Data provided to `custom-type:update` hook handlers.
+ */
+export type CustomTypeUpdateHookData = {
+	model: TypesInternal.CustomType;
+};
+
+/**
+ * Return value for `custom-type:update` hook handlers.
+ */
+export type CustomTypeUpdateHookReturnType = void;
+
+/**
+ * Base version of a `custom-type:update` hook handler without plugin runner
+ * context.
+ *
+ * @internal
+ */
+export type CustomTypeUpdateHookBase = PluginHook<
+	CustomTypeUpdateHookData,
+	CustomTypeUpdateHookReturnType
+>;
+
+/**
+ * Handler for the `custom-type:update` hook. The hook is called when a Custom
+ * Type is updated.
+ *
+ * `custom-type:update` is not called the first time a Custom Type is saved. The
+ * `custom-type:create` hook is called instead.
+ *
+ * @typeParam TPluginOptions - User-provided options for the hook's plugin.
+ */
+export type CustomTypeUpdateHook<
+	TPluginOptions extends PluginOptions = PluginOptions,
+> = ExtendPluginSystemHook<CustomTypeUpdateHookBase, TPluginOptions>;

package/src/hooks/customTypeLibrary-read.ts

@@ -0,0 +1,38 @@
+import type {
+	ExtendPluginSystemHook,
+	PluginOptions,
+	PluginHook,
+} from "../types";
+
+/**
+ * Data provided to `custom-type-library:read` hook handlers.
+ */
+export type CustomTypeLibraryReadHookData = undefined;
+
+/**
+ * Return value for `custom-type-library:read` hook handlers.
+ */
+export type CustomTypeLibraryReadHookReturnType = {
+	ids: string[];
+};
+
+/**
+ * Base version of a `custom-type-library:read` hook handler without plugin
+ * runner context.
+ *
+ * @internal
+ */
+export type CustomTypeLibraryReadHookBase = PluginHook<
+	CustomTypeLibraryReadHookData,
+	CustomTypeLibraryReadHookReturnType
+>;
+
+/**
+ * Handler for the `custom-type-library:read` hook. The hook is called when a
+ * Custom Type Library's metadata is needed.
+ *
+ * @typeParam TPluginOptions - User-provided options for the hook's plugin.
+ */
+export type CustomTypeLibraryReadHook<
+	TPluginOptions extends PluginOptions = PluginOptions,
+> = ExtendPluginSystemHook<CustomTypeLibraryReadHookBase, TPluginOptions>;

package/src/hooks/debug.ts

@@ -0,0 +1,31 @@
+import type {
+	ExtendPluginSystemHook,
+	PluginOptions,
+	PluginHook,
+} from "../types";
+
+/**
+ * Data provided to `debug` hook handlers.
+ */
+export type DebugHookData = unknown;
+
+/**
+ * Return value for `debug` hook handlers.
+ */
+export type DebugHookReturnType = unknown;
+
+/**
+ * Base version of a `debug` hook handler without plugin runner context.
+ *
+ * @internal
+ */
+export type DebugHookBase = PluginHook<DebugHookData, DebugHookReturnType>;
+
+/**
+ * Handler for the `debug` hook. This hook is never called in a production app.
+ * It can be used for testing purposes.
+ *
+ * @typeParam TPluginOptions - User-provided options for the hook's plugin.
+ */
+export type DebugHook<TPluginOptions extends PluginOptions = PluginOptions> =
+	ExtendPluginSystemHook<DebugHookBase, TPluginOptions>;

package/src/hooks/project-init.ts

@@ -0,0 +1,48 @@
+import type {
+	ExtendPluginSystemHook,
+	PluginOptions,
+	PluginHook,
+} from "../types";
+
+/**
+ * Data provided to `project:init` hook handlers.
+ */
+export type ProjectInitHookData = {
+	/**
+	 * Log messages. The message may be sent to the console or elsewhere.
+	 */
+	log: (message: string) => void;
+	/**
+	 * Install package dependencies. The correct package manager will
+	 * automatically be used (npm/Yarn/pnpm/etc.).
+	 */
+	installDependencies: (args: {
+		dependencies: Record<string, string>;
+		dev?: boolean;
+	}) => Promise<void>;
+};
+
+/**
+ * Return value for `project:init` hook handlers.
+ */
+export type ProjectInitHookReturnType = void;
+
+/**
+ * Base version of `project:init` without plugin runner context.
+ *
+ * @internal
+ */
+export type ProjectInitHookBase = PluginHook<
+	ProjectInitHookData,
+	ProjectInitHookReturnType
+>;
+
+/**
+ * Handler for the `project:init` hook. The hook is called during the init
+ * Project for plugins to init
+ *
+ * @typeParam TPluginOptions - User-provided options for the hook's plugin.
+ */
+export type ProjectInitHook<
+	TPluginOptions extends PluginOptions = PluginOptions,
+> = ExtendPluginSystemHook<ProjectInitHookBase, TPluginOptions>;

package/src/hooks/slice-create.ts

@@ -0,0 +1,44 @@
+import TypesInternal from "@prismicio/types-internal/lib/customtypes/index.js";
+
+import type {
+	ExtendPluginSystemHook,
+	PluginOptions,
+	PluginHook,
+} from "../types";
+
+/**
+ * Data provided to `slice:create` hook handlers.
+ */
+export type SliceCreateHookData = {
+	libraryID: string;
+	model: TypesInternal.SharedSlice;
+	componentContents?: string;
+};
+
+/**
+ * Return value for `slice:create` hook handlers.
+ */
+export type SliceCreateHookReturnType = void;
+
+/**
+ * Base version of `slice:create` without plugin runner context.
+ *
+ * @internal
+ */
+export type SliceCreateHookBase = PluginHook<
+	SliceCreateHookData,
+	SliceCreateHookReturnType
+>;
+
+/**
+ * Handler for the `slice:create` hook. The hook is called when a Slice is
+ * created.
+ *
+ * `slice:create` is only called the first time a Slice is saved. Subsequent
+ * saves will call the `slice:update` hook.
+ *
+ * @typeParam TPluginOptions - User-provided options for the hook's plugin.
+ */
+export type SliceCreateHook<
+	TPluginOptions extends PluginOptions = PluginOptions,
+> = ExtendPluginSystemHook<SliceCreateHookBase, TPluginOptions>;

package/src/hooks/slice-delete.ts

@@ -0,0 +1,40 @@
+import TypesInternal from "@prismicio/types-internal/lib/customtypes/index.js";
+
+import type {
+	ExtendPluginSystemHook,
+	PluginOptions,
+	PluginHook,
+} from "../types";
+
+/**
+ * Data provided to `slice:delete` hook handlers.
+ */
+export type SliceDeleteHookData = {
+	libraryID: string;
+	model: TypesInternal.SharedSlice;
+};
+
+/**
+ * Return value for `slice:delete` hook handlers.
+ */
+export type SliceDeleteHookReturnType = void;
+
+/**
+ * Base version of a `slice:delete` hook handler without plugin runner context.
+ *
+ * @internal
+ */
+export type SliceDeleteHookBase = PluginHook<
+	SliceDeleteHookData,
+	SliceDeleteHookReturnType
+>;
+
+/**
+ * Handler for the `slice:delete` hook. The hook is called when a Slice is
+ * deleted.
+ *
+ * @typeParam TPluginOptions - User-provided options for the hook's plugin.
+ */
+export type SliceDeleteHook<
+	TPluginOptions extends PluginOptions = PluginOptions,
+> = ExtendPluginSystemHook<SliceDeleteHookBase, TPluginOptions>;

package/src/hooks/slice-read.ts

@@ -0,0 +1,44 @@
+import TypesInternal from "@prismicio/types-internal/lib/customtypes/index.js";
+
+import type {
+	ExtendPluginSystemHook,
+	PluginOptions,
+	PluginHook,
+} from "../types";
+
+/**
+ * Data provided to `slice:read` hook handlers.
+ */
+export type SliceReadHookData = {
+	libraryID: string;
+	sliceID: string;
+};
+
+/**
+ * Return value for `slice:read` hook handlers.
+ */
+export type SliceReadHookReturnType = { model: TypesInternal.SharedSlice };
+
+/**
+ * Base version of a `slice:read` hook handler without plugin runner context.
+ *
+ * @internal
+ */
+export type SliceReadHookBase = PluginHook<
+	SliceReadHookData,
+	SliceReadHookReturnType
+>;
+
+/**
+ * Handler for the `slice:read` hook. The hook is called when a Slice's model is
+ * needed.
+ *
+ * This hook is **required** to be implemented by adapters.
+ *
+ * This hook will only be called in adapters.
+ *
+ * @typeParam TPluginOptions - User-provided options for the hook's plugin.
+ */
+export type SliceReadHook<
+	TPluginOptions extends PluginOptions = PluginOptions,
+> = ExtendPluginSystemHook<SliceReadHookBase, TPluginOptions>;

package/src/hooks/slice-rename.ts

@@ -0,0 +1,40 @@
+import TypesInternal from "@prismicio/types-internal/lib/customtypes/index.js";
+
+import type {
+	ExtendPluginSystemHook,
+	PluginOptions,
+	PluginHook,
+} from "../types";
+
+/**
+ * Data provided to `slice:rename` hook handlers.
+ */
+export type SliceRenameHookData = {
+	libraryID: string;
+	model: TypesInternal.SharedSlice;
+};
+
+/**
+ * Return value for `slice:rename` hook handlers.
+ */
+export type SliceRenameHookReturnType = void;
+
+/**
+ * Base version of a `slice:rename` hook handler without plugin runner context.
+ *
+ * @internal
+ */
+export type SliceRenameHookBase = PluginHook<
+	SliceRenameHookData,
+	SliceRenameHookReturnType
+>;
+
+/**
+ * Handler for the `slice:rename` hook. The hook is called when a Slice is
+ * renamed.
+ *
+ * @typeParam TPluginOptions - User-provided options for the hook's plugin.
+ */
+export type SliceRenameHook<
+	TPluginOptions extends PluginOptions = PluginOptions,
+> = ExtendPluginSystemHook<SliceRenameHookBase, TPluginOptions>;

package/src/hooks/slice-update.ts

@@ -0,0 +1,43 @@
+import TypesInternal from "@prismicio/types-internal/lib/customtypes/index.js";
+
+import type {
+	ExtendPluginSystemHook,
+	PluginOptions,
+	PluginHook,
+} from "../types";
+
+/**
+ * Data provided to `slice:update` hook handlers.
+ */
+export type SliceUpdateHookData = {
+	libraryID: string;
+	model: TypesInternal.SharedSlice;
+};
+
+/**
+ * Return value for `slice:update` hook handlers.
+ */
+export type SliceUpdateHookReturnType = void;
+
+/**
+ * Base version of a `slice:update` hook handler without plugin runner context.
+ *
+ * @internal
+ */
+export type SliceUpdateHookBase = PluginHook<
+	SliceUpdateHookData,
+	SliceUpdateHookReturnType
+>;
+
+/**
+ * Handler for the `slice:update` hook. The hook is called when a Slice is
+ * updated.
+ *
+ * `slice:update` is not called the first time a Slice is saved. The
+ * `slice:create` hook is called instead.
+ *
+ * @typeParam TPluginOptions - User-provided options for the hook's plugin.
+ */
+export type SliceUpdateHook<
+	TPluginOptions extends PluginOptions = PluginOptions,
+> = ExtendPluginSystemHook<SliceUpdateHookBase, TPluginOptions>;