@sixtyninecommerce/admin 0.8.0 → 0.10.0

package/dist/events/index.js

@@ -0,0 +1,147 @@
+import { createEventHandler, createEventsClient, createPage, readRestPage, ValidationError, } from '@sixtyninecommerce/core';
+/** Most event ids one `redrive` call may name. */
+export const MAX_REDRIVE_EVENT_IDS = 100;
+/** The caller's test `data` is the envelope payload: sent verbatim, never case-converted. */
+const SEND_TEST_PASSTHROUGH = new Set(['data']);
+/** `evidence` is stored JSONB: its keys are data, not structure. */
+const DELIVERY_PASSTHROUGH = new Set(['evidence']);
+function requireId(id) {
+    if (typeof id !== 'string' || id.trim() === '') {
+        throw new ValidationError({
+            code: 'VALIDATION_ERROR',
+            message: 'A subscription id is required.',
+            status: 400,
+            service: 'plugins',
+        });
+    }
+    return encodeURIComponent(id);
+}
+/** Refused rather than dropped: the caller believes a retry is safe, and it is not. */
+function refuseIdempotencyKey(options, message) {
+    if (options && 'idempotencyKey' in options && options.idempotencyKey !== undefined) {
+        throw new ValidationError({
+            code: 'IDEMPOTENCY_NOT_SUPPORTED',
+            message,
+            status: 400,
+            service: 'plugins',
+        });
+    }
+}
+export function createEventsModule(transport) {
+    async function list(options) {
+        // `?cursor=1` opts into the paged shape; without it the route answers a bare array and
+        // ignores `limit` (`wantsCursor`, spec §18 amendment 9).
+        const body = await transport.rest('plugins', {
+            method: 'GET',
+            path: '/event-subscriptions',
+            query: { cursor: 1, after: options?.after, limit: options?.limit },
+        }, options);
+        const { items, meta } = readRestPage(body);
+        return createPage(items, meta, (cursor) => list({ ...options, after: cursor }));
+    }
+    async function deliveries(id, options) {
+        const body = await transport.rest('plugins', {
+            method: 'GET',
+            path: `/event-subscriptions/${requireId(id)}/deliveries`,
+            query: { cursor: 1, after: options?.after, limit: options?.limit },
+        }, { ...options, preserveKeys: DELIVERY_PASSTHROUGH });
+        const { items, meta } = readRestPage(body);
+        return createPage(items, meta, (cursor) => deliveries(id, { ...options, after: cursor }));
+    }
+    const subscriptions = {
+        list,
+        deliveries,
+        async create(input, options) {
+            refuseIdempotencyKey(options, 'events.subscriptions.create takes no idempotency key: its response carries the signing secret, which the platform never stores for replay. Check list() before retrying.');
+            return transport.rest('plugins', { method: 'POST', path: '/event-subscriptions', body: input }, options);
+        },
+        async update(id, input, options) {
+            return transport.rest('plugins', { method: 'PUT', path: `/event-subscriptions/${requireId(id)}`, body: input }, options);
+        },
+        async setEnabled(id, enabled, options) {
+            if (typeof enabled !== 'boolean') {
+                throw new ValidationError({
+                    code: 'VALIDATION_ERROR',
+                    message: 'enabled must be true or false.',
+                    status: 400,
+                    service: 'plugins',
+                });
+            }
+            return transport.rest('plugins', {
+                method: 'POST',
+                path: `/event-subscriptions/${requireId(id)}/enabled`,
+                body: { enabled },
+            }, options);
+        },
+        async remove(id, options) {
+            await transport.rest('plugins', { method: 'DELETE', path: `/event-subscriptions/${requireId(id)}`, expect: 'void' }, options);
+        },
+        async sendTest(id, type, options) {
+            if (typeof type !== 'string' || type.trim() === '') {
+                throw new ValidationError({
+                    code: 'VALIDATION_ERROR',
+                    message: 'An event type is required, e.g. order.created.',
+                    status: 400,
+                    service: 'plugins',
+                });
+            }
+            const { data, ...call } = options ?? {};
+            if (data !== undefined &&
+                (data === null || typeof data !== 'object' || Array.isArray(data))) {
+                throw new ValidationError({
+                    code: 'VALIDATION_ERROR',
+                    message: 'data must be a JSON object: the envelope data to send.',
+                    status: 400,
+                    service: 'plugins',
+                });
+            }
+            return transport.rest('plugins', {
+                method: 'POST',
+                path: `/event-subscriptions/${requireId(id)}/test`,
+                body: data === undefined ? { type } : { type, data },
+            }, { ...call, preserveKeys: SEND_TEST_PASSTHROUGH });
+        },
+        async rotateSecret(id, options) {
+            refuseIdempotencyKey(options, 'events.subscriptions.rotateSecret takes no idempotency key: its response carries the new signing secret, which the platform never stores for replay.');
+            const { force, ...call } = options ?? {};
+            return transport.rest('plugins', {
+                method: 'POST',
+                path: `/event-subscriptions/${requireId(id)}/rotate-secret`,
+                query: { force: force === true ? true : undefined },
+            }, call);
+        },
+    };
+    async function redrives(subscriptionId, options) {
+        const body = await transport.rest('plugins', {
+            method: 'GET',
+            path: `/event-subscriptions/${requireId(subscriptionId)}/redrives`,
+            query: { after: options?.after, limit: options?.limit },
+        }, options);
+        const { items, meta } = readRestPage(body);
+        return createPage(items, meta, (cursor) => redrives(subscriptionId, { ...options, after: cursor }));
+    }
+    async function redrive(subscriptionId, eventIds, options) {
+        if (!Array.isArray(eventIds) ||
+            eventIds.length === 0 ||
+            eventIds.length > MAX_REDRIVE_EVENT_IDS) {
+            throw new ValidationError({
+                code: 'VALIDATION_ERROR',
+                message: `events.redrive takes 1-${String(MAX_REDRIVE_EVENT_IDS)} event ids.`,
+                status: 400,
+                service: 'plugins',
+            });
+        }
+        return transport.rest('plugins', {
+            method: 'POST',
+            path: `/event-subscriptions/${requireId(subscriptionId)}/redrive`,
+            body: { eventIds: [...eventIds] },
+        }, options);
+    }
+    return {
+        ...createEventsClient(transport),
+        subscribe: createEventHandler,
+        subscriptions,
+        redrive,
+        redrives,
+    };
+}

