emdash 1.1.0 → 1.3.0

package/dist/types-sUHaH7lC.mjs.map

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

package/dist/types-slSqujQL.d.mts

@@ -0,0 +1,204 @@
+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, 40 for Editor, 30 for Author) */
+  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 (Author, who can publish their own content)
+   */
+  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;
+  /**
+   * Update user's name from the IdP on every authenticated request
+   * When false, name is only set on first provisioning, so names edited in the admin are kept
+   * @default true
+   */
+  syncName?: boolean;
+  /**
+   * Map IdP group names to EmDash role levels
+   * First match wins if user is in multiple groups
+   *
+   * @example
+   * ```ts
+   * roleMapping: {
+   *   "Admins": 50,        // Admin
+   *   "Editors": 40,       // Editor
+   *   "Content Team": 30,  // Author
+   * }
+   * ```
+   */
+  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-slSqujQL.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types-slSqujQL.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;EA8GoB;;;;EAxGpB,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;;;;;;EAOA,QAAA;;;;;;;;;;;;;;EAeA,WAAA,GAAc,MAAA;AAAA"}

package/dist/update-check-BxNg9T6N.mjs

@@ -0,0 +1,161 @@
+import { t as after } from "./after-PcEvMY_6.mjs";
+import { t as OptionsRepository } from "./options-DhrI7eMv.mjs";
+import { a as parseDurationSeconds } from "./config-DBU6iUQB.mjs";
+import { n as VERSION } from "./version-DHmGpcch.mjs";
+import { t as ErrorCode } from "./errors-BOYNdIo3.mjs";
+
+//#region src/api/handlers/update-check.ts
+/** Options-table key for the cached registry result. */
+const CORE_UPDATE_OPTION = "emdash:core_update_check";
+/** Check the registry at most once per day, whether or not the check succeeds. */
+const CHECK_INTERVAL_MS = 1440 * 60 * 1e3;
+/** npm packument for `emdash`: the `latest` dist-tag and each version's publish time. */
+const REGISTRY_URL = "https://registry.npmjs.org/emdash";
+/** Default time a release must be public before admins are told about it. */
+const DEFAULT_MINIMUM_RELEASE_AGE = "24h";
+const REGISTRY_TIMEOUT_MS = 1e4;
+const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(-.+)?$/;
+const STABLE_RE = /^\d+\.\d+\.\d+$/;
+/**
+* True when `latest` is a strictly newer release than `current`.
+*
+* Handles plain `major.minor.patch` versions. Anything unparsable —
+* including the `"dev"` fallback version — compares as "not newer", so
+* dev/test runs never show the banner. On an equal base version, a stable
+* release is newer than a prerelease of it, so a site running
+* `0.24.0-beta.1` is notified when `0.24.0` ships. Prerelease identifiers
+* are not compared to each other.
+*/
+function isNewerVersion(latest, current) {
+	const l = SEMVER_RE.exec(latest);
+	const c = SEMVER_RE.exec(current);
+	if (!l || !c) return false;
+	for (let i = 1; i <= 3; i++) {
+		const a = Number(l[i]);
+		const b = Number(c[i]);
+		if (a !== b) return a > b;
+	}
+	return !l[4] && !!c[4];
+}
+function field(value, key) {
+	return typeof value === "object" && value !== null && Object.hasOwn(value, key) ? Reflect.get(value, key) : void 0;
+}
+/**
+* Fetch the stable releases and their publish times from the npm registry
+* and cache them. Exported for tests; production callers go through
+* `handleCoreUpdateStatus`, which defers this via `after()`.
+*/
+async function refreshCoreUpdateCache(db, fetchImpl = fetch) {
+	const response = await fetchImpl(REGISTRY_URL, {
+		headers: { accept: "application/json" },
+		signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS)
+	});
+	if (!response.ok) throw new Error(`registry responded ${response.status}`);
+	const body = await response.json();
+	const latest = field(field(body, "dist-tags"), "latest");
+	if (typeof latest !== "string" || !STABLE_RE.test(latest)) throw new Error("registry response missing a valid version");
+	const time = field(body, "time");
+	const versions = field(body, "versions");
+	const releases = {};
+	if (typeof time === "object" && time !== null) for (const [version, publishedAt] of Object.entries(time)) {
+		if (!STABLE_RE.test(version) || isNewerVersion(version, latest)) continue;
+		const manifest = field(versions, version);
+		if (manifest === void 0 || field(manifest, "deprecated") !== void 0) continue;
+		if (typeof publishedAt !== "string" || Number.isNaN(Date.parse(publishedAt))) continue;
+		releases[version] = publishedAt;
+	}
+	if (!releases[latest]) throw new Error("registry response missing a publish time for the latest version");
+	const cache = {
+		releases,
+		checkedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	await new OptionsRepository(db).set(CORE_UPDATE_OPTION, cache);
+}
+function parseCache(value) {
+	const releases = field(value, "releases");
+	const checkedAt = field(value, "checkedAt");
+	if (typeof releases !== "object" || releases === null || typeof checkedAt !== "string") return null;
+	if (Number.isNaN(Date.parse(checkedAt))) return null;
+	const valid = {};
+	for (const [version, publishedAt] of Object.entries(releases)) if (STABLE_RE.test(version) && typeof publishedAt === "string" && !Number.isNaN(Date.parse(publishedAt))) valid[version] = publishedAt;
+	return {
+		releases: valid,
+		checkedAt
+	};
+}
+/** The newest release published at least `minimumAgeMs` before `now`. */
+function newestReleased(releases, now, minimumAgeMs) {
+	let newest = null;
+	for (const [version, publishedAt] of Object.entries(releases)) {
+		if (now.getTime() - Date.parse(publishedAt) < minimumAgeMs) continue;
+		if (!newest || isNewerVersion(version, newest)) newest = version;
+	}
+	return newest;
+}
+/**
+* Seconds a release must be public before it is reported, from the
+* `updateCheck` option. Throws on an invalid duration.
+*/
+function minimumReleaseAgeSeconds(option) {
+	return parseDurationSeconds((typeof option === "object" ? option?.minimumReleaseAge : void 0) ?? DEFAULT_MINIMUM_RELEASE_AGE);
+}
+/**
+* Report the cached update status and, when the cache is stale (or
+* missing), kick a deferred registry refresh. Never blocks on the
+* network: the first request after install/expiry reports the previous
+* state and the next request sees the refreshed one.
+*/
+async function handleCoreUpdateStatus(db, options) {
+	const current = options?.current ?? VERSION;
+	if (options?.enabled === false) return {
+		success: true,
+		data: {
+			current,
+			latest: null,
+			updateAvailable: false,
+			checkedAt: null
+		}
+	};
+	try {
+		const repo = new OptionsRepository(db);
+		const cache = parseCache(await repo.get(CORE_UPDATE_OPTION));
+		const now = options?.now ?? /* @__PURE__ */ new Date();
+		const minimumAgeMs = (options?.minimumReleaseAgeSeconds ?? minimumReleaseAgeSeconds(void 0)) * 1e3;
+		if ((!cache || now.getTime() - Date.parse(cache.checkedAt) >= CHECK_INTERVAL_MS) && current !== "dev") after(async () => {
+			try {
+				await refreshCoreUpdateCache(db);
+			} catch (error) {
+				console.warn("[update-check] registry refresh failed:", error);
+				if (parseCache(await repo.get(CORE_UPDATE_OPTION))?.checkedAt !== cache?.checkedAt) return;
+				const retryLater = {
+					releases: cache?.releases ?? {},
+					checkedAt: (/* @__PURE__ */ new Date()).toISOString()
+				};
+				await repo.set(CORE_UPDATE_OPTION, retryLater);
+			}
+		});
+		const latest = cache ? newestReleased(cache.releases, now, minimumAgeMs) : null;
+		return {
+			success: true,
+			data: {
+				current,
+				latest,
+				updateAvailable: latest ? isNewerVersion(latest, current) : false,
+				checkedAt: cache?.checkedAt ?? null
+			}
+		};
+	} catch (error) {
+		console.error("[update-check] status read failed:", error);
+		return {
+			success: false,
+			error: {
+				code: ErrorCode.UPDATE_CHECK_ERROR,
+				message: "Failed to read update status"
+			}
+		};
+	}
+}
+
+//#endregion
+export { minimumReleaseAgeSeconds as n, handleCoreUpdateStatus as t };
+//# sourceMappingURL=update-check-BxNg9T6N.mjs.map

