emdash 1.0.1 → 1.1.0

package/dist/types-ClFEExxn.mjs

@@ -1,37 +0,0 @@
-import { CAPABILITY_RENAMES, isDeprecatedCapability, normalizeCapabilities, normalizeCapability } from "@emdash-cms/plugin-types";
-
-//#region src/plugins/types.ts
-const PLUGIN_CAPABILITY_IMPLICATIONS = [
-	["content:write", "content:read"],
-	["content:revisions:read", "content:read"],
-	["taxonomies:write", "taxonomies:read"],
-	["content:publish", "content:read"],
-	["media:write", "media:read"],
-	["comments:moderate", "comments:read"],
-	["redirects:write", "redirects:read"],
-	["network:request:unrestricted", "network:request"]
-];
-function normalizePluginCapabilities(capabilities) {
-	const normalized = new Set(normalizeCapabilities(capabilities));
-	for (const [granted, implied] of PLUGIN_CAPABILITY_IMPLICATIONS) if (normalized.has(granted)) normalized.add(implied);
-	return [...normalized];
-}
-const WARNED_DEPRECATED_CAPABILITY_PLUGINS = Symbol.for("emdash:warned-deprecated-capability-plugins");
-/**
-* Warn, once per plugin per process, that a plugin declares deprecated
-* capability names. Call with the plugin's raw, un-normalized capabilities.
-*/
-function warnDeprecatedPluginCapabilities(pluginId, capabilities) {
-	const deprecated = capabilities.filter(isDeprecatedCapability);
-	if (deprecated.length === 0) return;
-	const g = globalThis;
-	const warned = g[WARNED_DEPRECATED_CAPABILITY_PLUGINS] ??= /* @__PURE__ */ new Set();
-	if (warned.has(pluginId)) return;
-	warned.add(pluginId);
-	const renames = deprecated.map((cap) => `${cap} → ${CAPABILITY_RENAMES[cap]}`).join(", ");
-	console.warn(`[emdash] Plugin "${pluginId}" declares deprecated capability names (${renames}). They still work, but support will be removed in a future major release. Update the plugin, or ask its author to publish a version that uses the current names.`);
-}
-
-//#endregion
-export { normalizePluginCapabilities as a, normalizeCapability as i, isDeprecatedCapability as n, warnDeprecatedPluginCapabilities as o, normalizeCapabilities as r, CAPABILITY_RENAMES as t };
-//# sourceMappingURL=types-ClFEExxn.mjs.map