package/dist/feeds/ai.d.ts

@@ -0,0 +1,46 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+import { type CategorySuggestEnqueueResult, type CategorySuggestStatus, type FeedAiSuggestion, type GenerateTitlePresetInput, type SuggestCategoryMappingsInput, type TitlePresetStatus } from './types.js';
+/** A title preset samples the catalogue and waits on a model; 15 seconds is not enough. */
+export declare const TITLE_PRESET_TIMEOUT_MS = 60000;
+/**
+ * Whether a refusal means "this platform has no model configured" rather than
+ * "the model failed".
+ *
+ * The two need different handling: one is a permanent property of the
+ * environment (offer nothing, explain), the other is worth retrying. Both AI
+ * writes refuse with a 409 `AI_UNAVAILABLE`, while the two READS answer 200
+ * with `aiAvailable: false` — availability is a field there, never an error, so
+ * a page can render the disabled hint without provoking a failure state.
+ */
+export declare function isAiUnavailable(error: unknown): boolean;
+/**
+ * The AI helpers: categorising a channel's collections, and proposing a better
+ * `title` mapping for one feed.
+ *
+ * Nothing here is applied on its own. A categorisation pass writes ordinary
+ * `suggested` category mappings that `categoryMappings.bulkStatus` decides on;
+ * a title preset is stored as a PROPOSAL and only `acceptSuggestion` merges it
+ * into the feed's `mappingJson`, through the same compile-before-write path a
+ * hand-edited mapping takes.
+ */
+export interface FeedAiModule {
+    /**
+     * Queue a categorisation pass over the channel's collections. Refuses with a
+     * 409 `AI_UNAVAILABLE` when no model is configured — read
+     * {@link FeedAiModule.categorySuggestStatus} first and offer the action only
+     * when `aiAvailable`.
+     */
+    suggestCategories(input?: SuggestCategoryMappingsInput, options?: Call): Promise<CategorySuggestEnqueueResult>;
+    /** State of the channel's latest pass. Always 200 — availability is a field, not an error. */
+    categorySuggestStatus(options?: Call): Promise<CategorySuggestStatus>;
+    /** Ask for one improved `title` mapping for a feed. Slow, and 409s when no model is configured. */
+    generateTitlePreset(configId: string, input?: GenerateTitlePresetInput, options?: Call): Promise<FeedAiSuggestion>;
+    /** A feed's latest PENDING title proposal, plus whether a new one can be asked for. */
+    titlePreset(configId: string, options?: Call): Promise<TitlePresetStatus>;
+    /** Record the decision and merge the proposal into the feed's `mappingJson`. */
+    acceptSuggestion(suggestionId: string, options?: Call): Promise<FeedAiSuggestion>;
+    /** Record the decision. Changes no configuration. */
+    dismissSuggestion(suggestionId: string, options?: Call): Promise<FeedAiSuggestion>;
+}
+export declare function createFeedAiModule(transport: Transport): FeedAiModule;

