import { z } from 'zod';

/**
 * Context passed to all DataSource operations
 * Contains internal state that should not be mixed with user query parameters
 */
interface BaseDataSourceContext {
    /**
     * Whether to filter to only published/complete content
     * Set by site-builder: true for production, false for preview
     */
    publishedOnly?: boolean;
    /**
     * Scoped entity service that auto-applies publishedOnly filter
     * Datasources should use this instead of their injected entityService
     * to ensure consistent filtering behavior across environments
     */
    entityService: EntityService;
}
/**
 * DataSource Interface
 *
 * Provides data for templates through fetch, generate, or transform operations.
 * DataSources are registered in the DataSourceRegistry and referenced by templates
 * via their dataSourceId property.
 */
interface DataSource {
    /**
     * Unique identifier for this data source
     */
    id: string;
    /**
     * Human-readable name for this data source
     */
    name: string;
    /**
     * Optional description of what this data source provides
     */
    description?: string;
    /**
     * Optional: Fetch existing data
     * Used by data sources that aggregate or retrieve data (e.g., dashboard stats, API data)
     * DataSources validate output using the provided schema
     * @param query - Query parameters for fetching data
     * @param outputSchema - Schema for validating output data
     * @param context - Context with environment
     */
    fetch?: <T>(query: unknown, outputSchema: z.ZodSchema<T>, context: BaseDataSourceContext) => Promise<T>;
    /**
     * Optional: Generate new content
     * Used by data sources that create content (e.g., AI-generated content, reports)
     */
    generate?: <T>(request: unknown, schema: z.ZodSchema<T>) => Promise<T>;
    /**
     * Optional: Transform content between formats
     * Used by data sources that convert content (e.g., markdown to HTML, data formatting)
     */
    transform?: <T>(content: unknown, format: string, schema: z.ZodSchema<T>) => Promise<T>;
}
/**
 * DataSource capabilities for discovery and validation
 */
interface DataSourceCapabilities {
    canFetch: boolean;
    canGenerate: boolean;
    canTransform: boolean;
}

declare const canonicalContentVisibilitySchema: z.ZodEnum<["public", "shared", "restricted"]>;
type ContentVisibility = z.infer<typeof canonicalContentVisibilitySchema>;
type RawContentVisibility = ContentVisibility | "private";

/**
 * Entity type for unstructured notes (the "base" entity type).
 * Used as a sentinel for the default catch-all markdown file shape —
 * no typed frontmatter schema required, content is the entire file body.
 */
declare const BASE_ENTITY_TYPE = "base";
/**
 * Options for entity mutation operations (create, update, upsert)
 */
interface EntityJobOptions {
    priority?: number;
    maxRetries?: number;
}

/**
 * Options for entity creation (extends EntityJobOptions with deduplication)
 */
interface CreateEntityOptions extends EntityJobOptions {
    deduplicateId?: boolean;
}
/**
 * Result of an entity mutation that triggers an embedding job.
 * When skipped is true, content was unchanged — no DB write, no event, no embedding job.
 */
interface EntityMutationResult {
    entityId: string;
    jobId: string;
    skipped: boolean;
}
/**
 * Input for adapter-validated direct creation from finalized markdown.
 */
interface CreateEntityFromMarkdownInput {
    entityType: string;
    id: string;
    markdown: string;
}
/**
 * Data for storing an embedding for an entity
 */
interface StoreEmbeddingData {
    entityId: string;
    entityType: string;
    embedding: Float32Array;
    contentHash: string;
}
/**
 * Base entity schema that all entities must extend
 */