package/dist/types-ClFEExxn.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"types-ClFEExxn.mjs","names":[],"sources":["../src/plugins/types.ts"],"sourcesContent":["/**\n * Plugin System Types v2\n *\n * New plugin API with:\n * - Single unified context shape for all hooks and routes\n * - Paginated storage queries (no async iterators)\n * - Unified KV API (replaces settings + options)\n * - Explicit ctx.http and ctx.log\n *\n */\n\nimport type { Permission } from \"@emdash-cms/auth\";\nimport type { ConfirmDialog, Element, PluginUiContext } from \"@emdash-cms/blocks\";\n// The plugin capability vocabulary, the legacy-rename map, and the manifest\n// shape are authored once in @emdash-cms/plugin-types and shared between core\n// (the manifest reader at install/runtime) and @emdash-cms/plugin-cli (the\n// manifest writer at bundle/publish time).\n//\n// We import-and-re-export here so existing internal callers keep working\n// (e.g. `import { PluginCapability } from \"../plugins/types.js\"`).\nimport {\n\tCAPABILITY_RENAMES,\n\tcapabilitiesToDeclaredAccess,\n\tdeclaredAccessToCapabilities,\n\tisDeprecatedCapability,\n\tnormalizeCapabilities,\n\tnormalizeCapability,\n\ttype CurrentPluginCapability,\n\ttype DeclaredAccess,\n\ttype DeprecatedPluginCapability,\n\ttype ManifestHookEntry,\n\ttype ManifestMcpTool,\n\ttype ManifestRouteEntry,\n\ttype PluginMcpManifestConfig,\n\ttype PluginCapability,\n\ttype PluginEditorDraftAccess,\n\ttype PluginEditorDraftFieldSelector,\n\ttype PluginFormData,\n\ttype PluginRouteBodyMode,\n\ttype PluginRouteQuery,\n\ttype PluginRouteRequest,\n\ttype PluginStorageConfig,\n\ttype RouteOptions,\n\ttype StorageCollectionConfig,\n} from \"@emdash-cms/plugin-types\";\nimport type { JSX } from \"astro/jsx-runtime\";\nimport type { z } from \"astro/zod\";\n// =============================================================================\n// Core Types\n// =============================================================================\n\nimport type { ContentFieldFilters } from \"../content-list-query.js\";\nimport type { FieldType, FieldValidation, FieldWidgetOptions } from \"../schema/types.js\";\n\nexport type {\n\tContentFieldFilterScalar,\n\tContentFieldFilterValue,\n\tContentFieldFilters,\n\tContentFieldInFilter,\n\tContentFieldRangeFilter,\n} from \"../content-list-query.js\";\n\nexport {\n\tCAPABILITY_RENAMES,\n\tcapabilitiesToDeclaredAccess,\n\tdeclaredAccessToCapabilities,\n\tisDeprecatedCapability,\n\tnormalizeCapabilities,\n\tnormalizeCapability,\n\ttype CurrentPluginCapability,\n\ttype DeclaredAccess,\n\ttype DeprecatedPluginCapability,\n\ttype ManifestHookEntry,\n\ttype ManifestMcpTool,\n\ttype ManifestRouteEntry,\n\ttype PluginMcpManifestConfig,\n\ttype PluginCapability,\n\ttype PluginEditorDraftAccess,\n\ttype PluginEditorDraftFieldSelector,\n\ttype PluginStorageConfig,\n\ttype StorageCollectionConfig,\n};\n\nexport const PLUGIN_CAPABILITY_IMPLICATIONS: ReadonlyArray<\n\treadonly [PluginCapability, PluginCapability]\n> = [\n\t[\"content:write\", \"content:read\"],\n\t[\"content:revisions:read\", \"content:read\"],\n\t[\"taxonomies:write\", \"taxonomies:read\"],\n\t[\"content:publish\", \"content:read\"],\n\t[\"media:write\", \"media:read\"],\n\t[\"comments:moderate\", \"comments:read\"],\n\t[\"redirects:write\", \"redirects:read\"],\n\t[\"network:request:unrestricted\", \"network:request\"],\n];\n\nexport function normalizePluginCapabilities(\n\tcapabilities: readonly PluginCapability[],\n): PluginCapability[];\nexport function normalizePluginCapabilities(capabilities: readonly string[]): string[];\nexport function normalizePluginCapabilities(capabilities: readonly string[]): string[] {\n\tconst normalized = new Set(normalizeCapabilities(capabilities));\n\tfor (const [granted, implied] of PLUGIN_CAPABILITY_IMPLICATIONS) {\n\t\tif (normalized.has(granted)) normalized.add(implied);\n\t}\n\treturn [...normalized];\n}\n\nconst WARNED_DEPRECATED_CAPABILITY_PLUGINS = Symbol.for(\n\t\"emdash:warned-deprecated-capability-plugins\",\n);\n\n/**\n * Warn, once per plugin per process, that a plugin declares deprecated\n * capability names. Call with the plugin's raw, un-normalized capabilities.\n */\nexport function warnDeprecatedPluginCapabilities(\n\tpluginId: string,\n\tcapabilities: readonly string[],\n): void {\n\tconst deprecated = capabilities.filter(isDeprecatedCapability);\n\tif (deprecated.length === 0) return;\n\n\tconst g = globalThis as Record<symbol, unknown>;\n\t// eslint-disable-next-line typescript/no-unsafe-type-assertion -- globalThis singleton pattern (see request-context.ts)\n\tconst warned = (g[WARNED_DEPRECATED_CAPABILITY_PLUGINS] ??= new Set<string>()) as Set<string>;\n\tif (warned.has(pluginId)) return;\n\twarned.add(pluginId);\n\n\tconst renames = deprecated.map((cap) => `${cap} → ${CAPABILITY_RENAMES[cap]}`).join(\", \");\n\tconsole.warn(\n\t\t`[emdash] Plugin \"${pluginId}\" declares deprecated capability names (${renames}). ` +\n\t\t\t\"They still work, but support will be removed in a future major release. \" +\n\t\t\t\"Update the plugin, or ask its author to publish a version that uses the current names.\",\n\t);\n}\n\n// =============================================================================\n// Storage Types\n// =============================================================================\n//\n// `StorageCollectionConfig` and `PluginStorageConfig` are re-exported above\n// from `@emdash-cms/plugin-types`. The manifest carries these shapes\n// verbatim; both this package (reader) and plugin-cli (writer) agree on\n// the same types via the shared package.\n\n/**\n * Query filter operators\n */\nexport interface RangeFilter {\n\tgt?: number | string;\n\tgte?: number | string;\n\tlt?: number | string;\n\tlte?: number | string;\n}\n\nexport interface InFilter {\n\tin: Array<string | number>;\n}\n\nexport interface StartsWithFilter {\n\tstartsWith: string;\n}\n\n/**\n * Where clause value types\n */\nexport type WhereValue =\n\t| string\n\t| number\n\t| boolean\n\t| null\n\t| RangeFilter\n\t| InFilter\n\t| StartsWithFilter;\n\n/**\n * Where clause for storage queries\n */\nexport type WhereClause = Record<string, WhereValue>;\n\n/**\n * Query options for storage.query()\n */\nexport interface QueryOptions {\n\twhere?: WhereClause;\n\torderBy?: Record<string, \"asc\" | \"desc\">;\n\t/** Default 50, max 100 */\n\tlimit?: number;\n\tcursor?: string;\n}\n\n/**\n * Paginated result (used by storage.query, content.list, media.list)\n */\nexport interface PaginatedResult<T> {\n\titems: T[];\n\tcursor?: string;\n\thasMore: boolean;\n}\n\nexport interface VersionedValue<T = unknown> {\n\tvalue: T;\n\t/** Opaque host revision, valid only for the key from which it was read. */\n\trevision: string;\n}\n\nexport type ConditionalWriteResult = { applied: true; revision: string } | { applied: false };\n\nexport interface ConditionalDeleteResult {\n\tapplied: boolean;\n}\n\n/**\n * A single per-field integer delta for {@link StorageCollection.updateIf}.\n *\n * `inc`/`dec` values must be safe integers, enforced at runtime with\n * `Number.isSafeInteger` (which also rejects `NaN`/`Infinity`), because a TS\n * `number` cannot forbid float literals. Deltas are applied entirely in-SQL\n * over the stored value with `COALESCE(<value>, 0) ± n`, so a delta on a\n * missing or JSON-`null` field starts from `0` (never corrupts the document).\n *\n * `updateIf` does NOT clamp: a `dec` can drive a field negative when the\n * `where` guard doesn't cover the delta magnitude (e.g. stock `2` with\n * `where: { stock: { gte: 1 } }` and `delta: { stock: { dec: 3 } }` → `-1`,\n * `applied: true`). The guard is the caller's responsibility — pair a `dec: k`\n * with a `gte: k` guard to prevent underflow.\n */\nexport type NumericDelta = { inc: number } | { dec: number };\n\n/**\n * Arguments to {@link StorageCollection.updateIf}.\n *\n * `where` reuses the {@link QueryOptions} `WhereClause` verbatim — the guard is\n * evaluated in-SQL with the same numeric-correct, total comparisons as\n * `query()`. An empty `where: {}` emits no guard, i.e. it matches the row\n * unconditionally (update-if-row-exists) — a footgun in the no-oversell case,\n * where a real predicate (e.g. `{ stock: { gte: 1 } }`) is what you want.\n *\n * At least one of `set` / `delta` must be present (a runtime error is thrown\n * otherwise). A field may not appear in both `set` and `delta` in the same\n * call. `set` and `delta` are separate arguments (not a union) so a wholesale\n * value that happens to look like `{ inc: 5 }` is never mistaken for a delta.\n */\nexport interface UpdateIfArgs<T> {\n\t/**\n\t * Guard evaluated in-SQL; identical semantics to `query({ where })`. An\n\t * empty `{}` means \"match the row unconditionally (no guard)\".\n\t */\n\twhere: WhereClause;\n\t/** Wholesale field values merged into the stored JSON document. */\n\tset?: Partial<T>;\n\t/** Per-field integer deltas applied in-SQL (`COALESCE(base, 0) ± n`). */\n\tdelta?: { [K in keyof T]?: NumericDelta };\n}\n\n/**\n * Result of {@link StorageCollection.updateIf}.\n *\n * `applied: false` intentionally conflates \"row absent\" and \"guard failed\": a\n * single-statement guarded `UPDATE` cannot distinguish them, and the caller\n * should not need to. `updateIf` is update-only — it never inserts a missing\n * row.\n */\nexport type UpdateIfResult<T> = { applied: true; data: T } | { applied: false };\n\n/**\n * Storage collection interface - the API exposed to plugins\n * No async iterators - all operations return promises with pagination\n */\nexport interface StorageCollection<T = unknown> {\n\t// Basic CRUD\n\tget(id: string): Promise<T | null>;\n\tput(id: string, data: T): Promise<void>;\n\tdelete(id: string): Promise<boolean>;\n\texists(id: string): Promise<boolean>;\n\t/** A stored JSON null returns an envelope with value: null; only an absent row returns null. */\n\tgetVersioned(id: string): Promise<VersionedValue<T> | null>;\n\t/** A null expected revision creates only when absent. Errors reject; conflicts return applied: false. */\n\tcompareAndSet(\n\t\tid: string,\n\t\texpectedRevision: string | null,\n\t\tdata: T,\n\t): Promise<ConditionalWriteResult>;\n\tcompareAndDelete(id: string, expectedRevision: string): Promise<ConditionalDeleteResult>;\n\n\t// Batch operations\n\tgetMany(ids: string[]): Promise<Map<string, T>>;\n\tputMany(items: Array<{ id: string; data: T }>): Promise<void>;\n\tdeleteMany(ids: string[]): Promise<number>;\n\n\t// Query - always paginated\n\tquery(options?: QueryOptions): Promise<PaginatedResult<{ id: string; data: T }>>;\n\tcount(where?: WhereClause): Promise<number>;\n\n\t// Conditional write (single-statement, atomic per row).\n\t/**\n\t * Predicate-guarded atomic update. Applies `set`/`delta` to the row `id`\n\t * only if it exists and the `where` guard matches, in a single guarded\n\t * `UPDATE … RETURNING`. This is the no-oversell primitive: the guard and the\n\t * arithmetic live in one statement, so N concurrent guarded decrements\n\t * serialize correctly. `applied: false` means the row was absent OR the\n\t * guard failed (the two are intentionally indistinguishable). Non-object\n\t * documents, invalid counters and unsafe arithmetic results also fail the\n\t * guard. Never inserts.\n\t *\n\t * Serialization failures and deadlocks throw `StorageSerializationError`.\n\t * Retry the write with a bounded policy; restart an explicit transaction\n\t * before retrying its operations.\n\t */\n\tupdateIf(id: string, args: UpdateIfArgs<T>): Promise<UpdateIfResult<T>>;\n}\n\n/**\n * Plugin storage context - typed based on declared collections\n */\nexport type PluginStorage<T extends PluginStorageConfig> = {\n\t[K in keyof T]: StorageCollection;\n};\n\n// =============================================================================\n// Context APIs\n// =============================================================================\n\n/**\n * Plugin-scoped key-value state.\n *\n * Convention:\n * - `state:*` - Internal plugin state (not shown to users)\n * - `cache:*` - Reusable computed or remote data\n *\n * The `settings:*` namespace remains a compatibility alias through EmDash\n * 0.x. New code uses `PluginContext.settings` for user configuration.\n */\nexport interface KVAccess {\n\tget<T>(key: string): Promise<T | null>;\n\tgetVersioned<T>(key: string): Promise<VersionedValue<T> | null>;\n\t/** A null expected revision creates only when absent. Errors reject; conflicts return applied: false. */\n\tcompareAndSet(\n\t\tkey: string,\n\t\texpectedRevision: string | null,\n\t\tvalue: unknown,\n\t): Promise<ConditionalWriteResult>;\n\tcompareAndDelete(key: string, expectedRevision: string): Promise<ConditionalDeleteResult>;\n\tset(key: string, value: unknown): Promise<void>;\n\tdelete(key: string): Promise<boolean>;\n\tlist(prefix?: string): Promise<Array<{ key: string; value: unknown }>>;\n}\n\n/** Plugin settings. Fields declared as `secret` in `admin.settingsSchema` are encrypted. */\nexport interface SettingsAccess {\n\tget<T>(key: string): Promise<T | null>;\n\tgetVersioned<T>(key: string): Promise<VersionedValue<T> | null>;\n\tcompareAndSet(\n\t\tkey: string,\n\t\texpectedRevision: string | null,\n\t\tvalue: unknown,\n\t): Promise<ConditionalWriteResult>;\n\tcompareAndDelete(key: string, expectedRevision: string): Promise<ConditionalDeleteResult>;\n\tset(key: string, value: unknown): Promise<void>;\n\tdelete(key: string): Promise<boolean>;\n\tlist(prefix?: string): Promise<Array<{ key: string; value: unknown }>>;\n}\n\n/**\n * SEO metadata for a content item, as stored in the core SEO panel.\n *\n * Only present on items in collections with `has_seo = 1`. For collections\n * without SEO enabled, `ContentItem.seo` is `undefined`.\n */\nexport interface ContentItemSeo {\n\ttitle: string | null;\n\tdescription: string | null;\n\timage: string | null;\n\tcanonical: string | null;\n\tnoIndex: boolean;\n}\n\n/**\n * SEO input accepted by content write operations.\n *\n * All fields are optional — only fields that are present overwrite existing\n * values. An empty object is treated as a no-op.\n */\nexport interface ContentItemSeoInput {\n\ttitle?: string | null;\n\tdescription?: string | null;\n\timage?: string | null;\n\tcanonical?: string | null;\n\tnoIndex?: boolean;\n}\n\n/**\n * Content item returned from content API\n */\nexport interface ContentItem {\n\tid: string;\n\ttype: string;\n\tslug: string | null;\n\tstatus: string;\n\tlocale: string | null;\n\tdata: Record<string, unknown>;\n\t/**\n\t * SEO metadata, populated when the collection has SEO enabled\n\t * (`has_seo = 1`). `undefined` for non-SEO collections.\n\t */\n\tseo?: ContentItemSeo;\n\tcreatedAt: string;\n\tupdatedAt: string;\n\tpublishedAt: string | null;\n\t/** Scheduled publication time, if set (e.g. scheduled items or scheduled draft changes). */\n\tscheduledAt?: string | null;\n\tauthorId?: string | null;\n\ttranslationGroup?: string | null;\n\tliveRevisionId?: string | null;\n\tdraftRevisionId?: string | null;\n\tversion?: number;\n}\n\nexport interface ContentTranslationSummary {\n\tid: string;\n\tlocale: string | null;\n\tslug: string | null;\n\tstatus: string;\n\tupdatedAt: string;\n}\n\nexport interface ContentRevisionInfo {\n\tid: string;\n\tcollection: string;\n\tentryId: string;\n\tdata: Record<string, unknown>;\n\tcreatedAt: string;\n}\n\nexport interface FieldSchemaInfo {\n\tslug: string;\n\tlabel: string;\n\ttype: FieldType;\n\trequired: boolean;\n\tunique: boolean;\n\tdefault?: unknown;\n\tvalidation?: FieldValidation;\n\twidget?: string;\n\toptions?: FieldWidgetOptions;\n\tsearchable: boolean;\n\tindexed: boolean;\n\ttranslatable: boolean;\n\tsortOrder: number;\n}\n\nexport interface CollectionSchemaInfo {\n\tslug: string;\n\tlabel: string;\n\tlabelSingular: string | null;\n\tdescription: string | null;\n\tsupports: string[];\n\thasSeo: boolean;\n\ttitleField: string | null;\n\tdateField: string | null;\n\turlPattern: string | null;\n\troutable: boolean;\n\thidden: boolean;\n\tfields: FieldSchemaInfo[];\n}\n\nexport interface SchemaAccess {\n\tlistCollections(): Promise<CollectionSchemaInfo[]>;\n\tgetCollection(slug: string): Promise<CollectionSchemaInfo | null>;\n}\n\nexport interface ContentListWhere {\n\t/** Exact match on `status` (e.g. `\"published\"`, `\"draft\"`). */\n\tstatus?: string;\n\t/** Exact match on `locale` (e.g. `\"en\"`, `\"fr-CA\"`). */\n\tlocale?: string;\n\t/** AND-combined filters over custom fields explicitly marked as indexed. */\n\tfieldFilters?: ContentFieldFilters;\n}\n\n/**\n * Content list options\n */\nexport interface ContentListOptions {\n\tlimit?: number;\n\tcursor?: string;\n\torderBy?: Record<string, \"asc\" | \"desc\">;\n\twhere?: ContentListWhere;\n}\n\n/**\n * Input accepted by `content.create` / `content.update`.\n *\n * Most entries are field slugs mapped to their values. The reserved `seo`\n * key is extracted and routed to the core SEO panel (the `_emdash_seo`\n * table), matching the shape accepted by the REST API. Passing `seo` for a\n * collection that does not have SEO enabled throws a validation error.\n */\nexport type ContentWriteInput = Record<string, unknown> & {\n\tseo?: ContentItemSeoInput;\n};\n\n/** Options accepted by `content.create`. */\nexport interface ContentCreateOptions {\n\t/** Locale for the new content row. Defaults to the configured site locale, then `en`. */\n\tlocale?: string;\n\t/** Existing row in the same collection whose translation group the new row joins. */\n\ttranslationOf?: string;\n}\n\nexport type PluginContentCreateCallback = (\n\tpluginId: string,\n\tcollection: string,\n\tdata: ContentWriteInput,\n\toptions?: ContentCreateOptions & {\n\t\t/** Save-hook origin supplied by sandbox transports to prevent hook re-entry. */\n\t\toriginHook?: \"content:beforeSave\" | \"content:afterSave\";\n\t\tsandboxOrigin?: true;\n\t},\n) => Promise<ContentItem>;\n\n/**\n * Taxonomy definition returned from the taxonomy API (e.g. \"category\", \"tag\").\n */\nexport interface TaxonomyDefInfo {\n\tname: string;\n\tlabel: string;\n\tlabelSingular: string | null;\n\thierarchical: boolean;\n\t/** Collections this taxonomy is attached to (e.g. `[\"posts\"]`). */\n\tcollections: string[];\n\tlocale: string;\n}\n\n/**\n * Taxonomy term returned from the taxonomy API. Flat shape — for hierarchical\n * taxonomies the tree is reconstructed via `parentId` (which stores the\n * parent's locale-agnostic `translationGroup`).\n */\nexport interface TaxonomyTermInfo {\n\tid: string;\n\t/** Taxonomy name this term belongs to (e.g. \"category\"). */\n\ttaxonomy: string;\n\tslug: string;\n\tlabel: string;\n\tparentId: string | null;\n\t/** Term metadata as edited in the admin (`description` etc.). */\n\tdata: Record<string, unknown> | null;\n\tlocale: string;\n\ttranslationGroup: string | null;\n}\n\n/**\n * Options accepted by taxonomy read operations. Omitting `locale` returns\n * rows for every locale.\n */\nexport interface TaxonomyReadOptions {\n\tlocale?: string;\n}\n\nexport interface TaxonomyTermCreateInput {\n\tlabel: string;\n\tslug?: string;\n\tparentId?: string | null;\n\tdescription?: string;\n\tlocale?: string;\n\ttranslationOf?: string;\n}\n\n/**\n * Content access interface - capability-gated\n */\nexport interface ContentAccess {\n\t// Read operations (requires read:content)\n\tget(collection: string, id: string): Promise<ContentItem | null>;\n\tlist(collection: string, options?: ContentListOptions): Promise<PaginatedResult<ContentItem>>;\n\tgetTranslations?(\n\t\tcollection: string,\n\t\tid: string,\n\t): Promise<{ translationGroup: string; translations: ContentTranslationSummary[] }>;\n\tgetPublicUrl?(collection: string, id: string): Promise<string | null>;\n\tlistRevisions?(\n\t\tcollection: string,\n\t\tid: string,\n\t\toptions?: { limit?: number },\n\t): Promise<ContentRevisionInfo[]>;\n\tgetRevision?(\n\t\tcollection: string,\n\t\tid: string,\n\t\trevisionId: string,\n\t): Promise<ContentRevisionInfo | null>;\n\n\t// Write operations (requires write:content) - optional on interface\n\tcreate?(\n\t\tcollection: string,\n\t\tdata: ContentWriteInput,\n\t\toptions?: ContentCreateOptions,\n\t): Promise<ContentItem>;\n\tupdate?(collection: string, id: string, data: ContentWriteInput): Promise<ContentItem>;\n\tdelete?(collection: string, id: string): Promise<boolean>;\n\tgetVersioned?(collection: string, id: string): Promise<VersionedContentItem | null>;\n\tpublish?(\n\t\tcollection: string,\n\t\tid: string,\n\t\toptions: { _rev: string },\n\t): Promise<VersionedContentItem>;\n\tunpublish?(\n\t\tcollection: string,\n\t\tid: string,\n\t\toptions: { _rev: string },\n\t): Promise<VersionedContentItem>;\n\tschedule?(\n\t\tcollection: string,\n\t\tid: string,\n\t\toptions: { scheduledAt: string; _rev: string },\n\t): Promise<VersionedContentItem>;\n\tunschedule?(\n\t\tcollection: string,\n\t\tid: string,\n\t\toptions: { _rev: string },\n\t): Promise<VersionedContentItem>;\n\tgetTrashedVersioned?(collection: string, id: string): Promise<VersionedContentItem | null>;\n\trestore?(\n\t\tcollection: string,\n\t\tid: string,\n\t\toptions: { _rev: string },\n\t): Promise<VersionedContentItem>;\n}\n\nexport interface VersionedContentItem {\n\titem: ContentItem;\n\t_rev: string;\n}\n\nexport interface ContentPublicationAccess extends ContentAccess {\n\tgetVersioned(collection: string, id: string): Promise<VersionedContentItem | null>;\n\tpublish(collection: string, id: string, options: { _rev: string }): Promise<VersionedContentItem>;\n\tunpublish(\n\t\tcollection: string,\n\t\tid: string,\n\t\toptions: { _rev: string },\n\t): Promise<VersionedContentItem>;\n\tschedule(\n\t\tcollection: string,\n\t\tid: string,\n\t\toptions: { scheduledAt: string; _rev: string },\n\t): Promise<VersionedContentItem>;\n\tunschedule(\n\t\tcollection: string,\n\t\tid: string,\n\t\toptions: { _rev: string },\n\t): Promise<VersionedContentItem>;\n}\n\nexport interface ContentRestoreAccess {\n\tgetTrashedVersioned(collection: string, id: string): Promise<VersionedContentItem | null>;\n\trestore(collection: string, id: string, options: { _rev: string }): Promise<VersionedContentItem>;\n}\n\n/**\n * Taxonomy access interface — capability-gated on `taxonomies:read`.\n */\nexport interface TaxonomyAccess {\n\t/** List taxonomy definitions. */\n\tgetAll(options?: TaxonomyReadOptions): Promise<TaxonomyDefInfo[]>;\n\t/** All terms of a taxonomy, ordered by label. */\n\tgetTerms(taxonomy: string, options?: TaxonomyReadOptions): Promise<TaxonomyTermInfo[]>;\n\t/** Terms assigned to a content entry, optionally scoped to one taxonomy. */\n\tgetEntryTerms(\n\t\tcollection: string,\n\t\tentryId: string,\n\t\toptions?: TaxonomyReadOptions & { taxonomy?: string },\n\t): Promise<TaxonomyTermInfo[]>;\n\tcreateTerm?(taxonomy: string, input: TaxonomyTermCreateInput): Promise<TaxonomyTermInfo>;\n\taddEntryTerms?(\n\t\tcollection: string,\n\t\tentryId: string,\n\t\ttaxonomy: string,\n\t\ttermIds: string[],\n\t): Promise<TaxonomyTermInfo[]>;\n\tremoveEntryTerms?(\n\t\tcollection: string,\n\t\tentryId: string,\n\t\ttaxonomy: string,\n\t\ttermIds: string[],\n\t): Promise<TaxonomyTermInfo[]>;\n}\n\n/** Taxonomy mutations available with `taxonomies:write`. */\nexport interface TaxonomyAccessWithWrite extends TaxonomyAccess {\n\tcreateTerm(taxonomy: string, input: TaxonomyTermCreateInput): Promise<TaxonomyTermInfo>;\n\taddEntryTerms(\n\t\tcollection: string,\n\t\tentryId: string,\n\t\ttaxonomy: string,\n\t\ttermIds: string[],\n\t): Promise<TaxonomyTermInfo[]>;\n\tremoveEntryTerms(\n\t\tcollection: string,\n\t\tentryId: string,\n\t\ttaxonomy: string,\n\t\ttermIds: string[],\n\t): Promise<TaxonomyTermInfo[]>;\n}\n\n/**\n * Public byline profile returned from the byline API. Omits the linked user\n * account, guest flag, and custom field values.\n */\nexport interface BylineInfo {\n\tid: string;\n\tslug: string;\n\tdisplayName: string;\n\tbio: string | null;\n\twebsiteUrl: string | null;\n\t/** Media ID of the avatar image. Resolve it with `ctx.media.get()`. */\n\tavatarMediaId: string | null;\n\tlocale: string;\n\t/** Locale-agnostic identity shared by every translation of the byline. */\n\ttranslationGroup: string;\n}\n\n/** A byline credited on a content entry. */\nexport interface BylineCreditInfo {\n\tbyline: BylineInfo;\n\tsortOrder: number;\n\troleLabel: string | null;\n\t/**\n\t * `explicit` for a credit assigned in the editor; `inferred` when the entry\n\t * has no credits and the byline linked to the entry's author is used.\n\t */\n\tsource: \"explicit\" | \"inferred\";\n}\n\nexport interface BylineListOptions {\n\t/** Match one locale. Omit to list every locale. */\n\tlocale?: string;\n\t/** Page size, clamped to 1–100. Defaults to 50. */\n\tlimit?: number;\n\tcursor?: string;\n}\n\n/** Byline credits for one entry in a batched lookup. */\nexport interface EntryBylineCredits {\n\tentryId: string;\n\tbylines: BylineCreditInfo[];\n}\n\n/**\n * Byline access interface — capability-gated on `bylines:read`.\n */\nexport interface BylineAccess {\n\t/** Get a byline by its row ID. */\n\tget(id: string): Promise<BylineInfo | null>;\n\t/** List bylines, newest first. */\n\tlist(options?: BylineListOptions): Promise<PaginatedResult<BylineInfo>>;\n\t/**\n\t * Bylines credited on up to 100 entries of one collection, in the order the\n\t * IDs were given. Duplicate IDs are returned once. Credits resolve at each\n\t * entry's own locale, matching what the site renders. Trashed and missing\n\t * entries have no credits.\n\t */\n\tgetEntriesBylines(collection: string, entryIds: string[]): Promise<EntryBylineCredits[]>;\n}\n\nexport type RedirectStatus = 301 | 302 | 307 | 308 | 410 | 451;\n\nexport interface RedirectInfo {\n\tid: string;\n\tsource: string;\n\tdestination: string;\n\ttype: RedirectStatus;\n\tisPattern: boolean;\n\tenabled: boolean;\n\thits: number;\n\tlastHitAt: string | null;\n\tgroupName: string | null;\n\tauto: boolean;\n\tcreatedAt: string;\n\tupdatedAt: string;\n}\n\nexport interface VersionedRedirect {\n\tredirect: RedirectInfo;\n\t/** Opaque host revision. Pass it back unchanged for update or delete. */\n\t_rev: string;\n}\n\nexport interface RedirectListOptions {\n\tlimit?: number;\n\tcursor?: string;\n\tsearch?: string;\n\tgroup?: string;\n\tenabled?: boolean;\n\tauto?: boolean;\n}\n\nexport interface RedirectCreateInput {\n\tsource: string;\n\tdestination?: string;\n\ttype?: RedirectStatus;\n\tenabled?: boolean;\n\tgroupName?: string | null;\n}\n\nexport interface RedirectUpdateInput {\n\tsource?: string;\n\tdestination?: string;\n\ttype?: RedirectStatus;\n\tenabled?: boolean;\n\tgroupName?: string | null;\n}\n\nexport interface RedirectAccess {\n\tlist(options?: RedirectListOptions): Promise<PaginatedResult<RedirectInfo>>;\n\tget(id: string): Promise<VersionedRedirect | null>;\n\tcreate?(input: RedirectCreateInput): Promise<VersionedRedirect>;\n\tupdate?(id: string, input: RedirectUpdateInput & { _rev: string }): Promise<VersionedRedirect>;\n\tdelete?(id: string, options: { _rev: string }): Promise<boolean>;\n}\n\nexport interface RedirectAccessWithWrite extends RedirectAccess {\n\tcreate(input: RedirectCreateInput): Promise<VersionedRedirect>;\n\tupdate(id: string, input: RedirectUpdateInput & { _rev: string }): Promise<VersionedRedirect>;\n\tdelete(id: string, options: { _rev: string }): Promise<boolean>;\n}\n\n/**\n * Full content access with write operations\n */\nexport interface ContentAccessWithWrite extends ContentAccess {\n\tcreate(\n\t\tcollection: string,\n\t\tdata: ContentWriteInput,\n\t\toptions?: ContentCreateOptions,\n\t): Promise<ContentItem>;\n\tupdate(collection: string, id: string, data: ContentWriteInput): Promise<ContentItem>;\n\tdelete(collection: string, id: string): Promise<boolean>;\n}\n\n/**\n * Media item returned from media API\n */\nexport interface MediaItem {\n\tid: string;\n\tfilename: string;\n\tmimeType: string;\n\tsize: number | null;\n\turl: string;\n\tcreatedAt: string;\n\twidth?: number | null;\n\theight?: number | null;\n\talt?: string | null;\n\tcaption?: string | null;\n\tfocalX?: number | null;\n\tfocalY?: number | null;\n\tblurhash?: string | null;\n\tdominantColor?: string | null;\n\tfolderId?: string | null;\n\tstatus?: \"ready\";\n}\n\nexport interface MediaBytes {\n\tbytes: Uint8Array;\n\tfilename: string;\n\tmimeType: string;\n\tsize: number;\n\tcontentHash?: string;\n}\n\nexport interface MediaMetadataPatch {\n\talt?: string | null;\n\tcaption?: string | null;\n\tfocalX?: number | null;\n\tfocalY?: number | null;\n}\n\n/**\n * Media list options\n */\nexport interface MediaListOptions {\n\tlimit?: number;\n\tcursor?: string;\n\tmimeType?: string; // Filter by mime type prefix, e.g., \"image/\"\n}\n\n/**\n * Media access interface - capability-gated\n */\nexport interface MediaAccess {\n\t// Read operations (requires read:media)\n\tget(id: string): Promise<MediaItem | null>;\n\tlist(options?: MediaListOptions): Promise<PaginatedResult<MediaItem>>;\n\t/** Read ready media bytes, bounded by the caller's limit and the host maximum. */\n\treadBytes?(id: string, options?: { maxBytes?: number }): Promise<MediaBytes>;\n\t/** Change only alt text, caption, or the complete focal-point pair. */\n\tupdateMetadata?(id: string, patch: MediaMetadataPatch): Promise<MediaItem>;\n\n\t// Write operations (requires write:media) - optional on interface\n\tgetUploadUrl?(\n\t\tfilename: string,\n\t\tcontentType: string,\n\t): Promise<{ uploadUrl: string; mediaId: string }>;\n\t/**\n\t * Upload media bytes directly. Preferred in sandboxed mode where\n\t * plugins cannot make external requests to a presigned URL.\n\t * Returns the created media item.\n\t */\n\tupload?(\n\t\tfilename: string,\n\t\tcontentType: string,\n\t\tbytes: ArrayBuffer,\n\t): Promise<{ mediaId: string; storageKey: string; url: string }>;\n\tdelete?(id: string): Promise<boolean>;\n}\n\n/**\n * Full media access with write operations\n */\nexport interface MediaAccessWithWrite extends MediaAccess {\n\tgetUploadUrl(\n\t\tfilename: string,\n\t\tcontentType: string,\n\t): Promise<{ uploadUrl: string; mediaId: string }>;\n\tupload(\n\t\tfilename: string,\n\t\tcontentType: string,\n\t\tbytes: ArrayBuffer,\n\t): Promise<{ mediaId: string; storageKey: string; url: string }>;\n\tdelete(id: string): Promise<boolean>;\n}\n\n/**\n * HTTP client interface - requires network:request capability\n */\nexport interface HttpAccess {\n\t/**\n\t * Fetch an allowed external URL and return a buffered response.\n\t * Decoded request and response bodies are each limited to 8 MiB.\n\t */\n\tfetch(url: string, init?: RequestInit): Promise<Response>;\n}\n\n/**\n * Logger interface - always available\n */\nexport interface LogAccess {\n\tdebug(message: string, data?: unknown): void;\n\tinfo(message: string, data?: unknown): void;\n\twarn(message: string, data?: unknown): void;\n\terror(message: string, data?: unknown): void;\n}\n\n// =============================================================================\n// Site & User Access\n// =============================================================================\n\n/**\n * Site information available to all plugins\n */\nexport interface SiteInfo {\n\t/** Site name (from settings) */\n\tname: string;\n\t/** Site URL (from settings or request) */\n\turl: string;\n\t/** Site locale (from settings, defaults to \"en\") */\n\tlocale: string;\n\t/**\n\t * Astro's `trailingSlash` routing policy, from the host's Astro config.\n\t * Plugins that build absolute URLs (sitemap, canonical, hreflang) should\n\t * honor this so the URLs they emit match what the site serves. `createSiteInfo`\n\t * always populates it (defaulting to `\"ignore\"`, Astro's default); it is\n\t * optional on the type so pre-existing `SiteInfo` construction stays valid.\n\t */\n\ttrailingSlash?: \"always\" | \"never\" | \"ignore\";\n}\n\n/**\n * Read-only user information exposed to plugins.\n * Sensitive fields (password hashes, sessions, passkeys) are excluded.\n */\nexport interface UserInfo {\n\tid: string;\n\temail: string;\n\tname: string | null;\n\trole: number;\n\tcreatedAt: string;\n}\n\n/**\n * User access interface - requires read:users capability\n */\nexport interface UserAccess {\n\t/** Get a user by ID */\n\tget(id: string): Promise<UserInfo | null>;\n\t/** Get a user by email */\n\tgetByEmail(email: string): Promise<UserInfo | null>;\n\t/** List users with optional filters */\n\tlist(opts?: { role?: number; limit?: number; cursor?: string }): Promise<{\n\t\titems: UserInfo[];\n\t\tnextCursor?: string;\n\t}>;\n}\n\nexport type PluginCommentStatus = \"approved\" | \"pending\" | \"spam\";\n\n/** Comment data exposed by the explicit personal-data `comments:read` capability. */\nexport interface PluginComment {\n\tid: string;\n\tcollection: string;\n\tcontentId: string;\n\tparentId: string | null;\n\tauthorName: string;\n\tauthorEmail: string;\n\tbody: string;\n\tstatus: PluginCommentStatus;\n\tipHash: string | null;\n\tuserAgent: string | null;\n\tmoderationMetadata: Record<string, unknown> | null;\n\tcreatedAt: string;\n\tupdatedAt: string;\n}\n\nexport interface CommentListOptions {\n\tstatus?: PluginCommentStatus;\n\tcollection?: string;\n\tcontentId?: string;\n\tlimit?: number;\n\tcursor?: string;\n}\n\nexport interface CommentCountOptions {\n\tstatus?: PluginCommentStatus;\n\tcollection?: string;\n\tcontentId?: string;\n}\n\nexport interface CommentAccess {\n\tget(id: string): Promise<PluginComment | null>;\n\tlist(options?: CommentListOptions): Promise<PaginatedResult<PluginComment>>;\n\tcount(options?: CommentCountOptions): Promise<number>;\n\tsetStatus?(\n\t\tid: string,\n\t\tstatus: PluginCommentStatus,\n\t\toptions: { expectedStatus: PluginCommentStatus },\n\t): Promise<PluginComment>;\n}\n\n// =============================================================================\n// Plugin Context\n// =============================================================================\n\n/**\n * The unified plugin context - same shape for all hooks and routes\n */\nexport interface PluginContext<TStorage extends PluginStorageConfig = PluginStorageConfig> {\n\t/** Plugin metadata */\n\tplugin: {\n\t\tid: string;\n\t\tversion: string;\n\t};\n\n\t/** Storage collections - only if plugin declares storage */\n\tstorage: PluginStorage<TStorage>;\n\n\t/** Key-value store for internal state */\n\tkv: KVAccess;\n\n\t/** Plugin settings. Secret schema fields are encrypted by the host. */\n\tsettings: SettingsAccess;\n\n\t/** Content access - only if read:content or write:content capability */\n\tcontent?: ContentAccess | ContentAccessWithWrite;\n\t/** Schema discovery - only if schema:read capability */\n\tschema?: SchemaAccess;\n\n\t/** Taxonomy access - only if a taxonomy capability is declared. */\n\ttaxonomies?: TaxonomyAccess | TaxonomyAccessWithWrite;\n\n\t/** Byline access - only if bylines:read capability */\n\tbylines?: BylineAccess;\n\n\t/** Redirect access - only if redirects:read or redirects:write capability */\n\tredirects?: RedirectAccess | RedirectAccessWithWrite;\n\n\t/** Media access - only if read:media or write:media capability */\n\tmedia?: MediaAccess | MediaAccessWithWrite;\n\n\t/** HTTP client - only if network:request capability */\n\thttp?: HttpAccess;\n\n\t/** Logger - always available */\n\tlog: LogAccess;\n\n\t/** Site information - always available */\n\tsite: SiteInfo;\n\n\t/** URL helper - generates absolute URLs from paths. Always available. */\n\turl(path: string): string;\n\n\t/** User access - only if read:users capability */\n\tusers?: UserAccess;\n\n\t/** Comment access — only if comments:read or comments:moderate is declared. */\n\tcomments?: CommentAccess;\n\n\t/** Cron task scheduling - always available, scoped to plugin */\n\tcron?: CronAccess;\n\n\t/** Email access - only if email:send capability and a provider is configured */\n\temail?: EmailAccess;\n}\n\n// =============================================================================\n// Cron Types\n// =============================================================================\n\n/**\n * Cron access interface �� always available on plugin context, scoped to plugin.\n */\nexport interface CronAccess {\n\t/** Schedule a recurring or one-shot task */\n\tschedule(name: string, opts: { schedule: string; data?: Record<string, unknown> }): Promise<void>;\n\t/** Cancel a scheduled task */\n\tcancel(name: string): Promise<void>;\n\t/** List this plugin's scheduled tasks */\n\tlist(): Promise<CronTaskInfo[]>;\n}\n\n/**\n * Task info returned from CronAccess.list()\n */\nexport interface CronTaskInfo {\n\tname: string;\n\tschedule: string;\n\tnextRunAt: string;\n\tlastRunAt: string | null;\n}\n\n/**\n * Event passed to the `cron` hook handler\n */\nexport interface CronEvent {\n\tname: string;\n\tdata?: Record<string, unknown>;\n\tscheduledAt: string;\n}\n\n/**\n * Cron hook handler type\n */\nexport type CronHandler = (event: CronEvent, ctx: PluginContext) => Promise<void>;\n\n// =============================================================================\n// Email Types\n// =============================================================================\n\n/**\n * Email access interface — requires `email:send` capability.\n * Undefined when no `email:deliver` provider is configured.\n *\n * Related capabilities:\n * - `email:send` — grants ctx.email (this interface)\n * - `email:provide` — allows registering the `email:deliver` exclusive hook\n * - `email:intercept` — allows registering `email:beforeSend` / `email:afterSend` hooks\n */\nexport interface EmailAccess {\n\tsend(message: EmailMessage): Promise<void>;\n}\n\n/**\n * Email message shape\n */\nexport interface EmailMessage {\n\tto: string;\n\t/** Additional visible recipients. */\n\tcc?: string[];\n\t/** Address that replies go to instead of the sender. */\n\treplyTo?: string;\n\tsubject: string;\n\ttext: string;\n\thtml?: string;\n}\n\n/**\n * Event passed to email:beforeSend hooks (middleware — transform, validate, cancel)\n */\nexport interface EmailBeforeSendEvent {\n\tmessage: EmailMessage;\n\t/** Where the email originated — \"system\" for auth emails, plugin ID for plugin emails */\n\tsource: string;\n}\n\n/**\n * Event passed to email:deliver hook (exclusive — exactly one provider delivers)\n */\nexport interface EmailDeliverEvent {\n\tmessage: EmailMessage;\n\tsource: string;\n}\n\n/**\n * Event passed to email:afterSend hooks (logging, analytics, fire-and-forget)\n */\nexport interface EmailAfterSendEvent {\n\tmessage: EmailMessage;\n\tsource: string;\n}\n\n/**\n * Handler type for email:beforeSend hooks.\n * Returns modified message, or false to cancel delivery.\n */\nexport type EmailBeforeSendHandler = (\n\tevent: EmailBeforeSendEvent,\n\tctx: PluginContext,\n) => Promise<EmailMessage | false>;\n\n/**\n * Handler type for email:deliver hooks (exclusive provider).\n */\nexport type EmailDeliverHandler = (event: EmailDeliverEvent, ctx: PluginContext) => Promise<void>;\n\n/**\n * Handler type for email:afterSend hooks (fire-and-forget).\n */\nexport type EmailAfterSendHandler = (\n\tevent: EmailAfterSendEvent,\n\tctx: PluginContext,\n) => Promise<void>;\n\n// =============================================================================\n// Comment Types\n// =============================================================================\n\n/**\n * Collection comment settings (read from _emdash_collections)\n */\nexport interface CollectionCommentSettings {\n\tcommentsEnabled: boolean;\n\tcommentsModeration: \"all\" | \"first_time\" | \"none\";\n\tcommentsClosedAfterDays: number;\n\tcommentsAutoApproveUsers: boolean;\n}\n\n/**\n * Event passed to comment:beforeCreate hooks (middleware — transform, enrich, reject)\n */\nexport interface CommentBeforeCreateEvent {\n\tcomment: {\n\t\tcollection: string;\n\t\tcontentId: string;\n\t\tparentId: string | null;\n\t\tauthorName: string;\n\t\tauthorEmail: string;\n\t\tauthorUserId: string | null;\n\t\tbody: string;\n\t\tipHash: string | null;\n\t\tuserAgent: string | null;\n\t};\n\t/** Metadata bag — plugins can attach signals for the moderator */\n\tmetadata: Record<string, unknown>;\n}\n\n/**\n * Event passed to comment:moderate hook (exclusive — decides initial status)\n */\nexport interface CommentModerateEvent {\n\tcomment: CommentBeforeCreateEvent[\"comment\"];\n\tmetadata: Record<string, unknown>;\n\tcollectionSettings: CollectionCommentSettings;\n\t/** Number of prior approved comments from this email address */\n\tpriorApprovedCount: number;\n}\n\n/**\n * Moderation decision returned by the comment:moderate handler\n */\nexport interface ModerationDecision {\n\tstatus: \"approved\" | \"pending\" | \"spam\";\n\t/** Optional reason for admin visibility */\n\treason?: string;\n}\n\n/**\n * Stored comment shape (full record with id, status, timestamps)\n */\nexport interface StoredComment {\n\tid: string;\n\tcollection: string;\n\tcontentId: string;\n\tparentId: string | null;\n\tauthorName: string;\n\tauthorEmail: string;\n\tauthorUserId: string | null;\n\tbody: string;\n\tstatus: string;\n\tmoderationMetadata: Record<string, unknown> | null;\n\tcreatedAt: string;\n\tupdatedAt: string;\n}\n\n/**\n * Event passed to comment:afterCreate hooks (fire-and-forget)\n */\nexport interface CommentAfterCreateEvent {\n\tcomment: StoredComment;\n\tmetadata: Record<string, unknown>;\n\t/** The content item the comment is on */\n\tcontent: { id: string; collection: string; slug: string; title?: string };\n\t/** The content author (for notifications) */\n\tcontentAuthor?: { id: string; name: string | null; email: string };\n}\n\n/**\n * Event passed to comment:afterModerate hooks (fire-and-forget, admin status change)\n */\nexport interface CommentAfterModerateEvent {\n\tcomment: StoredComment;\n\tpreviousStatus: string;\n\tnewStatus: string;\n\t/** The admin who moderated */\n\tmoderator: { id: string; name: string | null };\n\t/** Identifies whether an administrator or a plugin initiated the transition. */\n\torigin?: { source: \"admin\"; userId: string } | { source: \"plugin\"; pluginId: string };\n}\n\n/**\n * Handler type for comment:beforeCreate hooks.\n * Returns modified event, or false to reject the comment.\n */\nexport type CommentBeforeCreateHandler = (\n\tevent: CommentBeforeCreateEvent,\n\tctx: PluginContext,\n) => Promise<CommentBeforeCreateEvent | false | void>;\n\n/**\n * Handler type for comment:moderate hook (exclusive provider).\n */\nexport type CommentModerateHandler = (\n\tevent: CommentModerateEvent,\n\tctx: PluginContext,\n) => Promise<ModerationDecision>;\n\n/**\n * Handler type for comment:afterCreate hooks (fire-and-forget).\n */\nexport type CommentAfterCreateHandler = (\n\tevent: CommentAfterCreateEvent,\n\tctx: PluginContext,\n) => Promise<void>;\n\n/**\n * Handler type for comment:afterModerate hooks (fire-and-forget).\n */\nexport type CommentAfterModerateHandler = (\n\tevent: CommentAfterModerateEvent,\n\tctx: PluginContext,\n) => Promise<void>;\n\n// =============================================================================\n// Hook Types\n// =============================================================================\n\n/**\n * Hook configuration\n */\nexport interface HookConfig<THandler> {\n\t/** Explicit ordering - lower numbers run first (default: 100) */\n\tpriority?: number;\n\t/** Max execution time in ms (default: 5000) */\n\ttimeout?: number;\n\t/** Run after these plugins */\n\tdependencies?: string[];\n\t/** Error handling policy */\n\terrorPolicy?: \"continue\" | \"abort\";\n\t/**\n\t * Mark this hook as exclusive — only one plugin can be the active provider.\n\t * Exclusive hooks skip the priority pipeline and dispatch only to the\n\t * admin-selected provider. Used for email:deliver, search, image optimization, etc.\n\t */\n\texclusive?: boolean;\n\t/** The hook handler */\n\thandler: THandler;\n}\n\n/**\n * Acting user that triggered a content hook. Present for authenticated\n * saves; absent for unauthenticated or internal writes.\n */\nexport interface ActorInfo {\n\treadonly id: string;\n\treadonly role: number;\n\treadonly source?: \"api\" | \"mcp\" | \"visual-editor\";\n}\n\nexport type ContentActionOrigin =\n\t| { source: \"api\" | \"mcp\" | \"visual-editor\" }\n\t| { source: \"plugin\"; pluginId: string }\n\t| { source: \"scheduler\" }\n\t| { source: \"system\" };\n\nexport type ContentPolicyDecision = void | { cancel: true; reason: string };\n\n/**\n * Content hook event\n */\nexport interface ContentHookEvent {\n\tcontent: Record<string, unknown>;\n\tcollection: string;\n\tisNew: boolean;\n\t/**\n\t * ID of the existing item on `content:beforeSave` for an update. Absent on\n\t * creates, where the ID is assigned when the save completes, and on\n\t * `content:afterSave`, where `content.id` carries it.\n\t */\n\tid?: string;\n\t/**\n\t * The acting user for this save. Carries the same authenticated identity\n\t * used to set the revision author, so plugins (e.g. audit logs) can record\n\t * who made the change.\n\t */\n\tactor?: ActorInfo;\n}\n\n/**\n * Content delete hook event\n */\nexport interface ContentDeleteEvent {\n\tid: string;\n\tcollection: string;\n\t/** `true` when the content is permanently deleted (not just trashed). */\n\tpermanent: boolean;\n}\n\n/**\n * Content state-change hook event (fired after publish, unpublish, restore,\n * schedule, or unschedule).\n */\nexport interface ContentStateChangeEvent {\n\tcontent: Record<string, unknown>;\n\tcollection: string;\n}\n\n/**\n * Content publish/unpublish hook event.\n */\nexport type ContentPublishStateChangeEvent = ContentStateChangeEvent;\n\n/**\n * Content restore hook event.\n */\nexport type ContentRestoreStateChangeEvent = ContentStateChangeEvent;\n\n/**\n * Content schedule/unschedule hook event.\n */\nexport type ContentScheduleStateChangeEvent = ContentStateChangeEvent;\n\nexport interface ContentPolicyEvent extends ContentStateChangeEvent {\n\torigin: ContentActionOrigin;\n\tactor?: ActorInfo;\n}\n\nexport interface ContentSchedulePolicyEvent extends ContentPolicyEvent {\n\tscheduledAt: string;\n}\n\n/**\n * Media hook event\n */\nexport interface MediaUploadEvent {\n\tfile: { name: string; type: string; size: number };\n}\n\n/**\n * Media after upload event\n */\nexport interface MediaAfterUploadEvent {\n\tmedia: MediaItem;\n}\n\n/**\n * Lifecycle hook event\n */\nexport interface LifecycleEvent {\n\t// Empty for install/activate/deactivate\n}\n\n/**\n * Uninstall hook event\n */\nexport interface UninstallEvent {\n\tdeleteData: boolean;\n}\n\n// Hook handler types - all receive (event, ctx) with unified context\nexport type ContentBeforeSaveHandler = (\n\tevent: ContentHookEvent,\n\tctx: PluginContext,\n) => Promise<Record<string, unknown> | void>;\n\nexport type ContentAfterSaveHandler = (\n\tevent: ContentHookEvent,\n\tctx: PluginContext,\n) => Promise<void>;\n\nexport type ContentBeforeDeleteHandler = (\n\tevent: ContentDeleteEvent,\n\tctx: PluginContext,\n) => Promise<boolean | void>;\n\nexport type ContentAfterDeleteHandler = (\n\tevent: ContentDeleteEvent,\n\tctx: PluginContext,\n) => Promise<void>;\n\nexport type ContentBeforePublishHandler = (\n\tevent: ContentPolicyEvent,\n\tctx: PluginContext,\n) => Promise<ContentPolicyDecision>;\n\nexport type ContentBeforeScheduleHandler = (\n\tevent: ContentSchedulePolicyEvent,\n\tctx: PluginContext,\n) => Promise<ContentPolicyDecision>;\n\nexport type ContentBeforeUnpublishHandler = (\n\tevent: ContentPolicyEvent,\n\tctx: PluginContext,\n) => Promise<ContentPolicyDecision>;\n\nexport type ContentAfterPublishHandler = (\n\tevent: ContentPublishStateChangeEvent,\n\tctx: PluginContext,\n) => Promise<void>;\n\nexport type ContentAfterUnpublishHandler = (\n\tevent: ContentPublishStateChangeEvent,\n\tctx: PluginContext,\n) => Promise<void>;\n\nexport type ContentAfterRestoreHandler = (\n\tevent: ContentRestoreStateChangeEvent,\n\tctx: PluginContext,\n) => Promise<void>;\n\nexport type ContentAfterScheduleHandler = (\n\tevent: ContentScheduleStateChangeEvent,\n\tctx: PluginContext,\n) => Promise<void>;\n\nexport type ContentAfterUnscheduleHandler = (\n\tevent: ContentScheduleStateChangeEvent,\n\tctx: PluginContext,\n) => Promise<void>;\n\n/**\n * Event for `byline:afterSave`, fired after a byline profile or one of its\n * locale translations is created or updated.\n */\nexport interface BylineAfterSaveEvent {\n\tbyline: BylineInfo;\n\tisNew: boolean;\n}\n\n/**\n * Event for `byline:afterDelete`, fired after a byline row is deleted. When it\n * was the last locale of its translation group, its credits have already been\n * removed from every entry.\n */\nexport interface BylineAfterDeleteEvent {\n\tbyline: BylineInfo;\n}\n\nexport type BylineAfterSaveHandler = (\n\tevent: BylineAfterSaveEvent,\n\tctx: PluginContext,\n) => Promise<void>;\n\nexport type BylineAfterDeleteHandler = (\n\tevent: BylineAfterDeleteEvent,\n\tctx: PluginContext,\n) => Promise<void>;\n\nexport type MediaBeforeUploadHandler = (\n\tevent: MediaUploadEvent,\n\tctx: PluginContext,\n) => Promise<{ name: string; type: string; size: number } | void>;\n\nexport type MediaAfterUploadHandler = (\n\tevent: MediaAfterUploadEvent,\n\tctx: PluginContext,\n) => Promise<void>;\n\nexport type LifecycleHandler = (event: LifecycleEvent, ctx: PluginContext) => Promise<void>;\n\nexport type UninstallHandler = (event: UninstallEvent, ctx: PluginContext) => Promise<void>;\n\n// =============================================================================\n// Public Page Contribution Types\n// =============================================================================\n\n/** Placement targets for page fragment contributions */\nexport type PagePlacement = \"head\" | \"body:start\" | \"body:end\";\n\n/**\n * A single breadcrumb trail item. Used by `PublicPageContext.breadcrumbs`\n * so themes can publish breadcrumb trails that SEO plugins consume.\n */\nexport interface BreadcrumbItem {\n\t/** Display name for this crumb (e.g. \"Home\", \"Blog\", \"My Post\"). */\n\tname: string;\n\t/** Absolute or root-relative URL for this crumb. */\n\turl: string;\n}\n\n/**\n * Describes the page being rendered. Passed to page hooks so plugins\n * can decide what to contribute without fetching content themselves.\n */\nexport interface PublicPageContext {\n\turl: string;\n\tpath: string;\n\tlocale: string | null;\n\tkind: \"content\" | \"custom\";\n\tpageType: string;\n\t/** Full document title for the rendered page */\n\ttitle: string | null;\n\t/** Page-only title for OG/Twitter/JSON-LD headline output */\n\tpageTitle?: string | null;\n\tdescription: string | null;\n\tcanonical: string | null;\n\timage: string | null;\n\tcontent?: {\n\t\tcollection: string;\n\t\tid: string;\n\t\tslug: string | null;\n\t};\n\t/** SEO meta for base metadata generation in EmDashHead */\n\tseo?: {\n\t\togTitle?: string | null;\n\t\togDescription?: string | null;\n\t\togImage?: string | null;\n\t\trobots?: string | null;\n\t};\n\t/** Article metadata for Open Graph article: tags */\n\tarticleMeta?: {\n\t\tpublishedTime?: string | null;\n\t\tmodifiedTime?: string | null;\n\t\tauthor?: string | null;\n\t};\n\t/** Site name for structured data and og:site_name */\n\tsiteName?: string;\n\t/**\n\t * Optional breadcrumb trail for this page, root first. When set,\n\t * SEO plugins should use this verbatim rather than deriving a trail\n\t * from `path`. Themes typically populate this at the point they\n\t * build the context (e.g. from a content hierarchy walk, taxonomy\n\t * lookup, or per-`pageType` routing logic).\n\t *\n\t * Semantics for consumers:\n\t *   - `undefined` — theme has no opinion; consumer falls back to\n\t *     its own derivation.\n\t *   - `[]` — this page has no breadcrumbs (e.g. homepage); consumer\n\t *     should skip `BreadcrumbList` emission entirely.\n\t *   - Non-empty array — used verbatim for `BreadcrumbList` output.\n\t */\n\tbreadcrumbs?: BreadcrumbItem[];\n\t/** Public-facing site URL (origin) for structured data */\n\tsiteUrl?: string;\n}\n\n// ── page:metadata ───────────────────────────────────────────────\n\nexport interface PageMetadataEvent {\n\tpage: PublicPageContext;\n}\n\n/**\n * Allowed rel values for link contributions.\n * This is a security-critical allowlist -- sandboxed plugins can only inject\n * link tags with these rel values. Adding \"stylesheet\", \"prefetch\", \"prerender\"\n * etc. would allow sandboxed plugins to inject external resources.\n */\nexport type PageMetadataLinkRel =\n\t| \"canonical\"\n\t| \"alternate\"\n\t| \"author\"\n\t| \"license\"\n\t| \"nlweb\"\n\t| \"site.standard.document\";\n\nexport type PageMetadataContribution =\n\t| { kind: \"meta\"; name: string; content: string; key?: string }\n\t| { kind: \"property\"; property: string; content: string; key?: string }\n\t| { kind: \"link\"; rel: PageMetadataLinkRel; href: string; hreflang?: string; key?: string }\n\t| {\n\t\t\tkind: \"jsonld\";\n\t\t\tid?: string;\n\t\t\tgraph: Record<string, unknown> | Array<Record<string, unknown>>;\n\t  };\n\nexport type PageMetadataHandler = (\n\tevent: PageMetadataEvent,\n\tctx: PluginContext,\n) =>\n\t| PageMetadataContribution\n\t| PageMetadataContribution[]\n\t| null\n\t| Promise<PageMetadataContribution | PageMetadataContribution[] | null>;\n\n// ── page:fragments (trusted-only) ──────────────────────────────\n\nexport interface PageFragmentEvent {\n\tpage: PublicPageContext;\n}\n\nexport type PageFragmentContribution =\n\t| {\n\t\t\tkind: \"external-script\";\n\t\t\tplacement: PagePlacement;\n\t\t\tsrc: string;\n\t\t\tasync?: boolean;\n\t\t\tdefer?: boolean;\n\t\t\tattributes?: Record<string, string>;\n\t\t\tkey?: string;\n\t  }\n\t| {\n\t\t\tkind: \"inline-script\";\n\t\t\tplacement: PagePlacement;\n\t\t\tcode: string;\n\t\t\tattributes?: Record<string, string>;\n\t\t\tkey?: string;\n\t  }\n\t| {\n\t\t\tkind: \"html\";\n\t\t\tplacement: PagePlacement;\n\t\t\thtml: string;\n\t\t\tkey?: string;\n\t  };\n\nexport type PageFragmentHandler = (\n\tevent: PageFragmentEvent,\n\tctx: PluginContext,\n) =>\n\t| PageFragmentContribution\n\t| PageFragmentContribution[]\n\t| null\n\t| Promise<PageFragmentContribution | PageFragmentContribution[] | null>;\n\n/**\n * Plugin hooks definition\n */\nexport interface PluginHooks {\n\t// Lifecycle hooks\n\t\"plugin:install\"?: HookConfig<LifecycleHandler> | LifecycleHandler;\n\t\"plugin:activate\"?: HookConfig<LifecycleHandler> | LifecycleHandler;\n\t\"plugin:deactivate\"?: HookConfig<LifecycleHandler> | LifecycleHandler;\n\t\"plugin:uninstall\"?: HookConfig<UninstallHandler> | UninstallHandler;\n\n\t// Content hooks\n\t\"content:beforeSave\"?: HookConfig<ContentBeforeSaveHandler> | ContentBeforeSaveHandler;\n\t\"content:afterSave\"?: HookConfig<ContentAfterSaveHandler> | ContentAfterSaveHandler;\n\t\"content:beforeDelete\"?: HookConfig<ContentBeforeDeleteHandler> | ContentBeforeDeleteHandler;\n\t\"content:afterDelete\"?: HookConfig<ContentAfterDeleteHandler> | ContentAfterDeleteHandler;\n\t\"content:beforePublish\"?: HookConfig<ContentBeforePublishHandler> | ContentBeforePublishHandler;\n\t\"content:beforeSchedule\"?:\n\t\t| HookConfig<ContentBeforeScheduleHandler>\n\t\t| ContentBeforeScheduleHandler;\n\t\"content:beforeUnpublish\"?:\n\t\t| HookConfig<ContentBeforeUnpublishHandler>\n\t\t| ContentBeforeUnpublishHandler;\n\t\"content:afterPublish\"?: HookConfig<ContentAfterPublishHandler> | ContentAfterPublishHandler;\n\t\"content:afterUnpublish\"?:\n\t\t| HookConfig<ContentAfterUnpublishHandler>\n\t\t| ContentAfterUnpublishHandler;\n\t\"content:afterRestore\"?: HookConfig<ContentAfterRestoreHandler> | ContentAfterRestoreHandler;\n\t\"content:afterSchedule\"?: HookConfig<ContentAfterScheduleHandler> | ContentAfterScheduleHandler;\n\t\"content:afterUnschedule\"?:\n\t\t| HookConfig<ContentAfterUnscheduleHandler>\n\t\t| ContentAfterUnscheduleHandler;\n\n\t// Media hooks\n\t\"media:beforeUpload\"?: HookConfig<MediaBeforeUploadHandler> | MediaBeforeUploadHandler;\n\t\"media:afterUpload\"?: HookConfig<MediaAfterUploadHandler> | MediaAfterUploadHandler;\n\n\t// Cron hook\n\tcron?: HookConfig<CronHandler> | CronHandler;\n\n\t// Email hooks\n\t\"email:beforeSend\"?: HookConfig<EmailBeforeSendHandler> | EmailBeforeSendHandler;\n\t\"email:deliver\"?: HookConfig<EmailDeliverHandler> | EmailDeliverHandler;\n\t\"email:afterSend\"?: HookConfig<EmailAfterSendHandler> | EmailAfterSendHandler;\n\n\t// Comment hooks\n\t\"comment:beforeCreate\"?: HookConfig<CommentBeforeCreateHandler> | CommentBeforeCreateHandler;\n\t\"comment:moderate\"?: HookConfig<CommentModerateHandler> | CommentModerateHandler;\n\t\"comment:afterCreate\"?: HookConfig<CommentAfterCreateHandler> | CommentAfterCreateHandler;\n\t\"comment:afterModerate\"?: HookConfig<CommentAfterModerateHandler> | CommentAfterModerateHandler;\n\t\"byline:afterSave\"?: HookConfig<BylineAfterSaveHandler> | BylineAfterSaveHandler;\n\t\"byline:afterDelete\"?: HookConfig<BylineAfterDeleteHandler> | BylineAfterDeleteHandler;\n\n\t// Public page hooks\n\t\"page:metadata\"?: HookConfig<PageMetadataHandler> | PageMetadataHandler;\n\t\"page:fragments\"?: HookConfig<PageFragmentHandler> | PageFragmentHandler;\n}\n\n/**\n * Hook names\n */\n/**\n * Hook name in a manifest. Core's exhaustive union of recognised hook names,\n * derived from the `PluginHooks` registry. The serialised manifest carries\n * these as opaque strings; this stricter type is only used for type-checking\n * inside core. `ManifestHookEntry` is re-exported from\n * `@emdash-cms/plugin-types` near the top of this file.\n */\nexport type HookName = keyof PluginHooks;\n\n/**\n * Resolved hook with normalized config\n */\nexport interface ResolvedHook<THandler> {\n\tpriority: number;\n\ttimeout: number;\n\tdependencies: string[];\n\terrorPolicy: \"continue\" | \"abort\";\n\t/** Whether this hook is exclusive (provider pattern) */\n\texclusive: boolean;\n\thandler: THandler;\n\tpluginId: string;\n}\n\n// =============================================================================\n// Request Metadata Types\n// =============================================================================\n\n/**\n * Geographic location information derived from the request.\n * Available when running on Cloudflare Workers (via the `cf` object).\n */\nexport interface GeoInfo {\n\tcountry: string | null;\n\tregion: string | null;\n\tcity: string | null;\n}\n\n/**\n * Normalized request metadata available to plugin route handlers.\n * Extracted from request headers and platform-specific properties.\n */\nexport interface RequestMeta {\n\tip: string | null;\n\tuserAgent: string | null;\n\treferer: string | null;\n\tgeo: GeoInfo | null;\n}\n\n// =============================================================================\n// Route Types\n// =============================================================================\n\n/**\n * Route handler context extends plugin context with request-specific data\n */\nexport interface RouteContext<TInput = unknown> extends PluginContext {\n\t/** Validated input from request body */\n\tinput: TInput;\n\t/** Original request */\n\trequest: Request;\n\t/** Normalized request metadata (IP, user agent, geo) */\n\trequestMeta: RequestMeta;\n\t/** Host-attested context for a validated Block Kit request. */\n\tui?: PluginUiContext;\n\t/**\n\t * Authenticated caller, if the route is private. The host has already\n\t * authenticated and authorized this user before dispatch, so the value\n\t * is trustworthy — unlike a user id read from the request body.\n\t *\n\t * `undefined` for public routes (which skip auth entirely) and for\n\t * token-authed requests where no user is bound to the token.\n\t *\n\t * Not gated by the `users:read` capability: this is the caller's own\n\t * identity for the current request, not a user directory lookup.\n\t */\n\tuser?: UserInfo;\n}\n\n/**\n * Route definition\n */\nexport interface PluginRoute<TInput = unknown> extends Omit<RouteOptions, \"request\"> {\n\t/** Zod schema for input validation */\n\tinput?: z.ZodType<TInput>;\n\t/**\n\t * Mark this route as publicly accessible (no authentication required).\n\t * Public routes skip session/token auth and CSRF checks.\n\t */\n\tpublic?: boolean;\n\t/** RBAC permission required to invoke the route. Legacy routes default to plugins:manage. */\n\tpermission?: Permission;\n\t/**\n\t * `Cache-Control` header value for successful GET responses, e.g.\n\t * `\"public, max-age=60, stale-while-revalidate=300\"`. Only honored on\n\t * routes that are also `public: true` — authenticated responses always\n\t * keep the default `private, no-store`. Errors are never cached.\n\t */\n\tcacheControl?: string;\n\t/** Bounded request parsing and incoming-header declaration. */\n\trequest?: PluginRouteRequest;\n\t/** Route handler */\n\thandler: { bivarianceHack(ctx: RouteContext<TInput>): Promise<unknown> }[\"bivarianceHack\"];\n}\n\nexport type PluginRouteInput<TMode extends PluginRouteBodyMode> = TMode extends \"none\"\n\t? PluginRouteQuery\n\t: TMode extends \"text\"\n\t\t? string\n\t\t: TMode extends \"bytes\"\n\t\t\t? Uint8Array\n\t\t\t: TMode extends \"form-data\"\n\t\t\t\t? PluginFormData\n\t\t\t\t: unknown;\n\nexport type PluginRouteDefinition<TMode extends PluginRouteBodyMode = PluginRouteBodyMode> = Omit<\n\tPluginRoute<PluginRouteInput<TMode>>,\n\t\"request\"\n> & {\n\trequest: PluginRouteRequest & { body: TMode };\n};\n\nexport interface PluginMcpToolDefinition {\n\tdescription: string;\n\troute: string;\n\tinput: z.ZodType;\n\toutput?: z.ZodType;\n\tdestructive?: boolean;\n}\n\nexport interface PluginMcpConfig {\n\ttools: Record<string, PluginMcpToolDefinition>;\n}\n\n// =============================================================================\n// Plugin Definition\n// =============================================================================\n\n/**\n * Admin page definition\n */\nexport interface PluginAdminPage {\n\tpath: string;\n\tlabel: string;\n\ticon?: string;\n}\n\n/**\n * Dashboard widget definition\n */\nexport interface PluginDashboardWidget {\n\tid: string;\n\tsize?: \"full\" | \"half\" | \"third\";\n\ttitle?: string;\n}\n\nexport interface PluginEditorPanel {\n\tid: string;\n\ttitle: string;\n\troute: string;\n\tcollections?: string[];\n\torder?: number;\n\tdraft?: PluginEditorDraftAccess;\n}\n\nexport interface PluginEditorAction {\n\tid: string;\n\tlabel: string;\n\troute: string;\n\tplacement: \"toolbar\" | \"overflow\";\n\tcollections?: string[];\n\tstyle?: \"default\" | \"danger\";\n\tconfirm?: ConfirmDialog;\n\tdraft?: PluginEditorDraftAccess;\n}\n\n/**\n * Settings field types (for admin UI generation)\n */\nexport type SettingFieldType =\n\t| \"string\"\n\t| \"number\"\n\t| \"boolean\"\n\t| \"select\"\n\t| \"secret\"\n\t| \"url\"\n\t| \"email\";\n\nexport interface BaseSettingField {\n\ttype: SettingFieldType;\n\tlabel: string;\n\tdescription?: string;\n}\n\nexport interface StringSettingField extends BaseSettingField {\n\ttype: \"string\";\n\tdefault?: string;\n\tmultiline?: boolean;\n}\n\nexport interface NumberSettingField extends BaseSettingField {\n\ttype: \"number\";\n\tdefault?: number;\n\tmin?: number;\n\tmax?: number;\n}\n\nexport interface BooleanSettingField extends BaseSettingField {\n\ttype: \"boolean\";\n\tdefault?: boolean;\n}\n\nexport interface SelectSettingField extends BaseSettingField {\n\ttype: \"select\";\n\toptions: Array<{ value: string; label: string }>;\n\tdefault?: string;\n}\n\nexport interface SecretSettingField extends BaseSettingField {\n\ttype: \"secret\";\n}\n\nexport interface UrlSettingField extends BaseSettingField {\n\ttype: \"url\";\n\tdefault?: string;\n\tplaceholder?: string;\n}\n\nexport interface EmailSettingField extends BaseSettingField {\n\ttype: \"email\";\n\tdefault?: string;\n\tplaceholder?: string;\n}\n\nexport type SettingField =\n\t| StringSettingField\n\t| NumberSettingField\n\t| BooleanSettingField\n\t| SelectSettingField\n\t| SecretSettingField\n\t| UrlSettingField\n\t| EmailSettingField;\n\n/**\n * Block Kit element for block editing fields.\n * This is the `Element` discriminated union from `@emdash-cms/blocks`.\n * Plugin authors should use `@emdash-cms/blocks` builder functions to create these.\n */\nexport type PortableTextBlockField = Element;\n\n/**\n * Configuration for a Portable Text block type contributed by a plugin\n */\nexport interface PortableTextBlockConfig {\n\t/** Block type name (must match the `_type` in Portable Text) */\n\ttype: string;\n\t/** Human-readable label shown in slash commands and modals */\n\tlabel: string;\n\t/** Icon key (e.g., \"video\", \"code\", \"link\", \"link-external\") */\n\ticon?: string;\n\t/** Description shown in slash command menu */\n\tdescription?: string;\n\t/** Placeholder text for the URL input */\n\tplaceholder?: string;\n\t/** Block Kit form fields for the editing UI. If declared, replaces the simple URL input. */\n\tfields?: PortableTextBlockField[];\n\t/**\n\t * Optional. Display category in the slash menu. Defaults to \"Embeds\".\n\t *\n\t * Plugin authors should pick a meaningful category that reflects what the\n\t * block actually is — e.g. \"Sections\", \"Marketing\", \"Media\", \"Embeds\",\n\t * \"Layout\". Blocks with the same category are grouped together in the\n\t * editor's slash menu.\n\t */\n\tcategory?: string;\n}\n\n/**\n * Configuration for a field widget type contributed by a plugin.\n * A field widget provides a custom editing UI for a schema field.\n * The field references the widget via `widget: \"pluginId:widgetName\"`.\n */\nexport interface FieldWidgetConfig {\n\t/** Widget name (without plugin ID prefix) */\n\tname: string;\n\t/** Human-readable label for the admin UI */\n\tlabel: string;\n\t/** Which field types this widget can edit (e.g., [\"json\", \"string\"]) */\n\tfieldTypes: FieldType[];\n\t/** Block Kit elements for sandboxed rendering. Omit for trusted plugins using React. */\n\telements?: Element[];\n}\n\n/**\n * Admin configuration\n */\nexport interface PluginAdminConfig {\n\t/** Module specifier for admin UI exports (e.g., \"@emdash-cms/plugin-audit-log/admin\") */\n\tentry?: string;\n\t/** Settings schema for auto-generated UI */\n\tsettingsSchema?: Record<string, SettingField>;\n\t/** Admin pages */\n\tpages?: PluginAdminPage[];\n\t/** Dashboard widgets */\n\twidgets?: PluginDashboardWidget[];\n\t/** Saved-entry Block Kit panels. */\n\teditorPanels?: PluginEditorPanel[];\n\t/** Saved-entry host-rendered actions. */\n\teditorActions?: PluginEditorAction[];\n\t/** Portable Text block types this plugin provides */\n\tportableTextBlocks?: PortableTextBlockConfig[];\n\t/** Field widget types this plugin provides */\n\tfieldWidgets?: FieldWidgetConfig[];\n}\n\n/**\n * Plugin definition - input to definePlugin()\n */\nexport interface PluginDefinition<TStorage extends PluginStorageConfig = PluginStorageConfig> {\n\t/** Unique plugin identifier */\n\tid: string;\n\t/** Plugin version (semver) */\n\tversion: string;\n\n\t/** Declared capabilities */\n\tcapabilities?: PluginCapability[];\n\n\t/** Allowed hosts for network:request (wildcards supported: *.example.com) */\n\tallowedHosts?: string[];\n\n\t/** Storage collections with indexes */\n\tstorage?: TStorage;\n\n\t/** Hooks */\n\thooks?: PluginHooks;\n\n\t/** API routes */\n\troutes?: Record<string, PluginRoute>;\n\n\t/** Routes explicitly exposed as agent-callable MCP tools. */\n\tmcp?: PluginMcpConfig;\n\n\t/** Admin UI configuration */\n\tadmin?: PluginAdminConfig;\n}\n\n/**\n * Resolved plugin - after definePlugin() processing\n */\nexport interface ResolvedPlugin<TStorage extends PluginStorageConfig = PluginStorageConfig> {\n\tid: string;\n\tversion: string;\n\tcapabilities: PluginCapability[];\n\tallowedHosts: string[];\n\tstorage: TStorage;\n\thooks: ResolvedPluginHooks;\n\troutes: Record<string, PluginRoute>;\n\tmcp?: PluginMcpConfig;\n\tadmin: PluginAdminConfig;\n}\n\n/**\n * Resolved hooks with normalized config\n */\nexport interface ResolvedPluginHooks {\n\t\"plugin:install\"?: ResolvedHook<LifecycleHandler>;\n\t\"plugin:activate\"?: ResolvedHook<LifecycleHandler>;\n\t\"plugin:deactivate\"?: ResolvedHook<LifecycleHandler>;\n\t\"plugin:uninstall\"?: ResolvedHook<UninstallHandler>;\n\t\"content:beforeSave\"?: ResolvedHook<ContentBeforeSaveHandler>;\n\t\"content:afterSave\"?: ResolvedHook<ContentAfterSaveHandler>;\n\t\"content:beforeDelete\"?: ResolvedHook<ContentBeforeDeleteHandler>;\n\t\"content:afterDelete\"?: ResolvedHook<ContentAfterDeleteHandler>;\n\t\"content:beforePublish\"?: ResolvedHook<ContentBeforePublishHandler>;\n\t\"content:beforeSchedule\"?: ResolvedHook<ContentBeforeScheduleHandler>;\n\t\"content:beforeUnpublish\"?: ResolvedHook<ContentBeforeUnpublishHandler>;\n\t\"content:afterPublish\"?: ResolvedHook<ContentAfterPublishHandler>;\n\t\"content:afterUnpublish\"?: ResolvedHook<ContentAfterUnpublishHandler>;\n\t\"content:afterRestore\"?: ResolvedHook<ContentAfterRestoreHandler>;\n\t\"content:afterSchedule\"?: ResolvedHook<ContentAfterScheduleHandler>;\n\t\"content:afterUnschedule\"?: ResolvedHook<ContentAfterUnscheduleHandler>;\n\t\"media:beforeUpload\"?: ResolvedHook<MediaBeforeUploadHandler>;\n\t\"media:afterUpload\"?: ResolvedHook<MediaAfterUploadHandler>;\n\tcron?: ResolvedHook<CronHandler>;\n\t\"email:beforeSend\"?: ResolvedHook<EmailBeforeSendHandler>;\n\t\"email:deliver\"?: ResolvedHook<EmailDeliverHandler>;\n\t\"email:afterSend\"?: ResolvedHook<EmailAfterSendHandler>;\n\t\"comment:beforeCreate\"?: ResolvedHook<CommentBeforeCreateHandler>;\n\t\"comment:moderate\"?: ResolvedHook<CommentModerateHandler>;\n\t\"comment:afterCreate\"?: ResolvedHook<CommentAfterCreateHandler>;\n\t\"comment:afterModerate\"?: ResolvedHook<CommentAfterModerateHandler>;\n\t\"byline:afterSave\"?: ResolvedHook<BylineAfterSaveHandler>;\n\t\"byline:afterDelete\"?: ResolvedHook<BylineAfterDeleteHandler>;\n\t\"page:metadata\"?: ResolvedHook<PageMetadataHandler>;\n\t\"page:fragments\"?: ResolvedHook<PageFragmentHandler>;\n}\n\n// =============================================================================\n// Plugin Admin Exports\n// =============================================================================\n\n/**\n * What a plugin exports from its /admin entrypoint\n * Uses generic component type to avoid React dependency\n */\nexport interface PluginAdminExports {\n\twidgets?: Record<string, JSX.Element>;\n\tpages?: Record<string, JSX.Element>;\n\tfields?: Record<string, JSX.Element>;\n}\n\n// =============================================================================\n// Sandbox Types\n// =============================================================================\n\n/**\n * Plugin manifest — the metadata portion of a plugin bundle, used for\n * sandboxed plugins loaded from the marketplace.\n *\n * This interface is core's stricter version of the manifest contract: it\n * uses the exhaustive `HookName` union and core's typed `PluginAdminConfig`.\n * The wire-shape lives in `@emdash-cms/plugin-types` as `PluginManifest`\n * with looser types (so the registry CLI can serialise hook names it\n * doesn't know about). Both must stay structurally compatible: every value\n * of this type must be assignable to the shared one. The static assertion\n * below catches any drift at compile time.\n */\nexport interface PluginManifest {\n\tid: string;\n\tversion: string;\n\t/**\n\t * The trust contract (see `@emdash-cms/plugin-types`). Authoritative;\n\t * `capabilities`/`allowedHosts` are derived from it at the parse boundary\n\t * via `reconcileManifestAccess`. Optional during the wire-format migration.\n\t */\n\tdeclaredAccess?: DeclaredAccess;\n\tcapabilities: PluginCapability[];\n\tallowedHosts: string[];\n\tstorage: PluginStorageConfig;\n\t/** Hook declarations — either plain name strings or structured objects */\n\thooks: Array<ManifestHookEntry | HookName>;\n\t/** Route declarations — either plain name strings or structured objects */\n\troutes: Array<ManifestRouteEntry | string>;\n\tmcp?: PluginMcpManifestConfig;\n\tadmin: PluginAdminConfig;\n}\n\n// Type-level guard: core's `PluginManifest` is intentionally a SUBTYPE of\n// the shared wire shape (`@emdash-cms/plugin-types` `PluginManifest`). The\n// wire shape uses looser types like `string` for hook names so the registry\n// CLI can serialise plugins targeting hook versions this core doesn't yet\n// know about. Core narrows `string` to `HookName` and `Record<string,\n// unknown>` to `PluginAdminConfig` because core's loader actually executes\n// against those types.\n//\n// We assert one direction at compile time: `core extends shared`. The\n// reverse direction (`shared extends core`) intentionally does NOT hold\n// because shared is wider -- a manifest written against the wire shape\n// could carry a hook name core doesn't know. That runtime narrowing is the\n// job of `manifest-schema.ts` (zod-validated, called at every JSON.parse\n// of a manifest.json), not of the type system. The static check below\n// catches the OTHER failure mode: core adding a required field or\n// non-assignable type that the wire shape doesn't allow.\n//\n// `type X = never` is itself legal as a type alias, so the assertion has to\n// be in a value position (`const _check: T = true`) for the compiler to\n// error when T resolves to `never`. Don't replace this with a bare type\n// alias.\ntype _AssertManifestCompat =\n\tPluginManifest extends import(\"@emdash-cms/plugin-types\").PluginManifest ? true : never;\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nconst _MANIFEST_COMPAT: _AssertManifestCompat = true;\n"],"mappings":";;;AAmFA,MAAa,iCAET;CACH,CAAC,iBAAiB,eAAe;CACjC,CAAC,0BAA0B,eAAe;CAC1C,CAAC,oBAAoB,kBAAkB;CACvC,CAAC,mBAAmB,eAAe;CACnC,CAAC,eAAe,aAAa;CAC7B,CAAC,qBAAqB,gBAAgB;CACtC,CAAC,mBAAmB,iBAAiB;CACrC,CAAC,gCAAgC,kBAAkB;CACnD;AAMD,SAAgB,4BAA4B,cAA2C;CACtF,MAAM,aAAa,IAAI,IAAI,sBAAsB,aAAa,CAAC;AAC/D,MAAK,MAAM,CAAC,SAAS,YAAY,+BAChC,KAAI,WAAW,IAAI,QAAQ,CAAE,YAAW,IAAI,QAAQ;AAErD,QAAO,CAAC,GAAG,WAAW;;AAGvB,MAAM,uCAAuC,OAAO,IACnD,8CACA;;;;;AAMD,SAAgB,iCACf,UACA,cACO;CACP,MAAM,aAAa,aAAa,OAAO,uBAAuB;AAC9D,KAAI,WAAW,WAAW,EAAG;CAE7B,MAAM,IAAI;CAEV,MAAM,SAAU,EAAE,0DAA0C,IAAI,KAAa;AAC7E,KAAI,OAAO,IAAI,SAAS,CAAE;AAC1B,QAAO,IAAI,SAAS;CAEpB,MAAM,UAAU,WAAW,KAAK,QAAQ,GAAG,IAAI,KAAK,mBAAmB,OAAO,CAAC,KAAK,KAAK;AACzF,SAAQ,KACP,oBAAoB,SAAS,0CAA0C,QAAQ,mKAG/E"}

