훅 레퍼런스

훅을 사용하면 플러그인이 콘텐츠, 미디어, 이메일, 댓글, 페이지 라이프사이클의 특정 지점에서 EmDash 동작을 가로채고 수정할 수 있습니다.

훅 개요

다음 표는 각 훅, 트리거, 수정 가능한 항목, 배타적 여부를 나열합니다:

콘텐츠 훅

content:beforeSave

콘텐츠가 데이터베이스에 저장되기 전에 실행됩니다. 콘텐츠 검증, 변환 또는 보강에 사용합니다.

import { definePlugin } from "emdash";

export default definePlugin({
	id: "my-plugin",
	version: "1.0.0",
	hooks: {
		"content:beforeSave": async (event, ctx) => {
			const { content, collection, isNew } = event;

			if (isNew) {
				content.createdBy = "system";
			}
			content.modifiedAt = new Date().toISOString();

			return content;
		},
	},
});

Event

interface ContentHookEvent {
	content: Record<string, unknown>;
	collection: string;
	isNew: boolean;
}

반환값

• 변경을 적용하려면 수정된 콘텐츠 객체를 반환
• 변경 없이 통과시키려면 void 반환

content:afterSave

콘텐츠 저장 후 실행됩니다. 알림, 캐시 무효화 또는 외부 동기화와 같은 부작용에 사용합니다.

hooks: {
  "content:afterSave": async (event, ctx) => {
    const { content, collection, isNew } = event;

    if (collection === "posts" && content.status === "published") {
      await ctx.http?.fetch("https://api.example.com/notify", {
        method: "POST",
        body: JSON.stringify({ postId: content.id }),
      });
    }
  },
}

반환값

반환값이 필요하지 않습니다.

content:beforeDelete

콘텐츠 삭제 전에 실행됩니다. 삭제 검증이나 방지에 사용합니다.

hooks: {
  "content:beforeDelete": async (event, ctx) => {
    const { id, collection } = event;

    const item = await ctx.content?.get(collection, id);
    if (item?.data.protected) {
      return false;
    }
    return true;
  },
}

Event

interface ContentDeleteEvent {
	id: string;
	collection: string;
}

반환값

• 삭제를 취소하려면 false 반환
• 허용하려면 true 또는 void 반환

content:afterDelete

콘텐츠 삭제 후 실행됩니다. 정리 작업에 사용합니다.

hooks: {
  "content:afterDelete": async (event, ctx) => {
    const { id, collection } = event;
    await ctx.storage.relatedItems.delete(`${collection}:${id}`);
  },
}

content:afterRestore

휴지통 콘텐츠 복원 후 실행됩니다. content:read 능력이 필요합니다.

hooks: {
  "content:afterRestore": async (event, ctx) => {
    ctx.log.info(`Restored ${event.collection}/${event.content.id}`);
  },
}

content:afterSchedule

콘텐츠의 미래 게시 예약 후 실행됩니다. content:read 능력이 필요합니다.

hooks: {
  "content:afterSchedule": async (event, ctx) => {
    ctx.log.info(`Scheduled ${event.collection}/${event.content.id}`);
  },
}

content:afterUnschedule

예약된 콘텐츠의 예약 해제 후 실행됩니다. content:read 능력이 필요합니다.

hooks: {
  "content:afterUnschedule": async (event, ctx) => {
    ctx.log.info(`Unscheduled ${event.collection}/${event.content.id}`);
  },
}

Event

interface ContentStateChangeEvent {
	content: Record<string, unknown>;
	collection: string;
}

반환값

반환값이 필요하지 않습니다.

미디어 훅

media:beforeUpload

파일 업로드 전에 실행됩니다. 파일 검증, 이름 변경 또는 거부에 사용합니다.

hooks: {
  "media:beforeUpload": async (event, ctx) => {
    const { file } = event;

    if (file.size > 10 * 1024 * 1024) {
      throw new Error("File too large");
    }

    return {
      name: `${Date.now()}-${file.name}`,
      type: file.type,
      size: file.size,
    };
  },
}