package/dist/feeds/ai.js

@@ -0,0 +1,43 @@
+import { PlatformError } from '@sixtyninecommerce/core';
+import { FEEDS_PRESERVE_KEYS, segment } from './preserve.js';
+import { AI_UNAVAILABLE_CODE, } from './types.js';
+const MAPPINGS = '/feeds/category-mappings';
+const CONFIGS = '/feeds/configs';
+const SUGGESTIONS = '/feeds/ai-suggestions';
+/** A title preset samples the catalogue and waits on a model; 15 seconds is not enough. */
+export const TITLE_PRESET_TIMEOUT_MS = 60_000;
+/**
+ * Whether a refusal means "this platform has no model configured" rather than
+ * "the model failed".
+ *
+ * The two need different handling: one is a permanent property of the
+ * environment (offer nothing, explain), the other is worth retrying. Both AI
+ * writes refuse with a 409 `AI_UNAVAILABLE`, while the two READS answer 200
+ * with `aiAvailable: false` — availability is a field there, never an error, so
+ * a page can render the disabled hint without provoking a failure state.
+ */
+export function isAiUnavailable(error) {
+    return error instanceof PlatformError && error.code === AI_UNAVAILABLE_CODE;
+}
+export function createFeedAiModule(transport) {
+    return {
+        suggestCategories(input = {}, options) {
+            return transport.rest('plugins', { method: 'POST', path: `${MAPPINGS}/suggest`, body: input }, options);
+        },
+        categorySuggestStatus(options) {
+            return transport.rest('plugins', { method: 'GET', path: `${MAPPINGS}/suggest/status` }, options);
+        },
+        generateTitlePreset(configId, input = {}, options) {
+            return transport.rest('plugins', { method: 'POST', path: `${CONFIGS}/${segment(configId)}/title-preset`, body: input }, { ...options, preserveKeys: FEEDS_PRESERVE_KEYS, timeoutMs: TITLE_PRESET_TIMEOUT_MS });
+        },
+        titlePreset(configId, options) {
+            return transport.rest('plugins', { method: 'GET', path: `${CONFIGS}/${segment(configId)}/title-preset` }, { ...options, preserveKeys: FEEDS_PRESERVE_KEYS });
+        },
+        acceptSuggestion(suggestionId, options) {
+            return transport.rest('plugins', { method: 'POST', path: `${SUGGESTIONS}/${segment(suggestionId)}/accept` }, { ...options, preserveKeys: FEEDS_PRESERVE_KEYS });
+        },
+        dismissSuggestion(suggestionId, options) {
+            return transport.rest('plugins', { method: 'POST', path: `${SUGGESTIONS}/${segment(suggestionId)}/dismiss` }, { ...options, preserveKeys: FEEDS_PRESERVE_KEYS });
+        },
+    };
+}

package/dist/feeds/categories.d.ts