package/dist/types-D994zUWB.d.mts

@@ -1,85 +0,0 @@
-//#region src/settings/types.d.ts
-/**
- * Site Settings Types
- *
- * Global configuration for the site (title, logo, social links, etc.)
- */
-/**
- * Media reference for logo/favicon/seo.defaultOgImage.
- *
- * Stored shape is just `{ mediaId, alt? }`. The remaining fields are
- * populated by `resolveMediaReference` on read so templates can emit
- * correct head tags without a second round-trip to the media table.
- *
- * The Zod schemas at the REST/MCP boundary are split:
- *  - `mediaReferenceInput` (used by `settingsUpdateBody`) defines only
- *    `mediaId` and `alt`. Default strip-mode parsing discards any
- *    resolved fields a client posts back, so they never reach storage.
- *  - `mediaReferenceResponse` (used by `siteSettingsSchema`) includes
- *    the resolved fields so generated OpenAPI clients see them.
- *
- * If you ever switch `mediaReferenceInput` to `passthrough`, you must
- * also strip the resolved fields explicitly in `setSiteSettings`, or
- * stored options will accumulate stale `url` / `contentType` / `width`
- * / `height` snapshots.
- */
-interface MediaReference {
-  mediaId: string;
-  alt?: string;
-  /** Resolved URL. Populated by `resolveMediaReference`; absent on raw stored values. */
-  url?: string;
-  /** Stored MIME type (e.g. `image/svg+xml`). Populated alongside `url`. */
-  contentType?: string;
-  /** Pixel width if known. Populated alongside `url`. */
-  width?: number;
-  /** Pixel height if known. Populated alongside `url`. */
-  height?: number;
-}
-/** Site-level SEO settings */
-interface SeoSettings {
-  /** Separator between page title and site title (e.g., " | ", " — ") */
-  titleSeparator?: string;
-  /** Default OG image when content has no seo_image */
-  defaultOgImage?: MediaReference;
-  /** Custom robots.txt content. If unset, a default is generated. */
-  robotsTxt?: string;
-  /** Google Search Console verification meta tag content */
-  googleVerification?: string;
-  /** Bing Webmaster Tools verification meta tag content */
-  bingVerification?: string;
-}
-/** Site settings schema */
-interface SiteSettings {
-  title: string;
-  tagline?: string;
-  logo?: MediaReference;
-  favicon?: MediaReference;
-  url?: string;
-  postsPerPage: number;
-  dateFormat: string;
-  timezone: string;
-  social?: {
-    twitter?: string;
-    github?: string;
-    facebook?: string;
-    instagram?: string;
-    linkedin?: string;
-    youtube?: string;
-  };
-  seo?: SeoSettings;
-}
-/** Partial SEO update. `null` removes the configured default image. */
-interface SeoSettingsUpdate extends Omit<SeoSettings, "defaultOgImage"> {
-  defaultOgImage?: MediaReference | null;
-}
-/** Site-settings write shape. `null` removes media references; omitted fields are unchanged. */
-interface SiteSettingsUpdate extends Omit<Partial<SiteSettings>, "logo" | "favicon" | "seo"> {
-  logo?: MediaReference | null;
-  favicon?: MediaReference | null;
-  seo?: SeoSettingsUpdate;
-}
-/** Keys that are valid site settings */
-type SiteSettingKey = keyof SiteSettings;
-//#endregion
-export { SiteSettings as a, SiteSettingKey as i, SeoSettings as n, SiteSettingsUpdate as o, SeoSettingsUpdate as r, MediaReference as t };
-//# sourceMappingURL=types-D994zUWB.d.mts.map