package/dist/update-check-BxNg9T6N.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check-BxNg9T6N.mjs","names":[],"sources":["../src/api/handlers/update-check.ts"],"sourcesContent":["/**\n * Core update status handler.\n *\n * Caches the publish times of stable `emdash` releases from the npm\n * registry in the options table, and reports the newest release that has\n * been public for the minimum release age when it is newer than the\n * running `VERSION`. A stale or missing cache schedules a deferred refresh.\n */\n\nimport type { Kysely } from \"kysely\";\n\nimport { after } from \"../../after.js\";\nimport { OptionsRepository } from \"../../database/repositories/options.js\";\nimport type { Database } from \"../../database/types.js\";\nimport { parseDurationSeconds } from \"../../registry/config.js\";\nimport { VERSION } from \"../../version.js\";\nimport { ErrorCode } from \"../errors.js\";\nimport type { ApiResult } from \"../types.js\";\n\n/** Options-table key for the cached registry result. */\nexport const CORE_UPDATE_OPTION = \"emdash:core_update_check\";\n\n/** Check the registry at most once per day, whether or not the check succeeds. */\nconst CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;\n\n/** npm packument for `emdash`: the `latest` dist-tag and each version's publish time. */\nconst REGISTRY_URL = \"https://registry.npmjs.org/emdash\";\n\n/** Default time a release must be public before admins are told about it. */\nexport const DEFAULT_MINIMUM_RELEASE_AGE = \"24h\";\n\nconst REGISTRY_TIMEOUT_MS = 10_000;\n\n/** Cached registry state, stored in the options table. */\ninterface CoreUpdateCache {\n\t/** Publish time (ISO) of each non-deprecated stable release up to the `latest` dist-tag. */\n\treleases: Record<string, string>;\n\t/** ISO timestamp of the last registry check. */\n\tcheckedAt: string;\n}\n\nexport interface CoreUpdateStatus {\n\t/** The running EmDash version (`\"dev\"` in uncompiled dev/test runs). */\n\tcurrent: string;\n\t/**\n\t * Newest stable release that has been public for the minimum release\n\t * age, or null when no check has completed yet.\n\t */\n\tlatest: string | null;\n\tupdateAvailable: boolean;\n\t/** ISO timestamp of the last registry check, if any. */\n\tcheckedAt: string | null;\n}\n\nconst SEMVER_RE = /^(\\d+)\\.(\\d+)\\.(\\d+)(-.+)?$/;\nconst STABLE_RE = /^\\d+\\.\\d+\\.\\d+$/;\n\n/**\n * True when `latest` is a strictly newer release than `current`.\n *\n * Handles plain `major.minor.patch` versions. Anything unparsable —\n * including the `\"dev\"` fallback version — compares as \"not newer\", so\n * dev/test runs never show the banner. On an equal base version, a stable\n * release is newer than a prerelease of it, so a site running\n * `0.24.0-beta.1` is notified when `0.24.0` ships. Prerelease identifiers\n * are not compared to each other.\n */\nexport function isNewerVersion(latest: string, current: string): boolean {\n\tconst l = SEMVER_RE.exec(latest);\n\tconst c = SEMVER_RE.exec(current);\n\tif (!l || !c) return false;\n\tfor (let i = 1; i <= 3; i++) {\n\t\tconst a = Number(l[i]);\n\t\tconst b = Number(c[i]);\n\t\tif (a !== b) return a > b;\n\t}\n\treturn !l[4] && !!c[4];\n}\n\nfunction field(value: unknown, key: string): unknown {\n\treturn typeof value === \"object\" && value !== null && Object.hasOwn(value, key)\n\t\t? (Reflect.get(value, key) as unknown)\n\t\t: undefined;\n}\n\n/**\n * Fetch the stable releases and their publish times from the npm registry\n * and cache them. Exported for tests; production callers go through\n * `handleCoreUpdateStatus`, which defers this via `after()`.\n */\nexport async function refreshCoreUpdateCache(\n\tdb: Kysely<Database>,\n\tfetchImpl: typeof fetch = fetch,\n): Promise<void> {\n\tconst response = await fetchImpl(REGISTRY_URL, {\n\t\theaders: { accept: \"application/json\" },\n\t\tsignal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS),\n\t});\n\tif (!response.ok) {\n\t\tthrow new Error(`registry responded ${response.status}`);\n\t}\n\tconst body: unknown = await response.json();\n\tconst latest = field(field(body, \"dist-tags\"), \"latest\");\n\tif (typeof latest !== \"string\" || !STABLE_RE.test(latest)) {\n\t\tthrow new Error(\"registry response missing a valid version\");\n\t}\n\tconst time = field(body, \"time\");\n\tconst versions = field(body, \"versions\");\n\tconst releases: Record<string, string> = {};\n\tif (typeof time === \"object\" && time !== null) {\n\t\tfor (const [version, publishedAt] of Object.entries(time)) {\n\t\t\tif (!STABLE_RE.test(version) || isNewerVersion(version, latest)) continue;\n\t\t\tconst manifest = field(versions, version);\n\t\t\tif (manifest === undefined || field(manifest, \"deprecated\") !== undefined) continue;\n\t\t\tif (typeof publishedAt !== \"string\" || Number.isNaN(Date.parse(publishedAt))) continue;\n\t\t\treleases[version] = publishedAt;\n\t\t}\n\t}\n\tif (!releases[latest]) {\n\t\tthrow new Error(\"registry response missing a publish time for the latest version\");\n\t}\n\tconst cache: CoreUpdateCache = { releases, checkedAt: new Date().toISOString() };\n\tawait new OptionsRepository(db).set(CORE_UPDATE_OPTION, cache);\n}\n\nfunction parseCache(value: unknown): CoreUpdateCache | null {\n\tconst releases = field(value, \"releases\");\n\tconst checkedAt = field(value, \"checkedAt\");\n\tif (typeof releases !== \"object\" || releases === null || typeof checkedAt !== \"string\") {\n\t\treturn null;\n\t}\n\t// An unparsable checkedAt would make the staleness math NaN (never\n\t// stale), freezing a corrupt cache forever — treat it as no cache so\n\t// the next request schedules a refresh that overwrites it.\n\tif (Number.isNaN(Date.parse(checkedAt))) return null;\n\tconst valid: Record<string, string> = {};\n\tfor (const [version, publishedAt] of Object.entries(releases)) {\n\t\tif (\n\t\t\tSTABLE_RE.test(version) &&\n\t\t\ttypeof publishedAt === \"string\" &&\n\t\t\t!Number.isNaN(Date.parse(publishedAt))\n\t\t) {\n\t\t\tvalid[version] = publishedAt;\n\t\t}\n\t}\n\treturn { releases: valid, checkedAt };\n}\n\n/** The newest release published at least `minimumAgeMs` before `now`. */\nfunction newestReleased(\n\treleases: Record<string, string>,\n\tnow: Date,\n\tminimumAgeMs: number,\n): string | null {\n\tlet newest: string | null = null;\n\tfor (const [version, publishedAt] of Object.entries(releases)) {\n\t\tif (now.getTime() - Date.parse(publishedAt) < minimumAgeMs) continue;\n\t\tif (!newest || isNewerVersion(version, newest)) newest = version;\n\t}\n\treturn newest;\n}\n\n/**\n * Seconds a release must be public before it is reported, from the\n * `updateCheck` option. Throws on an invalid duration.\n */\nexport function minimumReleaseAgeSeconds(\n\toption: boolean | { minimumReleaseAge?: string | number } | null | undefined,\n): number {\n\tconst age = typeof option === \"object\" ? option?.minimumReleaseAge : undefined;\n\treturn parseDurationSeconds(age ?? DEFAULT_MINIMUM_RELEASE_AGE);\n}\n\n/**\n * Report the cached update status and, when the cache is stale (or\n * missing), kick a deferred registry refresh. Never blocks on the\n * network: the first request after install/expiry reports the previous\n * state and the next request sees the refreshed one.\n */\nexport async function handleCoreUpdateStatus(\n\tdb: Kysely<Database>,\n\toptions?: { now?: Date; enabled?: boolean; minimumReleaseAgeSeconds?: number; current?: string },\n): Promise<ApiResult<CoreUpdateStatus>> {\n\tconst current = options?.current ?? VERSION;\n\tif (options?.enabled === false) {\n\t\treturn {\n\t\t\tsuccess: true,\n\t\t\tdata: { current, latest: null, updateAvailable: false, checkedAt: null },\n\t\t};\n\t}\n\n\ttry {\n\t\tconst repo = new OptionsRepository(db);\n\t\tconst cache = parseCache(await repo.get(CORE_UPDATE_OPTION));\n\n\t\tconst now = options?.now ?? new Date();\n\t\tconst minimumAgeMs =\n\t\t\t(options?.minimumReleaseAgeSeconds ?? minimumReleaseAgeSeconds(undefined)) * 1000;\n\t\tconst stale = !cache || now.getTime() - Date.parse(cache.checkedAt) >= CHECK_INTERVAL_MS;\n\t\t// A \"dev\" version can never compare as outdated, so skip the\n\t\t// registry round-trip entirely in uncompiled dev/test runs.\n\t\tif (stale && current !== \"dev\") {\n\t\t\tafter(async () => {\n\t\t\t\ttry {\n\t\t\t\t\tawait refreshCoreUpdateCache(db);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tconsole.warn(\"[update-check] registry refresh failed:\", error);\n\t\t\t\t\tconst latestCache = parseCache(await repo.get(CORE_UPDATE_OPTION));\n\t\t\t\t\tif (latestCache?.checkedAt !== cache?.checkedAt) return;\n\t\t\t\t\tconst retryLater: CoreUpdateCache = {\n\t\t\t\t\t\treleases: cache?.releases ?? {},\n\t\t\t\t\t\tcheckedAt: new Date().toISOString(),\n\t\t\t\t\t};\n\t\t\t\t\tawait repo.set(CORE_UPDATE_OPTION, retryLater);\n\t\t\t\t}\n\t\t\t});\n\t\t}\n\n\t\tconst latest = cache ? newestReleased(cache.releases, now, minimumAgeMs) : null;\n\t\treturn {\n\t\t\tsuccess: true,\n\t\t\tdata: {\n\t\t\t\tcurrent,\n\t\t\t\tlatest,\n\t\t\t\tupdateAvailable: latest ? isNewerVersion(latest, current) : false,\n\t\t\t\tcheckedAt: cache?.checkedAt ?? null,\n\t\t\t},\n\t\t};\n\t} catch (error) {\n\t\tconsole.error(\"[update-check] status read failed:\", error);\n\t\treturn {\n\t\t\tsuccess: false,\n\t\t\terror: { code: ErrorCode.UPDATE_CHECK_ERROR, message: \"Failed to read update status\" },\n\t\t};\n\t}\n}\n"],"mappings":";;;;;;;;AAoBA,MAAa,qBAAqB;;AAGlC,MAAM,oBAAoB,OAAU,KAAK;;AAGzC,MAAM,eAAe;;AAGrB,MAAa,8BAA8B;AAE3C,MAAM,sBAAsB;AAuB5B,MAAM,YAAY;AAClB,MAAM,YAAY;;;;;;;;;;;AAYlB,SAAgB,eAAe,QAAgB,SAA0B;CACxE,MAAM,IAAI,UAAU,KAAK,OAAO;CAChC,MAAM,IAAI,UAAU,KAAK,QAAQ;AACjC,KAAI,CAAC,KAAK,CAAC,EAAG,QAAO;AACrB,MAAK,IAAI,IAAI,GAAG,KAAK,GAAG,KAAK;EAC5B,MAAM,IAAI,OAAO,EAAE,GAAG;EACtB,MAAM,IAAI,OAAO,EAAE,GAAG;AACtB,MAAI,MAAM,EAAG,QAAO,IAAI;;AAEzB,QAAO,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE;;AAGrB,SAAS,MAAM,OAAgB,KAAsB;AACpD,QAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,OAAO,OAAO,OAAO,IAAI,GAC3E,QAAQ,IAAI,OAAO,IAAI,GACxB;;;;;;;AAQJ,eAAsB,uBACrB,IACA,YAA0B,OACV;CAChB,MAAM,WAAW,MAAM,UAAU,cAAc;EAC9C,SAAS,EAAE,QAAQ,oBAAoB;EACvC,QAAQ,YAAY,QAAQ,oBAAoB;EAChD,CAAC;AACF,KAAI,CAAC,SAAS,GACb,OAAM,IAAI,MAAM,sBAAsB,SAAS,SAAS;CAEzD,MAAM,OAAgB,MAAM,SAAS,MAAM;CAC3C,MAAM,SAAS,MAAM,MAAM,MAAM,YAAY,EAAE,SAAS;AACxD,KAAI,OAAO,WAAW,YAAY,CAAC,UAAU,KAAK,OAAO,CACxD,OAAM,IAAI,MAAM,4CAA4C;CAE7D,MAAM,OAAO,MAAM,MAAM,OAAO;CAChC,MAAM,WAAW,MAAM,MAAM,WAAW;CACxC,MAAM,WAAmC,EAAE;AAC3C,KAAI,OAAO,SAAS,YAAY,SAAS,KACxC,MAAK,MAAM,CAAC,SAAS,gBAAgB,OAAO,QAAQ,KAAK,EAAE;AAC1D,MAAI,CAAC,UAAU,KAAK,QAAQ,IAAI,eAAe,SAAS,OAAO,CAAE;EACjE,MAAM,WAAW,MAAM,UAAU,QAAQ;AACzC,MAAI,aAAa,UAAa,MAAM,UAAU,aAAa,KAAK,OAAW;AAC3E,MAAI,OAAO,gBAAgB,YAAY,OAAO,MAAM,KAAK,MAAM,YAAY,CAAC,CAAE;AAC9E,WAAS,WAAW;;AAGtB,KAAI,CAAC,SAAS,QACb,OAAM,IAAI,MAAM,kEAAkE;CAEnF,MAAM,QAAyB;EAAE;EAAU,4BAAW,IAAI,MAAM,EAAC,aAAa;EAAE;AAChF,OAAM,IAAI,kBAAkB,GAAG,CAAC,IAAI,oBAAoB,MAAM;;AAG/D,SAAS,WAAW,OAAwC;CAC3D,MAAM,WAAW,MAAM,OAAO,WAAW;CACzC,MAAM,YAAY,MAAM,OAAO,YAAY;AAC3C,KAAI,OAAO,aAAa,YAAY,aAAa,QAAQ,OAAO,cAAc,SAC7E,QAAO;AAKR,KAAI,OAAO,MAAM,KAAK,MAAM,UAAU,CAAC,CAAE,QAAO;CAChD,MAAM,QAAgC,EAAE;AACxC,MAAK,MAAM,CAAC,SAAS,gBAAgB,OAAO,QAAQ,SAAS,CAC5D,KACC,UAAU,KAAK,QAAQ,IACvB,OAAO,gBAAgB,YACvB,CAAC,OAAO,MAAM,KAAK,MAAM,YAAY,CAAC,CAEtC,OAAM,WAAW;AAGnB,QAAO;EAAE,UAAU;EAAO;EAAW;;;AAItC,SAAS,eACR,UACA,KACA,cACgB;CAChB,IAAI,SAAwB;AAC5B,MAAK,MAAM,CAAC,SAAS,gBAAgB,OAAO,QAAQ,SAAS,EAAE;AAC9D,MAAI,IAAI,SAAS,GAAG,KAAK,MAAM,YAAY,GAAG,aAAc;AAC5D,MAAI,CAAC,UAAU,eAAe,SAAS,OAAO,CAAE,UAAS;;AAE1D,QAAO;;;;;;AAOR,SAAgB,yBACf,QACS;AAET,QAAO,sBADK,OAAO,WAAW,WAAW,QAAQ,oBAAoB,WAClC,4BAA4B;;;;;;;;AAShE,eAAsB,uBACrB,IACA,SACuC;CACvC,MAAM,UAAU,SAAS,WAAW;AACpC,KAAI,SAAS,YAAY,MACxB,QAAO;EACN,SAAS;EACT,MAAM;GAAE;GAAS,QAAQ;GAAM,iBAAiB;GAAO,WAAW;GAAM;EACxE;AAGF,KAAI;EACH,MAAM,OAAO,IAAI,kBAAkB,GAAG;EACtC,MAAM,QAAQ,WAAW,MAAM,KAAK,IAAI,mBAAmB,CAAC;EAE5D,MAAM,MAAM,SAAS,uBAAO,IAAI,MAAM;EACtC,MAAM,gBACJ,SAAS,4BAA4B,yBAAyB,OAAU,IAAI;AAI9E,OAHc,CAAC,SAAS,IAAI,SAAS,GAAG,KAAK,MAAM,MAAM,UAAU,IAAI,sBAG1D,YAAY,MACxB,OAAM,YAAY;AACjB,OAAI;AACH,UAAM,uBAAuB,GAAG;YACxB,OAAO;AACf,YAAQ,KAAK,2CAA2C,MAAM;AAE9D,QADoB,WAAW,MAAM,KAAK,IAAI,mBAAmB,CAAC,EACjD,cAAc,OAAO,UAAW;IACjD,MAAM,aAA8B;KACnC,UAAU,OAAO,YAAY,EAAE;KAC/B,4BAAW,IAAI,MAAM,EAAC,aAAa;KACnC;AACD,UAAM,KAAK,IAAI,oBAAoB,WAAW;;IAE9C;EAGH,MAAM,SAAS,QAAQ,eAAe,MAAM,UAAU,KAAK,aAAa,GAAG;AAC3E,SAAO;GACN,SAAS;GACT,MAAM;IACL;IACA;IACA,iBAAiB,SAAS,eAAe,QAAQ,QAAQ,GAAG;IAC5D,WAAW,OAAO,aAAa;IAC/B;GACD;UACO,OAAO;AACf,UAAQ,MAAM,sCAAsC,MAAM;AAC1D,SAAO;GACN,SAAS;GACT,OAAO;IAAE,MAAM,UAAU;IAAoB,SAAS;IAAgC;GACtF"}

