emdash 0.40.0 → 0.41.0

package/dist/types-OC5c-edM.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-OC5c-edM.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\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\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/** 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\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\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\"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"}

package/dist/types-aOOxRSx6.mjs

@@ -0,0 +1,103 @@
+import { i as encodeBase64, t as decodeBase64 } from "./base64-DvnNgP7e.mjs";
+
+//#region src/database/repositories/types.ts
+/**
+* Hard cap on cursor length. Cursors we issue are short JSON-in-base64
+* blobs; a real cursor is well under 200 chars. This guards against
+* malicious callers passing megabyte-sized strings to force the base64
+* decoder to allocate (decodeBase64 is O(N) in input size). The MCP and
+* REST schemas also clamp at 2048 — this 4096 cap is a defense-in-depth
+* floor inside the repository helpers.
+*/
+const MAX_CURSOR_LENGTH = 4096;
+/**
+* Order value stamped into a cursor over a *staged* reference selection, whose
+* anchor is a translation group rather than a row in the link table.
+*
+* A preview and a public render page the same field from different places, so a
+* cursor can cross that boundary in either direction — the draft publishes, or
+* the preview session ends, mid-pagination. Both sides recognise this marker so
+* they can tell a foreign cursor from a malformed one and restart the field's
+* page rather than failing or silently emptying it.
+*/
+const STAGED_CURSOR_MARKER = "staged";
+/** Encode a cursor from order value + id */
+function encodeCursor(orderValue, id) {
+	return encodeBase64(JSON.stringify({
+		orderValue,
+		id
+	}));
+}
+/**
+* Thrown when a pagination cursor cannot be decoded.
+*
+* Repository callers should let this propagate; handler catch blocks
+* map it to a structured `INVALID_CURSOR` error so client pagination
+* bugs surface immediately rather than silently re-fetching the first
+* page.
+*/
+var InvalidCursorError = class extends Error {
+	constructor(cursor) {
+		const display = cursor.length > 50 ? `${cursor.slice(0, 47)}...` : cursor;
+		super(`Invalid pagination cursor: ${display}`);
+		this.name = "InvalidCursorError";
+	}
+};
+/**
+* Decode a cursor to order value + id.
+*
+* Throws `InvalidCursorError` if the cursor is empty, not valid base64,
+* not valid JSON, or doesn't contain string `orderValue` and `id` fields.
+*/
+function decodeCursor(cursor) {
+	if (!cursor) throw new InvalidCursorError(cursor);
+	if (cursor.length > MAX_CURSOR_LENGTH) throw new InvalidCursorError(cursor);
+	let parsed;
+	try {
+		parsed = JSON.parse(decodeBase64(cursor));
+	} catch {
+		throw new InvalidCursorError(cursor);
+	}
+	if (parsed === null || typeof parsed !== "object") throw new InvalidCursorError(cursor);
+	const candidate = parsed;
+	if (typeof candidate.orderValue !== "string" || typeof candidate.id !== "string") throw new InvalidCursorError(cursor);
+	return {
+		orderValue: candidate.orderValue,
+		id: candidate.id
+	};
+}
+var EmDashValidationError = class extends Error {
+	constructor(message, details) {
+		super(message);
+		this.details = details;
+		this.name = "EmDashValidationError";
+	}
+};
+var ContentCollectionNotFoundError = class extends Error {
+	constructor(collection) {
+		super(`Collection '${collection}' not found`);
+		this.name = "ContentCollectionNotFoundError";
+	}
+};
+/**
+* Thrown by `publish()` when called with `requireDue` for a row that is no
+* longer due (its `scheduled_at` was cleared or pushed into the future between
+* selection and publish — e.g. an editor unscheduled it). Lets the scheduled
+* sweep skip the row silently rather than treating it as a publish failure.
+*/
+var ScheduledNotDueError = class extends Error {
+	constructor(message = "Content is no longer scheduled to publish") {
+		super(message);
+		this.name = "ScheduledNotDueError";
+	}
+};
+var ContentMutationConflictError = class extends Error {
+	constructor(message = "Content changed while the operation was in progress") {
+		super(message);
+		this.name = "ContentMutationConflictError";
+	}
+};
+
+//#endregion
+export { STAGED_CURSOR_MARKER as a, encodeCursor as c, InvalidCursorError as i, ContentMutationConflictError as n, ScheduledNotDueError as o, EmDashValidationError as r, decodeCursor as s, ContentCollectionNotFoundError as t };
+//# sourceMappingURL=types-aOOxRSx6.mjs.map