package/dist/types-D994zUWB.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types-D994zUWB.d.mts","names":[],"sources":["../src/settings/types.ts"],"mappings":";;AAyBA;;;;;;;;;;;;AAcA;;;;;;;;;;;UAdiB,cAAA;EAChB,OAAA;EACA,GAAA;;EAEA,GAAA;EA6BU;EA3BV,WAAA;EAgDiB;EA9CjB,KAAA;EAsBA;EApBA,MAAA;AAAA;;UAIgB,WAAA;EAmBN;EAjBV,cAAA;EAuBA;EArBA,cAAA,GAAiB,cAAA;EAuBjB;EArBA,SAAA;EAyBC;EAvBD,kBAAA;EAyBC;EAvBD,gBAAA;AAAA;;UAIgB,YAAA;EAEhB,KAAA;EACA,OAAA;EACA,IAAA,GAAO,cAAA;EACP,OAAA,GAAU,cAAA;EAGV,GAAA;EAGA,YAAA;EACA,UAAA;EACA,QAAA;EAGA,MAAA;IACC,OAAA;IACA,MAAA;IACA,QAAA;IACA,SAAA;IACA,QAAA;IACA,OAAA;EAAA;EAID,GAAA,GAAM,WAAA;AAAA;;UAIU,iBAAA,SAA0B,IAAA,CAAK,WAAA;EAC/C,cAAA,GAAiB,cAAA;AAAA;;UAID,kBAAA,SAA2B,IAAA,CAC3C,OAAA,CAAQ,YAAA;EAGR,IAAA,GAAO,cAAA;EACP,OAAA,GAAU,cAAA;EACV,GAAA,GAAM,iBAAA;AAAA;;KAIK,cAAA,SAAuB,YAAA"}