Event

interface MediaUploadEvent {
	file: {
		name: string;
		type: string;
		size: number;
	};
}

반환값

• 변경을 적용하려면 수정된 파일 메타데이터 반환
• 변경 없이 통과시키려면 void 반환
• 업로드를 거부하려면 에러 throw

media:afterUpload

파일 업로드 후 실행됩니다. 처리, 썸네일 또는 메타데이터 추출에 사용합니다.

hooks: {
  "media:afterUpload": async (event, ctx) => {
    const { media } = event;

    if (media.mimeType.startsWith("image/")) {
      await ctx.kv.set(`media:${media.id}:analyzed`, {
        processedAt: new Date().toISOString(),
      });
    }
  },
}

Event

interface MediaAfterUploadEvent {
	media: {
		id: string;
		filename: string;
		mimeType: string;
		size: number | null;
		url: string;
		createdAt: string;
	};
}

라이프사이클 훅

plugin:install

플러그인 최초 설치 시 실행됩니다. 초기 설정, 스토리지 컬렉션 생성 또는 데이터 시딩에 사용합니다.

hooks: {
  "plugin:install": async (event, ctx) => {
    await ctx.kv.set("settings:enabled", true);
    await ctx.kv.set("settings:threshold", 100);
    ctx.log.info("Plugin installed successfully");
  },
}

plugin:activate

플러그인이 활성화될 때 (설치 후 또는 재활성화) 실행됩니다.

hooks: {
  "plugin:activate": async (event, ctx) => {
    ctx.log.info("Plugin activated");
  },
}

plugin:deactivate

플러그인이 비활성화될 때 실행됩니다.

hooks: {
  "plugin:deactivate": async (event, ctx) => {
    ctx.log.info("Plugin deactivated");
  },
}

plugin:uninstall

플러그인이 제거될 때 실행됩니다. 정리에 사용합니다.

hooks: {
  "plugin:uninstall": async (event, ctx) => {
    const { deleteData } = event;

    if (deleteData) {
      const items = await ctx.kv.list("settings:");
      for (const { key } of items) {
        await ctx.kv.delete(key);
      }
    }

    ctx.log.info("Plugin uninstalled");
  },
}

Event

interface UninstallEvent {
	deleteData: boolean;
}

Cron 훅

cron

예약 작업이 실행될 때 발생합니다. ctx.cron.schedule()로 작업을 예약합니다.

hooks: {
  "cron": async (event, ctx) => {
    if (event.name === "daily-sync") {
      const data = await ctx.http?.fetch("https://api.example.com/data");
      ctx.log.info("Sync complete");
    }
  },
}

Event

interface CronEvent {
	name: string;
	data?: Record<string, unknown>;
	scheduledAt: string;
}

이메일 훅

이메일 훅은 순서대로 실행됩니다: email:beforeSend, 그 다음 email:deliver, 그 다음 email:afterSend.

email:beforeSend

능력: hooks.email-events:register

전달 전에 실행되는 미들웨어 훅. 메시지 변환 또는 전달 취소에 사용.

hooks: {
  "email:beforeSend": async (event, ctx) => {
    return {
      ...event.message,
      text: event.message.text + "\n\n—Sent from My Site",
    };
  },
}

Event

interface EmailBeforeSendEvent {
	message: { to: string; subject: string; text: string; html?: string };
	source: string;
}

반환값

• 변환하려면 수정된 메시지 반환
• 전달을 취소하려면 false 반환
• 변경 없이 통과시키려면 void 반환

email:deliver

능력: hooks.email-transport:register | 배타적: 예

트랜스포트 프로바이더. 이메일을 전달할 수 있는 플러그인은 하나뿐입니다. 이메일 서비스를 통해 실제로 메시지를 보내는 역할을 합니다.

hooks: {
  "email:deliver": {
    exclusive: true,
    handler: async (event, ctx) => {
      await sendViaSES(event.message);
    },
  },
}