@@ -0,0 +1,50 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+import type { BulkStatusUpdateResult, BulkUpdateCategoryMappingStatusInput, CreateFeedCategoryMappingInput, FeedCategoryMapping, FeedCategoryMappingSource, FeedCategoryMappingStatus, FeedCategoryMatchType, FeedTaxonomyNode, UpdateFeedCategoryMappingInput } from './types.js';
+export interface ListFeedCategoryMappingsOptions extends ListOptions {
+    matchType?: FeedCategoryMatchType;
+    status?: FeedCategoryMappingStatus;
+    source?: FeedCategoryMappingSource;
+}
+export interface SearchTaxonomyOptions extends Call {
+    /** 1…50; omitted ⇒ 20. */
+    limit?: number;
+}
+/**
+ * The channel's catalogue mapped onto the Google product taxonomy.
+ *
+ * Resolution order at generation time is `collection` → `facet_value` →
+ * `default`, and only `approved` rows are ever applied — a `suggested` row is
+ * a proposal awaiting a decision, never live configuration.
+ *
+ * Every taxonomy value that comes back is RESOLVED, never echoed: a path sent
+ * by a client is ignored and re-derived from the id against the vendored
+ * taxonomy, because a stale or hand-typed path is the classic way a whole feed
+ * gets disapproved.
+ */
+export interface FeedCategoryMappingsModule {
+    list(options?: ListFeedCategoryMappingsOptions): Promise<Page<FeedCategoryMapping>>;
+    get(id: string, options?: Call): Promise<FeedCategoryMapping>;
+    create(input: CreateFeedCategoryMappingInput, options?: Call): Promise<FeedCategoryMapping>;
+    update(id: string, input: UpdateFeedCategoryMappingInput, options?: Call): Promise<FeedCategoryMapping>;
+    delete(id: string, options?: Call): Promise<void>;
+    /**
+     * Approve or reject up to {@link MAX_BULK_STATUS_IDS} mappings in one call —
+     * the AI review queue's primary action. Ids belonging to another channel are
+     * SKIPPED, not errored, so an `updated` count lower than `ids.length` is
+     * information rather than a failure.
+     */
+    bulkStatus(input: BulkUpdateCategoryMappingStatusInput, options?: Call): Promise<BulkStatusUpdateResult>;
+}
+/**
+ * Ranked search over the vendored Google product taxonomy.
+ *
+ * The file is identical for every tenant, so this route takes no channel — but
+ * it is still entitlement-gated, so a store without the feeds plugin connected
+ * is refused.
+ */
+export interface FeedTaxonomyModule {
+    search(query: string, options?: SearchTaxonomyOptions): Promise<FeedTaxonomyNode[]>;
+}
+export declare function createFeedCategoryMappingsModule(transport: Transport): FeedCategoryMappingsModule;
+export declare function createFeedTaxonomyModule(transport: Transport): FeedTaxonomyModule;

package/dist/feeds/categories.js

@@ -0,0 +1,56 @@
+import { createPage, readRestPage } from '@sixtyninecommerce/core';
+import { FEEDS_PRESERVE_KEYS, feedQuery, segment } from './preserve.js';
+const MAPPINGS = '/feeds/category-mappings';
+const TAXONOMY_SEARCH = '/feeds/taxonomy/search';
+export function createFeedCategoryMappingsModule(transport) {
+    async function list(options) {
+        const body = await transport.rest('plugins', {
+            method: 'GET',
+            path: MAPPINGS,
+            query: feedQuery({
+                // The wire spelling, written out: query keys are NOT case-converted by
+                // the transport (only bodies and responses are), so `matchType` would
+                // reach the DTO as an unknown member and be dropped — silently
+                // listing every mapping in the channel instead of the one kind asked
+                // for.
+                match_type: options?.matchType,
+                status: options?.status,
+                source: options?.source,
+                limit: options?.limit,
+                after: options?.after,
+            }),
+        }, { ...options, preserveKeys: FEEDS_PRESERVE_KEYS });
+        const { items, meta } = readRestPage(body);
+        return createPage(items, meta, (cursor) => list({ ...options, after: cursor }));
+    }
+    return {
+        list,
+        get(id, options) {
+            return transport.rest('plugins', { method: 'GET', path: `${MAPPINGS}/${segment(id)}` }, { ...options, preserveKeys: FEEDS_PRESERVE_KEYS });
+        },
+        create(input, options) {
+            return transport.rest('plugins', { method: 'POST', path: MAPPINGS, body: input }, { ...options, preserveKeys: FEEDS_PRESERVE_KEYS });
+        },
+        update(id, input, options) {
+            return transport.rest('plugins', { method: 'PATCH', path: `${MAPPINGS}/${segment(id)}`, body: input }, { ...options, preserveKeys: FEEDS_PRESERVE_KEYS });
+        },
+        async delete(id, options) {
+            await transport.rest('plugins', { method: 'DELETE', path: `${MAPPINGS}/${segment(id)}`, expect: 'void' }, options);
+        },
+        bulkStatus(input, options) {
+            return transport.rest('plugins', { method: 'POST', path: `${MAPPINGS}/bulk-status`, body: input }, options);
+        },
+    };
+}
+export function createFeedTaxonomyModule(transport) {
+    return {
+        async search(query, options) {
+            const body = await transport.rest('plugins', {
+                method: 'GET',
+                path: TAXONOMY_SEARCH,
+                query: feedQuery({ q: query, limit: options?.limit }),
+            }, options);
+            return body.data;
+        },
+    };
+}