package/dist/types-DAj1ByJQ.d.mts

@@ -1,125 +0,0 @@
-//#region src/object-cache/types.d.ts
-/**
- * Object cache types
- *
- * The object cache is an optional, distributed read-through cache that sits
- * *beneath* the per-request cache (`requestCached`) and *above* the database.
- * Query results (content entries, settings, menus, taxonomies) are stored in a
- * fast key/value store (Cloudflare KV, or an in-isolate memory store for Node)
- * so repeat reads across requests and isolates skip the database entirely.
- *
- * Backends only ever deal in strings — serialization (including `Date`
- * preservation) is handled by the core read-through layer in `./codec.ts`, so
- * every backend behaves identically.
- */
-/**
- * A pluggable object-cache backend.
- *
- * Implementations must be safe to call concurrently and should never throw on
- * cache misses — `get` returns `null` for a miss. A backend that throws (e.g.
- * a transient KV error) degrades gracefully: the read-through layer treats a
- * thrown `get` as a miss and a thrown `set` as a no-op, so the database
- * remains the source of truth.
- */
-interface ObjectCacheBackend {
-  /** Return the stored string for `key`, or `null` on a miss. */
-  get(key: string): Promise<string | null>;
-  /**
-   * Store `value` under `key`.
-   *
-   * @param ttlSeconds Optional time-to-live in seconds. Backends that don't
-   *   support TTLs may ignore it, but distributed backends (KV) should honor
-   *   it so orphaned, epoch-busted keys are eventually reclaimed.
-   */
-  set(key: string, value: string, ttlSeconds?: number): Promise<void>;
-  /** Remove `key`. Idempotent — deleting a missing key is not an error. */
-  delete(key: string): Promise<void>;
-}
-/**
- * Serializable descriptor for an object-cache backend.
- *
- * Mirrors {@link import("../storage/types.js").StorageDescriptor}: `entrypoint`
- * is a module specifier resolved at build time that exports a
- * {@link CreateObjectCacheBackendFn} named `createObjectCache`; `config` is the
- * plain, serializable runtime config passed to it.
- */
-interface ObjectCacheDescriptor {
-  /** Module path exporting a `createObjectCache` function. */
-  entrypoint: string;
-  /** Serializable config passed to `createObjectCache` at runtime. */
-  config: ObjectCacheRuntimeConfig;
-}
-/**
- * Runtime config shared by every backend, plus backend-specific keys.
- *
- * The read-through layer reads `defaultTtl`, `revalidate`, and `keyPrefix`;
- * individual backends read their own keys (e.g. the KV backend reads
- * `binding`).
- */
-interface ObjectCacheRuntimeConfig {
-  /**
-   * Default time-to-live for cached entries, in seconds.
-   *
-   * Invalidation works by epoch comparison, not key deletion: a stale value
-   * is detected on read (its stored epoch no longer matches) and overwritten
-   * in place under the same key. The TTL is just a backstop that reclaims
-   * keys that are never read again.
-   *
-   * @default 3600 (1 hour)
-   */
-  defaultTtl?: number;
-  /**
-   * How long (milliseconds) an isolate may reuse a cached namespace epoch
-   * before re-reading it from the backend.
-   *
-   * After a write bumps a namespace's epoch, an isolate keeps serving the
-   * previous epoch's keys until its cached epoch expires after this window. It
-   * is only part of the cross-isolate staleness: a distributed backend adds its
-   * own propagation delay (KV's edge cache is eventually consistent, up to
-   * ~60s), so on KV the effective window is that propagation plus this value.
-   * Preview and edit requests bypass the cache. Renders that may fill Astro's
-   * route cache also bypass it, preventing an older KV snapshot from being
-   * stored as a fresh HTML response after a purge.
-   *
-   * Set to `0` to re-read the epoch on every query (strongest freshness, more
-   * backend reads).
-   *
-   * @default 1000
-   */
-  revalidate?: number;
-  /**
-   * Prefix applied to every cache key. Lets multiple EmDash sites share one
-   * KV namespace without colliding.
-   *
-   * @default "em"
-   */
-  keyPrefix?: string;
-  /**
-   * Maximum time (milliseconds) to wait for a single backend read before
-   * treating it as a cache miss and falling back to the database.
-   *
-   * Guards against a backend operation that stalls without resolving or
-   * rejecting (e.g. a cold cross-region KV read, or one queued behind the
-   * Workers simultaneous-connection limit), which would otherwise hang the
-   * request. A timed-out read degrades to a miss; the database remains the
-   * source of truth.
-   *
-   * Set to `0` to disable the timeout (not recommended on Cloudflare).
-   *
-   * @default 2000
-   */
-  timeout?: number;
-  /** Backend-specific keys (e.g. the KV binding name). */
-  [key: string]: unknown;
-}
-/**
- * Factory signature exported as `createObjectCache` from a backend entrypoint.
- *
- * Each backend accesses its own resources directly: the KV backend imports
- * bindings from `cloudflare:workers`; the memory backend uses an in-isolate
- * map.
- */
-type CreateObjectCacheBackendFn = (config: ObjectCacheRuntimeConfig) => ObjectCacheBackend;
-//#endregion
-export { ObjectCacheRuntimeConfig as i, ObjectCacheBackend as n, ObjectCacheDescriptor as r, CreateObjectCacheBackendFn as t };
-//# sourceMappingURL=types-DAj1ByJQ.d.mts.map