package/dist/types-aOOxRSx6.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-aOOxRSx6.mjs","names":[],"sources":["../src/database/repositories/types.ts"],"sourcesContent":["import type { ContentFieldFilters } from \"../../content-list-query.js\";\nimport type { CustomFieldValue } from \"../../schema/types.js\";\nimport { encodeBase64, decodeBase64 } from \"../../utils/base64.js\";\n\n/**\n * Hard cap on cursor length. Cursors we issue are short JSON-in-base64\n * blobs; a real cursor is well under 200 chars. This guards against\n * malicious callers passing megabyte-sized strings to force the base64\n * decoder to allocate (decodeBase64 is O(N) in input size). The MCP and\n * REST schemas also clamp at 2048 — this 4096 cap is a defense-in-depth\n * floor inside the repository helpers.\n */\nconst MAX_CURSOR_LENGTH = 4096;\n\nexport interface CreateContentInput {\n\t/** Explicit content ID for stable seed imports. Omit to generate a ULID. */\n\tid?: string;\n\ttype: string;\n\tslug?: string | null;\n\tdata: Record<string, unknown>;\n\tstatus?: string;\n\tauthorId?: string;\n\tprimaryBylineId?: string | null;\n\tlocale?: string;\n\ttranslationOf?: string;\n\t/** Field columns selected atomically from `translationOf` during the insert. */\n\tinheritFields?: string[];\n\tpublishedAt?: string | null;\n\t/** Override created_at (ISO 8601). Used by importers to preserve original dates. */\n\tcreatedAt?: string | null;\n}\n\nexport interface UpdateContentInput {\n\tdata?: Record<string, unknown>;\n\tstatus?: string;\n\tslug?: string | null;\n\tpublishedAt?: string | null;\n\tscheduledAt?: string | null;\n\t/** Entry owner (`ec_{collection}.author_id`). */\n\tauthorId?: string | null;\n\t/** Revision author, separate from entry ownership. */\n\trevisionAuthorId?: string | null;\n\tprimaryBylineId?: string | null;\n}\n\n/** SEO fields for content items */\nexport interface ContentSeo {\n\ttitle: string | null;\n\tdescription: string | null;\n\timage: string | null;\n\tcanonical: string | null;\n\tnoIndex: boolean;\n}\n\n/** Input for updating SEO fields on content */\nexport interface ContentSeoInput {\n\ttitle?: string | null;\n\tdescription?: string | null;\n\timage?: string | null;\n\tcanonical?: string | null;\n\tnoIndex?: boolean;\n}\n\nexport interface BylineSummary {\n\tid: string;\n\tslug: string;\n\tdisplayName: string;\n\tbio: string | null;\n\tavatarMediaId: string | null;\n\t/**\n\t * The avatar media's storage key, folded in by a LEFT JOIN on the\n\t * `media` table. Populated by the content-credit hydration path\n\t * (`getContentBylines` / `getContentBylinesMany`, i.e. the\n\t * `entry.data.bylines` populated by `getEmDashCollection` /\n\t * `getEmDashEntry`) and by the single-row finders (`findById`,\n\t * `findBySlug`, `findByUserId`, `findByUserIds`). `findMany` doesn't\n\t * join media, so it leaves this null.\n\t *\n\t * Lets a page build a direct storage URL for an author avatar without a\n\t * per-byline `MediaRepository.findById`, avoiding an N+1 when many distinct\n\t * authors appear on one page.\n\t *\n\t * Optional so adding it is a non-breaking change for existing code that\n\t * constructs a `BylineSummary` literal; the repositories always populate it\n\t * (to `null` when there's no avatar or no media join).\n\t */\n\tavatarStorageKey?: string | null;\n\t/** Avatar media alt text, from the same media join. Null when not joined. */\n\tavatarAlt?: string | null;\n\t/**\n\t * Avatar media blurhash (LQIP placeholder, migration 024), folded in by the\n\t * same media join as `avatarStorageKey`. Lets a renderer paint a blurred\n\t * placeholder while the full avatar loads, with no extra media lookup.\n\t * Null when the byline has no avatar, the media row has no blurhash, or the\n\t * byline came from `findMany`, which doesn't join media.\n\t */\n\tavatarBlurhash?: string | null;\n\t/**\n\t * Avatar media dominant colour (LQIP placeholder, migration 024), from the\n\t * same media join. Null under the same conditions as `avatarBlurhash`.\n\t */\n\tavatarDominantColor?: string | null;\n\twebsiteUrl: string | null;\n\tuserId: string | null;\n\tisGuest: boolean;\n\tcreatedAt: string;\n\tupdatedAt: string;\n\t/**\n\t * Locale this byline row is presented in. Added by migration 040.\n\t * `(slug, locale)` is unique; a single slug can repeat across locales.\n\t */\n\tlocale: string;\n\t/**\n\t * Shared across translations of the same byline. Added by migration 040.\n\t * `_emdash_content_bylines.byline_id` and `ec_*.primary_byline_id` store\n\t * this value, so a credit spans every locale variant of a byline.\n\t * Nullable in storage for backwards compatibility; new rows always\n\t * populate it.\n\t */\n\ttranslationGroup: string | null;\n\t/**\n\t * Custom field values registered via the byline-fields schema (migration\n\t * 041, Discussion #1174). Optional in the TypeScript shape so existing\n\t * object-literal consumers (test fixtures, plugin renderers) stay\n\t * source-compatible; the runtime always returns `{}` when no fields are\n\t * registered. Translatable values reflect this row's locale; non-\n\t * translatable values are shared across every locale variant of the\n\t * byline's `translation_group`.\n\t */\n\tcustomFields?: Record<string, CustomFieldValue>;\n}\n\nexport interface ContentBylineCredit {\n\tbyline: BylineSummary;\n\tsortOrder: number;\n\troleLabel: string | null;\n\t/** Whether this credit was explicitly assigned or inferred from authorId */\n\tsource?: \"explicit\" | \"inferred\";\n}\n\n/** A whitelisted timestamp column a content-list date range can filter on. */\nexport type ContentDateField = \"createdAt\" | \"updatedAt\" | \"publishedAt\";\n\n/**\n * Inclusive date-range filter for a single whitelisted timestamp column.\n * Bounds are compared lexicographically against the stored ISO 8601 strings,\n * which is correct because every timestamp is written via `toISOString()`.\n * Callers wanting an inclusive upper bound should pass an end-of-day value\n * (e.g. `2024-12-31T23:59:59.999Z`); the repository does not widen `to`.\n */\nexport interface ContentDateFilter {\n\tfield: ContentDateField;\n\tfrom?: string;\n\tto?: string;\n}\n\n/**\n * Byline filter for a content list.\n *\n * `mode: \"any\"` matches entries credited to at least one of `bylineIds`;\n * `mode: \"none\"` matches entries with no credit at all.\n *\n * `bylineIds` are `translation_group` values — what\n * `_emdash_content_bylines.byline_id` stores since migration 040 — so a filter\n * matches a byline across every locale variant.\n *\n * By default only explicit credits count. `includeInferred` widens the filter\n * to the byline the list actually renders, which for an entry with no credits\n * is the one linked to its `author_id` (see `hydrateBylinesMany`).\n */\nexport interface ContentBylineFilter {\n\tmode: \"any\" | \"none\";\n\t/** Ignored when `mode` is `\"none\"`. An empty list matches nothing. */\n\tbylineIds?: string[];\n\tincludeInferred?: boolean;\n\t/**\n\t * Locale a credit has to resolve at — the locale the list is scoped to.\n\t * Applies to explicit credits as well as inferred ones, since a byline\n\t * group credited to an entry renders only where it has a row at that\n\t * locale. Defaults to each entry's own locale when the list spans locales.\n\t */\n\tlocale?: string;\n}\n\nexport interface FindManyOptions {\n\twhere?: {\n\t\tstatus?: string;\n\t\tauthorId?: string;\n\t\tlocale?: string;\n\t\t/** Case-insensitive substring to match against `searchColumns`. */\n\t\tq?: string;\n\t\t/**\n\t\t * Columns the `q` substring filter is applied to (OR'd together).\n\t\t * Resolved by the handler from the collection's display fields, slug,\n\t\t * and any field marked searchable. Each name is validated as a SQL\n\t\t * identifier.\n\t\t */\n\t\tsearchColumns?: string[];\n\t\t/**\n\t\t * Serve `q` from the collection's FTS5 index (`_emdash_fts_<slug>`)\n\t\t * instead of an unindexable substring LIKE. Set by the handler only\n\t\t * when the collection has search enabled and the index exists\n\t\t * (SQLite only). The repository combines a token-prefix MATCH with\n\t\t * an index-served slug prefix so slug lookups keep working.\n\t\t */\n\t\tuseFts?: boolean;\n\t\t/** Inclusive date range over a whitelisted timestamp column. */\n\t\tdateFilter?: ContentDateFilter;\n\t\t/** Restrict to entries by their byline credits. */\n\t\tbylineFilter?: ContentBylineFilter;\n\t\t/** AND-combined filters over custom fields explicitly marked as indexed. */\n\t\tfieldFilters?: ContentFieldFilters;\n\t};\n\torderBy?: {\n\t\tfield: string;\n\t\tdirection: \"asc\" | \"desc\";\n\t};\n\t/**\n\t * Extra field slugs allowed as `orderBy` beyond the system columns — the\n\t * collection's configured titleField/dateField. Resolved by the\n\t * handler server-side so `orderBy` stays a closed set per request.\n\t */\n\tsortableExtras?: string[];\n\tlimit?: number;\n\tcursor?: string; // Base64-encoded JSON: {orderValue: string, id: string}\n}\n\nexport interface FindManyResult<T> {\n\titems: T[];\n\tnextCursor?: string; // Base64-encoded JSON: {orderValue: string, id: string}\n\t/**\n\t * Total number of rows matching the where clause (ignoring pagination).\n\t * Optional because not every caller needs it; repositories that compute\n\t * it should set it so the UI can render a stable pagination denominator.\n\t */\n\ttotal?: number;\n}\n\n/**\n * Order value stamped into a cursor over a *staged* reference selection, whose\n * anchor is a translation group rather than a row in the link table.\n *\n * A preview and a public render page the same field from different places, so a\n * cursor can cross that boundary in either direction — the draft publishes, or\n * the preview session ends, mid-pagination. Both sides recognise this marker so\n * they can tell a foreign cursor from a malformed one and restart the field's\n * page rather than failing or silently emptying it.\n */\nexport const STAGED_CURSOR_MARKER = \"staged\";\n\n/** Encode a cursor from order value + id */\nexport function encodeCursor(orderValue: string, id: string): string {\n\treturn encodeBase64(JSON.stringify({ orderValue, id }));\n}\n\n/**\n * Thrown when a pagination cursor cannot be decoded.\n *\n * Repository callers should let this propagate; handler catch blocks\n * map it to a structured `INVALID_CURSOR` error so client pagination\n * bugs surface immediately rather than silently re-fetching the first\n * page.\n */\nexport class InvalidCursorError extends Error {\n\tconstructor(cursor: string) {\n\t\tconst display = cursor.length > 50 ? `${cursor.slice(0, 47)}...` : cursor;\n\t\tsuper(`Invalid pagination cursor: ${display}`);\n\t\tthis.name = \"InvalidCursorError\";\n\t}\n}\n\n/**\n * Decode a cursor to order value + id.\n *\n * Throws `InvalidCursorError` if the cursor is empty, not valid base64,\n * not valid JSON, or doesn't contain string `orderValue` and `id` fields.\n */\nexport function decodeCursor(cursor: string): { orderValue: string; id: string } {\n\tif (!cursor) throw new InvalidCursorError(cursor);\n\tif (cursor.length > MAX_CURSOR_LENGTH) throw new InvalidCursorError(cursor);\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(decodeBase64(cursor));\n\t} catch {\n\t\tthrow new InvalidCursorError(cursor);\n\t}\n\tif (parsed === null || typeof parsed !== \"object\") {\n\t\tthrow new InvalidCursorError(cursor);\n\t}\n\tconst candidate = parsed as { orderValue?: unknown; id?: unknown };\n\tif (typeof candidate.orderValue !== \"string\" || typeof candidate.id !== \"string\") {\n\t\tthrow new InvalidCursorError(cursor);\n\t}\n\treturn { orderValue: candidate.orderValue, id: candidate.id };\n}\n\nexport interface ContentItem {\n\tid: string;\n\ttype: string;\n\tslug: string | null;\n\tstatus: string;\n\tdata: Record<string, unknown>;\n\tauthorId: string | null;\n\tprimaryBylineId: string | null;\n\tbyline?: BylineSummary | null;\n\tbylines?: ContentBylineCredit[];\n\tcreatedAt: string;\n\tupdatedAt: string;\n\tpublishedAt: string | null;\n\tscheduledAt: string | null;\n\tliveRevisionId: string | null;\n\tdraftRevisionId: string | null;\n\tversion: number;\n\tlocale: string | null;\n\ttranslationGroup: string | null;\n\t/** SEO metadata — only populated for collections with `has_seo` enabled */\n\tseo?: ContentSeo;\n\t/**\n\t * For collections that support `revisions`: when a draft revision exists,\n\t * `data` reflects the unsaved draft and `liveData` carries the currently-\n\t * published values. When no draft exists, `liveData` is undefined.\n\t *\n\t * Hydrated by `EmDashRuntime.hydrateDraftData()` — repositories themselves\n\t * never set this field; it's purely a runtime-overlay concept that gives\n\t * agents a clear picture of \"draft vs. live\" without re-fetching the\n\t * revision history.\n\t */\n\tliveData?: Record<string, unknown>;\n\t/**\n\t * First page of each reference field's resolved selection, keyed by field\n\t * slug. Only populated when the caller opts in via `handleContentGet`'s\n\t * `referenceOptions` param (see content.ts) — hydration is never\n\t * unconditional because it can leak draft ids/slugs to callers without\n\t * `content:read_drafts`.\n\t *\n\t * Shape mirrors `EntryRef` from `api/handlers/relations.ts`, duplicated\n\t * here (rather than imported) so the database layer doesn't depend on\n\t * the api/handlers layer.\n\t */\n\treferences?: Record<\n\t\tstring,\n\t\t{\n\t\t\tchildren: Array<{\n\t\t\t\tid: string;\n\t\t\t\tslug: string | null;\n\t\t\t\tcollection: string;\n\t\t\t\ttitle: string | null;\n\t\t\t\tlocale: string | null;\n\t\t\t\ttranslationGroup: string | null;\n\t\t\t\tsortOrder?: number;\n\t\t\t}>;\n\t\t\tnextCursor?: string;\n\t\t}\n\t>;\n}\n\nexport class EmDashValidationError extends Error {\n\tconstructor(\n\t\tmessage: string,\n\t\tpublic details?: unknown,\n\t) {\n\t\tsuper(message);\n\t\tthis.name = \"EmDashValidationError\";\n\t}\n}\n\nexport class ContentCollectionNotFoundError extends Error {\n\tconstructor(collection: string) {\n\t\tsuper(`Collection '${collection}' not found`);\n\t\tthis.name = \"ContentCollectionNotFoundError\";\n\t}\n}\n\n/**\n * Thrown by `publish()` when called with `requireDue` for a row that is no\n * longer due (its `scheduled_at` was cleared or pushed into the future between\n * selection and publish — e.g. an editor unscheduled it). Lets the scheduled\n * sweep skip the row silently rather than treating it as a publish failure.\n */\nexport class ScheduledNotDueError extends Error {\n\tconstructor(message = \"Content is no longer scheduled to publish\") {\n\t\tsuper(message);\n\t\tthis.name = \"ScheduledNotDueError\";\n\t}\n}\n\nexport class ContentMutationConflictError extends Error {\n\tconstructor(message = \"Content changed while the operation was in progress\") {\n\t\tsuper(message);\n\t\tthis.name = \"ContentMutationConflictError\";\n\t}\n}\n"],"mappings":";;;;;;;;;;;AAYA,MAAM,oBAAoB;;;;;;;;;;;AA4O1B,MAAa,uBAAuB;;AAGpC,SAAgB,aAAa,YAAoB,IAAoB;AACpE,QAAO,aAAa,KAAK,UAAU;EAAE;EAAY;EAAI,CAAC,CAAC;;;;;;;;;;AAWxD,IAAa,qBAAb,cAAwC,MAAM;CAC7C,YAAY,QAAgB;EAC3B,MAAM,UAAU,OAAO,SAAS,KAAK,GAAG,OAAO,MAAM,GAAG,GAAG,CAAC,OAAO;AACnE,QAAM,8BAA8B,UAAU;AAC9C,OAAK,OAAO;;;;;;;;;AAUd,SAAgB,aAAa,QAAoD;AAChF,KAAI,CAAC,OAAQ,OAAM,IAAI,mBAAmB,OAAO;AACjD,KAAI,OAAO,SAAS,kBAAmB,OAAM,IAAI,mBAAmB,OAAO;CAC3E,IAAI;AACJ,KAAI;AACH,WAAS,KAAK,MAAM,aAAa,OAAO,CAAC;SAClC;AACP,QAAM,IAAI,mBAAmB,OAAO;;AAErC,KAAI,WAAW,QAAQ,OAAO,WAAW,SACxC,OAAM,IAAI,mBAAmB,OAAO;CAErC,MAAM,YAAY;AAClB,KAAI,OAAO,UAAU,eAAe,YAAY,OAAO,UAAU,OAAO,SACvE,OAAM,IAAI,mBAAmB,OAAO;AAErC,QAAO;EAAE,YAAY,UAAU;EAAY,IAAI,UAAU;EAAI;;AA+D9D,IAAa,wBAAb,cAA2C,MAAM;CAChD,YACC,SACA,AAAO,SACN;AACD,QAAM,QAAQ;EAFP;AAGP,OAAK,OAAO;;;AAId,IAAa,iCAAb,cAAoD,MAAM;CACzD,YAAY,YAAoB;AAC/B,QAAM,eAAe,WAAW,aAAa;AAC7C,OAAK,OAAO;;;;;;;;;AAUd,IAAa,uBAAb,cAA0C,MAAM;CAC/C,YAAY,UAAU,6CAA6C;AAClE,QAAM,QAAQ;AACd,OAAK,OAAO;;;AAId,IAAa,+BAAb,cAAkD,MAAM;CACvD,YAAY,UAAU,uDAAuD;AAC5E,QAAM,QAAQ;AACd,OAAK,OAAO"}