package/dist/feeds/configs.d.ts

@@ -0,0 +1,54 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+import type { CreateFeedConfigInput, FeedConfig, FeedDestination, FeedDestinationKey, FeedItemIssue, FeedItemIssueSeverity, FeedPreview, FeedPreviewDraft, FeedRegenerateResult, FeedRun, FeedRunStatus, RotateFeedTokenResult, UpdateFeedConfigInput } from './types.js';
+/**
+ * A preview walks the catalogue and evaluates every rule, so it is slower than
+ * a read by an order of magnitude — the SDK's 15-second default would time out
+ * a sample the service is still perfectly happy to answer.
+ */
+export declare const FEED_PREVIEW_TIMEOUT_MS = 60000;
+export interface ListFeedConfigsOptions extends ListOptions {
+    destination?: FeedDestinationKey;
+    enabled?: boolean;
+}
+export interface ListFeedRunsOptions extends ListOptions {
+    status?: FeedRunStatus;
+}
+export interface ListFeedIssuesOptions extends ListOptions {
+    severity?: FeedItemIssueSeverity;
+    /** One issue code, e.g. `no_category`. Free text — codes are not a closed set. */
+    code?: string;
+}
+/**
+ * Feed configurations, their generation runs and the item issues the last run
+ * produced (spec §8.14).
+ *
+ * Every method is CHANNEL-SCOPED by the client's own tenant: the service reads
+ * `x-channel-id` and never takes a channel argument, so a feed created here
+ * belongs to the store this client is bound to and no other.
+ */
+export interface FeedConfigsModule {
+    /** One page of the channel's feed configurations, newest first. */
+    list(options?: ListFeedConfigsOptions): Promise<Page<FeedConfig>>;
+    get(id: string, options?: Call): Promise<FeedConfig>;
+    create(input: CreateFeedConfigInput, options?: Call): Promise<FeedConfig>;
+    update(id: string, input: UpdateFeedConfigInput, options?: Call): Promise<FeedConfig>;
+    delete(id: string, options?: Call): Promise<void>;
+    /** Mint a new token; the previous public feed URL stops resolving immediately. */
+    rotateToken(id: string, options?: Call): Promise<RotateFeedTokenResult>;
+    /** Enqueue a regeneration; the run row appears in {@link FeedConfigsModule.runs} seconds later. */
+    regenerate(id: string, options?: Call): Promise<FeedRegenerateResult>;
+    /** The destination registry and its field templates — a frozen server-side constant. */
+    destinations(options?: Call): Promise<FeedDestination[]>;
+    /**
+     * Evaluate a DRAFT configuration against real catalogue rows. Persists
+     * nothing — no config, no run, no output — which is why it takes the whole
+     * draft rather than an id.
+     */
+    preview(draft: FeedPreviewDraft, options?: Call): Promise<FeedPreview>;
+    /** Generation history for one feed, newest first. Failed runs included — that is the point. */
+    runs(configId: string, options?: ListFeedRunsOptions): Promise<Page<FeedRun>>;
+    /** Item issues from the LATEST successful run — there is no run selector. */
+    issues(configId: string, options?: ListFeedIssuesOptions): Promise<Page<FeedItemIssue>>;
+}
+export declare function createFeedConfigsModule(transport: Transport): FeedConfigsModule;

package/dist/feeds/configs.js

