@everscribe/components-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,286 @@
+interface Event {
+    id: string;
+    tenant_id?: string;
+    occurred_at: string;
+    actor?: Record<string, unknown>;
+    action: string;
+    target?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    origin?: Record<string, unknown>;
+    result?: Record<string, unknown>;
+    change?: Record<string, unknown>;
+    idempotency_key?: string;
+}
+interface EmbedClaims {
+    v: number;
+    iss: string;
+    sub: string;
+    aud: string;
+    exp: number;
+    iat: number;
+    jti: string;
+    tenant_id?: string;
+    columns?: string[];
+    actions?: string[];
+    /**
+     * actions_prefix is a list of action prefixes the token can read
+     * (e.g. ["user.", "billing."]). Server-enforced; the component
+     * uses it only when filtering the action dropdown.
+     */
+    actions_prefix?: string[];
+    /**
+     * allowed_fields restricts which catalog fields the token can
+     * use in DSL filters (and the NLP endpoint). When set, the
+     * Query and AI tabs constrain what the user can ask for; the
+     * server rejects out-of-scope fields independently.
+     */
+    allowed_fields?: string[];
+    /**
+     * allow_dsl_input toggles the Query (advanced DSL) tab. When
+     * false, the embed API also rejects ?q=... requests.
+     */
+    allow_dsl_input?: boolean;
+    /**
+     * allow_nlp toggles the AI ("Ask in plain English") tab. When
+     * false, POST /v1/embed/events/nlp returns 403.
+     */
+    allow_nlp?: boolean;
+}
+/**
+ * MetadataKey describes one entry in the project's metadata
+ * vocabulary side table - surfaced for the inline metadata-filter
+ * builder's autocomplete and the NLP context.
+ */
+interface MetadataKey {
+    key: string;
+    observed_type: string;
+    sample_value?: string;
+    event_count: number;
+}
+/**
+ * ChangeField names a field that's been observed changing on
+ * mutation events. Drives the change-field picker autocomplete.
+ */
+interface ChangeField {
+    field: string;
+    event_count: number;
+}
+/**
+ * GenerateNLPFiltersRequest is the JSON body for
+ * POST /v1/embed/events/nlp. Mirrors the server's NLP response shape.
+ */
+interface GenerateNLPFiltersRequest {
+    q: string;
+}
+/**
+ * GenerateNLPFiltersResponse is the JSON shape returned by
+ * POST /v1/embed/events/nlp. DSL is empty when the model couldn't
+ * translate anything; the caller falls back to rendering the
+ * unsupported list.
+ */
+interface GenerateNLPFiltersResponse {
+    dsl: string;
+    unsupported?: string[];
+    explanation?: string;
+    model?: string;
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_hit_tokens?: number;
+}
+
+type ApiErrorKind = 'unauthorized' | 'not_found' | 'rate_limited' | 'bad_request' | 'server' | 'network';
+interface ApiErrorInfo {
+    kind: ApiErrorKind;
+    status?: number;
+    retryAfterMs?: number;
+    message?: string;
+    cause?: unknown;
+}
+declare class EmbedError extends Error {
+    readonly kind: ApiErrorKind;
+    readonly status?: number;
+    readonly retryAfterMs?: number;
+    constructor(info: ApiErrorInfo);
+}
+interface ListEventsResponse {
+    events: Event[];
+    next_cursor?: string;
+}
+interface GetEventResponse {
+    event: Event;
+}
+interface ListEventsParams {
+    limit?: number;
+    cursor?: string;
+    since?: string;
+    before?: string;
+    action?: string;
+    actor?: string;
+    actorType?: string;
+    tenantId?: string;
+    targetType?: string;
+    targetId?: string;
+    resultStatus?: string;
+    originIP?: string;
+    /**
+     * q is the Lucene-flavored DSL accepted by the embed events
+     * endpoint. Server rejects it (claim_error) when the token
+     * lacks allow_dsl_input.
+     */
+    q?: string;
+}
+interface DistinctActionsResponse {
+    actions: string[];
+}
+interface DistinctActorTypesResponse {
+    actor_types: string[];
+}
+interface DistinctTargetTypesResponse {
+    target_types: string[];
+}
+interface DistinctTenantsResponse {
+    tenants: string[];
+}
+interface DistinctResultStatusesResponse {
+    statuses: string[];
+}
+interface MetadataKeysResponse {
+    keys: MetadataKey[];
+}
+interface ChangeFieldsResponse {
+    fields: ChangeField[];
+}
+type ExportFormat = 'csv' | 'json';
+interface ExportEventsParams {
+    format: ExportFormat;
+    since?: string;
+    before?: string;
+    action?: string;
+    actor?: string;
+    actorType?: string;
+    tenantId?: string;
+    targetType?: string;
+    targetId?: string;
+    resultStatus?: string;
+    originIP?: string;
+    q?: string;
+}
+interface ExportEventsResult {
+    blob: Blob;
+    filename: string;
+}
+interface RequestOptions {
+    apiBase: string;
+    token: string;
+    signal?: AbortSignal;
+}
+declare function listEvents(opts: RequestOptions & {
+    params?: ListEventsParams;
+}): Promise<ListEventsResponse>;
+declare function getEvent(opts: RequestOptions & {
+    id: string;
+}): Promise<GetEventResponse>;
+declare function listDistinctActions(opts: RequestOptions): Promise<DistinctActionsResponse>;
+declare function listDistinctActorTypes(opts: RequestOptions): Promise<DistinctActorTypesResponse>;
+declare function listDistinctTargetTypes(opts: RequestOptions): Promise<DistinctTargetTypesResponse>;
+declare function listDistinctTenants(opts: RequestOptions): Promise<DistinctTenantsResponse>;
+declare function listDistinctResultStatuses(opts: RequestOptions): Promise<DistinctResultStatusesResponse>;
+declare function listMetadataKeys(opts: RequestOptions): Promise<MetadataKeysResponse>;
+declare function listChangeFields(opts: RequestOptions): Promise<ChangeFieldsResponse>;
+declare function generateNLPFilters(opts: RequestOptions & {
+    query: string;
+}): Promise<GenerateNLPFiltersResponse>;
+declare function exportEvents(opts: RequestOptions & {
+    params: ExportEventsParams;
+}): Promise<ExportEventsResult>;
+interface TokenSourceOptions {
+    tokenEndpoint?: string;
+    onTokenExpired?: () => Promise<string>;
+}
+declare function fetchTokenViaOpts(opts: TokenSourceOptions): Promise<string | null>;
+
+declare function decodeJwtPayload<T = unknown>(token: string): T;
+
+declare function parseClaims(token: string | null | undefined): EmbedClaims | null;
+
+type DiffKind = 'same' | 'removed' | 'added' | '';
+interface DiffLine {
+    before: string;
+    after: string;
+    beforeKind: DiffKind;
+    afterKind: DiffKind;
+}
+interface DiffView {
+    lines: DiffLine[];
+}
+declare function renderDiff(change: unknown): DiffView;
+declare function hasParseableDiff(change: unknown): boolean;
+
+declare const COLUMN_LABELS: Record<string, string>;
+declare const ALL_COLUMNS: string[];
+
+declare function formatAbsolute(rfc3339: string): string;
+declare function formatRelative(rfc3339: string, now: number): string;
+declare function formatTimeCell(rfc3339: string, now: number): string;
+declare const RELATIVE_TIME_TICK_MS = 30000;
+
+type EventsStatus = 'loading' | 'ok' | 'error' | 'expired';
+interface EventsStoreConfig {
+    apiBase: string;
+    token: string | null;
+    pageSize: number;
+    pollInterval: number;
+    tokenEndpoint?: string;
+    onTokenExpired?: () => Promise<string>;
+    onError?: (err: Error) => void;
+    since?: string;
+    before?: string;
+    action?: string;
+    actor?: string;
+    actorType?: string;
+    tenantId?: string;
+    targetType?: string;
+    targetId?: string;
+    resultStatus?: string;
+    originIP?: string;
+    q?: string;
+}
+interface EventsStoreState {
+    events: Event[];
+    nextCursor: string | null;
+    status: EventsStatus;
+    error: EmbedError | null;
+}
+interface EventsStore {
+    getSnapshot(): EventsStoreState;
+    subscribe(listener: () => void): () => void;
+    loadMore(): void;
+    refresh(): void;
+    dispose(): void;
+}
+declare function createEventsStore(config: EventsStoreConfig): EventsStore;
+
+interface DistinctValues {
+    actions: string[];
+    actorTypes: string[];
+    targetTypes: string[];
+    tenants: string[];
+    resultStatuses: string[];
+    metadataKeys: MetadataKey[];
+    changeFields: ChangeField[];
+}
+interface DistinctValuesStoreConfig {
+    apiBase: string;
+    token: string | null;
+    tokenEndpoint?: string;
+    onTokenExpired?: () => Promise<string>;
+}
+interface DistinctValuesStore {
+    getSnapshot(): DistinctValues;
+    subscribe(listener: () => void): () => void;
+    dispose(): void;
+}
+declare const EMPTY_DISTINCT_VALUES: DistinctValues;
+declare function createDistinctValuesStore(config: DistinctValuesStoreConfig): DistinctValuesStore;
+
+export { ALL_COLUMNS, type ApiErrorInfo, type ApiErrorKind, COLUMN_LABELS, type ChangeField, type ChangeFieldsResponse, type DiffKind, type DiffLine, type DiffView, type DistinctActionsResponse, type DistinctActorTypesResponse, type DistinctResultStatusesResponse, type DistinctTargetTypesResponse, type DistinctTenantsResponse, type DistinctValues, type DistinctValuesStore, type DistinctValuesStoreConfig, EMPTY_DISTINCT_VALUES, type EmbedClaims, EmbedError, type Event, type EventsStatus, type EventsStore, type EventsStoreConfig, type EventsStoreState, type ExportEventsParams, type ExportEventsResult, type ExportFormat, type GenerateNLPFiltersRequest, type GenerateNLPFiltersResponse, type GetEventResponse, type ListEventsParams, type ListEventsResponse, type MetadataKey, type MetadataKeysResponse, RELATIVE_TIME_TICK_MS, type RequestOptions, type TokenSourceOptions, createDistinctValuesStore, createEventsStore, decodeJwtPayload, exportEvents, fetchTokenViaOpts, formatAbsolute, formatRelative, formatTimeCell, generateNLPFilters, getEvent, hasParseableDiff, listChangeFields, listDistinctActions, listDistinctActorTypes, listDistinctResultStatuses, listDistinctTargetTypes, listDistinctTenants, listEvents, listMetadataKeys, parseClaims, renderDiff };