declare const baseEntitySchema: z.ZodObject<{
    id: z.ZodString;
    entityType: z.ZodString;
    content: z.ZodString;
    created: z.ZodString;
    updated: z.ZodString;
    visibility: z.ZodEffects<z.ZodOptional<z.ZodUnion<[z.ZodEnum<["public", "shared", "restricted"]>, z.ZodLiteral<"private">]>>, "public" | "shared" | "restricted", "public" | "shared" | "restricted" | "private" | undefined>;
    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
    contentHash: z.ZodString;
}, "strip", z.ZodTypeAny, {
    id: string;
    entityType: string;
    content: string;
    created: string;
    updated: string;
    visibility: "public" | "shared" | "restricted";
    metadata: Record<string, unknown>;
    contentHash: string;
}, {
    id: string;
    entityType: string;
    content: string;
    created: string;
    updated: string;
    metadata: Record<string, unknown>;
    contentHash: string;
    visibility?: "public" | "shared" | "restricted" | "private" | undefined;
}>;
/**
 * Base entity type - generic to support typed metadata
 * TMetadata defaults to Record<string, unknown> for backward compatibility
 */
interface BaseEntity<TMetadata = Record<string, unknown>> {
    id: string;
    entityType: string;
    content: string;
    created: string;
    updated: string;
    visibility: ContentVisibility;
    metadata: TMetadata;
    /** SHA256 hash of content for change detection */
    contentHash: string;
}
/**
 * Entity input type for creation - allows partial entities with optional system fields
 * contentHash is excluded because it's computed automatically by the entity service
 */
type EntityInput<T extends BaseEntity> = Omit<T, "id" | "created" | "updated" | "contentHash" | "visibility"> & {
    id?: string;
    created?: string;
    updated?: string;
    visibility?: RawContentVisibility;
};
/**
 * Search result type
 */
interface SearchResult<T extends BaseEntity = BaseEntity> {
    entity: T;
    score: number;
    excerpt: string;
}
/**
 * Normalized system_create input shape used by plugin create interceptors.
 */
interface CreateCoverImageInput {
    generate?: boolean | undefined;
    prompt?: string | undefined;
}
interface CreateFromAttachmentInput {
    kind: "entity-attachment";
    sourceEntityType: string;
    sourceEntityId: string;
    attachmentType: string;
}
interface CreateFromUploadInput {
    kind: "upload";
    id: string;
}
type CreateFromInput = CreateFromAttachmentInput | CreateFromUploadInput;
type CreateTransform = "extract-markdown";
interface CreateInput {
    entityType: string;
    prompt?: string;
    title?: string;
    content?: string;
    url?: string;
    from?: CreateFromInput;
    transform?: CreateTransform;
    replace?: boolean;
    targetEntityType?: string;
    targetEntityId?: string;
    coverImage?: boolean | CreateCoverImageInput;
}
/**
 * Minimal caller context forwarded to plugin create interceptors.
 */
interface CreateExecutionContext {
    interfaceType: string;
    userId: string;
    channelId?: string;
    channelName?: string;
}
/**
 * Result returned to system_create when a plugin fully handles creation.
 */
declare const createResultAttachmentSchema: z.ZodObject<{
    mediaType: z.ZodString;
    url: z.ZodString;
    downloadUrl: z.ZodOptional<z.ZodString>;
    previewUrl: z.ZodOptional<z.ZodString>;
    filename: z.ZodOptional<z.ZodString>;
    sizeBytes: z.ZodOptional<z.ZodNumber>;
    source: z.ZodOptional<z.ZodObject<{
        entityType: z.ZodOptional<z.ZodString>;
        entityId: z.ZodOptional<z.ZodString>;
        attachmentType: z.ZodOptional<z.ZodString>;
    }, "strip", z.ZodTypeAny, {
        entityType?: string | undefined;
        entityId?: string | undefined;
        attachmentType?: string | undefined;
    }, {
        entityType?: string | undefined;
        entityId?: string | undefined;
        attachmentType?: string | undefined;
    }>>;
}, "strip", z.ZodTypeAny, {
    mediaType: string;
    url: string;
    downloadUrl?: string | undefined;
    previewUrl?: string | undefined;
    filename?: string | undefined;
    sizeBytes?: number | undefined;
    source?: {
        entityType?: string | undefined;
        entityId?: string | undefined;
        attachmentType?: string | undefined;
    } | undefined;
}, {
    mediaType: string;
    url: string;
    downloadUrl?: string | undefined;
    previewUrl?: string | undefined;
    filename?: string | undefined;
    sizeBytes?: number | undefined;
    source?: {
        entityType?: string | undefined;
        entityId?: string | undefined;
        attachmentType?: string | undefined;
    } | undefined;
}>;
type CreateResultAttachment = z.infer<typeof createResultAttachmentSchema>;
type CreateResult = {
    success: true;
    data: {
        entityId?: string;
        jobId?: string;
        status: string;
        attachment?: CreateResultAttachment;
    };
} | {
    success: false;
    error: string;
};
/**
 * Plugin create interceptors can either fully handle creation,
 * or continue with a rewritten normalized input.
 */