package/dist/types-DAj1ByJQ.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types-DAj1ByJQ.d.mts","names":[],"sources":["../src/object-cache/types.ts"],"mappings":";;AAuBA;;;;;;;;;;;;;;;;;;;;;UAAiB,kBAAA;EAuBqB;EArBrC,GAAA,CAAI,GAAA,WAAc,OAAA;EAyBc;;;;;;AAUjC;EA3BC,GAAA,CAAI,GAAA,UAAa,KAAA,UAAe,UAAA,YAAsB,OAAA;;EAEtD,MAAA,CAAO,GAAA,WAAc,OAAA;AAAA;;;;;;;AAyFtB;;UA9EiB,qBAAA;EA8EgF;EA5EhG,UAAA;EA4EyC;EA1EzC,MAAA,EAAQ,wBAAA;AAAA;;;;;;;;UAUQ,wBAAA;;;;;;;;;;;EAWhB,UAAA;;;;;;;;;;;;;;;;;;;EAmBA,UAAA;;;;;;;EAOA,SAAA;;;;;;;;;;;;;;;EAeA,OAAA;;GAEC,GAAA;AAAA;;;;;;;;KAUU,0BAAA,IAA8B,MAAA,EAAQ,wBAAA,KAA6B,kBAAA"}

package/dist/types-Dlv6esp4.mjs

