/**
 * Public types for the signals read surface.
 *
 * Mirrors the sources types so downstream consumers (CLI, MCP) get a
 * uniform shape across both surfaces. `sourceRef`, `citations`, and
 * `entity_refs` are surfaced as typed fields on the full document
 * because they're the cross-reference primitives an agent needs.
 */
import type { SignalType } from "../schemas/signal-types.js";
import type { EntityContext } from "../types.js";
import type { PresignTransportClient } from "../object-io.js";
/**
 * Lightweight summary returned by listSignals(). `frontmatter` and
 * `sourceRef` are only populated when the caller passes
 * `includeFrontmatter: true`.
 */
export interface SignalSummary {
    /** Stable ID derived from the object key (filename minus `.md`). */
    signalId: string;
    signalType: SignalType;
    /** Full S3 object key (e.g. "signals/action_item/foo.md"). */
    key: string;
    lastModified: Date;
    size: number;
    /** Convenience field parsed from frontmatter.source_ref when includeFrontmatter:true. */
    sourceRef?: string;
    /** Parsed YAML frontmatter — only present when includeFrontmatter:true. */
    frontmatter?: Record<string, unknown>;
}
/**
 * Full signal document returned by getSignal().
 *
 * `sourceRef`, `citations`, and `entity_refs` are surfaced as typed
 * fields so callers don't have to fish inside `frontmatter`. They're
 * still present on `frontmatter` too.
 */
export interface SignalDocument {
    key: string;
    /** Parsed YAML frontmatter, or `null` if the document had no frontmatter block. */
    frontmatter: Record<string, unknown> | null;
    /** Markdown body (everything after the closing `---`). */
    body: string;
    /** frontmatter.source_ref, if present and a string. */
    sourceRef?: string;
    /** frontmatter.citations[], if present and an array. */
    citations?: string[];
    /** frontmatter.entity_refs[], if present and an array. */
    entityRefs?: string[];
}
export interface ListSignalsOptions {
    entity: EntityContext;
    signalType: SignalType;
    /**
     * Max keys per page. Under direct S3 this maps to `MaxKeys`; under the
     * presigned transport ({@link vault} + a company vault) it is advisory — the
     * vault `list` endpoint controls page size server-side. Defaults to the S3
     * default (1000) on the direct path.
     */
    limit?: number;
    /** Opaque continuation token returned by a prior page. */
    continuationToken?: string;
    /** When true, fetches+parses each entry's frontmatter (extra GETs). */
    includeFrontmatter?: boolean;
    /**
     * Presign-capable vault client. When supplied and {@link entity} is a company
     * vault (cmp_*), reads use the presigned-URL transport (ACL-filtered, no
     * direct S3). Personal vaults and the absent-client path stay on direct S3.
     */
    vault?: PresignTransportClient;
}
export interface ListSignalsResult {
    entries: SignalSummary[];
    /** Present when the result was truncated; pass back as continuationToken. */
    nextToken?: string;
}
export interface GetSignalOptions {
    entity: EntityContext;
    signalType: SignalType;
    signalId: string;
    /**
     * Presign-capable vault client. When supplied and {@link entity} is a company
     * vault (cmp_*), reads use the presigned-URL transport (no direct S3).
     */
    vault?: PresignTransportClient;
}
//# sourceMappingURL=types.d.ts.map