type CreateInterceptionResult = {
    kind: "handled";
    result: CreateResult;
} | {
    kind: "continue";
    input: CreateInput;
};
type CreateInterceptor = (input: CreateInput, executionContext: CreateExecutionContext) => Promise<CreateInterceptionResult>;
/**
 * Interface for entity adapter - handles conversion between entities and markdown
 * following the hybrid storage model
 *
 * @template TEntity - The full entity type
 * @template TMetadata - The metadata type (defaults to Record<string, unknown>)
 */
interface EntityAdapter<TEntity extends BaseEntity<TMetadata>, TMetadata = Record<string, unknown>> {
    entityType: string;
    schema: z.ZodType<TEntity, z.ZodTypeDef, unknown>;
    toMarkdown(entity: TEntity): string;
    fromMarkdown(markdown: string): Partial<TEntity>;
    extractMetadata(entity: TEntity): TMetadata;
    parseFrontMatter<TFrontmatter>(markdown: string, schema: z.ZodSchema<TFrontmatter>): TFrontmatter;
    generateFrontMatter(entity: TEntity): string;
    /** Optional: Zod schema for frontmatter fields. Used by CMS config generation. */
    frontmatterSchema?: z.ZodObject<z.ZodRawShape>;
    /** Optional: Declares this entity type is a singleton (one file, e.g., identity/identity.md). Used by CMS to generate files collection. */
    isSingleton?: boolean;
    /** Optional: Whether this entity has a free-form markdown body below frontmatter. Defaults to true. When false, CMS omits the body widget. */
    hasBody?: boolean;
    /** Returns a markdown body template with section headings for this entity type. Empty string for free-form entities. */
    getBodyTemplate(): string;
    /** Optional: Declares that this entity type supports cover images via coverImageId in frontmatter */
    supportsCoverImage?: boolean;
    /** Optional: Extract coverImageId from entity content/frontmatter */
    getCoverImageId?(entity: TEntity): string | undefined;
    /**
     * Optional: build the markdown content and metadata for a queued-generation stub.
     * When undefined, this entity type does not support prompt-based queued creation
     * via system_create; the tool will reject the call rather than silently degrade.
     * The returned metadata must satisfy this entity's metadata schema (with
     * status set to "generating"); central code only stamps id/timestamps/visibility.
     */
    buildStub?(input: {
        id: string;
        title: string;
    }): {
        content: string;
        metadata: TMetadata;
    };
}
/**
 * Sort field specification for multi-field sorting
 */
interface SortField {
    /** Field to sort by - "created", "updated", or a metadata field name */
    field: string;
    /** Sort direction */
    direction: "asc" | "desc";
    /** Sort NULL values before non-NULL values (default: false / SQLite default) */
    nullsFirst?: boolean;
}
/**
 * List entities options
 * Generic over metadata type for type-safe filtering
 */
interface ListOptions<TMetadata = Record<string, unknown>> {
    limit?: number;
    offset?: number;
    /** Multi-field sorting - supports system fields (created, updated) and metadata fields */
    sortFields?: SortField[];
    filter?: {
        metadata?: Partial<TMetadata>;
        visibilityScope?: ContentVisibility;
    };
    /** Filter to only entities with metadata.status = "published" */
    publishedOnly?: boolean;
}
/**
 * Search options
 */