@@ -1,77 +0,0 @@
-//#region src/plugins/sandbox/types.ts
-const SANDBOX_ROUTE_ERROR_DEFINITIONS = {
-	MEDIA_USAGE_ACTIVATION_IN_PROGRESS: {
-		message: "Media usage activation is in progress",
-		status: 503
-	},
-	MEDIA_USAGE_ACTIVATION_CHECK_FAILED: {
-		message: "Unable to verify media usage activation state",
-		status: 503
-	},
-	TRANSFER_IMPORT_IN_PROGRESS: {
-		message: "A site import is in progress or incomplete; writes are disabled",
-		status: 503
-	},
-	TRANSFER_FENCE_CHECK_FAILED: {
-		message: "Unable to verify whether site writes are allowed",
-		status: 503
-	}
-};
-function isRecord(value) {
-	return typeof value === "object" && value !== null;
-}
-function isSandboxRouteErrorCode(value) {
-	return typeof value === "string" && value in SANDBOX_ROUTE_ERROR_DEFINITIONS;
-}
-function getSandboxRouteErrorDetails(error) {
-	if (!isRecord(error)) return null;
-	const propertyCode = isSandboxRouteErrorCode(error.code) ? error.code : null;
-	const nameCode = error instanceof Error && isSandboxRouteErrorCode(error.name) ? error.name : null;
-	if (propertyCode && nameCode && propertyCode !== nameCode) return null;
-	const code = propertyCode ?? nameCode;
-	if (!code || error.status !== void 0 && error.status !== 503) return null;
-	return {
-		code,
-		...SANDBOX_ROUTE_ERROR_DEFINITIONS[code]
-	};
-}
-function createSandboxRouteError(code) {
-	const details = {
-		code,
-		...SANDBOX_ROUTE_ERROR_DEFINITIONS[code]
-	};
-	return Object.assign(new Error(details.message), details, { name: code });
-}
-function createSandboxRouteErrorEnvelope(error) {
-	const details = getSandboxRouteErrorDetails(error);
-	return details ? {
-		__emdashSandboxRouteError: true,
-		error: details
-	} : null;
-}
-function getSandboxRouteErrorEnvelope(value) {
-	if (!isRecord(value) || value.__emdashSandboxRouteError !== true) return null;
-	const details = getSandboxRouteErrorDetails(value.error);
-	return details ? {
-		__emdashSandboxRouteError: true,
-		error: details
-	} : null;
-}
-function withUnavailableReason(message, runner) {
-	const reason = runner?.unavailableReason?.();
-	return reason ? `${message}: ${reason}` : message;
-}
-/**
-* Error thrown when the sandbox runtime is unavailable.
-* This happens when the sidecar process has crashed or hasn't started.
-*/
-var SandboxUnavailableError = class extends Error {
-	constructor(pluginId, reason) {
-		super(`Plugin sandbox unavailable for ${pluginId}: ${reason}`);
-		this.name = "SandboxUnavailableError";
-	}
-};
-
-//#endregion
-export { getSandboxRouteErrorEnvelope as a, getSandboxRouteErrorDetails as i, createSandboxRouteError as n, withUnavailableReason as o, createSandboxRouteErrorEnvelope as r, SandboxUnavailableError as t };
-//# sourceMappingURL=types-Dlv6esp4.mjs.map