email:afterSend

능력: hooks.email-events:register

성공적인 전달 후의 fire-and-forget 훅. 에러는 기록되지만 전파되지 않습니다.

hooks: {
  "email:afterSend": async (event, ctx) => {
    await ctx.kv.set(`email:log:${Date.now()}`, {
      to: event.message.to,
      subject: event.message.subject,
    });
  },
}

댓글 훅

댓글 훅은 순서대로 실행됩니다: comment:beforeCreate, 그 다음 comment:moderate, 그 다음 comment:afterCreate. comment:afterModerate 훅은 관리자가 댓글 상태를 변경할 때 별도로 발생합니다.

comment:beforeCreate

능력: users:read

댓글 저장 전 미들웨어 훅. 댓글 보강, 검증 또는 거부에 사용.

hooks: {
  "comment:beforeCreate": async (event, ctx) => {
    if (event.comment.body.includes("http")) {
      return false;
    }
  },
}

Event

interface CommentBeforeCreateEvent {
	comment: {
		collection: string;
		contentId: string;
		parentId: string | null;
		authorName: string;
		authorEmail: string;
		authorUserId: string | null;
		body: string;
		ipHash: string | null;
		userAgent: string | null;
	};
	metadata: Record<string, unknown>;
}

반환값

• 변환하려면 수정된 이벤트 반환
• 거부하려면 false 반환
• 통과시키려면 void 반환

comment:moderate

능력: users:read | 배타적: 예

댓글이 승인, 대기 또는 스팸인지 결정합니다. 활성 모더레이션 프로바이더는 하나뿐입니다.

hooks: {
  "comment:moderate": {
    exclusive: true,
    handler: async (event, ctx) => {
      const score = await checkSpam(event.comment);
      return {
        status: score > 0.8 ? "spam" : score > 0.5 ? "pending" : "approved",
        reason: `Spam score: ${score}`,
      };
    },
  },
}

Event

interface CommentModerateEvent {
	comment: { /* beforeCreate와 동일 */ };
	metadata: Record<string, unknown>;
	collectionSettings: {
		commentsEnabled: boolean;
		commentsModeration: "all" | "first_time" | "none";
		commentsClosedAfterDays: number;
		commentsAutoApproveUsers: boolean;
	};
	priorApprovedCount: number;
}

반환값

{ status: "approved" | "pending" | "spam"; reason?: string }

comment:afterCreate

능력: users:read

댓글 저장 후의 fire-and-forget 훅. 알림에 사용합니다.

hooks: {
  "comment:afterCreate": async (event, ctx) => {
    if (event.comment.status === "approved") {
      await ctx.email?.send({
        to: event.contentAuthor?.email,
        subject: `New comment on "${event.content.title}"`,
        text: `${event.comment.authorName} commented: ${event.comment.body}`,
      });
    }
  },
}

comment:afterModerate

능력: users:read

관리자가 수동으로 댓글 상태를 변경할 때의 fire-and-forget 훅.

Event

interface CommentAfterModerateEvent {
	comment: { id: string; /* ... */ };
	previousStatus: string;
	newStatus: string;
	moderator: { id: string; name: string | null };
}

페이지 훅

페이지 훅은 공개 페이지 렌더링 시 실행됩니다. 플러그인이 메타데이터와 스크립트를 주입할 수 있게 합니다.

page:metadata

능력: 필요 없음

페이지 head에 메타 태그, Open Graph 속성, JSON-LD 구조화 데이터 또는 링크 태그를 기여합니다.

hooks: {
  "page:metadata": async (event, ctx) => {
    return [
      { kind: "meta", name: "generator", content: "EmDash" },
      { kind: "property", property: "og:site_name", content: event.page.siteName },
      { kind: "jsonld", graph: { "@type": "WebSite", name: event.page.siteName } },
    ];
  },
}

기여 타입

