@endora-commerce/contracts 0.100.0

package/dist/search.d.ts

@@ -0,0 +1,321 @@
+import { z } from 'zod';
+import { type ProductAudience, type ProductListSort, type ProductSummary } from './catalog.js';
+/**
+ * Maximum allowed phrase length, in characters. Mirrors the
+ * `phrase varchar(512)` upper bound in `data-model.md §1.1` so the wire
+ * contract refuses anything that the storage layer would refuse anyway.
+ */
+export declare const SEARCH_PHRASE_MAX_LENGTH = 512;
+/**
+ * Hard cap on `limit`; the per-channel `search.popup.suggestion_count`
+ * setting is what callers normally observe. The cap exists so a misbehaving
+ * client cannot ask for more than the popup UX could realistically render.
+ */
+export declare const SEARCH_SUGGEST_LIMIT_MAX = 50;
+export declare const SearchSuggestQuerySchema: z.ZodObject<{
+    q: z.ZodString;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type SearchSuggestQuery = z.infer<typeof SearchSuggestQuerySchema>;
+export declare const SearchSuggestMetaSchema: z.ZodObject<{
+    limit: z.ZodNumber;
+    minimumQueryLength: z.ZodNumber;
+    queryEcho: z.ZodString;
+}, z.core.$strip>;
+export type SearchSuggestMeta = z.infer<typeof SearchSuggestMetaSchema>;
+/**
+ * Money carried by an enriched suggestion. The amount is a decimal STRING
+ * (e.g. "199.00") to preserve trailing zeros across the wire, matching the
+ * `resolved-price` endpoint's shape (feature 011) rather than the foundation
+ * `moneySchema` (which uses a number for the legacy `ProductSummary.price`).
+ */
+export declare const searchSuggestMoneySchema: z.ZodObject<{
+    amount: z.ZodString;
+    currency: z.ZodString;
+}, z.core.$strip>;
+export type SearchSuggestMoney = z.infer<typeof searchSuggestMoneySchema>;
+/**
+ * A typeahead suggestion. Extends the foundation `ProductSummary` (id, sku,
+ * name, slug, `primaryAssetUrl`, legacy `price`) with the per-customer
+ * price-list resolution so the popup can render the SKU, image, and the
+ * price the searching user would actually pay — honouring their price list
+ * and price-visibility (`priceDisplayMode`, where `none` hides the price).
+ *
+ * The pricing fields are optional: when the search module runs without a
+ * pricing enricher wired (foundation tests, Meilisearch-only deployments)
+ * the response degrades to a plain `ProductSummary` and the storefront
+ * falls back to the legacy `price` projection.
+ */
+export declare const searchSuggestItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    sku: z.ZodString;
+    type: z.ZodEnum<{
+        simple: "simple";
+        configurable: "configurable";
+        grouped: "grouped";
+        bundle: "bundle";
+        virtual: "virtual";
+    }>;
+    name: z.ZodString;
+    slug: z.ZodString;
+    categorySlugs: z.ZodArray<z.ZodString>;
+    primaryAssetUrl: z.ZodNullable<z.ZodString>;
+    price: z.ZodNullable<z.ZodObject<{
+        amount: z.ZodNumber;
+        currency: z.ZodString;
+    }, z.core.$strip>>;
+    stockIndicator: z.ZodNullable<z.ZodEnum<{
+        available: "available";
+        out_of_stock: "out_of_stock";
+        to_order: "to_order";
+    }>>;
+    stockLevel: z.ZodNullable<z.ZodNumber>;
+    priceUnavailable: z.ZodOptional<z.ZodBoolean>;
+    availability: z.ZodOptional<z.ZodObject<{
+        band: z.ZodEnum<{
+            available: "available";
+            out_of_stock: "out_of_stock";
+            high: "high";
+            medium: "medium";
+            low: "low";
+        }>;
+        inStock: z.ZodBoolean;
+    }, z.core.$strip>>;
+    basePrice: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        amount: z.ZodString;
+        currency: z.ZodString;
+    }, z.core.$strip>>>;
+    salePrice: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        amount: z.ZodString;
+        currency: z.ZodString;
+    }, z.core.$strip>>>;
+    priceDisplayMode: z.ZodOptional<z.ZodEnum<{
+        both: "both";
+        none: "none";
+        gross_only: "gross_only";
+        net_only: "net_only";
+    }>>;
+}, z.core.$strip>;
+export type SearchSuggestItem = z.infer<typeof searchSuggestItemSchema>;
+export declare const SearchSuggestResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        sku: z.ZodString;
+        type: z.ZodEnum<{
+            simple: "simple";
+            configurable: "configurable";
+            grouped: "grouped";
+            bundle: "bundle";
+            virtual: "virtual";
+        }>;
+        name: z.ZodString;
+        slug: z.ZodString;
+        categorySlugs: z.ZodArray<z.ZodString>;
+        primaryAssetUrl: z.ZodNullable<z.ZodString>;
+        price: z.ZodNullable<z.ZodObject<{
+            amount: z.ZodNumber;
+            currency: z.ZodString;
+        }, z.core.$strip>>;
+        stockIndicator: z.ZodNullable<z.ZodEnum<{
+            available: "available";
+            out_of_stock: "out_of_stock";
+            to_order: "to_order";
+        }>>;
+        stockLevel: z.ZodNullable<z.ZodNumber>;
+        priceUnavailable: z.ZodOptional<z.ZodBoolean>;
+        availability: z.ZodOptional<z.ZodObject<{
+            band: z.ZodEnum<{
+                available: "available";
+                out_of_stock: "out_of_stock";
+                high: "high";
+                medium: "medium";
+                low: "low";
+            }>;
+            inStock: z.ZodBoolean;
+        }, z.core.$strip>>;
+        basePrice: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            amount: z.ZodString;
+            currency: z.ZodString;
+        }, z.core.$strip>>>;
+        salePrice: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            amount: z.ZodString;
+            currency: z.ZodString;
+        }, z.core.$strip>>>;
+        priceDisplayMode: z.ZodOptional<z.ZodEnum<{
+            both: "both";
+            none: "none";
+            gross_only: "gross_only";
+            net_only: "net_only";
+        }>>;
+    }, z.core.$strip>>;
+    meta: z.ZodObject<{
+        limit: z.ZodNumber;
+        minimumQueryLength: z.ZodNumber;
+        queryEcho: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type SearchSuggestResponse = z.infer<typeof SearchSuggestResponseSchema>;
+/**
+ * The four `search.llm.*` settings whose values are inspected by the
+ * toggle wrapper. `enabled` must be present; the other three must be
+ * non-empty when `enabled=true`. The wrapper itself only writes the
+ * `enabled` setting — the embedder fields are written through the
+ * generic Settings admin route and read by the wrapper at validation
+ * time.
+ */
+export declare const LlmToggleRequestSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    salesChannelCodes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    expectedVersion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type LlmToggleRequest = z.infer<typeof LlmToggleRequestSchema>;
+export declare const LlmToggleResponseSchema: z.ZodObject<{
+    code: z.ZodLiteral<"search.llm.enabled">;
+    enabled: z.ZodBoolean;
+    newVersion: z.ZodString;
+    appliedChannelIds: z.ZodArray<z.ZodUUID>;
+}, z.core.$strip>;
+export type LlmToggleResponse = z.infer<typeof LlmToggleResponseSchema>;
+/**
+ * Fire-and-forget analytics ingest. The storefront's `/search` page
+ * fires this on render, AFTER `listProducts` resolves so `resultCount`
+ * is meaningful. The endpoint always returns `202 { ok: true }` once
+ * the input passes shape validation; persistence failures degrade to a
+ * warn log (FR-015 — recording must never delay or fail the search
+ * response).
+ */
+export declare const RecordPhraseRequestSchema: z.ZodObject<{
+    phrase: z.ZodString;
+    resultCount: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type RecordPhraseRequest = z.infer<typeof RecordPhraseRequestSchema>;
+export declare const RecordPhraseResponseSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export type RecordPhraseResponse = z.infer<typeof RecordPhraseResponseSchema>;
+/**
+ * Triggers an immediate, synchronous full reindex of every sales-channel
+ * Meilisearch index — the same work the periodic background sweep performs
+ * (`search.reindex_interval_minutes`). Body is empty; the response carries a
+ * per-run summary so the admin UI can confirm what was rebuilt.
+ */
+export declare const SearchReindexResponseSchema: z.ZodObject<{
+    channelsReindexed: z.ZodNumber;
+    documentCount: z.ZodNumber;
+}, z.core.$strip>;
+export type SearchReindexResponse = z.infer<typeof SearchReindexResponseSchema>;
+/** The channel a search runs in, resolved before the query is built. */
+export interface ResolvedSearchChannel {
+    id: string;
+    code: string;
+    isPublic: boolean;
+    defaultCurrency: string;
+    defaultLanguage: string;
+}
+export interface SearchQueryContext {
+    resolvedChannel: ResolvedSearchChannel;
+    /**
+     * Who is asking (issue #227). The index is not the authority on this: it
+     * carries `visibility` as a filterable attribute and has never carried
+     * `allowed_organization_ids` at all, so the answer is recomputed against the
+     * Postgres rows the hits hydrate from — the same place this path already
+     * insists the price comes from.
+     */
+    audience: ProductAudience;
+    preferredLanguage?: string | undefined;
+}
+export interface SearchListProductsParams {
+    q?: string | undefined;
+    limit: number;
+    cursor?: string | undefined;
+    /**
+     * Feature 086 widened this to the catalogue's own sort union so the two
+     * backends keep sharing one input type. The two price members can never
+     * reach this backend — `catalog/routes.public.ts` routes a price ordering to
+     * Postgres before it chooses Meilisearch — and `buildSort` answers `[]` for
+     * them, because returning a sort expression for a field the document does not
+     * carry would be a trap for the next author.
+     */
+    sort?: ProductListSort | undefined;
+    categorySlug?: string | undefined;
+    attributeFilters?: Record<string, string[]> | undefined;
+}
+export interface SearchListResult {
+    data: ProductSummary[];
+    pagination: {
+        cursor: string | null;
+        hasMore: boolean;
+        limit: number;
+    };
+}
+/**
+ * What a listing query answered: the page, or the fact that the index could
+ * not be reached.
+ *
+ * The second arm exists so the caller does not have to write a `catch` to
+ * learn it. `search` raises `SearchBackendUnavailable` internally when
+ * Meilisearch is unreachable; the port converts it here, on the owner's side,
+ * because a consumer catching it would be a `catch` around a port call — and
+ * that `catch` would swallow `ModuleDisabledError` too, turning "the operator
+ * switched `search` off" into "the index is slow today". Two different facts
+ * with two different right answers, fused by one `catch` clause.
+ *
+ * This is the `allowedIdsFor(): Promise<string[] | null>` shape AGENTS.md names
+ * as the worked example: where a degrade genuinely belongs, it goes inside the
+ * owner's implementation and is expressed in the return type.
+ */
+export type SearchListOutcome = {
+    status: 'ok';
+    result: SearchListResult;
+}
+/** Meilisearch refused or timed out. `reason` is for the caller's log line. */
+ | {
+    status: 'index-unavailable';
+    reason: string;
+};
+/**
+ * Container name: `searchQueryPort`. Owner: `search`.
+ *
+ * **The one port in the sweep whose consumer is right to degrade rather than
+ * fail**, and the degrade is already where it belongs: `catalog`'s listing
+ * route checks the backend setting and falls back to its own Postgres query.
+ * That is a `nonBindingDependencies` edge, declared, not a `catch` — a search
+ * index being unavailable must not take the catalogue down with it.
+ *
+ * Note what the fallback is *not* allowed to be: a `try`/`catch` around the
+ * call. Catching here would swallow `ModuleDisabledError` and make a
+ * switched-off `search` look like a slow one, which is the fail-open shape
+ * `check:port-catches` exists for. That is why `listProducts` answers a
+ * {@link SearchListOutcome} rather than throwing: the consumer distinguishes
+ * the two states by reading a field, and never by catching.
+ */
+export interface SearchQueryPort {
+    listProducts(params: SearchListProductsParams, ctx: SearchQueryContext): Promise<SearchListOutcome>;
+}
+/**
+ * Container name: `searchReindexPort`. Owner: `search`.
+ *
+ * A full rebuild of every channel's index, over the one indexer `searchModule`
+ * holds — so a composition has exactly one Meilisearch client whichever entry
+ * point triggers the reindex. `catalog` runs it as a `search_reindex` bulk
+ * operation when an attribute's `searchable` flag flips, and the `search:reindex`
+ * CLI command is the other caller.
+ *
+ * Published by `specs/117-instance-bring-up/` Phase 6, which is when it first
+ * had a consumer that resolves it **by name**: a composition root used to
+ * resolve it and hand `catalog` a closure, and a root's read is outside
+ * `check:port-shape`'s population, so the name went unpublished for as long as
+ * nothing inside a module asked for it.
+ *
+ * **Owner off:** `catalog` decides presence in front of the gate rather than
+ * catching behind it, and answers `{ documentCount: 0 }` — its manifest declares
+ * the edge `degrades-without`, because with `search` absent there is no index to
+ * rebuild and 503-ing an unrelated attribute edit would make an operator's
+ * supported off-switch fail a catalogue write.
+ */
+export interface SearchReindexPort {
+    reindexAll(): Promise<{
+        documentCount: number;
+    }>;
+}
+//# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}

package/dist/search.js

@@ -0,0 +1,160 @@
+// Search module — feature 006 contract surface.
+//
+// Public API:
+//   - GET  /api/v1/search/suggest           (typeahead popup feed — US1)
+//   - POST /api/v1/search/record            (analytics ingest — US3)
+//   - POST /api/v1/admin/search/llm/toggle  (LLM-mode toggle wrapper — US2)
+//
+// Schemas live in three sections, populated by the user-story phases that
+// own them. Foundation (T002) seeded the file empty; US1 (T009) adds the
+// suggest contracts below. US2 / US3 schemas land later.
+import { z } from 'zod';
+import { productSummarySchema, } from './catalog.js';
+import { displayModeSchema } from './price-lists.js';
+// ---------------------------------------------------------------------------
+// (1) GET /api/v1/search/suggest — US1 / T009
+// ---------------------------------------------------------------------------
+/**
+ * Maximum allowed phrase length, in characters. Mirrors the
+ * `phrase varchar(512)` upper bound in `data-model.md §1.1` so the wire
+ * contract refuses anything that the storage layer would refuse anyway.
+ */
+export const SEARCH_PHRASE_MAX_LENGTH = 512;
+/**
+ * Hard cap on `limit`; the per-channel `search.popup.suggestion_count`
+ * setting is what callers normally observe. The cap exists so a misbehaving
+ * client cannot ask for more than the popup UX could realistically render.
+ */
+export const SEARCH_SUGGEST_LIMIT_MAX = 50;
+export const SearchSuggestQuerySchema = z.object({
+    q: z
+        .string()
+        .min(1, 'phrase is required')
+        .max(SEARCH_PHRASE_MAX_LENGTH, 'phrase exceeds the maximum length'),
+    limit: z.coerce
+        .number()
+        .int()
+        .positive()
+        .max(SEARCH_SUGGEST_LIMIT_MAX)
+        .optional(),
+});
+export const SearchSuggestMetaSchema = z.object({
+    /** Effective limit applied to the response. */
+    limit: z.number().int().nonnegative(),
+    /** The channel's resolved minimum query length, echoed back so the
+     *  client can self-correct without a separate round-trip. */
+    minimumQueryLength: z.number().int().positive(),
+    /** Echo of `q` after trimming, for client-side reconciliation when the
+     *  popup is rendering stale state. */
+    queryEcho: z.string(),
+});
+/**
+ * Money carried by an enriched suggestion. The amount is a decimal STRING
+ * (e.g. "199.00") to preserve trailing zeros across the wire, matching the
+ * `resolved-price` endpoint's shape (feature 011) rather than the foundation
+ * `moneySchema` (which uses a number for the legacy `ProductSummary.price`).
+ */
+export const searchSuggestMoneySchema = z.object({
+    amount: z.string(),
+    currency: z.string(),
+});
+/**
+ * A typeahead suggestion. Extends the foundation `ProductSummary` (id, sku,
+ * name, slug, `primaryAssetUrl`, legacy `price`) with the per-customer
+ * price-list resolution so the popup can render the SKU, image, and the
+ * price the searching user would actually pay — honouring their price list
+ * and price-visibility (`priceDisplayMode`, where `none` hides the price).
+ *
+ * The pricing fields are optional: when the search module runs without a
+ * pricing enricher wired (foundation tests, Meilisearch-only deployments)
+ * the response degrades to a plain `ProductSummary` and the storefront
+ * falls back to the legacy `price` projection.
+ */
+export const searchSuggestItemSchema = productSummarySchema.extend({
+    /** Resolved price-list Base price for this customer; `null` when no
+     *  bracket applies or the price is hidden. */
+    basePrice: searchSuggestMoneySchema.nullable().optional(),
+    /** Resolved Sale price, when a sale list applies to this customer. */
+    salePrice: searchSuggestMoneySchema.nullable().optional(),
+    /** Resolved price-visibility mode. `none` ⇒ the storefront must hide the
+     *  price and offer a quote affordance instead. */
+    priceDisplayMode: displayModeSchema.optional(),
+});
+export const SearchSuggestResponseSchema = z.object({
+    data: z.array(searchSuggestItemSchema),
+    meta: SearchSuggestMetaSchema,
+});
+// ---------------------------------------------------------------------------
+// (2) POST /api/v1/admin/search/llm/toggle — US2 / T021
+// ---------------------------------------------------------------------------
+/**
+ * The four `search.llm.*` settings whose values are inspected by the
+ * toggle wrapper. `enabled` must be present; the other three must be
+ * non-empty when `enabled=true`. The wrapper itself only writes the
+ * `enabled` setting — the embedder fields are written through the
+ * generic Settings admin route and read by the wrapper at validation
+ * time.
+ */
+export const LlmToggleRequestSchema = z.object({
+    enabled: z.boolean(),
+    /**
+     * When omitted, applies to every channel in the setting's scope
+     * (parallels SettingsAdminService.setValueForAllChannels). When
+     * present, applies only to the listed channels.
+     */
+    salesChannelCodes: z.array(z.string().min(1)).optional(),
+    /**
+     * Optimistic-concurrency token from the latest GET of
+     * `search.llm.enabled`. When stale, the call rejects with
+     * `409 VERSION_CONFLICT` (mirrors Settings' existing model).
+     */
+    expectedVersion: z.string().nullable().optional(),
+});
+export const LlmToggleResponseSchema = z.object({
+    /** Always `search.llm.enabled` — present for parity with the generic Settings route. */
+    code: z.literal('search.llm.enabled'),
+    enabled: z.boolean(),
+    /** New optimistic-concurrency token; the admin UI stores it for the next save. */
+    newVersion: z.string(),
+    /**
+     * Channel UUIDs whose `setting_values` row was written. Mirrors the
+     * `affectedChannelIds` SetValueResult shape from feature 004.
+     */
+    appliedChannelIds: z.array(z.uuid()),
+});
+// ---------------------------------------------------------------------------
+// (3) POST /api/v1/search/record — US3 / T030
+// ---------------------------------------------------------------------------
+/**
+ * Fire-and-forget analytics ingest. The storefront's `/search` page
+ * fires this on render, AFTER `listProducts` resolves so `resultCount`
+ * is meaningful. The endpoint always returns `202 { ok: true }` once
+ * the input passes shape validation; persistence failures degrade to a
+ * warn log (FR-015 — recording must never delay or fail the search
+ * response).
+ */
+export const RecordPhraseRequestSchema = z.object({
+    phrase: z
+        .string()
+        .min(1)
+        .max(SEARCH_PHRASE_MAX_LENGTH),
+    /** Result-page count; `0` for dead-end phrases (FR-014). */
+    resultCount: z.number().int().nonnegative().optional(),
+});
+export const RecordPhraseResponseSchema = z.object({
+    ok: z.literal(true),
+});
+// ---------------------------------------------------------------------------
+// (4) POST /api/v1/admin/search/reindex — manual full Meilisearch reindex
+// ---------------------------------------------------------------------------
+/**
+ * Triggers an immediate, synchronous full reindex of every sales-channel
+ * Meilisearch index — the same work the periodic background sweep performs
+ * (`search.reindex_interval_minutes`). Body is empty; the response carries a
+ * per-run summary so the admin UI can confirm what was rebuilt.
+ */
+export const SearchReindexResponseSchema = z.object({
+    channelsReindexed: z.number().int().nonnegative(),
+    documentCount: z.number().int().nonnegative(),
+});
+//# sourceMappingURL=search.js.map

package/dist/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}

package/dist/seo.d.ts

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+/**
+ * SEO meta + sitemap contracts (T235 / FR-101, FR-102).
+ *
+ * The `entityType` enum is closed — only entities the storefront actually
+ * renders public pages for can carry meta overrides.
+ */
+export declare const seoEntityTypeSchema: z.ZodEnum<{
+    category: "category";
+    cms_page: "cms_page";
+    product: "product";
+}>;
+export type SeoEntityType = z.infer<typeof seoEntityTypeSchema>;
+export declare const resolvedMetaSchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodString;
+    openGraph: z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodString;
+        image: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    source: z.ZodEnum<{
+        override: "override";
+        rule: "rule";
+    }>;
+    locale: z.ZodString;
+}, z.core.$strip>;
+export type ResolvedMeta = z.infer<typeof resolvedMetaSchema>;
+export declare const seoMetaOverrideSchema: z.ZodObject<{
+    id: z.ZodString;
+    entityType: z.ZodEnum<{
+        category: "category";
+        cms_page: "cms_page";
+        product: "product";
+    }>;
+    entityId: z.ZodString;
+    locale: z.ZodString;
+    title: z.ZodNullable<z.ZodString>;
+    description: z.ZodNullable<z.ZodString>;
+    ogTitle: z.ZodNullable<z.ZodString>;
+    ogDescription: z.ZodNullable<z.ZodString>;
+    ogImageUrl: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export declare const upsertSeoMetaOverrideRequestSchema: z.ZodObject<{
+    locale: z.ZodString;
+    title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    ogTitle: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    ogDescription: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    ogImageUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type UpsertSeoMetaOverrideRequest = z.infer<typeof upsertSeoMetaOverrideRequestSchema>;
+export declare const sitemapStatusSchema: z.ZodObject<{
+    generatedAt: z.ZodNullable<z.ZodString>;
+    byteSize: z.ZodNullable<z.ZodNumber>;
+    urlCount: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type SitemapStatus = z.infer<typeof sitemapStatusSchema>;
+/**
+ * Per-channel sitemap row returned by the admin list endpoint
+ * (`GET /api/v1/admin/seo/sitemap`). One row per active sales channel —
+ * each carries its own cache (regenerate, preview and download act on a
+ * single channel) and its own resolved storefront URL.
+ */
+export declare const sitemapChannelStatusSchema: z.ZodObject<{
+    generatedAt: z.ZodNullable<z.ZodString>;
+    byteSize: z.ZodNullable<z.ZodNumber>;
+    urlCount: z.ZodNullable<z.ZodNumber>;
+    salesChannelCode: z.ZodString;
+    salesChannelName: z.ZodString;
+    storefrontUrl: z.ZodString;
+    storefrontUrlSource: z.ZodEnum<{
+        env: "env";
+        setting: "setting";
+        fallback: "fallback";
+    }>;
+}, z.core.$strip>;
+export type SitemapChannelStatus = z.infer<typeof sitemapChannelStatusSchema>;
+export declare const sitemapChannelListResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        generatedAt: z.ZodNullable<z.ZodString>;
+        byteSize: z.ZodNullable<z.ZodNumber>;
+        urlCount: z.ZodNullable<z.ZodNumber>;
+        salesChannelCode: z.ZodString;
+        salesChannelName: z.ZodString;
+        storefrontUrl: z.ZodString;
+        storefrontUrlSource: z.ZodEnum<{
+            env: "env";
+            setting: "setting";
+            fallback: "fallback";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SitemapChannelListResponse = z.infer<typeof sitemapChannelListResponseSchema>;
+/**
+ * Container name: `seoMetaWritePort`. Owner: `seo`.
+ *
+ * Narrow write surface for PIM importers (feature 089 / FR-029): upsert product
+ * meta overrides by locale. Channel dimension does not exist on Endora SEO rows.
+ *
+ * **Owner off:** resolving this port throws `ModuleDisabledError` (503).
+ */
+export interface SeoMetaWritePort {
+    upsertProductMeta(input: {
+        productId: string;
+        locale: string;
+        title?: string | null;
+        description?: string | null;
+    }): Promise<void>;
+}
+//# sourceMappingURL=seo.d.ts.map

package/dist/seo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo.d.ts","sourceRoot":"","sources":["../src/seo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AAEH,eAAO,MAAM,mBAAmB;;;;EAA8C,CAAC;AAC/E,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;iBAW7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;iBAYhC,CAAC;AAEH,eAAO,MAAM,kCAAkC;;;;;;;iBAO7C,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE9F,eAAO,MAAM,mBAAmB;;;;iBAI9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;iBAKrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;iBAE3C,CAAC;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAE1F;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB,CAAC,KAAK,EAAE;QACvB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC7B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB"}

package/dist/seo.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { isoDateTimeSchema, uuidSchema } from './common.js';
+/**
+ * SEO meta + sitemap contracts (T235 / FR-101, FR-102).
+ *
+ * The `entityType` enum is closed — only entities the storefront actually
+ * renders public pages for can carry meta overrides.
+ */
+export const seoEntityTypeSchema = z.enum(['product', 'category', 'cms_page']);
+export const resolvedMetaSchema = z.object({
+    title: z.string(),
+    description: z.string(),
+    openGraph: z.object({
+        title: z.string(),
+        description: z.string(),
+        image: z.string().nullable(),
+    }),
+    /** Whether the resolved values came from a stored override or the rule. */
+    source: z.enum(['override', 'rule']),
+    locale: z.string(),
+});
+export const seoMetaOverrideSchema = z.object({
+    id: uuidSchema,
+    entityType: seoEntityTypeSchema,
+    entityId: uuidSchema,
+    locale: z.string().min(2).max(10),
+    title: z.string().nullable(),
+    description: z.string().nullable(),
+    ogTitle: z.string().nullable(),
+    ogDescription: z.string().nullable(),
+    ogImageUrl: z.string().url().nullable(),
+    createdAt: isoDateTimeSchema,
+    updatedAt: isoDateTimeSchema,
+});
+export const upsertSeoMetaOverrideRequestSchema = z.object({
+    locale: z.string().min(2).max(10),
+    title: z.string().min(1).max(160).nullable().optional(),
+    description: z.string().min(1).max(400).nullable().optional(),
+    ogTitle: z.string().min(1).max(160).nullable().optional(),
+    ogDescription: z.string().min(1).max(400).nullable().optional(),
+    ogImageUrl: z.string().url().nullable().optional(),
+});
+export const sitemapStatusSchema = z.object({
+    generatedAt: isoDateTimeSchema.nullable(),
+    byteSize: z.number().int().nonnegative().nullable(),
+    urlCount: z.number().int().nonnegative().nullable(),
+});
+/**
+ * Per-channel sitemap row returned by the admin list endpoint
+ * (`GET /api/v1/admin/seo/sitemap`). One row per active sales channel —
+ * each carries its own cache (regenerate, preview and download act on a
+ * single channel) and its own resolved storefront URL.
+ */
+export const sitemapChannelStatusSchema = sitemapStatusSchema.extend({
+    salesChannelCode: z.string(),
+    salesChannelName: z.string(),
+    storefrontUrl: z.string(),
+    storefrontUrlSource: z.enum(['setting', 'env', 'fallback']),
+});
+export const sitemapChannelListResponseSchema = z.object({
+    data: z.array(sitemapChannelStatusSchema),
+});
+//# sourceMappingURL=seo.js.map