package/dist/types-Dlv6esp4.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"types-Dlv6esp4.mjs","names":[],"sources":["../src/plugins/sandbox/types.ts"],"sourcesContent":["/**\n * Plugin Sandbox Types\n *\n * Defines interfaces for running plugins in sandboxed V8 isolates.\n * The SandboxRunner interface is implemented by platform adapters\n * (e.g., Cloudflare Worker Loader) to provide isolation.\n *\n */\n\nimport type { PluginUiContext } from \"@emdash-cms/blocks/server\";\nimport type { Kysely } from \"kysely\";\n\nimport type { Database } from \"../../database/types.js\";\nimport type { ContentActionCallbacks } from \"../context.js\";\nimport type {\n\tContentCreateOptions,\n\tContentItem,\n\tContentWriteInput,\n\tPluginComment,\n\tPluginCommentStatus,\n\tPluginManifest,\n\tRequestMeta,\n\tTaxonomyAccessWithWrite,\n\tUserInfo,\n} from \"../types.js\";\n\n/**\n * Resource limits for sandboxed plugins.\n * Enforced by the sandbox runtime (e.g., Worker Loader).\n */\nexport interface ResourceLimits {\n\t/** CPU time per invocation in milliseconds (default: 50ms) */\n\tcpuMs?: number;\n\t/** Memory limit in MB (default: 128MB) */\n\tmemoryMb?: number;\n\t/** Maximum subrequests per invocation (default: 10) */\n\tsubrequests?: number;\n\t/** Wall-clock time limit in milliseconds (default: 30000ms) */\n\twallTimeMs?: number;\n}\n\n/**\n * Storage interface for loading plugin code.\n * Could be R2, local filesystem, or any other storage backend.\n */\nexport interface PluginCodeStorage {\n\t/** Get plugin bundle code by path */\n\tget(path: string): Promise<string | null>;\n\t/** Check if a bundle exists */\n\texists(path: string): Promise<boolean>;\n}\n\n/**\n * Serialized email message for sandbox RPC transport.\n * Matches the core EmailMessage type but uses only serializable fields.\n */\nexport interface SandboxEmailMessage {\n\tto: string;\n\tcc?: string[];\n\treplyTo?: string;\n\tsubject: string;\n\ttext: string;\n\thtml?: string;\n}\n\n/**\n * Callback for sending email from a sandboxed plugin.\n * The sandbox runner wires this up from the EmailPipeline.\n *\n * @param message - The email message to send\n * @param pluginId - The sending plugin's ID (used as source)\n */\nexport type SandboxEmailSendCallback = (\n\tmessage: SandboxEmailMessage,\n\tpluginId: string,\n) => Promise<void>;\n\nexport type SandboxCommentModerateCallback = (\n\tpluginId: string,\n\tid: string,\n\tstatus: PluginCommentStatus,\n\texpectedStatus: PluginCommentStatus,\n) => Promise<PluginComment>;\n\nexport type SandboxContentCreateCallback = (\n\tpluginId: string,\n\tcollection: string,\n\tdata: ContentWriteInput,\n\toptions?: ContentCreateOptions & {\n\t\toriginHook?: \"content:beforeSave\" | \"content:afterSave\";\n\t\tsandboxOrigin?: true;\n\t},\n) => Promise<ContentItem>;\n\nexport type SandboxHttpFetchCallback = typeof fetch;\n\n/**\n * Options for creating a sandbox runner\n */\nexport interface SandboxOptions {\n\t/** Storage interface for loading plugin code */\n\tstorage?: PluginCodeStorage;\n\t/** Database for bridge operations */\n\tdb: Kysely<Database>;\n\t/**\n\t * Called immediately before a sandboxed plugin content mutation; it throws\n\t * to refuse the write. When it returns a function, the bridge calls that\n\t * function once the write has succeeded.\n\t */\n\tbeforeContentWrite?: () => Promise<void | (() => Promise<void>)>;\n\t/** Runtime-owned taxonomy mutation surface used by sandbox bridges. */\n\ttaxonomyWrite?: TaxonomyAccessWithWrite;\n\tcontentActions?: ContentActionCallbacks;\n\t/** Clock used to calculate recurring plugin task schedules. */\n\tnow?: () => Date;\n\t/** Default resource limits */\n\tlimits?: ResourceLimits;\n\t/** Site info for plugin context (injected into wrapper at generation time) */\n\tsiteInfo?: {\n\t\tname: string;\n\t\turl: string;\n\t\tlocale: string;\n\t\ttrailingSlash?: \"always\" | \"never\" | \"ignore\";\n\t};\n\t/** Email send callback, wired from the EmailPipeline by the runtime */\n\temailSend?: SandboxEmailSendCallback;\n\tcommentModerate?: SandboxCommentModerateCallback;\n\t/** Optional host HTTP transport used by test hosts and custom runtimes. */\n\thttpFetch?: SandboxHttpFetchCallback;\n\t/**\n\t * Media storage adapter for sandboxed plugin byte reads, uploads, and deletes.\n\t * Each operation remains gated by its own media capability.\n\t */\n\tmediaStorage?: {\n\t\tupload(options: { key: string; body: Uint8Array; contentType: string }): Promise<unknown>;\n\t\tdownload(key: string): Promise<{\n\t\t\tbody: ReadableStream<Uint8Array>;\n\t\t\tcontentType: string;\n\t\t\tsize: number;\n\t\t}>;\n\t\tdelete(key: string): Promise<unknown>;\n\t};\n\t/** Worker Loader name suffix. The plugin's logical ID remains unchanged. */\n\tisolateKey?: string;\n}\n\n/**\n * Handle to a sandboxed plugin running inside an isolate. Returned\n * by `SandboxRunner.load` and held by the runtime's cache so hooks /\n * routes can be invoked across the isolate boundary. Distinct from\n * the author-facing `SandboxedPlugin` type in `emdash/plugin`, which\n * describes the source-level shape of a plugin's default export.\n */\nexport interface SandboxedPluginInstance {\n\t/** Unique identifier: `${manifest.id}:${manifest.version}` */\n\treadonly id: string;\n\n\t/**\n\t * Invoke a hook in the sandboxed plugin.\n\t *\n\t * @param hookName - Name of the hook (e.g., \"content:beforeSave\")\n\t * @param event - Event data to pass to the hook\n\t * @returns Hook result (transformed content, void, etc.)\n\t */\n\tinvokeHook(hookName: string, event: unknown): Promise<unknown>;\n\n\t/**\n\t * Invoke an API route in the sandboxed plugin.\n\t *\n\t * @param routeName - Name of the route\n\t * @param input - Validated input data\n\t * @param request - Serialized request info for context\n\t * @returns Route response data\n\t */\n\tinvokeRoute(\n\t\trouteName: string,\n\t\tinput: unknown,\n\t\trequest: SerializedRequest,\n\t\toptions?: SandboxInvocationOptions,\n\t): Promise<unknown>;\n\n\t/**\n\t * Change whether the plugin may access host services.\n\t * Deactivation revokes credentials synchronously; reactivation issues fresh credentials.\n\t */\n\tsetActive?(active: boolean): void;\n\n\t/**\n\t * Terminate the sandboxed plugin.\n\t * Releases resources and prevents further invocations.\n\t */\n\tterminate(): Promise<void>;\n}\n\nexport interface SandboxInvocationOptions {\n\tinvalidateContentCache?: (tags: string[]) => Promise<void>;\n}\n\n/**\n * Serialized request for RPC transport.\n * Worker Loader can't pass Request objects directly.\n */\nexport interface SerializedRequest {\n\turl: string;\n\tmethod: string;\n\theaders: Record<string, string>;\n\t/** Normalized request metadata extracted before RPC serialization */\n\tmeta: RequestMeta;\n\t/** Host-attested context for a validated Block Kit request. */\n\tui?: PluginUiContext;\n\t/**\n\t * Authenticated caller for private routes, resolved by the host before\n\t * dispatch. Undefined for public routes and unbound machine tokens.\n\t */\n\tuser?: UserInfo;\n}\n\nconst SANDBOX_ROUTE_ERROR_DEFINITIONS = {\n\tMEDIA_USAGE_ACTIVATION_IN_PROGRESS: {\n\t\tmessage: \"Media usage activation is in progress\",\n\t\tstatus: 503,\n\t},\n\tMEDIA_USAGE_ACTIVATION_CHECK_FAILED: {\n\t\tmessage: \"Unable to verify media usage activation state\",\n\t\tstatus: 503,\n\t},\n\tTRANSFER_IMPORT_IN_PROGRESS: {\n\t\tmessage: \"A site import is in progress or incomplete; writes are disabled\",\n\t\tstatus: 503,\n\t},\n\tTRANSFER_FENCE_CHECK_FAILED: {\n\t\tmessage: \"Unable to verify whether site writes are allowed\",\n\t\tstatus: 503,\n\t},\n} as const;\n\nexport type SandboxRouteErrorCode = keyof typeof SANDBOX_ROUTE_ERROR_DEFINITIONS;\n\nexport interface SandboxRouteErrorDetails {\n\tcode: SandboxRouteErrorCode;\n\tmessage: string;\n\tstatus: 503;\n}\n\nexport interface SandboxRouteErrorEnvelope {\n\t__emdashSandboxRouteError: true;\n\terror: SandboxRouteErrorDetails;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null;\n}\n\nfunction isSandboxRouteErrorCode(value: unknown): value is SandboxRouteErrorCode {\n\treturn typeof value === \"string\" && value in SANDBOX_ROUTE_ERROR_DEFINITIONS;\n}\n\nexport function getSandboxRouteErrorDetails(error: unknown): SandboxRouteErrorDetails | null {\n\tif (!isRecord(error)) return null;\n\n\tconst propertyCode = isSandboxRouteErrorCode(error.code) ? error.code : null;\n\tconst nameCode =\n\t\terror instanceof Error && isSandboxRouteErrorCode(error.name) ? error.name : null;\n\tif (propertyCode && nameCode && propertyCode !== nameCode) return null;\n\n\tconst code = propertyCode ?? nameCode;\n\tif (!code || (error.status !== undefined && error.status !== 503)) return null;\n\n\treturn {\n\t\tcode,\n\t\t...SANDBOX_ROUTE_ERROR_DEFINITIONS[code],\n\t};\n}\n\nexport function createSandboxRouteError(\n\tcode: SandboxRouteErrorCode,\n): Error & SandboxRouteErrorDetails {\n\tconst details: SandboxRouteErrorDetails = {\n\t\tcode,\n\t\t...SANDBOX_ROUTE_ERROR_DEFINITIONS[code],\n\t};\n\treturn Object.assign(new Error(details.message), details, { name: code });\n}\n\nexport function createSandboxRouteErrorEnvelope(error: unknown): SandboxRouteErrorEnvelope | null {\n\tconst details = getSandboxRouteErrorDetails(error);\n\treturn details ? { __emdashSandboxRouteError: true, error: details } : null;\n}\n\nexport function getSandboxRouteErrorEnvelope(value: unknown): SandboxRouteErrorEnvelope | null {\n\tif (!isRecord(value) || value.__emdashSandboxRouteError !== true) return null;\n\tconst details = getSandboxRouteErrorDetails(value.error);\n\treturn details ? { __emdashSandboxRouteError: true, error: details } : null;\n}\n\n/**\n * Sandbox runner interface.\n * Platform adapters implement this to provide plugin isolation.\n */\nexport interface SandboxRunner {\n\t/**\n\t * Check if sandboxing is available on this platform.\n\t * Returns false for platforms that don't support isolation.\n\t */\n\tisAvailable(): boolean;\n\n\t/**\n\t * Check if the sandbox runtime is currently healthy.\n\t * For in-process runners this always returns true.\n\t * For sidecar-based runners (workerd), returns false if the\n\t * child process has crashed and hasn't been restarted yet.\n\t */\n\tisHealthy(): boolean;\n\n\t/**\n\t * Why the runner cannot run plugins, once isAvailable() or isHealthy()\n\t * has returned false. A lowercase clause without a final period: callers\n\t * append it to their own message after a colon.\n\t *\n\t * Making this required breaks runners implemented outside this repository.\n\t */\n\tunavailableReason?(): string;\n\n\t/**\n\t * Load a sandboxed plugin from code.\n\t *\n\t * @param manifest - Plugin manifest with metadata and capabilities\n\t * @param code - The bundled plugin JavaScript code\n\t * @returns A sandboxed plugin instance\n\t * @throws If sandboxing is not available or plugin can't be loaded\n\t */\n\tload(manifest: PluginManifest, code: string): Promise<SandboxedPluginInstance>;\n\n\t/**\n\t * Set the email send callback for sandboxed plugins.\n\t * Called after the EmailPipeline is created, since the pipeline\n\t * doesn't exist when the sandbox runner is constructed.\n\t */\n\tsetEmailSend(callback: SandboxEmailSendCallback | null): void;\n\tsetCommentModerate?(callback: SandboxCommentModerateCallback | null): void;\n\tsetContentCreate?(callback: SandboxContentCreateCallback | null): void;\n\tsetContentActions?(callback: ContentActionCallbacks | null): void;\n\n\t/** Wake a long-lived scheduler after a sandboxed plugin changes its tasks. */\n\tsetCronReschedule?(callback: (() => void) | null): void;\n\n\t/**\n\t * Terminate all loaded sandboxed plugins.\n\t * Called during shutdown or when reconfiguring.\n\t */\n\tterminateAll(): Promise<void>;\n}\n\nexport function withUnavailableReason(message: string, runner: SandboxRunner | null): string {\n\tconst reason = runner?.unavailableReason?.();\n\treturn reason ? `${message}: ${reason}` : message;\n}\n\n/**\n * Error thrown when the sandbox runtime is unavailable.\n * This happens when the sidecar process has crashed or hasn't started.\n */\nexport class SandboxUnavailableError extends Error {\n\tconstructor(pluginId: string, reason: string) {\n\t\tsuper(`Plugin sandbox unavailable for ${pluginId}: ${reason}`);\n\t\tthis.name = \"SandboxUnavailableError\";\n\t}\n}\n\n/**\n * Factory function type for creating sandbox runners.\n * Exported by platform adapters (e.g., @emdash-cms/cloudflare/sandbox).\n *\n * @example\n * ```typescript\n * // In @emdash-cms/cloudflare/sandbox\n * export const createSandboxRunner: SandboxRunnerFactory = (options) => {\n *   return new CloudflareSandboxRunner(options);\n * };\n * ```\n */\nexport type SandboxRunnerFactory = (options: SandboxOptions) => SandboxRunner;\n"],"mappings":";AAyNA,MAAM,kCAAkC;CACvC,oCAAoC;EACnC,SAAS;EACT,QAAQ;EACR;CACD,qCAAqC;EACpC,SAAS;EACT,QAAQ;EACR;CACD,6BAA6B;EAC5B,SAAS;EACT,QAAQ;EACR;CACD,6BAA6B;EAC5B,SAAS;EACT,QAAQ;EACR;CACD;AAeD,SAAS,SAAS,OAAkD;AACnE,QAAO,OAAO,UAAU,YAAY,UAAU;;AAG/C,SAAS,wBAAwB,OAAgD;AAChF,QAAO,OAAO,UAAU,YAAY,SAAS;;AAG9C,SAAgB,4BAA4B,OAAiD;AAC5F,KAAI,CAAC,SAAS,MAAM,CAAE,QAAO;CAE7B,MAAM,eAAe,wBAAwB,MAAM,KAAK,GAAG,MAAM,OAAO;CACxE,MAAM,WACL,iBAAiB,SAAS,wBAAwB,MAAM,KAAK,GAAG,MAAM,OAAO;AAC9E,KAAI,gBAAgB,YAAY,iBAAiB,SAAU,QAAO;CAElE,MAAM,OAAO,gBAAgB;AAC7B,KAAI,CAAC,QAAS,MAAM,WAAW,UAAa,MAAM,WAAW,IAAM,QAAO;AAE1E,QAAO;EACN;EACA,GAAG,gCAAgC;EACnC;;AAGF,SAAgB,wBACf,MACmC;CACnC,MAAM,UAAoC;EACzC;EACA,GAAG,gCAAgC;EACnC;AACD,QAAO,OAAO,OAAO,IAAI,MAAM,QAAQ,QAAQ,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;;AAG1E,SAAgB,gCAAgC,OAAkD;CACjG,MAAM,UAAU,4BAA4B,MAAM;AAClD,QAAO,UAAU;EAAE,2BAA2B;EAAM,OAAO;EAAS,GAAG;;AAGxE,SAAgB,6BAA6B,OAAkD;AAC9F,KAAI,CAAC,SAAS,MAAM,IAAI,MAAM,8BAA8B,KAAM,QAAO;CACzE,MAAM,UAAU,4BAA4B,MAAM,MAAM;AACxD,QAAO,UAAU;EAAE,2BAA2B;EAAM,OAAO;EAAS,GAAG;;AA6DxE,SAAgB,sBAAsB,SAAiB,QAAsC;CAC5F,MAAM,SAAS,QAAQ,qBAAqB;AAC5C,QAAO,SAAS,GAAG,QAAQ,IAAI,WAAW;;;;;;AAO3C,IAAa,0BAAb,cAA6C,MAAM;CAClD,YAAY,UAAkB,QAAgB;AAC7C,QAAM,kCAAkC,SAAS,IAAI,SAAS;AAC9D,OAAK,OAAO"}