@@ -0,0 +1,85 @@
+import { createPage, readRestPage } from '@sixtyninecommerce/core';
+import { FEEDS_PRESERVE_KEYS, feedQuery, segment } from './preserve.js';
+const CONFIGS = '/feeds/configs';
+/**
+ * A preview walks the catalogue and evaluates every rule, so it is slower than
+ * a read by an order of magnitude — the SDK's 15-second default would time out
+ * a sample the service is still perfectly happy to answer.
+ */
+export const FEED_PREVIEW_TIMEOUT_MS = 60_000;
+export function createFeedConfigsModule(transport) {
+    async function list(options) {
+        const body = await transport.rest('plugins', {
+            method: 'GET',
+            path: CONFIGS,
+            query: feedQuery({
+                destination: options?.destination,
+                enabled: options?.enabled,
+                limit: options?.limit,
+                after: options?.after,
+            }),
+        }, { ...options, preserveKeys: FEEDS_PRESERVE_KEYS });
+        const { items, meta } = readRestPage(body);
+        return createPage(items, meta, (cursor) => list({ ...options, after: cursor }));
+    }
+    async function runs(configId, options) {
+        const body = await transport.rest('plugins', {
+            method: 'GET',
+            path: `${CONFIGS}/${segment(configId)}/runs`,
+            query: feedQuery({
+                status: options?.status,
+                limit: options?.limit,
+                after: options?.after,
+            }),
+        }, { ...options, preserveKeys: FEEDS_PRESERVE_KEYS });
+        const { items, meta } = readRestPage(body);
+        return createPage(items, meta, (cursor) => runs(configId, { ...options, after: cursor }));
+    }
+    async function issues(configId, options) {
+        const body = await transport.rest('plugins', {
+            method: 'GET',
+            path: `${CONFIGS}/${segment(configId)}/issues`,
+            query: feedQuery({
+                severity: options?.severity,
+                code: options?.code,
+                limit: options?.limit,
+                after: options?.after,
+            }),
+        }, { ...options, preserveKeys: FEEDS_PRESERVE_KEYS });
+        const { items, meta } = readRestPage(body);
+        return createPage(items, meta, (cursor) => issues(configId, { ...options, after: cursor }));
+    }
+    return {
+        list,
+        runs,
+        issues,
+        get(id, options) {
+            return transport.rest('plugins', { method: 'GET', path: `${CONFIGS}/${segment(id)}` }, { ...options, preserveKeys: FEEDS_PRESERVE_KEYS });
+        },
+        create(input, options) {
+            return transport.rest('plugins', { method: 'POST', path: CONFIGS, body: input }, { ...options, preserveKeys: FEEDS_PRESERVE_KEYS });
+        },
+        update(id, input, options) {
+            return transport.rest('plugins', { method: 'PATCH', path: `${CONFIGS}/${segment(id)}`, body: input }, { ...options, preserveKeys: FEEDS_PRESERVE_KEYS });
+        },
+        async delete(id, options) {
+            await transport.rest('plugins', { method: 'DELETE', path: `${CONFIGS}/${segment(id)}`, expect: 'void' }, options);
+        },
+        rotateToken(id, options) {
+            return transport.rest('plugins', { method: 'POST', path: `${CONFIGS}/${segment(id)}/rotate-token` }, options);
+        },
+        regenerate(id, options) {
+            return transport.rest('plugins', { method: 'POST', path: `${CONFIGS}/${segment(id)}/regenerate` }, options);
+        },
+        async destinations(options) {
+            // `{ data: [...] }`, not a page: the registry is a frozen constant with no
+            // cursor, and `readRestPage` would dress it up as a page that can never
+            // have a second one.
+            const body = await transport.rest('plugins', { method: 'GET', path: `${CONFIGS}/destinations` }, { ...options, preserveKeys: FEEDS_PRESERVE_KEYS });
+            return body.data;
+        },
+        preview(draft, options) {
+            return transport.rest('plugins', { method: 'POST', path: `${CONFIGS}/preview`, body: draft }, { ...options, preserveKeys: FEEDS_PRESERVE_KEYS, timeoutMs: FEED_PREVIEW_TIMEOUT_MS });
+        },
+    };
+}

package/dist/feeds/identifier-fields.d.ts

