@wordrhyme/plugin 0.1.0-alpha.5

package/dist/types-8P7XyoyQ.d.ts

@@ -0,0 +1,1599 @@
+import { GlobalizationState } from './globalization.js';
+import { R as RegistryReleaseEnvelope, a as RegistrySignature, b as RegistryCatalogPageEnvelope } from './release-CyapqJ3z.js';
+import { DateRangeResolver } from './time.js';
+
+/**
+ * Plugin Context - Injected into plugin handlers
+ *
+ * All plugin code receives this context, which provides:
+ * - Identity (pluginId, organizationId, userId)
+ * - Capabilities (logger, db, permissions, queue, notifications, settings, media, storage)
+ * - Observability (metrics, trace)
+ */
+
+interface PluginContext {
+    /** Plugin ID from manifest */
+    pluginId: string;
+    /** Current organization ID (from request context) */
+    organizationId?: string | undefined;
+    /** Original organization ID before any infrastructure policy context swap */
+    originalOrganizationId?: string | undefined;
+    /** Current user ID (from request context) */
+    userId?: string | undefined;
+    /** Current user profile snapshot from request context */
+    user?: {
+        id: string;
+        name?: string;
+        email?: string;
+    } | undefined;
+    /** Request/correlation ID from the host runtime */
+    requestId?: string | undefined;
+    /** Current user's primary role and expanded role set */
+    userRole?: string | undefined;
+    userRoles?: string[] | undefined;
+    /** Current team context for team-level permissions */
+    currentTeamId?: string | undefined;
+    /** Locale/timezone resolved by the host runtime */
+    locale?: string | undefined;
+    timezone?: string | undefined;
+    /** Client-reported timezone; business logic must not treat it as authoritative. */
+    clientTimeZone?: string | undefined;
+    /** Host-provided calendar-date resolver for shared query infrastructure. */
+    resolveDateRange?: DateRangeResolver | undefined;
+    /** Host-provided actor metadata; runtime plugin contexts resolve to `plugin`. */
+    actorType?: "plugin" | undefined;
+    apiTokenId?: string | undefined;
+    apiTokenScopes?: string[] | undefined;
+    isSystemContext?: false | undefined;
+    principal?: {
+        kind: "plugin";
+        id: string;
+        pluginId: string;
+    } | undefined;
+    invoker?: string | undefined;
+    /** Scoped logger */
+    logger: PluginLogger;
+    /**
+     * Drizzle-compatible ScopedDb bound to the plugin's private table prefix.
+     * Automatically enforces LBAC, tenant filtering, auditing, and plugin table isolation.
+     */
+    db: PluginScopedDb;
+    /** Host-only Marketplace execution boundary for platform reads and Publisher callbacks. */
+    marketplaceOrganizationExecution?: MarketplaceOrganizationExecutionV1 | undefined;
+    /** Authenticated upload actor supplied by the Host; never derived from request payloads. */
+    marketplacePublishActor?: MarketplacePublishActor | undefined;
+    /** Host-only Registry signing boundary. The private key never enters plugin settings or storage. */
+    marketplaceRegistrySigner?: MarketplaceRegistrySigningCapability | undefined;
+    /** Host-configured public Marketplace origin; null means production configuration is missing. */
+    marketplaceRegistryBaseUrl?: string | null | undefined;
+    /** Host-mediated Core organization creation for explicitly trusted plugins. */
+    organizationProvisioning?: PluginOrganizationProvisioningCapability | undefined;
+    /**
+     * Shared database transaction for synchronous cross-plugin pipe calls.
+     *
+     * When present, plugin code may use this transaction to participate in the
+     * caller's outer SQL transaction instead of opening an independent one.
+     */
+    tx?: any;
+    /** Permission capability */
+    permissions: PluginPermissionCapability;
+    /** Public plugin API caller alias over the host's pluginApis route tree */
+    plugins?: PluginApisCapability | undefined;
+    /** Queue capability (for async job processing) */
+    queue?: PluginQueueCapability | undefined;
+    /** Notification capability (for sending notifications) */
+    notifications?: PluginNotificationCapability | undefined;
+    /** Settings capability (for plugin configuration) */
+    settings: PluginSettingsCapability;
+    /** Currency capability (for effective organization currency/rate access) */
+    currency?: PluginCurrencyCapability | undefined;
+    /** Media capability (for unified file and asset management) */
+    media?: PluginMediaCapability | undefined;
+    /** Storage capability (for registering custom storage providers) */
+    storage?: PluginStorageCapability | undefined;
+    /** Opaque plugin artifact storage for explicitly approved first-party workflows. */
+    artifacts?: PluginArtifactCapability | undefined;
+    /** Metrics capability (for recording usage metrics) */
+    metrics?: PluginMetricsCapability | undefined;
+    /** Trace capability (for accessing trace context) */
+    trace?: PluginTraceCapability | undefined;
+    /** Hook capability (for registering hook handlers) */
+    hooks?: PluginHookCapability | undefined;
+    /** Usage capability (for explicit billing consumption in dynamic scenarios) */
+    usage?: PluginUsageCapability | undefined;
+    /** External authorization capability for tenant platform/API connections */
+    eAuth?: PluginEAuthCapability | undefined;
+    /** Entity extension capability (Core-mediated extension value persistence) */
+    entityExtensions?: PluginEntityExtensionCapability | undefined;
+    /** Generic AutoCrud extension provider injected by the host runtime. */
+    crudExtensions?: PluginCrudExtensionsCapability | undefined;
+    /** Public web surface capability injected for plugin-owned web route handlers. */
+    web?: PluginWebCapability | undefined;
+}
+/**
+ * Public SDK shape for the Host-provided Drizzle-compatible database.
+ *
+ * The concrete type deliberately remains structural so plugin packages do not
+ * depend on Server internals. Runtime enforcement is provided by ScopedDb.
+ */
+interface PluginScopedDb {
+    readonly query: any;
+    /** @deprecated Prefer the v2 object-style `query` API. */
+    readonly _query: any;
+    select(...args: any[]): any;
+    selectDistinct(...args: any[]): any;
+    selectDistinctOn(...args: any[]): any;
+    insert(table: any): any;
+    update(table: any): any;
+    delete(table: any, options?: {
+        softDelete?: false;
+    }): any;
+    $count(source: any, filters?: any): PromiseLike<number> & {
+        execute(placeholderValues?: Record<string, unknown>): Promise<number>;
+    };
+    transaction<T>(callback: (tx: PluginScopedDb) => Promise<T>, options?: unknown): Promise<T>;
+    forOrganization<T>(organizationId: string, callback: (db: PluginScopedDb) => Promise<T> | T): Promise<T>;
+}
+interface ReadonlyPluginScopedDb {
+    readonly query: any;
+    /** @deprecated Prefer the v2 object-style `query` API. */
+    readonly _query: any;
+    select(...args: any[]): any;
+    selectDistinct(...args: any[]): any;
+    selectDistinctOn(...args: any[]): any;
+    $count(source: any, filters?: any): PromiseLike<number> & {
+        execute(placeholderValues?: Record<string, unknown>): Promise<number>;
+    };
+}
+type MarketplacePlatformReadAction = "route" | "review-list" | "attestation-target" | "catalog";
+type MarketplacePublisherAction = "publish" | "review-command" | "release-attest" | "profile-manage";
+type MarketplaceExecutionErrorCode = "MARKETPLACE_EXECUTION_ACTION_DENIED" | "MARKETPLACE_PUBLISHER_UNAVAILABLE";
+type MarketplaceExecutionFailureCode = MarketplaceExecutionErrorCode | "PLUGIN_DB_SCOPE_EXPIRED";
+declare const MARKETPLACE_PUBLISH_AUTH_METHODS: readonly ["portal-session", "scoped-api-key"];
+type MarketplacePublishAuthMethod = (typeof MARKETPLACE_PUBLISH_AUTH_METHODS)[number];
+interface MarketplacePublishActor {
+    actorId: string;
+    authenticationMethod: MarketplacePublishAuthMethod;
+    authenticatedAt: string;
+    credentialId?: string | undefined;
+}
+interface MarketplaceRegistrySigningCapability {
+    /** Serialize Catalog generations and Release projection changes on the Registry database clock. */
+    withCatalogGeneration<T>(run: (generatedAt: string) => Promise<T>): Promise<T>;
+    sign(targetId: string, envelope: RegistryReleaseEnvelope): Promise<RegistrySignature>;
+    signCatalog(envelope: RegistryCatalogPageEnvelope): Promise<RegistrySignature>;
+}
+interface MarketplaceAttestationTargetV1 {
+    organizationId: string;
+    targetId: string;
+    envelopeSha256: string;
+}
+declare const publisherCandidateBrand: unique symbol;
+interface OpaquePublisherCandidateV1 {
+    readonly [publisherCandidateBrand]: true;
+}
+interface MarketplaceOrganizationExecutionV1 {
+    withPlatformRead(ctx: PluginContext, action: "route", run: (db: ReadonlyPluginScopedDb) => Promise<string | undefined>): Promise<OpaquePublisherCandidateV1 | undefined>;
+    withPlatformRead(ctx: PluginContext, action: "review-list", run: (db: ReadonlyPluginScopedDb) => Promise<string | undefined>): Promise<OpaquePublisherCandidateV1 | undefined>;
+    withPlatformRead(ctx: PluginContext, action: "attestation-target", run: (db: ReadonlyPluginScopedDb) => Promise<MarketplaceAttestationTargetV1 | undefined>): Promise<OpaquePublisherCandidateV1 | undefined>;
+    withPlatformRead<T>(ctx: PluginContext, action: Exclude<MarketplacePlatformReadAction, "route" | "attestation-target">, run: (db: ReadonlyPluginScopedDb) => Promise<T>): Promise<T>;
+    withPublisher<T>(ctx: PluginContext, binding: "current" | OpaquePublisherCandidateV1, action: MarketplacePublisherAction, run: (db: PluginScopedDb) => Promise<T>): Promise<T>;
+}
+interface PluginOrganizationProvisioningCapability {
+    provision(input: {
+        name: string;
+        idempotencyKey: string;
+        transaction: PluginScopedDb;
+        metadata?: Record<string, string | number | boolean | null> | undefined;
+    }): Promise<{
+        id: string;
+        name: string;
+        slug: string;
+        status: "created" | "existing";
+    }>;
+}
+/**
+ * Framework-neutral request envelope for plugin-owned public web routes.
+ *
+ * This contract intentionally avoids Next.js, Pages Router, App Router, RSC,
+ * TanStack Router, or any other host-specific request type. Host adapters
+ * translate their native request shape into this envelope before invoking a
+ * plugin web handler.
+ */
+interface WebPluginRouteRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    cookies: Record<string, string>;
+    path: string;
+    query: Record<string, string | string[]>;
+    organizationId: string;
+    locale?: string | undefined;
+    direction?: GlobalizationState["direction"] | undefined;
+    currency?: string | undefined;
+    timezone?: string | undefined;
+    globalization?: GlobalizationState | undefined;
+    tenant?: WebPluginTenantInfo | undefined;
+    site?: WebPluginSiteInfo | undefined;
+    renderSlot?: WebSlotRenderer | undefined;
+}
+interface WebSlotRenderRequest {
+    slot: string;
+    props?: Record<string, unknown> | undefined;
+    targetPluginId?: string | undefined;
+    routeId?: string | undefined;
+}
+interface WebSlotRenderOptions {
+    slot: string;
+    props?: Record<string, unknown> | undefined;
+    ownerPluginId?: string | undefined;
+    routeId?: string | undefined;
+}
+interface WebSlotExtensionQuery {
+    id: string;
+    procedure: string;
+    inputFrom?: "slotProps" | "static" | undefined;
+    staticInput?: Record<string, unknown> | undefined;
+}
+interface WebSlotQueryResult {
+    id: string;
+    procedure: string;
+    data?: unknown;
+    error?: string | undefined;
+}
+interface WebSlotRemoteExtension {
+    id: string;
+    pluginId: string;
+    label?: string | undefined;
+    component: string;
+    slot: string;
+    targetPluginId: string;
+    props: Record<string, unknown>;
+    remoteEntry: string;
+    devRemoteEntry?: string | undefined;
+    moduleName?: string | undefined;
+    expose?: string | undefined;
+    order?: number | undefined;
+    queries?: WebSlotExtensionQuery[] | undefined;
+    queryResults?: WebSlotQueryResult[] | undefined;
+}
+interface WebSlotRenderResult {
+    html: string;
+    extensions?: WebSlotRemoteExtension[] | undefined;
+    head?: WebPluginHead | undefined;
+    initialData?: Record<string, unknown> | undefined;
+    clientEntries?: string[] | undefined;
+}
+type WebSlotRenderer = (request: WebSlotRenderRequest) => WebSlotRenderResult | Promise<WebSlotRenderResult>;
+interface PluginWebCapability {
+    renderSlot(options: WebSlotRenderOptions): WebSlotRenderResult | Promise<WebSlotRenderResult>;
+}
+interface WebPluginTenantInfo {
+    organizationId: string;
+    name: string;
+    slug?: string | undefined;
+    logo?: string | null | undefined;
+}
+interface WebPluginSiteInfo {
+    mode: "custom-domain" | "platform-subdomain" | "platform-path" | "internal-override";
+    basePath: string;
+    publicOrigin?: string | undefined;
+    host?: string | undefined;
+}
+interface WebPluginHeadLink {
+    rel: string;
+    href: string;
+    as?: string | undefined;
+    type?: string | undefined;
+}
+interface WebPluginHead {
+    title?: string | undefined;
+    description?: string | undefined;
+    meta?: Record<string, string> | undefined;
+    links?: WebPluginHeadLink[] | undefined;
+}
+/**
+ * Framework-neutral SSR result returned by a plugin web handler.
+ *
+ * Redirects are represented as a 3xx status plus a `location` header so every
+ * host adapter can map them into its own redirect primitive.
+ */
+interface WebPluginRouteResult {
+    status: number;
+    headers?: Record<string, string> | undefined;
+    head?: WebPluginHead | undefined;
+    html?: string | undefined;
+    initialData?: unknown;
+    clientEntry?: string | undefined;
+    clientEntries?: string[] | undefined;
+    slotExtensions?: WebSlotRemoteExtension[] | undefined;
+    routeId?: string | undefined;
+    globalization?: GlobalizationState | undefined;
+    site?: WebPluginSiteInfo | undefined;
+}
+type WebPluginRouteHandler<TContext extends PluginContext = PluginContext> = (request: WebPluginRouteRequest, context: TContext) => WebPluginRouteResult | Promise<WebPluginRouteResult>;
+/**
+ * Plugin Permission Definition (CASL format)
+ *
+ * Defines a permission that a plugin registers for use in the CASL permission system.
+ * Plugins use this to declare what permissions they provide.
+ *
+ * @example
+ * // Simple permission (manage is default action)
+ * { subject: 'settings' }
+ *
+ * // Permission with specific actions
+ * { subject: 'analytics', actions: ['read', 'export'] }
+ *
+ * // Permission with field-level access
+ * { subject: 'report', actions: ['read'], fields: ['summary', 'chart'] }
+ */
+interface PluginPermissionDef {
+    /** Subject name (will be prefixed with plugin:{pluginId}:) */
+    subject: string;
+    /** Actions supported (default: ['manage']) */
+    actions?: string[];
+    /** Field-level restrictions (default: null = all fields) */
+    fields?: string[] | null;
+    /** Human-readable description for Admin UI */
+    description?: string;
+}
+/**
+ * Plugin Logger - Scoped logging interface
+ *
+ * Per OBSERVABILITY_GOVERNANCE §3.3:
+ * - info, warn, error: Always available
+ * - debug: Optional, only available when explicitly enabled by tenant admin
+ */
+interface PluginLogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Debug logging - only available when debug mode is enabled by tenant admin.
+     * Calls are silently ignored when debug mode is disabled.
+     */
+    debug?(message: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Plugin Permission Capability - Permission checking interface
+ *
+ * All permission checks are scoped to:
+ * - Permissions declared in the plugin manifest
+ * - Permissions granted to the current user
+ */
+interface PluginPermissionCapability {
+    /**
+     * Check if current user has a capability
+     * @param capability - Capability in format `resource:action:scope`
+     * @param context - Optional context override for checks that resolve tenant or role after request setup
+     * @returns true if allowed, false if denied
+     */
+    can(capability: string, context?: PluginPermissionCheckContext): Promise<boolean>;
+    /**
+     * Require a capability - throws if denied
+     * @param capability - Capability to require
+     * @param context - Optional context override for checks that resolve tenant or role after request setup
+     * @throws PermissionDeniedError if permission denied
+     */
+    require(capability: string, context?: PluginPermissionCheckContext): Promise<void>;
+    /**
+     * Check if plugin has access to a capability
+     * (Plugin must have declared this capability in manifest)
+     * @param capability - Capability to check
+     */
+    hasDeclared(capability: string): boolean;
+}
+interface PluginPermissionCheckContext {
+    requestId?: string | undefined;
+    organizationId?: string | undefined;
+    userId?: string | undefined;
+    userRole?: string | undefined;
+    userRoles?: string[] | undefined;
+    currentTeamId?: string | undefined;
+    actorType?: PluginContext["actorType"] | undefined;
+    apiTokenId?: string | undefined;
+    apiTokenScopes?: string[] | undefined;
+}
+type PluginApisCapability = Record<string, any>;
+type EAuthModel = "oauth_refresh" | "api_key" | "hmac" | "token" | "amazon_spapi";
+type EAuthStatus = "ok" | "reauth" | "retry";
+type EAuthUse = "products" | "orders" | "fulfillment" | "test" | string;
+type EAuthTokenResult = {
+    status: "ok";
+    accessToken: string;
+    accessTokenExpiresAt?: Date | undefined;
+} | {
+    status: "reauth";
+    code: string;
+    message: string;
+} | {
+    status: "retry";
+    code: string;
+    message: string;
+    retryAt?: Date | undefined;
+};
+interface EAuthRefreshInput {
+    refreshToken: string;
+    accountId: string;
+    meta?: Record<string, unknown> | undefined;
+}
+interface EAuthRefreshResult {
+    accessToken: string;
+    refreshToken?: string | undefined;
+    accessTokenExpiresAt?: Date | undefined;
+    refreshTokenExpiresAt?: Date | undefined;
+    scope?: string | undefined;
+    meta?: Record<string, unknown> | undefined;
+}
+interface EAuthProvider {
+    refresh(input: EAuthRefreshInput): Promise<EAuthRefreshResult>;
+}
+interface EAuthUpsertInput {
+    id?: string | undefined;
+    model: EAuthModel;
+    connectionId: string;
+    accountId: string;
+    accessToken?: string | undefined;
+    refreshToken?: string | undefined;
+    accessTokenExpiresAt?: Date | undefined;
+    refreshTokenExpiresAt?: Date | undefined;
+    scope?: string | undefined;
+    status?: EAuthStatus | undefined;
+    meta?: Record<string, unknown> | undefined;
+}
+interface PluginEAuthCapability {
+    registerProvider(provider: EAuthProvider): void;
+    upsert(input: EAuthUpsertInput): Promise<{
+        id: string;
+    }>;
+    token(input: {
+        eauthId: string;
+        use?: EAuthUse | undefined;
+    }): Promise<EAuthTokenResult>;
+}
+interface PluginCurrencyCapability {
+    /**
+     * Get enabled currencies with effective current rates in the current tenant context.
+     *
+     * The host resolves platform-vs-tenant ownership according to infra policy.
+     */
+    getEffectiveEnabledCurrencies(options?: {
+        organizationId?: string | undefined;
+    }): Promise<Array<{
+        code: string;
+        nameI18n?: Record<string, string> | null;
+        symbol?: string | null;
+        decimalDigits?: number | null;
+        isBase?: boolean;
+        currentRate?: string | null;
+    }>>;
+    /**
+     * Get the effective current rate for a currency code in the current tenant context.
+     *
+     * The host resolves platform-vs-tenant ownership according to infra policy.
+     */
+    getEffectiveCurrentRate(code: string, options?: {
+        organizationId?: string | undefined;
+    }): Promise<string | null>;
+    /**
+     * Convenience helper for CNY to USD conversions.
+     * Returns the effective CNY → USD rate, or null when not configured.
+     */
+    getEffectiveCnyToUsdRate(options?: {
+        organizationId?: string | undefined;
+    }): Promise<number | null>;
+}
+interface PluginEntityExtensionFilter {
+    id: string;
+    value: string | string[];
+    variant: string;
+    operator: string;
+    filterId?: string | undefined;
+}
+interface PluginEntityExtensionCapability {
+    /**
+     * Save extension values for a target plugin CRUD row through the platform contract.
+     *
+     * Values are keyed by manifest field name. The platform resolves each
+     * field owner from enabled plugin manifests, invokes owner save handlers,
+     * and refreshes Core's query projection.
+     */
+    saveValues(options: {
+        /** Globally unique extension target id, e.g. "com.example.shop.stores". */
+        id: string;
+        entityId: string;
+        ext?: Record<string, unknown> | null | undefined;
+        tx?: unknown;
+    }): Promise<void>;
+    /**
+     * Match target CRUD row ids from Core's query projection for extension-field filters.
+     *
+     * This is a Core-mediated read model query. Plugins receive row ids only;
+     * plugin-owned semantic extension values stay in the owner plugin's private
+     * storage and are not exposed through this capability.
+     */
+    matchEntityIds(options: {
+        /** Globally unique extension target id, e.g. "com.example.shop.stores". */
+        id: string;
+        filters: PluginEntityExtensionFilter[];
+        joinOperator?: "and" | "or" | undefined;
+        limit?: number | undefined;
+    }): Promise<string[]>;
+    /**
+     * Match target CRUD row ids by global search over fields whose manifest
+     * declaration has `search: true`.
+     */
+    searchEntityIds(options: {
+        /** Globally unique extension target id, e.g. "com.example.shop.stores". */
+        id: string;
+        search: string;
+        limit?: number | undefined;
+    }): Promise<string[]>;
+}
+interface PluginCrudExtensionFilter {
+    id: string;
+    value: string | string[];
+    variant: string;
+    operator: string;
+    filterId?: string | undefined;
+}
+interface PluginCrudExtensionMetadata {
+    schema?: unknown;
+    fields?: Record<string, unknown>;
+    errors?: string[] | undefined;
+}
+interface PluginCrudExtensionsCapability {
+    getMetadata?(options: {
+        /** Globally unique CRUD target id, e.g. "com.example.shop.stores". */
+        id: string;
+    }): Promise<PluginCrudExtensionMetadata>;
+    saveExtraValues(options: {
+        /** Globally unique CRUD target id, e.g. "com.example.shop.stores". */
+        id: string;
+        entityId: string;
+        rawValues: Record<string, unknown>;
+        baseValues: Record<string, unknown>;
+        extraValues: Record<string, unknown>;
+        tx?: unknown;
+    }): Promise<void>;
+    readProjection(options: {
+        /** Globally unique CRUD target id, e.g. "com.example.shop.stores". */
+        id: string;
+        entityIds: string[];
+        fields?: string[] | undefined;
+    }): Promise<Record<string, Record<string, unknown>>>;
+    matchEntityIds(options: {
+        /** Globally unique CRUD target id, e.g. "com.example.shop.stores". */
+        id: string;
+        filters: PluginCrudExtensionFilter[];
+        joinOperator?: "and" | "or" | undefined;
+        limit?: number | undefined;
+    }): Promise<string[]>;
+    searchEntityIds(options: {
+        /** Globally unique CRUD target id, e.g. "com.example.shop.stores". */
+        id: string;
+        search: string;
+        limit?: number | undefined;
+    }): Promise<string[]>;
+}
+/**
+ * Plugin Queue Capability - Async job processing
+ *
+ * All jobs are namespaced with plugin_{pluginId}_{jobName}
+ * Subject to rate limits and payload size restrictions.
+ */
+interface PluginQueueCapability {
+    /**
+     * Add a job to the queue
+     * @param jobName - Job name (will be prefixed with plugin_{pluginId}_)
+     * @param data - Job payload (must be JSON-serializable, max 64KB)
+     * @param options - Job options
+     */
+    addJob<T = unknown>(jobName: string, data: T, options?: PluginJobOptions): Promise<{
+        jobId: string;
+    }>;
+    /**
+     * Get job status
+     * @param jobId - Job ID returned from addJob
+     */
+    getJobStatus(jobId: string): Promise<PluginJobStatus>;
+    /**
+     * Cancel a pending job
+     * @param jobId - Job ID to cancel
+     */
+    cancelJob(jobId: string): Promise<boolean>;
+}
+/**
+ * Plugin Job Options
+ */
+interface PluginJobOptions {
+    /** Job priority: 'low' | 'normal' | 'high' | 'critical' */
+    priority?: "low" | "normal" | "high" | "critical";
+    /** Stable job id for idempotent queueing */
+    jobId?: string;
+    /** Delay in milliseconds before processing */
+    delay?: number;
+    /** Number of retry attempts on failure */
+    attempts?: number;
+    /** Backoff strategy for retries */
+    backoff?: {
+        type: "fixed" | "exponential";
+        delay: number;
+    };
+    /** Remove job after completion */
+    removeOnComplete?: boolean;
+    /** Remove job after failure */
+    removeOnFail?: boolean;
+}
+/**
+ * Plugin Job Status
+ */
+interface PluginJobStatus {
+    id: string;
+    name: string;
+    state: "waiting" | "active" | "completed" | "failed" | "delayed";
+    progress?: number;
+    returnValue?: unknown;
+    failedReason?: string;
+    timestamp: number;
+    processedOn?: number;
+    finishedOn?: number;
+}
+/**
+ * Plugin Notification Capability - Send notifications (Unified Contract v2)
+ *
+ * Plugins can send notifications to users via Core's notification system.
+ * All notifications are tagged with sourcePluginId and validated against manifest.
+ *
+ * Key features:
+ * - Type validation: notification type must be declared in manifest
+ * - Rate limiting: plugin-level and user-level limits enforced
+ * - Aggregation: automatic grouping based on manifest-declared strategy
+ * - Webhooks: async callbacks for click/archive events
+ */
+interface PluginNotificationCapability {
+    /**
+     * Send a notification using the unified contract
+     *
+     * The notification type must be declared in the plugin's manifest.
+     * Rate limits are enforced (plugin: 100/min, 1000/hr, 10000/day; user: 10/min, 50/hr).
+     *
+     * @param params - Notification parameters
+     * @returns Promise resolving to notification ID
+     * @throws PluginNotificationValidationError if type not declared in manifest
+     * @throws RateLimitExceededError if rate limit exceeded
+     * @throws PermissionDeniedError if notification:send not declared
+     */
+    send(params: PluginNotificationSendParams): Promise<PluginNotificationSendResult>;
+    /**
+     * Register a notification template (legacy, still supported)
+     * Templates are namespaced: plugin_{pluginId}_{templateKey}
+     */
+    registerTemplate(template: PluginNotificationTemplate): Promise<void>;
+    /**
+     * Register a notification channel (legacy, still supported)
+     * Channels are namespaced: plugin_{pluginId}_{channelKey}
+     */
+    registerChannel(channel: PluginNotificationChannel): Promise<void>;
+    /**
+     * Subscribe to notification.created events
+     * Allows plugins to enhance notifications (e.g., send to external services)
+     */
+    onNotificationCreated(handler: (event: PluginNotificationEvent) => void | Promise<void>): () => void;
+}
+/**
+ * Plugin Notification Send Parameters (Unified Contract v2)
+ *
+ * Simplified API where plugins declare "intent", platform handles "execution".
+ */
+interface PluginNotificationSendParams {
+    /**
+     * Notification type ID - must match a type declared in manifest.notifications.types
+     * @example "task_reminder", "content_liked"
+     */
+    type: string;
+    /**
+     * Target user ID to receive the notification
+     */
+    userId: string;
+    /**
+     * Actor who triggered the notification (optional)
+     * If not provided, the plugin itself is treated as the actor
+     */
+    actor?: PluginNotificationActor;
+    /**
+     * Target object the notification is about
+     */
+    target: PluginNotificationTarget;
+    /**
+     * Custom data for template rendering
+     * These values are passed to i18n templates as variables
+     */
+    data?: Record<string, unknown>;
+    /**
+     * Locale for i18n (e.g., 'en-US', 'zh-CN')
+     * Falls back to user preference or 'en-US'
+     */
+    locale?: string;
+}
+/**
+ * Notification Actor - who triggered the notification
+ */
+interface PluginNotificationActor {
+    /** Actor ID (user ID or plugin ID) */
+    id: string;
+    /** Actor type */
+    type: "user" | "plugin";
+    /** Display name */
+    name: string;
+    /** Avatar URL (optional) */
+    avatarUrl?: string;
+}
+/**
+ * Notification Target - what the notification is about
+ */
+interface PluginNotificationTarget {
+    /** Target type (e.g., 'post', 'comment', 'task') */
+    type: string;
+    /** Target ID */
+    id: string;
+    /** URL to navigate when notification is clicked */
+    url: string;
+    /** Preview image URL (optional, for rich notifications) */
+    previewImage?: string;
+}
+/**
+ * Plugin Notification Send Result
+ */
+interface PluginNotificationSendResult {
+    /** The created notification ID */
+    notificationId: string;
+}
+/**
+ * Plugin Notification Input (Legacy - use PluginNotificationSendParams instead)
+ * @deprecated Use PluginNotificationSendParams for new implementations
+ */
+interface PluginNotificationInput {
+    /** Target user ID */
+    userId: string;
+    /** Template key (will be prefixed with plugin_{pluginId}_ if not already) */
+    templateKey: string;
+    /** Variables for template interpolation */
+    variables: Record<string, unknown>;
+    /** Notification type */
+    type?: "info" | "success" | "warning" | "error";
+    /** Link to navigate when clicked */
+    link?: string;
+    /** Actor ID (who triggered the notification) */
+    actorId?: string;
+    /** Entity reference */
+    entityId?: string;
+    entityType?: string;
+    /** Grouping key for bundling */
+    groupKey?: string;
+    /** Idempotency key to prevent duplicates */
+    idempotencyKey?: string;
+    /** Priority override */
+    priority?: "low" | "normal" | "high" | "urgent";
+    /** Channel overrides */
+    channels?: string[];
+    /** Locale for i18n */
+    locale?: string;
+}
+/**
+ * Plugin Notification Result (Legacy)
+ * @deprecated Use PluginNotificationSendResult for new implementations
+ */
+interface PluginNotificationResult {
+    notificationId: string;
+    channels: string[];
+    decisionTrace: Array<{
+        channel: string;
+        included: boolean;
+        reason: string;
+    }>;
+}
+/**
+ * Plugin Notification Template
+ */
+interface PluginNotificationTemplate {
+    /** Template key (will be prefixed with plugin_{pluginId}_) */
+    key: string;
+    /** Display name */
+    name: string;
+    /** Description */
+    description?: string;
+    /** i18n title templates */
+    title: Record<string, string>;
+    /** i18n message templates */
+    message: Record<string, string>;
+    /** Variables that can be interpolated */
+    variables?: string[];
+    /** Default channels */
+    defaultChannels?: string[];
+    /** Default priority */
+    priority?: "low" | "normal" | "high" | "urgent";
+}
+/**
+ * Plugin Notification Channel
+ */
+interface PluginNotificationChannel {
+    /** Channel key (will be prefixed with plugin_{pluginId}_) */
+    key: string;
+    /** i18n display name */
+    name: Record<string, string>;
+    /** i18n description */
+    description?: Record<string, string>;
+    /** Icon name */
+    icon?: string;
+    /** User configuration schema (JSON Schema) */
+    configSchema?: Record<string, unknown>;
+}
+/**
+ * Plugin Notification Event (for onNotificationCreated)
+ */
+interface PluginNotificationEvent {
+    notification: {
+        id: string;
+        userId: string;
+        organizationId: string;
+        templateKey?: string;
+        type: string;
+        title: string;
+        message: string;
+        html?: string;
+        link?: string;
+        priority: "low" | "normal" | "high" | "urgent";
+        actorId?: string;
+        entityId?: string;
+        entityType?: string;
+        groupKey?: string;
+        sourcePluginId?: string;
+    };
+    user: {
+        id: string;
+        email?: string;
+        preferences: {
+            enabledChannels: string[];
+            emailFrequency: "instant" | "hourly" | "daily";
+        };
+    };
+    channels: string[];
+}
+/**
+ * Plugin Settings Capability - Configuration management for plugins
+ *
+ * All settings are automatically scoped to the plugin's namespace:
+ * - plugin_global: Plugin-wide settings (shared across all tenants)
+ * - plugin_tenant: Per-tenant plugin settings
+ *
+ * Plugins cannot access Core settings or other plugins' settings.
+ */
+interface PluginSettingsCapability {
+    /**
+     * Get a setting value
+     * Resolution order: plugin_tenant → plugin_global → defaultValue
+     *
+     * @param key - Setting key (without plugin prefix)
+     * @param defaultValue - Default value if not found
+     * @returns The setting value or default
+     */
+    get<T = unknown>(key: string, defaultValue?: T): Promise<T | null>;
+    /**
+     * Set a setting value
+     *
+     * @param key - Setting key (without plugin prefix)
+     * @param value - Value to store
+     * @param options - Additional options
+     */
+    set(key: string, value: unknown, options?: PluginSettingOptions): Promise<void>;
+    /**
+     * Delete a setting
+     *
+     * @param key - Setting key to delete
+     * @param options - Scope options
+     */
+    delete(key: string, options?: {
+        global?: boolean;
+    }): Promise<boolean>;
+    /**
+     * List all settings for the plugin
+     *
+     * @param options - Filter options
+     * @returns Array of settings
+     */
+    list(options?: {
+        global?: boolean;
+        keyPrefix?: string;
+    }): Promise<PluginSettingEntry[]>;
+    /**
+     * Check if a feature flag is enabled for the current context
+     *
+     * @param flagKey - Feature flag key
+     * @returns true if enabled, false otherwise
+     */
+    isFeatureEnabled(flagKey: string): Promise<boolean>;
+}
+/**
+ * Plugin Setting Options
+ */
+interface PluginSettingOptions {
+    /** Store as global (plugin_global) instead of tenant-scoped (plugin_tenant) */
+    global?: boolean;
+    /** Encrypt the value (for sensitive data like API keys) */
+    encrypted?: boolean;
+    /** Description for admin UI */
+    description?: string;
+}
+/**
+ * Plugin Setting Entry (for list operation)
+ */
+interface PluginSettingEntry {
+    key: string;
+    value: unknown;
+    scope: "plugin_global" | "plugin_tenant";
+    encrypted: boolean;
+    description?: string | undefined;
+}
+/**
+ * Plugin Media Capability - Unified file and asset management
+ *
+ * Provides plugins with the ability to upload, manage, and organize media.
+ * Replaces the separate File and Asset capabilities.
+ * All operations are scoped to the current tenant.
+ */
+interface PluginMediaCapability {
+    /**
+     * Upload a media file
+     * @param input - Media upload input
+     * @returns Uploaded media info
+     */
+    upload(input: PluginMediaUploadInput): Promise<PluginMediaInfo>;
+    /**
+     * Get media info by ID
+     * @param mediaId - Media ID
+     * @returns Media info or null if not found
+     */
+    get(mediaId: string): Promise<PluginMediaInfo | null>;
+    /**
+     * Update media metadata
+     * @param mediaId - Media ID
+     * @param data - Update data
+     */
+    update(mediaId: string, data: PluginMediaUpdateData): Promise<PluginMediaInfo>;
+    /**
+     * Download media content
+     * @param mediaId - Media ID
+     * @returns Media content as Buffer
+     */
+    download(mediaId: string): Promise<Buffer>;
+    /**
+     * Get signed URL for media access
+     * @param mediaId - Media ID
+     * @param options - URL options
+     * @returns Signed URL with expiration
+     */
+    getSignedUrl(mediaId: string, options?: {
+        expiresIn?: number;
+    }): Promise<{
+        url: string;
+        expiresIn: number;
+    }>;
+    /**
+     * Get fixed display URL for media access
+     * @param mediaId - Media ID
+     * @param options - Display URL options
+     * @returns Stable application-controlled display URL
+     */
+    getDisplayUrl(mediaId: string, options?: {
+        variant?: string;
+    }): Promise<{
+        url: string;
+        variant: string;
+    }>;
+    /**
+     * Resolve a media reference or legacy signed file URL to a display URL
+     * @param value - Media ID, signed file URL, display URL, or external URL
+     * @param options - Display URL options
+     * @returns Application-controlled display URL when resolvable
+     */
+    resolveAccessUrl(value: string, options?: {
+        variant?: string;
+    }): Promise<{
+        url: string;
+    }>;
+    /**
+     * Delete a media (soft delete)
+     * @param mediaId - Media ID
+     */
+    delete(mediaId: string): Promise<void>;
+    /**
+     * List media with filtering and pagination
+     * @param query - Query options
+     */
+    list(query?: PluginMediaQuery): Promise<PluginPaginatedResult<PluginMediaInfo>>;
+    /**
+     * Get URL for a media variant
+     * @param mediaId - Media ID
+     * @param variant - Variant name (e.g., 'thumbnail', 'medium')
+     */
+    getVariantUrl(mediaId: string, variant: string): Promise<string>;
+    /**
+     * Get all variants for a media
+     * @param mediaId - Media ID
+     */
+    getVariants(mediaId: string): Promise<PluginMediaVariant[]>;
+}
+/**
+ * Plugin Media Upload Input
+ */
+interface PluginMediaUploadInput {
+    /** File content */
+    content: Buffer;
+    /** Original filename */
+    filename: string;
+    /** MIME type */
+    mimeType: string;
+    /** Is publicly accessible */
+    isPublic?: boolean;
+    /** Alt text for accessibility */
+    alt?: string;
+    /** Title */
+    title?: string;
+    /** Tags for organization */
+    tags?: string[];
+    /** Folder path */
+    folderPath?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Plugin Media Info
+ */
+interface PluginMediaInfo {
+    id: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+    isPublic: boolean;
+    alt?: string;
+    title?: string;
+    tags: string[];
+    folderPath?: string;
+    width?: number;
+    height?: number;
+    format?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Plugin Media Update Data
+ */
+interface PluginMediaUpdateData {
+    alt?: string;
+    title?: string;
+    tags?: string[];
+    folderPath?: string;
+}
+/**
+ * Plugin Media Variant
+ */
+interface PluginMediaVariant {
+    name: string;
+    mediaId: string;
+    width?: number;
+    height?: number;
+    format?: string;
+}
+/**
+ * Plugin Media Query
+ */
+interface PluginMediaQuery {
+    /** Filter by MIME type or category (e.g., 'image/*') */
+    mimeType?: string;
+    /** Tag filter */
+    tags?: string[];
+    /** Folder path filter (prefix match) */
+    folderPath?: string;
+    /** Search in filename/alt/title */
+    search?: string;
+    /** Sort field */
+    sortBy?: "createdAt" | "updatedAt" | "filename";
+    /** Sort order */
+    sortOrder?: "asc" | "desc";
+    /** Page number */
+    page?: number;
+    /** Page size */
+    pageSize?: number;
+}
+/** @deprecated Use PluginMediaCapability */
+type PluginFileCapability = {
+    upload(input: PluginFileUploadInput): Promise<PluginFileInfo>;
+    get(fileId: string): Promise<PluginFileInfo | null>;
+    download(fileId: string): Promise<Buffer>;
+    getSignedUrl(fileId: string, options?: {
+        expiresIn?: number;
+    }): Promise<{
+        url: string;
+        expiresIn: number;
+    }>;
+    delete(fileId: string): Promise<void>;
+    list(query?: PluginFileQuery): Promise<PluginPaginatedResult<PluginFileInfo>>;
+};
+/** @deprecated Use PluginMediaUploadInput */
+interface PluginFileUploadInput {
+    content: Buffer;
+    filename: string;
+    mimeType: string;
+    isPublic?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** @deprecated Use PluginMediaInfo */
+interface PluginFileInfo {
+    id: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+    isPublic: boolean;
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** @deprecated Use PluginMediaQuery */
+interface PluginFileQuery {
+    search?: string;
+    mimeType?: string;
+    page?: number;
+    pageSize?: number;
+}
+/** @deprecated Use PluginMediaCapability */
+type PluginAssetCapability = {
+    create(fileId: string, options?: PluginAssetCreateOptions): Promise<PluginAssetInfo>;
+    get(assetId: string): Promise<PluginAssetInfo | null>;
+    update(assetId: string, data: PluginAssetUpdateData): Promise<PluginAssetInfo>;
+    delete(assetId: string): Promise<void>;
+    list(query?: PluginAssetQuery): Promise<PluginPaginatedResult<PluginAssetInfo>>;
+    getVariantUrl(assetId: string, variant: string): Promise<string>;
+    getVariants(assetId: string): Promise<PluginAssetVariant[]>;
+};
+/** @deprecated Use PluginMediaUpdateData */
+interface PluginAssetCreateOptions {
+    type?: "image" | "video" | "document" | "other";
+    alt?: string;
+    title?: string;
+    tags?: string[];
+    folderPath?: string;
+}
+/** @deprecated Use PluginMediaUpdateData */
+interface PluginAssetUpdateData {
+    alt?: string;
+    title?: string;
+    tags?: string[];
+    folderPath?: string;
+}
+/** @deprecated Use PluginMediaInfo */
+interface PluginAssetInfo {
+    id: string;
+    fileId: string;
+    type: "image" | "video" | "document" | "other";
+    alt?: string;
+    title?: string;
+    tags: string[];
+    folderPath?: string;
+    width?: number;
+    height?: number;
+    format?: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** @deprecated Use PluginMediaVariant */
+interface PluginAssetVariant {
+    name: string;
+    fileId: string;
+    width: number;
+    height: number;
+    format: string;
+}
+/** @deprecated Use PluginMediaQuery */
+interface PluginAssetQuery {
+    type?: "image" | "video" | "document" | "other";
+    tags?: string[];
+    folderPath?: string;
+    search?: string;
+    sortBy?: "createdAt" | "updatedAt" | "title";
+    sortOrder?: "asc" | "desc";
+    page?: number;
+    pageSize?: number;
+}
+/**
+ * Plugin Storage Capability - Custom storage provider registration
+ *
+ * Allows plugins to register custom storage providers (e.g., S3, OSS, R2).
+ * Providers registered by plugins are automatically namespaced with plugin ID.
+ */
+interface PluginStorageCapability {
+    /**
+     * Register a custom storage provider
+     * The provider type will be prefixed: plugin_{pluginId}_{type}
+     * @param config - Provider configuration
+     */
+    registerProvider(config: PluginStorageProviderConfig): Promise<void>;
+    /**
+     * List registered storage providers by this plugin
+     */
+    listProviders(): Promise<PluginStorageProviderInfo[]>;
+    /**
+     * Unregister a storage provider
+     * @param type - Provider type (without plugin prefix)
+     */
+    unregisterProvider(type: string): Promise<void>;
+}
+interface PluginArtifactCapability {
+    put(input: {
+        content: Uint8Array;
+        filename: string;
+        mediaType: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        key: string;
+        size: number;
+        sha256: string;
+    }>;
+    get(key: string): Promise<Uint8Array>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * Plugin Storage Provider Config
+ */
+interface PluginStorageProviderConfig {
+    /** Provider type (will be prefixed with plugin_{pluginId}_) */
+    type: string;
+    /** Display name for admin UI */
+    name: string;
+    /** Description */
+    description?: string;
+    /** Configuration schema (JSON Schema) */
+    configSchema: Record<string, unknown>;
+    /** Provider factory function */
+    factory: (config: Record<string, unknown>) => PluginStorageProvider;
+}
+/**
+ * Plugin Storage Provider Info
+ */
+interface PluginStorageProviderInfo {
+    type: string;
+    name: string;
+    description?: string;
+    pluginId: string;
+}
+/**
+ * Plugin Storage Provider Interface
+ * Plugins implementing custom storage must implement this interface.
+ */
+interface PluginStorageProvider {
+    /** Provider type identifier */
+    readonly type: string;
+    /** Upload a file */
+    upload(input: PluginStorageUploadInput): Promise<PluginStorageUploadResult>;
+    /** Download file content */
+    download(key: string): Promise<Buffer>;
+    /** Delete a file */
+    delete(key: string): Promise<void>;
+    /** Check if file exists */
+    exists(key: string): Promise<boolean>;
+    /** Get signed URL */
+    getSignedUrl(key: string, options: {
+        expiresIn: number;
+        operation: "get" | "put";
+        contentType?: string;
+    }): Promise<string>;
+    /** Initiate multipart upload */
+    initiateMultipartUpload(key: string): Promise<string>;
+    /** Upload a part */
+    uploadPart(uploadId: string, partNumber: number, body: Buffer): Promise<{
+        partNumber: number;
+        etag: string;
+    }>;
+    /** Complete multipart upload */
+    completeMultipartUpload(uploadId: string, parts: Array<{
+        partNumber: number;
+        etag: string;
+    }>): Promise<void>;
+    /** Abort multipart upload */
+    abortMultipartUpload(uploadId: string): Promise<void>;
+}
+/**
+ * Plugin Storage Upload Input
+ */
+interface PluginStorageUploadInput {
+    key: string;
+    body: Buffer;
+    contentType: string;
+    metadata?: Record<string, string>;
+}
+/**
+ * Plugin Storage Upload Result
+ */
+interface PluginStorageUploadResult {
+    key: string;
+    size: number;
+    etag?: string;
+}
+/**
+ * Generic paginated result
+ */
+interface PluginPaginatedResult<T> {
+    items: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}
+/**
+ * Allowed labels for plugin metrics
+ *
+ * Per OBSERVABILITY_GOVERNANCE §4.1:
+ * Only these labels are allowed to prevent cardinality explosion
+ */
+type PluginMetricsAllowedLabels = {
+    model?: string;
+    type?: string;
+    status?: "success" | "failure";
+};
+/**
+ * Plugin Metrics Capability - Usage metrics recording
+ *
+ * Per OBSERVABILITY_GOVERNANCE §4.1:
+ * - Only increment() for discrete event counters
+ * - No histogram/gauge/observe/set methods
+ * - Labels are restricted to a whitelist
+ */
+interface PluginMetricsCapability {
+    /**
+     * Increment a counter metric
+     *
+     * @param name - Metric name (will be prefixed with plugin_)
+     * @param labels - Optional labels (whitelist enforced: model, type, status)
+     * @param value - Increment value (default: 1)
+     *
+     * @example
+     * ctx.metrics.increment('content_generated', { model: 'gpt-4', status: 'success' });
+     */
+    increment(name: string, labels?: PluginMetricsAllowedLabels, value?: number): void;
+}
+/**
+ * Plugin Trace Capability - Read-only trace context access
+ *
+ * Per OBSERVABILITY_GOVERNANCE §5:
+ * - Plugins can only read trace context
+ * - Plugins cannot create spans or modify trace context
+ */
+interface PluginTraceCapability {
+    /**
+     * Get the current trace ID (W3C format, 32 hex chars)
+     * @returns The trace ID or undefined if not available
+     */
+    getTraceId(): string | undefined;
+    /**
+     * Get the current span ID (16 hex chars)
+     * @returns The span ID or undefined if not available
+     */
+    getSpanId(): string | undefined;
+}
+/**
+ * Hook Priority Enum
+ * Controls execution order within a hook
+ */
+declare enum HookPriority {
+    EARLIEST = 0,// System-level, plugins should not use
+    EARLY = 25,// Plugins needing early execution
+    NORMAL = 50,// Default priority
+    LATE = 75,// Plugins needing late execution
+    LATEST = 100
+}
+/**
+ * Hook Handler Options
+ */
+interface HookHandlerOptions {
+    /** Handler priority (default: NORMAL) */
+    priority?: HookPriority;
+    /** Handler timeout in ms (default: 5000) */
+    timeout?: number;
+}
+/**
+ * Plugin Hook Capability - Register hook handlers
+ *
+ * Plugins can register handlers for Core-defined hooks to:
+ * - Actions: Perform async side-effects (logging, notifications, external sync)
+ * - Filters: Transform data in the pipeline (validation, enrichment, masking)
+ *
+ * Per EVENT_HOOK_GOVERNANCE (Frozen v1):
+ * - Plugins CANNOT block Core execution (except via HookAbortError in filters)
+ * - Plugins CANNOT access other plugins' handlers
+ */
+/**
+ * Hook Event Map — Extensible type registry for TypeScript autocompletion
+ *
+ * Plugins can augment this interface to declare their hooks:
+ *
+ * ```typescript
+ * // plugins/crm/src/shared/hook-types.ts
+ * declare module '@wordrhyme/plugin' {
+ *     interface HookEventMap {
+ *         'crm.customer.promoted': { customerId: string; organizationId: string };
+ *         'crm.customer.beforeCreate': { name: string; organizationId: string };
+ *         'crm.createProspect': { name: string; organizationId: string; id?: string; status?: string };
+ *     }
+ * }
+ * ```
+ *
+ * This enables:
+ * - Hook ID autocompletion in on() and emit()
+ * - Automatic payload type inference
+ */
+interface HookEventMap {
+}
+interface PluginHookCapability {
+    /**
+     * Register a hook handler
+     *
+     * Subscribes to a hook. When someone calls `emit()` for this hookId,
+     * your handler will be called with the data.
+     *
+     * - Handler can optionally return modified data (for pipe mode)
+     * - Handler can throw HookAbortError to abort the operation
+     * - Returns an unsubscribe function
+     *
+     * @param hookId - The hook ID (e.g., 'crm.customer.afterCreate')
+     * @param handler - Handler function, optionally returns modified data
+     * @param options - Handler options (priority, timeout)
+     * @returns Unsubscribe function
+     *
+     * @example
+     * // Notification handler (no return needed)
+     * ctx.hooks.on('crm.customer.promoted', async (data) => {
+     *   await sendWelcomeEmail(data.customerId);
+     * });
+     *
+     * @example
+     * // Service handler (returns result)
+     * ctx.hooks.on('crm.createProspect', async (data) => {
+     *   const id = await db.insert(customers).values(data);
+     *   return { ...data, id, status: 'prospect' };
+     * });
+     *
+     * @example
+     * // Abort handler (blocks operation)
+     * ctx.hooks.on('crm.customer.beforeCreate', async (data) => {
+     *   if (!data.name) throw new HookAbortError('名字不能为空');
+     * });
+     */
+    on<K extends keyof HookEventMap>(hookId: K, handler: (data: HookEventMap[K], context: HookContext) => HookEventMap[K] | void | Promise<HookEventMap[K] | void>, options?: HookHandlerOptions): () => void;
+    on<K extends keyof HookEventMap>(hookId: K[], handler: (data: HookEventMap[K], context: HookContext) => HookEventMap[K] | void | Promise<HookEventMap[K] | void>, options?: HookHandlerOptions): () => void;
+    on<T = unknown>(hookId: string, handler: (data: T, context: HookContext) => T | void | Promise<T | void>, options?: HookHandlerOptions): () => void;
+    on<T = unknown>(hookId: string[], handler: (data: T, context: HookContext) => T | void | Promise<T | void>, options?: HookHandlerOptions): () => void;
+    /**
+     * Emit a hook (trigger all registered handlers)
+     *
+     * Default mode: handlers run in **parallel**, return value from the
+     * first handler that returns something (service call pattern).
+     *
+     * Pipe mode (`{ mode: 'pipe' }` or legacy `{ pipe: true }`): handlers run
+     * **serially**, each receives the previous handler's output (data
+     * transformation / synchronous service-call pattern).
+     *
+     * @param hookId - The hook ID
+     * @param data - Data to pass to handlers
+     * @param options - Emit options
+     * @returns The handler result (or original data if no handler returns)
+     *
+     * @example
+     * // Parallel (default) — notification, no return needed
+     * await ctx.hooks.emit('crm.customer.promoted', { customerId: 'xxx' });
+     *
+     * @example
+     * // Parallel — service call, get return value
+     * const customer = await ctx.hooks.emit('crm.createProspect', { name: 'Acme' });
+     *
+     * @example
+     * // Pipe mode — serial data transformation
+     * const enrichedData = await ctx.hooks.emit('crm.customer.beforeCreate', data, { mode: 'pipe' });
+     */
+    emit<K extends keyof HookEventMap>(hookId: K, data: HookEventMap[K], options?: HookEmitOptions): Promise<HookEventMap[K]>;
+    emit<T = unknown>(hookId: string, data: T, options?: HookEmitOptions): Promise<T>;
+    /**
+     * List all available hooks
+     *
+     * Returns the list of hook definitions that plugins can subscribe to.
+     * Useful for discovery and validation.
+     *
+     * @returns Array of hook definitions
+     */
+    listHooks(): Promise<Array<{
+        id: string;
+        description: string;
+    }>>;
+    /** @deprecated Use `on()` instead */
+    addAction<T = unknown>(hookId: string, handler: (data: T, ctx: PluginContext) => void | Promise<void>, options?: HookHandlerOptions): () => void;
+    /** @deprecated Use `on()` instead */
+    addFilter<T = unknown>(hookId: string, handler: (data: T, ctx: PluginContext) => T | Promise<T>, options?: HookHandlerOptions): () => void;
+    /** @deprecated Use `emit(hookId, data, { pipe: true })` instead */
+    applyFilter<T = unknown>(hookId: string, initialValue: T): Promise<T>;
+}
+/**
+ * Hook emit options
+ */
+interface HookEmitOptions {
+    /**
+     * Emit mode.
+     * - `event` (default): parallel fire-and-forget / first-result-wins
+     * - `pipe`: serial synchronous pipeline, fail-fast on handler error
+     * - `effect`: serial synchronous effects, fail-fast, ignores handler return values
+     */
+    mode?: "event" | "pipe" | "effect";
+    /**
+     * Dispatch intent.
+     * - `auto` (default): command-like bare ids may route to pluginApis.
+     * - `command`: only route to the matching pluginApis procedure.
+     * - `hook`: only notify registered hook listeners.
+     */
+    dispatch?: "auto" | "command" | "hook";
+    /**
+     * Shared database transaction.
+     *
+     * Only valid with `mode: 'pipe'` because event mode is intentionally
+     * fire-and-forget and does not provide transactional guarantees.
+     */
+    tx?: any;
+    /**
+     * Request user id to pass through to synchronous hook handlers.
+     */
+    userId?: string;
+    /** @deprecated Use `mode: 'pipe'` instead. Kept for backward compatibility. */
+    pipe?: boolean;
+}
+interface HookTransaction {
+    run<T>(callback: (db: NonNullable<PluginContext["db"]>) => Promise<T>): Promise<T>;
+}
+interface HookContext {
+    id: string;
+    hookId: string;
+    traceId?: string;
+    pluginId: string;
+    organizationId?: string | undefined;
+    userId?: string | undefined;
+    tx?: HookTransaction | undefined;
+}
+/**
+ * Hook Abort Error - Thrown by filters to block operations
+ *
+ * When a filter handler throws this error, the operation is aborted
+ * and the error message is returned to the caller.
+ */
+declare class HookAbortError extends Error {
+    constructor(message: string);
+}
+/**
+ * Plugin Usage Capability - Explicit billing consumption
+ *
+ * Used by plugins that need dynamic consumption amounts per request
+ * (e.g., token count, file size MB). For fixed consumption (1 unit per call),
+ * use manifest `capabilities.billing.procedures` instead (zero-code).
+ */
+interface PluginUsageCapability {
+    /**
+     * Consume usage for a specific billing subject
+     *
+     * @param subject - Billing capability subject (must use {pluginId}.* prefix)
+     * @param amount - Amount to consume (default: 1)
+     * @throws EntitlementDeniedError if capability not approved or no quota
+     */
+    consume(subject: string, amount?: number): Promise<void>;
+}
+type ApiPayload<T> = {
+    [K in keyof T]: T[K] extends Date ? string : T[K] extends Date | null ? string | null : T[K] extends Date | undefined ? string | undefined : T[K];
+};
+
+export { type PluginMetricsAllowedLabels as $, type ApiPayload as A, type PluginAssetCreateOptions as B, type PluginAssetInfo as C, type PluginAssetQuery as D, type EAuthModel as E, type PluginAssetUpdateData as F, type PluginAssetVariant as G, type HookContext as H, type PluginCurrencyCapability as I, type PluginEAuthCapability as J, type PluginEntityExtensionCapability as K, type PluginEntityExtensionFilter as L, MARKETPLACE_PUBLISH_AUTH_METHODS as M, type PluginFileCapability as N, type OpaquePublisherCandidateV1 as O, type PluginMediaInfo as P, type PluginFileInfo as Q, type PluginFileQuery as R, type PluginFileUploadInput as S, type PluginHookCapability as T, type PluginJobOptions as U, type PluginJobStatus as V, type PluginMediaCapability as W, type PluginMediaQuery as X, type PluginMediaUpdateData as Y, type PluginMediaUploadInput as Z, type PluginMediaVariant as _, type PluginContext as a, type PluginMetricsCapability as a0, type PluginNotificationActor as a1, type PluginNotificationCapability as a2, type PluginNotificationChannel as a3, type PluginNotificationEvent as a4, type PluginNotificationInput as a5, type PluginNotificationResult as a6, type PluginNotificationSendParams as a7, type PluginNotificationSendResult as a8, type PluginNotificationTarget as a9, type WebPluginSiteInfo as aA, type WebPluginTenantInfo as aB, type WebSlotExtensionQuery as aC, type WebSlotQueryResult as aD, type WebSlotRemoteExtension as aE, type WebSlotRenderOptions as aF, type WebSlotRenderRequest as aG, type WebSlotRenderResult as aH, type WebSlotRenderer as aI, type PluginNotificationTemplate as aa, type PluginOrganizationProvisioningCapability as ab, type PluginPaginatedResult as ac, type PluginPermissionCapability as ad, type PluginPermissionCheckContext as ae, type PluginPermissionDef as af, type PluginQueueCapability as ag, type PluginScopedDb as ah, type PluginSettingEntry as ai, type PluginSettingOptions as aj, type PluginSettingsCapability as ak, type PluginStorageCapability as al, type PluginStorageProvider as am, type PluginStorageProviderConfig as an, type PluginStorageProviderInfo as ao, type PluginStorageUploadInput as ap, type PluginStorageUploadResult as aq, type PluginTraceCapability as ar, type PluginUsageCapability as as, type PluginWebCapability as at, type ReadonlyPluginScopedDb as au, type WebPluginHead as av, type WebPluginHeadLink as aw, type WebPluginRouteHandler as ax, type WebPluginRouteRequest as ay, type WebPluginRouteResult as az, type HookHandlerOptions as b, type PluginLogger as c, type EAuthProvider as d, type EAuthRefreshInput as e, type EAuthRefreshResult as f, type EAuthStatus as g, type EAuthTokenResult as h, type EAuthUpsertInput as i, type EAuthUse as j, HookAbortError as k, type HookEmitOptions as l, HookPriority as m, type HookTransaction as n, type MarketplaceAttestationTargetV1 as o, type MarketplaceExecutionErrorCode as p, type MarketplaceExecutionFailureCode as q, type MarketplaceOrganizationExecutionV1 as r, type MarketplacePlatformReadAction as s, type MarketplacePublishActor as t, type MarketplacePublishAuthMethod as u, type MarketplacePublisherAction as v, type MarketplaceRegistrySigningCapability as w, type PluginApisCapability as x, type PluginArtifactCapability as y, type PluginAssetCapability as z };