interface SearchOptions {
    limit?: number;
    offset?: number;
    types?: string[];
    excludeTypes?: string[];
    sortBy?: "relevance" | "created" | "updated";
    sortDirection?: "asc" | "desc";
    /** Score multipliers per entity type - applied after initial search */
    weight?: Record<string, number>;
    visibilityScope?: ContentVisibility;
    /** Include queued/failed generation stubs in search results (default: false) */
    includeUngenerated?: boolean;
}
/**
 * Configuration for entity type registration
 */
interface EntityTypeConfig {
    /** Score multiplier for search results (default: 1.0) */
    weight?: number;
    /** Whether to generate embeddings for this entity type (default: true).
     *  Set to false for entity types with non-textual content (e.g., images). */
    embeddable?: boolean;
    /** Whether this entity type may be used as source material for derived projections (default: true).
     *  Set to false for projection outputs that would create feedback loops. */
    projectionSource?: boolean;
    /** Publish semantics for status-bearing entity types. Statuses listed here
     *  represent publication commitment/execution states and require the
     *  `publish` entity action when entered or modified. */
    publish?: {
        publishStatuses: string[];
    };
}
/**
 * Core entity service interface for read-only operations
 * Used by core plugins that need entity access but shouldn't modify entities
 */
interface GetEntityRequest {
    entityType: string;
    id: string;
    /**
     * Optional visibility scope. Undefined fails closed to "public" — callers
     * with elevated access must opt up explicitly.
     */
    visibilityScope?: ContentVisibility;
}
type GetEntityRawRequest = GetEntityRequest;
interface ListEntitiesRequest {
    entityType: string;
    options?: ListOptions | undefined;
}
interface CountEntitiesRequest {
    entityType: string;
    options?: Pick<ListOptions, "publishedOnly" | "filter"> | undefined;
}
interface CreateEntityRequest<T extends BaseEntity> {
    entity: EntityInput<T>;
    options?: CreateEntityOptions | undefined;
}
interface CreateEntityFromMarkdownRequest {
    input: CreateEntityFromMarkdownInput;
    options?: CreateEntityOptions | undefined;
}
interface UpdateEntityRequest<T extends BaseEntity> {
    entity: T;
    options?: EntityJobOptions | undefined;
}
interface DeleteEntityRequest {
    entityType: string;
    id: string;
}
interface UpsertEntityRequest<T extends BaseEntity> {
    entity: T;
    options?: EntityJobOptions | undefined;
}
interface EntitySearchRequest {
    query: string;
    options?: SearchOptions | undefined;
}
interface SearchWithDistancesRequest {
    query: string;
}
interface ICoreEntityService {
    getEntity<T extends BaseEntity>(request: GetEntityRequest): Promise<T | null>;
    /**
     * Get entity without content resolution (raw)
     * Used internally to avoid recursion when resolving image references
     */
    getEntityRaw<T extends BaseEntity>(request: GetEntityRawRequest): Promise<T | null>;
    listEntities<T extends BaseEntity>(request: ListEntitiesRequest): Promise<T[]>;
    search<T extends BaseEntity = BaseEntity>(request: EntitySearchRequest): Promise<SearchResult<T>[]>;
    getEntityTypes(): string[];
    hasEntityType(type: string): boolean;
    countEntities(request: CountEntitiesRequest): Promise<number>;
    /**
     * Group counts by entity type. Fails closed: undefined visibilityScope
     * filters to public-only counts so aggregate insights cannot reveal
     * non-public entity existence.
     */
    getEntityCounts(visibilityScope?: ContentVisibility): Promise<Array<{
        entityType: string;
        count: number;
    }>>;
    /** Get configuration for a specific entity type */
    getEntityTypeConfig(type: string): EntityTypeConfig;
    /** Get weight map for all registered entity types with non-default weights */
    getWeightMap(): Record<string, number>;
}
interface EntityService extends ICoreEntityService {
    createEntity<T extends BaseEntity>(request: CreateEntityRequest<T>): Promise<EntityMutationResult>;
    createEntityFromMarkdown(request: CreateEntityFromMarkdownRequest): Promise<EntityMutationResult>;
    updateEntity<T extends BaseEntity>(request: UpdateEntityRequest<T>): Promise<EntityMutationResult>;
    deleteEntity(request: DeleteEntityRequest): Promise<boolean>;
    upsertEntity<T extends BaseEntity>(request: UpsertEntityRequest<T>): Promise<EntityMutationResult & {
        created: boolean;
    }>;
    storeEmbedding(data: StoreEmbeddingData): Promise<void>;
    serializeEntity(entity: BaseEntity): string;
    deserializeEntity(markdown: string, entityType: string): Partial<BaseEntity>;
    countEmbeddings(): Promise<number>;
    searchWithDistances(request: SearchWithDistancesRequest): Promise<Array<{
        entityId: string;
        entityType: string;
        distance: number;
    }>>;
    initialize(): Promise<void>;
    getAsyncJobStatus(jobId: string): Promise<{
        status: "pending" | "processing" | "completed" | "failed";
        error?: string;
    } | null>;
}