package/dist/upload-attempts-DPFC4COv.mjs

@@ -0,0 +1,32 @@
+//#region src/media/upload-attempts.ts
+async function removeUploadAttempt(storage, repo, storageKey, options = {}) {
+	try {
+		if (!await repo.claimUploadAttemptForCleanup(storageKey)) {
+			if (await repo.hasUploadAttempt(storageKey) || !options.allowUntracked) return false;
+		}
+	} catch (error) {
+		console.error("[media] upload cleanup claim failed:", error);
+		return false;
+	}
+	try {
+		await storage.delete(storageKey);
+	} catch (error) {
+		console.error("[media] upload cleanup failed:", error);
+		try {
+			await repo.deferUploadAttemptCleanup(storageKey);
+		} catch (deferError) {
+			console.error("[media] upload cleanup deferral failed:", deferError);
+		}
+		return false;
+	}
+	try {
+		await repo.deleteUploadAttempt(storageKey);
+	} catch (error) {
+		console.error("[media] upload cleanup record deletion failed:", error);
+	}
+	return true;
+}
+
+//#endregion
+export { removeUploadAttempt as t };
+//# sourceMappingURL=upload-attempts-DPFC4COv.mjs.map

package/dist/upload-attempts-DPFC4COv.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-attempts-DPFC4COv.mjs","names":[],"sources":["../src/media/upload-attempts.ts"],"sourcesContent":["import type { MediaRepository } from \"../database/repositories/media.js\";\nimport type { Storage } from \"../storage/types.js\";\n\nexport async function removeUploadAttempt(\n\tstorage: Storage,\n\trepo: MediaRepository,\n\tstorageKey: string,\n\toptions: { allowUntracked?: boolean } = {},\n): Promise<boolean> {\n\ttry {\n\t\tif (!(await repo.claimUploadAttemptForCleanup(storageKey))) {\n\t\t\tconst tracked = await repo.hasUploadAttempt(storageKey);\n\t\t\tif (tracked || !options.allowUntracked) return false;\n\t\t}\n\t} catch (error) {\n\t\tconsole.error(\"[media] upload cleanup claim failed:\", error);\n\t\treturn false;\n\t}\n\n\ttry {\n\t\tawait storage.delete(storageKey);\n\t} catch (error) {\n\t\tconsole.error(\"[media] upload cleanup failed:\", error);\n\t\ttry {\n\t\t\tawait repo.deferUploadAttemptCleanup(storageKey);\n\t\t} catch (deferError) {\n\t\t\tconsole.error(\"[media] upload cleanup deferral failed:\", deferError);\n\t\t}\n\t\treturn false;\n\t}\n\n\ttry {\n\t\tawait repo.deleteUploadAttempt(storageKey);\n\t} catch (error) {\n\t\tconsole.error(\"[media] upload cleanup record deletion failed:\", error);\n\t}\n\treturn true;\n}\n"],"mappings":";AAGA,eAAsB,oBACrB,SACA,MACA,YACA,UAAwC,EAAE,EACvB;AACnB,KAAI;AACH,MAAI,CAAE,MAAM,KAAK,6BAA6B,WAAW,EAExD;OADgB,MAAM,KAAK,iBAAiB,WAAW,IACxC,CAAC,QAAQ,eAAgB,QAAO;;UAExC,OAAO;AACf,UAAQ,MAAM,wCAAwC,MAAM;AAC5D,SAAO;;AAGR,KAAI;AACH,QAAM,QAAQ,OAAO,WAAW;UACxB,OAAO;AACf,UAAQ,MAAM,kCAAkC,MAAM;AACtD,MAAI;AACH,SAAM,KAAK,0BAA0B,WAAW;WACxC,YAAY;AACpB,WAAQ,MAAM,2CAA2C,WAAW;;AAErE,SAAO;;AAGR,KAAI;AACH,QAAM,KAAK,oBAAoB,WAAW;UAClC,OAAO;AACf,UAAQ,MAAM,kDAAkD,MAAM;;AAEvE,QAAO"}