@@ -0,0 +1,25 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * Whether the engine this client talks to declares the product-feed identifier
+ * fields — `brand` / `condition` on a product, `gtin` / `mpn` on a variant.
+ *
+ * They are declared by the product-feeds plugin, and a caller deployed ahead of
+ * the engine (the dashboard ships independently) that selects or writes one the
+ * engine does not know fails GraphQL validation for the WHOLE document. Ask
+ * first; select and write them only when the answer is yes.
+ */
+export interface FeedIdentifierFieldSupport {
+    /** `Product.customFields.brand` AND `.condition` exist. */
+    product: boolean;
+    /** `ProductVariant.customFields.gtin` AND `.mpn` exist. */
+    variant: boolean;
+}
+export interface FeedIdentifierFieldsModule {
+    /**
+     * Introspect the engine once. A type the engine does not have at all (no
+     * custom fields on that entity) reads as unsupported.
+     */
+    identifierFieldSupport(options?: Call): Promise<FeedIdentifierFieldSupport>;
+}
+export declare function createFeedIdentifierFieldsModule(transport: Transport): FeedIdentifierFieldsModule;

package/dist/feeds/identifier-fields.js

@@ -0,0 +1,29 @@
+const IDENTIFIER_FIELDS_QUERY = /* GraphQL */ `
+  query FeedIdentifierFields {
+    product: __type(name: "ProductCustomFields") {
+      fields {
+        name
+      }
+    }
+    variant: __type(name: "ProductVariantCustomFields") {
+      fields {
+        name
+      }
+    }
+  }
+`;
+function declares(type, names) {
+    const declared = new Set((type?.fields ?? []).map((field) => field.name));
+    return names.every((name) => declared.has(name));
+}
+export function createFeedIdentifierFieldsModule(transport) {
+    return {
+        async identifierFieldSupport(options) {
+            const data = await transport.graphql({ api: 'admin', query: IDENTIFIER_FIELDS_QUERY, variables: {} }, options);
+            return {
+                product: declares(data?.product, ['brand', 'condition']),
+                variant: declares(data?.variant, ['gtin', 'mpn']),
+            };
+        },
+    };
+}

package/dist/feeds/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Product feeds (spec §8.14): the merchandising surface that turns the
+ * catalogue into a Google, Meta, TikTok or Pinterest feed.
+ *
+ * Five groups under one noun, because they are one workflow:
+ *
+ * - **the feed itself** — `admin.feeds.list/get/create/update/delete`, plus
+ *   `preview` (evaluate a draft, persist nothing), `regenerate`, `rotateToken`,
+ *   `runs` and `issues`;
+ * - **`internalFields` / `lookupTables`** — the channel-scoped pieces a rule
+ *   may reference (`internal:<name>`, `{ kind: 'lookup', tableName }`);
+ * - **`categoryMappings` / `taxonomy`** — the catalogue mapped onto the Google
+ *   product taxonomy, and the search behind every picker;
+ * - **`ai`** — the two model-backed helpers: categorising collections, and
+ *   proposing a better `title` mapping.
+ *
+ * Everything but `taxonomy` is scoped to the client's own channel through
+ * `x-channel-id`; no method takes a channel argument.
+ *
+ * **The rule payloads ride verbatim.** `mappingJson`, `filtersJson`,
+ * `settingsJson`, `rulesJson`, `entriesJson`, `perDestinationJson`,
+ * `payloadJson`, `statsJson` and a template's `defaultSource` are stored and
+ * echoed byte-for-byte, and the AST inside them is camelCase — see
+ * `preserve.ts` for why converting any of it corrupts a merchant's saved rules
+ * in a way the round trip hides.
+ */
+import type { Transport } from '@sixtyninecommerce/core';
+import { type FeedAiModule } from './ai.js';
+import { type FeedCategoryMappingsModule, type FeedTaxonomyModule } from './categories.js';
+import { type FeedConfigsModule } from './configs.js';
+import { type FeedIdentifierFieldsModule } from './identifier-fields.js';
+import { type FeedInternalFieldsModule, type FeedLookupTablesModule } from './rules.js';
+export type { FeedAiModule } from './ai.js';
+export { isAiUnavailable, TITLE_PRESET_TIMEOUT_MS } from './ai.js';
+export type { FeedCategoryMappingsModule, FeedTaxonomyModule, ListFeedCategoryMappingsOptions, SearchTaxonomyOptions, } from './categories.js';
+export type { FeedConfigsModule, ListFeedConfigsOptions, ListFeedIssuesOptions, ListFeedRunsOptions, } from './configs.js';
+export { FEED_PREVIEW_TIMEOUT_MS } from './configs.js';
+export type { FeedIdentifierFieldSupport, FeedIdentifierFieldsModule, } from './identifier-fields.js';
+export { FEEDS_PRESERVE_KEYS } from './preserve.js';
+export type { FeedInternalFieldsModule, FeedLookupTablesModule } from './rules.js';
+export * from './types.js';
+export interface FeedsModule extends FeedConfigsModule, FeedIdentifierFieldsModule {
+    /** Computed values a mapping references as `internal:<name>`. */
+    internalFields: FeedInternalFieldsModule;
+    /** Substitution tables a `lookup` value source resolves through. */
+    lookupTables: FeedLookupTablesModule;
+    /** The catalogue mapped onto the Google product taxonomy. */
+    categoryMappings: FeedCategoryMappingsModule;
+    /** Ranked search over the vendored Google taxonomy. Not channel-scoped. */
+    taxonomy: FeedTaxonomyModule;
+    /** Model-backed helpers. Availability is a field on the reads, a 409 on the writes. */
+    ai: FeedAiModule;
+}
+export declare function createFeedsModule(transport: Transport): FeedsModule;