/** Interface for objects that can generate a body template. */
interface BodyTemplateProvider {
    generateBodyTemplate(): string;
}
interface BaseEntityAdapterConfig<TEntity extends BaseEntity<TMetadata>, TMetadata extends object> {
    entityType: string;
    schema: z.ZodType<TEntity, z.ZodTypeDef, unknown>;
    frontmatterSchema: z.ZodObject<z.ZodRawShape>;
    isSingleton?: boolean;
    hasBody?: boolean;
    supportsCoverImage?: boolean;
    bodyFormatter?: BodyTemplateProvider;
}
/**
 * Abstract base class for entity adapters.
 *
 * Provides default implementations for the 3 boilerplate methods
 * (extractMetadata, parseFrontMatter, generateFrontMatter) and
 * protected helpers for common patterns in toMarkdown/fromMarkdown.
 *
 * Subclasses must implement toMarkdown() and fromMarkdown().
 */
declare abstract class BaseEntityAdapter<TEntity extends BaseEntity<TMetadata>, TMetadata extends object = Record<string, unknown>, TFrontmatter = TMetadata> implements EntityAdapter<TEntity, TMetadata> {
    readonly entityType: string;
    readonly schema: z.ZodType<TEntity, z.ZodTypeDef, unknown>;
    readonly frontmatterSchema: z.ZodObject<z.ZodRawShape>;
    readonly isSingleton?: boolean;
    readonly hasBody?: boolean;
    readonly supportsCoverImage?: boolean;
    private readonly fmSchema;
    private readonly bodyFormatter;
    constructor(config: BaseEntityAdapterConfig<TEntity, TMetadata>);
    abstract fromMarkdown(markdown: string): Partial<TEntity>;
    /**
     * Serialize an entity to markdown.
     *
     * Rebuilds frontmatter from entity.metadata overlaid on any existing
     * frontmatter parsed from entity.content. Body comes from renderBody,
     * which defaults to the body portion of entity.content (frontmatter
     * stripped).
     *
     * Adapters that want the body to reflect typed fields (e.g. a
     * structured about/skills section) override renderBody. Adapters that
     * need entirely custom serialization override toMarkdown.
     */
    toMarkdown(entity: TEntity): string;
    /**
     * Render the body section of the entity.
     *
     * Default returns the body portion of entity.content (frontmatter
     * stripped). Override when the body should be rebuilt from typed
     * fields on the entity.
     */
    protected renderBody(entity: TEntity): string;
    private readExistingFrontmatter;
    extractMetadata(entity: TEntity): TMetadata;
    parseFrontMatter<T>(markdown: string, schema: z.ZodSchema<T>): T;
    getBodyTemplate(): string;
    generateFrontMatter(entity: TEntity): string;
    /** Strip frontmatter and return the body content. */
    protected extractBody(markdown: string): string;
    /** Parse frontmatter using this adapter's frontmatter schema. */
    protected parseFrontmatter(markdown: string): TFrontmatter;
    /** Combine body and frontmatter into a markdown string. */
    protected buildMarkdown(body: string, frontmatter: Record<string, unknown>): string;
}