package/dist/types-m1WbUffD.d.mts

@@ -0,0 +1,198 @@
+import * as react from "react";
+
+//#region src/auth/types.d.ts
+/**
+ * Auth Provider Types
+ *
+ * Defines the interfaces for pluggable authentication providers.
+ *
+ * Two systems coexist:
+ * - `AuthDescriptor` — transparent auth (Cloudflare Access) that authenticates
+ *   every request via headers/cookies. No login UI needed.
+ * - `AuthProviderDescriptor` — pluggable login methods (GitHub, Google,
+ *   AT Protocol, etc.) that appear as options on the login page and setup
+ *   wizard. Passkey is built-in; providers are additive.
+ */
+/**
+ * Result of authenticating a request via an external auth provider
+ */
+interface AuthResult {
+  /** User's email address */
+  email: string;
+  /** User's display name */
+  name: string;
+  /** Resolved role level (e.g., 50 for Admin, 30 for Editor) */
+  role: number;
+  /** Provider-specific subject ID */
+  subject?: string;
+  /** Additional provider-specific data */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Auth descriptor — transparent auth providers (e.g., Cloudflare Access).
+ *
+ * These authenticate every request via headers/cookies. No login UI needed.
+ * The module's `authenticate()` function is called by middleware on each request.
+ */
+interface AuthDescriptor {
+  /**
+   * Auth provider type identifier
+   * @example "cloudflare-access", "okta", "auth0"
+   */
+  type: string;
+  /**
+   * Module specifier to import at runtime
+   * The module must export an `authenticate` function.
+   * @example "@emdash-cms/cloudflare/auth"
+   */
+  entrypoint: string;
+  /**
+   * Provider-specific configuration (JSON-serializable)
+   */
+  config: unknown;
+}
+/**
+ * Auth provider module interface
+ *
+ * Modules specified by AuthDescriptor.entrypoint must export
+ * an `authenticate` function matching this signature.
+ */
+interface AuthProviderModule {
+  /**
+   * Authenticate a request using the provider
+   *
+   * @param request - The incoming HTTP request
+   * @param config - Provider-specific configuration from AuthDescriptor
+   * @returns Authentication result if valid, throws if invalid
+   */
+  authenticate(request: Request, config: unknown): Promise<AuthResult>;
+}
+/**
+ * Descriptor for a pluggable auth provider.
+ *
+ * Auth providers appear as login options on the login page and setup wizard.
+ * They coexist with passkey (which is built-in) and with each other.
+ * Any provider can be used to create the initial admin account.
+ *
+ * @example
+ * ```ts
+ * // astro.config.ts
+ * import { atproto } from "@emdash-cms/auth-atproto";
+ *
+ * emdash({
+ *   authProviders: [atproto(), github(), google()],
+ * })
+ * ```
+ */
+interface AuthProviderDescriptor {
+  /** Unique provider ID (e.g., "github", "atproto") */
+  id: string;
+  /** Human-readable label for UI (e.g., "GitHub", "AT Protocol") */
+  label: string;
+  /** Provider-specific config (JSON-serializable) */
+  config?: unknown;
+  /**
+   * Module exporting React components for the admin UI.
+   * Statically imported at build time via virtual module.
+   *
+   * The module should export components matching `AuthProviderAdminExports`.
+   */
+  adminEntry?: string;
+  /**
+   * Astro route handlers this provider needs injected at build time.
+   * Used for login initiation, OAuth callbacks, well-known endpoints, etc.
+   */
+  routes?: AuthRouteDescriptor[];
+  /**
+   * URL prefixes/paths that should bypass auth middleware.
+   * Added to the public routes set so login/callback endpoints work
+   * for unauthenticated users.
+   */
+  publicRoutes?: string[];
+  /**
+   * Storage collections for persistent auth state (e.g., OAuth sessions).
+   * Same format as plugin storage — collections are stored in the shared
+   * `_plugin_storage` table namespaced under `auth:<providerId>`.
+   *
+   * Access via `getAuthProviderStorage()` from `emdash/api/route-utils`.
+   */
+  storage?: Record<string, {
+    indexes?: Array<string | string[]>;
+    uniqueIndexes?: Array<string | string[]>;
+  }>;
+}
+/**
+ * A route that an auth provider needs injected into the Astro app.
+ */
+interface AuthRouteDescriptor {
+  /** URL pattern (e.g., "/_emdash/api/auth/atproto/login") */
+  pattern: string;
+  /** Module specifier for the Astro route handler */
+  entrypoint: string;
+}
+/**
+ * Expected exports from an auth provider's `adminEntry` module.
+ *
+ * All exports are optional. Providers export whichever components
+ * make sense for their auth flow.
+ */
+interface AuthProviderAdminExports {
+  /**
+   * Compact button for the login page (icon + label).
+   * Used for providers with a simple redirect flow (GitHub, Google).
+   * Rendered in the "Or continue with" section.
+   */
+  LoginButton?: react.ComponentType;
+  /**
+   * Full login form for providers that need custom input.
+   * Used for providers like AT Protocol that need a handle field.
+   * Rendered as an expandable section on the login page.
+   */
+  LoginForm?: react.ComponentType;
+  /**
+   * Setup wizard step for creating the admin account via this provider.
+   * When present, this provider appears as an option in the setup wizard's
+   * "Create admin account" step.
+   */
+  SetupStep?: react.ComponentType<{
+    onComplete: () => void;
+  }>;
+}
+/**
+ * Configuration options common to external auth providers
+ */
+interface ExternalAuthConfig {
+  /**
+   * Automatically create EmDash users on first login
+   * @default true
+   */
+  autoProvision?: boolean;
+  /**
+   * Role level for users not matching any group in roleMapping
+   * @default 30 (Editor)
+   */
+  defaultRole?: number;
+  /**
+   * Update user's role on each login based on current IdP groups
+   * When false, role is only set on first provisioning
+   * @default false
+   */
+  syncRoles?: boolean;
+  /**
+   * Map IdP group names to EmDash role levels
+   * First match wins if user is in multiple groups
+   *
+   * @example
+   * ```ts
+   * roleMapping: {
+   *   "Admins": 50,        // Admin
+   *   "Developers": 40,    // Developer
+   *   "Content Team": 30,  // Editor
+   * }
+   * ```
+   */
+  roleMapping?: Record<string, number>;
+}
+//#endregion
+export { AuthResult as a, AuthProviderModule as i, AuthProviderAdminExports as n, AuthRouteDescriptor as o, AuthProviderDescriptor as r, ExternalAuthConfig as s, AuthDescriptor as t };
+//# sourceMappingURL=types-m1WbUffD.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types-m1WbUffD.d.mts","names":[],"sources":["../src/auth/types.ts"],"mappings":";;;;;;AAgBA;;;;;;;;;;;;UAAiB,UAAA;EAmBc;EAjB9B,KAAA;EAiB8B;EAf9B,IAAA;EA2BA;EAzBA,IAAA;EA8BM;EA5BN,OAAA;EAqCgB;EAnChB,QAAA,GAAW,MAAA;AAAA;;;;;;;UASK,cAAA;EAkCH;;;;EA7Bb,IAAA;EA6BmE;AAwBpE;;;;EA9CC,UAAA;EAsFuD;;;EAjFvD,MAAA;AAAA;;;;;;;UASgB,kBAAA;EAsEN;;;;;;;EA9DV,YAAA,CAAa,OAAA,EAAS,OAAA,EAAS,MAAA,YAAkB,OAAA,CAAQ,UAAA;AAAA;;;;AAoF1D;;;;;;;;;;;;;;UA5DiB,sBAAA;EAgFsC;EA9EtD,EAAA;EAoFgB;EAjFhB,KAAA;;EAGA,MAAA;EAmFA;;;;;;EA3EA,UAAA;;;;;EAMA,MAAA,GAAS,mBAAA;;;;;;EAOT,YAAA;;;;;;;;EASA,OAAA,GAAU,MAAA;IAEP,OAAA,GAAU,KAAA;IAA0B,aAAA,GAAgB,KAAA;EAAA;AAAA;;;;UAOvC,mBAAA;;EAEhB,OAAA;;EAEA,UAAA;AAAA;;;;;;;UASgB,wBAAA;;;;;;EAMhB,WAAA,GANwC,KAAA,CAMV,aAAA;;;;;;EAO9B,SAAA,GAP2C,KAAA,CAOf,aAAA;;;;;;EAO5B,SAAA,GAPyC,KAAA,CAOb,aAAA;IAAgB,UAAA;EAAA;AAAA;;;;UAM5B,kBAAA;;;;;EAKhB,aAAA;;;;;EAMA,WAAA;;;;;;EAOA,SAAA;;;;;;;;;;;;;;EAeA,WAAA,GAAc,MAAA;AAAA"}

package/dist/types-uxLoPBio.d.mts

@@ -0,0 +1,124 @@
+//#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.
+   * Only anonymous visitors are affected — preview and edit requests bypass the
+   * cache.
+   *
+   * 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-uxLoPBio.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types-uxLoPBio.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;;;;;;;AAwFtB;;UA7EiB,qBAAA;EA6EgF;EA3EhG,UAAA;EA2EyC;EAzEzC,MAAA,EAAQ,wBAAA;AAAA;;;;;;;;UAUQ,wBAAA;;;;;;;;;;;EAWhB,UAAA;;;;;;;;;;;;;;;;;;EAkBA,UAAA;;;;;;;EAOA,SAAA;;;;;;;;;;;;;;;EAeA,OAAA;;GAEC,GAAA;AAAA;;;;;;;;KAUU,0BAAA,IAA8B,MAAA,EAAQ,wBAAA,KAA6B,kBAAA"}