type PageMetadataContribution =
	| { kind: "meta"; name: string; content: string; key?: string }
	| { kind: "property"; property: string; content: string; key?: string }
	| {
			kind: "link";
			rel: "canonical" | "alternate" | "author" | "license" | "nlweb" | "site.standard.document";
			href: string;
			hreflang?: string;
			key?: string;
	  }
	| {
			kind: "jsonld";
			id?: string;
			graph: Record<string, unknown> | Array<Record<string, unknown>>;
	  };

key 필드는 기여를 중복 제거합니다 — 주어진 key의 마지막 기여만 사용됩니다.

page:fragments

능력: hooks.page-fragments:register

페이지에 스크립트 또는 HTML을 주입합니다. 네이티브 플러그인에서만 사용 가능합니다.

hooks: {
  "page:fragments": async (event, ctx) => {
    return [
      {
        kind: "external-script",
        placement: "body:end",
        src: "https://analytics.example.com/script.js",
        async: true,
      },
      {
        kind: "inline-script",
        placement: "head",
        code: `window.siteId = "abc123";`,
      },
    ];
  },
}

기여 타입

type PageFragmentContribution =
	| {
			kind: "external-script";
			placement: "head" | "body:start" | "body:end";
			src: string;
			async?: boolean;
			defer?: boolean;
			attributes?: Record<string, string>;
			key?: string;
		}
	| {
			kind: "inline-script";
			placement: "head" | "body:start" | "body:end";
			code: string;
			attributes?: Record<string, string>;
			key?: string;
		}
	| {
			kind: "html";
			placement: "head" | "body:start" | "body:end";
			html: string;
			key?: string;
		};

훅 구성

훅은 핸들러 함수 또는 구성 객체를 받습니다:

hooks: {
  // 간단한 핸들러
  "content:afterSave": async (event, ctx) => { ... },

  // 구성 포함
  "content:beforeSave": {
    priority: 50,        // 낮은 값이 먼저 실행 (기본값: 100)
    timeout: 10000,      // 최대 실행 시간 ms (기본값: 5000)
    dependencies: [],    // 이 플러그인들 이후에 실행
    errorPolicy: "abort", // "continue" 또는 "abort" (기본값)
    handler: async (event, ctx) => { ... },
  },
}

구성 옵션

플러그인 컨텍스트

모든 훅은 플러그인 API에 접근할 수 있는 컨텍스트 객체를 받습니다:

interface PluginContext {
	plugin: { id: string; version: string };
	storage: PluginStorage;
	kv: KVAccess;
	content?: ContentAccess;
	media?: MediaAccess;
	http?: HttpAccess;
	log: LogAccess;
	site: { name: string; url: string; locale: string };
	url(path: string): string;
	users?: UserAccess;
	cron?: CronAccess;
	email?: EmailAccess;
}

능력 요구사항과 메서드 세부사항은 플러그인 개요 — 플러그인 컨텍스트를 참조하세요.

에러 처리

훅의 에러는 errorPolicy에 따라 기록되고 처리됩니다:

• "abort" (기본값) — 실행 중지, 해당하는 경우 트랜잭션 롤백
• "continue" — 에러를 기록하고 다음 훅으로 계속

hooks: {
  "content:beforeSave": {
    errorPolicy: "continue",
    handler: async (event, ctx) => {
      try {
        await ctx.http?.fetch("https://api.example.com/validate");
      } catch (error) {
        ctx.log.warn("Validation service unavailable", error);
      }
    },
  },
}

실행 순서

훅은 이 순서로 실행됩니다:

1. priority로 정렬 (오름차순)
2. dependencies가 있는 플러그인은 의존성 이후에 실행
3. 동일 우선순위 내에서 순서는 결정적이지만 미지정

// 이것이 첫 번째로 실행 (우선순위 10)
{ priority: 10, handler: ... }

// 이것이 두 번째로 실행 (우선순위 50)
{ priority: 50, handler: ... }

// 이것이 마지막으로 실행 (기본 우선순위 100)
{ handler: ... }