@sixtyninecommerce/admin 0.8.0 → 0.10.0

package/dist/feeds/types.d.ts

@@ -0,0 +1,654 @@
+/**
+ * The product-feed contract: the rule AST a merchant builds, the configuration
+ * it lives in, and everything the generator, the review queues and the AI
+ * helpers report back.
+ *
+ * TWO CASING WORLDS meet here, and the difference is not cosmetic.
+ *
+ * 1. **The DTOs are camelCase**, like every other module: the wire is
+ *    snake_case (`language_code`, `refresh_interval_minutes` — the plugins
+ *    controllers project every row onto it) and the transport converts in both
+ *    directions.
+ * 2. **The rule AST inside `mappingJson`, `filtersJson`, `settingsJson`,
+ *    `rulesJson`, `entriesJson`, `perDestinationJson`, `payloadJson`,
+ *    `statsJson` and `defaultSource` is camelCase ON THE WIRE**, stored and
+ *    echoed byte-for-byte by the service. Those subtrees are never converted
+ *    (see `preserve.ts`), so what a consumer builds is what the compiler reads.
+ *
+ * SYNC NOTE — the AST block mirrors `services/plugins/src/feeds/rules/types.ts`
+ * (plus `destinations/types.ts` for the destination and delivery keys, and the
+ * entity modules for the string unions). It is a hand-kept mirror, not
+ * generated: every shape is copied verbatim, never "improved" in transit. When
+ * the engine's AST changes, change this file in the same branch, or the rules a
+ * consumer emits come back as a 400 `INVALID_RULES`.
+ */
+/**
+ * How one output value is produced. Every variant resolves to a STRING —
+ * numeric source fields are stringified on the way out and only compared
+ * numerically inside conditions.
+ */
+export type FeedValueSource = 
+/** A source-field key from the registry, e.g. `title`, `facet:colour`, `internal:size`. */
+{
+    kind: 'field';
+    field: string;
+}
+/** A literal. */
+ | {
+    kind: 'static';
+    value: string;
+}
+/** Concatenation of parts, blank parts dropped before joining. */
+ | {
+    kind: 'combine';
+    parts: FeedValueSource[];
+    separator: string;
+}
+/** First-match substitution through a named lookup table; a miss yields ''. */
+ | {
+    kind: 'lookup';
+    source: FeedValueSource;
+    tableName: string;
+}
+/** Regex extraction; no match yields ''. `group` defaults to 1 (0 = whole match). */
+ | {
+    kind: 'extract';
+    source: FeedValueSource;
+    pattern: string;
+    group?: number;
+}
+/** The already-computed value of an internal field at a lower position. */
+ | {
+    kind: 'internal';
+    name: string;
+};
+/** Every `FeedValueSource.kind`, in the order a builder should offer them. */
+export declare const FEED_VALUE_SOURCE_KINDS: readonly ["field", "static", "combine", "lookup", "extract", "internal"];
+/** Discriminates a {@link FeedValueSource} without a switch at every call site. */
+export declare function isFeedValueSourceKind<K extends FeedValueSource['kind']>(source: FeedValueSource, kind: K): source is Extract<FeedValueSource, {
+    kind: K;
+}>;
+export type FeedConditionOperator = 'eq' | 'neq' | 'contains' | 'not_contains' | 'blank' | 'not_blank' | 'gt' | 'lt' | 'gte' | 'lte' | 'in';
+export declare const FEED_CONDITION_OPERATORS: readonly ["eq", "neq", "contains", "not_contains", "blank", "not_blank", "gt", "lt", "gte", "lte", "in"];
+/** Operators that take NO `value` — a builder must hide the operand input for these. */
+export declare const VALUELESS_FEED_CONDITION_OPERATORS: readonly FeedConditionOperator[];
+/** Comparison operand. `in` takes the array form; `blank`/`not_blank` take none. */
+export type FeedConditionValue = string | number | boolean | Array<string | number>;
+/**
+ * A condition reads EITHER a bare source field (the common case) OR a full
+ * value source (for computed left-hand sides). The union makes "exactly one of
+ * them" a type error rather than a runtime check.
+ */
+export type FeedConditionOperand = {
+    field: string;
+    source?: never;
+} | {
+    source: FeedValueSource;
+    field?: never;
+};
+export type FeedCondition = FeedConditionOperand & {
+    op: FeedConditionOperator;
+    value?: FeedConditionValue;
+};
+/** Boolean group; nests arbitrarily deep. An empty `conditions` array is vacuously true. */
+export interface FeedConditionGroup {
+    logic: 'and' | 'or';
+    conditions: Array<FeedCondition | FeedConditionGroup>;
+}
+/** Narrows a node of a {@link FeedConditionGroup.conditions} array. */
+export declare function isFeedConditionGroup(node: FeedCondition | FeedConditionGroup): node is FeedConditionGroup;
+/** A post-processing step applied to a resolved value, in array order. */
+export type FeedTransformSpec = {
+    kind: 'strip_html';
+} | {
+    kind: 'truncate';
+    maxLen: number;
+} | {
+    kind: 'upper';
+} | {
+    kind: 'lower';
+} | {
+    kind: 'capitalize';
+}
+/**
+ * Minor units → `"1234.50 EUR"`, always in the feed's own currency — the
+ * amount is denominated in it, so no other code may label it.
+ */
+ | {
+    kind: 'price_format';
+};
+/** Every `FeedTransformSpec.kind`, in the order a builder should offer them. */
+export declare const FEED_TRANSFORM_KINDS: readonly ["strip_html", "truncate", "upper", "lower", "capitalize", "price_format"];
+/** One conditional assignment. `when` omitted ⇒ unconditional (a catch-all). */
+export interface FeedFieldRule {
+    when?: FeedConditionGroup;
+    value: FeedValueSource;
+}
+/** Rules producing one feed output field, e.g. `g:id` or `title`. */
+export interface FeedFieldMapping {
+    /** Template target key this mapping fills. */
+    target: string;
+    /** Evaluated in order; FIRST MATCHING rule wins. */
+    rules: FeedFieldRule[];
+    /** Used when no rule matched. Without it the template's `defaultSource` applies. */
+    fallback?: FeedValueSource;
+    /** Applied to the resolved value, in order. */
+    transforms?: FeedTransformSpec[];
+}
+/** Stored shape of `feed_config.mapping_json` (column default `{}`). */
+export interface FeedMappingSpec {
+    fields?: FeedFieldMapping[];
+}
+/**
+ * A computed value referenced as `internal:<name>`. Evaluated in ascending
+ * `position`, and may reference ONLY internal fields at a strictly lower
+ * position — the compiler rejects forward references.
+ */
+export interface FeedInternalFieldSpec {
+    name: string;
+    position: number;
+    rules: FeedFieldRule[];
+    fallback?: FeedValueSource;
+    transforms?: FeedTransformSpec[];
+}
+/** Stored shape of `feed_internal_field.rules_json` — the spec minus its columns. */
+export type FeedInternalFieldRules = Omit<FeedInternalFieldSpec, 'name' | 'position'>;
+/**
+ * Row inclusion. Both sides are optional; `exclude` WINS over `include` — a row
+ * matched by both is dropped.
+ */
+export interface FeedFilterSpec {
+    include?: FeedConditionGroup;
+    exclude?: FeedConditionGroup;
+}
+/** One substitution. `caseInsensitive` applies to this entry's `match` only. */
+export interface FeedLookupEntry {
+    match: string;
+    value: string;
+    caseInsensitive?: boolean;
+}
+export type FeedDestinationKey = 'google' | 'meta' | 'tiktok' | 'pinterest';
+/** Enforced by a CHECK constraint on `feed_config.destination`. */
+export declare const FEED_DESTINATIONS: readonly ["google", "meta", "tiktok", "pinterest"];
+/**
+ * How the items reach the destination:
+ * - `hosted-xml` — the platform hosts a URL the destination fetches on a schedule.
+ * - `api-push`   — the platform pushes items over the destination's API.
+ */
+export type FeedDeliveryMode = 'hosted-xml' | 'api-push';
+/** Server default page size; a list that omits `limit` gets this many rows. */
+export declare const DEFAULT_FEED_PAGE_LIMIT = 20;
+/** Hard ceiling — a larger `limit` is a 400, not a silent clamp. */
+export declare const MAX_FEED_PAGE_LIMIT = 100;
+/**
+ * Non-rule knobs the generator and the delivery layer read directly. Stored in
+ * `settings_json`, a preserved column — so these keys stay camelCase on the wire.
+ */
+export interface FeedConfigSettings {
+    /** Drop rows whose availability is `out_of_stock` instead of emitting them. */
+    excludeOutOfStock?: boolean;
+    /** Hard cap on emitted items; unset/0 means "no cap". */
+    maxItems?: number;
+    /** Storefront origin used to build `link`, e.g. `https://shop.example.com`. */
+    storefrontUrl?: string;
+    /** Public base URL assets are served from, used to build `image_link`. */
+    assetBaseUrl?: string;
+}
+export interface FeedConfig {
+    id: string;
+    name: string;
+    destination: FeedDestinationKey;
+    enabled: boolean;
+    /** Vendure `LanguageCode`, e.g. `nl` or `pt-BR`. */
+    languageCode: string;
+    /** ISO 3166-1 alpha-2, upper-case. */
+    country: string;
+    /** ISO 4217, upper-case. */
+    currencyCode: string;
+    /** Unguessable path segment of the public feed URL (32 hex chars). */
+    token: string;
+    filtersJson: FeedFilterSpec;
+    mappingJson: FeedMappingSpec;
+    settingsJson: FeedConfigSettings;
+    refreshIntervalMinutes: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** `token` is deliberately absent: it is minted server-side and only rotated. */
+export interface CreateFeedConfigInput {
+    name: string;
+    destination: FeedDestinationKey;
+    enabled?: boolean;
+    languageCode: string;
+    country: string;
+    currencyCode: string;
+    filtersJson?: FeedFilterSpec;
+    mappingJson?: FeedMappingSpec;
+    settingsJson?: FeedConfigSettings;
+    refreshIntervalMinutes?: number;
+}
+export interface UpdateFeedConfigInput {
+    name?: string;
+    /** Changing this re-validates `mappingJson` against the new destination template. */
+    destination?: FeedDestinationKey;
+    enabled?: boolean;
+    languageCode?: string;
+    country?: string;
+    currencyCode?: string;
+    filtersJson?: FeedFilterSpec;
+    mappingJson?: FeedMappingSpec;
+    settingsJson?: FeedConfigSettings;
+    refreshIntervalMinutes?: number;
+}
+/**
+ * Accepted range for `refreshIntervalMinutes` — mirrors the DTO's own bounds.
+ *
+ * The floor is the sweep's, not an arbitrary one: the scheduler ticks every 10
+ * minutes and refuses to rebuild a feed more often than every 30, so a shorter
+ * interval was accepted and then quietly held to 30 — a setting that read back
+ * as something the platform never did.
+ */
+export declare const MIN_REFRESH_INTERVAL_MINUTES = 30;
+export declare const MAX_REFRESH_INTERVAL_MINUTES = 10080;
+/** Column default: rebuild every 6 hours. */
+export declare const DEFAULT_REFRESH_INTERVAL_MINUTES = 360;
+/** What `feeds.rotateToken` answers — the previous public URL stops resolving. */
+export interface RotateFeedTokenResult {
+    token: string;
+}
+/**
+ * One output field in a destination's template.
+ *
+ * `defaultSource` is a rule AST echoed verbatim, which is why it is preserved:
+ * without that a `lookup` default would arrive as `table_name` and a builder
+ * would save it corrupted.
+ */
+export interface FeedDestinationTemplateEntry {
+    /** Output key exactly as it must appear in the feed, e.g. `g:id`, `title`. */
+    target: string;
+    /** Missing/blank at validation time ⇒ an `error` issue (the item is unusable). */
+    required: boolean;
+    /** Platform cap in characters. Over-length values are truncated, then warned about. */
+    maxLen?: number;
+    /** Applied when the channel's mapping produced no value for `target`. */
+    defaultSource?: FeedValueSource;
+    /** Human note surfaced in the rule builder. */
+    notes?: string;
+    /**
+     * The feed GENERATOR fills this target itself — `link` from the canonical
+     * route, `g:item_group_id` from the product id, `g:additional_image_link`
+     * from the row's images, `g:google_product_category` from the channel's
+     * category mappings. No `defaultSource` can express any of those, so a UI
+     * that reads only `defaultSource` would report a filled field as unfilled.
+     * A mapping on such a target still wins.
+     */
+    generatorFilled?: boolean;
+}
+export interface FeedDestination {
+    key: FeedDestinationKey;
+    label: string;
+    deliveryMode: FeedDeliveryMode;
+    /** Absent for `api-push` destinations whose payload is not a field template. */
+    template?: FeedDestinationTemplateEntry[];
+}
+export type FeedRunStatus = 'running' | 'completed' | 'failed';
+export declare const FEED_RUN_STATUSES: readonly ["running", "completed", "failed"];
+/** What asked for the run. `source_changed` = the catalogue watermark moved. */
+export type FeedRunTrigger = 'scheduled' | 'source_changed' | 'manual';
+export declare const FEED_RUN_TRIGGERS: readonly ["scheduled", "source_changed", "manual"];
+/**
+ * Free-form per-run display data, written by the generator and echoed verbatim
+ * — so its members are camelCase and its counters are keyed by ISSUE CODE
+ * (`no_category`, `missing_required`), which is why the whole subtree is
+ * preserved.
+ */
+export interface FeedRunStats {
+    /** Issue code → number of issues with that code in this run. */
+    issueCounts?: Record<string, number>;
+    /** Language the snapshot was extracted in — one run covers exactly one. */
+    languageCode?: string;
+    [key: string]: unknown;
+}
+export interface FeedRun {
+    id: string;
+    feedConfigId: string;
+    status: FeedRunStatus;
+    trigger: FeedRunTrigger;
+    /** `productFeedSourceStats.version` the snapshot was taken at (bigint as text). */
+    sourceVersion: string;
+    itemsTotal: number;
+    itemsIncluded: number;
+    itemsExcluded: number;
+    /** Size of the UNCOMPRESSED rendered feed body. */
+    bytes: number;
+    durationMs: number;
+    /** Populated only for `status = 'failed'`. */
+    error: string | null;
+    statsJson: FeedRunStats;
+    startedAt: string;
+    finishedAt: string | null;
+    createdAt: string;
+}
+/** `error` blocks the item at the destination; `warning` ships but degrades it. */
+export type FeedItemIssueSeverity = 'error' | 'warning';
+export declare const FEED_ITEM_ISSUE_SEVERITIES: readonly ["error", "warning"];
+/**
+ * One finding about one item. Only the LATEST successful run's issues are kept
+ * per configuration — these always describe the body being served right now.
+ */
+export interface FeedItemIssue {
+    id: string;
+    runId: string;
+    feedConfigId: string;
+    productId: string;
+    variantId: string;
+    severity: FeedItemIssueSeverity;
+    /** Machine code, e.g. `missing_required`, `no_category`, `duplicate_id`. Not a closed set. */
+    code: string;
+    /** Template target the issue is about (`title`, `g:gtin`); null for item-level issues. */
+    field: string | null;
+    message: string;
+    sampleValue: string | null;
+    createdAt: string;
+}
+/** Ack for an enqueued regeneration — the work happens on the queue. */
+export interface FeedRegenerateResult {
+    /**
+     * Always `true` on a 2xx: a job for this feed IS on the queue, whether this
+     * call put it there or found it already waiting.
+     */
+    enqueued: boolean;
+    /** Queue job id, so a caller can correlate the run that appears seconds later. */
+    jobId: string;
+    feedConfigId: string;
+    /**
+     * Present and `true` only when this press found the SAME feed's job already
+     * queued or running, so nothing new was enqueued. A caller should say
+     * "already queued" rather than claim it started a second pass — eleven
+     * impatient clicks are one run.
+     */
+    deduplicated?: true;
+}
+/**
+ * The 429 a forced regeneration is refused with while the CHANNEL's throttle
+ * window is still open. Every forced pass walks the whole catalogue on a
+ * `concurrency: 1` worker shared by every tenant, so a tenant with twenty feeds
+ * cannot queue twenty walks ahead of everyone else's scheduled refresh.
+ *
+ * It is NOT the dedup case above: that one is a 202 and means "your job is
+ * already running". This one means "nothing was queued, come back later".
+ */
+export declare const FEED_REGENERATE_THROTTLED = "FEED_REGENERATE_THROTTLED";
+/** A refused regeneration, with the wait the service asked for. */
+export interface FeedRegenerateThrottle {
+    /** Seconds to wait, when the service named one. */
+    retryAfterSeconds?: number;
+}
+/**
+ * Read a rejected {@link FeedsModule.regenerate} as a throttle refusal, or
+ * `null` for anything else (a 404, a network failure) — those stay generic.
+ *
+ * A guard rather than a class check: the transport maps the problem body onto a
+ * `RateLimitedError`, and a caller should key on the stable CODE rather than on
+ * an instance that a future mapping change could swap.
+ */
+export declare function readFeedRegenerateThrottle(error: unknown): FeedRegenerateThrottle | null;
+/** A draft configuration evaluated against real source rows and thrown away. */
+export interface FeedPreviewDraft {
+    destination: FeedDestinationKey;
+    languageCode: string;
+    country: string;
+    currencyCode: string;
+    filtersJson?: FeedFilterSpec;
+    mappingJson?: FeedMappingSpec;
+    settingsJson?: FeedConfigSettings;
+    /** 1…50; omitted ⇒ the server's default of 10. */
+    sampleSize?: number;
+}
+export interface FeedPreviewIssue {
+    severity: FeedItemIssueSeverity;
+    code: string;
+    field: string;
+    message: string;
+}
+export interface FeedPreviewItem {
+    productId: string;
+    variantId: string;
+    sku: string;
+    /** False when the draft's filters dropped the row; `values` is then empty. */
+    included: boolean;
+    /** Final evaluated values keyed by template target — post-transform, post-truncation. */
+    values: Record<string, string>;
+    /** Resolved internal-field values, keyed by name. */
+    appliedInternal: Record<string, string>;
+    issues: FeedPreviewIssue[];
+}
+export interface FeedPreview {
+    /** Rows actually evaluated (may be fewer than requested on a small catalogue). */
+    sampleSize: number;
+    items: FeedPreviewItem[];
+    /** Per-code totals across the sample, for the "N items have no category" banner. */
+    issueCounts: Record<string, number>;
+}
+/** Sample size when the caller does not ask for one. */
+export declare const DEFAULT_PREVIEW_SAMPLE_SIZE = 10;
+/** Hard ceiling on a preview sample; a bigger request is a 400. */
+export declare const MAX_PREVIEW_SAMPLE_SIZE = 50;
+/**
+ * A channel-scoped computed value that mapping rules reference as
+ * `internal:<name>`. Evaluated in ascending `position`; a field may only
+ * reference fields at a strictly LOWER position.
+ */
+export interface FeedInternalField {
+    id: string;
+    /** Identifier (not a label): `^[a-z][a-z0-9_]*$`, unique within the channel. */
+    name: string;
+    position: number;
+    rulesJson: FeedInternalFieldRules;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateFeedInternalFieldInput {
+    name: string;
+    position?: number;
+    rulesJson: FeedInternalFieldRules;
+}
+export interface UpdateFeedInternalFieldInput {
+    name?: string;
+    position?: number;
+    rulesJson?: FeedInternalFieldRules;
+}
+/** Identifier rule shared by internal fields and lookup tables. */
+export declare const FEED_IDENTIFIER_PATTERN: RegExp;
+/**
+ * A named substitution table referenced by `{ kind: 'lookup', tableName }`.
+ * Entries are ordered and FIRST MATCH WINS; a miss yields the empty string.
+ */
+export interface FeedLookupTable {
+    id: string;
+    name: string;
+    entriesJson: FeedLookupEntry[];
+    /** Convenience for list views that must not walk the array to count it. */
+    entryCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateFeedLookupTableInput {
+    name: string;
+    entriesJson: FeedLookupEntry[];
+}
+export interface UpdateFeedLookupTableInput {
+    name?: string;
+    /** Entries are replaced WHOLESALE — send the full list, never a delta. */
+    entriesJson?: FeedLookupEntry[];
+}
+/** Server cap on `entriesJson` length. */
+export declare const MAX_LOOKUP_ENTRIES = 5000;
+/** How a mapping row is matched against an item. */
+export type FeedCategoryMatchType = 'collection' | 'facet_value' | 'default';
+export declare const FEED_CATEGORY_MATCH_TYPES: readonly ["collection", "facet_value", "default"];
+/** Where the mapping came from — a human, or the AI categoriser. */
+export type FeedCategoryMappingSource = 'manual' | 'ai';
+export declare const FEED_CATEGORY_MAPPING_SOURCES: readonly ["manual", "ai"];
+/** Review state. Only `approved` rows are applied when generating a feed. */
+export type FeedCategoryMappingStatus = 'approved' | 'suggested' | 'rejected';
+export declare const FEED_CATEGORY_MAPPING_STATUSES: readonly ["approved", "suggested", "rejected"];
+/**
+ * Per-destination category overrides, keyed by destination key. Stored in the
+ * preserved column `per_destination_json`, so the inner keys stay camelCase.
+ */
+export type FeedPerDestinationCategories = Partial<Record<FeedDestinationKey, {
+    categoryId?: string;
+    categoryPath?: string;
+}>>;
+export interface FeedCategoryMapping {
+    id: string;
+    matchType: FeedCategoryMatchType;
+    /** Vendure Collection id; set iff `matchType === 'collection'`. */
+    collectionId: string | null;
+    /** Vendure FacetValue id; set iff `matchType === 'facet_value'`. */
+    facetValueId: string | null;
+    /** Google taxonomy numeric id, as text (it is an identifier, not a number). */
+    googleCategoryId: string;
+    /** Full ` > `-separated path — always RE-DERIVED server-side, never echoed. */
+    googleCategoryPath: string;
+    perDestinationJson: FeedPerDestinationCategories;
+    source: FeedCategoryMappingSource;
+    /** Model confidence in [0,1] for `source = 'ai'`; null for manual rows. */
+    aiConfidence: number | null;
+    status: FeedCategoryMappingStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * `collectionId` is set iff `matchType = 'collection'`, `facetValueId` iff
+ * `'facet_value'`; `'default'` carries neither (at most one per channel).
+ *
+ * A `googleCategoryPath` is accepted but IGNORED — the service re-derives it
+ * from `googleCategoryId` against the vendored taxonomy, which is why this
+ * input does not offer one.
+ */
+export interface CreateFeedCategoryMappingInput {
+    matchType: FeedCategoryMatchType;
+    collectionId?: string;
+    facetValueId?: string;
+    googleCategoryId: string;
+    perDestinationJson?: FeedPerDestinationCategories;
+    source?: FeedCategoryMappingSource;
+    aiConfidence?: number;
+    status?: FeedCategoryMappingStatus;
+}
+export interface UpdateFeedCategoryMappingInput {
+    googleCategoryId?: string;
+    perDestinationJson?: FeedPerDestinationCategories;
+    status?: FeedCategoryMappingStatus;
+}
+/**
+ * Decide a batch of suggestions, selected EITHER by id or by confidence.
+ *
+ * `minConfidence` is not a convenience: a client only ever holds the rows it
+ * has paged in, so an id list built from the loaded page silently stops at the
+ * page boundary. Selecting server-side is the only way "approve everything the
+ * model was sure about" can mean every such row in the channel.
+ */
+export interface BulkUpdateCategoryMappingStatusInput {
+    /** Explicit rows (max {@link MAX_BULK_STATUS_IDS}). Takes precedence over the threshold. */
+    ids?: string[];
+    /** Every `suggested` AI row in the channel at or above this confidence. */
+    minConfidence?: number;
+    status: FeedCategoryMappingStatus;
+}
+export interface BulkStatusUpdateResult {
+    /** Rows actually changed — ids belonging to another channel are skipped, not errored. */
+    updated: number;
+    status: FeedCategoryMappingStatus;
+}
+/** Server cap on one bulk status call. */
+export declare const MAX_BULK_STATUS_IDS = 500;
+export interface FeedTaxonomyNode {
+    /** Google's numeric taxonomy id, e.g. 166. */
+    id: number;
+    /** Full ` > `-separated path, e.g. `Apparel & Accessories > Clothing`. */
+    path: string;
+}
+export declare const TAXONOMY_DEFAULT_LIMIT = 20;
+export declare const TAXONOMY_MAX_LIMIT = 50;
+/** Lifecycle of one channel's categorisation pass. `idle` = never run / marker expired. */
+export type FeedCategorySuggestState = 'idle' | 'queued' | 'running' | 'completed' | 'failed';
+/** What a finished pass produced. Every counter is merchant-facing. */
+export interface FeedCategorySuggestSummary {
+    collectionsConsidered: number;
+    /** Collections that already had a manual or approved mapping. */
+    collectionsSkipped: number;
+    suggestionsWritten: number;
+    /** Model answers whose path did not match the taxonomy — discarded, never guessed. */
+    discardedNoMatch: number;
+    cacheHits: number;
+    /** Suggestions lost to a mapping the merchant created WHILE the pass ran. */
+    writeConflicts: number;
+    /**
+     * Answers that proposed exactly the category the merchant had rejected for
+     * that collection — not re-proposed. Absent on a summary from an older
+     * plugins service.
+     */
+    rejectedAgain?: number;
+}
+export interface SuggestCategoryMappingsInput {
+    /** Re-ask the model for every collection, ignoring the per-collection result cache. */
+    force?: boolean;
+}
+export interface CategorySuggestEnqueueResult {
+    enqueued: boolean;
+    jobId: string | null;
+    aiAvailable: boolean;
+}
+export interface CategorySuggestStatus {
+    state: FeedCategorySuggestState;
+    /** False when the platform has no LLM configured — render the hint, don't error. */
+    aiAvailable: boolean;
+    jobId: string | null;
+    queuedAt: string | null;
+    startedAt: string | null;
+    finishedAt: string | null;
+    summary: FeedCategorySuggestSummary | null;
+    error: string | null;
+}
+export type FeedAiSuggestionKind = 'title_preset';
+export type FeedAiSuggestionStatus = 'suggested' | 'accepted' | 'dismissed';
+/**
+ * One before/after pair. `after` is evaluated SERVER-SIDE with the real rules
+ * engine against a real catalogue row — it is what the feed will emit, not text
+ * the model wrote.
+ */
+export interface TitlePresetExample {
+    sku: string;
+    before: string;
+    after: string;
+}
+/** `payloadJson` of a `title_preset` suggestion. `mapping` is a rule AST. */
+export interface TitlePresetPayload {
+    mapping: FeedFieldMapping;
+    rationale: string;
+    examples: TitlePresetExample[];
+    model?: string;
+}
+export interface FeedAiSuggestion {
+    id: string;
+    feedConfigId: string | null;
+    kind: FeedAiSuggestionKind;
+    status: FeedAiSuggestionStatus;
+    payloadJson: TitlePresetPayload;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Read shape of a mapping tab's AI affordance: the pending proposal, if any. */
+export interface TitlePresetStatus {
+    aiAvailable: boolean;
+    suggestion: FeedAiSuggestion | null;
+}
+export interface GenerateTitlePresetInput {
+    /** Rows to sample; the server default is 20. */
+    sampleSize?: number;
+}
+/** The 409 both AI endpoints refuse with when no LLM is configured. */
+export declare const AI_UNAVAILABLE_CODE = "AI_UNAVAILABLE";