package/dist/feeds/index.js

@@ -0,0 +1,46 @@
+/**
+ * Product feeds (spec §8.14): the merchandising surface that turns the
+ * catalogue into a Google, Meta, TikTok or Pinterest feed.
+ *
+ * Five groups under one noun, because they are one workflow:
+ *
+ * - **the feed itself** — `admin.feeds.list/get/create/update/delete`, plus
+ *   `preview` (evaluate a draft, persist nothing), `regenerate`, `rotateToken`,
+ *   `runs` and `issues`;
+ * - **`internalFields` / `lookupTables`** — the channel-scoped pieces a rule
+ *   may reference (`internal:<name>`, `{ kind: 'lookup', tableName }`);
+ * - **`categoryMappings` / `taxonomy`** — the catalogue mapped onto the Google
+ *   product taxonomy, and the search behind every picker;
+ * - **`ai`** — the two model-backed helpers: categorising collections, and
+ *   proposing a better `title` mapping.
+ *
+ * Everything but `taxonomy` is scoped to the client's own channel through
+ * `x-channel-id`; no method takes a channel argument.
+ *
+ * **The rule payloads ride verbatim.** `mappingJson`, `filtersJson`,
+ * `settingsJson`, `rulesJson`, `entriesJson`, `perDestinationJson`,
+ * `payloadJson`, `statsJson` and a template's `defaultSource` are stored and
+ * echoed byte-for-byte, and the AST inside them is camelCase — see
+ * `preserve.ts` for why converting any of it corrupts a merchant's saved rules
+ * in a way the round trip hides.
+ */
+import { createFeedAiModule } from './ai.js';
+import { createFeedCategoryMappingsModule, createFeedTaxonomyModule, } from './categories.js';
+import { createFeedConfigsModule } from './configs.js';
+import { createFeedIdentifierFieldsModule, } from './identifier-fields.js';
+import { createFeedInternalFieldsModule, createFeedLookupTablesModule, } from './rules.js';
+export { isAiUnavailable, TITLE_PRESET_TIMEOUT_MS } from './ai.js';
+export { FEED_PREVIEW_TIMEOUT_MS } from './configs.js';
+export { FEEDS_PRESERVE_KEYS } from './preserve.js';
+export * from './types.js';
+export function createFeedsModule(transport) {
+    return {
+        ...createFeedConfigsModule(transport),
+        ...createFeedIdentifierFieldsModule(transport),
+        internalFields: createFeedInternalFieldsModule(transport),
+        lookupTables: createFeedLookupTablesModule(transport),
+        categoryMappings: createFeedCategoryMappingsModule(transport),
+        taxonomy: createFeedTaxonomyModule(transport),
+        ai: createFeedAiModule(transport),
+    };
+}