/**
 * Configuration for frontmatter handling
 */
interface FrontmatterConfig<T extends BaseEntity> {
    /**
     * Fields to explicitly include in frontmatter
     * If not specified, includes all non-system fields
     */
    includeFields?: (keyof T)[];
    /**
     * Fields to exclude from frontmatter
     * By default excludes: id, entityType, content, created, updated
     */
    excludeFields?: (keyof T)[];
    /**
     * Custom serializers for complex fields
     */
    customSerializers?: {
        [K in keyof T]?: (value: T[K]) => unknown;
    };
    /**
     * Custom deserializers for complex fields
     */
    customDeserializers?: {
        [K in keyof T]?: (value: unknown) => T[K];
    };
}
/**
 * Generate markdown with frontmatter from content and metadata
 */
declare function generateMarkdownWithFrontmatter(content: string, metadata: Record<string, unknown>): string;
/**
 * Parse markdown with frontmatter into content and metadata
 */
declare function parseMarkdownWithFrontmatter<T>(markdown: string, schema: z.ZodSchema<T>): {
    content: string;
    metadata: T;
};
/**
 * Generate frontmatter string from metadata
 */
declare function generateFrontmatter(metadata: Record<string, unknown>): string;

/**
 * Schema for pagination information
 * Used by datasources that return paginated lists
 */
declare const paginationInfoSchema: z.ZodObject<{
    currentPage: z.ZodNumber;
    totalPages: z.ZodNumber;
    totalItems: z.ZodNumber;
    pageSize: z.ZodNumber;
    hasNextPage: z.ZodBoolean;
    hasPrevPage: z.ZodBoolean;
}, "strip", z.ZodTypeAny, {
    currentPage: number;
    totalPages: number;
    totalItems: number;
    pageSize: number;
    hasNextPage: boolean;
    hasPrevPage: boolean;
}, {
    currentPage: number;
    totalPages: number;
    totalItems: number;
    pageSize: number;
    hasNextPage: boolean;
    hasPrevPage: boolean;
}>;
/**
 * Pagination information type
 */
type PaginationInfo = z.infer<typeof paginationInfoSchema>;
/**
 * Build pagination info from total count and page parameters
 * Used for database-level pagination where we have a separate count query
 */
declare function buildPaginationInfo(totalItems: number, page: number, pageSize: number): PaginationInfo;
/**
 * Options for paginating items
 */
interface PaginateOptions {
    page?: number | undefined;
    limit?: number | undefined;
    pageSize?: number | undefined;
}
/**
 * Result of paginating items
 */
interface PaginateResult<T> {
    items: T[];
    pagination: PaginationInfo | null;
}
/**
 * Paginate a list of items
 *
 * When `page` is specified, returns paginated results with pagination info.
 * When only `limit` is specified, returns first N items without pagination info.
 * When neither is specified, returns all items without pagination info.
 *
 * @param items - The full list of items to paginate (should already be sorted)
 * @param options - Pagination options
 * @returns Paginated items and optional pagination info
 */
declare function paginateItems<T>(items: T[], options: PaginateOptions): PaginateResult<T>;

export { BASE_ENTITY_TYPE, BaseEntityAdapter, baseEntitySchema, buildPaginationInfo, generateFrontmatter, generateMarkdownWithFrontmatter, paginateItems, paginationInfoSchema, parseMarkdownWithFrontmatter };
export type { BaseDataSourceContext, BaseEntity, CreateExecutionContext, CreateInput, CreateInterceptionResult, CreateInterceptor, CreateResult, DataSource, DataSourceCapabilities, EntityAdapter, EntityInput, EntityMutationResult, EntityTypeConfig, FrontmatterConfig, ListOptions, PaginateOptions, PaginateResult, PaginationInfo, SearchOptions, SearchResult };
